functionalscript 0.43.1 → 0.45.0

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/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,124 @@
+/**
+ * `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.
+ *
+ * `RevisionError` is the union of the two stages' own error types, so each
+ * failure reaches the caller as it was raised — `ValidationError` from the
+ * schema, `string` from {@link checkReferences} — which is exactly what
+ * `okThen` produces here.
+ *
+ * @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,163 @@
+/**
+ * `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, okThen } 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.
+ *
+ * `RevisionError` is the union of the two stages' own error types, so each
+ * failure reaches the caller as it was raised — `ValidationError` from the
+ * schema, `string` from {@link checkReferences} — which is exactly what
+ * `okThen` produces here.
+ *
+ * @type {(value: Unknown) => Result<Revision, RevisionError>}
+ */
+export const validate = value => okThen(checkReferences)(validateShape(value))
+
+/**
+ * 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 => okThen(validate)(parseJson(text))
+
+/** {@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)

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

@@ -0,0 +1,46 @@
+/**
+ * @import { Object as JsonObject } from '../json/types.ts'
+ * @import { LockMap } from './types.ts'
+ */
+export declare const proof: {
+    dialectAndMediaType: () => void;
+    isHash: {
+        validHash: () => void;
+        httpsRejected: () => void;
+        arbitraryStringRejected: () => void;
+    };
+    validate: {
+        allFieldsPresent: () => void;
+        nonHashSubjectAccepted: () => void;
+        multiParentAccepted: () => void;
+        missingSnapshotRejected: () => void;
+        nonHashSnapshotRejected: () => void;
+        missingGenerationRejected: () => void;
+        nonIntegerGenerationRejected: () => void;
+        negativeGenerationRejected: () => void;
+        unsafeIntegerGenerationRejected: () => void;
+        positiveGenerationAccepted: () => void;
+        httpsRejectedInParents: () => void;
+        archivedAccepted: () => void;
+        lockAbsentAccepted: () => void;
+        emptyLockAccepted: () => void;
+        validLockAccepted: () => void;
+        malformedLockRejected: () => void;
+        invalidHashLockRejected: () => void;
+        aliasHashLockAccepted: () => void;
+        wrongDialectRejected: () => void;
+        missingSubjectRejected: () => void;
+        extraFieldsAccepted: () => void;
+    };
+    decodeText: {
+        validJson: () => void;
+        keyOrderIndependent: () => void;
+        malformedJsonRejected: () => void;
+        ordinaryJsonRejected: () => void;
+    };
+    encodeText: {
+        recursivelySortsObjectsLexicographically: () => void;
+        preservesArrayOrder: () => void;
+        parsedEquivalentSourcesConverge: () => void;
+    };
+};