@hviana/sema 0.1.9 → 0.2.1

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

@@ -0,0 +1,5 @@
+export { Mind } from "./mind.js";
+export type { Input, Response } from "./mind.js";
+export type { ComputedSpan, ExtensionHost } from "./mind.js";
+export type { MechanismResult, PipelineMechanism, Precomputed, } from "./pipeline-mechanism.js";
+export type { InspectRationale, RationaleItem, RationaleStep, } from "./rationale.js";

package/dist/src/mind/index.js

@@ -0,0 +1,5 @@
+// mind/index.ts — public surface of the mind module.
+//
+// Re-exports the Mind class and all public types that were previously
+// exported from mind/mind.ts directly.
+export { Mind } from "./mind.js";

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

@@ -0,0 +1,95 @@
+import type { MindContext } from "./types.js";
+export interface Junction {
+    /** The node whose learnt bytes evidence this junction (a container form,
+     *  a continuation, or a context). */
+    id: number;
+    /** The bytes that belong between left and right. */
+    interior: Uint8Array;
+}
+/** Seed node ids to ascend from for one side of a junction: the side's own
+ *  node when it is a stored form, plus — when the node has no structural
+ *  parents — its canonical window ids.  A non-W-aligned node may have no
+ *  parents, but its constituent W-grams typically do; the window ids
+ *  provide alternative ascent paths.  The `parentsFirst(…, 1)` probe is a
+ *  single indexed lookup, far cheaper than computing every window id, so
+ *  the window-id path is only taken when the node alone cannot ascend.
+ *  Exported for callers (synonym junctions) that hold one side FIXED across
+ *  several calls and so compute its seeds once instead of per call. */
+export declare function junctionSeeds(ctx: MindContext, b: Uint8Array): number[];
+/** Per-response cache of the identity walks' pure reads (capped bytes,
+ *  parent pages, container pages), keyed by the response lifecycle object
+ *  (ctx.climbMemo).  One response issues many walks whose ancestries overlap
+ *  heavily (pair sides repeat across combos, and synonym walks revisit the
+ *  same neighbourhoods); the store is read-only while a response is in flight,
+ *  so every one of these reads is a pure function of the id — repeats cost a
+ *  Map hit instead of a SQL statement or a byte reconstruction. */
+export interface WalkCache {
+    /** id → prefix bytes read so far + whether they are the COMPLETE bytes
+     *  (shorter than the cap that read them). */
+    reads: Map<number, {
+        b: Uint8Array;
+        complete: boolean;
+    }>;
+    parents: Map<number, number[]>;
+    containers: Map<number, number[]>;
+}
+export declare function walkCache(ctx: MindContext): WalkCache | null;
+export declare function cachedRead(ctx: MindContext, cache: WalkCache | null, id: number, cap: number): Uint8Array;
+/** Tier 1 body, parameterised on already-resolved seed lists so a caller
+ *  holding one side FIXED across several calls (synonym junctions) pays for
+ *  that side's seeds once, not once per call.  The byte-containment check
+ *  below ensures only genuine containers are returned regardless of seeds.
+ *
+ *  BOUNDED at corpus scale by three disciplines (profiled on a 17.7M-node
+ *  store, where the unbounded form spent >90% of a query's CPU here):
+ *   • PHRASE-SCALE READS — a junction container is by contract a whole the
+ *     pair nearly exhausts (glue from a period to a phrase), so every visit
+ *     reads at most `maxContainer + 1` bytes (`bytesPrefix` stops early).
+ *     A node whose bytes exceed the cap cannot be a junction container, and
+ *     its ancestors are strictly larger — the branch is PRUNED, never
+ *     reconstructing a corpus-sized deposit (an oasst2 conversation) just
+ *     to reject it.
+ *   • EXPANSION BUDGET — at most √N·W nodes are popped in total: a √N-wide
+ *     frontier (the one fan-out convention) through the ~W structural
+ *     levels that separate phrase-scale content from its containers
+ *     (perception trees are W-ary, so a junction container lies within a
+ *     few levels of its parts).  A side too common to decide within the
+ *     budget abstains here and falls through to the resonance tier (the
+ *     climb's own saturation semantics).
+ *   • per-node hub guards — parent fan-outs beyond √N are hubs (not
+ *     expanded); each node contributes at most one √N page of containers;
+ *     √N collected candidates decide. */
+export declare function junctionContainersFrom(ctx: MindContext, left: Uint8Array, right: Uint8Array, maxContainer: number, leftSeeds: number[], rightSeeds: number[], 
+/** Shared expansion budget — a TIER's √N pops, not each walk's, when one
+ *  tier issues several walks (synonym junctions try up to 2·haloQueryK
+ *  siblings; without a shared budget each sibling would spend its own √N). */
+budget?: {
+    n: number;
+}, 
+/** ORDER-FREE containment: also accept containers holding right-then-left.
+ *  A junction is evidence that the two forms were LEARNT TOGETHER; which
+ *  one the query happened to mention first is a fact about the query, not
+ *  about the learnt whole.  The walk is identical (the seed ascent does not
+ *  depend on order) — only the byte-containment test gains a second probe,
+ *  so order-freedom costs two indexOf calls per visited node, never a
+ *  second walk. */
+unordered?: boolean): Junction[];
+/** Tier 1 entry point: every learnt whole that literally contains
+ *  left-then-right, found by ascending the structural DAG (parents +
+ *  containment links) from the two sides' content-addressed identities.
+ *  Both sides' seeds resolved fresh, one call. */
+export declare function junctionContainers(ctx: MindContext, left: Uint8Array, right: Uint8Array, maxContainer: number, unordered?: boolean): Junction[];
+/** Tier 2.5: synonym junctions — the container ascent (tier 1) applied to
+ *  halo siblings of left and right.  When a distributional synonym of one
+ *  form participates in a learnt whole with the other form, the container
+ *  between the synonym and the other side is valid evidence for the
+ *  original pair.  The container evidence is exact (content-addressed DAG
+ *  ascent, with window-id-enhanced seeds so non-W-aligned siblings still
+ *  ascend); the relaxation is only in which form occupies one side — a
+ *  distributional sibling rather than the exact form.
+ *
+ *  ONE expansion budget is shared by every sibling walk in this call, so
+ *  cost is bounded at √N·W pops total regardless of how many siblings are
+ *  tried.  A sibling whose bytes exceed `maxInterior` is skipped (it
+ *  cannot be junction-sized). */
+export declare function junctionSynonyms(ctx: MindContext, left: Uint8Array, right: Uint8Array, maxInterior: number, unordered?: boolean): Promise<Junction[]>;

package/dist/src/mind/junction.js

@@ -0,0 +1,262 @@
+// junction.ts — content-addressed junction search (bridge Tier 1).
+//
+// "Which learnt wholes ran L and R together?" answered by DAG ascent, not a
+// similarity guess: hash-consing means any deposit containing L's bytes shares
+// L's node (or L's canonical-window ids — position-independent identities), so
+// climbing parents + containment links from L's and R's seeds reaches every
+// container that literally holds L-then-R.  A resonance seed (the gist of the
+// bare concatenation — an object never learnt) could rank the true container
+// out of its top-k; the ascent cannot.
+//
+// Extracted from resonance.ts so BOTH the bridge (a connector between two
+// adjacent ANSWER pieces) and cross-region attention (the joint CONTEXT of two
+// non-adjacent QUERY regions) ascend by the same disciplined, bounded walk.
+import { read, resolve } from "./primitives.js";
+import { windowIds } from "./canonical.js";
+import { hubBound } from "./traverse.js";
+import { haloSiblings } from "./match.js";
+import { indexOf } from "../bytes.js";
+/** Seed node ids to ascend from for one side of a junction: the side's own
+ *  node when it is a stored form, plus — when the node has no structural
+ *  parents — its canonical window ids.  A non-W-aligned node may have no
+ *  parents, but its constituent W-grams typically do; the window ids
+ *  provide alternative ascent paths.  The `parentsFirst(…, 1)` probe is a
+ *  single indexed lookup, far cheaper than computing every window id, so
+ *  the window-id path is only taken when the node alone cannot ascend.
+ *  Exported for callers (synonym junctions) that hold one side FIXED across
+ *  several calls and so compute its seeds once instead of per call. */
+export function junctionSeeds(ctx, b) {
+    const r = resolve(ctx, b);
+    if (r !== null) {
+        if (ctx.store.parentsFirst(r, 1).length > 0)
+            return [r];
+        const wids = [...windowIds(ctx, b).values()];
+        return [r, ...wids];
+    }
+    const wids = [...windowIds(ctx, b).values()];
+    if (wids.length <= 2)
+        return wids;
+    return [wids[0], wids[wids.length - 1]];
+}
+const walkCaches = new WeakMap();
+export function walkCache(ctx) {
+    if (ctx.climbMemo === null)
+        return null;
+    let c = walkCaches.get(ctx.climbMemo);
+    if (c === undefined) {
+        walkCaches.set(ctx.climbMemo, c = { reads: new Map(), parents: new Map(), containers: new Map() });
+    }
+    return c;
+}
+export function cachedRead(ctx, cache, id, cap) {
+    if (cache === null)
+        return read(ctx, id, cap + 1);
+    const hit = cache.reads.get(id);
+    // A cached COMPLETE read serves any cap; a cached truncated read serves
+    // any cap it already covers (the caller only checks `length > cap`).
+    if (hit !== undefined && (hit.complete || hit.b.length > cap))
+        return hit.b;
+    const b = read(ctx, id, cap + 1);
+    cache.reads.set(id, { b, complete: b.length <= cap });
+    return b;
+}
+function cachedParents(ctx, cache, id, limit) {
+    if (cache === null)
+        return ctx.store.parentsFirst(id, limit);
+    let v = cache.parents.get(id);
+    if (v === undefined) {
+        v = ctx.store.parentsFirst(id, limit);
+        cache.parents.set(id, v);
+    }
+    return v;
+}
+function cachedContainers(ctx, cache, id, limit) {
+    if (cache === null)
+        return ctx.store.containersSlice(id, 0, limit);
+    let v = cache.containers.get(id);
+    if (v === undefined) {
+        v = ctx.store.containersSlice(id, 0, limit);
+        cache.containers.set(id, v);
+    }
+    return v;
+}
+/** Tier 1 body, parameterised on already-resolved seed lists so a caller
+ *  holding one side FIXED across several calls (synonym junctions) pays for
+ *  that side's seeds once, not once per call.  The byte-containment check
+ *  below ensures only genuine containers are returned regardless of seeds.
+ *
+ *  BOUNDED at corpus scale by three disciplines (profiled on a 17.7M-node
+ *  store, where the unbounded form spent >90% of a query's CPU here):
+ *   • PHRASE-SCALE READS — a junction container is by contract a whole the
+ *     pair nearly exhausts (glue from a period to a phrase), so every visit
+ *     reads at most `maxContainer + 1` bytes (`bytesPrefix` stops early).
+ *     A node whose bytes exceed the cap cannot be a junction container, and
+ *     its ancestors are strictly larger — the branch is PRUNED, never
+ *     reconstructing a corpus-sized deposit (an oasst2 conversation) just
+ *     to reject it.
+ *   • EXPANSION BUDGET — at most √N·W nodes are popped in total: a √N-wide
+ *     frontier (the one fan-out convention) through the ~W structural
+ *     levels that separate phrase-scale content from its containers
+ *     (perception trees are W-ary, so a junction container lies within a
+ *     few levels of its parts).  A side too common to decide within the
+ *     budget abstains here and falls through to the resonance tier (the
+ *     climb's own saturation semantics).
+ *   • per-node hub guards — parent fan-outs beyond √N are hubs (not
+ *     expanded); each node contributes at most one √N page of containers;
+ *     √N collected candidates decide. */
+export function junctionContainersFrom(ctx, left, right, maxContainer, leftSeeds, rightSeeds, 
+/** Shared expansion budget — a TIER's √N pops, not each walk's, when one
+ *  tier issues several walks (synonym junctions try up to 2·haloQueryK
+ *  siblings; without a shared budget each sibling would spend its own √N). */
+budget, 
+/** ORDER-FREE containment: also accept containers holding right-then-left.
+ *  A junction is evidence that the two forms were LEARNT TOGETHER; which
+ *  one the query happened to mention first is a fact about the query, not
+ *  about the learnt whole.  The walk is identical (the seed ascent does not
+ *  depend on order) — only the byte-containment test gains a second probe,
+ *  so order-freedom costs two indexOf calls per visited node, never a
+ *  second walk. */
+unordered = false) {
+    const bound = hubBound(ctx);
+    const joinedLength = left.length + right.length;
+    const seeds = [...new Set([...leftSeeds, ...rightSeeds])];
+    if (seeds.length === 0)
+        return [];
+    const b = budget ?? { n: bound * ctx.space.maxGroup };
+    // DEPTH CAP: perception trees are W-ary and a junction container is
+    // phrase-scale, so it sits within ~log_W(maxContainer) structural levels
+    // of its parts — at most W levels for any practical W (plus the
+    // containment hop the seeds already are).  Ancestry beyond that depth is
+    // strictly larger than any admissible container; walking it can only burn
+    // budget, never find a junction.
+    const maxDepth = ctx.space.maxGroup;
+    const out = [];
+    const cache = walkCache(ctx);
+    const seen = new Set(seeds);
+    const stack = seeds.map((id) => ({
+        id,
+        d: 0,
+    }));
+    while (stack.length > 0 && out.length < bound && b.n-- > 0) {
+        const { id: x, d } = stack.pop();
+        const f = cachedRead(ctx, cache, x, maxContainer);
+        if (f.length > maxContainer)
+            continue; // beyond phrase scale: prune branch
+        if (unordered) {
+            // Order-free containment does NOT require disjoint occurrences: two
+            // grid-aligned fragments of the same whole legitimately OVERLAP inside
+            // it ("red " at 0 and " cir" at 3 in `red circle`), and both being
+            // literal substrings is the evidence.  The interior is the gap between
+            // them when they are disjoint, empty otherwise.  Only the containment
+            // test differs from the ordered form — and because occurrences may
+            // overlap or abut, `f.length > joinedLength` is too strict (grid
+            // fragments of one whole sum past it; "red " + "circle" exactly equals
+            // `red circle`).  The container must be a STRICT super-form of each
+            // side, so that holding both is more than restating either.
+            const li = indexOf(f, left, 0);
+            const ri = li >= 0 ? indexOf(f, right, 0) : -1;
+            if (li >= 0 && ri >= 0 && f.length > Math.max(left.length, right.length)) {
+                const lo = Math.min(li + left.length, ri + right.length);
+                const hi = Math.max(li, ri);
+                out.push({
+                    id: x,
+                    interior: lo < hi ? f.subarray(lo, hi) : f.subarray(0, 0),
+                });
+            }
+        }
+        else if (f.length > joinedLength) {
+            const li = indexOf(f, left, 0);
+            if (li >= 0) {
+                const ri = indexOf(f, right, li + left.length);
+                if (ri >= 0) {
+                    out.push({ id: x, interior: f.subarray(li + left.length, ri) });
+                }
+            }
+        }
+        if (d >= maxDepth)
+            continue; // deeper ancestry is beyond phrase scale
+        const parents = cachedParents(ctx, cache, x, bound + 1);
+        if (parents.length <= bound) { // beyond √N parents: a hub, not expanded
+            for (const p of parents) {
+                if (!seen.has(p)) {
+                    seen.add(p);
+                    stack.push({ id: p, d: d + 1 });
+                }
+            }
+        }
+        // Containment fan-out under the SAME hub reading as parents: a node
+        // whose containers fill a whole √N page is COMMON content — its
+        // containment ancestry reaches a non-discriminative slice of the corpus
+        // (the climb's saturation semantics), and walking it would spend the
+        // entire budget discovering nothing a junction could use.  Such a node
+        // is not expanded through containment; a pair whose sides are common
+        // abstains here in a handful of pops and falls through to the resonance
+        // tier.  Below the page bound the read IS the full container list, so
+        // the walk stays exact exactly where identity evidence discriminates.
+        const containers = cachedContainers(ctx, cache, x, bound);
+        if (containers.length < bound) {
+            for (const c of containers) {
+                if (!seen.has(c)) {
+                    seen.add(c);
+                    stack.push({ id: c, d: d + 1 });
+                }
+            }
+        }
+    }
+    return out;
+}
+/** Tier 1 entry point: every learnt whole that literally contains
+ *  left-then-right, found by ascending the structural DAG (parents +
+ *  containment links) from the two sides' content-addressed identities.
+ *  Both sides' seeds resolved fresh, one call. */
+export function junctionContainers(ctx, left, right, maxContainer, unordered = false) {
+    return junctionContainersFrom(ctx, left, right, maxContainer, junctionSeeds(ctx, left), junctionSeeds(ctx, right), undefined, unordered);
+}
+/** Tier 2.5: synonym junctions — the container ascent (tier 1) applied to
+ *  halo siblings of left and right.  When a distributional synonym of one
+ *  form participates in a learnt whole with the other form, the container
+ *  between the synonym and the other side is valid evidence for the
+ *  original pair.  The container evidence is exact (content-addressed DAG
+ *  ascent, with window-id-enhanced seeds so non-W-aligned siblings still
+ *  ascend); the relaxation is only in which form occupies one side — a
+ *  distributional sibling rather than the exact form.
+ *
+ *  ONE expansion budget is shared by every sibling walk in this call, so
+ *  cost is bounded at √N·W pops total regardless of how many siblings are
+ *  tried.  A sibling whose bytes exceed `maxInterior` is skipped (it
+ *  cannot be junction-sized). */
+export async function junctionSynonyms(ctx, left, right, maxInterior, unordered = false) {
+    const out = [];
+    const lId = resolve(ctx, left);
+    const rId = resolve(ctx, right);
+    if (lId === null && rId === null)
+        return out;
+    const budget = { n: hubBound(ctx) * ctx.space.maxGroup };
+    // Left-side synonyms: containers of sibling+right.  `right`'s seeds are
+    // FIXED across every sibling this loop tries.
+    if (lId !== null) {
+        const rightSeeds = junctionSeeds(ctx, right);
+        for (const sib of await haloSiblings(ctx, lId)) {
+            const sibBytes = read(ctx, sib.id, maxInterior + 1);
+            if (sibBytes.length === 0 || sibBytes.length > maxInterior)
+                continue;
+            const containers = junctionContainersFrom(ctx, sibBytes, right, sibBytes.length + right.length + maxInterior, junctionSeeds(ctx, sibBytes), rightSeeds, budget, unordered);
+            for (const c of containers)
+                out.push(c);
+        }
+    }
+    // Right-side synonyms: containers of left+sibling.  `left`'s seeds are
+    // likewise fixed across this loop.
+    if (rId !== null) {
+        const leftSeeds = junctionSeeds(ctx, left);
+        for (const sib of await haloSiblings(ctx, rId)) {
+            const sibBytes = read(ctx, sib.id, maxInterior + 1);
+            if (sibBytes.length === 0 || sibBytes.length > maxInterior)
+                continue;
+            const containers = junctionContainersFrom(ctx, left, sibBytes, left.length + sibBytes.length + maxInterior, leftSeeds, junctionSeeds(ctx, sibBytes), budget, unordered);
+            for (const c of containers)
+                out.push(c);
+        }
+    }
+    return out;
+}

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

@@ -0,0 +1,47 @@
+import { Sema } from "../sema.js";
+import type { Input, MindContext } from "./types.js";
+/** Intern a perceived tree into node ids, bottom-up, sharing equal subtrees.
+ *  Returns the root node id and a map from tree nodes to their ids.
+ *
+ *  Memoized by NODE IDENTITY (ctx._internIds): the pyramid fold shares a
+ *  prefix's subtree OBJECTS across an accumulated context's deposits, and a
+ *  node already interned needs nothing again — its id is permanent
+ *  (content-addressed) and its intern-time side effects (gist capture, kid
+ *  rows) fired at first mint; re-interning was pure lookups.  A memo hit
+ *  therefore skips the WHOLE shared subtree, making the intern walk
+ *  O(new nodes) per deposit instead of O(context).  Only the hit node
+ *  itself enters `ids`; descendants stay reachable via the memo (see
+ *  idOf in indexSubSpans and the changedNodes prune). */
+export declare function internTreeIds(ctx: MindContext, node: Sema, ids: Map<Sema, number>): Promise<number>;
+/** Index flat branches for sub-spans of a deposit's byte stream, linked to
+ *  their structural chunks via durable CONTAINMENT edges. */
+export declare function indexSubSpans(ctx: MindContext, tree: Sema, ids: Map<Sema, number>): Promise<boolean>;
+/** Perceive, intern, and index a single input.  Returns the perceived tree,
+ *  root id, id map, and the changed (new) subtrees for halo reinforcement. */
+export declare function deposit(ctx: MindContext, input: Input, track: boolean): Promise<{
+    tree: Sema;
+    rootId: number;
+    ids: Map<Sema, number>;
+    changed: Sema[];
+}>;
+/** Ingest a single input (a bare experience, no continuation). */
+export declare function ingestOne(ctx: MindContext, input: Input): Promise<Sema & {
+    id: number;
+}>;
+/** Ingest a pair (context, continuation) — learn an edge and pour halos. */
+export declare function ingestPair(ctx: MindContext, ctxInput: Input, cont: Input): Promise<void>;
+/** Dispatch the public ingest input shapes onto one-input / pair handlers —
+ *  THE one reading of ingest's polymorphic surface (scalar, (context,
+ *  continuation) pair, or a list mixing bare inputs and pairs).  Both ingest
+ *  paths — the direct one below and {@link CachedIngest} — route through
+ *  this, so the shape-detection can never drift between them again (the
+ *  ingest cache once re-implemented it and drifted). */
+export declare function dispatchIngest(input: Input | (Input | [Input, Input])[], second: Input | undefined, onOne: (input: Input) => Promise<Sema & {
+    id: number;
+}>, onPair: (ctxInput: Input, cont: Input) => Promise<void>): Promise<(Sema & {
+    id: number;
+}) | undefined>;
+/** Ingest an input or array of inputs/pairs.  The public ingest entry point. */
+export declare function ingest(ctx: MindContext, input: Input | (Input | [Input, Input])[], second?: Input): Promise<(Sema & {
+    id: number;
+}) | undefined>;

