functionalscript 0.45.0 → 0.46.1

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

@@ -17,11 +17,12 @@
  * @import { Unknown } from '../json/types.ts'
  * @import { Result } from '../../types/result/types.ts'
  * @import { DialectEntry } from '../types.ts'
- * @import { Revision, RevisionError } from './types.ts'
+ * @import { String as RttiString } from '../../types/rtti/types.ts'
+ * @import { LockField, LockFieldSchema, LockMap, LockSchema, Revision, RevisionError } from './types.ts'
  */
 
-import { array, number, option, record, string } from '../../types/rtti/module.f.mjs'
-import { validate as rttiValidate } from '../../types/rtti/validate/module.f.mjs'
+import { array, number, option, string } from '../../types/rtti/module.f.mjs'
+import { parse as rttiParse } from '../../types/rtti/parse/module.f.mjs'
 import { parse as parseJson } from '../json/module.f.mjs'
 import { cBase32ToVec } from '../../basen/cbase32/module.f.mjs'
 import { error, ok, okThen } from '../../types/result/module.f.mjs'
@@ -49,8 +50,64 @@ export const mediaType = /** @type {const} */ (`application/${dialect}+json`)
  */
 export const hash = string
 
-/** Structural schema for a Stage 1 flat lock map. */
-export const _lock = record(string)
+/**
+ * rtti schema for a lock map: an open map whose every value is either a
+ * direct hash string or a nested lock map, to any depth.
+ *
+ * Self-referential through {@link lockValue}, which is a module-level
+ * constant rather than a union rebuilt inside the thunk: the rtti data form
+ * (`fjs/types/rtti/data`, which `toJsonSchema` routes through) closes
+ * reference cycles by *identity*, so a schema handing out a fresh union thunk
+ * on every call would present an infinite graph and never terminate.
+ *
+ * The named `@type` — rather than `@type {const}` — is what a self-referential
+ * schema needs twice over: a `const` cannot reference itself in its own
+ * initializer at all, and naming the recursive position is also what keeps
+ * declaration emit from inlining the structure and giving up at depth (see
+ * `fjs/AGENTS.md` §3.2 and `../json/rtti/module.f.mjs`).
+ *
+ * Like `hash`, this is `string` at the structural level; cbase32 decodability
+ * of every direct value, at every depth, is enforced by
+ * {@link checkReferences}.
+ *
+ * @type {LockSchema}
+ */
+export const lock = () => ['record', lockValue]
+
+/**
+ * One lock-map value: a direct hash, or a nested lock map. Written as the
+ * union tuple rather than as `or(string, lock)` so the thunk carries the name
+ * `lockValue`: this is where the reference cycle closes, and the data form
+ * names a rule after its defining function — an anonymous thunk would publish
+ * the recursion as `$defs: { '': … }` in every derived JSON Schema.
+ *
+ * @type {() => readonly['or', RttiString, LockSchema]}
+ */
+const lockValue = () => ['or', string, lock]
+
+/**
+ * rtti schema for a revision's `lock` **field**: the bindings inline as a lock
+ * map, or a hash naming a `vnd.fjs.lock` blob (`fjs/media/lock`) that holds
+ * one to share — see [Shared lock references](./README.md#shared-lock-references).
+ *
+ * Structurally identical to {@link lockValue}, and deliberately a separate
+ * name: the two positions mean different things. A string *inside* a map is a
+ * dependency's content hash; a string in this position is a lock blob's hash,
+ * i.e. where the whole map lives. Only the top level is widened, so a nested
+ * string keeps meaning exactly what it always did and no position is
+ * ambiguous.
+ *
+ * Widening the field rather than adding a `lockRef` sibling is what keeps this
+ * dialect: an older reader validates `lock` as a map and rejects a string
+ * outright, whereas an unknown sibling field would validate and be read as
+ * "no bindings were recorded" — the fail-open misread the versioning rule
+ * exists to prevent. It also makes "inline map *and* reference" unstatable, so
+ * the format defines no precedence between them, consistent with its refusal
+ * to define overlay or inheritance for nested maps.
+ *
+ * @type {LockFieldSchema}
+ */
+export const lockField = () => ['or', hash, lock]
 
 /**
  * rtti schema for a `revision` BLOB. See the README for the full semantics of
@@ -64,7 +121,7 @@ export const revisionSchema = /** @type {const} */ ({
     snapshot: hash,
     generation: number,
     archived: option(true),
-    lock: option(_lock),
+    lock: option(lockField),
 })
 
 /** Serializes a revision canonically, recursively sorting every object's property names.
@@ -73,19 +130,70 @@ export const revisionSchema = /** @type {const} */ ({
 export const encodeText = stringify(sort)
 
 /** Structural-only validator: checks the shape, not the hash / generation semantics. */
-const validateShape = rttiValidate(revisionSchema)
+const validateShape = rttiParse(revisionSchema)
 
 /** True when `s` decodes as a cbase32 CAS hash (rejects `https://` and any other non-cbase32 string).
  * @type {(s: string) => boolean}
  */
 export const isHash = s => cBase32ToVec(s) !== null
 
+/**
+ * The first reason a structurally valid lock map is not a valid one, or
+ * `null` when every direct value at every depth is a cbase32 hash
+ * ({@link isHash}). Nested maps are scopes, not references, so only the
+ * strings are checked; `scope` names the path walked to reach the offending
+ * value, so a failure deep in a nested map still says where it is.
+ *
+ * @type {(scope: readonly string[]) => (lock: LockMap) => string | null}
+ */
+const lockError = scope => lock => {
+    for (const [subject, value] of definedEntries(lock)) {
+        const path = [...scope, subject]
+        const message = typeof value === 'string'
+            ? (isHash(value) ? null : `lock value for ${path.join('/')} is not a valid hash: ${value}`)
+            : lockError(path)(value)
+        if (message !== null) { return message }
+    }
+    return null
+}
+
+/**
+ * The first reason a structurally valid lock map is not a valid one, or `null`
+ * — {@link lockError} rooted at the empty scope, so a reported path is
+ * relative to the map itself.
+ *
+ * Exported because `fjs/media/lock` validates the very same map as a
+ * standalone blob: one recursive schema and one semantic check, so a map means
+ * the same thing inline and shared, and the two forms cannot drift.
+ *
+ * @type {(lock: LockMap) => string | null}
+ */
+export const lockMapError = lockError([])
+
+/**
+ * The first reason a structurally valid `lock` field is not a valid one, or
+ * `null`. A map is checked entry by entry ({@link lockMapError}); a string is
+ * a reference to a `vnd.fjs.lock` blob and is checked as a cbase32 hash and
+ * nothing more — this module is pure format with no store access, so whether
+ * the blob exists, and what its bindings mean once fetched, stay a resolver's
+ * business exactly as they do for `snapshot`.
+ *
+ * @type {(value: LockField) => string | null}
+ */
+export const lockFieldError = value =>
+    typeof value === 'string'
+        ? (isHash(value) ? null : `lock reference is not a valid hash: ${value}`)
+        : lockMapError(value)
+
 /**
  * Checks the semantic refinements the structural schema can't express on an
  * already shape-valid revision: every `parents` entry and the `snapshot` must
- * decode as a cbase32 hash ({@link isHash}), and `generation` must be a
+ * decode as a cbase32 hash ({@link isHash}), the `lock` field must too —
+ * every direct value at every depth of an inline map, or the shared-lock
+ * reference itself ({@link lockFieldError}) — and `generation` must be a
  * non-negative *safe* integer. `subject` is not checked — it is an identity
- * string, never a snapshot reference, so any string is valid.
+ * string, never a snapshot reference, so any string is valid, and the same
+ * goes for a lock map's keys, which are subjects.
  *
  * `generation` uses `Number.isSafeInteger`, not `Number.isInteger`: a value at
  * or above `2 ** 53` passes `isInteger` but is no longer uniquely
@@ -113,9 +221,8 @@ export const checkReferences = r => {
         if (!isHash(p)) { return error(`parent is not a valid hash: ${p}`) }
     }
     if (!isHash(r.snapshot)) { return error(`snapshot is not a valid hash: ${r.snapshot}`) }
-    for (const [subject, snapshot] of definedEntries(r.lock ?? {})) {
-        if (!isHash(snapshot)) { return error(`lock value for ${subject} is not a valid hash: ${snapshot}`) }
-    }
+    const lockMessage = r.lock === undefined ? null : lockFieldError(r.lock)
+    if (lockMessage !== null) { return error(lockMessage) }
     if (!Number.isSafeInteger(r.generation) || r.generation < 0) {
         return error(`generation must be a non-negative safe integer: ${r.generation}`)
     }

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

@@ -28,6 +28,13 @@ export declare const proof: {
         malformedLockRejected: () => void;
         invalidHashLockRejected: () => void;
         aliasHashLockAccepted: () => void;
+        nestedLockAccepted: () => void;
+        deeplyNestedLockAccepted: () => void;
+        malformedNestedLockRejected: () => void;
+        invalidNestedHashLockRejected: () => void;
+        sharedLockReferenceAccepted: () => void;
+        invalidSharedLockReferenceRejected: () => void;
+        nestedValueIsStillNotAReference: () => void;
         wrongDialectRejected: () => void;
         missingSubjectRejected: () => void;
         extraFieldsAccepted: () => void;
@@ -40,6 +47,9 @@ export declare const proof: {
     };
     encodeText: {
         recursivelySortsObjectsLexicographically: () => void;
+        sortsNestedLockKeys: () => void;
+        equivalentNestedLockOrdersConverge: () => void;
+        serializesSharedLockReferenceAsAString: () => void;
         preservesArrayOrder: () => void;
         parsedEquivalentSourcesConverge: () => void;
     };

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

@@ -16,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} */
@@ -155,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 })
@@ -213,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])
@@ -229,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

