functionalscript 0.44.0 → 0.46.0

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'
 
@@ -13,6 +16,11 @@ const alias = /** @type {const} */ ('I')
 /** @type {LockMap} */
 const _lockMapAllowsMissingSubjects = {}
 
+// A lock map's values are `string | LockMap | undefined` at every depth, so
+// the same value is a legal binding for a direct hash and for a nested scope.
+/** @type {LockMap} */
+const _lockMapNests = { direct: h1, scope: { direct: h2, deeper: { direct: h1 } } }
+
 // A shape-valid revision: every required field present (`snapshot` and
 // `generation` included), with `extra` overriding or adding fields per test.
 /** @type {(extra: JsonObject) => JsonObject} */
@@ -152,6 +160,62 @@ export const proof = {
             assertEq(t, 'ok')
         },
 
+        // A nested map scopes further bindings under a subject — the
+        // incompatible-diamond case from the README, where `B` and `C` each
+        // pick their own `D`.
+        nestedLockAccepted: () => {
+            const r = validate(revisionOf({ lock: { B: { B: h1, D: h1 }, C: { C: h2, D: h2 } } }))
+            assert(r[0] === 'ok', ['expected ok', r])
+            assert(encodeText(r[1]).includes(`"lock":{"B":{"B":"${h1}","D":"${h1}"},"C":{"C":"${h2}","D":"${h2}"}}`))
+        },
+
+        // Nesting has no depth limit, and a nested map may be sparse — it need
+        // not bind the subject it appears under, or anything at all.
+        deeplyNestedLockAccepted: () => {
+            const [t] = validate(revisionOf({ lock: { B: { C: { D: { E: h1 } } }, empty: {} } }))
+            assertEq(t, 'ok')
+        },
+
+        // A direct value must be a string or a map at every depth: a number
+        // nested two levels down fails structural (rtti) validation, exactly
+        // as it does at the root.
+        malformedNestedLockRejected: () => {
+            const [t] = validate(revisionOf({ lock: { B: { D: 1 } } }))
+            assertEq(t, 'error')
+        },
+
+        // Semantic reference checking recurses too: a non-hash string deep in
+        // a nested scope is rejected, and the message names the path to it.
+        invalidNestedHashLockRejected: () => {
+            const r = validate(revisionOf({ lock: { B: { D: 'https://example.com/x' } } }))
+            assert(r[0] === 'error', ['expected error', r])
+            assertEq(r[1], 'lock value for B/D is not a valid hash: https://example.com/x')
+        },
+
+        // In place of the map, `lock` may be the hash of a `vnd.fjs.lock`
+        // blob holding one — the only position where a string means "where
+        // the bindings are" rather than "this dependency's content".
+        sharedLockReferenceAccepted: () => {
+            const r = validate(revisionOf({ lock: h1 }))
+            assert(r[0] === 'ok', ['expected ok', r])
+            assertEq(r[1].lock, h1)
+        },
+
+        // A reference is validated as a cbase32 hash and nothing more — the
+        // same contract `snapshot` has — so a non-hash one is rejected.
+        invalidSharedLockReferenceRejected: () => {
+            const r = validate(revisionOf({ lock: 'https://example.com/lock' }))
+            assert(r[0] === 'error', ['expected error', r])
+            assertEq(r[1], 'lock reference is not a valid hash: https://example.com/lock')
+        },
+
+        // Only the top level is widened: a nested value is still a hash or a
+        // map, so nothing about an inline map's meaning changed.
+        nestedValueIsStillNotAReference: () => {
+            const [t] = validate(revisionOf({ lock: { B: { D: h1 } } }))
+            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 })
@@ -210,6 +274,32 @@ export const proof = {
                 `{"dialect":"${dialect}","generation":0,"lock":{"10":"${h1}","2":"${h2}"},"parents":[],"snapshot":"${h2}","subject":"${h1}"}`,
             )
         },
