functionalscript 0.36.0 → 0.38.0

package/{fs → fjs/media}/json/rpc/module.f.js

@@ -7,16 +7,16 @@
  * value to a response value (or `null` for a notification) and performs no I/O.
  *
  * Out of scope here (follow-ups): transports — stdio / HTTP framing — over
- * `fs/effects/node`, and concrete method sets such as MCP (i665-mcp), which layer
+ * `fjs/effects/node`, and concrete method sets such as MCP (i665-mcp), which layer
  * on top of `dispatch`.
  *
  * https://www.jsonrpc.org/specification
  *
  * @module
  */
-import { number, string, or, option } from "../../types/rtti/module.f.js";
-import { validate } from "../../types/rtti/validate/module.f.js";
-import { unknown } from "../module.f.js";
+import { number, string, or, option } from '../../../types/rtti/module.f.js';
+import { validate } from '../../../types/rtti/validate/module.f.js';
+import { unknown } from '../module.f.js';
 export const jsonrpc = '2.0';
 /** Request/response identifier: a string, a number, or `null`. */
 const id = or(string, number, null);

package/{fs → fjs/media}/json/rpc/proof.f.js

@@ -1,7 +1,7 @@
-import { assert, assertEq } from "../../asserts/module.f.js";
-import { ok, error } from "../../types/result/module.f.js";
-import { validate } from "../../types/rtti/validate/module.f.js";
-import { error as errorSchema, decodeRequest, dispatch, rpcError, parseError, invalidRequest, methodNotFound, invalidParams, internalError, } from "./module.f.js";
+import { assert, assertEq } from '../../../asserts/module.f.js';
+import { ok, error } from '../../../types/result/module.f.js';
+import { validate } from '../../../types/rtti/validate/module.f.js';
+import { error as errorSchema, decodeRequest, dispatch, rpcError, parseError, invalidRequest, methodNotFound, invalidParams, internalError, } from './module.f.js';
 const isOk = (r) => r[0] === 'ok';
 const handlers = {
     ping: () => ok('pong'),

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

@@ -0,0 +1,78 @@
+/**
+ * Converts an rtti schema to a JSON Schema (draft 2020-12) object.
+ *
+ * Driven by `fjs/types/rtti/common/module.f.ts`'s `visit`, the same shared
+ * `Type`-ADT walker used by `validate` and `parse`.
+ *
+ * @module
+ */
+import { type Type as RttiType } from '../../../types/rtti/module.f.ts';
+import type { Ts } from '../../../types/rtti/ts/module.f.ts';
+import type { Phantom } from '../../../types/phantom/module.f.ts';
+import { unknown as jsonUnknown } from '../module.f.ts';
+declare const unknownThunk: () => readonly ['const', {
+    readonly type: import("../../../types/rtti/module.f.ts").Or<["boolean", "number", "string", "integer", "array", "object", undefined]>;
+    readonly const: import("../../../types/rtti/module.f.ts").Or<readonly [typeof jsonUnknown, undefined]>;
+    readonly not: import("../../../types/rtti/module.f.ts").Or<readonly [Phantom<() => readonly ['const', /*elided*/ any], UnknownConst>, undefined]>;
+    readonly anyOf: import("../../../types/rtti/module.f.ts").Or<readonly [import("../../../types/rtti/module.f.ts").Type1<"array", Phantom<() => readonly ['const', any], UnknownConst>>, undefined]>;
+    readonly items: import("../../../types/rtti/module.f.ts").Or<[Phantom<() => readonly ['const', any], UnknownConst>, false, undefined]>;
+    readonly prefixItems: import("../../../types/rtti/module.f.ts").Or<readonly [import("../../../types/rtti/module.f.ts").Type1<"array", Phantom<() => readonly ['const', any], UnknownConst>>, undefined]>;
+    readonly properties: import("../../../types/rtti/module.f.ts").Or<readonly [import("../../../types/rtti/module.f.ts").Type1<"record", Phantom<() => readonly ['const', any], UnknownConst>>, undefined]>;
+    readonly required: import("../../../types/rtti/module.f.ts").Or<readonly [import("../../../types/rtti/module.f.ts").Type1<"array", import("../../../types/rtti/module.f.ts").String>, undefined]>;
+    readonly additionalProperties: import("../../../types/rtti/module.f.ts").Or<readonly [Phantom<() => readonly ['const', any], UnknownConst>, undefined]>;
+}];
+/** rtti schema for a JSON Schema (draft 2020-12) document. */
+export declare const unknown: Phantom<typeof unknownThunk, UnknownConst>;
+/** A JSON Schema (draft 2020-12) document — the subset of keywords that `toJsonSchema` emits. */
+export type Unknown = Ts<typeof unknown>;
+declare const unknownConst: {
+    readonly type: import("../../../types/rtti/module.f.ts").Or<["boolean", "number", "string", "integer", "array", "object", undefined]>;
+    readonly const: import("../../../types/rtti/module.f.ts").Or<readonly [typeof jsonUnknown, undefined]>;
+    readonly not: import("../../../types/rtti/module.f.ts").Or<readonly [Phantom<typeof unknownThunk, UnknownConst>, undefined]>;
+    readonly anyOf: import("../../../types/rtti/module.f.ts").Or<readonly [import("../../../types/rtti/module.f.ts").Type1<"array", Phantom<typeof unknownThunk, UnknownConst>>, undefined]>;
+    readonly items: import("../../../types/rtti/module.f.ts").Or<[Phantom<typeof unknownThunk, UnknownConst>, false, undefined]>;
+    readonly prefixItems: import("../../../types/rtti/module.f.ts").Or<readonly [import("../../../types/rtti/module.f.ts").Type1<"array", Phantom<typeof unknownThunk, UnknownConst>>, undefined]>;
+    readonly properties: import("../../../types/rtti/module.f.ts").Or<readonly [import("../../../types/rtti/module.f.ts").Type1<"record", Phantom<typeof unknownThunk, UnknownConst>>, undefined]>;
+    readonly required: import("../../../types/rtti/module.f.ts").Or<readonly [import("../../../types/rtti/module.f.ts").Type1<"array", import("../../../types/rtti/module.f.ts").String>, undefined]>;
+    readonly additionalProperties: import("../../../types/rtti/module.f.ts").Or<readonly [Phantom<typeof unknownThunk, UnknownConst>, undefined]>;
+};
+/**
+ * Hand-written base type used as the `$out` annotation on `unknown`.
+ *
+ * The `?` markers are required even though `Ts<>` already includes `undefined`
+ * in each field type. Without `?`, `Unknown = UnknownConst` would require all
+ * 9 fields to be present in every object literal returned by `toJsonSchema`,
+ * because TypeScript distinguishes "field absent" (`?`) from "field present but
+ * undefined" (`T | undefined`). JSON Schema objects only include the fields
+ * they need, so all fields must be optional.
+ */
+type UnknownConst = {
+    readonly type?: Ts<typeof unknownConst.type>;
+    readonly const?: Ts<typeof unknownConst.const>;
+    readonly not?: Ts<typeof unknownConst.not>;
+    readonly anyOf?: Ts<typeof unknownConst.anyOf>;
+    readonly items?: Ts<typeof unknownConst.items>;
+    readonly prefixItems?: Ts<typeof unknownConst.prefixItems>;
+    readonly properties?: Ts<typeof unknownConst.properties>;
+    readonly required?: Ts<typeof unknownConst.required>;
+    readonly additionalProperties?: Ts<typeof unknownConst.additionalProperties>;
+};
+/**
+ * Converts an rtti `Type` to a JSON Schema (draft 2020-12) object.
+ *
+ * | rtti                                          | JSON Schema                                                                         |
+ * |-----------------------------------------------|-------------------------------------------------------------------------------------|
+ * | `boolean` / `number` / `string`               | `{ "type": "..." }`                                                                 |
+ * | `bigint`                                      | `{ "type": "integer" }` (lossy; JSON integers are IEEE-754 doubles)                 |
+ * | `unknown`                                     | `{}` (always-true schema)                                                           |
+ * | primitive const (`42`, `'x'`, `true`, `null`) | `{ "const": <value> }`                                                              |
+ * | `bigint` const                                | `{ "const": Number(value) }` (lossy for \|value\| > MAX_SAFE_INTEGER)               |
+ * | `undefined` const                             | `{ "not": {} }` (no JSON value satisfies this)                                      |
+ * | struct `{ a: T, … }`                          | `{ "type": "object", "properties": { "a": …T… }, "required": [non-optional keys] }` |
+ * | tuple `[A, B]`                                | `{ "type": "array", "prefixItems": […A…, …B…], "items": false }`                    |
+ * | `array(T)`                                    | `{ "type": "array", "items": …T… }`                                                 |
+ * | `record(T)`                                   | `{ "type": "object", "additionalProperties": …T… }`                                 |
+ * | `or(...types)`                                | `{ "anyOf": […each…] }`                                                             |
+ */
+export declare const toJsonSchema: (rtti: RttiType) => Unknown;
+export {};

package/{fs → fjs/media}/json/schema/module.f.js

@@ -1,13 +1,14 @@
 /**
  * Converts an rtti schema to a JSON Schema (draft 2020-12) object.
  *
- * Mirrors the visitor structure of `fs/types/rtti/ts/module.f.ts` (`printer` / `toTs`),
- * but emits a JSON Schema object instead of a TypeScript type string.
+ * Driven by `fjs/types/rtti/common/module.f.ts`'s `visit`, the same shared
+ * `Type`-ADT walker used by `validate` and `parse`.
  *
  * @module
  */
-import { array, option, or, record, string } from "../../types/rtti/module.f.js";
-import { unknown as jsonUnknown } from "../module.f.js";
+import { array, option, or, record, string } from '../../../types/rtti/module.f.js';
+import { visit } from '../../../types/rtti/common/module.f.js';
+import { unknown as jsonUnknown } from '../module.f.js';
 const unknownThunk = () => ['const', unknownConst];
 /** rtti schema for a JSON Schema (draft 2020-12) document. */
 export const unknown = unknownThunk;
@@ -45,24 +46,10 @@ const stripUndefined = (rtti) => {
     const rest = r.flatMap(t => t !== undefined ? [t] : []);
     return rest.length === 1 ? rest[0] : or(...rest);
 };
-const constToJsonSchema = (rtti) => {
-    if (typeof rtti === 'undefined') {
-        return { not: {} };
-    }
-    if (typeof rtti !== 'object' || rtti === null) {
-        // bigint consts are represented as numbers (lossy for |value| > MAX_SAFE_INTEGER)
-        return { const: typeof rtti === 'bigint' ? Number(rtti) : rtti };
-    }
-    if (rtti instanceof Array) {
-        return {
-            type: 'array',
-            prefixItems: rtti.map(toJsonSchema),
-            items: false,
-        };
-    }
-    // Struct: keys not admitting undefined go into `required`; optional keys have
-    // undefined stripped from their property schema. additionalProperties is omitted
-    // (lenient), matching rtti's open-struct validation semantics.
+// Struct: keys not admitting undefined go into `required`; optional keys have
+// undefined stripped from their property schema. additionalProperties is omitted
+// (lenient), matching rtti's open-struct validation semantics.
+const structSchema = (rtti) => {
     const ents = Object.entries(rtti);
     const properties = Object.fromEntries(ents.map(([k, v]) => [k, toJsonSchema(stripUndefined(v))]));
     const required = ents
@@ -74,6 +61,21 @@ const constToJsonSchema = (rtti) => {
         ...(required.length > 0 ? { required } : {}),
     };
 };
+const constPrimitiveSchema = (rtti) => rtti === undefined
+    ? { not: {} }
+    // bigint consts are represented as numbers (lossy for |value| > MAX_SAFE_INTEGER)
+    : { const: typeof rtti === 'bigint' ? Number(rtti) : rtti };
+const visitor = {
+    tuple: (t) => ({ type: 'array', prefixItems: t.map(toJsonSchema), items: false }),
+    struct: structSchema,
+    array: item => ({ type: 'array', items: toJsonSchema(item) }),
+    record: item => ({ type: 'object', additionalProperties: toJsonSchema(item) }),
+    or: variants => ({ anyOf: variants.map(toJsonSchema) }),
+    constPrimitive: constPrimitiveSchema,
+    // bigint is not representable in JSON Schema; 'integer' is the closest approximation
+    primitive0: tag => ({ type: tag === 'bigint' ? 'integer' : tag }),
+    unknown: () => ({}),
+};
 /**
  * Converts an rtti `Type` to a JSON Schema (draft 2020-12) object.
  *
@@ -91,22 +93,4 @@ const constToJsonSchema = (rtti) => {
  * | `record(T)`                                   | `{ "type": "object", "additionalProperties": …T… }`                                 |
  * | `or(...types)`                                | `{ "anyOf": […each…] }`                                                             |
  */
-export const toJsonSchema = (rtti) => {
-    if (typeof rtti !== 'function') {
-        return constToJsonSchema(rtti);
-    }
-    const [tag, ...rest] = rtti();
-    switch (tag) {
-        case 'const': return constToJsonSchema(rest[0]);
-        case 'boolean': return { type: 'boolean' };
-        case 'number': return { type: 'number' };
-        case 'string': return { type: 'string' };
-        // bigint is not representable in JSON Schema; 'integer' is the closest approximation
-        case 'bigint': return { type: 'integer' };
-        case 'unknown': return {};
-        case 'array': return { type: 'array', items: toJsonSchema(rest[0]) };
-        case 'record': return { type: 'object', additionalProperties: toJsonSchema(rest[0]) };
-        case 'or': return { anyOf: rest.map(toJsonSchema) };
-        default: return {};
-    }
-};
+export const toJsonSchema = visit(visitor);

package/{fs → fjs/media}/json/schema/proof.f.js

@@ -1,13 +1,12 @@
-import { boolean, number, string, bigint, unknown, array, record, or, option } from "../../types/rtti/module.f.js";
-import { stringify } from "../module.f.js";
-import { toJsonSchema, unknown as schemaUnknown } from "./module.f.js";
+import { boolean, number, string, bigint, unknown, array, record, or, option } from '../../../types/rtti/module.f.js';
+import { stringify } from '../module.f.js';
+import { toJsonSchema, unknown as schemaUnknown } from './module.f.js';
+import { assert, assertEq } from '../../../asserts/module.f.js';
 const serialize = (v) => stringify(e => e)(v);
 const eq = (rtti, expected) => () => {
     const result = serialize(toJsonSchema(rtti));
     const exp = serialize(expected);
-    if (result !== exp) {
-        throw [result, exp];
-    }
+    assertEq(result, exp, [result, exp]);
 };
 export const proof = {
     tag0: {
@@ -62,9 +61,7 @@ export const proof = {
     },
     schemaUnknownTag: () => {
         const r = schemaUnknown();
-        if (r[0] !== 'const') {
-            throw r[0];
-        }
+        assert(r[0] === 'const');
     },
     nested: {
         arrayOfRecords: eq(array(record(boolean)), {

package/{fs → fjs/media}/json/serializer/module.f.d.ts

@@ -3,7 +3,7 @@
  *
  * @module
  */
-import { type List } from '../../types/list/module.f.ts';
+import { type List } from '../../../types/list/module.f.ts';
 /**
  * Serializes a string as a JSON string literal.
  */

package/{fs → fjs/media}/json/serializer/module.f.js

@@ -3,8 +3,8 @@
  *
  * @module
  */
-import { flat, reduce, empty } from "../../types/list/module.f.js";
-import {} from "../../types/function/operator/module.f.js";
+import { flat, reduce, empty } from '../../../types/list/module.f.js';
+import {} from '../../../types/function/operator/module.f.js';
 const jsonStringify = JSON.stringify;
 /**
  * Serializes a string as a JSON string literal.

package/{fs → fjs/media}/json/serializer/proof.f.js

@@ -1,25 +1,20 @@
-import { arrayWrap, boolSerialize, numberSerialize, objectWrap, stringSerialize } from "./module.f.js";
-import * as list from "../../types/list/module.f.js";
+import { arrayWrap, boolSerialize, numberSerialize, objectWrap, stringSerialize } from './module.f.js';
+import * as list from '../../../types/list/module.f.js';
+import { assertEq } from '../../../asserts/module.f.js';
 const { toArray } = list;
 export const proof = {
     arrayWrap: [
         () => {
             const result = JSON.stringify(toArray(arrayWrap(null)));
-            if (result !== '["[","]"]') {
-                throw result;
-            }
+            assertEq(result, '["[","]"]');
         },
         () => {
             const result = JSON.stringify(toArray(arrayWrap([['a', 'b']])));
-            if (result !== '["[","a","b","]"]') {
-                throw result;
-            }
+            assertEq(result, '["[","a","b","]"]');
         },
         () => {
             const result = JSON.stringify(toArray(arrayWrap([['a'], ['b']])));
-            if (result !== '["[","a",",","b","]"]') {
-                throw result;
-            }
+            assertEq(result, '["[","a",",","b","]"]');
         }
     ],
     objectWrap: [
@@ -45,43 +40,31 @@ export const proof = {
     stringSerialize: [
         () => {
             const result = JSON.stringify(toArray(stringSerialize('abc')));
-            if (result !== '["\\"abc\\""]') {
-                throw result;
-            }
+            assertEq(result, '["\\"abc\\""]');
         },
         () => {
             const result = JSON.stringify(toArray(stringSerialize('123')));
-            if (result !== '["\\"123\\""]') {
-                throw result;
-            }
+            assertEq(result, '["\\"123\\""]');
         }
     ],
     numberSerialize: [
         () => {
             const result = JSON.stringify(toArray(numberSerialize(123)));
-            if (result !== '["123"]') {
-                throw result;
-            }
+            assertEq(result, '["123"]');
         },
         () => {
             const result = JSON.stringify(toArray(numberSerialize(10e20)));
-            if (result !== '["1e+21"]') {
-                throw result;
-            }
+            assertEq(result, '["1e+21"]');
         }
     ],
     boolSerialize: [
         () => {
             const result = JSON.stringify(toArray(boolSerialize(false)));
-            if (result !== '["false"]') {
-                throw result;
-            }
+            assertEq(result, '["false"]');
         },
         () => {
             const result = JSON.stringify(toArray(boolSerialize(true)));
-            if (result !== '["true"]') {
-                throw result;
-            }
+            assertEq(result, '["true"]');
         }
     ]
 };

package/{fs → fjs/media}/json/tokenizer/module.f.d.ts

@@ -1,5 +1,5 @@
-import { type List } from '../../types/list/module.f.ts';
-import { type EofToken, type ErrorToken, type NumberToken, type StringToken } from '../../js/tokenizer/module.f.ts';
+import { type List } from '../../../types/list/module.f.ts';
+import { type EofToken, type ErrorToken, type NumberToken, type StringToken } from '../../../js/tokenizer/module.f.ts';
 export type JsonToken = {
     readonly kind: 'true' | 'false' | 'null';
 } | {

package/{fs → fjs/media}/json/tokenizer/module.f.js

@@ -3,10 +3,10 @@
  *
  * @module
  */
-import {} from "../../types/function/operator/module.f.js";
-import { concat, empty, flat, stateScan } from "../../types/list/module.f.js";
-import { multiply } from "../../types/bigfloat/module.f.js";
-import { tokenize as jsTokenize } from "../../js/tokenizer/module.f.js";
+import {} from '../../../types/function/operator/module.f.js';
+import { concat, empty, flat, stateScan } from '../../../types/list/module.f.js';
+import { multiply } from '../../../types/bigfloat/module.f.js';
+import { tokenize as jsTokenize } from '../../../js/tokenizer/module.f.js';
 const mapToken = input => {
     switch (input.kind) {
         case '{':

package/{fs → fjs/media}/json/tokenizer/proof.f.js

@@ -1,8 +1,8 @@
-import { tokenize } from "./module.f.js";
-import { toArray } from "../../types/list/module.f.js";
-import { stringifyAsTree } from "../../djs/serializer/module.f.js";
-import { sort } from "../../types/object/module.f.js";
-import { stringToList } from "../../text/utf16/module.f.js";
+import { tokenize } from './module.f.js';
+import { toArray } from '../../../types/list/module.f.js';
+import { stringifyAsTree } from '../../../djs/serializer/module.f.js';
+import { sort } from '../../../types/object/module.f.js';
+import { stringToList } from '../../../text/utf16/module.f.js';
 const tokenizeString = s => toArray(tokenize(stringToList(s)));
 const stringify = stringifyAsTree(sort);
 export const proof = {

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

@@ -0,0 +1,37 @@
+/**
+ * Media-type detection entry point: dialect-tagged JSON recognition layered
+ * on top of the byte-signature / UTF-8 detector.
+ *
+ * `fjs/media/type` classifies raw bytes (magic-byte signatures, UTF-8
+ * text-vs-binary) with no notion of a JSON dialect. `detect` here adds one
+ * more classification step in front of it: when the whole blob is
+ * whole-blob-valid UTF-8 text (as `fjs/media/type` already determined), try
+ * parsing it as JSON and validating it against a known dialect's rtti schema
+ * (currently just `vnd.fjs.revision` — see `fjs/media/revision`). A match
+ * reports the dialect's derived media type; anything that isn't valid JSON,
+ * or doesn't validate against a known dialect, falls through to the
+ * `fjs/media/type` verdict unchanged.
+ *
+ * Detection is semantic, not syntactic: any JSON that satisfies a dialect's
+ * schema is recognized regardless of key order, whitespace, or any other
+ * serialization detail — there is no byte-level shortcut such as a
+ * `{"dialect":` prefix check.
+ *
+ * This only classifies an already-buffered `Vec` (`detectVec`'s single-`Vec`
+ * form), because dialect validation needs the whole parsed value. A single
+ * `Vec` already caps at `maxLength` bits (128 KiB — the same bound as the
+ * existing inline-content cap), so dialect detection is naturally
+ * size-bounded. The unbounded streaming detector (`fjs/media/type`
+ * `detectStream`) is untouched and stays a pure byte-signature/UTF-8
+ * classifier with no dialect awareness.
+ *
+ * @module
+ */
+import type { Vec } from '../types/bit_vec/module.f.ts';
+import { type DetectMeta } from './type/module.f.ts';
+/**
+ * Classifies a whole buffered `Vec`, the same three-way `{ length, mime_type,
+ * type }` shape as `fjs/media/type` `detectVec`, but with dialect-tagged JSON
+ * recognized ahead of the plain `text/plain` fallback.
+ */
+export declare const detect: (bytes: Vec) => DetectMeta;

package/fjs/media/module.f.js

@@ -0,0 +1,23 @@
+import { fromVec } from '../text/utf8/module.f.js';
+import { detectVec } from './type/module.f.js';
+import { decodeText as decodeRevisionText, mediaType as revisionMediaType } from './revision/module.f.js';
+import { assertNotNullish } from '../asserts/module.f.js';
+/**
+ * Classifies a whole buffered `Vec`, the same three-way `{ length, mime_type,
+ * type }` shape as `fjs/media/type` `detectVec`, but with dialect-tagged JSON
+ * recognized ahead of the plain `text/plain` fallback.
+ */
+export const detect = (bytes) => {
+    const base = detectVec(bytes);
+    // Only whole-blob-valid UTF-8 text can possibly be JSON; a magic-byte hit
+    // or binary fallback is never a dialect match.
+    if (base.type !== 'text') {
+        return base;
+    }
+    // `detectVec`'s `type: 'text'` verdict already means `bytes` is byte-aligned,
+    // whole-blob-valid UTF-8 — the same two conditions `fromVec` checks, via the
+    // same decoder — so `fromVec` cannot return `null` here.
+    const text = assertNotNullish(fromVec(bytes), 'detect: type text implies fromVec succeeds');
+    const [tag] = decodeRevisionText(text);
+    return tag === 'ok' ? { ...base, mime_type: revisionMediaType } : base;
+};

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

@@ -0,0 +1,9 @@
+export declare const proof: {
+    validRevision: () => void;
+    keyOrderIndependent: () => void;
+    invalidRevisionFallsThrough: () => void;
+    ordinaryJsonFallsThrough: () => void;
+    plainTextFallsThrough: () => void;
+    binaryFallsThrough: () => void;
+    largeNonJsonWithinBound: () => void;
+};

package/fjs/media/proof.f.js

@@ -0,0 +1,58 @@
+import { assertEq } from '../asserts/module.f.js';
+import { msb, u8ListToVec, repeat, vec8 } from '../types/bit_vec/module.f.js';
+import { detect } from './module.f.js';
+import { dialect } from './revision/module.f.js';
+// All test strings here are ASCII, so char code === UTF-8 byte value.
+const utf8Bytes = (s) => u8ListToVec(msb)([...s].map(c => c.charCodeAt(0)));
+const revisionJson = `{"dialect":"${dialect}","subject":"8","parents":[],"snapshot":"8","generation":0}`;
+export const proof = {
+    // A valid revision blob is recognized and reported under its derived media type.
+    validRevision: () => {
+        const m = detect(utf8Bytes(revisionJson));
+        assertEq(m.type, 'text');
+        assertEq(m.mime_type, 'application/vnd.fjs.revision+json');
+    },
+    // Key order carries no meaning: a valid revision whose `dialect` key is
+    // not first must still be detected.
+    keyOrderIndependent: () => {
+        const text = `{"parents":[],"subject":"8","dialect":"${dialect}","snapshot":"8","generation":0}`;
+        const m = detect(utf8Bytes(text));
+        assertEq(m.mime_type, 'application/vnd.fjs.revision+json');
+    },
+    // A revision missing a required field (here `snapshot` and `generation`)
+    // fails validation and falls through to the ordinary text/plain
+    // classification.
+    invalidRevisionFallsThrough: () => {
+        const text = `{"dialect":"${dialect}","subject":"8","parents":["8","r"]}`;
+        const m = detect(utf8Bytes(text));
+        assertEq(m.type, 'text');
+        assertEq(m.mime_type, 'text/plain');
+    },
+    // Ordinary JSON with no `dialect` field at all falls through unchanged.
+    ordinaryJsonFallsThrough: () => {
+        const m = detect(utf8Bytes('{"hello":"world"}'));
+        assertEq(m.type, 'text');
+        assertEq(m.mime_type, 'text/plain');
+    },
+    // Plain (non-JSON) text is unaffected.
+    plainTextFallsThrough: () => {
+        const m = detect(utf8Bytes('hello'));
+        assertEq(m.type, 'text');
+        assertEq(m.mime_type, 'text/plain');
+    },
+    // Binary content (magic-byte hit) is unaffected by dialect detection.
+    binaryFallsThrough: () => {
+        const m = detect(u8ListToVec(msb)([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]));
+        assertEq(m.type, 'base64');
+        assertEq(m.mime_type, 'image/png');
+    },
+    // A large blob is still bounded by the single-`Vec` `maxLength` cap; this
+    // only exercises that dialect detection doesn't change size handling for
+    // non-JSON content within that bound.
+    largeNonJsonWithinBound: () => {
+        const a = repeat(1000n)(vec8(0x61n)); // 1,000 bytes of 'a'
+        const m = detect(a);
+        assertEq(m.type, 'text');
+        assertEq(m.mime_type, 'text/plain');
+    },
+};

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

@@ -0,0 +1,78 @@
+import { type ValidationError } from '../../types/rtti/validate/module.f.ts';
+import type { Ts } from '../../types/rtti/ts/module.f.ts';
+import type { Unknown } from '../json/module.f.ts';
+import { type Result } from '../../types/result/module.f.ts';
+/**
+ * Format tag: names the dialect of this BLOB. The media type it is served
+ * with is derived mechanically: `application/` + `dialect` + `+json`.
+ */
+export declare const dialect: 'vnd.fjs.revision';
+/** The media type derived from {@link dialect}: `application/vnd.fjs.revision+json`. */
+export declare const mediaType: "application/vnd.fjs.revision+json";
+/**
+ * rtti schema for the snapshot-reference type: a cbase32 CAS hash string.
+ *
+ * This is `string` at the rtti (structural) level — rtti schemas can't
+ * express string-content refinements — so cbase32 decodability, and the
+ * rejection of `https://` bridge URLs and any other location-addressed
+ * reference form, is enforced by {@link isHash} / {@link validate} below,
+ * not by this schema on its own.
+ */
+export declare const hash: import("../../types/rtti/module.f.ts").String;
+/**
+ * rtti schema for a `revision` BLOB. See the README for the full semantics of
+ * each field; `dialect` is the type discriminant, matched here as an exact
+ * literal so structural validation alone rejects any other dialect's blob.
+ */
+export declare const revisionSchema: {
+    readonly dialect: "vnd.fjs.revision";
+    readonly subject: import("../../types/rtti/module.f.ts").String;
+    readonly parents: import("../../types/rtti/module.f.ts").Type1<"array", import("../../types/rtti/module.f.ts").String>;
+    readonly snapshot: import("../../types/rtti/module.f.ts").String;
+    readonly generation: import("../../types/rtti/module.f.ts").Number;
+    readonly archived: import("../../types/rtti/module.f.ts").Or<readonly [true, undefined]>;
+};
+/** The TypeScript type derived from {@link revisionSchema} — the single source of truth. */
+export type Revision = Ts<typeof revisionSchema>;
+/** True when `s` decodes as a cbase32 CAS hash (rejects `https://` and any other non-cbase32 string). */
+export declare const isHash: (s: string) => boolean;
+/** Either a structural validation error or a semantic (hash / generation) error message. */
+export type RevisionError = ValidationError | string;
+/**
+ * Checks the semantic refinements the structural schema can't express on an
+ * already shape-valid revision: every `parents` entry and the `snapshot` must
+ * decode as a cbase32 hash ({@link isHash}), and `generation` must be a
+ * non-negative *safe* integer. `subject` is not checked — it is an identity
+ * string, never a snapshot reference, so any string is valid.
+ *
+ * `generation` uses `Number.isSafeInteger`, not `Number.isInteger`: a value at
+ * or above `2 ** 53` passes `isInteger` but is no longer uniquely
+ * representable, so `1 + max(parents' generations)` — how a writer derives the
+ * next generation — can round back to the parent's value and fail to advance.
+ * Rejecting unsafe integers keeps stored generations exact.
+ *
+ * Both `snapshot` and `generation` are required by the schema, so no absence
+ * ever has to be resolved here: a revision states its content and its
+ * generation explicitly, and is fully interpretable in isolation (see the
+ * README). The former snapshot-resolution algorithm (subject-as-fallback,
+ * single-parent inheritance, multi-parent rejection) is gone.
+ *
+ * Exported separately from {@link validate} for callers that assemble a
+ * `Revision` themselves from already-typed fields (e.g. `fjs/cas/evo`'s
+ * `addRevision`): the shape is then guaranteed by TypeScript already, so only
+ * these semantic (string-only error) checks are worth re-running — routing
+ * through the combined structural-plus-semantic `validate` would add an
+ * unreachable structural-error branch on the caller's side.
+ */
+export declare const checkReferences: (r: Revision) => Result<Revision, string>;
+/**
+ * Validates an already-parsed JSON value as a `revision` BLOB: structural
+ * (rtti) validation followed by the hash / generation semantic checks.
+ */
+export declare const validate: (value: Unknown) => Result<Revision, RevisionError>;
+/**
+ * Decodes `text` as a `revision` BLOB: JSON-parses it, then validates it per
+ * {@link validate}. Detection is semantic, not syntactic — any JSON that
+ * satisfies the schema is a revision, regardless of key order or whitespace.
+ */
+export declare const decodeText: (text: string) => Result<Revision, RevisionError>;