docs(trios-chat): port conventions for .t27 specs and the swap layout

[dmitrii-f-t27]

Closes #1824

Part of the epic #1812.

What

Adds docs/chat/T27_PORT_CONVENTIONS.md: the rules every agent follows when it writes a trios-chat .t27 spec in gHashTag/t27 or swaps generated code into crates/trios-chat/. Sections: owner decisions in force; spec location and module line; ASCII text; the verdict; types, bytes and constructs; tests; behaviour fidelity; checks 0-14; swap layout; crypto boundary; words we do not use; toolchain traps; how the snippets were checked.

Owner decisions recorded (2026-10-11): D5 = a named verdict struct with a payload-free enum, Ok first; D2 = own lane only (every port is written by agents acting as dmitrii-f-t27; no Queen fallback); D4 = interim hand-written adapters.

Documentation only. No Rust source, no Cargo.toml / Cargo.lock, no CODEOWNERS file changes, no .sh files.

L16 rationale: clippy -D warnings already fails at base 8b229e9 and ci.yml skips it; this PR changes no Rust source.

What changed against the draft after compile-checking

• Methods as free functions: the parameter must not be named self. gen-rust keeps the name and rustc rejects it ("self parameter is only allowed in associated functions"). The document now says type_method(t: *T, ...).
• @log2 is float-only in Zig (integer argument: BLOCKED); for f64 Zig passes and the Rust gets @log2 verbatim (parse error).
• \x00 escapes and raw UTF-8 in strings are wrong in both backends (test-report fails), not only in Rust.
• Cross-module use x::a::f; now resolves when the spec path has a specs/ directory above it (t27c splices f into the generated file); from inside the directory with a bare file name it is still BLOCKED. Helpers stay inline.

Snippet checks

t27c binary built from gHashTag/t27 master 67cbf82849e40a74e5cc92d4a25c764dc5862f90 (2026-10-10; not rebuilt for this PR). Between that commit and the current master 39d5af36b86c no change touches bootstrap/src/compiler.rs (checked with the GitHub compare API). Zig 0.16.0, rustc 1.94.0, bash. Each fenced t27 block of the document was extracted to its own file by a script (the doc has 3 t27 blocks and 1 rust block) and run as below.

$ t27c --version; zig version; rustc --version
t27c 0.5.2
0.16.0
rustc 1.94.0 (4a4ef493e 2026-03-02)

