Add specs/vsa/trinity_compat: the VSA contract the Trinity facade runs (S04 of trinity#988)

[dmitrii-f-t27]

Closes #3566 -- work package S04 of gHashTag/trinity#988: the VSA and numeric contract the Trinity facade actually runs. Stacked on #3579 (S03), #3578 (S02) and #3577 (S01): the diff shows all four until the earlier ones merge; S04 itself touches only specs/vsa/, conformance/, tools/, docs/now/, the S01 README and OWNERS.

What

specs/vsa/trinity_compat.t27 (module vsa_trinity_compat, KIND = "vsa-compat"). trinity:src/trinity.zig re-exports sixteen VSA operations from the package the consumer pins -- gHashTag/zig-golden-float e7ce3288, src/vsa/core.zig, passed through gHashTag/zig-hdc b73b2fa2 name by name -- while specs/vsa/vsa_core.t27 describes the same names with other semantics. The spec names the facade and the owner and records, per export, the owner function (file:line), the canonical function (name:line), a finding and a verdict:

• 4 agree on every input: permute, inversePermute, countNonZero, vectorNorm.
• 6 agree on equal lengths only (the length policies differ: the owner pads to max(len) with a zero trit and divides dot similarity by max(len), the canonical spec cuts to min(len) and divides by min(len); cosine norms run over the whole vector in the owner and over the shared prefix in the spec): bundle2, bundle3, cosineSimilarity, hammingDistance, hammingSimilarity, dotSimilarity.
• 6 differ in kind: bind and unbind (the owner multiplies, so a zero trit annihilates; vsa_core.t27, ops.t27 and coptic_bind keep the zero trit as an identity), encodeSequence (the owner adds permuted vectors with a carrying balanced-ternary add, not a bundle), probeSequence, randomVector (two different generators), bundleN (the owner takes the sign of the sum of all vectors; the canonical spec folds bundle3(result, result, next) and reads vectors[2] for a count of two).

The semantics the pinned consumer executes are selected as the reference of the Trinity profile and stated as elementwise functions the C backend runs, because the compiler does not lower array parameters (S02): trit_bind, trit_bind_zero_identity, trit_sign, trit_bundle2, trit_bundle3, trit_differs, trit_nonzero, len_max, len_min, rotate_right, rotate_left, packed_bytes, pack_index, pack_slot, cosine_defined, tri27_bind. The zero-identity bind of the canonical specs and the additive TRI27 register bind of src/tri27/emu/executor.zig (mod 19683, zero register as identity) are classified separately, each with its own function and tests. The numeric representation is declared: i8 trits, five to a byte, two capacities in one package (12000 packed in packed_trit.zig, 59049 hybrid in ternary/hybrid.zig, the type the sixteen operations take), SIMD width 32, an i32 dot accumulator in the owner (i64 in the canonical spec; both hold, |dot| <= 59049), f64 similarities, no GoldenFloat format on the facade (0 references to gf16 in trinity.zig, sdk.zig, science.zig, vm.zig, jit.zig), no allocation and no error in the sixteen operations. Ten test blocks (the nine bind pairs, the four pairs where the variant differs, self-inverse on nonzero trits only, bundle ties, the length rules, the rotation law, packing arithmetic, the cosine precondition, the TRI27 cases) and five invariants.

tools/trinity_vsa_compat.py

• vectors writes conformance/vsa_trinity_compat.json from a Python statement of the owner's semantics as read at e7ce3288: 149 vectors over 15 operations -- equal lengths, one SIMD chunk, a chunk plus a remainder, unequal lengths, all-zero and empty vectors, ties, every pair of trits once, the rotation identities (k = 0, k = len, k > len) and the inverse law, packing, the TRI27 fix-up. The pseudo-random trits come from the tool's own LCG, never from the owner's PRNG.
• run generates the spec to C with t27c gen-c, composes the elementwise functions into whole-vector operations in a C driver whose length rules are the spec's own len_max, len_min and rotate_*, replays every vector and records the verdict with the compiler, the C compiler, the host and the spec hash. Model and spec are two independent statements of one reading of the owner; a failing vector names a wrong reading, a wrong function or a wrong composition.
• check holds the committed record to the spec and the model: drifted vectors, constants or operations, a missing operation, a replay of another spec text, a changed vector count and a recorded failure are findings; the facade tables must have one entry per export, every verdict must be one of VERDICTS and open its finding, and the three counts must equal the verdicts.
• --self-check plants a wrong expected trit (fails exactly its vector), a zero-identity bind in the spec (fails only bind-shaped vectors: 28 of 149, all bind, unbind, cosine_similarity, dot_similarity), drifted vectors, a stale replay and a recorded failure.

Also: docs/now entry; specs/trinity/README.md gains the S04 section and two rows; specs/OWNERS.md names the file under vsa/; seal .trinity/seals/vsa_vsa_trinity_compat.json; tools/published_figures.py test-blocks pin 12663 -> 12673.

Measured (2026-09-12)

• t27c typecheck: 0 errors, 0 warnings; gen-c + cc -DT27_TEST_MAIN: All 10 tests passed.; gen, gen-rust, gen-verilog exit 0.
• Replay: 149 of 149 vectors pass with t27c 0.2.0 and Apple clang 21 (the record carries them).
• Not measured: the owner's Zig itself. The package does not build with the Zig available on this host (0.15.2 cannot link against the host SDK; the 0.17 nightly rejects the package), so the reference is read from the owner's source and executed through the spec's functions; the spec records this in NOT_MEASURED. A differential run against the owner remains the owner's own test suite.

Verification

python3 tools/trinity_vsa_compat.py --self-check                        ok (12 checks)
python3 tools/trinity_vsa_compat.py vectors / run / check               149/149, 0 findings
t27c seal --verify specs/vsa/trinity_compat.t27                         all hashes MATCH
check_seal_currency/coverage, specs_generate, duplicate_declarations, duplicate_agreement, assertionless,
json_parses, devhome, documented_commands, conflict_markers, catalog count/integrity, damage_negatives --require,
ring_spec_drift, published_figures, status tables, untrusted interp, now-entry shape (as PR)   exit 0
t27c ci --repo-root .                                                   115 issues, all pre-existing on master

The red test-ratchet on #3578/#3579 is pre-existing: the same 23 Rust tests (icarus_lowerable, lex_conform, parse_conform, tests_w458) fail on every Bootstrap Test Ratchet run of master since 2026-09-08 (e.g. run 34237060544 at f6a4a0fa, same "113 targets ran; 23 failing" summary); the S02 fixtures do not change the set.

What this does not claim

• That vsa_core.t27 is wrong: it is a different contract, and this spec records which one the consumer runs. Reconciling the two, or moving the consumer to the canonical semantics, is a decision for the owners, not a side effect of S04.
• That whole-vector operations are lowered by the compiler: the composition lives in the tool's C driver and is stated in the record (operations), the elementwise functions live in the spec.
• Anything about bundleN for more than three vectors beyond what src/vsa/core.zig:324 says, or about the sequence helpers' numeric behaviour: they are recorded as differing in kind and carry no vectors.

Do not merge without the owner's approval.

🤖 Generated with Claude Code