Normalize markdown heading levels and remove @module JSDoc tags - #1756

The merge queue dequeued this for MERGE_CONFLICT. One conflict, in the Related
section: both sides were additive, so both survive — my two ownership links,
and main's note recording that jsdoc-typedef-strip-internal is retired rather
than merely unlinked.

Main's heading normalization and todo renames (#1756) auto-merged; all links in
the three touched files still resolve and tsc is clean.

Re-measured everything the documents assert, since main moved a lot. The
invariants hold exactly: 16 private.ts, fjs/emergent_testing still has none
(so it remains a valid stand-in for a future module), 0 runtime imports among
the 226 in authored .ts, and bigfloat's divide is still unexported with
_BigFloatWithRemainder still private.

The absolute counts drifted for the third time, though: 675/659 is now 677/661
and 377 declarations is 378. The numbers were never the claim — "exactly 16
disappear, and they are exactly the private.d.ts" is — so the prose now says
that, with the totals marked as a re-measured snapshot. Future drift makes the
snapshot old rather than making the document wrong.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LqeS5t2ZKkSu3chRPMXR7n

Review caught a trap in this issue's own instructions. "Every `["{}"]` →
`["{}", []]`" reads as a blanket rewrite, but one of the seven occurrences
in `edag-stage1-discussion.md` is not an empty object: the validation rule
writes "every element of a `["{}"]` node's entry array must be a recognized
entry form", where the tag names *an object-constructor node*. Rewriting
that one with the examples makes the sentence contradict itself — an empty
entry array has no elements to check — so an implementer following this
issue literally would have introduced the defect.

It is also the occurrence #1756 introduced rather than inherited: the
previous wording said "every `["{}", ...]` operand", which stopped
describing the shape once the operands became one array.

Added as a fourth class with its own treatment. The shorthand only became
ambiguous when `["{}", []]` acquired a meaning, so it wants a nonempty
placeholder — `["{}", entries]` — rather than the empty form or a bare tag.
The counts in the problem statement, the class-1 blurb and the task list
are qualified to match: six genuine empty objects, one shorthand.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T7vAocRuxfmWJDnujCoMup

Two issues asked the same question. #1756 answered it — strip the tag,
`fjs/AGENTS.md` §2 was right — and applied that to 102 files, then deleted
`fjs/todo/module-tag-on-types-ts.md` and missed this one.

Every premise in it is now false. "90 of the 94 `types.ts` files carry it
anyway" is 0 of 98. Its three tasks are done: the convention was decided,
applied to every `types.ts`, and `fjs/web/types.ts` — named as the minority
case — matches. Nothing cites it.

Nothing to move before deleting: the decision it asked for lives in
`fjs/AGENTS.md` §2, which never changed, and the CI-enforcement question it
did not ask about is settled the other way by §6.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T7vAocRuxfmWJDnujCoMup

Three more review findings, all correct.

The module header lacked @module. fjs/AGENTS.md §2 requires it on every
module.* entry point, and all five sibling fjs/ci modules carry one; #1756
removed the tag from non-module files, not from these.

The proof lived in the parent. fjs/ci/deno, fjs/ci/nix and fjs/ci/node all have
co-located proofs, so the precedent is the opposite of what I assumed. The job's
own shape is now proved in fjs/ci/package/proof.f.mjs, and the parent keeps only
what the assembled workflow can show: that the job is wired in, and that the job
it waits for is really the one that uploads — an edge pointing at a job that
never produces the artifact would satisfy the ordering and still never run.

The compiler pin was the substantive one. Reading devDependencies.typescript
gives a dependency specification, not a resolved version: this repository pins
=7.0.2, but a project writing ^7.0.0 would have had npm choose, which is exactly
the determinism the checkout-less job exists to preserve. The script now
compares the installed version against the literal pin and refuses when they
differ.

That case is worse than it looks, and the test shows why: ^7.0.0 installs 7.0.2
today, so a range is indistinguishable from an exact pin until the day the
registry publishes 7.0.3 and the verdict moves with no change to the package.
Verified: ^7.0.0 exits non-zero, =7.0.2 exits 0 at 396 declarations, and a
second tarball named other-package still resolves and passes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LqeS5t2ZKkSu3chRPMXR7n

§2 said the tag belongs only to `module.f.mjs` / `module.mjs`. That is the
rule #1756 enforced across 102 files, and it had the reason backwards.

`deno doc` reads the tag and nothing else. A file whose leading block
carries it gets that prose as `module_doc`; a file without it gets no
`module_doc` at all — the block is dropped, not demoted. Checked against
the Deno the repository pins, for `.mjs` and `.ts` alike, and the tag need
not be in the first block, only in some block. So the tag is what makes a
leading block *be* documentation, and it goes wherever a file has module
documentation to publish: `module.f.mjs`, `types.ts`, `private.ts`. A block
holding only `@import` tags has nothing to attach and wants none. Where the
documentation is never published the tag buys nothing, which is `proof.*`.

98 of the 102 stripped files had real prose, so their module documentation
is currently invisible to `deno doc` — the output
`fjs/website/todo/publish-deno-doc-to-website.md` plans to publish. §2 says
so plainly rather than describing a tree that does not exist, and points at
the restore.

`fjs/todo/module-tag-restore.md` (P3) carries the inventory, split by the
three decisions it actually contains: 89 `types.ts` with prose, mechanical;
11 proof files where the rule says leave them but that is worth confirming;
and two files that are neither — `browser.mjs` has real prose and reads
like the first group, `testlib.f.mjs` held only `@import` tags and wants no
tag at all.

`todo/jsdoc-verification.md` (P4) asks how any of this could be checked.
Three passes over one tag with no signal at any point is the argument for
looking; §6 ruling out text patterns is why the answer has to parse, and
"not worth it, leave it to review" is a legitimate outcome to record.

Documentation only. `npx tsc` clean, suite 3533/3533.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T7vAocRuxfmWJDnujCoMup

…d claim

Three review findings, all against text I wrote in the previous commit.

§1.2 still showed a `proof.f.mjs` leading block carrying `@module`, while the
§2 I had just rewritten said a proof's documentation is never published so
the tag has nothing to attach to. Same file, opposite instructions for the
same shape. The example loses the tag and says why.

The restore issue omitted `private.ts`. All 16 have prose and none carry the
tag — stripped by #1750 rather than #1756, so they were not in the 102 I
counted, but it is the same reading and the same fix, and §2 names
`private.ts` explicitly. As written the issue could have been completed in
full while leaving 16 files violating the rule it exists to satisfy, and its
last task says to delete §2's non-compliance note.

And the publication rationale was overstated. The website issue plans
`deno doc --html **/module.f.mjs`, a glob excluding every `types.ts` and
`private.ts`, so restoring the tag alone puts nothing on the website. The
tag is necessary, not sufficient: it decides whether `deno doc` *can* see a
file's module documentation, and what the build is pointed at is a separate
question. Both §2 and the issue say that now, and widening the glob is named
as the other half.

Also added: a task to correct `todo/migrate-typescript-to-mjs.md`, which
restates the old rule verbatim under "Module header and import ordering"
rather than linking §2, so it did not move when §2 did.

Documentation only. `npx tsc` clean, suite 3533/3533.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01T7vAocRuxfmWJDnujCoMup