functionalscript 0.43.1 → 0.44.0

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

@@ -0,0 +1,228 @@
+/** @import { Object as JsonObject } from '../json/types.ts' */
+/** @import { LockMap } from './types.ts' */
+import { assert, assertEq } from '../../asserts/module.f.mjs'
+import { dialect, mediaType, isHash, validate, decodeText, encodeText } from './module.f.mjs'
+
+// Valid cbase32 hashes (round-tripped in fjs/basen/cbase32/proof.f.mjs): 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 = /** @type {const} */ ('I')
+
+/** @type {LockMap} */
+const _lockMapAllowsMissingSubjects = {}
+
+// A shape-valid revision: every required field present (`snapshot` and
+// `generation` included), with `extra` overriding or adding fields per test.
+/** @type {(extra: JsonObject) => JsonObject} */
+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/revision/types.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Type-level API for `fjs/media/revision/module.f.mjs`: `LockMap`,
+ * `Revision`, and `RevisionError`, derived from the module's own rtti
+ * schemas.
+ *
+ * @module
+ */
+import type { Ts } from '../../types/rtti/ts/types.ts';
+import type { ValidationError } from '../../types/rtti/common/types.ts';
+import type { _lock, revisionSchema } from './module.f.mjs';
+/** A flat set of subject-to-snapshot bindings supplied to dependency resolvers. */
+export type LockMap = Ts<typeof _lock>;
+/** The TypeScript type derived from `revisionSchema` — the single source of truth. */
+export type Revision = Ts<typeof revisionSchema>;
+/** Either a structural validation error or a semantic (hash / generation) error message. */
+export type RevisionError = ValidationError | string;

package/fjs/media/revision/types.js

@@ -0,0 +1,8 @@
+/**
+ * Type-level API for `fjs/media/revision/module.f.mjs`: `LockMap`,
+ * `Revision`, and `RevisionError`, derived from the module's own rtti
+ * schemas.
+ *
+ * @module
+ */
+export {};

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

@@ -0,0 +1,61 @@
+/**
+ * Rust source literals.
+ *
+ * Printing a value as Rust source is not specific to any one generator: the
+ * MVP roadmap's `fjs compile <input>.rs` backend and `nanvm-lib`'s generated
+ * operator tests both need the same escaping and the same spelling of the
+ * numeric edge cases. This module owns that layer — the syntax of a literal —
+ * and nothing above it. Expressions, items, and whatever API a generator
+ * targets stay with the generator.
+ *
+ * The sibling of `fjs/media/nix`, which does the same for Nix expressions.
+ *
+ * @module
+ *
+ * @example
+ *
+ * ```js
+ * import { f64Literal, i64Literal, stringLiteral } from './module.f.mjs'
+ *
+ * stringLiteral('a"b') // '"a\\"b"'
+ * f64Literal(-0)       // '-0f64'
+ * i64Literal(-456n)    // '-456'
+ * ```
+ */
+/**
+ * A double-quoted Rust string literal.
+ *
+ * Any other control character is rejected rather than escaped: no caller needs
+ * one, and a silently mangled literal is worse than a failed generation.
+ *
+ * @type {(v: string) => string}
+ */
+export declare const stringLiteral: (v: string) => string;
+/**
+ * An `f64` literal.
+ *
+ * `toString` already prints the shortest round-tripping decimal and Rust
+ * parses decimal float literals the same way JavaScript does, so the digits
+ * carry over unchanged. Only the three non-finite values and `-0` — which
+ * `toString` prints as `0` — need spelling out. The `f64` suffix keeps whole
+ * numbers from lexing as integers.
+ *
+ * @type {(v: number) => string}
+ */
+export declare const f64Literal: (v: number) => string;
+/**
+ * An `i64` literal. Throws for a value the type cannot hold, rather than
+ * silently truncating it.
+ *
+ * @type {(v: bigint) => string}
+ */
+export declare const i64Literal: (v: bigint) => string;
+/**
+ * A `snake_case` Rust identifier from a `camelCase` name.
+ *
+ * Only the casing is converted: a name that is not already a valid identifier
+ * stays invalid, so callers pass names they control.
+ *
+ * @type {(v: string) => string}
+ */
+export declare const snakeCase: (v: string) => string;

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