+        // The one `stringify(sort)` rule already reaches every depth, so a
+        // nested lock map needs no serialization special case: its keys sort
+        // as strings like every other object's ("10" before "2").
+        sortsNestedLockKeys: () => {
+            const revision = revisionOf({ lock: { scope: { '2': h2, '10': h1 }, '2': h2, '10': h1 } })
+            const decoded = validate(revision)
+            assert(decoded[0] === 'ok', ['expected ok', decoded])
+            assert(encodeText(decoded[1]).includes(
+                `"lock":{"10":"${h1}","2":"${h2}","scope":{"10":"${h1}","2":"${h2}"}}`))
+        },
+        // Two nested maps differing only in property order converge on one
+        // byte sequence, so they address the same CAS blob.
+        equivalentNestedLockOrdersConverge: () => {
+            const a = validate(revisionOf({ lock: { B: { B: h1, D: h2 }, C: { D: h1 } } }))
+            const b = validate(revisionOf({ lock: { C: { D: h1 }, B: { D: h2, B: h1 } } }))
+            assert(a[0] === 'ok', ['expected ok', a])
+            assert(b[0] === 'ok', ['expected ok', b])
+            assertEq(encodeText(a[1]), encodeText(b[1]))
+        },
+        // A shared-lock reference serializes as the plain string it is — no
+        // wrapper, no marker: the two forms are told apart by JSON type.
+        serializesSharedLockReferenceAsAString: () => {
+            const decoded = validate(revisionOf({ lock: h1 }))
+            assert(decoded[0] === 'ok', ['expected ok', decoded])
+            assert(encodeText(decoded[1]).includes(`"lock":"${h1}"`))
+        },
         preservesArrayOrder: () => {
             const decoded = validate(revisionOf({ parents: [h2, h1] }))
             assert(decoded[0] === 'ok', ['expected ok', decoded])
@@ -226,3 +316,4 @@ export const proof = {
 }
 
 void _lockMapAllowsMissingSubjects
+void _lockMapNests

package/fjs/media/revision/types.d.ts

@@ -1,15 +1,44 @@
 /**
  * Type-level API for `fjs/media/revision/module.f.mjs`: `LockMap`,
- * `Revision`, and `RevisionError`, derived from the module's own rtti
- * schemas.
+ * `LockSchema`, `LockField`, `LockFieldSchema`, `Revision`, and
+ * `RevisionError`.
+ *
+ * `LockMap` is written by hand rather than derived, so that the recursion
+ * reads directly, and is then pinned against the module's rtti schema with
+ * `Assert<Equal<LockMap, Ts<typeof lock>>>` — the same arrangement the JSON
+ * data model uses in [`../json/types.ts`](../json/types.ts). `LockSchema` is
+ * the schema side of the same recursion: `lock` cannot infer its own type
+ * (a `const` may not reference itself in its own initializer), so it carries
+ * this named annotation instead.
  *
  * @module
  */
 import type { Ts } from '../../types/rtti/ts/types.ts';
+import type { String as RttiString } from '../../types/rtti/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>;
+import type { revisionSchema } from './module.f.mjs';
+/**
+ * A set of subject-to-snapshot bindings supplied to dependency resolvers.
+ * A direct string value selects immutable content; a nested map scopes
+ * further bindings under that subject (see the README).
+ *
+ * Spelled inline rather than as `StringMap<string | LockMap>`: a type alias
+ * may not reference itself through another alias's instantiation (TS2456).
+ */
+export type LockMap = {
+    readonly [subject in string]?: string | LockMap;
+};
+/** The rtti schema type of `lock` — a record of `string | LockSchema`. */
+export type LockSchema = () => readonly ['record', () => readonly ['or', RttiString, LockSchema]];
+/**
+ * A revision's `lock` field: the bindings inline as a {@link LockMap}, or the
+ * cbase32 hash of a `vnd.fjs.lock` blob (`fjs/media/lock`) holding one to
+ * share. Only the top level admits a hash — a string *inside* a map is a
+ * dependency's content, unchanged.
+ */
+export type LockField = string | LockMap;
+/** The rtti schema type of `lockField` — a shared-lock reference or a lock map. */
+export type LockFieldSchema = () => readonly ['or', RttiString, LockSchema];
 /** 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. */

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,21 +28,54 @@
  * | `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 { Operation } from '../../effects/types.ts'
+ * @import { List } from '../../effects/list/types.ts'
+ * @import { IoChannel, IoResult } from '../../effects/node/types.ts'
+ * @import { Effect } from '../../effects/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';
-import type { Effect, Operation } from '../../effects/types.ts';
+import type { Operation } from '../../effects/types.ts';
 import type { List } from '../../effects/list/types.ts';
-import type { IoResult } from '../../effects/node/types.ts';
+import type { IoChannel } from '../../effects/node/types.ts';
+import type { Effect } from '../../effects/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, as
+ * the magic projection of the streaming detector below — one fold, read two
+ * ways, rather than a second copy of it.
+ *
+ * The two agree because `magicStep` returns a non-`scan` state unchanged, so
+ * both absorbing states are its fixed points. `detect`'s old loop stopped at
+ * the first one; `push` stops only once the *whole* verdict is settled and may
+ * keep folding for the UTF-8 factor after the magic state is `dead` — but a
+ * `dead` or `matched` magic cannot move again, so the final magic is the same
+ * either way. A signature still in `scan` at the end of the `Vec` — a prefix
+ * too short to complete any signature — reads as `null`.
+ *
+ * Cost follows `push`, which stops only once the whole verdict is settled, not
+ * once the magic state is. On a signature match or on non-text bytes that is
+ * still an early exit; on valid text it now reads the whole `Vec`, because the
+ * shared machine is still tracking the UTF-8 factor this function ignores
+ * (measured: 100 KB of ASCII, 1.2 ms before, 82 ms after). That is the same
+ * work {@link detectVec} already does on the same bytes, and `Vec` is capped at
+ * `maxLength`, so the cost is bounded rather than unbounded — but a caller
+ * scanning many large text blobs for signatures alone should know it is paying
+ * for the UTF-8 fold too.
+ *
+ * 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
@@ -87,11 +121,12 @@ export declare const finish: (s: DetectState) => 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.
+ * deriving `cas_get` metadata without ever materializing the blob. A stream that
+ * fails carries its failure out as this one's, through `step` rather than
+ * through a case in the loop.
  *
  * @template {Operation} O
- * @param {List<O, IoResult<Vec>>} stream
- * @returns {Effect<O, IoResult<DetectMeta>>}
+ * @param {List<O, Vec, IoChannel>} stream
+ * @returns {Effect<O, DetectMeta, IoChannel>}
  */
-export declare const detectStream: <O extends Operation>(stream: List<O, IoResult<Vec>>) => Effect<O, IoResult<DetectMeta>>;
+export declare const detectStream: <O extends Operation>(stream: List<O, Vec, IoChannel>) => Effect<O, DetectMeta, IoChannel>;

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

@@ -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,107 +28,51 @@
  * | `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 { Operation } from '../../effects/types.ts'
+ * @import { List } from '../../effects/list/types.ts'
+ * @import { IoChannel, IoResult } from '../../effects/node/types.ts'
+ * @import { Effect } from '../../effects/types.ts'
+ * @import { DetectMeta, DetectState, _MagicState, _Signature, _Utf8Detect } from './types.ts'
  */
 
-import { msb, fromSentinel, length, u8List } from '../../types/bit_vec/module.f.mjs'
-/** @import { Vec } from '../../types/bit_vec/types.ts' */
+import { msb, length, u8List } from '../../types/bit_vec/module.f.mjs'
 import { iterable } from '../../types/list/module.f.mjs'
-/** @import { Nullable } from '../../types/nullable/types.ts' */
-import { pure, step } from '../../effects/module.f.mjs'
-/** @import { Effect, Operation } from '../../effects/types.ts' */
-/** @import { List } from '../../effects/list/types.ts' */
-/** @import { IoResult } from '../../effects/node/types.ts' */
-import { ok, error } from '../../types/result/module.f.mjs'
+import { pureOk, step as ioStep } from '../../effects/module.f.mjs'
 import { isValidCodePoint, isTextCodePoint } from '../../text/code_point/module.f.mjs'
 import { utf8ByteToCodePointOp } from '../../text/utf8/module.f.mjs'
-/** @import { DetectMeta, DetectState, _MagicState, _Signature, _Utf8Detect } from './types.ts' */
-
-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.
- *
- * @type {readonly (readonly [Vec, string])[]}
- */
-const table = [
-    [sig(0x1_89_50_4e_47_0d_0a_1a_0an), 'image/png'],
-    [sig(0x1_ff_d8_ffn), '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(0x1_47_49_46_38_37_61n), 'image/gif'],
-    [sig(0x1_47_49_46_38_39_61n), 'image/gif'],
-    [sig(0x1_25_50_44_46_2dn), '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(0x1_50_4b_03_04n), 'application/zip'],
-    [sig(0x1_50_4b_05_06n), 'application/zip'],
-    [sig(0x1_50_4b_07_08n), '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(0x1_52_49_46_46n)
-const webp = sig(0x1_57_45_42_50n)
-
-/** @type {(bytes: Vec) => boolean} */
-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).
- *
- * @type {(bytes: Vec) => Nullable<string>}
- */
-export const detect = bytes => {
-    if (isWebp(bytes)) { return 'image/webp' }
-    for (const [s, m] of table) {
-        if (startsWith(s)(bytes)) { return m }
-    }
-    return null
-}
-
-// ── Streaming detector ────────────────────────────────────────────────────────────
+// ── Magic-byte signatures ─────────────────────────────────────────────────────────
 //
-// A byte-accepting state machine that derives the same `{ length, mime_type, type }`
-// metadata as the pure `detect` + UTF-8 path, but **without buffering the blob**.
-// It is the product of three independent folds over the byte stream — length,
-// magic-byte signature elimination, and a UTF-8 validity DFA — read off at
-// end-of-stream by `finish`. This lets `cas_get` inspect arbitrarily large blobs
-// (where a single `Vec` would overflow `maxLength`) in O(1) space, since the bulk
-// of a large blob costs only length counting once the verdict is fixed (see
-// `isSettled`: a magic match settles it immediately, a dead magic once utf8 fails).
+// The single declaration of what a signature is: a byte pattern the eliminator can
+// consume one byte at a time, with `null` for a wildcard byte. Both `detect` and
+// the streaming detector below eliminate against this one list, so a signature is
+// added or corrected in exactly one place.
 
-// 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.
 /** @type {readonly _Signature[]} */
 const signatures = [
     { pattern: [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a], mime: 'image/png' },
     { pattern: [0xff, 0xd8, 0xff], mime: 'image/jpeg' },
+    // Match the full GIF version headers ("GIF87a" / "GIF89a"), not just "GIF8",
+    // so opaque bytes that merely start with "GIF8" are not mistyped.
     { 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' },
+    // ZIP has three "PK" local-header variants: a normal entry, an empty
+    // archive (end-of-central-directory only), and a spanned archive.
     { pattern: [0x50, 0x4b, 0x03, 0x04], mime: 'application/zip' },
     { pattern: [0x50, 0x4b, 0x05, 0x06], mime: 'application/zip' },
     { pattern: [0x50, 0x4b, 0x07, 0x08], mime: 'application/zip' },
+    // WebP: "RIFF" at offset 0, "WEBP" at offset 8; the four bytes between are
+    // the little-endian file size, matched as wildcards.
     {
         pattern: [0x52, 0x49, 0x46, 0x46, null, null, null, null, 0x57, 0x45, 0x42, 0x50],
         mime: 'image/webp',
@@ -154,6 +99,52 @@ const magicStep = (m, byte) => {
 /** @type {(m: _MagicState) => Nullable<string>} */
 const magicMime = m => m.tag === 'matched' ? m.mime : null
 
+/**
+ * Detects the MIME type of `bytes` from its leading magic-byte signature, as
+ * the magic projection of the streaming detector below — one fold, read two
+ * ways, rather than a second copy of it.
+ *
+ * The two agree because `magicStep` returns a non-`scan` state unchanged, so
+ * both absorbing states are its fixed points. `detect`'s old loop stopped at
+ * the first one; `push` stops only once the *whole* verdict is settled and may
+ * keep folding for the UTF-8 factor after the magic state is `dead` — but a
+ * `dead` or `matched` magic cannot move again, so the final magic is the same
+ * either way. A signature still in `scan` at the end of the `Vec` — a prefix
+ * too short to complete any signature — reads as `null`.
+ *
+ * Cost follows `push`, which stops only once the whole verdict is settled, not
+ * once the magic state is. On a signature match or on non-text bytes that is
+ * still an early exit; on valid text it now reads the whole `Vec`, because the
+ * shared machine is still tracking the UTF-8 factor this function ignores
+ * (measured: 100 KB of ASCII, 1.2 ms before, 82 ms after). That is the same
+ * work {@link detectVec} already does on the same bytes, and `Vec` is capped at
+ * `maxLength`, so the cost is bounded rather than unbounded — but a caller
+ * scanning many large text blobs for signatures alone should know it is paying
+ * for the UTF-8 fold too.
+ *
+ * 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
+ *   the signature it might otherwise match).
+ *
+ * @type {(bytes: Vec) => Nullable<string>}
+ */
+export const detect = bytes => magicMime(push(detectInit)(bytes).magic)
+
+// ── Streaming detector ────────────────────────────────────────────────────────────
+//
+// A byte-accepting state machine that derives the same `{ length, mime_type, type }`
+// metadata as the pure `detect` + UTF-8 path, but **without buffering the blob**.
+// It is the product of three independent folds over the byte stream — length,
+// magic-byte signature elimination, and a UTF-8 validity DFA — read off at
+// end-of-stream by `finish`. This lets `cas_get` inspect arbitrarily large blobs
+// (where a single `Vec` would overflow `maxLength`) in O(1) space, since the bulk
+// of a large blob costs only length counting once the verdict is fixed (see
+// `isSettled`: a magic match settles it immediately, a dead magic once utf8 fails).
+
 /** @type {_Utf8Detect} */
 const utf8Init = { st: null, valid: true, text: true }
 
@@ -258,24 +249,23 @@ 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.
+ * deriving `cas_get` metadata without ever materializing the blob. A stream that
+ * fails carries its failure out as this one's, through `step` rather than
+ * through a case in the loop.
  *
  * @template {Operation} O
- * @param {List<O, IoResult<Vec>>} stream
- * @returns {Effect<O, IoResult<DetectMeta>>}
+ * @param {List<O, Vec, IoChannel>} stream
+ * @returns {Effect<O, DetectMeta, IoChannel>}
  */
 export const detectStream = stream => {
-    /** @type {(s: DetectState) => (l: List<O, IoResult<Vec>>) => Effect<O, IoResult<DetectMeta>>} */
+    /** @type {(s: DetectState) => (l: List<O, Vec, IoChannel>) => Effect<O, DetectMeta, IoChannel>} */
     const loop = s => l =>
-        step(
+        ioStep(
             l,
             node => {
-                if (node === undefined) { return pure(ok(finish(s))) }
+                if (node === undefined) { return pureOk(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(push(s)(first))(tail)
             })
     return loop(detectInit)(stream)
 }

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

@@ -1,3 +1,9 @@
+/**
+ * @import { Vec } from '../../types/bit_vec/types.ts'
+ * @import { List } from '../../effects/list/types.ts'
+ * @import { IoChannel } from '../../effects/node/types.ts'
+ * @import { DetectMeta } from './types.ts'
+ */
 export declare const proof: {
     png: () => void;
     jpeg: () => void;
@@ -7,11 +13,22 @@ export declare const proof: {
     pdf: () => void;
     zip: () => void;
     emptyZip: () => void;
+    spannedZip: () => void;
     webp: () => void;
     riffNotWebp: () => void;
+    settledMagicIsAFixedPoint: (() => void)[];
     textIsNull: () => void;
     shortIsNull: () => void;
     emptyIsNull: () => void;
+    truncated: {
+        png: () => void;
+        jpeg: () => void;
+        gif87a: () => void;
+        gif89a: () => void;
+        pdf: () => void;
+        zip: () => void;
+        webp: () => void;
+    };
     stream: {
         text: () => void;
         png: () => void;