Migrate 10 modules to .f.mjs under the stage-1 TypeScript-to-mjs migration - #1484

Reviewed at head 04f2633 against origin/main (30e7c64). The change itself looks correct — I have no objection to the code. Three notes, one of which is about the test plan rather than the diff.

What I verified

• npx tsc — clean, 0 errors.
• node ./fjs/module.ts t — 2356 pass / 0 fail, matching main.
• Public type surface: built main and this branch separately, ran prepack in both, diffed every emitted export type keyed by name. 0 removed, 0 changed. Four added, all _-prefixed assertion typedefs from object/proof.f.mjs — JSDoc @typedef has no non-exported form, so this is inherent to the migration, and _NodeList in patricia_trie/proof.f.d.mts is already the same shape on main. Not a new problem.
• No any leakage in the emitted declarations for either migrated module — every export in object/module.f.d.mts and hmac/module.f.d.mts carries its full named type. Worth stating explicitly given #1478.
• hmac's runtime logic is unchanged; the JSDoc conversion is faithful.
• CHANGELOG has entries for both migrations.

1. The test plan's tsc claim is not accurate

npx tsc --noEmit — error count unchanged at the pre-existing baseline (105 errors, confirmed identical via git stash/git stash pop against origin/main)

There is no 105-error baseline. origin/main at 30e7c64 type-checks with 0 errors, and so does this branch — I ran both.

This is worth correcting even though the outcome is fine, because the two claims set very different bars. "Error count unchanged at 105" passes whether or not the change introduces type errors, as long as some other 105 disappear; "clean, and still clean" is the bar this repo actually holds, and the one CI enforces. Had this PR introduced errors, the stated method would not have caught them.

I tried to reproduce 105 to identify the cause and could not: not from the git stash hypothesis (untracked new files surviving a stash of tracked edits — still 0), and not from a missing @types/node (that yields 1). So I can't tell you where the number came from, only that it does not describe this repo. Suggest re-running and replacing the claim with the real result.

2. The title and summary don't mention the hmac migration

The third commit migrates fjs/crypto/hmac to .f.mjs. The title says fjs/types/object, and the summary's four bullets are all about fjs/types/object. A reviewer reading either would not know a crypto module is in scope.

Credit where due — it is in the CHANGELOG, and correctly marked breaking, so it is not undisclosed to consumers. This is only about the PR's own description. Same note I made on #1483; worth getting into the habit since the summary is what describes this in history.

3. hmac loses @param/@returns prose that the convention would keep

The conversion replaced the documented signature with a bare @type:

- * @param hashFunc - The hash function implementation to use.
- * @returns - A function that takes a key and returns another function
- * that takes a message and computes the HMAC.
+ * @type {(hashFunc: Sha2) => Reduce}

That prose was in the emitted declaration on main and is gone from it now. It didn't have to be — typed JSDoc keeps both, which is how the other migrated modules do it (99 @param uses across module.f.mjs files; types/result/module.f.mjs is a clean example):

/**
 * @template T
 * @param {T} value - The value to wrap.
 * @returns {Ok<T>} A successful result containing the value.
 */

@type is fine where there was never any prose. Here there was, and it was dropped rather than translated.

Not blocking on any of this from a correctness standpoint — the migration is sound and I'd be happy to approve once the test plan reflects a real run. CI is green.

Approving. Re-verified at head 493f06c against origin/main (30e7c64).

All three of my earlier notes are addressed, and two of them beyond what I asked:

• The tsc claim now reads "clean, 0 errors, matching main" — which matches what I measure.
• The title and summary name the migrated modules instead of just fjs/types/object.
• hmac's @param/@returns prose is restored in the typed form the other migrated modules use (@param {Sha2} hashFunc - … / @returns {Reduce} …), so it is back in the emitted declaration rather than merely back in the source.

Verification at 493f06c

Nine modules now migrate here — types/object, crypto/hmac, path, sul/level/literal, sul/id, types/sorted_set, types/byte_set, types/string_set, media/json/serializer.

• npx tsc — clean, 0 errors.
• 2356 pass / 0 fail, matching main exactly.
• Public type surface: prepack in both trees, every emitted export type diffed by name — 0 removed, 0 changed.
• No any anywhere in the emitted declarations. Zero hits repo-wide once prose matches are excluded (the two raw hits are the words "before any symbol is seen" and "any JSON that satisfies"). Checking this properly matters given #1478, so: every export in all nine modules carries its full named type.
• CHANGELOG has a **BREAKING CHANGES:** entry for all nine, including sul/id from the last commit.

Two non-blocking follow-ups