@@ -0,0 +1,93 @@
+/**
+ * Rust source literals.
+ *
+ * Printing a value as Rust source is not specific to any one generator: the
+ * MVP roadmap's `fjs compile <input>.rs` backend and `nanvm-lib`'s generated
+ * operator tests both need the same escaping and the same spelling of the
+ * numeric edge cases. This module owns that layer — the syntax of a literal —
+ * and nothing above it. Expressions, items, and whatever API a generator
+ * targets stay with the generator.
+ *
+ * The sibling of `fjs/media/nix`, which does the same for Nix expressions.
+ *
+ * @module
+ *
+ * @example
+ *
+ * ```js
+ * import { f64Literal, i64Literal, stringLiteral } from './module.f.mjs'
+ *
+ * stringLiteral('a"b') // '"a\\"b"'
+ * f64Literal(-0)       // '-0f64'
+ * i64Literal(-456n)    // '-456'
+ * ```
+ */
+
+/**
+ * A double-quoted Rust string literal.
+ *
+ * Any other control character is rejected rather than escaped: no caller needs
+ * one, and a silently mangled literal is worse than a failed generation.
+ *
+ * @type {(v: string) => string}
+ */
+export const stringLiteral = v => `"${[...v].map(c => {
+    switch (c) {
+        case '\\': { return '\\\\' }
+        case '"': { return '\\"' }
+        case '\n': { return '\\n' }
+        case '\r': { return '\\r' }
+        case '\t': { return '\\t' }
+        default: {
+            if (c < ' ' || c === '\u007f') {
+                throw ['control character in a Rust string literal', v]
+            }
+            return c
+        }
+    }
+}).join('')}"`
+
+/**
+ * An `f64` literal.
+ *
+ * `toString` already prints the shortest round-tripping decimal and Rust
+ * parses decimal float literals the same way JavaScript does, so the digits
+ * carry over unchanged. Only the three non-finite values and `-0` — which
+ * `toString` prints as `0` — need spelling out. The `f64` suffix keeps whole
+ * numbers from lexing as integers.
+ *
+ * @type {(v: number) => string}
+ */
+export const f64Literal = v => {
+    if (Number.isNaN(v)) { return 'f64::NAN' }
+    if (v === Infinity) { return 'f64::INFINITY' }
+    if (v === -Infinity) { return 'f64::NEG_INFINITY' }
+    return `${Object.is(v, -0) ? '-0' : v.toString()}f64`
+}
+
+const i64Min = -(2n ** 63n)
+const i64Max = 2n ** 63n - 1n
+
+/**
+ * An `i64` literal. Throws for a value the type cannot hold, rather than
+ * silently truncating it.
+ *
+ * @type {(v: bigint) => string}
+ */
+export const i64Literal = v => {
+    if (v < i64Min || v > i64Max) { throw ['bigint out of i64 range', v] }
+    return v.toString()
+}
+
+/**
+ * A `snake_case` Rust identifier from a `camelCase` name.
+ *
+ * Only the casing is converted: a name that is not already a valid identifier
+ * stays invalid, so callers pass names they control.
+ *
+ * @type {(v: string) => string}
+ */
+export const snakeCase = v => [...v].map(c => {
+    const lower = c.toLowerCase()
+    return c === lower ? c : `_${lower}`
+}).join('')

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

@@ -0,0 +1,17 @@
+/**
+ * Proofs for Rust source literals.
+ *
+ * @module
+ */
+export declare const proof: {
+    stringLiteral: () => void;
+    f64Literal: () => void;
+    i64Literal: () => void;
+    snakeCase: () => void;
+    throw: {
+        i64TooLarge: () => string;
+        i64TooSmall: () => string;
+        controlCharacter: () => string;
+        deleteCharacter: () => string;
+    };
+};

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

