spec(t27mcp): examples -- which short slice of the corpus answers a .t27 idiom question

[gHashTag]

Closes #10081

Part of the epic #10066 (learnability: worked examples for cheap models). Stacked on #10080 (mcp-t27-check), which adds specs/t27mcp/ and its OWNERS.md row.

What

specs/t27mcp/examples.t27 (module T27mcpExamples): the decision behind the t27 MCP server's new t27_examples tool (gHashTag/t27-mcp). A model that learns .t27 idioms from failed compiles pays one round trip each; the corpus already shows each idiom in a small tested spec, but t27_spec returns the whole file. This spec holds the pointers.

• topic_code(q): maps the words of a question to one of seven topics (clocked, comb, fn, test, reset_async, reset_sync, reset_none), in a fixed order. async is tested before sync, which it contains. A question no rule knows gets T_NONE, and the server then lists the topics and invents no example.
• pick(topic, k): the row of the k-th example of a topic, or NO_ROW.
• Tables (emitted for the server by t27c gen-js): PIN (one commit of this repository, so a pointer cannot drift), and per row the path, the line range, an optional module / use / footer line and a one-line reason.
• row_ok / bad_rows: every row names a non-empty range and a rebuilt slice of at most 40 lines.

specs/OWNERS.md extends the t27mcp/ row.

Evidence (Railway lab, t27c 0.5.2)

• t27c test-report specs/t27mcp/examples.t27: 8 of 8 pass, 0 vacuous.
• Negative controls in the spec: an unknown question gets no topic and no row; row_ok refuses topic 0, an out-of-range topic, an empty or reversed range and 41 lines. With one row widened past 40 lines the table test fails (7 of 8).
• Every row's slice was rebuilt from PIN and run with t27c test-report: parse and typecheck clean and, where the slice has tests, all pass with 0 vacuous. The reset_sync slice has no tests and says so. A candidate for reset_none (verilog_prim.t27) was dropped because it does not compile on its own (undeclared identifier 'Startupe2Out', it needs its use closure).
• t27c gen-c plus zig cc -target wasm32-wasi lowers it to a 914-byte wasm; the build and sha256 are in wasm/BUILD of the server PR.
• Each topic answers with 955 to 1900 bytes of JSON.

Known limit

reset_sync is weak: the corpus has no small, tested synchronous reset. A synchronous reset is ordinary logic (the slice shows the ResetKind enum and the release-path shift register, with no tests), so the row's reason says that instead of claiming more.

find and has repeat the two helpers of check_hints.t27 instead of importing them (I did not try use across the two specs). A shared string-helper spec for t27mcp/ is a follow-up.

🤖 Generated with Claude Code