functionalscript 0.44.0 → 0.45.0

package/fjs/media/json/schema/proof.f.mjs

@@ -1,11 +1,13 @@
 /**
  * @import { Unknown as JsonValue } from '../types.ts'
  * @import { Unknown } from './module.f.mjs'
+ * @import { Data } from '../../../types/rtti/data/types.ts'
  */
 
-import { boolean, number, string, bigint, unknown, array, record, or, option } from '../../../types/rtti/module.f.mjs'
+import { boolean, number, string, bigint, never, unknown, array, record, or, option } from '../../../types/rtti/module.f.mjs'
 import { stringify } from '../module.f.mjs'
-import { toJsonSchema, unknown as schemaUnknown } from './module.f.mjs'
+import { dataToJsonSchema, toJsonSchema, unknown as schemaUnknown } from './module.f.mjs'
+import { unitBit } from '../../../types/rtti/data/module.f.mjs'
 import { assert, assertEq } from '../../../asserts/module.f.mjs'
 
 /** @type {(v: Unknown) => string} */
@@ -18,6 +20,46 @@ const eq = (rtti, expected) => () => {
     assertEq(result, exp, [result, exp])
 }
 
+/** @type {(data: Data, expected: Unknown) => () => void} */
+const eqData = (data, expected) => () => {
+    const result = serialize(dataToJsonSchema(data))
+    const exp = serialize(expected)
+    assertEq(result, exp, [result, exp])
+}
+
+/** A recursive list: `type _List = readonly _List[]`. */
+/** @typedef {() => readonly ['array', _List]} _List */
+/** @type {_List} */
+const list = () => ['array', list]
+
+/** Mutual recursion through a container. */
+/** @typedef {() => readonly ['or', typeof number, _Forest]} _Tree */
+/** @typedef {() => readonly ['array', _Tree]} _Forest */
+/** @type {_Tree} */
+const tree = () => ['or', number, forest]
+/** @type {_Forest} */
+const forest = () => ['array', tree]
+
+/** The recursive revision lock schema. Its cycle closes through the
+ * anonymous `or` thunk, which becomes the (empty-string-named) rule. */
+/** @typedef {() => readonly ['record', () => readonly ['or', typeof string, _Lock]]} _Lock */
+/** @type {_Lock} */
+const lock = () => ['record', or(string, lock)]
+
+/** Self-recursive record. */
+/** @typedef {() => readonly ['record', _Rec]} _Rec */
+/** @type {_Rec} */
+const rec = () => ['record', rec]
+
+const listRef = /** @type {const} */ ({ $ref: '#/$defs/list' })
+const treeRef = /** @type {const} */ ({ $ref: '#/$defs/tree' })
+
+/** @type {Unknown} */
+const listDef = { type: 'array', items: listRef }
+
+/** @type {Unknown} */
+const treeDef = { anyOf: [{ type: 'number' }, { type: 'array', items: treeRef }] }
+
 export const proof = {
     tag0: {
         boolean: eq(boolean, { type: 'boolean' }),
@@ -37,10 +79,12 @@ export const proof = {
     },
     array: eq(array(number), { type: 'array', items: { type: 'number' } }),
     record: eq(record(string), { type: 'object', additionalProperties: { type: 'string' } }),
-    or: eq(or(string, number), { anyOf: [{ type: 'string' }, { type: 'number' }] }),
+    // `anyOf` members follow the canonical kind order, not the operand order
+    or: eq(or(string, number), { anyOf: [{ type: 'number' }, { type: 'string' }] }),
     tuple: eq(/** @type {const} */ ([number, string]), {
         type: 'array',
         prefixItems: [{ type: 'number' }, { type: 'string' }],
+        minItems: 2,
         items: false,
     }),
     struct: {
@@ -58,16 +102,35 @@ export const proof = {
             type: 'object',
             properties: { x: { type: 'number' } },
         }),
-        empty: eq(/** @type {const} */ ({}), { type: 'object', properties: {} }),
+        // an unconstrained struct is the whole object kind
+        empty: eq(/** @type {const} */ ({}), { type: 'object' }),
         orOptional: eq(/** @type {const} */ ({ x: or(string, number, undefined) }), {
             type: 'object',
-            properties: { x: { anyOf: [{ type: 'string' }, { type: 'number' }] } },
+            properties: { x: { anyOf: [{ type: 'number' }, { type: 'string' }] } },
         }),
         withConst: eq(/** @type {const} */ ({ x: null, y: string }), {
             type: 'object',
             properties: { x: { const: null }, y: { type: 'string' } },
             required: ['x', 'y'],
         }),
+        optionalOfEveryKind: eq(/** @type {const} */ ({
+            a: option(number),
+            b: option(string),
+            c: option(bigint),
+            d: option(array(number)),
+            e: option(record(string)),
+            f: or(null, undefined),
+        }), {
+            type: 'object',
+            properties: {
+                a: { type: 'number' },
+                b: { type: 'string' },
+                c: { type: 'integer' },
+                d: { type: 'array', items: { type: 'number' } },
+                e: { type: 'object', additionalProperties: { type: 'string' } },
+                f: { const: null },
+            },
+        }),
     },
     schemaUnknownTag: () => {
         const r = schemaUnknown()
@@ -79,15 +142,164 @@ export const proof = {
             items: { type: 'object', additionalProperties: { type: 'boolean' } },
         }),
         orWithConst: eq(or(null, string, /** @type {const} */ (42)), {
-            anyOf: [{ const: null }, { type: 'string' }, { const: 42 }],
+            anyOf: [{ const: null }, { const: 42 }, { type: 'string' }],
         }),
         structWithOr: eq(/** @type {const} */ ({ id: or(string, number), name: option(string) }), {
             type: 'object',
             properties: {
-                id: { anyOf: [{ type: 'string' }, { type: 'number' }] },
+                id: { anyOf: [{ type: 'number' }, { type: 'string' }] },
                 name: { type: 'string' },
             },
             required: ['id'],
         }),
+        topInsideTuple: eq(/** @type {const} */ ([unknown, number]), {
+            type: 'array',
+            prefixItems: [{}, { type: 'number' }],
+            minItems: 2,
+            items: false,
+        }),
+    },
+    normalization: {
+        booleanFromConsts: eq(or(true, false), { type: 'boolean' }),
+        unitMembers: eq(or(null, undefined, true), {
+            anyOf: [{ const: null }, { not: {} }, { const: true }],
+        }),
+        literalAbsorbed: eq(or(/** @type {const} */ (42), number), { type: 'number' }),
+        duplicateLiteral: eq(or(/** @type {const} */ (1), /** @type {const} */ (1)), { const: 1 }),
+        never: eq(never, { not: {} }),
+        emptyTuple: eq(/** @type {const} */ ([]), { type: 'array', items: false }),
+        // `readonly [number] ⊂ readonly number[]` — the tuple pattern is dropped
+        coverageCollapse: eq(or(/** @type {const} */ ([number]), array(number)), {
+            type: 'array',
+            items: { type: 'number' },
+        }),
+        commutative: () => {
+            const a = serialize(toJsonSchema(or(string, number)))
+            const b = serialize(toJsonSchema(or(number, string)))
+            assertEq(a, b, [a, b])
+        },
+    },
+    recursion: {
+        selfList: eq(list, { ...listRef, $defs: { list: listDef } }),
+        mutualEntry: eq(tree, { ...treeRef, $defs: { tree: treeDef } }),
+        mutualInline: eq(forest, { type: 'array', items: treeRef, $defs: { tree: treeDef } }),
+        recursiveUnion: eq(or(number, list), {
+            anyOf: [{ type: 'number' }, { type: 'array', items: listRef }],
+            $defs: { list: listDef },
+        }),
+        recursiveRecord: eq(rec, {
+            $ref: '#/$defs/rec',
+            $defs: { rec: { type: 'object', additionalProperties: { $ref: '#/$defs/rec' } } },
+        }),
+        optionalRecursiveProperty: eq(/** @type {const} */ ({ p: option(list) }), {
+            type: 'object',
+            properties: { p: { type: 'array', items: listRef } },
+            $defs: { list: listDef },
+        }),
+        revisionLock: eq(lock, {
+            type: 'object',
+            additionalProperties: { $ref: '#/$defs/' },
+            $defs: {
+                '': {
+                    anyOf: [
+                        { type: 'string' },
+                        { type: 'object', additionalProperties: { $ref: '#/$defs/' } },
+                    ],
+                },
+            },
+        }),
+        sharedNonRecursive: () => {
+            // a shared, non-recursive definition is inlined at each use — no `$defs`
+            const person = /** @type {const} */ ({ name: string })
+            /** @type {Unknown} */
+            const personSchema = {
+                type: 'object',
+                properties: { name: { type: 'string' } },
+                required: ['name'],
+            }
+            eq(/** @type {const} */ ([person, person]), {
+                type: 'array',
+                prefixItems: [personSchema, personSchema],
+                minItems: 2,
+                items: false,
+            })()
+        },
+    },
+    data: (() => {
+        /** @type {Data} */
+        const tupleWithRest = [{}, { array: [{ prefix: [{ number: true }], rest: { string: true } }] }]
+        /** @type {Data} */
+        const structWithRest = [{}, {
+            object: [{ props: { a: { number: true } }, rest: { string: true } }],
+        }]
+        /** @type {Data} */
+        const optionalByReference = [
+            { r: { unit: unitBit(null) | unitBit(undefined), number: true } },
+            { object: [{ props: { p: 'r' } }] },
+        ]
+        return {
+            plain: eqData([{}, { number: true }], { type: 'number' }),
+            tupleWithRest: eqData(tupleWithRest, {
+                type: 'array',
+                prefixItems: [{ type: 'number' }],
+                minItems: 1,
+                items: { type: 'string' },
+            }),
+            structWithRest: eqData(structWithRest, {
+                type: 'object',
+                properties: { a: { type: 'number' } },
+                required: ['a'],
+                additionalProperties: { type: 'string' },
+            }),
+            // a referenced definition admitting `undefined` makes the key
+            // optional; the reference itself is kept as the property schema
+            optionalByReference: eqData(optionalByReference, {
+                type: 'object',
+                properties: { p: { $ref: '#/$defs/r' } },
+                $defs: { r: { anyOf: [{ const: null }, { not: {} }, { type: 'number' }] } },
+            }),
+        }
+    })(),
+    refEncoding: (() => {
+        /** @type {Data} */
+        const d = [
+            {
+                'a~b': { number: true },
+                'a/b': { number: true },
+                '%2F': { number: true },
+                'a b': { number: true },
+                'é': { number: true },
+            },
+            { array: [{ prefix: ['a~b', 'a/b', '%2F', 'a b', 'é'] }] },
+        ]
+        return eqData(d, {
+            type: 'array',
+            prefixItems: [
+                { $ref: '#/$defs/a~0b' },
+                { $ref: '#/$defs/a~1b' },
+                { $ref: '#/$defs/%252F' },
+                { $ref: '#/$defs/a%20b' },
+                { $ref: '#/$defs/%C3%A9' },
+            ],
+            minItems: 5,
+            items: false,
+            $defs: {
+                'a~b': { type: 'number' },
+                'a/b': { type: 'number' },
+                '%2F': { type: 'number' },
+                'a b': { type: 'number' },
+                'é': { type: 'number' },
+            },
+        })
+    })(),
+    throw: {
+        missingRootDefinition: () => dataToJsonSchema([{}, 'nope']),
+        // an `Object.prototype` member name is still a missing definition
+        missingPrototypeDefinition: () => dataToJsonSchema([{}, 'toString']),
+        missingNestedDefinition: () => {
+            /** @type {Data} */
+            const d = [{ a: { array: [{ prefix: [], rest: 'missing' }] } }, 'a']
+            return dataToJsonSchema(d)
+        },
     },
 }