@@ -0,0 +1,50 @@
+/**
+ * Proofs for Rust source literals.
+ *
+ * @module
+ */
+
+import { assertEq } from '../../asserts/module.f.mjs'
+import { f64Literal, i64Literal, snakeCase, stringLiteral } from './module.f.mjs'
+
+export const proof = {
+    stringLiteral: () => {
+        assertEq(stringLiteral(''), '""')
+        assertEq(stringLiteral('abc'), '"abc"')
+        assertEq(stringLiteral('a\\b'), '"a\\\\b"')
+        assertEq(stringLiteral('a"b'), '"a\\"b"')
+        assertEq(stringLiteral('a\nb'), '"a\\nb"')
+        assertEq(stringLiteral('a\rb'), '"a\\rb"')
+        assertEq(stringLiteral('a\tb'), '"a\\tb"')
+        // Non-ASCII needs no escape: Rust source is UTF-8.
+        assertEq(stringLiteral('é'), '"é"')
+    },
+    f64Literal: () => {
+        assertEq(f64Literal(NaN), 'f64::NAN')
+        assertEq(f64Literal(Infinity), 'f64::INFINITY')
+        assertEq(f64Literal(-Infinity), 'f64::NEG_INFINITY')
+        assertEq(f64Literal(-0), '-0f64')
+        assertEq(f64Literal(0), '0f64')
+        assertEq(f64Literal(2.3), '2.3f64')
+        assertEq(f64Literal(-239), '-239f64')
+        // Rust's exponent accepts a `+`, which is how `toString` prints it.
+        assertEq(f64Literal(1e21), '1e+21f64')
+    },
+    i64Literal: () => {
+        assertEq(i64Literal(0n), '0')
+        assertEq(i64Literal(-456n), '-456')
+        assertEq(i64Literal(-(2n ** 63n)), '-9223372036854775808')
+        assertEq(i64Literal(2n ** 63n - 1n), '9223372036854775807')
+    },
+    snakeCase: () => {
+        assertEq(snakeCase('emptyArray'), 'empty_array')
+        assertEq(snakeCase('stringCoercion'), 'string_coercion')
+        assertEq(snakeCase('eq'), 'eq')
+    },
+    throw: {
+        i64TooLarge: () => i64Literal(2n ** 63n),
+        i64TooSmall: () => i64Literal(-(2n ** 63n) - 1n),
+        controlCharacter: () => stringLiteral('a\u0000b'),
+        deleteCharacter: () => stringLiteral('a\u007fb'),
+    },
+}

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

@@ -0,0 +1,97 @@
+/**
+ * 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.
+ *
+ * See `./types.ts` for the type-level API.
+ *
+ * @module
+ */
+import type { Vec } from '../../types/bit_vec/types.ts';
+import type { Nullable } from '../../types/nullable/types.ts';
+import type { Effect, Operation } from '../../effects/types.ts';
+import type { List } from '../../effects/list/types.ts';
+import type { IoResult } from '../../effects/node/types.ts';
+import type { DetectMeta, DetectState } from './types.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).
+ *
+ * @type {(bytes: Vec) => Nullable<string>}
+ */
+export declare const detect: (bytes: Vec) => Nullable<string>;
+/** The initial detector state `q₀`.
+ *
+ * @type {DetectState}
+ */
+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.
+ *
+ * @type {(s: DetectState) => (chunk: Vec) => DetectState}
+ */
+export declare const push: (s: DetectState) => (chunk: Vec) => DetectState;
+/**
+ * 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.
+ *
+ * @type {(s: DetectState) => DetectMeta}
+ */
+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.
+ *
+ * @type {(bytes: Vec) => DetectMeta}
+ */
+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.
+ *
+ * @template {Operation} O
+ * @param {List<O, IoResult<Vec>>} stream
+ * @returns {Effect<O, IoResult<DetectMeta>>}
+ */
+export declare const detectStream: <O extends Operation>(stream: List<O, IoResult<Vec>>) => Effect<O, IoResult<DetectMeta>>;