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); replaces #7, which GitHub marked merged although its commits never reached a landed branch; 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, is a stale assertion that predates this stack (it summed a per-backend count against a spec count); it is fixed in the stacked brief PR feat: t27_spec brief by default; field lists and failure reasons from a .t27 spec (Closes gHashTag/t27#10090) #10.
• 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 t27_examples, a new MCP tool that returns 1–3 short, compiler-checked .t27 slices for a given topic (clocked, comb, fn, test, reset with async/sync/none). The topic→rows mapping and the pinned commit live in specs/t27mcp/examples.t27, compiled to wasm/examples.wasm + wasm/examples_table.mjs; examples.mjs fetches each slice from the pinned commit and cuts the lines.

Worth a look

• examples.mjs:14–17 — Manual WASM memory management: base captures the initial memory size, then memory.grow(1) adds 64 KiB, and the query string is written at base. If the WASM module ever uses more initial memory or the string exceeds ~64 KiB (currently capped at 200 chars), this overwrites or reads garbage. The coupling between JS layout and WASM exports is fragile.
• examples.mjs:24–25 — at(n) returns l[n-1] or [] if undefined. EX_FOOTER[8] = 257 (for the reset_sync row) is far beyond the 40-line slice limit; if the source file actually has ≥257 lines, an unrelated line gets appended to the example. This looks like a sentinel that should be NO_POS (4294967295) instead.
• wasm/examples_table.mjs:14 — PIN = "a18d7ee14a99..." hardcodes a single commit. If that commit becomes unreachable (force-push, repo deletion, GitHub outage), all t27_examples calls fail. No fallback or versioning strategy is present.
• server.mjs:663 — The handler passes fresh through to getText, but examples.mjs doesn't validate or sanitize the topic string before lowercasing and truncating. An extremely long topic string (before the 200-char slice) could cause excessive allocation in TextEncoder.
• smoke.mjs:115–121 — Smoke tests assert exact strings like fn on_clock and specific topic names (reset_async, reset_sync). These are tied to the current pinned corpus; any regeneration of examples.t27 that changes the selected slices or their line ranges will break the tests even if the tool works correctly.

---

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