functionalscript 0.43.1 → 0.44.0

package/fjs/media/nix/proof.f.mjs

@@ -0,0 +1,181 @@
+import { assert, assertEq } from '../../asserts/module.f.mjs'
+import { toArray } from '../../types/list/module.f.mjs'
+import { nix, nixToString } from './module.f.mjs'
+/** @import { Expression } from './types.ts' */
+
+/** @type {(nodePackage: string, shellHook: boolean) => Expression} */
+const nodeFlake = (nodePackage, shellHook) => ['set',
+    ['=', ['inputs', 'nixpkgs', 'url'], 'github:NixOS/nixpkgs/<commit>'],
+    ['=', ['outputs'], ['lambda',
+        ['open-set-pattern', 'nixpkgs'],
+        ['set',
+            ['=', ['devShells', 'aarch64-linux', 'default'],
+                ['let', [
+                    ['=', ['pkgs'], ['apply',
+                        ['ref', 'import'],
+                        ['ref', 'nixpkgs'],
+                        ['set', ['=', ['system'], 'aarch64-linux']]
+                    ]]
+                ], ['apply',
+                    ['ref', 'pkgs', 'mkShell'],
+                    ['set',
+                        ['=', ['packages'], ['list', ['ref', 'pkgs', nodePackage]]],
+                        ...(shellHook ? [/** @type {const} */ ([
+                            '=',
+                            ['shellHook'],
+                            ['indented-string', `export NPM_CONFIG_PREFIX="$HOME/.npm-global"
+export PATH="$NPM_CONFIG_PREFIX/bin:$PATH"
+mkdir -p "$NPM_CONFIG_PREFIX"`]
+                        ])] : [])
+                    ]
+                ]]
+            ]
+        ]
+    ]]
+]
+
+const node24 = `{
+    inputs.nixpkgs.url = "github:NixOS/nixpkgs/<commit>";
+    outputs = { nixpkgs, ... }: {
+        devShells.aarch64-linux.default = let
+            pkgs = import nixpkgs {
+                system = "aarch64-linux";
+            };
+        in
+        pkgs.mkShell {
+            packages = [ pkgs.nodejs_24 ];
+        };
+    };
+}
+`
+
+const node22 = `{
+    inputs.nixpkgs.url = "github:NixOS/nixpkgs/<commit>";
+    outputs = { nixpkgs, ... }: {
+        devShells.aarch64-linux.default = let
+            pkgs = import nixpkgs {
+                system = "aarch64-linux";
+            };
+        in
+        pkgs.mkShell {
+            packages = [ pkgs.nodejs_22 ];
+            shellHook = ''
+                export NPM_CONFIG_PREFIX="$HOME/.npm-global"
+                export PATH="$NPM_CONFIG_PREFIX/bin:$PATH"
+                mkdir -p "$NPM_CONFIG_PREFIX"
+            '';
+        };
+    };
+}
+`
+
+export const proof = {
+    strings: () => {
+        assertEq(nixToString('"\\${\n\r\t'), `"\\"\\\\\\\${\\n\\r\\t"\n`)
+    },
+    reference: () => {
+        assertEq(nixToString(['ref', 'pkgs', 'a.b', 'or']), 'pkgs."a.b"."or"\n')
+        assertEq(nixToString(['ref', "a-b'9"]), "a-b'9\n")
+        assertEq(nixToString(['ref', '_AZ']), '_AZ\n')
+    },
+    emptySetAndList: () => {
+        assertEq(nixToString(['set']), '{}\n')
+        assertEq(nixToString(['list']), '[ ]\n')
+    },
+    multiReferenceList: () => {
+        assertEq(
+            nixToString(['list', ['ref', 'pkgs', 'nodejs_22'], ['ref', 'pkgs', 'nodejs_24']]),
+            '[ pkgs.nodejs_22 pkgs.nodejs_24 ]\n'
+        )
+    },
+    compatiblePaths: () => {
+        assertEq(
+            nixToString(['set', ['=', ['x', 'y'], 'a'], ['=', ['x', 'z'], 'b']]),
+            '{\n    x.y = "a";\n    x.z = "b";\n}\n'
+        )
+    },
+    chunks: () => {
+        const chunks = nix(['list', ['ref', 'pkgs', 'nodejs_24']])
+        assert(chunks !== undefined)
+        const [open, reference, close, extra] = toArray(chunks)
+        assertEq(open, '[ ')
+        assertEq(reference, 'pkgs.nodejs_24')
+        assertEq(close, ' ]')
+        assertEq(extra, undefined)
+    },
+    indentedStringEscaping: () => {
+        assertEq(nixToString(['indented-string', "a '' ${b}"]), "''\n    a ''' ''${b}\n''\n")
+        assertEq(
+            nixToString(['indented-string', '  a\n\t b\n  ']),
+            "''\n    ''\\ ''\\ a\n    ''\\t''\\ b\n    ''\\ ''\\ \n''\n"
+        )
+    },
+    emptyPattern: () => {
+        assertEq(nixToString(['lambda', ['open-set-pattern'], ['set']]), '{ ... }: {}\n')
+    },
+    node24: () => {
+        assertEq(nixToString(nodeFlake('nodejs_24', false)), node24)
+    },
+    node22: () => {
+        assertEq(nixToString(nodeFlake('nodejs_22', true)), node22)
+    },
+    invalid: {
+        reference: () => assertEq(nixToString(['ref', 'not valid']), undefined),
+        reservedReference: () => assertEq(nixToString(['ref', 'let']), undefined),
+        emptyReference: () => assertEq(nixToString(['ref', '']), undefined),
+        digitReference: () => assertEq(nixToString(['ref', '1abc']), undefined),
+        nonAsciiReference: () => assertEq(nixToString(['ref', 'é']), undefined),
+        pattern: () => assertEq(
+            nixToString(['lambda', ['open-set-pattern', 'if'], ['set']]),
+            undefined
+        ),
+        duplicatePattern: () => assertEq(
+            nixToString(['lambda', ['open-set-pattern', 'x', 'x'], ['set']]),
+            undefined
+        ),
+        duplicateBinding: () => assertEq(
+            nixToString(['set', ['=', ['x'], 'a'], ['=', ['x'], 'b']]),
+            undefined
+        ),
+        parentThenChildBinding: () => assertEq(
+            nixToString(['set', ['=', ['x'], 'a'], ['=', ['x', 'y'], 'b']]),
+            undefined
+        ),
+        childThenParentBinding: () => assertEq(
+            nixToString(['set', ['=', ['x', 'y'], 'a'], ['=', ['x'], 'b']]),
+            undefined
+        ),
+        duplicateLetBinding: () => assertEq(
+            nixToString(['let', [['=', ['x'], 'a'], ['=', ['x'], 'b']], ['ref', 'x']]),
+            undefined
+        ),
+        bindingValue: () => assertEq(
+            nixToString(['set', ['=', ['ok'], ['ref', 'bad name']]]),
+            undefined
+        ),
+        listItem: () => assertEq(
+            nixToString(['list', ['ref', 'valid'], ['ref', 'bad name']]),
+            undefined
+        ),
+        applicationFunction: () => assertEq(
+            nixToString(['apply', ['ref', 'with']]),
+            undefined
+        ),
+        applicationArgument: () => assertEq(
+            nixToString(['apply', ['ref', 'f'], ['ref', 'bad name']]),
+            undefined
+        ),
+        lambdaBody: () => assertEq(
+            nixToString(['lambda', ['open-set-pattern', 'good'], ['ref', 'bad name']]),
+            undefined
+        ),
+        letBinding: () => assertEq(
+            nixToString(['let', [['=', ['x'], ['ref', 'bad name']]], ['ref', 'x']]),
+            undefined
+        ),
+        letBody: () => assertEq(
+            nixToString(['let', [], ['ref', 'bad name']]),
+            undefined
+        ),
+    }
+}

