Twin boundary: R public package vs Julia engine

Status contract, not a promotion. Engine-covered evidence does not make an R formula fitted or production-ready. Read Can I fit and report this? before reporting.

hsquared and HSquared.jl are sibling packages with different jobs. The boundary is part of the public status contract:

• hsquared is the R-facing public package. It owns formula syntax, input validation, user-facing documentation, S3 methods, plotting, and the R-to-Julia bridge.
• HSquared.jl is the Julia computational engine. It owns relationship matrices, likelihoods, solvers, EBVs, G matrices, and low-level diagnostics.

An engine capability is not automatically an R capability. A Julia function may be implemented, tested, and marked covered in the engine’s validation_status() while the corresponding R formula, payload mapping, user documentation, and R-side evidence remain planned or partial. In that case the engine result is engine-covered, not R-public-covered.

Current 0.9 honesty fence

The current public_covered_count is 7. It counts the R-public covered surface; it is not the number of engine rows marked covered. The count must not increase merely because an engine-only validation row is promoted.

The current release is experimental 0.9.0. It does not claim production readiness, CRAN acceptance or public availability, or a covered-status flip.

In particular:

• Factor-analytic covariance (V4-FA) is covered only as a Julia engine, validation-scale, opt-in capability for the narrow S4 cell: t = 4, K = 1, positive Ledermann slack and interior uniqueness, with rotation-invariant G/R/psi outputs only. Broad calibration passed 8 of 10 scenarios, so it is not a general FA claim. R also has a partial, explicit expert-control payload for complete four-trait Gaussian pedigree fits with K = 1, trait intercepts, and estimated unstructured residual covariance. Formula grammar remains planned (cov = fa(K) is not parsed).
• Single-step (V2-SSHINV) is covered only as a Julia engine, validation-scale, opt-in capability for H-scale sigma-a2/sigma-e2 under ordinary defaults (tau = omega = 1, blend/ridge zero) and the teaching G = A22 + 0.05I kernel. H-scale h2 is reported but not claim-gated, and fit parity to preGSf90/BLUPF90 is still absent. R single_step() remains opt-in partial and does not inherit the engine row’s covered status.

See Model status, Validation evidence, and the live validation_status() output. For the engine-side ledger, use the HSquared.jl validation status and the twin Documenter twin-boundary page.

How to read a covered row

When a status row says covered, check all three scopes:

1. Engine scope: what Julia computes and the validation evidence attached to that row.
2. R-public scope: whether hsquared exposes the syntax and routes it through the bridge.
3. Default scope: whether the route is public/default, or remains opt-in and experimental.

Only the second scope changes public_covered_count, and only after the cross-twin bridge and R-side evidence are complete. Engine coverage alone is not permission to describe an R formula as fitted or production-ready.

Twin contract rule

Where one twin’s documentation states an input contract, an output definition, an identifiability claim, or an exactness claim, the other twin’s corresponding page must state it too, or link to it. A reader should not have to cross the language boundary to learn what a value means, what a function requires, or which parameters are identified versus rotation- or scale-dependent. HSquared.jl’s docs/src/twin-boundary.md is the sibling page for this rule on the Julia side and carries the matching paragraph (landed in HSquared.jl PR #338).

Documentation map (applied journey)

Both sites use the same five-step reader journey. This pkgdown article set owns formula examples and reporting fences; Documenter owns engine utilities and the live status table regenerated at build time.

Step	hsquared (here)	HSquared.jl (Documenter)
Get started	Getting started	Quick start
Choose a model	Fitting models, Formula grammar, Multivariate, Genomic prediction	Standard QG models, Model spec grammar, Multivariate models, Genomic models
Fit	Fitting models	Quick start, Fitting at scale
Diagnose	Visualizing models, validation_status()	Validation status
Report	Can I fit and report this?, this article	Twin boundary, Progression and evidence

Intentional asymmetry: comparator vignettes, Gryphon, QTL/GWAS status, inheritance systems, and GPU roadmap articles have no Julia mirror yet. Julia Developer pages hold backend roadmap detail that R-first readers can skip initially.