functionalscript 0.43.1 → 0.45.0

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

@@ -0,0 +1,265 @@
+/**
+ * Magic-byte MIME type detection.
+ *
+ * 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 `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
+ * `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 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 { msb, length, u8List } from '../../types/bit_vec/module.f.mjs'
+import { iterable } from '../../types/list/module.f.mjs'
+import { pure, step } from '../../effects/module.f.mjs'
+import { ok, error } from '../../types/result/module.f.mjs'
+import { isValidCodePoint, isTextCodePoint } from '../../text/code_point/module.f.mjs'
+import { utf8ByteToCodePointOp } from '../../text/utf8/module.f.mjs'
+
+// ── Magic-byte signatures ─────────────────────────────────────────────────────────
+//
+// 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.
+
+/** @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',
+    },
+]
+
+/** @type {_MagicState} */
+const magicInit = { tag: 'scan', pos: 0, viable: signatures }
+
+/** @type {(m: _MagicState, byte: number) => _MagicState} */
+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 }
+}
+
+/** @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 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
+ *   the signature it might otherwise match).
+ *
+ * @type {(bytes: Vec) => Nullable<string>}
+ */
+export const detect = bytes => {
+    /** @type {_MagicState} */
+    let magic = magicInit
+    for (const byte of iterable(u8List(msb)(bytes))) {
+        magic = magicStep(magic, byte)
+        if (magic.tag !== 'scan') { break }
+    }
+    return magicMime(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 }
+
+/** @type {(u: _Utf8Detect, byte: number) => _Utf8Detect} */
+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 }
+}
+
+/** @type {(u: _Utf8Detect) => boolean} */
+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).
+/** @type {(u: _Utf8Detect) => boolean} */
+const utf8Text = u => utf8Valid(u) && u.text
+
+/** The initial detector state `q₀`.
+ *
+ * @type {DetectState}
+ */
+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.
+/** @type {(magic: _MagicState, utf8: _Utf8Detect) => boolean} */
+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.
+ *
+ * @type {(s: DetectState) => (chunk: Vec) => DetectState}
+ */
+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.
+ *
+ * @type {(s: DetectState) => DetectMeta}
+ */
+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 & 0b111n) === 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.
+ *
+ * @type {(bytes: Vec) => DetectMeta}
+ */
+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.
+ *
+ * @template {Operation} O
+ * @param {List<O, IoResult<Vec>>} stream
+ * @returns {Effect<O, IoResult<DetectMeta>>}
+ */
+export const detectStream = stream => {
+    /** @type {(s: DetectState) => (l: List<O, IoResult<Vec>>) => Effect<O, IoResult<DetectMeta>>} */
+    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)
+}

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

@@ -0,0 +1,56 @@
+/**
+ * @import { Vec } from '../../types/bit_vec/types.ts'
+ * @import { List } from '../../effects/list/types.ts'
+ * @import { Result } from '../../types/result/types.ts'
+ * @import { DetectMeta } from './types.ts'
+ */
+export declare const proof: {
+    png: () => void;
+    jpeg: () => void;
+    gif89a: () => void;
+    gif87a: () => void;
+    gif8NotGif: () => void;
+    pdf: () => void;
+    zip: () => void;
+    emptyZip: () => void;
+    spannedZip: () => void;
+    webp: () => void;
+    riffNotWebp: () => 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;
+        octetStream: () => void;
+        nul: () => void;
+        controlByte: () => void;
+        c1Control: () => void;
+        whitespaceControlsStayText: () => void;
+        magicAcrossChunks: () => void;
+        webp: () => void;
+        utf8AcrossChunks: () => void;
+        validUntilTrailingInvalidByte: () => void;
+        truncatedSequence: () => void;
+        largeMultiChunkBlob: () => void;
+        pdfThenLargeTextTail: () => void;
+        pdfThenBinaryTail: () => void;
+        readErrorSurfaces: () => void;
+        empty: () => void;
+    };
+    vec: {
+        text: () => void;
+        png: () => void;
+        octetStream: () => void;
+        nul: () => void;
+    };
+};

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