package/fjs/media/nix/types.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Type-level API for the Nix expression eDSL.
+ *
+ * @module
+ */
+type _Identifier = string;
+type _AttributeName = string;
+export type _AttributePath = readonly [_AttributeName, ..._AttributeName[]];
+export type _Binding = readonly ['=', _AttributePath, Expression];
+export type _Reference = readonly ['ref', _Identifier, ..._AttributeName[]];
+export type _AttributeSet = readonly ['set', ..._Binding[]];
+export type _NixList = readonly ['list', ..._Reference[]];
+type _ApplicationArgument = _Reference | _AttributeSet;
+export type _Application = readonly ['apply', _Reference, ..._ApplicationArgument[]];
+export type _OpenSetPattern = readonly ['open-set-pattern', ..._Identifier[]];
+export type _Lambda = readonly ['lambda', _OpenSetPattern, Expression];
+export type _Let = readonly ['let', readonly _Binding[], Expression];
+export type _IndentedString = readonly ['indented-string', string];
+/** The Nix syntax supported by the serializer. */
+export type Expression = string | _Reference | _AttributeSet | _NixList | _Application | _Lambda | _Let | _IndentedString;
+export type _Chunks = readonly string[];
+export {};

package/fjs/media/nix/types.js

@@ -0,0 +1,6 @@
+/**
+ * Type-level API for the Nix expression eDSL.
+ *
+ * @module
+ */
+export {};

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

