functionalscript 0.36.0 → 0.37.0

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

@@ -0,0 +1,78 @@
+/**
+ * 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.
+ *
+ * @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/{json → media/json}/schema/module.f.js

@@ -6,8 +6,8 @@
  *
  * @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 { 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;

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

@@ -1,6 +1,6 @@
-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';
 const serialize = (v) => stringify(e => e)(v);
 const eq = (rtti, expected) => () => {
     const result = serialize(toJsonSchema(rtti));

package/fs/{json → 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/{json → 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/{json → media/json}/serializer/proof.f.js

@@ -1,5 +1,5 @@
-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';
 const { toArray } = list;
 export const proof = {
     arrayWrap: [

package/fs/{json → 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/{json → 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/{json → 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/fs/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.
+ *
+ * `fs/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 `fs/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 `fs/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
+ * `fs/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 (`fs/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 `fs/media/type` `detectVec`, but with dialect-tagged JSON
+ * recognized ahead of the plain `text/plain` fallback.
+ */
+export declare const detect: (bytes: Vec) => DetectMeta;

package/fs/media/module.f.js

@@ -0,0 +1,24 @@
+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 { assert } from '../asserts/module.f.js';
+/**
+ * Classifies a whole buffered `Vec`, the same three-way `{ length, mime_type,
+ * type }` shape as `fs/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;
+    }
+    const text = fromVec(bytes);
+    // `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.
+    assert(text !== null, 'detect: type text implies fromVec succeeds');
+    const [tag] = decodeRevisionText(text);
+    return tag === 'ok' ? { ...base, mime_type: revisionMediaType } : base;
+};

package/fs/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/fs/media/proof.f.js

@@ -0,0 +1,57 @@
+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":[]}`;
+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}"}`;
+        const m = detect(utf8Bytes(text));
+        assertEq(m.mime_type, 'application/vnd.fjs.revision+json');
+    },
+    // Structurally invalid revision (bad multi-parent snapshot rule) 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/fs/media/revision/module.f.d.ts

@@ -0,0 +1,51 @@
+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").Or<readonly [import("../../types/rtti/module.f.ts").String, undefined]>;
+    readonly generation: import("../../types/rtti/module.f.ts").Or<readonly [import("../../types/rtti/module.f.ts").Number, undefined]>;
+    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 (snapshot-reference) error message. */
+export type RevisionError = ValidationError | string;
+/**
+ * Validates an already-parsed JSON value as a `revision` BLOB: structural
+ * (rtti) validation followed by the snapshot-reference 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>;

package/fs/media/revision/module.f.js

@@ -0,0 +1,110 @@
+/**
+ * `vnd.fjs.revision` — one step in the evolution of a mutable object on top
+ * of an immutable content-addressable store.
+ *
+ * A revision BLOB links back to its parent revision(s) (a DAG, not just a
+ * chain, so concurrent edits can merge) and carries the full materialized
+ * content of that step — never an incremental diff (see the versioning rule
+ * in the README). This module is the pure format only: the rtti schema, the
+ * `dialect` tag, and decode/validate. No store access, no effects — head
+ * resolution, materialization, and reverse indexes are a separate, deferred
+ * concern.
+ *
+ * See `README.md` for the full spec.
+ *
+ * @module
+ */
+import { array, number, option, string } from '../../types/rtti/module.f.js';
+import { validate as rttiValidate } from '../../types/rtti/validate/module.f.js';
+import { parse as jsonParse } from '../json/parser/module.f.js';
+import { tokenize as jsonTokenize } from '../json/tokenizer/module.f.js';
+import { stringToList } from '../../text/utf16/module.f.js';
+import { cBase32ToVec } from '../../basen/cbase32/module.f.js';
+import { error, ok } from '../../types/result/module.f.js';
+/**
+ * Format tag: names the dialect of this BLOB. The media type it is served
+ * with is derived mechanically: `application/` + `dialect` + `+json`.
+ */
+export const dialect = 'vnd.fjs.revision';
+/** The media type derived from {@link dialect}: `application/vnd.fjs.revision+json`. */
+export const mediaType = `application/${dialect}+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 const hash = 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 const revisionSchema = {
+    dialect,
+    subject: string,
+    parents: array(hash),
+    snapshot: option(hash),
+    generation: option(number),
+    archived: option(true),
+};
+/** Structural-only validator: checks the shape, not the snapshot-reference semantics. */
+const validateShape = rttiValidate(revisionSchema);
+/** True when `s` decodes as a cbase32 CAS hash (rejects `https://` and any other non-cbase32 string). */
+export const isHash = (s) => cBase32ToVec(s) !== null;
+/**
+ * Checks the snapshot-reference semantics of an already shape-valid revision:
+ * every parent must be a hash; `snapshot`, when present, must be a hash;
+ * when `snapshot` is absent, zero parents fall back to `subject` (which must
+ * then be a hash), exactly one parent inherits that parent's snapshot, and
+ * more than one parent without an explicit `snapshot` is invalid — there is
+ * no single parent snapshot to inherit, and falling back to `subject` would
+ * silently lose the merge result.
+ */
+const checkReferences = (r) => {
+    for (const p of r.parents) {
+        if (!isHash(p)) {
+            return error(`parent is not a valid hash: ${p}`);
+        }
+    }
+    if (r.snapshot !== undefined) {
+        return isHash(r.snapshot) ? ok(r) : error(`snapshot is not a valid hash: ${r.snapshot}`);
+    }
+    if (r.parents.length === 0) {
+        return isHash(r.subject)
+            ? ok(r)
+            : error(`subject must be a valid hash when snapshot is absent and there are no parents: ${r.subject}`);
+    }
+    if (r.parents.length === 1) {
+        return ok(r);
+    }
+    return error('snapshot is required when a revision has more than one parent');
+};
+/**
+ * Validates an already-parsed JSON value as a `revision` BLOB: structural
+ * (rtti) validation followed by the snapshot-reference semantic checks.
+ */
+export const validate = (value) => {
+    const [t, v] = validateShape(value);
+    if (t === 'error') {
+        return error(v);
+    }
+    return checkReferences(v);
+};
+/** Parses `text` as JSON without relying on `JSON.parse` (the shared `fs/media/json` parser/tokenizer). */
+const parseJson = (text) => jsonParse(jsonTokenize(stringToList(text)));
+/**
+ * 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 const decodeText = (text) => {
+    const [t, v] = parseJson(text);
+    if (t === 'error') {
+        return error(v);
+    }
+    return validate(v);
+};

package/fs/media/revision/proof.f.d.ts

@@ -0,0 +1,29 @@
+export declare const proof: {
+    dialectAndMediaType: () => void;
+    isHash: {
+        validHash: () => void;
+        httpsRejected: () => void;
+        arbitraryStringRejected: () => void;
+    };
+    validate: {
+        firstRevisionFallsBackToSubjectHash: () => void;
+        firstRevisionRejectsNonHashSubject: () => void;
+        explicitSnapshotAllowsArbitrarySubject: () => void;
+        singleParentInheritsSnapshot: () => void;
+        multiParentWithoutSnapshotRejected: () => void;
+        multiParentWithSnapshotAccepted: () => void;
+        httpsRejectedInParents: () => void;
+        httpsRejectedInSnapshot: () => void;
+        httpsRejectedAsFallbackSubject: () => void;
+        archivedAccepted: () => void;
+        wrongDialectRejected: () => void;
+        missingSubjectRejected: () => void;
+        extraFieldsAccepted: () => void;
+    };
+    decodeText: {
+        validJson: () => void;
+        keyOrderIndependent: () => void;
+        malformedJsonRejected: () => void;
+        ordinaryJsonRejected: () => void;
+    };
+};

package/fs/media/revision/proof.f.js

@@ -0,0 +1,119 @@
+import { assert, assertEq } from '../../asserts/module.f.js';
+import { dialect, mediaType, isHash, validate, decodeText } from './module.f.js';
+// Valid cbase32 hashes (round-tripped in fs/basen/cbase32/proof.f.ts): single
+// cbase32 symbols, cheap to write inline here.
+const h1 = '8';
+const h2 = 'r';
+const revisionOf = (extra) => ({
+    dialect,
+    subject: h1,
+    parents: [],
+    ...extra,
+});
+export const proof = {
+    dialectAndMediaType: () => {
+        assertEq(dialect, 'vnd.fjs.revision');
+        assertEq(mediaType, 'application/vnd.fjs.revision+json');
+    },
+    isHash: {
+        validHash: () => assert(isHash(h1)),
+        httpsRejected: () => assert(!isHash('https://example.com/blob/abc')),
+        arbitraryStringRejected: () => assert(!isHash('not-a-hash!')),
+    },
+    validate: {
+        // Zero parents, no `snapshot`: `subject` is the fallback snapshot
+        // reference and must itself be a hash.
+        firstRevisionFallsBackToSubjectHash: () => {
+            const [t] = validate(revisionOf({}));
+            assertEq(t, 'ok');
+        },
+        // Zero parents, no `snapshot`, `subject` is not a hash: invalid.
+        firstRevisionRejectsNonHashSubject: () => {
+            const [t] = validate(revisionOf({ subject: 'my-config' }));
+            assertEq(t, 'error');
+        },
+        // `snapshot` present: `subject` may be an arbitrary string.
+        explicitSnapshotAllowsArbitrarySubject: () => {
+            const [t] = validate(revisionOf({ subject: 'my-config', snapshot: h2 }));
+            assertEq(t, 'ok');
+        },
+        // Exactly one parent, no `snapshot`: the parent's snapshot is inherited,
+        // and `subject` may be an arbitrary string.
+        singleParentInheritsSnapshot: () => {
+            const [t] = validate(revisionOf({ subject: 'my-config', parents: [h2] }));
+            assertEq(t, 'ok');
+        },
+        // More than one parent with no `snapshot`: invalid — no single parent
+        // snapshot to inherit, and falling back to `subject` would silently
+        // lose the merge result.
+        multiParentWithoutSnapshotRejected: () => {
+            const [t] = validate(revisionOf({ subject: 'my-config', parents: [h1, h2] }));
+            assertEq(t, 'error');
+        },
+        // A merge revision with an explicit `snapshot` is valid.
+        multiParentWithSnapshotAccepted: () => {
+            const [t, v] = validate(revisionOf({ subject: 'my-config', parents: [h1, h2], snapshot: h2 }));
+            assertEq(t, 'ok');
+            assertEq(v.snapshot, h2);
+        },
+        // `https://` bridge URLs are rejected wherever a hash is required.
+        httpsRejectedInParents: () => {
+            const [t] = validate(revisionOf({ subject: 'my-config', parents: ['https://example.com/x'], snapshot: h2 }));
+            assertEq(t, 'error');
+        },
+        httpsRejectedInSnapshot: () => {
+            const [t] = validate(revisionOf({ subject: 'my-config', snapshot: 'https://example.com/x' }));
+            assertEq(t, 'error');
+        },
+        httpsRejectedAsFallbackSubject: () => {
+            const [t] = validate(revisionOf({ subject: 'https://example.com/x' }));
+            assertEq(t, 'error');
+        },
+        // `archived` follows the presence-only `option(true)` idiom.
+        archivedAccepted: () => {
+            const [t] = validate(revisionOf({ archived: true }));
+            assertEq(t, 'ok');
+        },
+        // Wrong dialect tag: structural validation rejects it outright.
+        wrongDialectRejected: () => {
+            const [t] = validate({ dialect: 'vnd.fjs.other', subject: h1, parents: [] });
+            assertEq(t, 'error');
+        },
+        // Missing required fields: rejected.
+        missingSubjectRejected: () => {
+            const [t] = validate({ dialect, parents: [] });
+            assertEq(t, 'error');
+        },
+        // rtti structs are open: extra fields don't break validation — the
+        // additive forward-compatibility path the versioning rule relies on.
+        extraFieldsAccepted: () => {
+            const [t] = validate(revisionOf({ future: 'field' }));
+            assertEq(t, 'ok');
+        },
+    },
+    decodeText: {
+        validJson: () => {
+            const [t, v] = decodeText(JSON.stringify(revisionOf({ generation: 0 })));
+            assertEq(t, 'ok');
+            assertEq(v.subject, h1);
+        },
+        // Key order carries no meaning: detection parses the JSON and
+        // validates the parsed value, so `dialect` need not be first.
+        keyOrderIndependent: () => {
+            const text = `{"parents":[],"subject":"${h1}","dialect":"${dialect}"}`;
+            const [t] = decodeText(text);
+            assertEq(t, 'ok');
+        },
+        malformedJsonRejected: () => {
+            const [t] = decodeText('{not json');
+            assertEq(t, 'error');
+        },
+        // Ordinary JSON that isn't a revision at all falls through as an error
+        // here — `fs/media`'s composed detector is what falls back to the
+        // ordinary detector; this module only reports validity.
+        ordinaryJsonRejected: () => {
+            const [t] = decodeText('{"hello":"world"}');
+            assertEq(t, 'error');
+        },
+    },
+};

package/fs/{mime → media/type}/module.f.d.ts

@@ -32,12 +32,12 @@
  *
  * @module
  */
-import { type Vec } from '../types/bit_vec/module.f.ts';
-import type { Nullable } from '../types/nullable/module.f.ts';
-import { type Effect, type Operation } from '../effects/module.f.ts';
-import type { List } from '../effects/list/module.f.ts';
-import type { IoResult } from '../effects/node/module.f.ts';
-import { type Utf8State } from '../text/utf8/module.f.ts';
+import { type Vec } from '../../types/bit_vec/module.f.ts';
+import type { Nullable } from '../../types/nullable/module.f.ts';
+import { type Effect, type Operation } from '../../effects/module.f.ts';
+import type { List } from '../../effects/list/module.f.ts';
+import type { IoResult } from '../../effects/node/module.f.ts';
+import { type Utf8State } from '../../text/utf8/module.f.ts';
 /**
  * Detects the MIME type of `bytes` from its leading magic-byte signature.
  *