functionalscript 0.43.0 → 0.44.0

package/fjs/media/nix/module.f.js

@@ -1,166 +0,0 @@
-/**
- * A minimal, checked eDSL for constructing and serializing Nix expressions.
- *
- * The tree deliberately models syntax rather than evaluated Nix values. String
- * expressions are escaped double-quoted strings; the other supported forms are
- * represented by tagged tuples.
- *
- * @module
- */
-import { toArray } from '../../types/list/module.f.js';
-import { concat } from '../../types/string/module.f.js';
-import { includes } from '../../types/array/module.f.js';
-import { digitRange, latinCapitalLetterRange, latinSmallLetterRange, range, } from '../../text/ascii/module.f.js';
-import { fromRange, get, merge } from '../../types/range_set/module.f.js';
-const reservedWords = [
-    'assert',
-    'else',
-    'if',
-    'in',
-    'inherit',
-    'let',
-    'or',
-    'rec',
-    'then',
-    'with',
-];
-const isReservedWord = includes(reservedWords);
-const letters = merge(fromRange(latinCapitalLetterRange))(fromRange(latinSmallLetterRange));
-const identifierInitial = toArray(merge(letters)(fromRange(range('_'))));
-const getIdentifierInitial = get(identifierInitial);
-const isIdentifierInitial = (character) => getIdentifierInitial(character.charCodeAt(0));
-const identifierTrailing = toArray(merge(merge(identifierInitial)(fromRange(digitRange)))(merge(fromRange(range("'")))(fromRange(range('-')))));
-const getIdentifierTrailing = get(identifierTrailing);
-const isIdentifierTrailing = (character) => getIdentifierTrailing(character.charCodeAt(0));
-const isIdentifier = (value) => {
-    const [initial, ...trailing] = value;
-    return initial !== undefined
-        && isIdentifierInitial(initial)
-        && trailing.every(isIdentifierTrailing)
-        && !isReservedWord(value);
-};
-const indent = (level) => '    '.repeat(level);
-const escapeQuoted = (value) => value
-    .replaceAll('\\', '\\\\')
-    .replaceAll('"', '\\"')
-    .replaceAll('${', '\\${')
-    .replaceAll('\n', '\\n')
-    .replaceAll('\r', '\\r')
-    .replaceAll('\t', '\\t');
-const quoted = (value) => `"${escapeQuoted(value)}"`;
-const attributeName = (value) => isIdentifier(value) ? value : quoted(value);
-const attributePath = (path) => path.map(attributeName).join('.');
-const escapeIndented = (value) => value
-    .replaceAll("''", "'''")
-    .replaceAll('${', "''${");
-const protectLeadingWhitespace = (line) => {
-    const contentStart = [...line, 'x'].findIndex(character => character !== ' ' && character !== '\t');
-    const leading = line.slice(0, contentStart)
-        .replaceAll(' ', "''\\ ")
-        .replaceAll('\t', "''\\t");
-    return `${leading}${line.slice(contentStart)}`;
-};
-const serializeReference = ([, name, ...selection]) => isIdentifier(name)
-    ? [name, ...selection.map(attributeName)].join('.')
-    : undefined;
-const serializeReferenceChunks = (reference) => {
-    const serialized = serializeReference(reference);
-    return serialized === undefined ? undefined : [serialized];
-};
-const serializePattern = ([, ...names]) => names.every((name, index) => isIdentifier(name) && names.indexOf(name) === index)
-    ? `{ ${[...names, '...'].join(', ')} }`
-    : undefined;
-const joinChunks = (chunks, separator) => chunks.flatMap((chunk, index) => index === 0 ? chunk : [separator, ...chunk]);
-const isPathPrefix = (prefix, path) => prefix.length <= path.length
-    && prefix.every((name, index) => name === path[index]);
-const pathsConflict = (a, b) => isPathPrefix(a, b) || isPathPrefix(b, a);
-const bindingsCompatible = (bindings) => bindings.every(([, path], index) => bindings.slice(0, index).every(([, previous]) => !pathsConflict(path, previous)));
-const serializeBindings = (bindings, level) => {
-    if (!bindingsCompatible(bindings)) {
-        return undefined;
-    }
-    const serialized = bindings.map(([, path, value]) => {
-        const expression = serialize(value, level);
-        return expression === undefined
-            ? undefined
-            : [indent(level), attributePath(path), ' = ', ...expression, ';'];
-    });
-    const defined = serialized.flatMap(value => value === undefined ? [] : [value]);
-    return defined.length !== serialized.length
-        ? undefined
-        : joinChunks(defined, '\n');
-};
-const serializeSet = ([, ...bindings], level) => {
-    if (bindings.length === 0) {
-        return ['{}'];
-    }
-    const body = serializeBindings(bindings, level + 1);
-    return body === undefined ? undefined : ['{\n', ...body, '\n', indent(level), '}'];
-};
-const serializeList = ([, ...references]) => {
-    const items = references.map(serializeReference);
-    const definedItems = items.flatMap(item => item === undefined ? [] : [item]);
-    return items.includes(undefined)
-        ? undefined
-        : items.length === 0
-            ? ['[ ]']
-            : ['[ ', ...definedItems.flatMap((item, index) => index === 0 ? [item] : [' ', item]), ' ]'];
-};
-const serializeApplication = ([, fn, ...args], level) => {
-    const serializedFn = serializeReference(fn);
-    const serializedArgs = args.map(argument => argument[0] === 'ref'
-        ? serializeReferenceChunks(argument)
-        : serializeSet(argument, level));
-    const definedArgs = serializedArgs.flatMap(argument => argument === undefined ? [] : [argument]);
-    return serializedFn === undefined || definedArgs.length !== serializedArgs.length
-        ? undefined
-        : [serializedFn, ...definedArgs.flatMap(argument => [' ', ...argument])];
-};
-const serializeLambda = ([, pattern, body], level) => {
-    const serializedPattern = serializePattern(pattern);
-    const serializedBody = serialize(body, level);
-    return serializedPattern === undefined || serializedBody === undefined
-        ? undefined
-        : [serializedPattern, ': ', ...serializedBody];
-};
-const serializeLet = ([, bindings, body], level) => {
-    const serializedBindings = serializeBindings(bindings, level + 1);
-    const serializedBody = serialize(body, level);
-    return serializedBindings === undefined || serializedBody === undefined
-        ? undefined
-        : ['let\n', ...serializedBindings, '\n', indent(level), 'in\n', indent(level), ...serializedBody];
-};
-const serialize = (expression, level) => {
-    if (typeof expression === 'string') {
-        return [quoted(expression)];
-    }
-    switch (expression[0]) {
-        case 'ref': {
-            return serializeReferenceChunks(expression);
-        }
-        case 'set': return serializeSet(expression, level);
-        case 'list': return serializeList(expression);
-        case 'apply': return serializeApplication(expression, level);
-        case 'lambda': return serializeLambda(expression, level);
-        case 'let': return serializeLet(expression, level);
-        case 'indented-string': {
-            const [, value] = expression;
-            const contentIndent = indent(level + 1);
-            const content = escapeIndented(value)
-                .split('\n')
-                .map(protectLeadingWhitespace)
-                .map(line => `${contentIndent}${line}`)
-                .join('\n');
-            return ["''\n", content, '\n', indent(level), "''"];
-        }
-    }
-};
-/** Serializes an expression into composable chunks, or rejects an invalid identifier. */
-export const nix = (expression) => {
-    return serialize(expression, 0);
-};
-/** Serializes an expression with exactly one trailing newline on success. */
-export const nixToString = (expression) => {
-    const chunks = nix(expression);
-    return chunks === undefined ? undefined : `${concat(chunks)}\n`;
-};

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