package/fjs/media/json/serializer/module.f.d.mts

@@ -1,3 +1,16 @@
+/**
+ * JSON serializer for deterministic string output.
+ *
+ * `stringSerialize` is FunctionalScript, not the host's `JSON.stringify`: it
+ * escapes over this repository's own UTF-16 decoder and reproduces the
+ * ECMAScript `QuoteJSONString` result exactly, lone surrogates included.
+ *
+ * @module
+ *
+ * @import { List } from '../../../types/list/types.ts'
+ * @import { Reduce } from '../../../types/function/operator/types.ts'
+ * @import { CodePoint } from '../../../text/utf16/types.ts'
+ */
 import type { List } from '../../../types/list/types.ts';
 /**
  * Serializes a string as a JSON string literal.

package/fjs/media/json/serializer/module.f.mjs

@@ -6,21 +6,22 @@
  * ECMAScript `QuoteJSONString` result exactly, lone surrogates included.
  *
  * @module
+ *
+ * @import { List } from '../../../types/list/types.ts'
+ * @import { Reduce } from '../../../types/function/operator/types.ts'
+ * @import { CodePoint } from '../../../text/utf16/types.ts'
  */
-/** @import { List } from '../../../types/list/types.ts' */
+
 import { flat, map, reduce, empty } from '../../../types/list/module.f.mjs'
