Migrate fjs/sul, fjs/media/html, fjs/crypto/sign, fjs/types/rtti to .f.mjs - #1485

Reviewed at 3024c8c against main (cbcc7ab). Three modules now — fjs/sul, fjs/media/html, fjs/crypto/sign. The migrations themselves are clean; one recurrence of the stale-link issue from #1484.

Runtime logic is provably unchanged

crypto/sign carries RFC6979 deterministic nonce generation, so "looks equivalent" isn't good enough. I compared main's compiled JavaScript (module.f.js from prepack) against the authored module.f.mjs on this branch, normalizing only the things TypeScript's emitter adds or an annotation removes — semicolons, and the parens left behind by dropped as const/type annotations:

TOKEN-IDENTICAL runtime: fjs/crypto/sign
TOKEN-IDENTICAL runtime: fjs/sul
TOKEN-IDENTICAL runtime: fjs/media/html

All three are token-for-token identical. The large computeK hunk in the diff is entirely re-indentation from the arrow chain changing shape — no expression moved.

Also verified

• npx tsc clean; 2356 pass / 0 fail.
• Public type surface: 0 removed, 0 changed. No any as a type anywhere in the emitted declarations.
• The _ prefix convention was applied on its own this time — _Attributes, _HashState, and _Signature were all non-exported type declarations on main and all carry the prefix here. That is the Byte/NodeList class of issue not recurring, which is the outcome I was hoping for.
• CHANGELOG has entries for all three, and their claims check out: media/html/types.ts does export Element/Node, sul/types.ts does export EncodeState/Encode.
• Both new .f.mjs proofs import only .f.mjs runtime modules, so they satisfy §2 — no repeat of the revert that #1484 needed.
• The crypto/sign commit updated its own todo/ docs in the same change. That is the right instinct; it just wasn't applied to the other two.

Three doc references to files this PR renames are stale

Same check as last time — main has 49 broken references, this head has 52, and the three added are yours:

65y-proof-asserteq-adoption.md:141 is the same half-updated-line shape as last time, now from the other side: it reads fjs/sul/proof.f.ts:1, fjs/sul/level/hash/proof.f.mjs:1 — the hash half was fixed in #1484 and the sul half on the same line is now stale.

Since this is the second PR in a row, it may be worth a one-line grep in the migration checklist — grep -rn 'old/path\.f\.ts' --include='*.md' . after each rename — rather than catching it in review each time.

Minor

The summary describes only fjs/sul; fjs/media/html and fjs/crypto/sign arrived after it was written. The CHANGELOG covers all three correctly, so this is just the PR body.

No correctness objection — happy to approve once the three references are updated.

Reviewed at 93fdc6e. The three stale references from my last pass are fixed, and this round introduces none — main and this head have the same 49 broken doc refs, so the rename sweep is now clean. Six modules migrate here.

Runtime logic is unchanged

Same method as before — main's compiled module.f.js versus the authored module.f.mjs, normalizing only semicolons and annotation-parens:

TOKEN-IDENTICAL: fjs/crypto/sign
TOKEN-IDENTICAL: fjs/sul
TOKEN-IDENTICAL: fjs/media/html
TOKEN-IDENTICAL: fjs/types/rtti
TOKEN-IDENTICAL: fjs/types/rtti/ts
DIFFERS:         fjs/types/rtti/common

The one difference is worth calling out because it is the migration working as designed, not a defect. main's emit begins with import {} from '../module.f.js'; — a bare side-effect import left behind because rtti/common/module.f.ts imported types from ../module.f.ts. Now those come through /** @import … from '../types.ts' */, so the runtime edge is gone. Strip that single import from main's emit and the two files are byte-identical. That is exactly the "type-only edge the migration wants gone" from #1483, and it is unobservable here since these modules are pure.

npx tsc clean, 2356 pass / 0 fail, no any as a type in any emitted declaration, public surface 0 removed.

1. Primitive0, Tag0, and Tag1 are no longer tied to their runtime lists

On main these were derived, so the list was the single source of truth:

const primitive0List = ['bigint', 'boolean', 'number', 'string'] as const
export type Primitive0 = typeof primitive0List[number]
export const tag0List = [...primitive0List, 'unknown'] as const
export type Tag0 = typeof tag0List[number]
const tag1List = ['array', 'record'] as const
export type Tag1 = typeof tag1List[number]

In types.ts they are now hand-written unions, while the lists stay in module.f.mjs. They agree today, so nothing is broken — but the guarantee that they must agree is gone. I tested it rather than assuming, in clean trees (an earlier attempt of mine was contaminated by prepack artifacts shadowing the .mjs with its .d.mts, so these numbers are from trees with no emitted files). Adding 'symbol' to primitive0List:

Both baselines are 0. My probe is a Assert<Equal<…>> that I negative-controlled first: asserting a deliberately false equality yields 2 errors, so silence means agreement rather than a probe that never ran.

Two fixes, both of which I verified compile and restore the guarantee:

• Tag0 is a one-liner, since tag0List is already exported. import type { tag0List } from './module.f.mjs' in types.ts, then export type Tag0 = typeof tag0List[number]. Baseline stays clean; the 'symbol' edit goes back to 2 errors. This is the same type-only import back into module.f.mjs that fjs/asn.1 already does.
• Primitive0/Tag1 can't do that without exporting their lists, so instead pin them from inside module.f.mjs, which can see them:

/** @typedef {Assert<Equal<Primitive0, typeof primitive0List[number]>>} _Primitive0Pinned */
/** @typedef {Assert<Equal<Tag1, typeof tag1List[number]>>} _Tag1Pinned */

Clean at baseline; drifting tag1List produces Type 'false' does not satisfy the constraint 'true'.

Worth noting this also confirms /** @type {const} */ ([…]) is behaving as a real as const — otherwise the derived form would not have matched the literal union at baseline.

2. Type0 and MakeType1 are newly public without the _ prefix

Both were non-exported on main (type Type0<T extends Tag0>, type MakeType1<K extends Tag1>) while appearing in the signatures of exported values like array: MakeType1<'array'>. They are now exported from types.ts unprefixed.

This is the Byte/NodeList case again, and the reason I raise it rather than assume it's deliberate is that the same PR gets it right five times — _Attributes, _HashState, _Signature, _Tests, _Entries all carry the prefix. So the convention was applied, just not to these two.

If Type0 is meant to be public now — it is documented and every exported Boolean/Number/String alias is built from it — that is a defensible call; it just deserves to be intentional rather than a side effect of the move.

No correctness objection; CI is green on the earlier commits and still running here. Happy to approve once these are settled.

Approving. Reviewed at b174648 against main (cbcc7ab). Thirteen modules.

Both prior findings are fixed, and the fix demonstrably works

439cf51 restores the derived-type guarantee and applies the prefixes. I re-ran the drift test rather than reading the diff — clean tree, no prepack artifacts:

Baseline is clean, so the lists and the types can no longer drift apart silently. Tag0 is back to typeof tag0List[number] via the type-only import, and Type0/MakeType1 are now _Type0/_MakeType1.

Runtime logic across all thirteen modules

main's compiled module.f.js versus each authored module.f.mjs:

equivalent: 13   differing: 0

I discount only four things, each an artifact of the migration rather than a change: elided type-only imports (the bare import {} from … TypeScript leaves behind), .f.js → .f.mjs specifiers for modules co-migrated in this PR, trailing commas, and parens left by removed annotations. To make sure that normalization isn't so permissive as to be meaningless, I checked it two ways: it still reports ci/bun and ci/deno as different modules, and injecting a one-token change (--release → --debug in ci/rust) is caught.

Also verified

• npx tsc clean; 2356 pass / 0 fail.
• Public type surface: 0 removed. 22 additions, every one _-prefixed — the convention is now being applied without prompting, including on the new media/nix split.
• The nine changed entries are all benign: Boolean/Number/String/Bigint/Unknown differ only by the Type0 → _Type0 rename, Expression only because its constituents gained the prefix, Primitive0/Tag1 are the intended re-derivation, and _Merge is my by-name comparison seeing btree's _Merge<A, T> alongside sul's unrelated module-scoped _Merge.
• No any as a type in any emitted declaration.
• Doc references are clean — 43 broken on main, 43 here, none added. The media/nix, rtti, and ci commits each swept their own todo/ files as they went, which is the habit that closes this out.

