Split JSON rtti schemas into .f.mjs and JSON types into types.ts - #1498

Reviewed at d30ee39aa612436caabb7d79ae9b88e4c381a412. This is clearly mid-experiment, so
not a review — just the datapoint that seems most useful given where #1497 ended up:
this approach fixes the prepack failure.

main                exit 0, 0 errors
#1497 f10c9f7f      exit 2, 5 errors
#1497 e4e8209       exit 2, 4 errors
this branch         exit 0, 0 errors

And the reason is visible in the emitted declaration, which is what makes it look like the
right fix rather than a coincidence. Naming the thunk type and annotating with it:

/** @typedef {() => ['or', typeof primitive, typeof object, typeof array]} Unknown */
/** @type {Unknown} */
export const unknown = () => ['or', primitive, object, array]

makes declaration emit write a reference instead of trying to expand a self-referential
structure:

export type Unknown = () => ['or', typeof primitive, typeof object, typeof array];
export declare const unknown: Unknown;
export declare const object: Type1<"record", Unknown>;
export declare const array: Type1<"array", Unknown>;

grep -c elided on that file is 0, where both #1497 heads emitted
Type1<"record", /*elided*/ any>. That elision was the root of all five errors, so removing
it at the source removes the whole class — a consumer importing through the declaration now
gets the same type the authored source has. npx tsc --noEmit exits 0 and npm test gives
2357/0, matching main.

Two things I noticed that I assume are just "not there yet", flagged only so they don't get
lost: types.ts is down to Primitive alone, so Unknown, Object, Array, Entry and
MapEntries have no home yet, and its Assert/Equal imports are now unused. Also
fjs/media/json/module.f.ts is still .f.ts on this branch, so the migration itself hasn't
happened — which is presumably the point of testing the rtti split on its own first.

One small thing worth deciding deliberately when you do fill it back in: the typedef is
() => ['or', ...] where main had as const, i.e. readonly ['or', ...]. It type-checks
because a mutable tuple is assignable where a readonly one is expected, but it does widen
the schema type slightly compared to main.

Reviewed at 334cd919457bb3570d916597e4f644fb8c93e033. Short follow-up, since the piece that
was still open last time is now settled.

The pin is back in types.ts — Assert<Equal<Unknown, Ts<typeof unknown>>>, importing
unknown across the file boundary from ./module.f.mjs — and npm run prepack is still
clean from a fresh tree: exit 0, 0 errors. That's the combination #1497 never reached. There
the pin either failed cross-file or had to be moved out of the way to stop failing, and the
four consumer errors survived either way. Here the tripwire is in place, cross-file, and
passes, and grep -c elided on the emitted fjs/media/json/module.f.d.mts is 0.

npx tsc --noEmit exits 0 and npm test gives 2357/0, matching main. Branch is level with
origin/main.

Also worth noting since I raised it on #1497: Entry and MapEntries landed in
fjs/media/json/common/module.f.ts, with MapEntries left non-exported. That is cleaner
than what #1497 had to do — it stays genuinely private rather than becoming a public name
just so a JSDoc @import could reach it.

Still a draft, so nothing to approve. No concerns from me at this head.

Reviewed at a681da6d530636db4f5f7773e444c742931818ea. Now that this has a real title and a
CHANGELOG entry, here is a full pass. One convention gap worth fixing, one softer note, and
otherwise it looks good — including one thing it improves over main.

Fix before merge: no @module header

fjs/media/json/rtti/module.f.mjs has no @module header — the file opens with a blank
line and then the import. §4 says every module should start with one, and the comparable
migrated modules all do (fjs/media/json/tokenizer, fjs/cas, fjs/dev,
fjs/effects/node/virtual).

Worth placing it carefully rather than mechanically: earlier in this series a header written
immediately above an import got folded into that import's leading trivia and vanished from
the emitted declaration along with the import. Here the import is a value import so it would
not be elided, but leaving a blank line between the header and the first import is the safe
habit.

Softer: no co-located proof for the new module

§3.2 says a new implementation module ships with a co-located proof, and
fjs/media/json/rtti/ contains only module.f.mjs. In practice the four exports are
exercised transitively — unknown is imported at runtime by fjs/protocol/json_rpc,
fjs/protocol/mcp, and fjs/media/json/schema — and this is moved code rather than newly
written code, so I would not call it a coverage regression. I also can't measure it: npm run cov runs 0 tests and prints a vacuous 100.00 in my environment (Node v23.11.0), and it
does the same on main, so that's my setup rather than anything about this branch. Flagging
it as a structural point for you to judge, not as a demonstrated gap.

What checks out

The core question from #1497 is settled here. From a clean tree, npm run prepack exits 0
with 0 errors, with the pin living in types.ts and importing unknown across the file
boundary — the exact arrangement that failed on both #1497 heads. npx tsc --noEmit exits 0
and npm test gives 2357/0, matching main. Branch is level with origin/main.

The readonly is back (() => readonly['or', ...]), so the schema type no longer widens
against main.

Public surface: 0 type-alias differences against main — Primitive, Unknown, Object
and Array keep identical shapes across the move to types.ts. The 8 const differences are
the four schemas relocating from fjs/media/json to fjs/media/json/rtti under the same
names.

And an improvement worth calling out: main's emitted fjs/media/json/module.f.d.ts contains
a /*elided*/ any, because declaration emit could not express the self-referential thunk.
The annotation on this branch removes it — grep -c elided on the emitted
rtti/module.f.d.mts is 0. So consumers reading the declaration now get the same type the
authored source has, which was not true before this PR.

CHANGELOG: one entry, correctly scoped, links only the PR, in the usual length band for this
series. It adds without deleting — the fjs/fsc/json.f.ts / bnf.f.ts entry that #1497
dropped is untouched here.

