functionalscript 0.40.0 → 0.42.0

package/fjs/djs/parser/proof.f.js

@@ -526,5 +526,31 @@ export const proof = {
             const result = stringifyDjsModule(obj[1]);
             assertEq(result, '[[],[null]]');
         },
+    ],
+    // Regression: closing a container popped the parser stack with `drop(1)`,
+    // which is lazy, so every closed container left one unforced thunk wrapping
+    // the stack. The chain was forced only at the end, costing a call-stack
+    // frame per container and overflowing at roughly 5000 of them — whether
+    // nested or flat siblings — while primitives were unbounded. `fjs/media/json`
+    // carried the same defect and was fixed in the same way.
+    containerStackCost: [
+        () => {
+            const [tag, value] = parseFromTokens(tokenizeString(`export default [${Array(20000).fill('{}').join(',')}]`));
+            assert(tag === 'ok', tag);
+            assertEq(value[1].length, 1);
+        },
+        () => {
+            const [tag] = parseFromTokens(tokenizeString(`export default [${Array(20000).fill('[]').join(',')}]`));
+            assert(tag === 'ok', tag);
+        },
+        () => {
+            const [tag] = parseFromTokens(tokenizeString('export default ' + '['.repeat(20000) + ']'.repeat(20000)));
+            assert(tag === 'ok', tag);
+        },
+        () => {
+            // primitives never touched the stack — the baseline that always passed
+            const [tag] = parseFromTokens(tokenizeString(`export default [${Array.from({ length: 20000 }, (_, i) => i).join(',')}]`));
+            assert(tag === 'ok', tag);
+        },
     ]
 };

package/fjs/djs/tokenizer/proof.f.js

