functionalscript 0.33.0 → 0.34.0

package/fs/effects/list/module.f.d.ts

@@ -0,0 +1,31 @@
+import { type Effect, type Operation } from "../module.f.ts";
+export type NonEmpty<O extends Operation, T> = {
+    readonly first: T;
+    readonly tail: List<O, T>;
+};
+/**
+ * The payload of a `List` effect: the next cons cell, or `undefined` at
+ * end-of-stream.
+ *
+ * Since `Pure<T>` is now itself a lazy thunk (`() => T`), the effect alone is the
+ * suspension point and the cell needs no extra wrapping thunk. `Effect<O, Next<O, T>>`
+ * is used directly in places where `List<O, T>` cannot be written as a return type
+ * (see {@link empty}).
+ */
+export type Next<O extends Operation, T> = NonEmpty<O, T> | undefined;
+export type List<O extends Operation, T> = Effect<O, Next<O, T>>;
+/**
+ * The empty `List`: a pure end-of-stream marker (`undefined`).
+ *
+ * The explicit `Effect<O, Next<O, T>>` return type lets the contextual type drive the
+ * check, so the recursive payload type-checks without a cast. Construct streams through
+ * these two combinators.
+ *
+ * Note: we use `Effect<O, Next<O, T>>` because TypeScript can't convert `pure(...)` to
+ *       `List<O, T>`.
+ */
+export declare const empty: <O extends Operation, T>() => Effect<O, Next<O, T>>;
+/**
+ * Prepends `head` to a `ListEffect` `tail`, as a pure cons cell. See {@link empty}.
+ */
+export declare const nonEmpty: <O extends Operation, T>(first: T, tail: List<O, T>) => Effect<O, Next<O, T>>;

package/fs/effects/list/module.f.js

@@ -0,0 +1,16 @@
+import { pure } from "../module.f.js";
+/**
+ * The empty `List`: a pure end-of-stream marker (`undefined`).
+ *
+ * The explicit `Effect<O, Next<O, T>>` return type lets the contextual type drive the
+ * check, so the recursive payload type-checks without a cast. Construct streams through
+ * these two combinators.
+ *
+ * Note: we use `Effect<O, Next<O, T>>` because TypeScript can't convert `pure(...)` to
+ *       `List<O, T>`.
+ */
+export const empty = () => pure(undefined);
+/**
+ * Prepends `head` to a `ListEffect` `tail`, as a pure cons cell. See {@link empty}.
+ */
+export const nonEmpty = (first, tail) => pure({ first, tail });

package/fs/effects/module.f.d.ts

@@ -10,12 +10,19 @@ export type Effect<O extends Operation, T> = {
     step: <Q extends Operation, R>(f: (p: T) => Effect<Q, R>) => Effect<O | Q, R>;
 };
 export type Value<O extends Operation, T> = Pure<T> | Do<O, T>;
-export type Pure<T> = readonly [T];
+export type Pure<T> = () => T;
 export type DoKPR<O extends Operation, T, K extends string, PR extends readonly [unknown, unknown]> = readonly [K, PR[0], (_: PR[1]) => Effect<O, T>];
 export type Pr<O extends Operation, K extends O[0]> = O extends readonly [K, (...args: infer P) => infer R] ? readonly [P, R] : never;
 export type DoK<O extends Operation, T, K extends O[0]> = DoKPR<O, T, K, Pr<O, K>>;
 export type Do<O extends Operation, T> = DoK<O, T, O[0]>;
 export declare const pure: <T>(v: T) => Effect<never, T>;
+/**
+ * A lazy pure effect. Like {@link pure}, but takes a thunk and evaluates it on
+ * demand instead of holding an already-computed value. Use this to produce the
+ * next item of a list without instantiating the rest — the thunk runs only when
+ * the effect is decoded (or stepped into).
+ */
+export declare const lazy: <T>(t: () => T) => Effect<never, T>;
 export declare const doFull: <O extends Operation, T, K extends O[0]>(cmd: K, param: Pr<O, K>[0], cont: (input: Pr<O, K>[1]) => Effect<O, T>) => Effect<O, T>;
 export type Param<O extends Operation> = F<O>[0];
 export type Return<O extends Operation> = F<O>[1];