@@ -1,127 +0,0 @@
-import { assert, assertEq } from '../../asserts/module.f.js';
-import { toArray } from '../../types/list/module.f.js';
-import { nix, nixToString } from './module.f.js';
-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 ? [[
-                                        '=',
-                                        ['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/proof.f.d.ts

@@ -1,19 +0,0 @@
-import { type DialectEntry } from './module.f.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.js

@@ -1,127 +0,0 @@
-import { assertEq } from '../asserts/module.f.js';
-import { msb, u8ListToVec, repeat, vec8 } from '../types/bit_vec/module.f.js';
-import { detect, dialectEntry } from './module.f.js';
-import { dialect, revisionDialect } from './revision/module.f.js';
-import { number, string } from '../types/rtti/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}`;
-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 = {
-    dialect: 'vnd.fjs.note',
-    text: string,
-};
-const noteDialect = dialectEntry(noteSchema);
-/** A dialect name outside `vnd.fjs.*` — registerable, and detected as itself. */
-const gadgetSchema = {
-    dialect: 'application.gadget',
-    size: number,
-};
-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.
- */
-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(1000n)(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.ts

@@ -1,86 +0,0 @@
-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';
-import { type DialectEntry } from '../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>;
-/**
- * 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.
- */
-export declare const revisionDialect: DialectEntry;

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

@@ -1,131 +0,0 @@
-/**
- * `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 parseJson } from '../json/module.f.js';
-import { cBase32ToVec } from '../../basen/cbase32/module.f.js';
-import { error, ok } from '../../types/result/module.f.js';
-import { dialectEntry } from '../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: hash,
-    generation: number,
-    archived: option(true),
-};
-/** 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). */
-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.
- */
-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}`);
-    }
-    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.
- */
-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.
- */
-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. */
-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.
- */
-export const revisionDialect = dialectEntry(revisionSchema, isValidRevision);