Broken relative markdown links: 144 on both sides, none added.

Still a draft, so I'm not approving. Happy to once it's marked ready, assuming the @module
header goes in.

Reviewed at cd5a10f583033b70f0327e8472fa0876e857a4bc. Docs-only since a681da6 — no code
files changed — so this is about the new rule rather than the migration.

Turning this into a written convention is the right call, and I went and reproduced the
measurements rather than taking them on faith, since they're now permanent claims in
AGENTS.md. All three rows of the table hold exactly, on
fjs/media/json/rtti/module.f.mjs:

Including the character counts. One thing worth knowing if anyone re-runs this: a naive
grep -c any on the typeof declaration returns 2, but both are the English word "any" in
the JSDoc prose ("matching any JSON primitive"), not the type — I briefly thought the claim
was overstated before checking. The unannotated form also trips TS2344 on the round-trip
assert alongside the four TS2345s, which if anything reinforces the last paragraph's point
about keeping the assert beside the schema.

The framing that this belongs in a rule rather than in review is the part I'd most agree
with. A failure visible only to a consumer of the published .d.mts, with npx tsc and
fjs t both green, is exactly what a reviewer misses — this one only surfaced because
npm pack runs prepack's second pass against the emitted declarations.

Still outstanding from my last pass: fjs/media/json/rtti/module.f.mjs still has no
@module header (§4). Small, and the only thing I'd want before approving.

Reviewed at 75bdaa25541b69ce535f6d33535217ba27e14978. Both items from my earlier passes are
resolved, and nothing new turned up. No blocking concerns left.

@module header. Present, and placed with a blank line before the first import — which
matters, because that's the arrangement that survives declaration emit. grep -c '@module'
on the emitted rtti/module.f.d.mts is 1, so it didn't get folded into the import's
leading trivia the way it did earlier in this migration series.

Co-located proof. fjs/media/json/rtti/proof.f.mjs covers all four exports. Tests go
2357 → 2368, and all 11 new cases are discovered and run. Its three runtime imports are
.f.mjs (asserts, types/rtti/validate, and the sibling module), so proof.f.mjs rather
than proof.f.ts is the right extension under §2.

I checked the proof isn't vacuous rather than assuming it. Flipping one expectation —
assertEq(unknownAccepts(undefined), 'error') → 'ok' — produces exactly one failure,
correctly attributed:

proof.unknown.rejectsUndefined(): error
Number of tests: pass: 2367, fail: 1, total: 2368

Something I hadn't expected and think is worth recording: the schemas now have three
independent guards, and they catch different things. I tried mutating unknown to admit
rtti core's unknown (the exact undefined-shaped drift this whole series has been about)
and it never reached the proof — the explicit @type rejected it at typecheck on arity,
Source has 5 element(s) but target allows only 4. So the annotation isn't just a
declaration-emit fix, it's load-bearing for correctness; the Assert<Equal<…>> pin catches
type-versus-schema divergence; and the proof catches expectation drift at runtime. That's a
good place for this module to end up.

Everything else. From a clean tree npm run prepack exits 0 with 0 errors, npx tsc --noEmit exits 0, the emitted declaration has 0 elided and 0 type-level any, the public
type surface is unchanged against main (0 alias differences), the new proof declaration adds
only proof itself, broken markdown links are 144 on both sides, and the branch is level
with origin/main. The See AGENTS.md §6.2 pointer in the new header resolves — the rule
really is in that section.

Still marked draft, so I'll leave the approval for when you flip it to ready; from my side
there's nothing outstanding.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 75bdaa2554

Reviewed at 6dbe384f68798eab4d7299d79a89797fda1a7b0a. Approving — everything I raised across
the earlier passes is resolved, and the final commit's header placement holds up under the
one check that mattered for it.

types.ts is the interesting case for a @module header, because every import in that file
is import type. That's the exact shape that bit this migration series before: a header
written flush against a type-only import gets absorbed into the import's leading trivia and
disappears from the emitted declaration along with it. The blank line here prevents that, and
it's confirmed rather than assumed — @module survives emit in all three:

fjs/media/json/types.d.ts             1
fjs/media/json/rtti/module.f.d.mts    1
fjs/media/json/rtti/proof.f.d.mts     1

Full state at this head, from a clean tree:

• npm run prepack exits 0 with 0 errors — the original blocker, and the reason #1497 was
  closed. npx tsc --noEmit exits 0.
• npm test: 2368 pass / 0 fail, up from main's 2357 by exactly the 11 new proof cases.
• Emitted rtti/module.f.d.mts has 0 /*elided*/ and 0 type-level any, where main's
  fjs/media/json/module.f.d.ts still carries an elision. This PR leaves the published
  declaration strictly more faithful than it found it.
• Public type surface: 0 alias differences. 9 const differences, all accounted for — the four
  schemas moving from fjs/media/json to fjs/media/json/rtti under the same names, plus the
  new proof export.
• Broken relative markdown links: 144, identical to main. Level with origin/main.
• CHANGELOG: one entry, correctly scoped, links only the PR, and adds without deleting.

The part I'd single out is that the typeof cross-reference turned out to be load-bearing
for more than declaration emit. When I tried to mutate unknown into admitting rtti core's
unknown — the undefined-shaped drift this whole series has circled — it never reached the
proof, because the annotation rejected it at typecheck on arity. Three independent guards now
sit on this module and each catches something the others don't: the annotation on schema
drift, the Assert<Equal<…>> pin on type-versus-schema divergence, and the proof on
expectation drift, which I verified is live by flipping one expectation and getting exactly
one correctly-named failure.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6dbe384f68