One nit

The two newest CHANGELOG entries name the pre-migration file — "fjs/types/rtti/parse/module.f.ts migrates from…" — where the sibling entries in the same section name the module (fjs/types/object, fjs/ci/common). Naming the old path is defensible for a migration note; it is only an inconsistency within one section, and not worth a commit on its own.

To be explicit about one thing my sweep flags that should not be changed: CHANGELOG.md:377 references fjs/ci/common/module.f.ts inside the released 0.39.0 section. §8.3 says not to rewrite released sections from an unrelated PR, so leaving it is correct.

CI is green on the earlier commits and still finishing on b174648; I verified locally at b174648 directly.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5941c986a1

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a035585300

Reviewed at e11269a (14 modules now). a035585's claim checks out — I scanned every relative markdown link in the repo and there are 0 label/target extension mismatches left. tsc clean, 2356 pass / 0 fail, public type surface 0 removed, 23 additions all _-prefixed.

fjs/bnf reorders top-level declarations (fullRange/unicodeRange/unicodeMax move below eof), so it is the one module that isn't token-identical to main's compiled output. Reordering consts can bite through TDZ, so I checked it properly rather than reading it: imported both module versions and compared all 23 exports. Names match exactly, the 5 value exports are identical (eof, fullRange, none, unicodeMax, unicodeRange), and the 18 function exports return identical results on sampled inputs. The other 13 modules are token-identical as before. Safe.

Two one-line things.

1. Two markdown links still point at fjs/bnf/module.f.ts

fjs/bnf/README.md:5    - the functional representation [./module.f.ts](./module.f.ts),
fjs/bnf/todo/46.md:9   [../module.f.ts](../module.f.ts), serializable form in

fjs/bnf/module.f.ts no longer exists. These survived both a035585 and e11269a for a mechanical reason worth naming, because it is the third variant of this bug: the target is relative and has no fjs/ prefix, so a grep 'fjs/bnf/module\.f\.ts' never sees it, and both label and target say .f.ts, so the […mjs](….ts) mismatch scan does not see it either. The two sweeps were each looking for a shape this instance doesn't have.

A check that would end this class outright is resolving every relative markdown link against the filesystem rather than pattern-matching the text. Against main as baseline that comes out at 144 broken links before and 146 after, and the two added are exactly the ones above — no other regressions anywhere in the repo, and the pre-existing 144 stay out of scope.

2. eof lost the TerminalRange annotation its neighbours just regained

e11269a adds @type {TerminalRange} to fullRange and unicodeRange, but eof is annotated on main and isn't here:

// main
export declare const eof: TerminalRange;
// this branch
export declare const eof: number;

TerminalRange is number, so nothing is weakened — assignability is unchanged in both directions and no caller can tell. It is purely that the declaration no longer says what the number means, and all three constants were consistent on main. One /** @type {TerminalRange} */ above export const eof restores it.

Not a finding, just so it's on record

The per-arrow @template/@param style emits the JSDoc block inside the parameter list of the shipped declaration:

export declare const option: <S extends Rule>(
/**
 * @template {Rule} S
 * @param {S} some
 * @returns {Option<S>}
 */
some: S) => Option<S>;

I checked before raising it and this is pre-existing — main already ships 14 of these from earlier migrations (types/array, types/sorted_list, types/sorted_set, range_map, bit_vec, list, sul/level/hash). This branch adds 7 more (bnf's three, sul::encode, and rtti/common's three), consistent with how the repo already does it. The types are correct; only the rendered declaration is noisy. Not this PR's job to fix, and I would not change the style here — worth a separate look someday if the emit ever matters.

CI green on the earlier commits, still finishing on e11269a; verified locally at e11269a. Happy to approve once the two above are in.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e11269a87c