feat: t27_examples -- short compiler-checked worked examples per .t27 topic

[gHashTag]

Closes gHashTag/t27#10081

Part of the epic gHashTag/t27#10066 (learnability: worked examples for cheap models). Stacked on #8 (t27-check); the spec is gHashTag/t27#10083.

What

A new tool, t27_examples: give it a topic (clocked, comb, fn, test, or reset with async, sync or none) and get one to three short slices of real specs, at most 40 lines each, with one line on what each shows. An unknown topic returns the list of topics and no example.

t27_examples({topic: "clocked counter"})
{ topic: "clocked", pin: "a18d7ee1...", examples: [
  { path: "specs/ternary/clocked_counter.t27", lines: "25-37", why: "Smallest clocked module: ...",
    source: "module ClockedCounter;\nvar count : u8 = 0\n\nfn on_clock() {\n    count = count + 1\n}\n..." },
  { path: "specs/fpga/ro_race.t27", lines: "16-46", ... } ] }

• wasm/examples.wasm + wasm/examples_table.mjs: generated from specs/t27mcp/examples.t27 by t27c gen-c + zig cc and t27c gen-js. The spec holds the topic matcher, the pinned commit and the pointer table; commands and sha256 are in wasm/BUILD. Built on the Railway lab.
• examples.mjs (24 lines) is glue: it passes the question to the wasm, fetches each row's file at the pinned commit through the server's cached getText, and cuts the lines. No table and no rule lives in it.

Hand-written JavaScript added: examples.mjs 24, server.mjs 8, smoke.mjs 8 = 40 lines (cap: 40 per file, 80 per PR).

Evidence

• npm run smoke: the three new t27_examples checks pass (clocked slices of at most 40 lines containing fn on_clock; async reset is reset_async and sync reset is reset_sync; an unknown topic returns the topic list and no example). The run's one failure, backendFailures tally matches the specs blaming a backend (737 counted vs 113 blaming), is in the live atlas data and in code this PR does not touch; it is the kind of tally logic the epic's last item moves into .t27.
• Each topic answers with 955 to 1900 bytes of JSON.
• Spec side: 8 of 8 tests, 0 vacuous, negative controls (spec(t27mcp): examples -- which short slice of the corpus answers a .t27 idiom question t27#10083). Every slice was rebuilt from the pinned commit and run with t27c test-report on the lab.

🤖 Generated with Claude Code

[tri-claw]

Summary by t27-bees

This PR adds a new MCP tool t27_examples that returns 1–3 short, compiler-checked .t27 slices (≤40 lines each) for topics like clocked, comb, fn, test, and reset (async/sync/none). The topic matcher and pointer table live in a .t27 spec compiled to wasm/examples.wasm + wasm/examples_table.mjs; examples.mjs (24 lines) fetches the actual source at a pinned commit and extracts the lines.

Worth a look

• examples.mjs:13–15 – W.memory.grow(1) is called after capturing base = W.memory.buffer.byteLength. The Uint8Array view is created inside topicOf (after the grow), so it uses the new buffer; this is correct, but fragile if the wasm module ever uses more memory or if grow fails (it throws on OOM, which would crash the tool).
• examples.mjs:25 – fetchText can throw (network error, 404 at the pinned commit). No try/catch; a missing file turns into an unhandled rejection that bubbles to the MCP caller as a generic error.
• wasm/examples_table.mjs:48 – EX_FOOTER[8] = 257 for the reset_sync slice (lines 21–58). at(257) accesses l[256], requiring the source file to have ≥257 lines. The smoke test passes, so the current file is long enough, but this coupling between a distant footer line and the slice is not validated by the 40-line limit.
• server.mjs:661 – The handler passes (pin, path) => getText(\${RAW}/${pin}/${path}`, fresh). RAWandgetTextare not in the diff; if either changes signature orRAW` format, this breaks silently at runtime.
• wasm/BUILD:89–97 – Build instructions pin t27c 0.5.2 and zig 0.16.0 on the Railway lab. The checked-in examples.wasm and examples_table.mjs must stay in sync with specs/t27mcp/examples.t27; a spec change without a rebuild produces stale data (the negative control in the spec catches width > 40, but not semantic drift).

---

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