1. Byte becomes public without the _ marker. On main, fjs/types/byte_set/module.f.ts declared type Byte = number deliberately non-exported — it appears in the emitted .d.ts as a bare type Byte, used by has, one, range, unset. It is now /** @typedef {number} Byte */ in module.f.mjs, and JSDoc typedefs are always exported, so the emitted declaration gained export type Byte = number;.

It is the only such case — the other four additions are the _-prefixed proof assertions in object/proof.f.mjs, which are inherent to the same JSDoc limitation and already have a precedent on main in patricia_trie/proof.f.d.mts.

The repo already has the answer for a private type that public signatures need: keep it exported but _-prefixed, as sorted_list/types.ts does with _MergeReduce. Renaming to _Byte would keep the intent that the main spelling had. Cosmetic, and I would not hold the PR for it.

2. The summary is behind the branch again. It describes types/object, crypto/hmac, and path; six more modules landed after it was written. The CHANGELOG — the part consumers actually read — is complete and correct for all nine, so this is only the PR's own description, and I mention it just because it is the third time on this branch. Worth a refresh before merge since the summary is what describes this in history.

CI was green at fdfe178 and is still running on 493f06c; I verified locally at 493f06c directly.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c8be1d2429

💡 Codex Review

Update issue documents after the module renames

Beyond the corrected AGENTS/SUL examples, a repo-wide rg still finds active todo/ documents pointing at paths deleted by this migration: for example, fjs/media/json/todo/number-edge-cases.md:202 and remove-native-json.md:141 link to ../serializer/module.f.ts, while several object, path, SUL, byte-set, and string-set issues cite their removed .f.ts modules. Because todo/ is this repository's issue tracker, these links and snippets now resolve to nonexistent modules and will misdirect follow-up work; sweep all ten renamed groups to their .f.mjs/types.ts paths.

AGENTS.md reference: AGENTS.md:L10-L11

Re-reviewed at 67fc299. _Byte is done, and the two Codex rounds landed well. Everything substantive still verifies clean; two small things below, both introduced by the newest commits.

Verified at 67fc299

• npx tsc clean; 2356 pass / 0 fail, matching main.
• Public type surface: 0 removed, 0 changed.
• No any as a type anywhere in the emitted declarations — zero hits repo-wide.
• CHANGELOG condensation is right. §8.3 asks for ~3 wrapped lines and says migration walkthroughs belong in the PR description, so dropping the per-module type enumerations is what the convention wants, not a loss. The wording "the module.f.ts of fjs/types/sorted_set and fjs/types/byte_set" is a nice touch — it stays accurate after the proof reverts.

The two proof reverts are correct, and worth saying explicitly since it is a subtle rule. §2 permits module.f.mjs + proof.f.ts outright, and only allows proof.f.mjs once every authored runtime dependency outside the migration group is already .f.mjs. Both proofs import from fjs/media/json/module.f.ts, which is still TypeScript, so they could not legitimately be .f.mjs yet. I also checked the reverted files against main: the (v: any) in byte_set/proof.f.ts and the explicit stringify/str annotations are all pre-existing there, so the revert restores them rather than introducing anything. By contrast sul/level/hash/proof.f.mjs imports only .f.mjs runtime modules, so its migration is fine.

1. NodeList needs the _ prefix — same case as Byte

fjs/sul/level/hash/proof.f.mjs:7 declares /** @typedef {readonly (readonly [Id, Id, Id, boolean])[]} NodeList */. On main this was type NodeList = … in proof.f.ts, deliberately non-exported. As a JSDoc typedef it now emits into the shipped proof.f.d.mts as export type NodeList, so it is the one unmarked new public type in the whole PR.

The precedent is the closest possible: fjs/types/patricia_trie/proof.f.mjs names the identical concept _NodeList, and that is already how it ships on main. This is just the Byte → _Byte fix applied to the module that arrived after it.

Minor extra reason to prefix it: NodeList is a DOM global, so it is a more collision-prone name than most to export from the package.

2. Five doc references to files this PR renamed are still stale

1b80d7e and 67fc299 both sweep stale todo/ links, but five renamed paths were missed. I diffed broken references against main to be sure these are yours and not pre-existing — main has 49 broken refs, this head has 54, and the five added are:

65y-proof-asserteq-adoption.md:140 shows the sweep was partial rather than skipped — the line already reads fjs/sul/id/module.f.mjs:19, with fjs/sul/id/proof.f.ts:1 left un-updated right beside it.

(For the avoidance of scope creep: the other 49 are pre-existing on main and not this PR's problem.)

Neither is a correctness issue and CI is green. Happy to approve once these are in — the rest of the change verifies clean.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 67fc299f57