Skip to content

fix(website): a half-printed module was coloured as a whole one - #1084

Merged
gHashTag merged 1 commit into
mainfrom
fix/spec-health-partial-backends
Sep 21, 2026
Merged

gHashTag merged 1 commit into
mainfrom
fix/spec-health-partial-backends

Conversation

@gHashTag

@gHashTag gHashTag commented Sep 21, 2026 •

Copy link
Copy Markdown
Owner

The Spec Explorer's health chips read 976 working · 100 warnings · 338 broken.

Most of the 338 was one defect in one place. gen-js and gen-ts emitted references to
names they had not bound, so 126 specs produced modules that are syntactically perfect and
throw a ReferenceError at import — one unbound name costs every declaration in the file.
gHashTag/t27#4528 fixes that (gHashTag/t27#4529). This PR vendors the compiler that carries
the fix and teaches the catalog the third answer it now gets back.

The third answer

A declarations backend can produce an artifact that is real and incomplete: it prints
what it can and names what it could not, inside the artifact, as data (__NOT_EMITTED__, a
frozen list). Whole and half-printed must not share a colour — a partial module is exactly
what a "Working" chip would be lying about.

t27-corpus.mjs reads notEmitted from the backend rather than regexing
__NOT_EMITTED__ back out of the code — which would be a second, weaker implementation of
something the backend already knows exactly. It records partialBackends, tags the spec
issue/backend-partial, and puts it in warn.

The catalog spec stops holding numbers nothing checks

specs/catalog/onboarding.t27 gains HEALTH_FAIL_UNPARSED and HEALTH_PARTIAL, both
derived from the manifest by onboarding-from-spec.mjs and therefore checked by
check:onboarding.

Two things were removed rather than updated:

  • The hand-typed class breakdown. It added to 154 beside a sentence that said 145 — a
    breakdown nothing checked, which is the one kind of number this document is not allowed to
    hold.
  • assert HEALTH_FAIL_JS_ONLY > 0. True the day it was written, and a lie the moment
    the class it counts is fixed. A test that forbids its own subject from reaching zero is a
    test against the work.

Measured over the corpus this PR ships

1419 specs — five more than the last sync, picked up from upstream on the way past.

before after
✓ working 976 1017
⚠ warnings 100 184
✕ broken 338 218
js backend fails 335 211
ts backend fails 335 211

211 is exactly the set that produces no AST at all — c, rust and zig fail the same
211, and no backend can serve them. The js/ts-only failing family is zero. The remaining
7 are specs that parse and then lose a backend (6 × verilog_hir, 1 × verilog).

71 specs now carry a non-empty __NOT_EMITTED__ and are counted apart — neither whole
nor broken.

Cache

The wasm is 731 581 bytes, so its content tag moves from 3f1e073c963c86e2 to
bb39b9a5ca412a26. No browser holding the old immutable entry is ever asked for it — the
lesson of #1078, and the reason the tag is derived from the bytes rather than stored.

Gates run locally

check:spec-catalog (1419 exact source links) · check:onboarding (spec tests 9, asserts
49, all hold) · check:t27-evolution · check:explorer-languages · check:discovery ·
check:shared-core — all PASS. audit:en / audit:ru need CHROME_PATH and did not run
here; they run in CI.

Sequenced after gHashTag/t27#4529 in the sense that the source of the vendored wasm lands
there, but this PR is self-contained: the wasm bytes are in it.

🤖 Generated with Claude Code

