@hviana/sema 0.1.0

package/src/mind/index.ts

@@ -0,0 +1,18 @@
+// 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";
+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/src/mind/junction.ts

@@ -0,0 +1,347 @@
+// 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 type { MindContext } from "./types.js";
+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";
+
+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 function junctionSeeds(ctx: MindContext, b: Uint8Array): number[] {
+  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]];
+}
+
+/** 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[]>;
+}
+const walkCaches = new WeakMap<object, WalkCache>();
+export function walkCache(ctx: MindContext): WalkCache | null {
+  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: MindContext,
+  cache: WalkCache | null,
+  id: number,
+  cap: number,
+): Uint8Array {
+  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: MindContext,
+  cache: WalkCache | null,
+  id: number,
+  limit: number,
+): number[] {
+  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: MindContext,
+  cache: WalkCache | null,
+  id: number,
+  limit: number,
+): number[] {
+  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: 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 = false,
+): Junction[] {
+  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: Junction[] = [];
+  const cache = walkCache(ctx);
+  const seen = new Set<number>(seeds);
+  const stack: Array<{ id: number; d: number }> = 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: MindContext,
+  left: Uint8Array,
+  right: Uint8Array,
+  maxContainer: number,
+  unordered = false,
+): Junction[] {
+  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: MindContext,
+  left: Uint8Array,
+  right: Uint8Array,
+  maxInterior: number,
+  unordered = false,
+): Promise<Junction[]> {
+  const out: Junction[] = [];
+
+  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/src/mind/learning.ts

@@ -0,0 +1,246 @@
+// 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 { Vec } from "../vec.js";
+import { bindSeat, companySignature, isChunk, Sema } from "../sema.js";
+import type { Input, MindContext } from "./types.js";
+import { changedNodes } from "./types.js";
+import { inputBytes, perceive, perceiveDeposit } 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: MindContext,
+  node: Sema,
+  ids: Map<Sema, number>,
+): Promise<number> {
+  const known = ctx._internIds.get(node);
+  if (known !== undefined) {
+    ids.set(node, known);
+    return known;
+  }
+  let id: number;
+  if (node.kids === null) {
+    id = await ctx.store.putLeaf(node.leaf ?? new Uint8Array(0), node.v);
+  } else {
+    const kds: number[] = [];
+    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: MindContext,
+  tree: Sema,
+  ids: Map<Sema, number>,
+): Promise<boolean> {
+  const chunkOf: Array<number | undefined> = [];
+  const streamIds: number[] = [];
+  const streamVecs: Vec[] = [];
+  const collect = (n: Sema): boolean => {
+    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: number, len: number): boolean => {
+    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: MindContext,
+  input: Input,
+  track: boolean,
+): Promise<
+  { tree: Sema; rootId: number; ids: Map<Sema, number>; changed: Sema[] }
+> {
+  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<Sema, number>();
+  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: MindContext,
+  input: Input,
+): Promise<Sema & { id: number }> {
+  const { tree, rootId, ids } = await deposit(ctx, input, true);
+  ctx.store.indexTarget(rootId);
+  const parts: number[] = 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 });
+}
+
+/** Ingest a pair (context, continuation) — learn an edge and pour halos. */
+export async function ingestPair(
+  ctx: MindContext,
+  ctxInput: Input,
+  cont: Input,
+): Promise<void> {
+  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);
+
+  // 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: 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> {
+  if (
+    Array.isArray(input) && !(input instanceof Uint8Array) &&
+    (input as { width?: unknown }).width === undefined
+  ) {
+    const arr = input as (Input | [Input, Input])[];
+    if (
+      arr.length === 2 && !Array.isArray(arr[0]) && !Array.isArray(arr[1])
+    ) {
+      await onPair(arr[0] as Input, arr[1] as Input);
+      return undefined;
+    }
+    for (const item of arr) {
+      if (Array.isArray(item) && item.length === 2) {
+        await onPair(item[0], item[1]);
+      } else await onOne(item as Input);
+    }
+    return undefined;
+  }
+  if (second === undefined) return onOne(input as Input);
+  await onPair(input as Input, second);
+  return undefined;
+}
+
+/** Ingest an input or array of inputs/pairs.  The public ingest entry point. */
+export async function ingest(
+  ctx: MindContext,
+  input: Input | (Input | [Input, Input])[],
+  second?: Input,
+): Promise<(Sema & { id: number }) | undefined> {
+  return dispatchIngest(
+    input,
+    second,
+    (i) => ingestOne(ctx, i),
+    (a, b) => ingestPair(ctx, a, b),
+  );
+}