functionalscript 0.43.0 → 0.44.0

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

@@ -1,31 +0,0 @@
-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;
-        wrongDialectRejected: () => void;
-        missingSubjectRejected: () => void;
-        extraFieldsAccepted: () => void;
-    };
-    decodeText: {
-        validJson: () => void;
-        keyOrderIndependent: () => void;
-        malformedJsonRejected: () => void;
-        ordinaryJsonRejected: () => void;
-    };
-};

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

@@ -1,140 +0,0 @@
-import { assert, assertEq } from '../../asserts/module.f.js';
-import { dialect, mediaType, isHash, validate, decodeText } 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';
-// 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');
-        },
-        // 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');
-        },
-    },
-};

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 {};

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

@@ -1,231 +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 { msb, fromSentinel, length, u8List } from '../../types/bit_vec/module.f.js';
-import { iterable } from '../../types/list/module.f.js';
-import { pure, step } from '../../effects/module.f.js';
-import { ok, error } from '../../types/result/module.f.js';
-import { isValidCodePoint, isTextCodePoint } from '../../text/code_point/module.f.js';
-import { utf8ByteToCodePointOp } from '../../text/utf8/module.f.js';
-const { startsWith, removeFront } = msb;
-// Each signature is written as a hex literal whose leading `1` nibble is a
-// sentinel marking the start of the byte run (so leading zero bytes survive)
-// and fixing the length — see `bit_vec` `fromSentinel`.
-const sig = fromSentinel;
-/**
- * Contiguous magic-byte signatures, checked in order; the first prefix match
- * wins. Ordering is irrelevant here — no signature is a prefix of another.
- */
-const table = [
-    [sig(0x189504e470d0a1a0an), 'image/png'],
-    [sig(0x1ffd8ffn), 'image/jpeg'],
-    // Match the full GIF version headers ("GIF87a" / "GIF89a"), not just "GIF8",
-    // so opaque bytes that merely start with "GIF8" are not mistyped.
-    [sig(0x1474946383761n), 'image/gif'],
-    [sig(0x1474946383961n), 'image/gif'],
-    [sig(0x1255044462dn), 'application/pdf'],
-    // ZIP has three "PK" local-header variants: a normal entry, an empty
-    // archive (end-of-central-directory only), and a spanned archive.
-    [sig(0x1504b0304n), 'application/zip'],
-    [sig(0x1504b0506n), 'application/zip'],
-    [sig(0x1504b0708n), 'application/zip'],
-];
-// WebP: "RIFF" at offset 0, "WEBP" at offset 8 (the 4 bytes between are the
-// file size). 12 bytes = 96 bits is the minimum to carry both markers.
-const riff = sig(0x152494646n);
-const webp = sig(0x157454250n);
-const isWebp = (bytes) => length(bytes) >= 96n
-    && startsWith(riff)(bytes)
-    && startsWith(webp)(removeFront(64n)(bytes));
-/**
- * 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 const detect = (bytes) => {
-    if (isWebp(bytes)) {
-        return 'image/webp';
-    }
-    for (const [s, m] of table) {
-        if (startsWith(s)(bytes)) {
-            return m;
-        }
-    }
-    return null;
-};
-// The streaming counterpart of `table`/`isWebp`: the same signatures expressed as
-// byte patterns the eliminator can consume one byte at a time. WebP's gap is the
-// only wildcard run.
-const signatures = [
-    { pattern: [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a], mime: 'image/png' },
-    { pattern: [0xff, 0xd8, 0xff], mime: 'image/jpeg' },
-    { pattern: [0x47, 0x49, 0x46, 0x38, 0x37, 0x61], mime: 'image/gif' },
-    { pattern: [0x47, 0x49, 0x46, 0x38, 0x39, 0x61], mime: 'image/gif' },
-    { pattern: [0x25, 0x50, 0x44, 0x46, 0x2d], mime: 'application/pdf' },
-    { pattern: [0x50, 0x4b, 0x03, 0x04], mime: 'application/zip' },
-    { pattern: [0x50, 0x4b, 0x05, 0x06], mime: 'application/zip' },
-    { pattern: [0x50, 0x4b, 0x07, 0x08], mime: 'application/zip' },
-    {
-        pattern: [0x52, 0x49, 0x46, 0x46, null, null, null, null, 0x57, 0x45, 0x42, 0x50],
-        mime: 'image/webp',
-    },
-];
-const magicInit = { tag: 'scan', pos: 0, viable: signatures };
-const magicStep = (m, byte) => {
-    if (m.tag !== 'scan') {
-        return m;
-    }
-    const { pos } = m;
-    const viable = m.viable.filter(s => {
-        const p = s.pattern[pos];
-        return p === null || p === byte;
-    });
-    for (const s of viable) {
-        if (s.pattern.length === pos + 1) {
-            return { tag: 'matched', mime: s.mime };
-        }
-    }
-    return viable.length === 0 ? { tag: 'dead' } : { tag: 'scan', pos: pos + 1, viable };
-};
-const magicMime = (m) => m.tag === 'matched' ? m.mime : null;
-const utf8Init = { st: null, valid: true, text: true };
-const utf8Step = (u, byte) => {
-    if (!u.valid) {
-        return u;
-    }
-    const [cps, st] = utf8ByteToCodePointOp(byte, u.st);
-    let text = u.text;
-    for (const cp of cps) {
-        if (!isValidCodePoint(cp)) {
-            return { st, valid: false, text };
-        }
-        if (!isTextCodePoint(cp)) {
-            text = false;
-        }
-    }
-    return { st, valid: true, text };
-};
-const utf8Valid = (u) => u.valid && u.st === null;
-// A blob is text only when it is whole-blob-valid UTF-8 *and* every decoded code
-// point is a text code point (no NUL/other controls).
-const utf8Text = (u) => utf8Valid(u) && u.text;
-/** The initial detector state `q₀`. */
-export const detectInit = {
-    length: 0n,
-    magic: magicInit,
-    utf8: utf8Init,
-};
-// The outcome can no longer change — `push` may stop decoding and only count
-// length — once `finish` is pinned down. A magic `matched` pins it on its own
-// (`finish` returns the detected mime and ignores the utf8 verdict), so we must
-// not wait for utf8 to go invalid (it may stay valid forever, e.g. an ASCII PDF).
-// A magic `dead` leaves text-vs-octet open, so it settles only once utf8 can no
-// longer be text — either invalid or a control byte seen (both absorbing); `scan`
-// is never settled.
-const isSettled = (magic, utf8) => {
-    switch (magic.tag) {
-        case 'matched': return true;
-        case 'dead': return !utf8.valid || !utf8.text;
-        case 'scan': return false;
-    }
-};
-/**
- * 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 const push = (s) => (chunk) => {
-    const bits = length(chunk);
-    let magic = s.magic;
-    let utf8 = s.utf8;
-    if (!isSettled(magic, utf8)) {
-        for (const byte of iterable(u8List(msb)(chunk))) {
-            magic = magicStep(magic, byte);
-            utf8 = utf8Step(utf8, byte);
-            if (isSettled(magic, utf8)) {
-                break;
-            }
-        }
-    }
-    return { length: s.length + bits, magic, utf8 };
-};
-/**
- * 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 const finish = (s) => {
-    const byteLength = s.length >> 3n;
-    const mime = magicMime(s.magic);
-    if (mime !== null) {
-        return { length: byteLength, mime_type: mime, type: 'base64' };
-    }
-    if (utf8Text(s.utf8) && (s.length & 7n) === 0n) {
-        return { length: byteLength, mime_type: 'text/plain', type: 'text' };
-    }
-    return { length: byteLength, mime_type: 'application/octet-stream', type: 'base64' };
-};
-/**
- * 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 const detectVec = (bytes) => finish(push(detectInit)(bytes));
-/**
- * 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 const detectStream = (stream) => {
-    const loop = (s) => (l) => step(l, (node) => {
-        if (node === undefined) {
-            return pure(ok(finish(s)));
-        }
-        const { first, tail } = node;
-        const [t, v] = first;
-        if (t === 'error') {
-            return pure(error(v));
-        }
-        return loop(push(s)(v))(tail);
-    });
-    return loop(detectInit)(stream);
-};