Migrate fjs/effects/node/virtual to .f.mjs - #1494

Reviewed at 2d37a40. tsc clean, 2357 pass / 0 fail, no any in any emitted declaration, and the mkdir restructure is the familiar annotate-via-named-const idiom (mkdirOp extracted so @type can name it) — operation receives the same function, so it is inert.

Nice to see this one land: effects/node/virtual is what has been blocking dev/update, website, ci, and ci/nix proofs from moving, and its own proof.f.ts migrates alongside here.

Entity was public on main, and the CHANGELOG says it wasn't

This is the first genuinely removed public type I have seen in this migration series. On main, fjs/effects/node/virtual/module.f.ts exports four types:

export type JsModule = () => Module
export type Entity = readonly Vec[] | Dir | JsModule
export type Dir = { … }
export type State = { … }

JsModule, Dir, and State stay public in types.ts. Entity becomes _Entity, so it leaves the published surface entirely.

The CHANGELOG entry describes it as "the internal _Entity type". That is accurate about the destination but not about the origin — it was exported, not internal, and a reader of the changelog would conclude nothing was narrowed.

To be clear about the size of this: no in-repo code imports Entity, I checked, so nothing breaks here, and making it private is defensible on the merits — it is the union extractEntity/insertEntityAt pass around, which does read as an implementation detail rather than API. My concern is only that a deliberate narrowing of the public surface is going out described as a no-op. An external consumer with import type { Entity } gets no signal from that line.

Either resolution works:

• keep it exported as Entity in types.ts if the intent was purely mechanical, or
• keep _Entity and say so — the entry is already marked **BREAKING CHANGES:**, so it only needs the wording to stop calling it internal, e.g. "…and narrowing the previously-exported Entity to the internal _Entity".

I would not hold the PR for the code either way; it is the changelog line that should not claim a type was always internal when it was not.

Everything else checks out: Dir changes only because its member references _Entity, JsModule and State are untouched, and no exported const signature moved.

Reviewed at 7c30b78. The Entity wording is fixed exactly right — "narrowing the previously-exported Entity to the internal _Entity" says what actually happens. Four more modules join: fjs/dev, fjs/cas, fjs/cas/cli, fjs/emergent_testing.

npx tsc clean, 2357 pass / 0 fail matching main, no any in any emitted declaration.

One thing: TestOp needs the _ prefix

fjs/cas/proof.f.mjs declares a proof-local TestOp, and because JSDoc @typedef has no non-exported form it lands on the published surface:

// fjs/cas/proof.f.d.mts
export type TestOp = FileCasOperation | WriteFile | ReadFile | Rm | Mkdir;

Nothing like it exists on main. It is the same case as _NodeList on #1485 and _Tests on #1488 — a type that is proof scaffolding rather than API, made public by the format rather than by intent. The convention answer is the prefix, and this PR already applies it correctly everywhere else: _TestAndPath (private on main, prefixed here) and _Entity both landed right.

It is the only unprefixed addition in the diff.

What I verified on the other four

• fjs/dev and fjs/cas/cli are token-identical to main's compiled output.
• fjs/cas differs by one extraction — the write branch of fileCas becomes a named writeImpl(sha2, path, stageDir, payload) so JSDoc can annotate it, with the previously-closed-over values passed explicitly. Same idiom as dispatchProps/foldStep/mkdirOp, semantically inert.
• fjs/emergent_testing differs only by dropping shouldLoad from an import. I checked it was genuinely unused — main references it once (the import itself) and zero times in the body — and the test count is unchanged at 2357, so proof discovery is unaffected. The shouldLoad that governs discovery lives in fjs/dev/module.f.ts and is untouched.
• The two changed signatures are inert: collectTests picks up the _TestAndPath rename, and defaultTest's { fn, throws }: TestEntry becomes a named entry parameter.
• effects/node/virtual still differs only by the mkdirOp extraction from the previous head.

Happy to approve once TestOp is _TestOp.

Reviewed at f4b0f8d. _TestOp is fixed. Four more modules join: fjs/js/tokenizer, fjs/media/json/tokenizer, fjs/media/json, fjs/media/json/parser.