$ t27c test-report snippet1_xxx_guard.t27
--- test report: snippet1_xxx_guard.t27 ---

  tests       4
  pass        4
  FAIL        0
  rate    100.0%

  runtime asserts executed, per test (#6509; a pass with 0 is vacuous, T730):
       1  xxx_01_ok
       3  xxx_02_too_many_reports_got_and_max
       2  xxx_03_zero_id_reports_index
       2  xxx_04_duplicate_reports_index
  vacuous passes  0 of 4  (passed with 0 runtime asserts executed)
exit=0
$ t27c gen-rust snippet1_xxx_guard.t27 > snippet1_xxx_guard.rs && rustc --edition 2021 --crate-type lib --out-dir out snippet1_xxx_guard.rs
gen-rust exit=0
rustc exit=0
rustc error lines: 0
rustc warning lines (unused_parens):
   1 warning: 3 warnings emitted
   3 warning: unnecessary parentheses around `if` condition
$ t27c coverage snippet1_xxx_guard.t27
=== snippet1_xxx_guard.t27 test coverage ===
Functions: 1
Tested:    1 (100%)
Untested:  0
exit=0

$ t27c test-report snippet2_constructs_example.t27
--- test report: snippet2_constructs_example.t27 ---

  tests       9
  pass        9
  FAIL        0
  rate    100.0%

  runtime asserts executed, per test (#6509; a pass with 0 is vacuous, T730):
       1  cx_01_first_byte
       1  cx_02_sum_typed_local_array
       1  cx_03_total_size
       2  cx_04_name_len
       1  cx_05_mul_wide_u64_max
       2  cx_06_make_rec_len_into_u64
       1  cx_07_low_byte
       2  cx_08_is_big
       2  cx_09_counter_bump
  vacuous passes  0 of 9  (passed with 0 runtime asserts executed)
exit=0
$ t27c gen-rust snippet2_constructs_example.t27 > snippet2_constructs_example.rs && rustc --edition 2021 --crate-type lib --out-dir out snippet2_constructs_example.rs
gen-rust exit=0
rustc exit=0
rustc error lines: 0
rustc warning lines (unused_parens):
   1 warning: 7 warnings emitted
   1 warning: unnecessary parentheses around `if` condition
   2 warning: unnecessary parentheses around `return` value
   4 warning: unnecessary parentheses around assigned value
$ t27c coverage snippet2_constructs_example.t27
=== snippet2_constructs_example.t27 test coverage ===
Functions: 9
Tested:    9 (100%)
Untested:  0
exit=0

$ t27c test-report snippet3_cast_example.t27
--- test report: snippet3_cast_example.t27 ---

  tests       4
  pass        4
  FAIL        0
  rate    100.0%

  runtime asserts executed, per test (#6509; a pass with 0 is vacuous, T730):
       1  cex_01_widen_len
       1  cex_02_widen_mul
       1  cex_03_low_u64
       4  cex_04_be_prefix
  vacuous passes  0 of 4  (passed with 0 runtime asserts executed)
exit=0
$ t27c gen-rust snippet3_cast_example.t27 > snippet3_cast_example.rs && rustc --edition 2021 --crate-type lib --out-dir out snippet3_cast_example.rs
gen-rust exit=0
rustc exit=0
rustc error lines: 0
rustc warning lines (unused_parens):
   1 warning: 7 warnings emitted
   3 warning: unnecessary parentheses around `return` value
   4 warning: unnecessary parentheses around assigned value
$ t27c coverage snippet3_cast_example.t27
=== snippet3_cast_example.t27 test coverage ===
Functions: 4
Tested:    4 (100%)
Untested:  0
exit=0

Section 8 adapter (the rust block, extracted as is) plus an XxxError enum and 4 tests, next to the gen-rust output of snippet 1 in t27gen/xxx_guard.rs:

$ rustc --edition 2021 --crate-type lib --out-dir out xxx_guard.rs   # section 8 adapter + XxxError + include of the snippet 1 gen-rust output
exit=0
$ rustc --edition 2021 --test --out-dir out xxx_guard.rs && out/xxx_guard
exit=0
test tests::duplicate ... ok
test tests::ok ... ok
test tests::too_many ... ok
test tests::zero_id ... ok
test result: ok. 4 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

The "Do not write" column of section 4 was re-measured with the same binary on minimal probe specs (one construct each): []const u8 parameter -> &'static str (E0277); []const [4]u8 and []const []const u8 -> Zig BLOCKED + Rust parse error; [3][]const u8 -> Vec<const u8> (parse error); u64::MAX -> Zig BLOCKED "type u64 has no members"; const x: u128 = a; and the i128 form -> E0308; a as u128 -> parse error "unknown cast target type"; usize into a u64 field -> E0308; @as(u64, p) with p: u128 -> Zig BLOCKED; @as(u8, @intCast(x)) -> E0282; untyped [_]u8{..} local -> Zig BLOCKED "cannot cast pointer to tuple"; methods inside a struct -> Zig BLOCKED, spec-status NOFN; .Variant outside return -> E0425; generics -> BLOCKED; closures and HashMap -> parse error. The gen-rust repro specs are filed in gHashTag/t27#8891.

The three bash blocks of section 7 (added in 6b93cf5) were run as written on the section 3 template in a scratch git tree: every # expected: value matched, the seal file was src_port::trios::crates::trios-chat::rings::CR-CHAT-99::src::xxx_guard.json, tests field passed 4, total 4, failed 0, vacuous 0.

Not verified here: the section 7 checks on a real port, and the swap layout of section 8 inside the real trios workspace (no ring was swapped by this PR); the measured adapter sizes are quoted from the 2026-10-10 scratch drafts.

Dmitrii Fedorov (@dmitrii-f-t27)

[tri-claw]

Summary by t27-bees

This PR adds a comprehensive conventions document (docs/chat/T27_PORT_CONVENTIONS.md) for porting trios-chat Rust code to .t27 specs and swapping generated code back. It codifies owner decisions (D2, D4, D5, D6), module naming, verdict structure, type mappings, test requirements, swap layout, crypto boundary, and a 15-step pre-PR check suite with runnable bash snippets. All embedded .t27 snippets were validated against t27c, Zig 0.16.0, and rustc 1.94.0.

Worth a look

• docs/chat/T27_PORT_CONVENTIONS.md:350 (Check 5) — The automated test-count check expects >= N_TEST tests in the spec, but Section 5 (line 285) explicitly exempts split files and crypto-adjacent files, requiring a test-mapping table instead. Running the check suite on such a spec will produce a false failure.
• docs/chat/T27_PORT_CONVENTIONS.md:105 — The verdict template declares idx: usize, yet Section 6 notes "ports drifted usize -> u32 and leaked a test constant NOW" and the adapter (line 435) casts v.a as usize / v.b as usize for TooMany while passing v.idx directly. If the original error expects a non-usize index, this mismatches or truncates on 32-bit targets.
• docs/chat/T27_PORT_CONVENTIONS.md:185 (Section 4 table, "read-only slice of T") — The table states the adapter passes .to_vec() because gen-rust lowers []const T to Vec<T> by value, but the lowering rules are only illustrated for three types in the constructs example (line 255). Writers of other slice types ([]const Rec, []const u64, etc.) have no documented guarantee of the same lowering.
• docs/chat/T27_PORT_CONVENTIONS.md:385 (Check 12) — The SEAL path construction uses sed -n 's/^module \(.*\);.*/\1/p' to extract the module name. If the module line has a trailing comment or whitespace after the semicolon, the captured group includes it, producing an invalid .json filename and a misleading git status check.
• docs/chat/T27_PORT_CONVENTIONS.md:490 (Section 11) — "Restoring a file with mv keeps an old mtime: touch it, or cargo skips the rebuild." None of the check scripts in Section 7 include a touch after file operations (e.g., after gen-rust writes $OUT/$STEM.rs), so an agent following the checks verbatim can hit stale-mtime incremental-build skips.

---

_{Read: 1 files, +579 -0, the whole diff. Head 6b93cf5. Model: openai-compatible/nvidia/nemotron-3-ultra-550b-a55b. Commands: @t27-bees review | summary | help | pause | resume. Free for every repository.}

[dmitrii-f-t27]

Review points checked one by one; changes in 6b93cf5:

1. D6: section 0 now defines it (quirks of the original: preserve bit for bit unless a separate trios PR fixes them first; status pending, recommendation preserve). Section 6 points to it.
2. Check 2: NAMES is an explicit FILL value with an example (NAMES='validate_epoch_rollover', several names as 'f_one|f_two'), used as grep -cE "^[[:space:]]*(pub )?fn (${NAMES})[(]".
3. Section 7 is now three bash blocks (setup, checks 0-11 and 14, seal). Each expected result is a # expected: comment. The blocks were run as written on the section 3 template in a scratch git tree; every expected value matched.
4. []const T: no inconsistency. Measured with t27c from master 67cbf82849e4: ids: []const u64 lowers to pub fn validate_xxx(ids: Vec<u64>) -> XxxVerdict, so the adapter takes &[u64] and passes ids.to_vec(). Sections 4 and 8 now say this explicitly. The adapter still compiles next to the generated file and its 4 tests pass.
5. Check 12 repeats the guard: only from the t27 worktree root with the repo-relative spec path; git status --short --untracked-files=all .trinity/seals must show exactly the expected seal file; then read its tests field.

The t27 snippets and the Rust adapter are byte-identical to 40617b6 and were re-checked (test-report 4/4, 9/9, 4/4, 0 vacuous; rustc exit 0; Untested: 0).

Dmitrii Fedorov (@dmitrii-f-t27)