@@ -0,0 +1,325 @@
+/**
+ * @import { Vec } from '../../types/bit_vec/types.ts'
+ * @import { List } from '../../effects/list/types.ts'
+ * @import { Result } from '../../types/result/types.ts'
+ * @import { DetectMeta } from './types.ts'
+ */
+
+import { assert, assertEq } from '../../asserts/module.f.mjs'
+import { msb, u8ListToVec, vec8, repeat, empty } from '../../types/bit_vec/module.f.mjs'
+import { runPure } from '../../effects/module.f.mjs'
+import { nonEmpty, empty as emptyList } from '../../effects/list/module.f.mjs'
+import { ok } from '../../types/result/module.f.mjs'
+import { detect, detectStream, detectVec } from './module.f.mjs'
+
+// Builds a big-endian `Vec` from a list of byte values — mirrors how the CAS
+// store would hold the leading bytes of a stored blob.
+/** @type {(...b: readonly number[]) => Vec} */
+const bytes = (...b) => u8ListToVec(msb)(b)
+
+// ── Streaming detector helpers ──────────────────────────────────────────────────
+
+// Builds a CAS-style read stream from a sequence of ok(chunk) items.
+/** @type {(...chunks: readonly Vec[]) => List<never, Result<Vec, unknown>>} */
+const stream = (...chunks) =>
+    chunks.reduceRight(
+        (tail, c) => nonEmpty(ok(c), tail),
+        /** @type {List<never, Result<Vec, unknown>>} */ (emptyList()))
+
+// Runs the streaming detector over the given chunks and unwraps the metadata.
+/** @type {(...chunks: readonly Vec[]) => DetectMeta} */
+const detectChunks = (...chunks) => {
+    const o = runPure(detectStream(stream(...chunks)))
+    assert(o.length === 1, 'effect is not pure')
+    const [r] = o
+    assert(r[0] !== 'error', r[1])
+    return r[1]
+}
+
+export const proof = {
+    png: () =>
+        assertEq(detect(bytes(0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a)), 'image/png'),
+
+    jpeg: () =>
+        assertEq(detect(bytes(0xff, 0xd8, 0xff, 0xe0)), 'image/jpeg'),
+
+    gif89a: () =>
+        assertEq(detect(bytes(0x47, 0x49, 0x46, 0x38, 0x39, 0x61)), 'image/gif'),
+
+    gif87a: () =>
+        assertEq(detect(bytes(0x47, 0x49, 0x46, 0x38, 0x37, 0x61)), 'image/gif'),
+
+    // "GIF8" alone, without a valid version suffix, is not a GIF.
+    gif8NotGif: () =>
+        assertEq(detect(bytes(0x47, 0x49, 0x46, 0x38, 0x30, 0x30)), null),
+
+    pdf: () =>
+        // "%PDF-1.4"
+        assertEq(detect(bytes(0x25, 0x50, 0x44, 0x46, 0x2d, 0x31, 0x2e, 0x34)), 'application/pdf'),
+
+    zip: () =>
+        assertEq(detect(bytes(0x50, 0x4b, 0x03, 0x04, 0x14, 0x00)), 'application/zip'),
+
+    // An empty ZIP archive starts with the end-of-central-directory record.
+    emptyZip: () =>
+        assertEq(detect(bytes(0x50, 0x4b, 0x05, 0x06, 0x00, 0x00)), 'application/zip'),
+
+    // A spanned ZIP archive — the third "PK" variant, so every entry of the
+    // signature list has a case that fails if it is dropped.
+    spannedZip: () =>
+        assertEq(detect(bytes(0x50, 0x4b, 0x07, 0x08, 0x00, 0x00)), 'application/zip'),
+
+    webp: () =>
+        // "RIFF" + 4-byte size + "WEBP"
+        assertEq(
+            detect(bytes(
+                0x52, 0x49, 0x46, 0x46, 0x1a, 0x00, 0x00, 0x00, 0x57, 0x45, 0x42, 0x50)),
+            'image/webp'),
+
+    // "RIFF…" without the "WEBP" marker (e.g. a WAV) is not WebP.
+    riffNotWebp: () =>
+        assertEq(
+            detect(bytes(
+                0x52, 0x49, 0x46, 0x46, 0x1a, 0x00, 0x00, 0x00, 0x57, 0x41, 0x56, 0x45)),
+            null),
+
+    // Plain ASCII text matches no signature.
+    textIsNull: () =>
+        assertEq(detect(bytes(0x68, 0x65, 0x6c, 0x6c, 0x6f)), null),
+
+    // A prefix shorter than any signature falls through to null, not a partial match.
+    shortIsNull: () =>
+        assertEq(detect(bytes(0x89, 0x50)), null),
+
+    emptyIsNull: () =>
+        assertEq(detect(empty), null),
+
+    // Every signature, one byte short of complete. A signature is only ever
+    // recognized on its *last* byte, so each of these must still be null — an
+    // off-by-one in the eliminator's terminal-position test would report the
+    // format here, and would fire the "GIF8"-prefix trap `gif8NotGif` guards.
+    truncated: {
+        png: () =>
+            assertEq(detect(bytes(0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a)), null),
+
+        jpeg: () =>
+            assertEq(detect(bytes(0xff, 0xd8)), null),
+
+        gif87a: () =>
+            assertEq(detect(bytes(0x47, 0x49, 0x46, 0x38, 0x37)), null),
+
+        gif89a: () =>
+            assertEq(detect(bytes(0x47, 0x49, 0x46, 0x38, 0x39)), null),
+
+        pdf: () =>
+            assertEq(detect(bytes(0x25, 0x50, 0x44, 0x46)), null),
+
+        zip: () =>
+            assertEq(detect(bytes(0x50, 0x4b, 0x03)), null),
+
+        // 11 bytes: "RIFF", the size wildcards, and all but the last byte of
+        // "WEBP" — the wildcard run must not shorten the pattern either.
+        webp: () =>
+            assertEq(
+                detect(bytes(
+                    0x52, 0x49, 0x46, 0x46, 0x1a, 0x00, 0x00, 0x00, 0x57, 0x45, 0x42)),
+                null),
+    },
+
+    // ── Streaming detector (detectStream) ───────────────────────────────────────
+
+    stream: {
+        // Plain UTF-8 text classifies as text/plain with the correct byte length.
+        text: () => {
+            const m = detectChunks(bytes(0x68, 0x65, 0x6c, 0x6c, 0x6f)) // "hello"
+            assertEq(m.type, 'text')
+            assertEq(m.mime_type, 'text/plain')
+            assertEq(m.length, 5n)
+        },
+
+        // A magic-byte signature classifies as base64 with the detected mime type.
+        png: () => {
+            const m = detectChunks(bytes(0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x01))
+            assertEq(m.type, 'base64')
+            assertEq(m.mime_type, 'image/png')
+            assertEq(m.length, 10n)
+        },
+
+        // Unknown binary (no signature, not UTF-8) falls back to octet-stream/base64.
+        octetStream: () => {
+            const m = detectChunks(bytes(0xff, 0xfe, 0x00, 0x01))
+            assertEq(m.type, 'base64')
+            assertEq(m.mime_type, 'application/octet-stream')
+            assertEq(m.length, 4n)
+        },
+
+        // A NUL-byte blob is valid single-byte UTF-8 (all U+0000) but is binary:
+        // NUL is the sharpest binary marker, so it classifies as octet-stream.
+        nul: () => {
+            const m = detectChunks(bytes(0x00, 0x00, 0x00))
+            assertEq(m.type, 'base64')
+            assertEq(m.mime_type, 'application/octet-stream')
+            assertEq(m.length, 3n)
+        },
+
+        // A control byte embedded in otherwise-valid ASCII (here ESC) is still
+        // binary — text/plain must not imply terminal escapes.
+        controlByte: () => {
+            const m = detectChunks(bytes(0x68, 0x69, 0x1b, 0x5b, 0x30, 0x6d)) // "hi\x1b[0m"
+            assertEq(m.type, 'base64')
+            assertEq(m.mime_type, 'application/octet-stream')
+            assertEq(m.length, 6n)
+        },
+
+        // A C1 control arrives as 2-byte UTF-8 (C2 85 = U+0085, NEL); invisible at
+        // the byte level, it is caught at the code-point level and reads as binary.
+        c1Control: () => {
+            const m = detectChunks(bytes(0x41, 0xc2, 0x85)) // "A" + U+0085
+            assertEq(m.type, 'base64')
+            assertEq(m.mime_type, 'application/octet-stream')
+            assertEq(m.length, 3n)
+        },
+
+        // The text whitespace controls (TAB, LF, VT, FF, CR) are legitimate in text.
+        whitespaceControlsStayText: () => {
+            const m = detectChunks(bytes(0x61, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x62)) // "a\t\n\v\f\rb"
+            assertEq(m.type, 'text')
+            assertEq(m.mime_type, 'text/plain')
+            assertEq(m.length, 7n)
+        },
+
+        // Magic-byte detection threads across a chunk boundary mid-signature.
+        magicAcrossChunks: () => {
+            const m = detectChunks(
+                bytes(0x89, 0x50, 0x4e),                   // first 3 bytes of the PNG signature
+                bytes(0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00)) // the rest, in a second chunk
+            assertEq(m.type, 'base64')
+            assertEq(m.mime_type, 'image/png')
+            assertEq(m.length, 9n)
+        },
+
+        // WebP's wildcard size gap is handled in the streaming form too.
+        webp: () => {
+            const m = detectChunks(
+                bytes(0x52, 0x49, 0x46, 0x46),             // "RIFF"
+                bytes(0x1a, 0x00, 0x00, 0x00),             // 4-byte size (wildcards)
+                bytes(0x57, 0x45, 0x42, 0x50))             // "WEBP"
+            assertEq(m.type, 'base64')
+            assertEq(m.mime_type, 'image/webp')
+            assertEq(m.length, 12n)
+        },
+
+        // A multi-byte UTF-8 sequence split across chunks stays valid text.
+        utf8AcrossChunks: () => {
+            const m = detectChunks(bytes(0xc3), bytes(0xa9)) // "é" = C3 A9
+            assertEq(m.type, 'text')
+            assertEq(m.mime_type, 'text/plain')
+            assertEq(m.length, 2n)
+        },
+
+        // The decisive case: valid UTF-8 for every chunk but the last, which adds a
+        // lone invalid byte. A leading-bytes buffer would wrongly say "text"; the
+        // streaming validator sees the whole blob and classifies it as base64.
+        validUntilTrailingInvalidByte: () => {
+            const m = detectChunks(
+                bytes(0x68, 0x65, 0x6c, 0x6c, 0x6f),       // "hello" — valid UTF-8
+                bytes(0xff))                               // trailing invalid byte
+            assertEq(m.type, 'base64')
+            assertEq(m.mime_type, 'application/octet-stream')
+            assertEq(m.length, 6n)
+        },
+
+        // A truncated multi-byte sequence at EOF is invalid UTF-8, hence base64.
+        truncatedSequence: () => {
+            const m = detectChunks(bytes(0xc3)) // lead byte with no continuation
+            assertEq(m.type, 'base64')
+            assertEq(m.mime_type, 'application/octet-stream')
+            assertEq(m.length, 1n)
+        },
+
+        // A blob larger than `maxLength` (1,048,576 bits) split across chunks — the
+        // exact case where `collectRead` would error — returns correct metadata.
+        largeMultiChunkBlob: () => {
+            const a = repeat(70_000n)(vec8(0x61n)) // 70,000 bytes of 'a' (560,000 bits)
+            const m = detectChunks(a, a)           // 140,000 bytes = 1,120,000 bits > maxLength
+            assertEq(m.type, 'text')
+            assertEq(m.mime_type, 'text/plain')
+            assertEq(m.length, 140_000n)
+        },
+
+        // A magic match settles the verdict on its own: a large magic-matched blob
+        // whose tail stays valid UTF-8 (an ASCII PDF) classifies by the signature.
+        // `push` stops decoding the tail once `magic` is matched — `finish` ignores
+        // the utf8 verdict here — so this is the magic-matched fast path.
+        pdfThenLargeTextTail: () => {
+            const header = bytes(0x25, 0x50, 0x44, 0x46, 0x2d) // "%PDF-"
+            const tail = repeat(70_000n)(vec8(0x61n))          // valid ASCII, never invalidates utf8
+            const m = detectChunks(header, tail)
+            assertEq(m.type, 'base64')
+            assertEq(m.mime_type, 'application/pdf')
+            assertEq(m.length, 70_005n)
+        },
+
+        // A magic match wins regardless of the tail: a binary (non-UTF-8) tail
+        // after the signature is still classified by the signature.
+        pdfThenBinaryTail: () => {
+            const header = bytes(0x25, 0x50, 0x44, 0x46, 0x2d) // "%PDF-"
+            const m = detectChunks(header, bytes(0xff, 0xfe, 0x00))
+            assertEq(m.type, 'base64')
+            assertEq(m.mime_type, 'application/pdf')
+            assertEq(m.length, 8n)
+        },
+
+        // A read `error` item short-circuits into the IoResult error.
+        readErrorSurfaces: () => {
+            /** @type {List<never, Result<Vec, unknown>>} */
+            const errStream =
+                nonEmpty(/** @type {const} */ (['error', 'boom']), emptyList())
+            const o = runPure(detectStream(errStream))
+            assert(o.length === 1, 'effect is not pure')
+            assert(o[0][0] === 'error')
+        },
+
+        // Empty stream: zero-length text/plain.
+        empty: () => {
+            const m = detectChunks()
+            assertEq(m.type, 'text')
+            assertEq(m.length, 0n)
+        },
+    },
+
+    // ── Single-Vec detector (detectVec) ─────────────────────────────────────────
+    // The whole-Vec form used by the `cas_get` content:true path; same machine,
+    // same three-way verdict as the streaming form.
+
+    vec: {
+        text: () => {
+            const m = detectVec(bytes(0x68, 0x65, 0x6c, 0x6c, 0x6f)) // "hello"
+            assertEq(m.type, 'text')
+            assertEq(m.mime_type, 'text/plain')
+            assertEq(m.length, 5n)
+        },
+
+        png: () => {
+            const m = detectVec(bytes(0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x01))
+            assertEq(m.type, 'base64')
+            assertEq(m.mime_type, 'image/png')
+            assertEq(m.length, 10n)
+        },
+
+        octetStream: () => {
+            const m = detectVec(bytes(0xff, 0xfe, 0x00, 0x01))
+            assertEq(m.type, 'base64')
+            assertEq(m.mime_type, 'application/octet-stream')
+            assertEq(m.length, 4n)
+        },
+
+        // Valid UTF-8 NUL run is binary in the single-Vec path too.
+        nul: () => {
+            const m = detectVec(bytes(0x00, 0x00, 0x00))
+            assertEq(m.type, 'base64')
+            assertEq(m.mime_type, 'application/octet-stream')
+            assertEq(m.length, 3n)
+        },
+    },
+}