npx tsc clean, 2357 pass / 0 fail matching main, no any in any emitted declaration, and three of the four new modules are token-identical to main's compiled output. fjs/js/tokenizer differs by an extraction of the same shape as the others (parseSinglelineCommentStateOp named so JSDoc can annotate it).

Nine types that were private on main are now public

The same case as _TestOp, but at scale. Each of these was a non-exported type in its module.f.ts on main, and each is now a JSDoc @typedef in module.f.mjs, so each lands on the published surface unprefixed:

I confirmed all nine were type X rather than export type X on main, so this is a widening rather than a preserved contract.

They are JSDoc typedefs rather than types.ts entries, so the types.ts option that worked for Handler on #1491 — a plain non-exported type — is not available here. The prefix is the applicable convention, same as _Byte, _NodeList, _Tests, _Signature, and _TestOp.

Nothing breaks either way: no in-repo consumer imports them, and tsc is clean. It is the published type surface picking up nine implementation details, which is the thing the prefix exists to prevent.

Also still open from earlier heads

Entity remains the one genuinely removed public type in this PR. That is deliberate and the CHANGELOG now describes it accurately, so no action — just noting it is still the only removal, and the nine above are the only unprefixed additions.

Happy to approve once those nine carry the prefix.

Reviewed at 0a9f1f050beebd2e7a784c08476205ae12627f8b. The nine unprefixed types are gone,
and the way they went is the cleanest possible: 0a9f1f05 reverts f4b0f8df exactly.
I checked that by tree hash rather than by reading the diff —
tree(0a9f1f05) == tree(fdc4af4a) == e2dfc76d, so the head is byte-identical to the
state before the migration commit I flagged. Nothing else was touched on the way out,
and the CHANGELOG entry for the reverted migration is gone with it (7 entries now, one
per migration commit). Approving.

The rest of the battery, re-run against this head:

Build and tests. tsc --noEmit exits 0. npm test gives 2357 pass / 0 fail, against
main's 2357 pass / 0 fail — no proof lost or gained, as a behaviour-preserving migration
should be. Branch is 10 commits ahead of 2b058dc with nothing on main it doesn't have.

Public surface, both axes. 36 type-alias differences against main, and every one is
either a _ privatization or a mechanical reference to one — Entity → _Entity,
JsToken's union members, and the ~30 tokenizer state types that had no exported form on
main because they were plain non-exported types in .f.ts. Zero unprefixed
additions, which is the thing I was asking for. Const signatures show 2 differences:
collectTests returning readonly _TestAndPath[], which is the same rename, and
defaultTest taking entry: TestEntry where main destructured { fn, throws } —
parameter names in a .d.ts are documentation, so that one is cosmetic.

Token equivalence, all 11 migrated files. fjs/cas/cli/module, fjs/dev/module,
fjs/dev/proof and fjs/media/json/tokenizer/module normalize identically to main's
compiled output. Three differ only in hex-literal letter case — 0x2an→0x2An,
0xaan→0xAAn, 0xbbn→0xBBn — same values. fjs/emergent_testing/module differs by
the dropped shouldLoad import from 66fea797; that one is safe because shouldLoad is
still exported from fjs/dev/module.f.mjs and still proved in
emergent_testing/proof.f.ts — the module genuinely wasn't using it, and tsc would
have failed if it were. The remaining three are the extraction idiom JSDoc forces —
writeImpl in cas, mkdirOp in virtual, parseSinglelineCommentStateOp in
js/tokenizer.

One thing worth recording since it looked alarming for a minute: a naive scan says
js/tokenizer loses a top-level startNegativeNumber. It doesn't — that binding is
inside a /* … */ block on main, and the grep was matching comment text. The migration
drops the commented-out block, which is the right call.

Docs. The AGENTS.md and todo/plan/roadmap.md edits are the two path references
the migrations invalidated, and both new targets exist. Resolving every relative markdown
link against the filesystem gives byte-identical broken-link sets on both sides — 144
pre-existing on main, none added, none fixed.

CHANGELOG. Seven entries, one per migration commit, correctly marked breaking. They
run ~420–560 characters, which is longer than §8.3's "about three wrapped lines" read
literally, but main's own merged migration entries sit at 283–476, so this is the
established shape for this class of entry rather than a drift I should be flagging on
this PR.