-/** @import { Reduce } from '../../../types/function/operator/types.ts' */
 import { concat } from '../../../types/string/module.f.mjs'
-/** @import { CodePoint } from '../../../text/utf16/types.ts' */
 import { codePointToString, stringToCodePointList } from '../../../text/utf16/module.f.mjs'
 import { errorMask } from '../../../text/code_point/module.f.mjs'
 import {
     backspace,
     cr,
-    digit0,
     ff,
+    hexDigitCodePoint,
     ht,
-    latinSmallLetterA,
     lf,
     quotationMark,
     reverseSolidus,
@@ -46,8 +47,7 @@ const escapeTable = /** @type {const} */ ({
 })
 
 /** @type {(value: number) => string} */
-const hexDigit = value =>
-    fromCharCode(value < 10 ? digit0 + value : latinSmallLetterA + value - 10)
+const hexDigit = value => fromCharCode(hexDigitCodePoint(value))
 
 /**
  * `\uXXXX` with lowercase hex digits, matching ECMAScript's `UnicodeEscape`.

package/fjs/media/json/tokenizer/module.f.d.mts

@@ -2,6 +2,11 @@
  * Tokenizer for JSON lexical analysis.
  *
  * @module
+ *
+ * @import { StateScan } from '../../../types/function/operator/types.ts'
+ * @import { List } from '../../../types/list/types.ts'
+ * @import { JsToken } from '../../../js/tokenizer/types.ts'
+ * @import { JsonToken, _ScanState, _ScanInput } from './types.ts'
  */
 import type { List } from '../../../types/list/types.ts';
 import type { JsonToken } from './types.ts';
@@ -15,3 +20,6 @@ import type { JsonToken } from './types.ts';
  * @type {(input: List<number>) => List<JsonToken>}
  */
 export declare const tokenize: (input: List<number>) => List<JsonToken>;
+export declare const proof: {
+    parseMinusStateEof: () => void;
+};

package/fjs/media/json/tokenizer/module.f.mjs

@@ -2,15 +2,17 @@
  * Tokenizer for JSON lexical analysis.
  *
  * @module
+ *
+ * @import { StateScan } from '../../../types/function/operator/types.ts'
+ * @import { List } from '../../../types/list/types.ts'
+ * @import { JsToken } from '../../../js/tokenizer/types.ts'
+ * @import { JsonToken, _ScanState, _ScanInput } from './types.ts'
  */
 
-/** @import { StateScan } from '../../../types/function/operator/types.ts' */
-/** @import { List } from '../../../types/list/types.ts' */
-import { concat, empty, flat, stateScan } from '../../../types/list/module.f.mjs'
+import { concat, empty, flat, stateScan, toArray } from '../../../types/list/module.f.mjs'
 import { multiply } from '../../../types/bigfloat/module.f.mjs'
 import { tokenize as jsTokenize } from '../../../js/tokenizer/module.f.mjs'
-/** @import { JsToken } from '../../../js/tokenizer/types.ts' */
-/** @import { JsonToken, _ScanState, _ScanInput } from './types.ts' */
+import { assertEq } from '../../../asserts/module.f.mjs'
 
 /** @type {(input: JsToken) => List<JsonToken>} */
 const mapToken = input => {
@@ -75,3 +77,20 @@ export const tokenize = input => {
     const jsTokens = jsTokenize(input)('')
     return flat(stateScan(scanToken)({ kind: 'def' })(concat(jsTokens)([null])))
 }
+
+export const proof = {
+    // `parseMinusState` only sees `null` if the JSON tokenizer's own EOF
+    // sentinel arrives while still in state '-' — i.e. input ends right after
+    // a lone `-`. Unreachable through the public `tokenize`: the underlying
+    // JS tokenizer always emits its own `eof` token first, and consuming that
+    // (the default branch, any kind other than '-' or 'number') resets state
+    // to 'def' before the sentinel `null` is ever seen. Call the private
+    // state handler directly to cover the branch anyway.
+    parseMinusStateEof: () => {
+        const [tokens, state] = parseMinusState(null)
+        assertEq(state.kind, 'def')
+        const a = toArray(tokens)
+        assertEq(a.length, 1)
+        assertEq(a[0].kind, 'error')
+    },
+}

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

@@ -1,3 +1,16 @@
+/**
+ * A minimal, checked eDSL for constructing and serializing Nix expressions.
+ *
+ * The tree deliberately models syntax rather than evaluated Nix values. String
+ * expressions are escaped double-quoted strings; the other supported forms are
+ * represented by tagged tuples. See `./types.ts` for the `Expression`
+ * type-level API.
+ *
+ * @module
+ *
+ * @import { List as ChunkList } from '../../types/list/types.ts'
+ * @import { Expression, _AttributePath, _Binding, _Reference, _AttributeSet, _NixList, _Application, _OpenSetPattern, _Lambda, _Let, _Chunks } from './types.ts'
+ */
 import type { List as ChunkList } from '../../types/list/types.ts';
 import type { Expression } from './types.ts';
 /**

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

@@ -7,8 +7,11 @@
  * type-level API.
  *
  * @module
+ *
+ * @import { List as ChunkList } from '../../types/list/types.ts'
+ * @import { Expression, _AttributePath, _Binding, _Reference, _AttributeSet, _NixList, _Application, _OpenSetPattern, _Lambda, _Let, _Chunks } from './types.ts'
  */
-/** @import { List as ChunkList } from '../../types/list/types.ts' */
+
 import { toArray } from '../../types/list/module.f.mjs'
 import { concat } from '../../types/string/module.f.mjs'
 import { includes } from '../../types/array/module.f.mjs'
@@ -19,7 +22,6 @@ import {
     range,
 } from '../../text/ascii/module.f.mjs'
 import { fromRange, get, merge } from '../../types/range_set/module.f.mjs'
-/** @import { Expression, _AttributePath, _Binding, _Reference, _AttributeSet, _NixList, _Application, _OpenSetPattern, _Lambda, _Let, _Chunks } from './types.ts' */
 
 const reservedWords = /** @type {const} */ ([
     'assert',

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

@@ -1,3 +1,6 @@
+/**
+ * @import { Expression } from './types.ts'
+ */
 export declare const proof: {
     strings: () => void;
     reference: () => void;

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

@@ -1,7 +1,10 @@
+/**
+ * @import { Expression } from './types.ts'
+ */
+
 import { assert, assertEq } from '../../asserts/module.f.mjs'
 import { toArray } from '../../types/list/module.f.mjs'
 import { nix, nixToString } from './module.f.mjs'
-/** @import { Expression } from './types.ts' */
 
 /** @type {(nodePackage: string, shellHook: boolean) => Expression} */
 const nodeFlake = (nodePackage, shellHook) => ['set',

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

@@ -97,6 +97,11 @@ 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>;

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

@@ -24,7 +24,7 @@ import { array, number, option, record, string } from '../../types/rtti/module.f
 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 } from '../../types/result/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'
@@ -126,13 +126,14 @@ export const checkReferences = 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 => {
-    const [t, v] = validateShape(value)
-    if (t === 'error') { return error(v) }
-    return checkReferences(v)
-}
+export const validate = value => okThen(checkReferences)(validateShape(value))
 
 /**
  * Decodes `text` as a `revision` BLOB: JSON-parses it, then validates it per
@@ -141,11 +142,7 @@ export const validate = value => {
  *
  * @type {(text: string) => Result<Revision, RevisionError>}
  */
-export const decodeText = text => {
-    const [t, v] = parseJson(text)
-    if (t === 'error') { return error(v) }
-    return validate(v)
-}
+export const decodeText = text => okThen(validate)(parseJson(text))
 
 /** {@link checkReferences} as the `boolean` refinement a {@link DialectEntry} takes.
  * @type {(r: Revision) => boolean}

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

@@ -1,3 +1,7 @@
+/**
+ * @import { Object as JsonObject } from '../json/types.ts'
+ * @import { LockMap } from './types.ts'
+ */
 export declare const proof: {
     dialectAndMediaType: () => void;
     isHash: {

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

@@ -1,5 +1,8 @@
-/** @import { Object as JsonObject } from '../json/types.ts' */
-/** @import { LockMap } from './types.ts' */
+/**
+ * @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'
 

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

@@ -1,15 +1,16 @@
 /**
  * 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.
+ * One list — `signatures` — declares every recognized magic-byte pattern, and
+ * both detectors read it through the same eliminator (`magicStep`): `detect`
+ * folds a whole `Vec` and returns a MIME type string or `null`, while
+ * `detectStream` folds a read stream one chunk at a time.
  *
- * 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.
+ * Beside `detect`, `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
@@ -27,12 +28,19 @@
  * | `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.
+ * sits between the `RIFF` and `WEBP` markers, so its pattern carries four
+ * wildcard bytes rather than being one contiguous run.
  *
  * See `./types.ts` for the type-level API.
  *
  * @module
+ *
+ * @import { Vec } from '../../types/bit_vec/types.ts'
+ * @import { Nullable } from '../../types/nullable/types.ts'
+ * @import { Effect, Operation } from '../../effects/types.ts'
+ * @import { List } from '../../effects/list/types.ts'
+ * @import { IoResult } from '../../effects/node/types.ts'
+ * @import { DetectMeta, DetectState, _MagicState, _Signature, _Utf8Detect } from './types.ts'
  */
 import type { Vec } from '../../types/bit_vec/types.ts';
 import type { Nullable } from '../../types/nullable/types.ts';
@@ -41,7 +49,16 @@ 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.
+ * Detects the MIME type of `bytes` from its leading magic-byte signature by
+ * folding them through the same eliminator the streaming detector uses. Both
+ * absorbing states end the fold: a `matched` signature is the answer, and a
+ * `dead` eliminator can no longer produce one. Bytes still in `scan` at the end
+ * of the `Vec` — a prefix too short to complete any signature — leave the
+ * eliminator unsettled, which reads as `null`.
+ *
+ * The bytes come from `u8List`, so a `Vec` whose length is not a whole number of
+ * bytes has its trailing partial byte zero-padded — the same reading of a ragged
+ * `Vec` the streaming detector already uses.
  *
  * @returns the MIME type string for a recognized format, or `null` when the
  *   leading bytes match no known signature (including any `Vec` shorter than