functionalscript 0.43.1 → 0.44.0

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

@@ -1,143 +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, record, 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';
-import { definedEntries, sort } from '../../types/object/module.f.js';
-import { stringify } from '../json/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;
-/** Structural schema for a Stage 1 flat lock map. */
-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 = {
-    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. */
-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). */
-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}`);
-    }
-    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.
- */
-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);

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

@@ -1,190 +0,0 @@
-import { assert, assertEq } from '../../asserts/module.f.js';
-import { dialect, mediaType, isHash, validate, decodeText, encodeText } from './module.f.js';
-// Valid cbase32 hashes (round-tripped in fjs/basen/cbase32/proof.f.ts): single
-// cbase32 symbols, cheap to write inline here.
-const h1 = '8';
-const h2 = 'r';
-// `I` is accepted as an alias spelling of canonical cBase32 `1`.
-const alias = 'I';
-const _lockMapAllowsMissingSubjects = {};
-// A shape-valid revision: every required field present (`snapshot` and
-// `generation` included), with `extra` overriding or adding fields per test.
-const revisionOf = (extra) => ({
-    dialect,
-    subject: h1,
-    parents: [],
-    snapshot: h2,
-    generation: 0,
-    ...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: {
-        // A fully explicit revision validates.
-        allFieldsPresent: () => {
-            const [t] = validate(revisionOf({}));
-            assertEq(t, 'ok');
-        },
-        // `subject` is a pure identity string, never a snapshot reference: a
-        // zero-parent revision whose `subject` is not a hash is now valid,
-        // because `snapshot` is always stated explicitly.
-        nonHashSubjectAccepted: () => {
-            const r = validate(revisionOf({ subject: 'my-config' }));
-            assert(r[0] === 'ok', ['expected ok', r]);
-            assertEq(r[1].subject, 'my-config');
-        },
-        // A merge revision (more than one parent) is valid like any other —
-        // there is no "multiple parents without snapshot" case left, because
-        // `snapshot` is required.
-        multiParentAccepted: () => {
-            const r = validate(revisionOf({ subject: 'my-config', parents: [h1, h2], snapshot: h2 }));
-            assert(r[0] === 'ok', ['expected ok', r]);
-            assertEq(r[1].snapshot, h2);
-        },
-        // `snapshot` is required: absent is a shape error.
-        missingSnapshotRejected: () => {
-            const [t] = validate({ dialect, subject: h1, parents: [], generation: 0 });
-            assertEq(t, 'error');
-        },
-        // `snapshot` must decode as a hash — `https://` bridge URLs rejected.
-        nonHashSnapshotRejected: () => {
-            const [t] = validate(revisionOf({ snapshot: 'https://example.com/x' }));
-            assertEq(t, 'error');
-        },
-        // `generation` is required: absent is a shape error.
-        missingGenerationRejected: () => {
-            const [t] = validate({ dialect, subject: h1, parents: [], snapshot: h2 });
-            assertEq(t, 'error');
-        },
-        // `generation` must be an integer: a fractional value is rejected.
-        nonIntegerGenerationRejected: () => {
-            const [t] = validate(revisionOf({ generation: 1.5 }));
-            assertEq(t, 'error');
-        },
-        // `generation` must be non-negative.
-        negativeGenerationRejected: () => {
-            const [t] = validate(revisionOf({ generation: -1 }));
-            assertEq(t, 'error');
-        },
-        // `generation` must be a *safe* integer: at `2 ** 53` and above the
-        // value is no longer uniquely representable, so `1 + max(...)` could
-        // fail to advance — such a blob is rejected (`Number.isInteger` would
-        // accept it; `Number.isSafeInteger` does not).
-        unsafeIntegerGenerationRejected: () => {
-            const [t] = validate(revisionOf({ generation: 2 ** 53 }));
-            assertEq(t, 'error');
-        },
-        // A positive integer generation is accepted.
-        positiveGenerationAccepted: () => {
-            const r = validate(revisionOf({ parents: [h1], generation: 3 }));
-            assert(r[0] === 'ok', ['expected ok', r]);
-            assertEq(r[1].generation, 3);
-        },
-        // `https://` bridge URLs are rejected wherever a hash is required.
-        httpsRejectedInParents: () => {
-            const [t] = validate(revisionOf({ parents: ['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');
-        },
-        lockAbsentAccepted: () => {
-            const r = validate(revisionOf({}));
-            assert(r[0] === 'ok', ['expected ok', r]);
-            assertEq(r[1].lock, undefined);
-        },
-        emptyLockAccepted: () => {
-            const r = validate(revisionOf({ lock: {} }));
-            assert(r[0] === 'ok', ['expected ok', r]);
-            assertEq(Object.keys(r[1].lock ?? {}).length, 0);
-        },
-        validLockAccepted: () => {
-            const [t] = validate(revisionOf({ lock: { dependency: h1 } }));
-            assertEq(t, 'ok');
-        },
-        malformedLockRejected: () => {
-            const [t] = validate(revisionOf({ lock: { dependency: 1 } }));
-            assertEq(t, 'error');
-        },
-        invalidHashLockRejected: () => {
-            const [t] = validate(revisionOf({ lock: { dependency: 'https://example.com/x' } }));
-            assertEq(t, 'error');
-        },
-        aliasHashLockAccepted: () => {
-            const [t] = validate(revisionOf({ lock: { dependency: alias } }));
-            assertEq(t, 'ok');
-        },
-        // Wrong dialect tag: structural validation rejects it outright.
-        wrongDialectRejected: () => {
-            const [t] = validate({ dialect: 'vnd.fjs.other', subject: h1, parents: [], snapshot: h2, generation: 0 });
-            assertEq(t, 'error');
-        },
-        // Missing required fields: rejected.
-        missingSubjectRejected: () => {
-            const [t] = validate({ dialect, parents: [], snapshot: h2, generation: 0 });
-            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 r = decodeText(JSON.stringify(revisionOf({})));
-            assert(r[0] === 'ok', ['expected ok', r]);
-            assertEq(r[1].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 = `{"generation":0,"snapshot":"${h2}","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 — `fjs/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');
-        },
-    },
-    encodeText: {
-        recursivelySortsObjectsLexicographically: () => {
-            const revision = revisionOf({ lock: { '2': h2, '10': h1 } });
-            const decoded = validate(revision);
-            assert(decoded[0] === 'ok', ['expected ok', decoded]);
-            assertEq(encodeText(decoded[1]), `{"dialect":"${dialect}","generation":0,"lock":{"10":"${h1}","2":"${h2}"},"parents":[],"snapshot":"${h2}","subject":"${h1}"}`);
-        },
-        preservesArrayOrder: () => {
-            const decoded = validate(revisionOf({ parents: [h2, h1] }));
-            assert(decoded[0] === 'ok', ['expected ok', decoded]);
-            assert(encodeText(decoded[1]).includes(`"parents":["${h2}","${h1}"]`));
-        },
-        parsedEquivalentSourcesConverge: () => {
-            const a = decodeText(` { "subject":"${h1}", "snapshot":"${h2}", "parents":[], "generation":0, "dialect":"${dialect}" } `);
-            const b = decodeText(`{"dialect":"${dialect}","generation":0,"parents":[],"snapshot":"${h2}","subject":"${h1}"}`);
-            assert(a[0] === 'ok', ['expected ok', a]);
-            assert(b[0] === 'ok', ['expected ok', b]);
-            assertEq(encodeText(a[1]), encodeText(b[1]));
-        },
-    },
-};
-void _lockMapAllowsMissingSubjects;

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

@@ -1,135 +0,0 @@
-/**
- * Magic-byte MIME type detection.
- *
- * `detect` is a pure table lookup over the leading bytes of a `Vec`: it returns a
- * MIME type string for the container formats whose signatures it knows, or `null`
- * for anything else — text, unknown binary, or a `Vec` too short to match.
- *
- * Beside it, `detectStream` is the **streaming counterpart**: a byte-accepting
- * state machine (length × magic-byte eliminator × UTF-8 validity DFA) that derives
- * `{ length, mime_type, type }` by folding a CAS read stream in O(1) space, without
- * ever buffering the blob into a single `maxLength`-bounded `Vec`. See the README
- * for the factored design.
- *
- * The CAS store is type-agnostic and keeps raw bytes only, so type is never
- * stored; it is recovered on read by sniffing the content. Callers decide what
- * `null` means: the CAS MCP adapter falls back to a plain text result.
- *
- * ## Recognised signatures
- *
- * | MIME type         | Leading bytes                          |
- * |-------------------|----------------------------------------|
- * | `image/png`       | `89 50 4E 47 0D 0A 1A 0A`              |
- * | `image/jpeg`      | `FF D8 FF`                             |
- * | `image/gif`       | `47 49 46 38 37 61` / `…39 61` (`"GIF87a"` / `"GIF89a"`) |
- * | `image/webp`      | `52 49 46 46 .. .. .. .. 57 45 42 50` (`"RIFF"…"WEBP"`) |
- * | `application/pdf` | `25 50 44 46 2D` (`"%PDF-"`)           |
- * | `application/zip` | `50 4B 03 04` / `05 06` / `07 08` (`"PK"` entry, empty, or spanned) |
- *
- * WebP is the one signature with a gap: the four-byte little-endian file size
- * sits between the `RIFF` and `WEBP` markers, so it is matched as a prefix plus
- * a second marker at byte offset 8 rather than a single contiguous run.
- *
- * @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';
-/**
- * Detects the MIME type of `bytes` from its leading magic-byte signature.
- *
- * @returns the MIME type string for a recognized format, or `null` when the
- *   leading bytes match no known signature (including any `Vec` shorter than
- *   the signature it might otherwise match).
- */
-export declare const detect: (bytes: Vec) => Nullable<string>;
-/**
- * A magic-byte signature as a byte pattern. `null` entries are wildcards (the
- * four little-endian size bytes of WebP, between its `RIFF` and `WEBP` markers).
- */
-type Signature = {
-    readonly pattern: readonly Nullable<number>[];
-    readonly mime: string;
-};
-/**
- * `A_magic`: signature elimination. `scan` holds the byte offset and the still-viable
- * signatures; a fully matched signature absorbs into `matched`, an empty viable set
- * into `dead`. Settles within 12 bytes — `matched`/`dead` are absorbing.
- */
-type MagicState = {
-    readonly tag: 'scan';
-    readonly pos: number;
-    readonly viable: readonly Signature[];
-} | {
-    readonly tag: 'matched';
-    readonly mime: string;
-} | {
-    readonly tag: 'dead';
-};
-/**
- * `A_utf8`: a streaming UTF-8 validity-and-text check riding the shared
- * `utf8ByteToCodePointOp` decoder. `st` is the decoder's mid-sequence state;
- * `valid` is `false` once an illegal byte, surrogate, or out-of-range code point
- * is seen — `valid: false` is absorbing. A non-null `st` at EOF (a truncated
- * multi-byte sequence) is invalid. `text` is the orthogonal text-ness verdict: it
- * is `false` once a non-text (control) code point is decoded, even though that
- * code point is perfectly well-formed UTF-8 — `text: false` is absorbing too.
- * Keeping the two distinct lets a valid-but-control blob (e.g. NUL) decode
- * cleanly yet still classify as binary.
- */
-type Utf8Detect = {
-    readonly st: Utf8State;
-    readonly valid: boolean;
-    readonly text: boolean;
-};
-/**
- * The product state: running bit length × magic eliminator × UTF-8 validator.
- * The factors never read each other; they meet only in {@link finish}.
- */
-export type DetectState = {
-    readonly length: bigint;
-    readonly magic: MagicState;
-    readonly utf8: Utf8Detect;
-};
-/** The initial detector state `q₀`. */
-export declare const detectInit: DetectState;
-/**
- * Folds one `Vec` chunk into the detector state (`δ` over a whole chunk). Length
- * always advances by the chunk's bit length; per-byte iteration stops as soon as
- * the verdict is fixed (see {@link isSettled}), so large blobs — including large
- * magic-matched ones — cost ≈ length counting.
- */
-export declare const push: (s: DetectState) => (chunk: Vec) => DetectState;
-/** The metadata read off the detector at end-of-stream. */
-export type DetectMeta = {
-    readonly length: bigint;
-    readonly mime_type: string;
-    readonly type: 'text' | 'base64';
-};
-/**
- * Reads the answer off the final state (`λ`). Reproduces the three-way result of
- * the pure path: magic hit → `base64` + detected mime; else whole-blob-valid UTF-8
- * that is also all-text (byte-aligned, no invalidity, no control bytes) → `text` +
- * `text/plain`; else → `base64` + `application/octet-stream`. A valid-but-control
- * blob (NUL, other controls) is well-formed UTF-8 yet falls through to the binary
- * branch.
- */
-export declare const finish: (s: DetectState) => DetectMeta;
-/**
- * Classifies a whole `Vec` with the same state machine as {@link detectStream}.
- * The single-buffer counterpart for callers that already hold the bytes (the
- * `cas_get` `content: true` path materializes the blob anyway): both paths read
- * the three-way `{ length, mime_type, type }` verdict from one machine instead of
- * re-deriving it from `detect` + a separate UTF-8 check.
- */
-export declare const detectVec: (bytes: Vec) => DetectMeta;
-/**
- * Folds a CAS read stream through {@link push} and reads {@link finish} at EOF,
- * deriving `cas_get` metadata without ever materializing the blob. A read `error`
- * item short-circuits into the `IoResult` error.
- */
-export declare const detectStream: <O extends Operation>(stream: List<O, IoResult<Vec>>) => Effect<O, IoResult<DetectMeta>>;
-export {};