{
  "version": 1,
  "head_sha": "a41600ad7f921412e64a47e3c4185b7dcc487743",
  "summary": "The Spec Explorer called 338 specs broken. With the js/ts value-layer fix vendored from t27, the manifest reports 218, and 71 specs that emit a real but incomplete artifact are counted apart as partial instead of being called either whole or broken.",
  "changes": [
    "t27-corpus.mjs derives partialBackends and notEmitted from the compiler's own targets.js.notEmitted field rather than regexing __NOT_EMITTED__ back out of the emitted code.",
    "A spec whose backends all emit, but where one of them omitted declarations, is now health warn and tagged issue/backend-partial instead of counting as fully working.",
    "notEmitted across backends is combined with a maximum, not a sum: one declaration refused by both js and ts is one missing declaration, not two.",
    "onboarding.t27 gained HEALTH_FAIL_UNPARSED and HEALTH_PARTIAL, both derived from the manifest by onboarding-from-spec.mjs so neither number can be typed by hand.",
    "A prose sentence asserting a count that nothing checked was replaced by an explanation of the class plus a constant the manifest verifies.",
    "Regenerated the vendored compiler wasm, manifest.json, shared-core.json, universe-atlas.json, agents.t27 and llms.txt against the new corpus of 1419 specs."
  ],
  "tests": [
    {
      "command": "npm run check:onboarding",
      "result": "reports the generated documents are up to date",
      "status": "passed",
      "evidence": "iterated sync, regenerate, sync until the printed constants stopped moving at corpus size 1419"
    },
    {
      "command": "npm run check:spec-catalog",
      "result": "the compiler is pinned at the new content hash",
      "status": "passed",
      "evidence": "prints compiler pinned at ?v=bb39b9a5ca412a26, derived by t27-wasm-tag from the new wasm bytes"
    },
    {
      "command": "node apps/website/scripts/t27-corpus.mjs",
      "result": "manifest health counts 1017 ok, 184 warn and 218 fail",
      "status": "passed",
      "evidence": "the same corpus read 976 ok, 100 warn and 338 fail before the vendored compiler changed"
    },
    {
      "command": "cargo test --bin t27c (upstream gHashTag/t27, branch fix/js-ts-value-layer)",
      "result": "1736 tests passed with none failing",
      "status": "passed",
      "evidence": "1736 passed, 0 failed, 2 ignored; the artifact vendored here is built from that branch"
    }
  ],
  "limitations": [
    "The 218 specs still counted broken produce no AST at all, so no backend can serve them; that parser work is deliberately not in this change.",
    "These health numbers only move on the live site once the upstream t27 compiler change lands and the wasm vendored here is rebuilt from it.",
    "Seven specs parse and then lose exactly one backend, six verilog_hir and one verilog, and this branch does not examine them.",
    "Test results are reported from local runs on this machine and are not independently rerun by the report generator."
  ],
  "tags": ["t27", "SpecExplorer", "compiler", "codegen"],
  "blog": {
    "title": "Why 338 specs looked broken when only 218 were",
    "summary": "A declarations backend that had no spelling for one initialiser used to refuse the entire module, so the Spec Explorer painted healthy specs red. Naming the omission inside the artifact instead turns them green, and introduces a third answer sitting between working and broken.",
    "outline": [
      "The health chip on app.t27.ai counted 338 broken specs, and that number turned out to describe how the js and ts backends reported failure rather than how many files were damaged.",
      "A declarations-only backend has a third possible answer: an artifact that is real but incomplete, printing every declaration it can and naming in __NOT_EMITTED__ each one it could not.",
      "Per-backend omission counts are combined with a maximum rather than a sum, because a single declaration refused by both js and ts is one missing declaration and not two of them.",
      "The five compiled backends receive null for that field rather than zero, so a catalog reading the manifest can tell no such question apart from no omissions at all.",
      "Every printed constant is derived from the manifest, so a corpus that grows by five specs in the middle of landing cannot leave a stale hand-typed number behind it."
    ]
  }
}

The Spec Explorer's health chips read 976 working / 100 warnings / 338 broken.
The 338 was mostly one defect in one place: `gen-js` and `gen-ts` emitted
references to names they had not bound, so 126 specs produced modules that are
syntactically perfect and throw a ReferenceError at import. gHashTag/t27#4528
fixes that; this vendors the compiler that carries the fix and teaches the
catalog the third answer it now gets back.

A declarations backend can produce an artifact that is real and incomplete: it
prints what it can and names what it could not, in the artifact, as data. Whole
and half-printed must not share a colour -- a partial module is exactly what a
"Working" chip would be lying about. `t27-corpus.mjs` reads `notEmitted` from
the backend rather than regexing `__NOT_EMITTED__` back out of the code, records
`partialBackends`, tags the spec `issue/backend-partial`, and puts it in warn.

`onboarding.t27` gains HEALTH_FAIL_UNPARSED and HEALTH_PARTIAL, both derived
from the manifest by `onboarding-from-spec.mjs` and therefore checked. Its
hand-typed class breakdown is gone: it added to 154 beside a sentence saying
145, which is the one kind of number this document is not allowed to hold. The
test that demanded HEALTH_FAIL_JS_ONLY > 0 is gone too -- a test that forbids
its own subject from reaching zero is a test against the work.

Measured over the corpus this commit ships (1419 specs, five more than the last
sync):

              before    after
  ok            976      1017
  warn          100       184
  fail          338       218

  js fails      335       211
  ts fails      335       211

211 is exactly the set that produces no AST at all -- c, rust and zig fail the
same 211, and no backend can serve them. The js/ts-only failing family is zero.
71 specs now carry a non-empty `__NOT_EMITTED__` and are counted apart.

The wasm is 731 581 bytes, so its content tag moves from 3f1e073c963c86e2 to
bb39b9a5ca412a26 and no browser holding the old immutable entry is asked for it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@github-actions github-actions Bot added the status:in-progress 🔵 Agent working label Sep 21, 2026
@gHashTag
gHashTag merged commit 5afa6a1 into main Sep 21, 2026
31 of 38 checks passed
@gHashTag
gHashTag deleted the fix/spec-health-partial-backends branch September 21, 2026 12:51
@github-actions github-actions Bot added status:completed Done and removed status:in-progress 🔵 Agent working labels Sep 21, 2026
github-actions Bot added a commit that referenced this pull request Sep 21, 2026
Merge pull request #1084 from gHashTag/fix/spec-health-partial-backends

fix(website): a half-printed module was coloured as a whole one
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant