@hviana/sema 0.5.9 → 0.7.1

package/dist/src/mind/pipeline.js

@@ -92,9 +92,18 @@ export async function think(ctx, query, mechs) {
     };
     // ── Pre-computation ──────────────────────────────────────────────────
     const mechanisms = mechs ?? defaultMechanisms;
-    const rec = recognise(ctx, query);
+    const meter = ctx.meter;
+    // recognition is a shared analysis (§2.14 contract 5): it does the query's
+    // own store work (perceive → foldTree → resolve), which used to land in
+    // `think` and in nothing narrower — the meter's one accounting surface must
+    // charge it to itself, exactly as attention/weave/resonance are charged.
+    const rec = meter
+        ? await meter.time("recognise", async () => recognise(ctx, query))
+        : recognise(ctx, query);
     // Phase 1: collect computed spans from mechanisms that implement parse()
-    const computed = await collectComputed(ctx, mechanisms, query);
+    const computed = meter
+        ? await meter.time("collectComputed", () => collectComputed(ctx, mechanisms, query))
+        : await collectComputed(ctx, mechanisms, query);
     if (computed.length > 0) {
         ctx.trace?.step("computeExtensions", [rItem(query, "query")], computed.map((u) => rItem(query.subarray(u.i, u.j), "operand", undefined, [u.i, u.j])), `extensions recognised and evaluated ${computed.length} computation(s)`);
         for (const u of computed) {
@@ -107,6 +116,9 @@ export async function think(ctx, query, mechs) {
     // method on Precomputed, first-touched by whichever mechanism's floor
     // survives its cheap gates and the worthRunning check.  A query no
     // mechanism climbs for (e.g. one an extension decided) never climbs.
+    // NOT phased: the constructor itself is trivial (it only derives `k`), so a
+    // phase here would add a zero-work entry to every profiled report — the meter
+    // attributes WORK (§2.14); the trace already represents structure.
     const pre = new Precomputed(ctx, query, rec, computed, ctx._edgeGuide);
     const grade = (w) => Math.floor(w / STEP);
     const unaccounted = (spans) => unexplainedSpans(query.length, spans)
@@ -155,7 +167,7 @@ export async function think(ctx, query, mechs) {
     // Per-mechanism accounting (src/meter.ts).  The market's whole premise is
     // that mechanisms compete on one cost scale — so the profiling read-out is
     // also per-mechanism, uniformly: the loop never asks which one it holds.
-    const meter = ctx.meter;
+    let regimeReported = false;
     for (const mech of mechanisms) {
         const floor = meter
             ? await meter.time(`${mech.name}.floor`, () => mech.floor(ctx, query, pre, worthRunning))
@@ -192,6 +204,42 @@ export async function think(ctx, query, mechs) {
                 scaffolding: r.scaffolding,
             });
         }
+        // REGIME PREDICTION (R8) — observational only.  After the FIRST mechanism
+        // runs (cover, which §2.6 places first and floors at 0), the market's
+        // outcome is already determined: the consensus climb runs exactly when
+        // `worthRunning(2 * STEP)` is true — CAST (floor 2·STEP) is the cheapest
+        // mechanism that first-touches it, so an incumbent at or below grade 2
+        // prunes CAST and, with it, confluence (3·STEP) and extraction
+        // (CONCEPT+STEP) (retrieval); anything above — or no incumbent — runs the
+        // full market and the climb (composition).  The predicate is
+        // `worthRunning`, the same function the loop just used — nothing is
+        // computed here that the engine had not already computed, and nothing is
+        // read back by inference.
+        if (!regimeReported) {
+            regimeReported = true;
+            const climbFloorGrade = grade(2 * STEP);
+            // TS narrows `best` to null in the outer flow (it cannot see the closure
+            // assignments in `consider`) — cast back, the same read-back as `decided`
+            // below.
+            const incumbent = best;
+            const incumbentGrade = incumbent === null
+                ? null
+                : grade(incumbent.weight);
+            const regime = worthRunning(2 * STEP)
+                ? "composition"
+                : "retrieval";
+            ctx.trace?.step("regimePrediction", [rItem(query, "query")], [], regime === "retrieval"
+                ? `retrieval regime — incumbent grade ${incumbentGrade} ≤ climb floor ${climbFloorGrade}, so no composition mechanism runs; ` +
+                    `the consensus climb will not run`
+                : `composition regime — ${incumbentGrade === null
+                    ? "no incumbent (nothing grounded)"
+                    : `incumbent grade ${incumbentGrade}`} above climb floor ${climbFloorGrade}, so the full market and climb run`, undefined, {
+                version: 1,
+                regime,
+                incumbentGrade,
+                climbFloorGrade,
+            });
+        }
     }
     // (TS cannot see the closure assignments into `best` and narrows it to its
     // initial null, so the read-back needs the assertion.)

package/dist/src/mind/recognition.d.ts

@@ -11,7 +11,12 @@ import type { MindContext, Recognition, Segment } from "./types.js";
  *     query's own cut cannot, and records sub-leaf boundaries as `splits`.
  *
  *  Both O(n · maxGroup) bounded O(1) probes — never a scan of the corpus. */
-export declare function recognise(ctx: MindContext, bytes: Uint8Array): Recognition;
+/** Decompose `bytes` into the learnt forms it contains.  `trimmed` skips the
+ *  edge-trim fallbacks (which recover misaligned FRAGMENTS) — for callers whose
+ *  own gate rejects fragments anyway (the pivot), so the O(n·W²) trim search is
+ *  paid only where its output can be used.  Byte-identical for every caller
+ *  that keeps only top-level forms. */
+export declare function recognise(ctx: MindContext, bytes: Uint8Array, trimmed?: boolean): Recognition;
 /** Segment bytes using the geometry's own groupings — leaf-parent
  *  nodes from the perceived tree, with consecutive bare leaves merged
  *  into one segment.  Each segment's gist is perceived from its bytes

package/dist/src/mind/recognition.js

@@ -22,7 +22,12 @@ import { isChunk } from "../sema.js";
  *     query's own cut cannot, and records sub-leaf boundaries as `splits`.
  *
  *  Both O(n · maxGroup) bounded O(1) probes — never a scan of the corpus. */
-export function recognise(ctx, bytes) {
+/** Decompose `bytes` into the learnt forms it contains.  `trimmed` skips the
+ *  edge-trim fallbacks (which recover misaligned FRAGMENTS) — for callers whose
+ *  own gate rejects fragments anyway (the pivot), so the O(n·W²) trim search is
+ *  paid only where its output can be used.  Byte-identical for every caller
+ *  that keeps only top-level forms. */
+export function recognise(ctx, bytes, trimmed = false) {
     // Content-keyed memo — works for both single-turn respond() and multi-turn
     // respondTurn() (where the map persists across calls).  ALWAYS consulted,
     // regardless of tracing — matching perceive()'s own memo, which carries no
@@ -62,7 +67,7 @@ export function recognise(ctx, bytes) {
     // not silent), so it is emitted here directly rather than only inside
     // recogniseImpl.
     if (ctx.recogniseMemo) {
-        const key = latin1Key(bytes);
+        const key = (trimmed ? "t" : "f") + latin1Key(bytes);
         const hit = ctx.recogniseMemo.get(key);
         if (hit !== undefined) {
             if (ctx.meter)
@@ -74,13 +79,13 @@ export function recognise(ctx, bytes) {
                 `lead somewhere (over ${hit.leaves.length} perceived leaves) [cached]`);
             return hit;
         }
-        const fresh = recogniseImpl(ctx, bytes);
+        const fresh = recogniseImpl(ctx, bytes, trimmed);
         ctx.recogniseMemo.set(key, fresh);
         return fresh;
     }
-    return recogniseImpl(ctx, bytes);
+    return recogniseImpl(ctx, bytes, trimmed);
 }
-function recogniseImpl(ctx, bytes) {
+function recogniseImpl(ctx, bytes, trimmed = false) {
     if (ctx.meter) {
         ctx.meter.recognitions++;
         ctx.meter.recognisedBytes += bytes.length;
@@ -194,7 +199,7 @@ function recogniseImpl(ctx, bytes) {
             // n.kids !== null enforces above) rather than degenerate into
             // single-byte-atom territory, which atomIsHub already governs
             // separately.
-            else if (end - start - 1 >= 2) {
+            else if (!trimmed && end - start - 1 >= 2) {
                 // The chunk's own boundary is drawn by content geometry, not by
                 // any notion of "form" — it can include one edge byte the query's
                 // fold happened to attach here that the trained span never had

package/dist/src/mind/resonance.js

@@ -9,7 +9,7 @@ import { mergeThreshold } from "../geometry.js";
 import { concat2, concatBytes, indexOf } from "../bytes.js";
 import { gistOf, read, resolve, walkTree } from "./primitives.js";
 import { perceive } from "./primitives.js";
-import { argmaxBy, argmaxCosine, candidateGist, hubBound } from "./traverse.js";
+import { argmaxCosine, candidateGist, hubBound } from "./traverse.js";
 import { cachedRead, junctionContainers, junctionSynonyms, walkCache, } from "./junction.js";
 import { recognise } from "./recognition.js";
 // ── The bridge — the junction between two adjacent results ──────────────────
@@ -288,7 +288,13 @@ export async function pivotInto(ctx, answer, consumed, voiced = []) {
         for (const c of n.kids)
             queue.push(c); // breadth-first: larger regions first
     }
-    const rec = recognise(ctx, answer);
+    // TRIMMED recognition: the pivot's own filter below rejects fragments
+    // (`hasParents || hasContainers → -Infinity`), and recognition's edge-trim
+    // fallbacks exist to find exactly those misaligned FRAGMENTS.  Skipping them
+    // (the structural pass + canonResolve still run) is byte-identical for every
+    // pivot — the fallbacks' output is discarded by the filter — and halves the
+    // O(n·W²) recognition of a long answer (measured: 36KB recognise 4.0s → 2.0s).
+    const rec = recognise(ctx, answer, true);
     for (const s of rec.sites) {
         if (!consumed.has(s.payload) && ctx.store.hasNext(s.payload)) {
             scored.set(s.payload, Math.max(scored.get(s.payload) ?? 0, 1));
@@ -296,7 +302,26 @@ export async function pivotInto(ctx, answer, consumed, voiced = []) {
     }
     // Byte containment, longest wins — the answer literally contains the
     // pivot's bytes, and the biggest well-evidenced span is the real pivot.
-    const found = argmaxBy(scored.keys(), (id) => {
+    //
+    // REAL SATURATION, not a hard cap: the score IS the candidate's byte
+    // length, so the scan is DECIDED the moment the first candidate that passes
+    // every filter is found in DESCENDING length order — a shorter candidate can
+    // never outscore it.  `contentLen` (the prefix-capped length read, §2.8) is
+    // the cheap ordering key, and the first-inserted tie-break is made explicit
+    // (`a.index - b.index`) so equal lengths keep `scored`'s insertion order —
+    // exactly the tie argmaxBy(strict) used to keep.  The bytes of at most ONE
+    // winning candidate are read; every shorter candidate the probes proposed is
+    // skipped without reconstruction, where the old argmax read them all.
+    const ranked = [...scored.keys()]
+        .map((id, index) => ({
+        id,
+        index,
+        len: ctx.store.contentLen(id, answer.length + 1),
+    }))
+        .sort((a, b) => b.len - a.len || a.index - b.index);
+    let pivotId = null;
+    for (const c of ranked) {
+        const id = c.id;
         // A PIVOT MUST BE A THING THE CORPUS DEPOSITED, NOT A PIECE OF ONE.
         // "Longest wins" ranks candidates but never asks whether the winner is
         // an entity at all, and by the time a chain reaches here `consumeAll`
@@ -330,18 +355,28 @@ export async function pivotInto(ctx, answer, consumed, voiced = []) {
         // what `parents`/`containers` record.  Reasoning steps THROUGH a fact;
         // a span that was never a fact on its own is not one to step through.
         // No constant enters — it is a structural predicate, not a threshold.
-        if (ctx.store.hasParents(id) || ctx.store.hasContainers(id)) {
-            return -Infinity;
-        }
+        if (ctx.store.hasParents(id) || ctx.store.hasContainers(id))
+            continue;
+        // A candidate whose bytes are LONGER than the answer cannot be a
+        // substring of it — `indexOf` would return −1 regardless.  Prune by
+        // length BEFORE reconstructing the bytes: `read` is an UNCAPPED read
+        // (AGENTS §2.8), and a resonated context far longer than the answer is
+        // exactly the candidate that makes it cost a whole deposit's worth of
+        // reconstruction for a containment test that must fail.  `contentLen`
+        // with the `answer.length + 1` cap is the prefix-capped length read the
+        // same contract prescribes; the prune is byte-identical to the old
+        // `indexOf` miss (it returns −1 for a needle longer than the haystack).
+        if (c.len > answer.length)
+            continue;
         const bytes = read(ctx, id);
         if (indexOf(answer, bytes, 0) < 0)
-            return -Infinity;
-        for (const v of voiced)
-            if (indexOf(v, bytes, 0) >= 0)
-                return -Infinity;
-        return bytes.length;
-    }, 0, true);
-    return found?.item ?? null;
+            continue;
+        if (voiced.some((v) => indexOf(v, bytes, 0) >= 0))
+            continue;
+        pivotId = id;
+        break;
+    }
+    return pivotId;
 }
 /** Which of the given labelled forms a span MEANS — generic resonance over
  *  perceived gists.  Each anchor form's gist is memoised; the span's gist

package/dist/src/store.js

@@ -723,7 +723,28 @@ export class AbstractStore {
             parts.push(child);
             got += child.length;
         }
-        return concat(parts);
+        const out = concat(parts);
+        // Cache the BRANCH too, not just the leaf above.  Reconstruction is a pure
+        // function of the store, so this is a transparent cache in the strict sense
+        // — an eviction costs a re-walk and nothing else — which is exactly what
+        // `_bytesCache`'s "smallest"/"clock" configuration is for.
+        //
+        // Caching only leaves made every branch re-walk its whole subtree on every
+        // request, and the DAG is hash-consed, so the same children recur under many
+        // parents.  Measured on the 18.9M-node store, ONE 1,314-byte query:
+        // 20,021,474 `_prefix` calls over 469,083 distinct ids (42.7x reuse) to
+        // produce 87,789 results — 97.7% of the work re-derived bytes it had already
+        // built.  One single-byte leaf was reconstructed 2,599,984 times.  Measuring
+        // reuse at the TOP level only shows 1.1x and hides all of it.
+        //
+        // Only a COMPLETE reconstruction may be cached: `_prefix` is also called
+        // with a cap, and a truncated prefix stored under `id` would be served as
+        // if it were the node's whole content by the `_bytesCache` hit above.
+        // `got < maxLen` is that proof — the walk ran out of children before it ran
+        // out of budget, so nothing below was truncated either.
+        if (got < maxLen)
+            this._bytesCache.set(id, out);
+        return out;
     }
     contentLen(id, cap = Infinity) {
         if (this.meter)

package/example/train_base/cache.ts

@@ -0,0 +1,251 @@
+// train_base/cache.ts — the durable disk cache and the download sink.
+//
+// This is the ONE place the trainer needs Node rather than the web platform:
+// every other byte in the pipeline moves through fetch, WHATWG streams,
+// DecompressionStream, TextDecoderStream and Blob, but writing a file is the
+// single capability the web platform does not expose. So the sink below wraps a
+// raw fs descriptor, and nothing else here does.
+//
+// Two invariants the rest of the trainer relies on:
+//   • ATOMIC — a download streams to "<file>.part", is fsync'd, then renamed
+//     into place. A file at its final path is, by construction, complete, so an
+//     interrupted download can never be mistaken for a cached one.
+//   • BOUNDED — a download blocks under the MAX_CACHE_GB ceiling, and a fully
+//     processed file is deleted by its caller immediately.
+
+import {
+  CACHE_DIR,
+  CACHE_WAIT_MS,
+  MAX_CACHE_BYTES,
+  PART_SUFFIX,
+} from "./config.js";
+import { httpError, retry, waitMs } from "./http.js";
+import {
+  closeSync,
+  existsSync,
+  fsyncSync,
+  mkdirSync,
+  openSync,
+  readdirSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeSync,
+} from "node:fs";
+import { basename, join } from "node:path";
+
+/** Delete every orphaned "<file>.part" in the cache, returning how many were
+ *  removed and the bytes they held.
+ *
+ *  A .part file at rest is by definition the debris of a download that never
+ *  finished — the rename that promotes one is the last step of `downloadFile`,
+ *  so a live .part exists only while THIS process is writing it. Sweeping at
+ *  startup is therefore safe, and it is load-bearing rather than cosmetic:
+ *  `cacheSize` deliberately counts .part files (an in-flight download really
+ *  does occupy the disk), so debris left by a killed run consumes ceiling
+ *  budget that nothing would ever free, and `ensureCacheRoom` would wait for
+ *  room that cannot appear.
+ *
+ *  The one assumption is that a cache directory belongs to ONE run at a time.
+ *  That was already true — two trainers sharing CACHE_DIR would write the same
+ *  .part path — so this adds no constraint that did not exist. */
+export function sweepPartials(): { files: number; bytes: number } {
+  const out = { files: 0, bytes: 0 };
+  if (!existsSync(CACHE_DIR)) return out;
+  for (const name of readdirSync(CACHE_DIR)) {
+    if (!name.endsWith(PART_SUFFIX)) continue;
+    const p = join(CACHE_DIR, name);
+    try {
+      const size = statSync(p).size;
+      unlinkSync(p);
+      out.files++;
+      out.bytes += size;
+    } catch { /* raced with another delete — nothing to reclaim */ }
+  }
+  return out;
+}
+
+/** Total bytes currently held in the cache directory — INCLUDING any .part
+ *  file, because an in-flight download occupies the disk like any other file.
+ *  Orphaned ones are removed by {@link sweepPartials} at startup. */
+export function cacheSize(): number {
+  if (!existsSync(CACHE_DIR)) return 0;
+  let total = 0;
+  for (const name of readdirSync(CACHE_DIR)) {
+    try {
+      total += statSync(join(CACHE_DIR, name)).size;
+    } catch { /* raced with a delete */ }
+  }
+  return total;
+}
+
+/** Block until there is room for a file of `fileBytes` under the ceiling.
+ *  A single file larger than the whole ceiling can never "fit", so we let it
+ *  through (it is deleted right after processing) rather than wait forever. */
+export async function ensureCacheRoom(
+  fileBytes: number,
+  signal: AbortSignal,
+  warn?: (msg: string) => void,
+  maxWaitMs = CACHE_WAIT_MS,
+): Promise<void> {
+  mkdirSync(CACHE_DIR, { recursive: true });
+  if (fileBytes >= MAX_CACHE_BYTES) return;
+  let warned = false;
+  const until = Date.now() + maxWaitMs;
+  // Stop waiting the moment a shutdown is requested — the abort signal unblocks
+  // a long cache-full wait so Ctrl+C is never swallowed by the ceiling.
+  while (!signal.aborted && cacheSize() + fileBytes > MAX_CACHE_BYTES) {
+    // BOUNDED. Room appears when this run consumes and deletes a file, so a
+    // cache already over the ceiling with nothing left to consume — stale files
+    // from another run, a ceiling set below one corpus — would otherwise wait
+    // for room that cannot arrive, forever, after a single warning line.
+    if (Date.now() >= until) {
+      throw new Error(
+        `cache still full after ${Math.round(maxWaitMs / 60_000)} min ` +
+          `(${(cacheSize() / 1e9).toFixed(1)} GB of a ` +
+          `${(MAX_CACHE_BYTES / 1e9).toFixed(0)} GB ceiling) — raise ` +
+          `MAX_CACHE_GB or clear ${CACHE_DIR}`,
+      );
+    }
+    if (!warned) {
+      warn?.(
+        `cache at ${
+          (MAX_CACHE_BYTES / 1e9).toFixed(0)
+        } GB ceiling — waiting for room…`,
+      );
+      warned = true;
+    }
+    await waitMs(5_000, signal);
+  }
+}
+
+export interface DownloadOptions {
+  signal: AbortSignal;
+  tries: number;
+  onFail?: (attempt: number, err: Error) => void;
+  onProgress?: (done: number, total: number) => void;
+}
+
+/** Stream `url` to `destPath`, atomically and with backpressure. */
+export async function downloadFile(
+  url: string,
+  destPath: string,
+  opts: DownloadOptions,
+): Promise<void> {
+  const partPath = destPath + PART_SUFFIX;
+  await retry(
+    `download ${basename(destPath)}`,
+    async () => {
+      // Abort promptly on shutdown rather than waiting out a slow socket.
+      if (opts.signal.aborted) {
+        const e: Error & { fatal?: boolean } = new Error("aborted");
+        e.fatal = true;
+        throw e;
+      }
+      const res = await fetch(url, { signal: opts.signal });
+      if (!res.ok) throw httpError(res);
+      if (!res.body) throw new Error("empty response body");
+
+      // `content-length` describes the bytes ON THE WIRE. When the server
+      // applied a content-coding, fetch hands us the DECODED body, so the
+      // header no longer describes what gets written to disk and the integrity
+      // guard below must not use it. Measured: raw.githubusercontent.com sends
+      // `content-encoding: gzip` with content-length 110,928 for a file that
+      // decodes to 1,607,931 bytes — a size check against that rejects every
+      // healthy download. (The bug stayed latent because Hugging Face sends
+      // `content-encoding: br` and NO content-length, leaving total = 0, which
+      // already disables the guard.)
+      const encoding = (res.headers.get("content-encoding") ?? "").trim()
+        .toLowerCase();
+      const decoded = encoding !== "" && encoding !== "identity";
+      const total = decoded
+        ? 0
+        : Number(res.headers.get("content-length")) || 0;
+      let done = 0;
+
+      // Stream straight to a ".part" sibling using pure WHATWG streams. A
+      // TransformStream meters progress; pipeTo into a WritableStream gives REAL
+      // backpressure natively — the sink's write() returns a promise the
+      // readable side awaits, so a fast server can never outrun the disk (no
+      // whole-file heap buffering). The sink wraps a single raw fs descriptor
+      // (the one capability the web platform lacks); writing to disk is the only
+      // Node operation in the whole pipeline. The final, valid file only ever
+      // appears via the atomic rename below, so a crash mid-transfer can never
+      // leave a truncated file at the real path.
+      const meter = new TransformStream<Uint8Array, Uint8Array>({
+        transform(chunk, controller) {
+          done += chunk.length;
+          opts.onProgress?.(done, total);
+          controller.enqueue(chunk);
+        },
+      });
+
+      const fd = openSync(partPath, "w");
+      let closed = false;
+      const closeFd = () => {
+        if (closed) return;
+        closed = true;
+        try {
+          closeSync(fd);
+        } catch { /* already closed */ }
+      };
+      const sink = new WritableStream<Uint8Array>({
+        write(chunk) {
+          // writeSync drains the whole chunk before returning, so the readable
+          // side is paused for exactly as long as the disk needs — backpressure.
+          let off = 0;
+          while (off < chunk.length) {
+            off += writeSync(fd, chunk, off, chunk.length - off);
+          }
+        },
+        close() {
+          fsyncSync(fd); // durable bytes before the rename promotes them
+          closeFd();
+        },
+        abort() {
+          closeFd();
+        },
+      });
+
+      try {
+        await res.body.pipeThrough(meter).pipeTo(sink, {
+          signal: opts.signal,
+        });
+      } catch (e) {
+        // pipeTo's abort() ran the sink's abort() (closing the descriptor); if
+        // it didn't (a non-abort throw), make sure the descriptor is not leaked.
+        closeFd();
+        try {
+          unlinkSync(partPath);
+        } catch { /* best effort */ }
+        throw e;
+      }
+
+      // Optional integrity guard: when the server advertised a size FOR THE
+      // BYTES WE WRITE (see the content-encoding note above — `total` is 0 for
+      // a decoded body, which disables this), a complete file must match it. A
+      // short read (silent truncation) is retried rather than promoted, so the
+      // parser never sees a partial file.
+      try {
+        const got = statSync(partPath).size;
+        if (total > 0 && got !== total) {
+          try {
+            unlinkSync(partPath);
+          } catch { /* best effort */ }
+          throw new Error(`size mismatch: got ${got}, expected ${total}`);
+        }
+      } catch (e) {
+        if (e instanceof Error && e.message.startsWith("size mismatch")) {
+          throw e;
+        }
+        // statSync failure is non-fatal here; the rename below will surface it.
+      }
+
+      // Atomic publish: rename is atomic within a filesystem, so the final path
+      // flips from "absent" to "complete" in one step — never an in-between.
+      renameSync(partPath, destPath);
+    },
+    opts.tries,
+    { signal: opts.signal, onFail: opts.onFail },
+  );
+}

package/example/train_base/config.ts

@@ -0,0 +1,128 @@
+// train_base/config.ts — RUN-LEVEL configuration, all from the environment.
+//
+// Only knobs that describe the RUN live here: the store, the checkpoint cadence,
+// the cache ceiling, the read budgets, the caps. A knob that describes ONE
+// CORPUS (which pairs of SmolSent, how many SODA dialogues, how long an Aya
+// field may be) belongs next to that corpus's adapter, together with the
+// evidence that fixed its default — see AGENTS.md §2.16: a comment carries the
+// constraint, and a constraint is only readable beside the code it constrains.
+
+import { join } from "node:path";
+
+/** Read an environment variable, or `d` when it is unset. */
+export const env = (k: string, d: string): string => process.env[k] ?? d;
+
+export const DB_PATH = env("DB_PATH", "sema"); // → {DB_PATH}.sqlite
+export const D = Number(env("D", "1024"));
+export const SEED = Number(env("SEED", "7"));
+
+// Checkpoint cadence is measured in LEARNED CONTENT, not deposits: a snapshot
+// every CHECKPOINT_MB megabytes of trained UTF-8 content (decimal MB, matching
+// the bytes() helper). A floor of 1 MB: a zero/NaN value must not make every
+// deposit checkpoint, nor silently disable checkpointing. The tail (a run that
+// learns less than one interval, or the remainder past the last interval) is
+// always saved by finish() at exit — a complete point.
+export const CHECKPOINT_BYTES = Math.max(
+  1_000_000,
+  Math.floor(Number(env("CHECKPOINT_MB", "100")) * 1_000_000) || 100_000_000,
+);
+
+// Target size of ONE materialised Parquet read, in uncompressed source bytes.
+// A row-GROUP is a layout choice made by whoever wrote the file, not a memory
+// budget: Aya ships 203 groups of 1,000 rows (~1 MB each), while SODA ships ONE
+// group of 1,191,582 rows (1.19 GB uncompressed) and 2Wiki ONE of 167,454
+// (666 MB). Reading "exactly one row-group" is therefore safe for the first and
+// fatal for the others, so reads are sized in BYTES instead — see
+// `parquetBatchRows`. Materialised JS objects cost several times their source
+// bytes, hence a default well under available memory.
+export const PARQUET_BATCH_BYTES = Math.max(
+  1_000_000,
+  Math.floor(Number(env("PARQUET_BATCH_MB", "32")) * 1_000_000) || 32_000_000,
+);
+
+export const LOCAL_PATH = env("LOCAL_PATH", ""); // train from a local dir
+export const CACHE_DIR = env("CACHE_DIR", join(process.cwd(), "cache"));
+export const MAX_CACHE_BYTES = Number(env("MAX_CACHE_GB", "100")) * 1e9;
+export const PROGRESS_MS = Number(env("PROGRESS_MS", "250")); // panel cadence
+
+// Index maintenance at checkpoints: compact (remove garbage), repair (fill
+// gaps), then refresh the canonical-form index (equivalence-class resolution —
+// src/canon.ts). All three are idempotent batch operations (the canon build is
+// additionally incremental via the store's `canon.upto` cursor);
+// INDEX_MAINTENANCE=0 disables.
+export const INDEX_MAINTENANCE = env("INDEX_MAINTENANCE", "1") !== "0";
+export const DOWNLOAD_TRIES = 5;
+
+// In-progress downloads are written to a sibling "<dest>.part" and atomically
+// renamed into place only after the bytes are fully flushed to disk. The cache
+// invariant is therefore absolute: a file at its final path is, by definition,
+// complete. Partial transfers (a crash, a kill, a dropped socket) leave only a
+// .part file, which is never fed to the parser and is swept at startup by
+// cache.ts's sweepPartials() — without which the debris would consume cache
+// ceiling that nothing frees.
+export const PART_SUFFIX = ".part";
+
+// The checkpoint recall is a best-effort diagnostic — it must NEVER stall
+// training. We bound it so a slow/large store cannot freeze the deposit loop.
+export const INFER_TIMEOUT_MS = Number(env("INFER_TIMEOUT_MS", "15000"));
+
+// How long the run may make NO progress before it gives up and exits non-zero.
+//
+// A long training run's worst failure is not a crash — a crash resumes. It is a
+// HANG: the uncaught-exception handler deliberately swallows dropped-connection
+// errors so a long run survives them, and the keep-alive timer deliberately
+// holds the process open; together, an error that escapes and leaves an await
+// unsettled produces a live process that will never do anything again. No error,
+// no exit, and a supervisor that sees a healthy pid. Exiting instead turns that
+// into a resume, which costs at most the work since the last checkpoint.
+//
+// "Progress" is any deposit, downloaded chunk, or rate-limit wait; time inside
+// index maintenance and the checkpoint recall does not count against it, since
+// those legitimately deposit nothing. Generous by default — this is a
+// last-resort backstop, not a latency budget. 0 disables it.
+export const STALL_MS = Math.max(
+  0,
+  Math.floor(Number(env("STALL_MIN", "15")) * 60_000) || 900_000,
+);
+
+// How long a download may wait for room under the cache ceiling before failing
+// the unit instead of waiting forever. The wait exists so a bounded cache can
+// throttle a fast source; it is not meant to outlast the run. The unit stays
+// resumable, so a genuine ceiling problem costs a retry, not the corpus.
+export const CACHE_WAIT_MS = Math.max(
+  60_000,
+  Math.floor(Number(env("CACHE_WAIT_MIN", "10")) * 60_000) || 600_000,
+);
+
+// The vector indices' memory knob (MiB) — each index's SQLite page cache.
+// The IVF index routes inserts through a RAM-resident pivot table and
+// appends to chunk blobs, so this cache mostly serves query-time cluster
+// scans; 256 MiB comfortably covers the probed working set of a trained
+// store.  Override with VECTOR_CACHE_MB (64 is the library default).
+export const VECTOR_CACHE_MB = Math.max(
+  0,
+  Number(env("VECTOR_CACHE_MB", "256")),
+);
+
+// Page cache for the MAIN DAG database (node/kid/edge/contain tables).
+// Training issues millions of content-addressed point probes per session
+// against a GB-scale file; the library default (64 MiB) is sized for a
+// small machine — a training box affords more.  Override with
+// SQLITE_CACHE_MB.
+export const SQLITE_CACHE_MB = Math.max(
+  0,
+  Number(env("SQLITE_CACHE_MB", "256")),
+);
+
+// Optional ceiling on how much LEARNED CONTENT to train, in megabytes (decimal,
+// like CHECKPOINT_MB). Default Infinity = unbounded. The cap is checked against
+// trainedContentBytes after each deposit, so a run stops at the first item that
+// carries the running total to/past the ceiling (that item is still counted).
+export const MAX_MB = Number(env("MAX_MB", "Infinity"));
+if (isNaN(MAX_MB) || MAX_MB < 0) {
+  process.stderr.write(
+    `fatal: MAX_MB must be a non-negative number or "Infinity"\n`,
+  );
+  process.exit(1);
+}
+export const MAX_BYTES = MAX_MB * 1_000_000; // Infinity stays Infinity