@@ -1167,12 +1167,19 @@ export const proof = {
         () => {
             // many distinct short tokens, well past the ~1000-1500 token crash threshold
             // the old whole-file recursive match hit for this shape
-            const src = Array.from({ length: 3000 }, (_, i) => `a${i % 10}`).join(' ');
+            const ids = Array.from({ length: 3000 }, (_, i) => `a${i % 10}`);
+            const src = ids.join(' ');
             const result = tokenizeString(src);
             assert(result !== 'error', result);
-            const parsed = JSON.parse(result);
-            // 3000 ids + 2999 separating ws + a trailing eof token
-            assertEq(parsed.length, 3000 + 2999 + 1);
+            // `tokenizeString` runs its own pipeline (`getTokensFromAstRule` +
+            // filter/scan + `stringify`), not `tokenizeJs`'s, so only its dump
+            // covers it. Compared whole rather than counted: at this size the
+            // count was the only thing the old JSON round-trip could check,
+            // while the reconstructed literal also pins every token's content.
+            assertEq(result, `[${ids.map(v => `{"kind":"id","value":"${v}"}`).join(',{"kind":"ws"},')},{"kind":"eof"}]`);
+            // The token list must agree with the dump: 3000 ids + 2999
+            // separating ws + a trailing eof token.
+            assertEq(toArray(tokenizeJs(stringToList(src))('a.js')).length, 3000 + 2999 + 1);
         },
         () => {
             // same many-short-tokens shape through the metadata-aware entry point

package/fjs/effects/module.f.d.ts

@@ -379,6 +379,26 @@ export type MatchResult<O extends Operation, T, R> = readonly ['done', T] | read
  * with the continuation. The one world-specific step — `await` for async
  * runners, state threading for sync ones — is left to the caller, so every
  * interpreter loop is this skeleton plus a single eliminator line.
+ *
+ * **The handler is looked up with `at`, never with `map[command]`.**
+ * `OperationMap<O, R>` pins `command` to `O[0]` at the type level, but a `Do`
+ * node's `command` is runtime data — it can reach an interpreter from a decoded
+ * payload or a deserialized continuation, where no type ever constrained it.
+ * `map` is an ordinary object, so a plain index read resolves an inherited name
+ * (`'constructor'`, `'toString'`, `'hasOwnProperty'`) to the `Object.prototype`
+ * member instead of `undefined`, and the line below would then call it with the
+ * node's payload: a value the type system promised was `(...payload) => R` turns
+ * out to be an arbitrary inherited function, chosen by the same input that
+ * supplies its arguments. `at` reads through `getOwnPropertyDescriptor`, which
+ * only ever sees own properties, so such a command yields `null` and never a
+ * callable.
+ *
+ * A `null` handler is an invariant violation, not an outcome: every `O1 extends
+ * O` the signature admits has its command in `map`, so reaching it means the
+ * node's `command` was never the `O1[0]` it claimed to be. It therefore throws
+ * (`assert`) rather than widening {@link MatchResult} with a variant no
+ * type-correct caller could ever observe — a runner cannot resume a command it
+ * has no handler for, so there is nothing for a recovery branch to do.
  */
 export declare const match: <O extends Operation, R>(map: OperationMap<O, R>) => <O1 extends O, T>(e: Effect<O1, T>) => MatchResult<O1, T, R>;
 export type ToAsyncOperationMap<O extends Operation> = {

package/fjs/effects/module.f.js

@@ -94,7 +94,9 @@
  *
  * @module
  */
+import { assert } from '../asserts/module.f.js';
 import { fold } from '../types/list/module.f.js';
+import { at } from '../types/object/module.f.js';
 export const pure = (v) => () => v;
 /**
  * Composes effects: run `e`, then continue with `f` applied to its result.
@@ -278,11 +280,33 @@ export const runPure = (e) => typeof e === 'function' ? [e()] : [];
  * with the continuation. The one world-specific step — `await` for async
  * runners, state threading for sync ones — is left to the caller, so every
  * interpreter loop is this skeleton plus a single eliminator line.
+ *
+ * **The handler is looked up with `at`, never with `map[command]`.**
+ * `OperationMap<O, R>` pins `command` to `O[0]` at the type level, but a `Do`
+ * node's `command` is runtime data — it can reach an interpreter from a decoded
+ * payload or a deserialized continuation, where no type ever constrained it.
+ * `map` is an ordinary object, so a plain index read resolves an inherited name
+ * (`'constructor'`, `'toString'`, `'hasOwnProperty'`) to the `Object.prototype`
+ * member instead of `undefined`, and the line below would then call it with the
+ * node's payload: a value the type system promised was `(...payload) => R` turns
+ * out to be an arbitrary inherited function, chosen by the same input that
+ * supplies its arguments. `at` reads through `getOwnPropertyDescriptor`, which
+ * only ever sees own properties, so such a command yields `null` and never a
+ * callable.
+ *
+ * A `null` handler is an invariant violation, not an outcome: every `O1 extends
+ * O` the signature admits has its command in `map`, so reaching it means the
+ * node's `command` was never the `O1[0]` it claimed to be. It therefore throws
+ * (`assert`) rather than widening {@link MatchResult} with a variant no
+ * type-correct caller could ever observe — a runner cannot resume a command it
+ * has no handler for, so there is nothing for a recovery branch to do.
  */
 export const match = (map) => (e) => {
     if (typeof e === 'function') {
         return ['done', e()];
     }
     const { command, payload, continuation } = e;
-    return ['cont', map[command](...payload), continuation];
+    const handler = at(command)(map);
+    assert(handler !== null, command);
+    return ['cont', handler(...payload), continuation];
 };

package/fjs/effects/proof.f.d.ts

@@ -31,6 +31,11 @@ export declare const proof: {
     match: {
         done: () => void;
         cont: () => void;
+        ownCommand: () => void;
+        throw: {
+            constructorCommand: () => void;
+            toStringCommand: () => void;
+        };
     };
     step: {
         pure: () => void;

package/fjs/effects/proof.f.js

@@ -15,6 +15,7 @@ export const assertPure = (e, expected) => {
     assertEq(o[0], expected);
 };
 const next = match({ add: (a, b) => a + b });
+const anyNext = match({ add: a => a + 1 });
 export const proof = {
     foldStep: {
         empty: () => {
@@ -103,6 +104,27 @@ export const proof = {
             assert(r2[0] === 'done', r2);
             assertEq(r2[1], 5);
         },
+        ownCommand: () => {
+            // The same map the two cases below dispatch against: an own
+            // property still resolves, so what they prove is refusal of
+            // inherited names, not a map that dispatches nothing.
+            const r = anyNext(do_('add')(41));
+            assert(r[0] === 'cont', r);
+            assertEq(r[1], 42);
+        },
+        // A `command` naming an `Object.prototype` member must not dispatch to
+        // the inherited value. `map['constructor']` is `Object` and
+        // `map['toString']` is `Function.prototype.toString` — both callable,
+        // neither a handler — so a plain index read would call one of them with
+        // the node's payload instead of throwing.
+        throw: {
+            constructorCommand: () => {
+                anyNext(do_('constructor')(1));
+            },
+            toStringCommand: () => {
+                anyNext(do_('toString')(1));
+            },
+        },
     },
     step: {
         pure: () => {

package/fjs/emergent_testing/proof.f.js

@@ -5,10 +5,27 @@ import { assert, assertEq } from '../asserts/module.f.js';
 import { testAll, defaultReporter, fmtPath, fmtTerm, fmtImport, ghEscape, isInteger, isIdentifier, registerModule, parseTestSet, defaultTest, } from './module.f.js';
 import { run as mockRun } from '../effects/mock/module.f.js';
 import { shouldLoad } from '../dev/module.f.js';
-const writeEvent = (event) => log(JSON.stringify(event));
-const parseEvents = (stdout) => stdout === '' ? [] : stdout.trimEnd().split('\n').map(line => JSON.parse(line));
+import { parse as parseJson } from '../media/json/module.f.js';
+import { array, number as rttiNumber, or, string as rttiString } from '../types/rtti/module.f.js';
+import { parse as rttiParse } from '../types/rtti/parse/module.f.js';
+import { unwrap } from '../types/result/module.f.js';
+/**
+ * The mock reporter's stdout lines. A schema rather than a hand-written type:
+ * the events round-trip through JSON, and this is what turns a line back into
+ * a typed value without an `as` cast — a shape change fails at the parse
+ * instead of silently at an assertion.
+ *
+ * `Reporter.result` also receives the test's `SandboxResult`, which is not
+ * written: no assertion here reads it, and its `undefined` payloads have no
+ * JSON representation to round-trip through anyway.
+ */
+const event = or(['result', rttiString, array(or(rttiString, null))], ['summary', rttiNumber, rttiNumber, rttiNumber]);
+const parseEvent = rttiParse(event);
+const writeEvent = (e) => log(JSON.stringify(e));
+const parseEvents = (stdout) => stdout === '' ? [] : stdout.trimEnd().split('\n')
+    .map(line => unwrap(parseEvent(unwrap(parseJson(line)))));
 const makeReporter = () => ({
-    result: (file, path, r, _throws) => writeEvent(['result', file, [...path], r]),
+    result: (file, path, _r, _throws) => writeEvent(['result', file, [...path]]),
     summary: (pass, fail, time) => writeEvent(['summary', pass, fail, time]),
     test: defaultTest,
 });

package/fjs/js/tokenizer/proof.f.js

@@ -357,6 +357,13 @@ export const proof = {
                 throw result;
             }
         },
+        () => {
+            // a second "." after the fraction has started (covers fullStopToToken's default branch)
+            const result = stringify(tokenizeString('1..'));
+            if (result !== '[{"kind":"error","message":"invalid number"},{"kind":"eof"}]') {
+                throw result;
+            }
+        },
         () => {
             const result = stringify(tokenizeString('0e1'));
             if (result !== '[{"bf":[0n,1],"kind":"number","value":"0e1"},{"kind":"eof"}]') {

package/fjs/mcp/cas/module.f.js

@@ -109,7 +109,8 @@ import { cBase32ToVec, vecToCBase32 } from '../../basen/cbase32/module.f.js';
 import { decode as base64Decode, encode as base64Encode } from '../../basen/base64/module.f.js';
 import { tryUtf8 } from '../../text/module.f.js';
 import { detectStream } from '../../media/type/module.f.js';
-import { detect as detectDialect } from '../../media/module.f.js';
+import { detect } from '../../media/module.f.js';
+import { revisionDialect } from '../../media/revision/module.f.js';
 import { maxLengthBytes } from '../../types/bit_vec/module.f.js';
 import { ok } from '../../types/result/module.f.js';
 import { toolEntry, errorResult, okResult, } from '../../protocol/mcp/module.f.js';
@@ -134,6 +135,8 @@ export const casGetArgs = {
 export const casListArgs = {};
 // ── Tool registry ──────────────────────────────────────────────────────────────
 const toJson = stringify(identity);
+/** The dialect-aware classifier, bound to the dialects this server recognizes. */
+const detectDialect = detect([revisionDialect]);
 /**
  * Registry of all CAS tools, bound to `home` and the Evo cache at
  * `cacheKey`. `cas_add` is the only tool that writes, so it is the only one

package/fjs/mcp/evo/module.f.d.ts

@@ -2,8 +2,13 @@ import { type Operation } from '../../effects/module.f.ts';
 import { type MemOp } from '../../effects/memory/module.f.ts';
 import { type ToolEntry } from '../../protocol/mcp/module.f.ts';
 import { type Evo } from '../../cas/evo/module.f.ts';
-/** Arguments for `evo_list`: none. */
-export declare const evoListArgs: {};
+/**
+ * Arguments for `evo_list`: an optional status filter, forwarded unchanged to
+ * `Evo.list` — omitted lists the active subjects, `true` the archived ones.
+ */
+export declare const evoListArgs: {
+    readonly archived: import("../../types/rtti/module.f.ts").Or<readonly [true, undefined]>;
+};
 /** Arguments for `evo_head`: the subject whose current heads are requested. */
 export declare const evoHeadArgs: {
     readonly subject: import("../../types/rtti/module.f.ts").String;

package/fjs/mcp/evo/module.f.js

@@ -8,7 +8,7 @@
  *
  * | Tool           | args                                          | action            | result                               |
  * |----------------|-----------------------------------------------|-------------------|--------------------------------------|
- * | `evo_list`     | `{}`                                          | `e.list()`        | subjects, as a JSON array of strings |
+ * | `evo_list`     | `{ archived? }`                               | `e.list(...)`     | subjects, as a JSON array of strings |
  * | `evo_head`     | `{ subject }`                                 | `e.head(...)`     | head hashes, one per line            |
  * | `evo_revision` | `{ hash }`                                    | `e.revision(...)` | the revision, as JSON `RevisionData` |
  * | `evo_add`      | `{ parents, snapshot?, subject?, archived? }`  | `e.add(...)`      | hash (cBase32)                       |
@@ -51,8 +51,13 @@ import { stringify } from '../../media/json/module.f.js';
 import { identity } from '../../types/function/module.f.js';
 import {} from '../../cas/evo/module.f.js';
 // ── Argument schemas (declared once, used for both inputSchema and validate) ─────
-/** Arguments for `evo_list`: none. */
-export const evoListArgs = {};
+/**
+ * Arguments for `evo_list`: an optional status filter, forwarded unchanged to
+ * `Evo.list` — omitted lists the active subjects, `true` the archived ones.
+ */
+export const evoListArgs = {
+    archived: option(true),
+};
 /** Arguments for `evo_head`: the subject whose current heads are requested. */
 export const evoHeadArgs = {
     subject: string,
@@ -77,12 +82,12 @@ export const evoAddArgs = {
 const toJson = stringify(identity);
 /** Registry of all Evo tools, bound to an `Evo<O>`. */
 export const evoToolRegistry = (e) => [
-    toolEntry('evo_list', 'List all subjects with at least one stored revision, as a JSON array of strings.', evoListArgs, 
+    toolEntry('evo_list', 'List subjects, as a JSON array of strings. By default only the active ones: a subject is active while at least one of its current heads is not archived. Pass `archived: true` to list the archived subjects instead — those with at least one current head, all of them archived. A subject with no current heads is in neither list.', evoListArgs, 
     // Subjects are arbitrary caller-supplied strings (unlike hashes, not
     // constrained to a newline-free alphabet), so a `join('\n')` line
     // format could not represent an empty subject or one containing a
     // newline without ambiguity — JSON encoding can.
-    () => step(e.list(), subjects => pure(okResult(toJson(subjects))))),
+    ({ archived }) => step(e.list(archived), subjects => pure(okResult(toJson(subjects))))),
     toolEntry('evo_head', 'List the current head hashes (cBase32) of a subject, one per line. Empty when the subject is unknown.', evoHeadArgs, ({ subject }) => step(e.head(subject), heads => pure(okResult(heads.join('\n'))))),
     toolEntry('evo_revision', 'Read one revision by hash, as JSON: `{ subject, parents, snapshot, generation, archived? }`. `parents[0]` is the mainline parent and every further entry is a merged-in branch; `parents` and `snapshot` come back in their canonical cBase32 spelling, so they compare directly against `evo_head` output. Errors when the hash is not cBase32, is not present in the store, could not be read, or does not hold a `vnd.fjs.revision` blob — use `cas_get` for raw bytes of non-revision content.', evoRevisionArgs, 
     // The revision goes out as JSON in a text content item, like

package/fjs/mcp/evo/proof.f.d.ts

@@ -2,6 +2,7 @@ export declare const proof: {
     toolNamesMatchTheDesign: () => void;
     evoListReflectsTheCache: () => void;
     evoListEncodesArbitrarySubjectsAsJson: () => void;
+    evoListForwardsTheArchivedFilter: () => void;
     evoHeadReflectsTheCache: () => void;
     evoHeadMissingSubjectIsInvalidArguments: () => void;
     evoRevisionReturnsRevisionJson: () => void;

package/fjs/mcp/evo/proof.f.js

@@ -6,7 +6,12 @@ import { vec8 } from '../../types/bit_vec/module.f.js';
 import { vecToCBase32 } from '../../basen/cbase32/module.f.js';
 import { initEvo, evo } from '../../cas/evo/module.f.js';
 import { evoToolRegistry } from './module.f.js';
+import { parse as parseJson } from '../../media/json/module.f.js';
+import { array, string as rttiString } from '../../types/rtti/module.f.js';
+import { parse as rttiParse } from '../../types/rtti/parse/module.f.js';
+import { unwrap } from '../../types/result/module.f.js';
 const home = '/home/user';
+const parseSubjects = rttiParse(array(rttiString));
 const findEntry = (registry, name) => {
     const entry = registry.find(e => e.name === name);
     assert(entry !== undefined, ['missing tool entry', name]);
@@ -52,11 +57,27 @@ export const proof = {
         const entry = findEntry(evoToolRegistry(e), 'evo_list');
         const [, result] = virtual(state2)(entry.handle({}));
         assert(!result.isError);
-        const subjects = JSON.parse(textOf(result));
+        const subjects = unwrap(parseSubjects(unwrap(parseJson(textOf(result)))));
         assertEq(subjects.length, 2);
         assert(subjects.includes('line one\nline two'), ['unexpected subjects', subjects]);
         assert(subjects.includes(''), ['unexpected subjects', subjects]);
     },
+    // The `archived` argument is a pass-through to `Evo.list`'s status filter:
+    // omitted lists the active subjects, `true` the archived ones.
+    evoListForwardsTheArchivedFilter: () => {
+        const c = fileCas(sha256)(home);
+        const [state0, cacheKey] = virtual(emptyState)(initEvo(c));
+        const e = evo(c)(cacheKey);
+        const [state1, add] = virtual(state0)(e.add({ parents: [], subject: 'gone', snapshot: vecToCBase32(vec8(0x2cn)), archived: true }));
+        assert(add[0] === 'ok', ['expected add ok', add]);
+        const entry = findEntry(evoToolRegistry(e), 'evo_list');
+        const [state2, active] = virtual(state1)(entry.handle({}));
+        assert(!active.isError);
+        assertEq(textOf(active), '[]');
+        const [, archived] = virtual(state2)(entry.handle({ archived: true }));
+        assert(!archived.isError);
+        assertEq(textOf(archived), '["gone"]');
+    },
     evoHeadReflectsTheCache: () => {
         const c = fileCas(sha256)(home);
         const [state0, cacheKey] = virtual(emptyState)(initEvo(c));

package/fjs/mcp/module.f.d.ts

@@ -14,7 +14,7 @@
  * | `cas_add`      | `{ content, type? }`                          | `c.write(...)`   | hash (cBase32)                      |
  * | `cas_get`      | `{ hash, content?: boolean }`                 | `c.read(key)`    | JSON `{length,mimeType,type[,uri][,text\|blob]}` |
  * | `cas_list`     | `{}`                                          | `c.list()`       | hashes, one per line                |
- * | `evo_list`     | `{}`                                          | `e.list()`       | subjects, one per line              |
+ * | `evo_list`     | `{ archived? }`                               | `e.list(...)`    | subjects, as a JSON array of strings |
  * | `evo_head`     | `{ subject }`                                 | `e.head(...)`    | head hashes, one per line           |
  * | `evo_revision` | `{ hash }`                                    | `e.revision(...)`| the revision, as JSON               |
  * | `evo_add`      | `{ parents, snapshot?, subject?, archived? }` | `e.add(...)`     | hash (cBase32)                      |

package/fjs/mcp/module.f.js

@@ -14,7 +14,7 @@
  * | `cas_add`      | `{ content, type? }`                          | `c.write(...)`   | hash (cBase32)                      |
  * | `cas_get`      | `{ hash, content?: boolean }`                 | `c.read(key)`    | JSON `{length,mimeType,type[,uri][,text\|blob]}` |
  * | `cas_list`     | `{}`                                          | `c.list()`       | hashes, one per line                |
- * | `evo_list`     | `{}`                                          | `e.list()`       | subjects, one per line              |
+ * | `evo_list`     | `{ archived? }`                               | `e.list(...)`    | subjects, as a JSON array of strings |
  * | `evo_head`     | `{ subject }`                                 | `e.head(...)`    | head hashes, one per line           |
  * | `evo_revision` | `{ hash }`                                    | `e.revision(...)`| the revision, as JSON               |
  * | `evo_add`      | `{ parents, snapshot?, subject?, archived? }` | `e.add(...)`     | hash (cBase32)                      |

package/fjs/mcp/proof.f.js

@@ -1,6 +1,9 @@
 import { assert, assertEq } from '../asserts/module.f.js';
 import { pure, step } from '../effects/module.f.js';
 import { create } from '../effects/memory/module.f.js';
+import { parse as parseJson } from '../media/json/module.f.js';
+import { number as rttiNumber, option, string as rttiString } from '../types/rtti/module.f.js';
+import { parse as rttiParse } from '../types/rtti/parse/module.f.js';
 import { msb, u8ListToVec, vec8, repeat, length, maxLengthBytes } from '../types/bit_vec/module.f.js';
 import { vecToCBase32 } from '../basen/cbase32/module.f.js';
 import { encode as base64Encode } from '../basen/base64/module.f.js';
@@ -12,10 +15,24 @@ import { nonEmpty, empty as elEmpty } from '../effects/list/module.f.js';
 import { mcpStep, uninitializedState, } from '../protocol/mcp/module.f.js';
 import { emptyState, virtual } from '../effects/node/virtual/module.f.js';
 import { casConfig, casMcpHandlers } from './module.f.js';
-import { ok as resultOk } from '../types/result/module.f.js';
+import { ok as resultOk, unwrap } from '../types/result/module.f.js';
 import { stdioTransport } from '../protocol/mcp/stdio/module.f.js';
 import { fromVec } from '../types/uint8array/module.f.js';
 import { initEvo } from '../cas/evo/module.f.js';
+// `cas_get`'s result JSON. As an rtti schema it both describes the shape and
+// checks it, so reading a field needs neither a hand-written type nor an `as`
+// cast — a response that drifts from this fails the test at the parse, not
+// silently at the assertion. `uri` is always emitted; only the payload
+// (`text` for `type: 'text'`, `blob` for `type: 'base64'`) is conditional.
+const casGetResult = {
+    length: rttiNumber,
+    mimeType: rttiString,
+    type: rttiString,
+    uri: rttiString,
+    text: option(rttiString),
+    blob: option(rttiString),
+};
+const parseCasGetResult = rttiParse(casGetResult);
 // ── Session driver ──────────────────────────────────────────────────────────────
 // Feeds each message to `handler` in order, collecting every response.
 const feed = (handler) => (msgs) => {
@@ -70,11 +87,13 @@ const runStdio = (root, home = '/home/user') => (msgs) => {
     const stdout = virtual({ ...emptyState, root, stdin: toBytes(input) })(effect)[0].stdout;
     // Only requests get a written line (notifications, like `initialized`,
     // write nothing) — drop the `init` response, keep one line per `msgs` entry.
-    return stdout.split('\n').filter(line => line.length > 0).slice(1).map(line => JSON.parse(line));
+    return stdout.split('\n').filter(line => line.length > 0).slice(1).map(line => unwrap(parseJson(line)));
 };
 const resultOf = (resp) => resp.result;
 const item0 = (resp) => resultOf(resp).content[0];
 const textOf = (resp) => item0(resp).text;
+/** The `text` payload of a `cas_get` response, parsed and checked against {@link casGetResult}. */
+const casGetResultOf = (resp) => unwrap(parseCasGetResult(unwrap(parseJson(textOf(resp)))));
 // A plain text sample for text add→get round-trips.
 const textSample = 'hello, world!';
 // A valid `vnd.fjs.revision` blob: every required field present, including the
@@ -115,7 +134,7 @@ const largeMultiChunkBlobMeta = (chunk0, chunk1, expectedType, expectedMime) =>
         call(2, 'cas_get', { hash }),
     ]).slice(2);
     assert(!resultOf(metaResp).isError);
-    const meta = JSON.parse(textOf(metaResp));
+    const meta = casGetResultOf(metaResp);
     assertEq(meta.type, expectedType);
     assertEq(meta.mimeType, expectedMime);
     assertEq(meta.length, Number((length(chunk0) + length(chunk1)) / 8n));
@@ -204,7 +223,7 @@ export const proof = {
             call(2, 'cas_get', { hash, content: true }),
         ]);
         assert(!resultOf(getResp).isError);
-        const result = JSON.parse(textOf(getResp));
+        const result = casGetResultOf(getResp);
         assertEq(result.type, 'base64');
         assertEq(result.length, 90_000);
     },
@@ -274,7 +293,7 @@ export const proof = {
         const hash = textOf(addResp);
         const [, getResp] = session(call(2, 'cas_add', { content: textSample }), call(3, 'cas_get', { hash }));
         assert(!resultOf(getResp).isError);
-        const result = JSON.parse(textOf(getResp));
+        const result = casGetResultOf(getResp);
         assertEq(result.mimeType, 'text/plain');
         assertEq(result.type, 'text');
         assertEq(result.length, textSample.length);
@@ -286,7 +305,7 @@ export const proof = {
         const hash = textOf(addResp);
         const [, getResp] = session(call(2, 'cas_add', { content: textSample }), call(3, 'cas_get', { hash, content: true }));
         assert(!resultOf(getResp).isError);
-        const result = JSON.parse(textOf(getResp));
+        const result = casGetResultOf(getResp);
         assertEq(result.type, 'text');
         assertEq(result.mimeType, 'text/plain');
         assertEq(result.text, textSample);
@@ -297,7 +316,7 @@ export const proof = {
         const hash = textOf(addResp);
         const [, getResp] = session(call(2, 'cas_add', { content: binarySample, type: 'base64' }), call(3, 'cas_get', { hash }));
         assert(!resultOf(getResp).isError);
-        const result = JSON.parse(textOf(getResp));
+        const result = casGetResultOf(getResp);
         assertEq(result.text, undefined);
         assertEq(result.type, 'text');
         assertEq(result.mimeType, 'text/plain');
@@ -308,7 +327,7 @@ export const proof = {
         const hash = textOf(addResp);
         const [, getResp] = session(call(2, 'cas_add', { content: binarySample, type: 'base64' }), call(3, 'cas_get', { hash, content: true }));
         assert(!resultOf(getResp).isError);
-        const result = JSON.parse(textOf(getResp));
+        const result = casGetResultOf(getResp);
         assertEq(result.type, 'text');
         assertEq(result.text, '*');
     },
@@ -317,7 +336,7 @@ export const proof = {
         const hash = textOf(addResp);
         const [, getResp] = session(call(2, 'cas_add', { content: textSample }), call(3, 'cas_get', { hash, content: true }));
         assert(!resultOf(getResp).isError);
-        const result = JSON.parse(textOf(getResp));
+        const result = casGetResultOf(getResp);
         assertEq(result.text, textSample);
     },
     // Text content (no magic-byte match, valid UTF-8) comes back with type:'text' when content requested.
@@ -326,7 +345,7 @@ export const proof = {
         const hash = textOf(addResp);
         const [, getResp] = session(call(2, 'cas_add', { content: textSample }), call(3, 'cas_get', { hash, content: true }));
         assertEq(item0(getResp) === null ? null : item0(getResp).type, 'text');
-        const result = JSON.parse(textOf(getResp));
+        const result = casGetResultOf(getResp);
         assertEq(result.type, 'text');
         assertEq(result.mimeType, 'text/plain');
     },
@@ -337,7 +356,7 @@ export const proof = {
         const [, getResp] = session(call(2, 'cas_add', { content: pngSample, type: 'base64' }), call(3, 'cas_get', { hash, content: true }));
         assert(!resultOf(getResp).isError);
         assertEq(item0(getResp).type, 'text');
-        const result = JSON.parse(textOf(getResp));
+        const result = casGetResultOf(getResp);
         assertEq(result.type, 'base64');
         assertEq(result.mimeType, 'image/png');
         assertEq(result.blob, pngSample);
@@ -351,7 +370,7 @@ export const proof = {
         const hash = textOf(addResp);
         const [, metaResp] = session(call(2, 'cas_add', { content: revisionSample }), call(3, 'cas_get', { hash }));
         assert(!resultOf(metaResp).isError);
-        const meta = JSON.parse(textOf(metaResp));
+        const meta = casGetResultOf(metaResp);
         assertEq(meta.mimeType, revisionMediaType);
         assertEq(meta.type, 'text');
     },
@@ -362,7 +381,7 @@ export const proof = {
         const hash = textOf(addResp);
         const [, getResp] = session(call(2, 'cas_add', { content: revisionSample }), call(3, 'cas_get', { hash, content: true }));
         assert(!resultOf(getResp).isError);
-        const result = JSON.parse(textOf(getResp));
+        const result = casGetResultOf(getResp);
         assertEq(result.mimeType, revisionMediaType);
         assertEq(result.type, 'text');
         assertEq(result.text, revisionSample);
@@ -449,7 +468,7 @@ export const proof = {
         const hash = textOf(addResp);
         const [, metaResp] = session(call(2, 'cas_add', { content: 'text content' }), call(3, 'cas_get', { hash }));
         assert(!resultOf(metaResp).isError);
-        const meta = JSON.parse(textOf(metaResp));
+        const meta = casGetResultOf(metaResp);
         assertEq(meta.mimeType, 'text/plain');
         assertEq(meta.type, 'text');
         assertEq(meta.length, 12);
@@ -460,7 +479,7 @@ export const proof = {
         const hash = textOf(addResp);
         const [, metaResp] = session(call(2, 'cas_add', { content: pngSample, type: 'base64' }), call(3, 'cas_get', { hash }));
         assert(!resultOf(metaResp).isError);
-        const meta = JSON.parse(textOf(metaResp));
+        const meta = casGetResultOf(metaResp);
         assertEq(meta.mimeType, 'image/png');
         assertEq(meta.type, 'base64');
         assertEq(meta.length, 10);
@@ -473,7 +492,7 @@ export const proof = {
         const hash = textOf(addResp);
         const [, metaResp] = session(call(2, 'cas_add', { content: binaryB64, type: 'base64' }), call(3, 'cas_get', { hash }));
         assert(!resultOf(metaResp).isError);
-        const meta = JSON.parse(textOf(metaResp));
+        const meta = casGetResultOf(metaResp);
         assertEq(meta.mimeType, 'application/octet-stream');
         assertEq(meta.type, 'base64');
         assertEq(meta.blob, undefined);
@@ -487,7 +506,7 @@ export const proof = {
         const hash = textOf(addResp);
         const [, metaResp] = session(call(2, 'cas_add', { content: nulB64, type: 'base64' }), call(3, 'cas_get', { hash }));
         assert(!resultOf(metaResp).isError);
-        const meta = JSON.parse(textOf(metaResp));
+        const meta = casGetResultOf(metaResp);
         assertEq(meta.mimeType, 'application/octet-stream');
         assertEq(meta.type, 'base64');
     },
@@ -508,7 +527,7 @@ export const proof = {
         const hash = textOf(addResp);
         const [, getResp] = session(call(2, 'cas_add', { content: binaryB64, type: 'base64' }), call(3, 'cas_get', { hash, content: true }));
         assert(!resultOf(getResp).isError);
-        const result = JSON.parse(textOf(getResp));
+        const result = casGetResultOf(getResp);
         assertEq(result.mimeType, 'application/octet-stream');
         assertEq(result.type, 'base64');
         assertEq(result.blob, binaryB64);

package/fjs/media/json/module.f.d.ts

@@ -2,6 +2,9 @@
  * JSON value types, rtti schemas, and utilities: `serialize`, `stringify`,
  * `parse`, and `setProperty` for immutable nested updates.
  *
+ * `parse` is the total, `Result`-returning `text → Unknown` entry point built
+ * on this module's own tokenizer and parser.
+ *
  * The JSON value types (`Unknown`, `Primitive`) are derived from the rtti
  * schemas defined here, so the schema is the single source of truth — no
  * hand-written types to keep in sync.
@@ -9,6 +12,7 @@
  * @module
  */
 import { type List } from '../../types/list/module.f.ts';
+import type { Result } from '../../types/result/module.f.ts';
 import { type Entry as ObjectEntry } from '../../types/object/module.f.ts';
 import type { Ts } from '../../types/rtti/ts/module.f.ts';
 /** rtti schema matching any JSON primitive: `null`, `boolean`, `number`, or `string`. */
@@ -46,5 +50,15 @@ export declare const serialize: (mapEntries: MapEntries) => (value: Unknown) =>
  * https://tc39.es/ecma262/#sec-serializejsonproperty
  */
 export declare const stringify: (mapEntries: MapEntries) => (value: Unknown) => string;
-export declare const parse: (value: string) => Unknown;
+/**
+ * Parses `text` as JSON with this module's own pure tokenizer and parser,
+ * reporting failure as a `Result` rather than throwing: malformed input is
+ * *available* as an `error` to branch on. Whether to branch or to `unwrap` it
+ * back into a panic is the caller's decision — the parser no longer makes it
+ * for them.
+ *
+ * The result is an untyped {@link Unknown}; narrow it to a domain type with an
+ * rtti schema (`fjs/types/rtti/parse`) rather than with an `as` cast.
+ */
+export declare const parse: (text: string) => Result<Unknown, string>;
 export {};