@@ -0,0 +1,19 @@
+import type { DialectEntry } from './types.ts';
+export declare const proof: {
+    validRevision: () => void;
+    keyOrderIndependent: () => void;
+    invalidRevisionFallsThrough: () => void;
+    nonHashSnapshotFallsThrough: () => void;
+    secondDialect: () => void;
+    nonVndDialectName: () => void;
+    firstMatchWins: () => void;
+    noDialects: () => void;
+    ordinaryJsonFallsThrough: () => void;
+    plainTextFallsThrough: () => void;
+    binaryFallsThrough: () => void;
+    largeNonJsonWithinBound: () => void;
+    throw: {
+        thunkDialectMember: () => DialectEntry;
+        noDialectMember: () => DialectEntry;
+    };
+};

package/fjs/media/proof.f.mjs

@@ -0,0 +1,159 @@
+/**
+ * @import { Vec } from '../types/bit_vec/types.ts'
+ * @import { DialectEntry } from './types.ts'
+ */
+import { assertEq } from '../asserts/module.f.mjs'
+import { msb, u8ListToVec, repeat, vec8 } from '../types/bit_vec/module.f.mjs'
+import { detect, dialectEntry } from './module.f.mjs'
+import { dialect, revisionDialect } from './revision/module.f.mjs'
+import { number, string } from '../types/rtti/module.f.mjs'
+
+// All test strings here are ASCII, so char code === UTF-8 byte value.
+/** @type {(s: string) => Vec} */
+const utf8Bytes = s => u8ListToVec(msb)([...s].map(c => c.charCodeAt(0)))
+
+const revisionJson = `{"dialect":"${dialect}","subject":"8","parents":[],"snapshot":"8","generation":0}`
+
+/** @type {readonly DialectEntry[]} */
+const dialects = [revisionDialect]
+
+const detectRevision = detect(dialects)
+
+/**
+ * A second dialect following the same `vnd.fjs.<name>` convention, registered
+ * with no refinement: structure alone decides the match.
+ */
+const noteSchema = /** @type {const} */ ({
+    dialect: 'vnd.fjs.note',
+    text: string,
+})
+
+/** @type {DialectEntry} */
+const noteDialect = dialectEntry(noteSchema)
+
+/** A dialect name outside `vnd.fjs.*` — registerable, and detected as itself. */
+const gadgetSchema = /** @type {const} */ ({
+    dialect: 'application.gadget',
+    size: number,
+})
+
+/** @type {DialectEntry} */
+const gadgetDialect = dialectEntry(gadgetSchema)
+
+/**
+ * `DialectEntry` is deliberately not opaque, so overlapping entries — which a
+ * self-discriminating schema can't produce on its own — can be stated directly.
+ * @type {(name: string) => DialectEntry}
+ */
+const anyEntry = name => ({ dialect: name, match: () => true })
+
+export const proof = {
+    // A valid revision blob is recognized and reported under its derived media type.
+    validRevision: () => {
+        const m = detectRevision(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 = detectRevision(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 = detectRevision(utf8Bytes(text))
+        assertEq(m.type, 'text')
+        assertEq(m.mime_type, 'text/plain')
+    },
+
+    // The `extraValidate` path: structurally a revision, but `snapshot` is not
+    // a cbase32 hash, so `revisionDialect`'s refinement rejects it and the
+    // verdict stays `text/plain` — exactly what `decodeText` would say.
+    nonHashSnapshotFallsThrough: () => {
+        const text = `{"dialect":"${dialect}","subject":"8","parents":[],"snapshot":"not a hash","generation":0}`
+        const m = detectRevision(utf8Bytes(text))
+        assertEq(m.type, 'text')
+        assertEq(m.mime_type, 'text/plain')
+    },
+
+    // A second dialect, registered by the caller, is recognized alongside the
+    // first — and an entry with no refinement matches on structure alone.
+    secondDialect: () => {
+        const d = detect([revisionDialect, noteDialect])
+        assertEq(d(utf8Bytes('{"dialect":"vnd.fjs.note","text":"hi"}')).mime_type, 'application/vnd.fjs.note+json')
+        assertEq(d(utf8Bytes(revisionJson)).mime_type, 'application/vnd.fjs.revision+json')
+        // Same tag, wrong shape: no entry matches.
+        assertEq(d(utf8Bytes('{"dialect":"vnd.fjs.note","text":42}')).mime_type, 'text/plain')
+    },
+
+    // The name is neither grammar-checked nor allowlisted: a dialect outside
+    // `vnd.fjs.*` yields its own derived media type.
+    nonVndDialectName: () => {
+        const m = detect([gadgetDialect])(utf8Bytes('{"dialect":"application.gadget","size":3}'))
+        assertEq(m.mime_type, 'application/application.gadget+json')
+    },
+
+    // Entries are tried in order and the first match wins.
+    firstMatchWins: () => {
+        const bytes = utf8Bytes('{}')
+        assertEq(detect([anyEntry('vnd.fjs.a'), anyEntry('vnd.fjs.b')])(bytes).mime_type, 'application/vnd.fjs.a+json')
+        assertEq(detect([anyEntry('vnd.fjs.b'), anyEntry('vnd.fjs.a')])(bytes).mime_type, 'application/vnd.fjs.b+json')
+    },
+
+    // An empty registry recognizes nothing; every blob keeps the
+    // `fjs/media/type` verdict.
+    noDialects: () => {
+        const m = detect([])(utf8Bytes(revisionJson))
+        assertEq(m.type, 'text')
+        assertEq(m.mime_type, 'text/plain')
+    },
+
+    // Ordinary JSON with no `dialect` field at all falls through unchanged.
+    ordinaryJsonFallsThrough: () => {
+        const m = detectRevision(utf8Bytes('{"hello":"world"}'))
+        assertEq(m.type, 'text')
+        assertEq(m.mime_type, 'text/plain')
+    },
+
+    // Plain (non-JSON) text is unaffected: the parse fails and the
+    // `fjs/media/type` verdict stands.
+    plainTextFallsThrough: () => {
+        const m = detectRevision(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 = detectRevision(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(1_000n)(vec8(0x61n)) // 1,000 bytes of 'a'
+        const m = detectRevision(a)
+        assertEq(m.type, 'text')
+        assertEq(m.mime_type, 'text/plain')
+    },
+
+    throw: {
+        // The `dialect` member must be a direct string const. A thunk-form one
+        // is a valid rtti schema but is not registerable, and `dialectEntry`
+        // says so at registration rather than per blob.
+        thunkDialectMember: () => dialectEntry({ dialect: string }),
+
+        // A schema with no `dialect` member at all is likewise refused.
+        noDialectMember: () => dialectEntry({ text: string }),
+    },
+}

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

@@ -0,0 +1,119 @@
+/**
+ * `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 { Unknown } from '../json/types.ts'
+ * @import { Result } from '../../types/result/types.ts'
+ * @import { DialectEntry } from '../types.ts'
+ * @import { Revision, RevisionError } from './types.ts'
+ */
+import type { Unknown } from '../json/types.ts';
+import type { Result } from '../../types/result/types.ts';
+import type { DialectEntry } from '../types.ts';
+import type { Revision, RevisionError } from './types.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/types.ts")._Type0<"string">;
+/** Structural schema for a Stage 1 flat lock map. */
+export declare const _lock: import("../../types/rtti/types.ts").Type1<"record", import("../../types/rtti/types.ts")._Type0<"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/types.ts")._Type0<"string">;
+    readonly parents: import("../../types/rtti/types.ts").Type1<"array", import("../../types/rtti/types.ts")._Type0<"string">>;
+    readonly snapshot: import("../../types/rtti/types.ts")._Type0<"string">;
+    readonly generation: import("../../types/rtti/types.ts")._Type0<"number">;
+    readonly archived: import("../../types/rtti/types.ts").Or<readonly [true, undefined]>;
+    readonly lock: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts").Type1<"record", import("../../types/rtti/types.ts")._Type0<"string">>, undefined]>;
+};
+/** Serializes a revision canonically, recursively sorting every object's property names.
+ * @type {(revision: Revision) => string}
+ */
+export declare const encodeText: (revision: Revision) => string;
+/** True when `s` decodes as a cbase32 CAS hash (rejects `https://` and any other non-cbase32 string).
+ * @type {(s: string) => boolean}
+ */
+export declare const isHash: (s: string) => boolean;
+/**
+ * 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.
+ *
+ * @type {(r: Revision) => Result<Revision, string>}
+ */
+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.
+ *
+ * @type {(value: Unknown) => Result<Revision, RevisionError>}
+ */
+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.
+ *
+ * @type {(text: string) => Result<Revision, RevisionError>}
+ */
+export declare const decodeText: (text: string) => Result<Revision, RevisionError>;
+/**
+ * This dialect as a registry entry for `fjs/media`'s `detect`. It carries the
+ * semantic checks too, so a blob is detected as `vnd.fjs.revision` exactly when
+ * {@link decodeText} would accept it — a structurally valid revision whose
+ * `snapshot` is not a cbase32 hash is not one.
+ *
+ * @type {DialectEntry}
+ */
+export declare const revisionDialect: DialectEntry;

package/fjs/media/revision/module.f.mjs

@@ -0,0 +1,166 @@
+/**
+ * `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 { Unknown } from '../json/types.ts'
+ * @import { Result } from '../../types/result/types.ts'
+ * @import { DialectEntry } from '../types.ts'
+ * @import { Revision, RevisionError } from './types.ts'
+ */
+
+import { array, number, option, record, string } from '../../types/rtti/module.f.mjs'
+import { validate as rttiValidate } from '../../types/rtti/validate/module.f.mjs'
+import { parse as parseJson } from '../json/module.f.mjs'
+import { cBase32ToVec } from '../../basen/cbase32/module.f.mjs'
+import { error, ok } from '../../types/result/module.f.mjs'
+import { dialectEntry } from '../module.f.mjs'
+import { definedEntries, sort } from '../../types/object/module.f.mjs'
+import { stringify } from '../json/module.f.mjs'
+
+/**
+ * Format tag: names the dialect of this BLOB. The media type it is served
+ * with is derived mechanically: `application/` + `dialect` + `+json`.
+ */
+export const dialect = /** @type {const} */ ('vnd.fjs.revision')
+
+/** The media type derived from {@link dialect}: `application/vnd.fjs.revision+json`. */
+export const mediaType = /** @type {const} */ (`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
+
+/** Structural schema for a Stage 1 flat lock map. */
+export const _lock = record(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 = /** @type {const} */ ({
+    dialect,
+    subject: string,
+    parents: array(hash),
+    snapshot: hash,
+    generation: number,
+    archived: option(true),
+    lock: option(_lock),
+})
+
+/** Serializes a revision canonically, recursively sorting every object's property names.
+ * @type {(revision: Revision) => string}
+ */
+export const encodeText = stringify(sort)
+
+/** Structural-only validator: checks the shape, not the hash / generation semantics. */
+const validateShape = rttiValidate(revisionSchema)
+
+/** True when `s` decodes as a cbase32 CAS hash (rejects `https://` and any other non-cbase32 string).
+ * @type {(s: string) => boolean}
+ */
+export const isHash = s => cBase32ToVec(s) !== null
+
+/**
+ * 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.
+ *
+ * @type {(r: Revision) => Result<Revision, string>}
+ */
+export const checkReferences = r => {
+    for (const p of r.parents) {
+        if (!isHash(p)) { return error(`parent is not a valid hash: ${p}`) }
+    }
+    if (!isHash(r.snapshot)) { return error(`snapshot is not a valid hash: ${r.snapshot}`) }
+    for (const [subject, snapshot] of definedEntries(r.lock ?? {})) {
+        if (!isHash(snapshot)) { return error(`lock value for ${subject} is not a valid hash: ${snapshot}`) }
+    }
+    if (!Number.isSafeInteger(r.generation) || r.generation < 0) {
+        return error(`generation must be a non-negative safe integer: ${r.generation}`)
+    }
+    return ok(r)
+}
+
+/**
+ * Validates an already-parsed JSON value as a `revision` BLOB: structural
+ * (rtti) validation followed by the hash / generation semantic checks.
+ *
+ * @type {(value: Unknown) => Result<Revision, RevisionError>}
+ */
+export const validate = value => {
+    const [t, v] = validateShape(value)
+    if (t === 'error') { return error(v) }
+    return checkReferences(v)
+}
+
+/**
+ * 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.
+ *
+ * @type {(text: string) => Result<Revision, RevisionError>}
+ */
+export const decodeText = text => {
+    const [t, v] = parseJson(text)
+    if (t === 'error') { return error(v) }
+    return validate(v)
+}
+
+/** {@link checkReferences} as the `boolean` refinement a {@link DialectEntry} takes.
+ * @type {(r: Revision) => boolean}
+ */
+const isValidRevision = r => {
+    const [tag] = checkReferences(r)
+    return tag === 'ok'
+}
+
+/**
+ * This dialect as a registry entry for `fjs/media`'s `detect`. It carries the
+ * semantic checks too, so a blob is detected as `vnd.fjs.revision` exactly when
+ * {@link decodeText} would accept it — a structurally valid revision whose
+ * `snapshot` is not a cbase32 hash is not one.
+ *
+ * @type {DialectEntry}
+ */
+export const revisionDialect = dialectEntry(revisionSchema, isValidRevision)