package/dist/src/mind/learning.js

@@ -0,0 +1,233 @@
+// learning.ts — ingest and deposition (Section 7 of the mind).
+//
+//   Learning is DEPOSITION: perceive a stream into a tree and intern every
+//   node.  A fact is an EDGE between node ids; recall traverses edges.
+import { bindSeat, companySignature, isChunk } from "../sema.js";
+import { changedNodes } from "./types.js";
+import { inputBytes, perceiveDeposit, resolve, } from "./primitives.js";
+import { canonicalWindows, leafIdPrefix } from "./canonical.js";
+import { fold as foldVecs } from "../sema.js";
+/** Intern a perceived tree into node ids, bottom-up, sharing equal subtrees.
+ *  Returns the root node id and a map from tree nodes to their ids.
+ *
+ *  Memoized by NODE IDENTITY (ctx._internIds): the pyramid fold shares a
+ *  prefix's subtree OBJECTS across an accumulated context's deposits, and a
+ *  node already interned needs nothing again — its id is permanent
+ *  (content-addressed) and its intern-time side effects (gist capture, kid
+ *  rows) fired at first mint; re-interning was pure lookups.  A memo hit
+ *  therefore skips the WHOLE shared subtree, making the intern walk
+ *  O(new nodes) per deposit instead of O(context).  Only the hit node
+ *  itself enters `ids`; descendants stay reachable via the memo (see
+ *  idOf in indexSubSpans and the changedNodes prune). */
+export async function internTreeIds(ctx, node, ids) {
+    const known = ctx._internIds.get(node);
+    if (known !== undefined) {
+        ids.set(node, known);
+        return known;
+    }
+    let id;
+    if (node.kids === null) {
+        id = await ctx.store.putLeaf(node.leaf ?? new Uint8Array(0), node.v);
+    }
+    else {
+        const kds = [];
+        for (const k of node.kids)
+            kds.push(await internTreeIds(ctx, k, ids));
+        id = await ctx.store.putBranch(kds, node.v);
+    }
+    ids.set(node, id);
+    ctx._internIds.set(node, id);
+    return id;
+}
+/** Index flat branches for sub-spans of a deposit's byte stream, linked to
+ *  their structural chunks via durable CONTAINMENT edges. */
+export async function indexSubSpans(ctx, tree, ids) {
+    const chunkOf = [];
+    const streamIds = [];
+    const streamVecs = [];
+    const collect = (n) => {
+        if (isChunk(n)) {
+            // A chunk inside a memo-skipped shared subtree is absent from `ids`;
+            // the intern memo still knows it (same object).  A miss on both (the
+            // WeakMap entry was collected) only forfeits the seenBefore skip.
+            const chunkId = ids.get(n) ?? ctx._internIds.get(n);
+            for (const k of n.kids) {
+                const lid = k.leaf ? ctx.store.findLeaf(k.leaf) : null;
+                if (lid === null)
+                    return false;
+                streamIds.push(lid);
+                streamVecs.push(k.v);
+                chunkOf.push(chunkId);
+            }
+            return true;
+        }
+        if (n.kids) {
+            for (const k of n.kids)
+                if (!collect(k))
+                    return false;
+        }
+        return true;
+    };
+    if (!collect(tree))
+        return false;
+    const W = ctx.space.maxGroup; // write side of the canonical contract
+    const prev = ctx._prevSeen;
+    const seenBefore = (off, len) => {
+        if (!prev)
+            return false;
+        for (let i = off; i < off + len; i++) {
+            const c = chunkOf[i];
+            if (c === undefined || !prev.has(c))
+                return false;
+        }
+        return true;
+    };
+    const lens = streamIds.length >= W ? canonicalWindows(W) : [streamIds.length];
+    for (const len of lens) {
+        if (len < 1)
+            continue;
+        for (let off = 0; off + len <= streamIds.length; off++) {
+            if (seenBefore(off, len))
+                continue;
+            const winIds = streamIds.slice(off, off + len);
+            const flatId = ctx.store.findBranch(winIds) ??
+                await ctx.store.putBranch(winIds, foldVecs(ctx.space, streamVecs.slice(off, off + len)));
+            for (let i = off; i < off + len; i++) {
+                const c = chunkOf[i];
+                if (c !== undefined)
+                    ctx.store.addContainer(flatId, c);
+            }
+        }
+    }
+    return true;
+}
+/** Perceive, intern, and index a single input.  Returns the perceived tree,
+ *  root id, id map, and the changed (new) subtrees for halo reinforcement. */
+export async function deposit(ctx, input, track) {
+    const bytes = inputBytes(ctx, input);
+    // Deposit-shaped perception: stable-prefix tree SEEDING (see
+    // perceiveDeposit) — an accumulated context re-folds only its new suffix,
+    // O(turn) instead of O(context) per conversation turn.  Cache-only here
+    // (no store-probe fallback): a knownPrefixLength scan on every novel fact
+    // would cost O(n²) hashing, while conversation replays are always warm —
+    // re-deposition replays from the first turn, rebuilding the cache as it
+    // goes.
+    const tree = perceiveDeposit(ctx, bytes);
+    const ids = new Map();
+    const rootId = await internTreeIds(ctx, tree, ids);
+    const indexed = await indexSubSpans(ctx, tree, ids);
+    const leafIds = leafIdPrefix(ctx, bytes);
+    if (leafIds.length === bytes.length && leafIds.length >= 2) {
+        await ctx.store.putBranch(leafIds, tree.v);
+    }
+    const changed = (track && ctx._prevSeen)
+        ? changedNodes(tree, ids, ctx._prevSeen)
+        : [tree];
+    if (track)
+        ctx._prevSeen = indexed ? new Set(ids.values()) : null;
+    return { tree, rootId, ids, changed };
+}
+/** Ingest a single input (a bare experience, no continuation). */
+export async function ingestOne(ctx, input) {
+    const { tree, rootId, ids } = await deposit(ctx, input, true);
+    ctx.store.indexTarget(rootId);
+    const parts = tree.kids
+        ? tree.kids.map((k) => ids.get(k))
+        : [rootId];
+    const stride = ctx.space.maxGroup;
+    if (parts.length > stride) {
+        for (let i = 0; i + stride < parts.length; i += stride) {
+            await ctx.store.link(parts[i], parts[i + stride]);
+        }
+        if ((parts.length - 1) % stride !== 0) {
+            const lastStart = Math.floor((parts.length - 1) / stride) * stride;
+            if (lastStart < parts.length - 1) {
+                await ctx.store.link(parts[lastStart], parts[parts.length - 1]);
+            }
+        }
+    }
+    else {
+        for (const id of parts)
+            ctx.store.indexTarget(id);
+    }
+    return Object.assign(tree, { id: rootId });
+}
+/** For each right-edge suffix of the context bytes, resolve it against the
+ *  store.  A suffix whose resolved node is already a known form inherits the
+ *  continuation edge.  Gate: ≥ 2 structural parents (reused across deposits),
+ *  or (halo > 0 ∧ already an edge source).  Pure answers do not qualify. */
+async function propagateSuffixes(ctx, src, dst) {
+    const W = ctx.space.maxGroup;
+    const bytes = ctx.store.bytes(src);
+    const n = bytes.length;
+    if (n < 2 * W)
+        return;
+    // Existence prefilter — the write side of the canonical contract: every
+    // deposit interns its WHOLE byte stream as a flat branch of per-byte leaf
+    // ids (deposit(), canonical.ts).  A suffix is a stored form exactly when
+    // that flat twin exists, so one content-hash probe per offset decides;
+    // only a hit pays for resolve()'s deposit-shaped perception.  This keeps
+    // the scan free of river folds — O(1) probes over cheap byte hashes
+    // instead of O(suffix) vector folds per offset.
+    const leafIds = leafIdPrefix(ctx, bytes);
+    for (let i = 1; i <= n - W; i++) {
+        if (ctx.store.findBranch(leafIds.slice(i)) === null)
+            continue;
+        const id = resolve(ctx, bytes.subarray(i));
+        if (id === null || id === src)
+            continue;
+        const known = ctx.store.parentsFirst(id, 2).length >= 2 ||
+            (ctx.store.haloMass(id) > 0 && ctx.store.hasNext(id));
+        if (!known)
+            continue;
+        await ctx.store.link(id, dst);
+    }
+}
+/** Ingest a pair (context, continuation) — learn an edge and pour halos. */
+export async function ingestPair(ctx, ctxInput, cont) {
+    const c = await deposit(ctx, ctxInput, true);
+    const cont_ = await deposit(ctx, cont, false);
+    const ctxId = c.rootId, contId = cont_.rootId;
+    await ctx.store.link(ctxId, contId);
+    await propagateSuffixes(ctx, ctxId, contId);
+    // Halos pour company SIGNATURES (identity), not gists (content) — see
+    // companySignature in sema.ts.
+    const contSeat = bindSeat(ctx.space, companySignature(ctx.space, contId), 1);
+    for (const part of c.changed) {
+        const partId = c.ids.get(part);
+        await ctx.store.pourHalo(partId, contSeat);
+        await ctx.store.pourHalo(contId, bindSeat(ctx.space, companySignature(ctx.space, partId), 0));
+    }
+}
+/** Dispatch the public ingest input shapes onto one-input / pair handlers —
+ *  THE one reading of ingest's polymorphic surface (scalar, (context,
+ *  continuation) pair, or a list mixing bare inputs and pairs).  Both ingest
+ *  paths — the direct one below and {@link CachedIngest} — route through
+ *  this, so the shape-detection can never drift between them again (the
+ *  ingest cache once re-implemented it and drifted). */
+export async function dispatchIngest(input, second, onOne, onPair) {
+    if (Array.isArray(input) && !(input instanceof Uint8Array) &&
+        input.width === undefined) {
+        const arr = input;
+        if (arr.length === 2 && !Array.isArray(arr[0]) && !Array.isArray(arr[1])) {
+            await onPair(arr[0], arr[1]);
+            return undefined;
+        }
+        for (const item of arr) {
+            if (Array.isArray(item) && item.length === 2) {
+                await onPair(item[0], item[1]);
+            }
+            else
+                await onOne(item);
+        }
+        return undefined;
+    }
+    if (second === undefined)
+        return onOne(input);
+    await onPair(input, second);
+    return undefined;
+}
+/** Ingest an input or array of inputs/pairs.  The public ingest entry point. */
+export async function ingest(ctx, input, second) {
+    return dispatchIngest(input, second, (i) => ingestOne(ctx, i), (a, b) => ingestPair(ctx, a, b));
+}