@@ -53,10 +60,10 @@ export type Decoded<O extends Operation, T> = {
 /**
  * Decodes an effect's next step: a pure result, or a command to perform.
  *
- * This is the only function that knows how `Value` is laid out (a length-1
- * tuple for `Pure`, a `[command, payload, continuation]` tuple for `Do`).
+ * This is the only function that knows how `Value` is laid out (a thunk
+ * `() => T` for `Pure`, a `[command, payload, continuation]` tuple for `Do`).
  * Interpreters and proofs must go through `decode` (or `match`) instead of
- * inspecting the tuple, so the representation can change without touching
+ * inspecting the value, so the representation can change without touching
  * them.
  */
 export declare const decode: <O extends Operation, T>({ value }: Effect<O, T>) => Decoded<O, T>;
@@ -82,4 +89,3 @@ export type ToAsyncOperationMap<O extends Operation> = {
 };
 export type F<O extends Operation> = Pr<O, O[0]>;
 export type Func<O extends Operation> = (..._: Param<O>) => Effect<O, Return<O>>;
-export type ListEffect<O extends Operation, T> = Effect<O, readonly [T, ListEffect<O, T>] | undefined>;

package/fs/effects/module.f.js

@@ -5,9 +5,19 @@
  */
 import { fold } from "../types/list/module.f.js";
 export const pure = (v) => ({
-    value: [v],
+    value: () => v,
     step: f => f(v)
 });
+/**
+ * A lazy pure effect. Like {@link pure}, but takes a thunk and evaluates it on
+ * demand instead of holding an already-computed value. Use this to produce the
+ * next item of a list without instantiating the rest — the thunk runs only when
+ * the effect is decoded (or stepped into).
+ */
+export const lazy = (t) => ({
+    value: t,
+    step: f => f(t())
+});
 export const doFull = (cmd, param, cont) => ({
     value: [cmd, param, cont],
     step: (f) => doFull(cmd, param, x => cont(x).step(f)),
@@ -32,14 +42,14 @@ export const forEachStep = (f) => (items) => foldStep((item) => () => f(item))(u
 /**
  * Decodes an effect's next step: a pure result, or a command to perform.
  *
- * This is the only function that knows how `Value` is laid out (a length-1
- * tuple for `Pure`, a `[command, payload, continuation]` tuple for `Do`).
+ * This is the only function that knows how `Value` is laid out (a thunk
+ * `() => T` for `Pure`, a `[command, payload, continuation]` tuple for `Do`).
  * Interpreters and proofs must go through `decode` (or `match`) instead of
- * inspecting the tuple, so the representation can change without touching
+ * inspecting the value, so the representation can change without touching
  * them.
  */
-export const decode = ({ value }) => value.length === 1
-    ? { done: true, result: value[0] }
+export const decode = ({ value }) => typeof value === 'function'
+    ? { done: true, result: value() }
     : { done: false, command: value[0], payload: value[1], continuation: value[2] };
 /**
  * Decodes an effect's next step and dispatches its command to `map`,

package/fs/effects/node/module.f.d.ts

@@ -1,9 +1,10 @@
-import type { Vec } from '../../types/bit_vec/module.f.ts';
+import { type Vec } from '../../types/bit_vec/module.f.ts';
 import type { MemOp } from '../memory/module.f.ts';
 import type { Nominal } from '../../types/nominal/module.f.ts';
 import { type Result } from '../../types/result/module.f.ts';
 import type { StringMap } from '../../types/object/module.f.ts';
 import { type Effect, type Func, type Operation, type ToAsyncOperationMap } from '../module.f.ts';
+import type { List } from '../list/module.f.ts';
 export type IoResult<T> = Result<T, unknown>;
 /**
  * True if `e` is a "file or directory does not exist" (`ENOENT`) error.
@@ -81,7 +82,32 @@ export type Exec = readonly ['exec', (command: string, stdin?: string) => IoResu
 export declare const exec: Func<Exec>;
 export type Access = readonly ['access', (path: string) => IoResult<void>];
 export declare const access: Func<Access>;
-export type Fs = Mkdir | ReadFile | ReadBytes | Readdir | WriteFile | Rm | Rename | Exec | Access;
+/**
+ * Creates `path` as an empty file with `O_CREAT|O_EXCL` — fails if it already
+ * exists. This is the exclusive create that claims a staging name in the
+ * lock-free upload ([staging-lease.md](../../../issues/cas/staging-lease.md));
+ * with 256 random bits in the name `EEXIST` never happens in practice, so it
+ * is just a sanity guard.
+ */
+export type CreateExclusive = readonly ['createExclusive', (path: string) => IoResult<void>];
+export declare const createExclusive: Func<CreateExclusive>;
+/**
+ * Writes the **entire** `data` vector to an **existing** `path` at byte `offset`
+ * (positional write). The mirror of {@link readBytes}: it never creates the file
+ * (a missing path is `ENOENT`), and it writes every byte or returns an error —
+ * the runner loops over short writes — so a later size check can never pass over
+ * a hole. Bounded to ≤128 KiB per call, like `readBytes`.
+ */
+export type WriteBytes = readonly ['writeBytes', (path: string, offset: number, data: Vec) => IoResult<void>];
+export declare const writeBytes: Func<WriteBytes>;
+export declare const writeFromStream: <O extends Operation>(path: string, e: List<O, IoResult<Vec>>) => Effect<O | WriteBytes | CreateExclusive, IoResult<void>>;
+/** File metadata returned by {@link stat}. Only `size` (in bytes) for now. */
+export type FileStat = {
+    readonly size: number;
+};
+export type Stat = readonly ['stat', (path: string) => IoResult<FileStat>];
+export declare const stat: Func<Stat>;
+export type Fs = Mkdir | ReadFile | ReadBytes | Readdir | WriteFile | Rm | Rename | Exec | Access | CreateExclusive | WriteBytes | Stat;
 export type Server = Nominal<'server', `160855c4f69310fece3273c1853ac32de43dee1eb41bf59d821917f8eebe9272`, unknown>;
 export type Headers = StringMap<string, string>;
 export type IncomingMessage = {
@@ -216,7 +242,7 @@ export type TestContext = {
 /** Effect operation that registers a named test with the active `TestContext`. */
 export type Test = readonly ['test', (ctx: TestContext, name: string, expectFailure: boolean, test: (t: TestContext) => Effect<Test | All | Await, void>) => void];
 export declare const test: Func<Test>;
-export type NodeOp = All | Await | Fetch | Fs | Http | Forever | Import | MemOp | Now | RandomInt | Read | Sandbox | Write | Test;
+export type NodeOp = Access | All | Await | Fetch | Fs | Http | Forever | Import | MemOp | Now | RandomInt | Read | Sandbox | Write | Test;
 export type NodeEffect<T> = Effect<NodeOp, T>;
 /**
  * Writes an error line to `stderr` and yields exit code `1`. The canonical

package/fs/effects/node/module.f.js

@@ -12,7 +12,8 @@ import { utf8, utf8ToString } from "../../text/module.f.js";
 import { toCodePointList } from "../../text/utf8/module.f.js";
 import { codePointListToString } from "../../text/utf16/module.f.js";
 import { reverse } from "../../types/list/module.f.js";
-import { ok } from "../../types/result/module.f.js";
+import { length } from "../../types/bit_vec/module.f.js";
+import { ok, error as resultError } from "../../types/result/module.f.js";
 import { do_, pure } from "../module.f.js";
 /**
  * True if `e` is a "file or directory does not exist" (`ENOENT`) error.
@@ -53,6 +54,39 @@ export const readBytes = do_('readBytes');
 export const randomInt = do_('randomInt');
 export const exec = do_('exec');
 export const access = do_('access');
+export const createExclusive = do_('createExclusive');
+export const writeBytes = do_('writeBytes');
+const writeLoop = (path) => {
+    const f = (offset, e) => e.step(r => {
+        if (r === undefined) {
+            return pure(ok(undefined));
+        }
+        const { first: [t, v], tail } = r;
+        if (t === 'error') {
+            return pure(resultError(v));
+        }
+        const lenV = length(v);
+        if ((lenV & 7n) !== 0n) {
+            return pure(resultError('invalid buffer size'));
+        }
+        return writeBytes(path, offset, v)
+            .step((r) => {
+            if (r[0] === 'error') {
+                return pure(r);
+            }
+            return f(offset + Number(lenV >> 3n), tail);
+        });
+    });
+    return f;
+};
+export const writeFromStream = (path, e) => createExclusive(path)
+    .step(([r, v]) => {
+    if (r === 'error') {
+        return pure(resultError(v));
+    }
+    return writeLoop(path)(0, e);
+});
+export const stat = do_('stat');
 export const createServer = do_('createServer');
 export const listen = do_('listen');
 export const forever = do_('forever');

package/fs/effects/node/module.js

@@ -35,6 +35,7 @@ import { memoryOperationMap } from "./memory/module.js";
 import {} from "./module.f.js";
 import { asBase, asNominal } from "../../types/nominal/module.f.js";
 import { error, ok } from "../../types/result/module.f.js";
+import { asyncTryCatch } from "../../types/result/module.js";
 import { fromVec, listToVec, toVec } from "../../types/uint8array/module.f.js";
 import { maxLengthBytes } from "../../types/bit_vec/module.f.js";
 /**
@@ -44,14 +45,6 @@ import { maxLengthBytes } from "../../types/bit_vec/module.f.js";
  * requires them present; this local view keeps the narrowing in one place.
  */
 const createServer = http.createServer;
-const tc = async (f) => {
-    try {
-        return ok(await f());
-    }
-    catch (e) {
-        return error(e);
-    }
-};
 const collect = async (v) => {
     let result = [];
     for await (const a of v) {
@@ -156,15 +149,15 @@ const readStdinByte = async () => {
 const runNodeEffect = asyncRun({
     ...memoryOperationMap(),
     all: async (...effects) => await Promise.all(effects.map(runNodeEffect)),
-    fetch: async (url) => tc(async () => {
+    fetch: async (url) => asyncTryCatch(async () => {
         const response = await fetch(url);
         if (!response.ok) {
             throw new Error(`Fetch error: ${response.status} ${response.statusText}`);
         }
         return toVec(new Uint8Array(await response.arrayBuffer()));
     }),
-    mkdir: (...p) => tc(async () => { await mkdir(...p); }),
-    readFile: path => tc(async () => {
+    mkdir: (...p) => asyncTryCatch(async () => { await mkdir(...p); }),
+    readFile: path => asyncTryCatch(async () => {
         const fileStats = await stat(path);
         // if the file is too big, toVec should fail anyway but in this case we don't want to load the file.
         if (fileStats.size > maxFileSizeBytes) {
@@ -172,16 +165,16 @@ const runNodeEffect = asyncRun({
         }
         return toVec(await readFile(path));
     }),
-    readdir: (path, r) => tc(async () => (await readdir(path, { ...r, withFileTypes: true }))
+    readdir: (path, r) => asyncTryCatch(async () => (await readdir(path, { ...r, withFileTypes: true }))
         .map(v => ({
         name: v.name,
         parentPath: normalize(v.parentPath),
         isFile: v.isFile()
     }))),
-    writeFile: (path, data) => tc(() => writeFile(path, fromVec(data))),
-    rm: path => tc(() => rm(path)),
-    rename: (src, dst) => tc(() => rename(src, dst)),
-    readBytes: (path, offset, size) => tc(async () => {
+    writeFile: (path, data) => asyncTryCatch(() => writeFile(path, fromVec(data))),
+    rm: path => asyncTryCatch(() => rm(path)),
+    rename: (src, dst) => asyncTryCatch(() => rename(src, dst)),
+    readBytes: (path, offset, size) => asyncTryCatch(async () => {
         if (offset < 0) {
             throw new Error(`Offset ${offset} is negative`);
         }
@@ -199,8 +192,29 @@ const runNodeEffect = asyncRun({
         }
     }),
     randomInt: async () => crypto.randomInt(2 ** 32),
-    access: path => tc(() => access(path)),
-    import: path => tc(() => asyncImport(path)),
+    access: path => asyncTryCatch(() => access(path)),
+    createExclusive: path => asyncTryCatch(async () => {
+        const fh = await open(path, 'wx');
+        await fh.close();
+    }),
+    writeBytes: (path, offset, data) => asyncTryCatch(async () => {
+        const fh = await open(path, 'r+');
+        try {
+            const buffer = fromVec(data);
+            // Loop over short writes so the whole Vec lands — a partial pwrite would
+            // leave a hole the publish-time size check could pass over.
+            let written = 0;
+            while (written < buffer.length) {
+                const { bytesWritten } = await fh.write(buffer, written, buffer.length - written, offset + written);
+                written += bytesWritten;
+            }
+        }
+        finally {
+            await fh.close();
+        }
+    }),
+    stat: path => asyncTryCatch(async () => ({ size: (await stat(path)).size })),
+    import: path => asyncTryCatch(() => asyncImport(path)),
     exec: (command, stdin) => new Promise(resolve => {
         const child = exec(command, (e, stdout, stderr) => resolve(e !== null ? ['error', e] : ok({ stdout, stderr })));
         child.stdin?.end(stdin);

package/fs/effects/node/virtual/module.f.js

@@ -290,6 +290,60 @@ const readBytesOp = (path, offset, size) => readOperation((dir, p) => {
     }
     return ok(result);
 })(path);
+/** Total byte size of a chunk-list file (each chunk is byte-aligned). */
+const fileSizeBytes = (chunks) => chunks.reduce((acc, c) => acc + Number(length(c) / 8n), 0);
+/** Absent-path error for an already-existing exclusive create, mirroring `EEXIST`. */
+const eexist = error({ code: 'EEXIST' });
+const createExclusive = operation((dir, path) => {
+    if (path.length !== 1) {
+        return [dir, invalidPath];
+    }
+    const [name] = path;
+    // O_EXCL: fail if the name is already taken; otherwise create an empty file.
+    if (dir[name] !== undefined) {
+        return [dir, eexist];
+    }
+    return [{ ...dir, [name]: [] }, okVoid];
+});
+// The lock-free upload only ever writes sequentially at the current end of the
+// staging file (`offset === size`), so the virtual model implements that append
+// case exactly: it never creates (a missing file is `ENOENT`), never overwrites
+// existing bytes, and never leaves a hole — matching the effect's contract for
+// the one access pattern its callers use.
+const writeBytesOp = (path, offset, data) => operation((dir, p) => {
+    if (p.length !== 1) {
+        return [dir, enoent];
+    }
+    const [name] = p;
+    const file = dir[name];
+    if (file === undefined) {
+        return [dir, enoent];
+    } // writeBytes never creates
+    if (!Array.isArray(file)) {
+        return [dir, error(`'${name}' is not a file`)];
+    }
+    if (!Number.isInteger(offset) || offset < 0) {
+        return [dir, error(`Offset ${offset} is invalid`)];
+    }
+    const chunks = file;
+    if (offset !== fileSizeBytes(chunks)) {
+        return [dir, error(`writeBytes offset ${offset} must equal the file size (append-only)`)];
+    }
+    return [{ ...dir, [name]: [...chunks, data] }, okVoid];
+})(path);
+const statOp = readOperation((dir, path) => {
+    if (path.length !== 1) {
+        return enoent;
+    }
+    const file = dir[path[0]];
+    if (file === undefined) {
+        return enoent;
+    }
+    if (!Array.isArray(file)) {
+        return error(`'${path[0]}' is not a file`);
+    }
+    return ok({ size: fileSizeBytes(file) });
+});
 const map = {
     all: (...a) => state => {
         let e = [];
@@ -330,6 +384,9 @@ const map = {
     rm,
     rename,
     readBytes: readBytesOp,
+    createExclusive,
+    writeBytes: writeBytesOp,
+    stat: statOp,
     randomInt: () => state => [{ ...state, randomNext: state.randomNext + 1 }, state.randomNext],
     exec: todo,
     createServer: todo,

package/fs/effects/proof.f.d.ts

@@ -1,4 +1,8 @@
 export declare const proof: {
+    lazy: {
+        value: () => void;
+        deferred: () => void;
+    };
     foldStep: {
         empty: () => void;
         threadsState: () => void;

package/fs/effects/proof.f.js

@@ -1,4 +1,4 @@
-import { decode, do_, foldStep, forEachStep, match, pure } from "./module.f.js";
+import { decode, do_, foldStep, forEachStep, lazy, match, pure } from "./module.f.js";
 const assertPure = (e, expected) => {
     const d = decode(e);
     if (!d.done) {
@@ -10,6 +10,23 @@ const assertPure = (e, expected) => {
 };
 const next = match({ add: (a, b) => a + b });
 export const proof = {
+    lazy: {
+        value: () => {
+            assertPure(lazy(() => 42), 42);
+        },
+        deferred: () => {
+            // The thunk runs only when the effect is decoded, not when `lazy` is called.
+            let evaluated = false;
+            const e = lazy(() => { evaluated = true; return 7; });
+            if (evaluated) {
+                throw 'lazy must not evaluate eagerly';
+            }
+            assertPure(e, 7);
+            if (!evaluated) {
+                throw 'decode must force the thunk';
+            }
+        },
+    },
     foldStep: {
         empty: () => {
             const e = foldStep((x) => (s) => pure(s + x))(10)([]);

package/fs/fjs/module.f.js

@@ -5,14 +5,11 @@
  */
 import { compile } from "../djs/module.f.js";
 import { main as testMain } from "../emergent_testing/module.f.js";
-import { commands as casCommands, fileCas } from "../cas/module.f.js";
+import { commands as casCommands } from "../cas/cli/module.f.js";
 import { main as ciMain } from "../ci/module.f.js";
 import { import_ } from "../effects/node/module.f.js";
 import { dispatch } from "../cli/module.f.js";
 import { casMcpServer } from "../cas/mcp/module.f.js";
-import { toPath } from "../cas/module.f.js";
-import { sha256 } from "../crypto/sha2/module.f.js";
-import { join } from "../path/module.f.js";
 import { pure } from "../effects/module.f.js";
 const commands = [
     {
@@ -33,10 +30,7 @@ const commands = [
     {
         names: ['mcp', 'm'],
         description: 'Run an MCP server over stdio exposing the CAS as tools',
-        handler: ({ home }) => {
-            const c = fileCas(sha256)(home);
-            return casMcpServer(c, home, hash => join(home, toPath(hash))).step(() => pure(0));
-        },
+        handler: ({ home }) => casMcpServer(home).step(() => pure(0)),
     },
     {
         names: ['ci', 'i'],

package/fs/html/module.f.js

@@ -46,15 +46,13 @@ const rawText = [
 /**
  * https://stackoverflow.com/questions/7381974/which-characters-need-to-be-escaped-in-html
  */
-const escapeCharCode = (code) => {
-    switch (code) {
-        case quotationMark: return '"';
-        case ampersand: return '&';
-        case lessThanSign: return '<';
-        case greaterThanSign: return '>';
-        default: return fromCharCode(code);
-    }
+const escapeTable = {
+    [quotationMark]: '"',
+    [ampersand]: '&',
+    [lessThanSign]: '<',
+    [greaterThanSign]: '>',
 };
+const escapeCharCode = (code) => escapeTable[code] ?? fromCharCode(code);
 const escape = compose(stringToList)(map(escapeCharCode));
 const node = (n) => typeof n === 'string' ? escape(n) : element(n);
 const nodes = flatMap(node);

package/fs/mcp/module.f.d.ts

@@ -229,4 +229,4 @@ export type McpConfig = {
  * - `tools/list` params (an optional pagination `cursor`) are validated and passed
  *   to the handler; invalid params → -32602.
  */
-export declare const mcpStep: <O extends Operation>({ protocolVersion, capabilities, serverInfo, }: McpConfig) => (handlers: McpHandlers<O>) => (stateKey: Key<McpSessionState>) => (value: Unknown) => Effect<MemOp | O, Response | null>;
+export declare const mcpStep: ({ protocolVersion, capabilities, serverInfo, }: McpConfig) => <O extends Operation>(handlers: McpHandlers<O>) => (stateKey: Key<McpSessionState>) => (value: Unknown) => Effect<MemOp | O, Response | null>;

package/fs/mime/module.f.d.ts

@@ -1,10 +1,15 @@
 /**
  * Magic-byte MIME type detection.
  *
- * A pure table lookup over the leading bytes of a `Vec`: no I/O, no
- * dependencies beyond `fs/types/bit_vec`. `detect` 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.
+ * `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
@@ -29,11 +34,102 @@
  */
 import { type Vec } from '../types/bit_vec/module.f.ts';
 import type { Nullable } from '../types/nullable/module.f.ts';
+import { type Effect, type Operation } from '../effects/module.f.ts';
+import type { List } from '../effects/list/module.f.ts';
+import type { IoResult } from '../effects/node/module.f.ts';
+import { type Utf8State } from '../text/utf8/module.f.ts';
 /**
  * Detects the MIME type of `bytes` from its leading magic-byte signature.
  *
- * @returns the MIME type string for a recognised format, or `null` when the
+ * @returns the MIME type string for a recognized format, or `null` when the
  *   leading bytes match no known signature (including any `Vec` shorter than
  *   the signature it might otherwise match).
  */
 export declare const detect: (bytes: Vec) => Nullable<string>;
+/**
+ * A magic-byte signature as a byte pattern. `null` entries are wildcards (the
+ * four little-endian size bytes of WebP, between its `RIFF` and `WEBP` markers).
+ */
+type Signature = {
+    readonly pattern: readonly Nullable<number>[];
+    readonly mime: string;
+};
+/**
+ * `A_magic`: signature elimination. `scan` holds the byte offset and the still-viable
+ * signatures; a fully matched signature absorbs into `matched`, an empty viable set
+ * into `dead`. Settles within 12 bytes — `matched`/`dead` are absorbing.
+ */
+type MagicState = {
+    readonly tag: 'scan';
+    readonly pos: number;
+    readonly viable: readonly Signature[];
+} | {
+    readonly tag: 'matched';
+    readonly mime: string;
+} | {
+    readonly tag: 'dead';
+};
+/**
+ * `A_utf8`: a streaming UTF-8 validity-and-text check riding the shared
+ * `utf8ByteToCodePointOp` decoder. `st` is the decoder's mid-sequence state;
+ * `valid` is `false` once an illegal byte, surrogate, or out-of-range code point
+ * is seen — `valid: false` is absorbing. A non-null `st` at EOF (a truncated
+ * multi-byte sequence) is invalid. `text` is the orthogonal text-ness verdict: it
+ * is `false` once a non-text (control) code point is decoded, even though that
+ * code point is perfectly well-formed UTF-8 — `text: false` is absorbing too.
+ * Keeping the two distinct lets a valid-but-control blob (e.g. NUL) decode
+ * cleanly yet still classify as binary.
+ */
+type Utf8Detect = {
+    readonly st: Utf8State;
+    readonly valid: boolean;
+    readonly text: boolean;
+};
+/**
+ * The product state: running bit length × magic eliminator × UTF-8 validator.
+ * The factors never read each other; they meet only in {@link finish}.
+ */
+export type DetectState = {
+    readonly length: bigint;
+    readonly magic: MagicState;
+    readonly utf8: Utf8Detect;
+};
+/** The initial detector state `q₀`. */
+export declare const detectInit: DetectState;
+/**
+ * Folds one `Vec` chunk into the detector state (`δ` over a whole chunk). Length
+ * always advances by the chunk's bit length; per-byte iteration stops as soon as
+ * the verdict is fixed (see {@link isSettled}), so large blobs — including large
+ * magic-matched ones — cost ≈ length counting.
+ */
+export declare const push: (s: DetectState) => (chunk: Vec) => DetectState;
+/** The metadata read off the detector at end-of-stream. */
+export type DetectMeta = {
+    readonly length: bigint;
+    readonly mime_type: string;
+    readonly type: 'text' | 'base64';
+};
+/**
+ * Reads the answer off the final state (`λ`). Reproduces the three-way result of
+ * the pure path: magic hit → `base64` + detected mime; else whole-blob-valid UTF-8
+ * that is also all-text (byte-aligned, no invalidity, no control bytes) → `text` +
+ * `text/plain`; else → `base64` + `application/octet-stream`. A valid-but-control
+ * blob (NUL, other controls) is well-formed UTF-8 yet falls through to the binary
+ * branch.
+ */
+export declare const finish: (s: DetectState) => DetectMeta;
+/**
+ * Classifies a whole `Vec` with the same state machine as {@link detectStream}.
+ * The single-buffer counterpart for callers that already hold the bytes (the
+ * `cas_get` `content: true` path materializes the blob anyway): both paths read
+ * the three-way `{ length, mime_type, type }` verdict from one machine instead of
+ * re-deriving it from `detect` + a separate UTF-8 check.
+ */
+export declare const detectVec: (bytes: Vec) => DetectMeta;
+/**
+ * Folds a CAS read stream through {@link push} and reads {@link finish} at EOF,
+ * deriving `cas_get` metadata without ever materializing the blob. A read `error`
+ * item short-circuits into the `IoResult` error.
+ */
+export declare const detectStream: <O extends Operation>(stream: List<O, IoResult<Vec>>) => Effect<O, IoResult<DetectMeta>>;
+export {};