@@ -37,24 +37,41 @@
  *
  * @import { Vec } from '../../types/bit_vec/types.ts'
  * @import { Nullable } from '../../types/nullable/types.ts'
- * @import { Effect, Operation } from '../../effects/types.ts'
+ * @import { Operation } from '../../effects/types.ts'
  * @import { List } from '../../effects/list/types.ts'
- * @import { IoResult } from '../../effects/node/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 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`.
+ * 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
@@ -104,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

@@ -37,16 +37,16 @@
  *
  * @import { Vec } from '../../types/bit_vec/types.ts'
  * @import { Nullable } from '../../types/nullable/types.ts'
- * @import { Effect, Operation } from '../../effects/types.ts'
+ * @import { Operation } from '../../effects/types.ts'
  * @import { List } from '../../effects/list/types.ts'
- * @import { IoResult } from '../../effects/node/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, 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 { 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'
 
@@ -100,12 +100,27 @@ const magicStep = (m, byte) => {
 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`.
+ * 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
@@ -117,15 +132,7 @@ const magicMime = m => m.tag === 'matched' ? m.mime : null
  *
  * @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)
-}
+export const detect = bytes => magicMime(push(detectInit)(bytes).magic)
 
 // ── Streaming detector ────────────────────────────────────────────────────────────
 //
@@ -242,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,7 +1,7 @@
 /**
  * @import { Vec } from '../../types/bit_vec/types.ts'
  * @import { List } from '../../effects/list/types.ts'
- * @import { Result } from '../../types/result/types.ts'
+ * @import { IoChannel } from '../../effects/node/types.ts'
  * @import { DetectMeta } from './types.ts'
  */
 export declare const proof: {
@@ -16,6 +16,7 @@ export declare const proof: {
     spannedZip: () => void;
     webp: () => void;
     riffNotWebp: () => void;
+    settledMagicIsAFixedPoint: (() => void)[];
     textIsNull: () => void;
     shortIsNull: () => void;
     emptyIsNull: () => void;

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

@@ -1,7 +1,7 @@
 /**
  * @import { Vec } from '../../types/bit_vec/types.ts'
  * @import { List } from '../../effects/list/types.ts'
- * @import { Result } from '../../types/result/types.ts'
+ * @import { IoChannel } from '../../effects/node/types.ts'
  * @import { DetectMeta } from './types.ts'
  */
 
@@ -9,7 +9,9 @@ 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 { pureError } from '../../effects/module.f.mjs'
+import { error, ok } from '../../types/result/module.f.mjs'
+import { ioError } from '../../effects/node/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
@@ -19,12 +21,12 @@ 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>>} */
+// Builds a CAS-style read stream from a sequence of chunks.
+/** @type {(...chunks: readonly Vec[]) => List<never, Vec, IoChannel>} */
 const stream = (...chunks) =>
     chunks.reduceRight(
-        (tail, c) => nonEmpty(ok(c), tail),
-        /** @type {List<never, Result<Vec, unknown>>} */ (emptyList()))
+        (tail, c) => nonEmpty(c, tail),
+        /** @satisfies {List<never, Vec, IoChannel>} */ (emptyList()))
 
 // Runs the streaming detector over the given chunks and unwraps the metadata.
 /** @type {(...chunks: readonly Vec[]) => DetectMeta} */
@@ -84,6 +86,25 @@ export const proof = {
             null),
 
     // Plain ASCII text matches no signature.
+    // `detect` is the magic projection of `push`, and that only holds because
+    // `magicStep` leaves a non-`scan` state alone. These pin both absorbing
+    // states as fixed points from the outside, where `magicStep` is private.
+    settledMagicIsAFixedPoint: [
+        // `matched` survives whatever follows the signature — including bytes
+        // that would not extend it, and a long tail that would otherwise keep
+        // the fold running.
+        () => assertEq(detect(bytes(0xff, 0xd8, 0xff, 0x00, 0x01, 0x02)), 'image/jpeg'),
+        () => assertEq(detect(bytes(0xff, 0xd8, 0xff, ...Array(64).fill(0x41))), 'image/jpeg'),
+        // `dead` survives too. This is the case where `push` keeps folding
+        // after the magic state is settled — `isSettled` stays false while the
+        // UTF-8 factor is still valid text — so a `dead` magic is fed many more
+        // bytes here than `detect`'s old loop ever gave it.
+        () => assertEq(detect(bytes(0x41)), null),
+        () => assertEq(detect(bytes(0x41, ...Array(64).fill(0x42))), null),
+        // ...and the same input still reads as text through the full detector,
+        // confirming the fold really did continue past the dead magic.
+        () => assertEq(detectVec(bytes(0x41, ...Array(64).fill(0x42))).type, 'text'),
+    ],
     textIsNull: () =>
         assertEq(detect(bytes(0x68, 0x65, 0x6c, 0x6c, 0x6f)), null),
 
@@ -270,11 +291,10 @@ export const proof = {
             assertEq(m.length, 8n)
         },
 
-        // A read `error` item short-circuits into the IoResult error.
+        // A stream that fails carries its failure out as the detector's own.
         readErrorSurfaces: () => {
-            /** @type {List<never, Result<Vec, unknown>>} */
-            const errStream =
-                nonEmpty(/** @type {const} */ (['error', 'boom']), emptyList())
+            /** @type {List<never, Vec, IoChannel>} */
+            const errStream = pureError(ioError({ message: 'boom' }))
             const o = runPure(detectStream(errStream))
             assert(o.length === 1, 'effect is not pure')
             assert(o[0][0] === 'error')