@hviana/sema 0.1.0 → 0.1.2

package/dist/src/mind/mind.js

@@ -0,0 +1,300 @@
+// mind/mind.ts — perceive, deposit, recall, think, express.
+//
+// Memory is a content-addressed node graph (see store.ts). Learning is
+// DEPOSITION: perceive a stream into a tree and intern every node, so equal —
+// and, by resonance, similar — subtrees collapse to one shared node. A fact is
+// an EDGE between node ids; recall traverses edges; thinking completes the
+// query's OWN tree, node by node, to a fixed point. No whole, no weights.
+//
+// Architecture: 4 primitives × 2 patterns = all inference.
+// Implementation split across src/mind/*.ts — this file assembles the Mind class.
+import { makeKeyring, rng, setVecConfig } from "../vec.js";
+import { Alphabet } from "../alphabet.js";
+import { reachThreshold, } from "../geometry.js";
+import { BoundedMap } from "../store.js";
+import { SQliteStore } from "../store-sqlite.js";
+import { resolveConfig } from "../config.js";
+import { bytesEqual } from "../bytes.js";
+import { GraphSearch, } from "./graph-search.js";
+import { Alu } from "../alu/src/index.js";
+import { decodeText, Rationale, } from "./rationale.js";
+import { gistOf, inputBytes, perceive as perceiveImpl, resolve as resolveImpl, } from "./primitives.js";
+import { chooseNext, edgeAncestors as edgeAncestorsFn } from "./traverse.js";
+import { follow } from "./match.js";
+import { recognise, segment } from "./recognition.js";
+import { meaningOf } from "./resonance.js";
+import { climbAttention as climbAttentionFn, naturalBreak as naturalBreakFn, } from "./attention.js";
+import { aluToMechanism, defaultMechanisms, think } from "./pipeline.js";
+import { articulate } from "./articulation.js";
+import { ingest } from "./learning.js";
+import { rItem } from "./trace.js";
+// ═══════════════════════════════════════════════════════════════════════════
+// THE MIND
+// ═══════════════════════════════════════════════════════════════════════════
+export class Mind {
+    space;
+    alphabet;
+    store;
+    cfg;
+    /** The lightest-derivation engine over the Sema graph. */
+    search;
+    /** The grounding mechanisms iterated by {@link think}. */
+    mechanisms = [];
+    /** The live rationale tracer for the inference currently in flight, or null. */
+    trace = null;
+    /** Per-response memo of the consensus climb.  NOTE: this memo and
+     *  {@link recogniseMemo} are BYPASSED while a rationale trace is attached
+     *  (every mechanism must emit its own steps), so a traced respond re-pays
+     *  up to four consensus climbs plus repeat recognitions — that is where the
+     *  traced-vs-untraced latency multiple comes from, by design. */
+    climbMemo = null;
+    /** Per-response memo of recognise() — see {@link MindContext.recogniseMemo}. */
+    recogniseMemo = null;
+    /** Per-response memo of perceive() — see {@link MindContext.perceiveMemo}. */
+    perceiveMemo = null;
+    /** The perceived gist of the query currently being answered.  Set by `think`
+     *  before the graph search runs; `chooseNext` consults it as a gate (a null
+     *  guide means no query is in flight, so structural walkers keep plain
+     *  first-edge behaviour) and the reverse projection uses it for
+     *  reverse-recall disambiguation via `chooseAmong`. */
+    _edgeGuide = null;
+    /** Per-response memo of {@link chooseNext} picks — ensures every mechanism
+     *  of a single response follows the SAME continuation for each ambiguous
+     *  context node. */
+    _edgeChoice = new Map();
+    /** Previous deposit's seen node ids for incremental change detection. */
+    _prevSeen = null;
+    /** Session cache of node-id → perceived gist for candidate scoring — see
+     *  {@link MindContext._gistCache}.  32 MB ≈ 8K gists at D=1024; hub
+     *  candidate sets (√N at most) fit comfortably and recur across queries. */
+    _gistCache = new BoundedMap(32_000_000, (v) => v.byteLength);
+    // Deposit-path fold-pyramid cache (see MindContext) — ENTRY-count
+    // bounded: a pyramid costs ~KB per content byte (one D-float gist per
+    // interior node), and only the few live conversation chains need to stay
+    // warm, so 8 entries is the honest budget.
+    _depositTrees = new BoundedMap(8);
+    _depositLens = new Set();
+    _internIds = new WeakMap();
+    // ── GraphSearchHost implementation ─────────────────────────────────────
+    /** Canonical node id of a byte span.  Required by GraphSearchHost & MindContext. */
+    resolve(bytes) {
+        return resolveImpl(this, bytes);
+    }
+    // recogniseSpan wraps recognise
+    recogniseSpan(bytes) {
+        const r = recognise(this, bytes);
+        return { sites: r.sites, leaves: r.leaves, splits: r.splits };
+    }
+    /** Disambiguate among multiple learnt continuations of the same context node.
+     *  Required by {@link GraphSearchHost} — the graph search calls this through the
+     *  host interface when a recognised form has more than one outgoing edge.
+     *  Delegates to the standalone {@link chooseNext} which picks the candidate
+     *  with the most distributional evidence (highest `prevOf` count — the
+     *  structural manifestation of its halo).  When evidence is equal the
+     *  first-inserted edge wins. */
+    chooseNext(node) {
+        return chooseNext(this, node, this._edgeGuide);
+    }
+    constructor(optsOrCfg, storeArg, _fromStore) {
+        let userMechanisms = [];
+        let userFactories = [];
+        if (_fromStore !== undefined) {
+            this.cfg = resolveConfig(optsOrCfg);
+            this.store = storeArg;
+        }
+        else {
+            const { store: optsStore, mechanisms: userMechs, mechanismFactories: userFacts, ...rest } = (optsOrCfg ?? {});
+            this.cfg = resolveConfig(rest);
+            this.store = optsStore ?? new SQliteStore({
+                maxGroup: this.cfg.geometry.maxGroup,
+            });
+            userMechanisms = userMechs ?? [];
+            userFactories = userFacts ?? [];
+        }
+        setVecConfig({
+            normalizeEpsilon: this.cfg.normalizeEpsilon,
+            cosineEpsilon: this.cfg.cosineEpsilon,
+        });
+        const seedRand = rng((this.cfg.seed ^ 0x9e3779) >>> 0);
+        const seats = makeKeyring(this.store.D, Math.max(8, this.cfg.geometry.maxGroup), seedRand);
+        this.space = {
+            D: this.store.D,
+            seats,
+            rand: rng((this.cfg.seed ^ 0x51f15e) >>> 0),
+            maxGroup: this.cfg.geometry.maxGroup,
+        };
+        this.alphabet = new Alphabet(this.cfg.seed, this.store.D, this.cfg.alphabet);
+        this.search = new GraphSearch(this.store, this.space.maxGroup, this);
+        // Build the mechanism list: default grounding + ALU + user mechanisms.
+        for (const m of defaultMechanisms)
+            this.mechanisms.push(m);
+        const host = this.extensionHost();
+        if (this.cfg.alu.enabled) {
+            const alu = new Alu({
+                tol: this.cfg.alu.tol,
+                maxIter: this.cfg.alu.maxIter,
+                precision: this.cfg.alu.precision,
+            }, host);
+            this.mechanisms.push(aluToMechanism(alu));
+        }
+        for (const m of userMechanisms)
+            this.mechanisms.push(m);
+        for (const f of userFactories)
+            this.mechanisms.push(f(host));
+    }
+    // ── Public API ───────────────────────────────────────────────────────────
+    /** Exposed for tests: the consensus climb over query sub-regions. */
+    climbAttention(query, k, mode = "inverse") {
+        return climbAttentionFn(this, query, k, mode);
+    }
+    /** Exposed for tests: climb the structural DAG from a node to its
+     *  edge-bearing ancestor contexts. */
+    edgeAncestors(id, contextCount) {
+        return edgeAncestorsFn(this, id, contextCount);
+    }
+    /** Exposed for tests: find the natural break point in a sorted vote list. */
+    naturalBreak(votes) {
+        return naturalBreakFn(votes);
+    }
+    // ── respond ───────────────────────────────────────────────────────────
+    /** Perceive input into a content-defined tree.  Deterministic — identical
+     *  bytes always produce an identical tree.  Public for ingest-cache. */
+    perceive(input, leafAt, lookup) {
+        return perceiveImpl(this, input, leafAt, lookup);
+    }
+    /** Open one response's transient state — the tracer and the per-response
+     *  memos.  Paired with {@link endResponse}; the ONE place this state is
+     *  created, so adding a memo cannot forget its reset. */
+    beginResponse(inspectRationale) {
+        this.trace = inspectRationale ? new Rationale(inspectRationale) : null;
+        this.climbMemo = new WeakMap();
+        this.recogniseMemo = new WeakMap();
+        this.perceiveMemo = new Map();
+    }
+    /** Close one response's transient state — every per-response field, incl.
+     *  the edge guide/choices `think` sets mid-flight. */
+    endResponse() {
+        this.trace = null;
+        this.climbMemo = null;
+        this.recogniseMemo = null;
+        this.perceiveMemo = null;
+        this._edgeGuide = null;
+        this._edgeChoice.clear();
+    }
+    async respond(input, inspectRationale) {
+        this.beginResponse(inspectRationale);
+        try {
+            const inBytes = inputBytes(this, input);
+            const top = this.trace?.enter("respond", [
+                rItem(inBytes, "query"),
+            ]);
+            const thought = await think(this, inBytes, this.mechanisms);
+            if (thought === null) {
+                top?.done([], "nothing to perceive or an empty store — no answer");
+                return { v: null, bytes: new Uint8Array(0) };
+            }
+            const voiced = await articulate(this, thought.bytes, inBytes);
+            top?.done([rItem(voiced, "answer", resolveImpl(this, voiced) ?? undefined)], "the answer, re-voiced in the asker's words");
+            return {
+                v: gistOf(this, voiced),
+                bytes: voiced,
+                provenance: thought.provenance,
+            };
+        }
+        finally {
+            this.endResponse();
+        }
+    }
+    /** Text view of {@link respond}.  NUL bytes (0x00) are stripped before
+     *  decoding — they are structural padding in text answers.  LOSSY for a
+     *  binary answer that legitimately contains NULs: use {@link respond} and
+     *  read `bytes` directly for binary/grid modalities. */
+    async respondText(input, inspectRationale) {
+        const r = await this.respond(input, inspectRationale);
+        return decodeText(r.bytes);
+    }
+    async embedding(input) {
+        return (await this.respond(input)).v;
+    }
+    /** Kinship note: the vector arm below is a miniature of recall's tier 3
+     *  (resonate → reach gate → read out the nearest form's bytes) — the
+     *  read-out direction of the same operation, without recall's grounding
+     *  ladder.  If either side's acceptance rule changes, revisit the other. */
+    async express(idOrV) {
+        if (typeof idOrV === "number")
+            return this.store.bytes(idOrV);
+        const [hit] = await this.store.resonate(idOrV, 1);
+        // The same confidence floor recall uses: a vector whose nearest stored
+        // form sits below the reach threshold relates to NOTHING in the store —
+        // returning that form's bytes anyway would fabricate an answer from an
+        // unrelated neighbour.  Silence is the honest read-out.
+        if (hit && hit.score >= reachThreshold(this.space.maxGroup)) {
+            return this.store.bytes(hit.id);
+        }
+        return new Uint8Array(0);
+    }
+    // ── Learning ─────────────────────────────────────────────────────────────
+    async ingest(input, second) {
+        return ingest(this, input, second);
+    }
+    // ── Extension Surface ────────────────────────────────────────────────────
+    extensionHost() {
+        const mind = this;
+        return {
+            meaningOf: (bytes, anchors) => meaningOf(this, bytes, anchors),
+            continuation: (bytes) => this.groundedContinuation(bytes),
+            segment: (bytes) => segment(this, bytes).map((s) => ({ i: s.start, j: s.end })),
+            get reach() {
+                return mind.space.maxGroup;
+            },
+        };
+    }
+    async groundedContinuation(bytes) {
+        const id = resolveImpl(this, bytes);
+        if (id === null)
+            return null;
+        const grounded = await follow(this, id);
+        if (grounded !== null && !bytesEqual(grounded, bytes))
+            return grounded;
+        return null;
+    }
+    // ── Content-index repair ───────────────────────────────────────────────
+    /** Re-index structurally-important nodes whose gists were evicted from the
+     *  pending cache before they reached the content index.  See {@link
+     *  Store.repairContentIndex} for the contract; this method wires the
+     *  Mind's perception into the store's repair walk.
+     *
+     *  Run this after training or at checkpoints to restore recall reach for
+     *  nodes that bridge experiences but were never indexed.  A pure interior
+     *  node (no edges, no halo) is deliberately skipped — it is scaffolding,
+     *  not an experience root or bridge, and regenerating its gist would waste
+     *  I/O and index space for no recall benefit.
+     *
+     *  @param minParents  only repair nodes with ≥ this many structural parents
+     *                     (default 2 — structural bridges)
+     *  @returns number of nodes added to the content index */
+    async repairContentIndex(minParents = 2) {
+        return this.store.repairContentIndex(async (id) => {
+            const bytes = this.store.bytes(id);
+            if (bytes.length === 0)
+                return null;
+            return gistOf(this, bytes);
+        }, minParents);
+    }
+    // ── Persistence ──────────────────────────────────────────────────────────
+    async save() {
+        const meta = new TextEncoder().encode(JSON.stringify(this.cfg));
+        await this.store.saveSnapshot(meta);
+        return meta;
+    }
+    static async load(snapshot, store) {
+        const cfg = JSON.parse(new TextDecoder().decode(snapshot));
+        return new Mind(cfg, store, true);
+    }
+    static async loadFromStore(store) {
+        const meta = await store.loadSnapshot();
+        if (!meta)
+            throw new Error("no snapshot in store");
+        return Mind.load(meta, store);
+    }
+}

package/dist/src/mind/pipeline-mechanism.d.ts

@@ -0,0 +1,142 @@
+import type { AncestorReach, MindContext, Recognition } from "./types.js";
+import type { AttentionRead } from "./types.js";
+import type { ComputedSpan } from "../extension.js";
+import type { Vec } from "../vec.js";
+import { type GradedRun } from "./match.js";
+export declare class Precomputed {
+    readonly ctx: MindContext;
+    readonly query: Uint8Array;
+    /** Recognition result (structural + canonical). */
+    readonly rec: Recognition;
+    /** Computed spans from mechanisms that implement `parse()` (e.g. ALU). */
+    readonly computed: ComputedSpan[];
+    /** The query's gist — the response-wide disambiguation guide. */
+    readonly guide: Vec;
+    /** The response's evidence-breadth constant: how many ranked candidates the
+     *  resonance probes, the weave alignment, and the climb all consider.
+     *  Derived once from config; every consumer reads it here. */
+    readonly k: number;
+    constructor(ctx: MindContext, query: Uint8Array, 
+    /** Recognition result (structural + canonical). */
+    rec: Recognition, 
+    /** Computed spans from mechanisms that implement `parse()` (e.g. ALU). */
+    computed: ComputedSpan[], 
+    /** The query's gist — the response-wide disambiguation guide. */
+    guide: Vec);
+    private _windows?;
+    /** Content-addressed W-window identities for every position in the query
+     *  (offset → node id).  O(|query|) probes. */
+    get queryWindows(): Map<number, number>;
+    private _resolved?;
+    /** The node id of the query itself, or null when it is not a stored form.
+     *  O(|query|) probes. */
+    get queryResolved(): number | null;
+    private _anchorWindows;
+    /** Content-addressed W-window identities of one anchor's own bytes
+     *  (offset → node id), memoised per anchor.  Confluence intersects these;
+     *  any future identity-based mechanism reads the same cache. */
+    windowsOf(anchor: number): Map<number, number>;
+    /** Shared memo for {@link reachOf} (structural-IDF reads): a window's
+     *  ancestor reach is a pure function of the read-only store, so one
+     *  response-scoped memo serves every mechanism that prices commonality. */
+    readonly reachMemo: Map<number, AncestorReach>;
+    private _attention?;
+    /** The full consensus climb (roots + ranked anchors) — the query-level
+     *  evidence CAST, confluence, extraction, recall's scaffolding tier, and
+     *  fusion all share.  Computed on first access; a query no mechanism
+     *  climbs for (e.g. one an extension decided outright) never pays for it. */
+    attention(): Promise<AttentionRead>;
+    private _weave?;
+    /** Result of {@link alignGraded} for the first k ranked anchors —
+     *  O(k · |query| · |ctx|).  Consumed by CAST; reusable by any future
+     *  mechanism doing analogical transfer. */
+    weave(): Promise<WeaveInfo>;
+    /** Span-shaped classification of one ranked anchor, memoised per anchor id
+     *  so repeated calls (extraction's own early-exit scan, any future
+     *  template-based mechanism) never redo the work.  Deliberately NOT an
+     *  eager all-anchors map: `skillExemplar` is the expensive part of
+     *  extraction (capped fan-out reads plus an O(|ctx|) scan), and most
+     *  queries are answered by the FIRST ranked anchor that qualifies — paying
+     *  for every ranked anchor regardless of where the scan stops would turn
+     *  an early-exit lookup into full O(k) work on every query. */
+    private _spanShaped;
+    spanShapedOf(anchor: number): Promise<SkillInfo | null>;
+    /** Every ranked anchor's classification at once, sharing the same
+     *  per-anchor cache as {@link spanShapedOf} — for a mechanism that
+     *  genuinely needs the full picture (not an early-exit scan).  Mixing
+     *  access patterns across mechanisms never duplicates work: whichever
+     *  anchors an early-exit consumer already asked for are reused here, and
+     *  whichever this computes first are reused by a later early-exit scan. */
+    spanShapedAll(): Promise<Map<number, SkillInfo | null>>;
+}
+/** The weave-local structural alignment, computed once and consumed by CAST
+ *  (and any future mechanism doing analogical transfer). */
+export interface WeaveInfo {
+    /** Per-anchor alignment: context bytes, vote weight, and graded runs. */
+    points: Array<{
+        anchor: number;
+        vote: number;
+        ctx: Uint8Array;
+        runs: GradedRun[];
+    }>;
+    /** Weighted depth at each query byte — sum of alignment weights.
+     *  `depth[i]` is the total evidence that byte i is shared among the
+     *  aligned structures. */
+    depth: Float64Array;
+}
+/** Span-shaped classification of one anchor — the structural information
+ *  extraction uses to decide whether a learned fact can serve as a template
+ *  for reading an analogous span out of the query. */
+export interface SkillInfo {
+    contextBytes: Uint8Array;
+    answerBytes: Uint8Array;
+}
+/** Raw result from a mechanism's `run()`.  The pipeline computes the weight
+ *  from `moves` + `PASS * unaccounted(accounted)` — the mechanism does not
+ *  know about the cost ladder.
+ *
+ *  When `weight` is present, the pipeline uses it directly instead of
+ *  computing `weigh(accounted, moves)`.  This is for mechanisms whose cost
+ *  is derived externally (e.g. cover: the A*LD derivation's g-value). */
+export interface MechanismResult {
+    bytes: Uint8Array;
+    accounted: Array<[number, number]>;
+    moves: number;
+    used?: ReadonlySet<number>;
+    unexplained: string;
+    /** Explicit weight override.  When absent, weight = moves + PASS·unaccounted. */
+    weight?: number;
+    /** Override the mechanism's default provenance for this result.
+     *  When absent, the pipeline uses `mech.provenance`. */
+    provenance?: string;
+}
+export interface PipelineMechanism {
+    /** Stable identifier for trace/debug. */
+    readonly name: string;
+    /** Which provenance tag the pipeline attaches to this mechanism's answers. */
+    readonly provenance: string;
+    /** Parse authoritative spans BEFORE the grounding loop.
+     *  Only needed by computational mechanisms (e.g. ALU).  Results from ALL
+     *  mechanisms that implement this are collected into `Precomputed.computed`
+     *  before any `floor()` or `run()` is called. */
+    parse?(query: Uint8Array): Promise<ComputedSpan[]>;
+    /** Admissible lower bound on this mechanism's weight.
+     *  Returns `null` when the mechanism structurally cannot fire.
+     *
+     *  `worthRunning(cheapFloor)` reports whether the CURRENT incumbent
+     *  (established by mechanisms that already ran this response, cover being
+     *  first — see `defaultMechanisms`) could still be beaten by a floor no
+     *  tighter than `cheapFloor`.  THE INVESTMENT DISCIPLINE: before
+     *  first-touching an expensive shared analysis (`pre.attention()`,
+     *  `pre.weave()`, …), check `worthRunning(bound)` with this mechanism's
+     *  cheapest possible bound — and when it fails, RETURN THE BOUND rather
+     *  than null.  The bound is still admissible (it never overstates cost),
+     *  the pipeline's own check then prunes `run()` and records the truthful
+     *  "cannot beat incumbent" trace note, and no analysis was computed just
+     *  to be discarded.  This is uniform: no mechanism asks what produced the
+     *  incumbent — a computed extension result and an ordinary cheap cover
+     *  prune the same way. */
+    floor(ctx: MindContext, query: Uint8Array, pre: Precomputed, worthRunning: (floor: number) => boolean): Promise<number | null>;
+    /** Produce candidate answers. */
+    run(ctx: MindContext, query: Uint8Array, pre: Precomputed): Promise<MechanismResult[]>;
+}

package/dist/src/mind/pipeline-mechanism.js

@@ -0,0 +1,213 @@
+// pipeline-mechanism.ts — the uniform grounding-mechanism interface.
+//
+// Every grounding mechanism (CAST, confluence, cover, extraction, recall, ALU,
+// user extensions) implements this ONE interface.  The pipeline (think()) sees
+// a list of PipelineMechanism objects — it never imports a mechanism-specific
+// type and never has a special-case branch for any mechanism.
+//
+// The four constraints of the free-will architecture (§14.5):
+//   1. DECOUPLING — mechanisms import nothing from each other or from pipeline.
+//   2. DECLARED COMPETENCE — floor() returns null when impossible, a number when
+//      possible.  Binary, auditable, no learned scores.
+//   3. VISIBLE BUDGET — every mechanism carries its own caps internally (√N, k).
+//   4. TRAVELING EVIDENCE — run() returns MechanismResult with accounted, moves,
+//      and unexplained.  The pipeline computes the weight.
+import { windowIds } from "./canonical.js";
+import { read, resolve } from "./primitives.js";
+import { alignGraded } from "./match.js";
+import { climbAttentionAll } from "./attention.js";
+import { skillExemplar } from "./mechanisms/extraction.js";
+// ── Precomputed ──────────────────────────────────────────────────────────────
+//
+// Precomputed is a LAZY container for structural analyses of the query — the
+// ONE place a response's shared evidence lives, for inter-mechanism exchange
+// and for analyses future mechanisms will want.  Eager fields (rec, computed,
+// guide) are populated by the pipeline before the mechanism loop; everything
+// expensive is a lazily-cached method that computes on first access.  A
+// mechanism that never asks for an analysis pays nothing for it; two
+// mechanisms asking for the same analysis pay once.
+//
+// This design serves THREE purposes:
+//   1. SHARING — when two mechanisms need the same analysis, it's computed once
+//      (even under trace, where the ctx-level memos are deliberately bypassed).
+//   2. EXTENSIBILITY — a new analysis is one method in one file.
+//   3. DECLARATIVE COST — a mechanism's floor() checks its cheap gates and the
+//      pipeline's `worthRunning` predicate BEFORE first-touching an expensive
+//      analysis, so lazy analyses are only ever computed for a mechanism that
+//      could still win.
+export class Precomputed {
+    ctx;
+    query;
+    rec;
+    computed;
+    guide;
+    /** The response's evidence-breadth constant: how many ranked candidates the
+     *  resonance probes, the weave alignment, and the climb all consider.
+     *  Derived once from config; every consumer reads it here. */
+    k;
+    constructor(ctx, query, 
+    /** Recognition result (structural + canonical). */
+    rec, 
+    /** Computed spans from mechanisms that implement `parse()` (e.g. ALU). */
+    computed, 
+    /** The query's gist — the response-wide disambiguation guide. */
+    guide) {
+        this.ctx = ctx;
+        this.query = query;
+        this.rec = rec;
+        this.computed = computed;
+        this.guide = guide;
+        this.k = ctx.cfg.recallQueryK * 2;
+    }
+    // ── Cheap lazy analyses ───────────────────────────────────────────────
+    _windows;
+    /** Content-addressed W-window identities for every position in the query
+     *  (offset → node id).  O(|query|) probes. */
+    get queryWindows() {
+        return this._windows ??= windowIds(this.ctx, this.query);
+    }
+    _resolved;
+    /** The node id of the query itself, or null when it is not a stored form.
+     *  O(|query|) probes. */
+    get queryResolved() {
+        if (this._resolved === undefined) {
+            this._resolved = resolve(this.ctx, this.query);
+        }
+        return this._resolved;
+    }
+    _anchorWindows = new Map();
+    /** Content-addressed W-window identities of one anchor's own bytes
+     *  (offset → node id), memoised per anchor.  Confluence intersects these;
+     *  any future identity-based mechanism reads the same cache. */
+    windowsOf(anchor) {
+        let w = this._anchorWindows.get(anchor);
+        if (w === undefined) {
+            w = windowIds(this.ctx, read(this.ctx, anchor));
+            this._anchorWindows.set(anchor, w);
+        }
+        return w;
+    }
+    /** Shared memo for {@link reachOf} (structural-IDF reads): a window's
+     *  ancestor reach is a pure function of the read-only store, so one
+     *  response-scoped memo serves every mechanism that prices commonality. */
+    reachMemo = new Map();
+    // ── Expensive lazy analyses ───────────────────────────────────────────
+    //
+    // Async, cached-by-promise: the first caller starts the computation, every
+    // later caller (any mechanism, any phase) awaits the same promise.  A
+    // mechanism MUST check its cheap floor gates and the pipeline's
+    // `worthRunning` predicate before first-touching one of these.
+    _attention;
+    /** The full consensus climb (roots + ranked anchors) — the query-level
+     *  evidence CAST, confluence, extraction, recall's scaffolding tier, and
+     *  fusion all share.  Computed on first access; a query no mechanism
+     *  climbs for (e.g. one an extension decided outright) never pays for it. */
+    attention() {
+        return this._attention ??= climbAttentionAll(this.ctx, this.query, this.k);
+    }
+    _weave;
+    /** Result of {@link alignGraded} for the first k ranked anchors —
+     *  O(k · |query| · |ctx|).  Consumed by CAST; reusable by any future
+     *  mechanism doing analogical transfer. */
+    weave() {
+        return this._weave ??= this.attention().then((climb) => computeWeave(this.ctx, this.query, this, climb));
+    }
+    /** Span-shaped classification of one ranked anchor, memoised per anchor id
+     *  so repeated calls (extraction's own early-exit scan, any future
+     *  template-based mechanism) never redo the work.  Deliberately NOT an
+     *  eager all-anchors map: `skillExemplar` is the expensive part of
+     *  extraction (capped fan-out reads plus an O(|ctx|) scan), and most
+     *  queries are answered by the FIRST ranked anchor that qualifies — paying
+     *  for every ranked anchor regardless of where the scan stops would turn
+     *  an early-exit lookup into full O(k) work on every query. */
+    _spanShaped = new Map();
+    spanShapedOf(anchor) {
+        let p = this._spanShaped.get(anchor);
+        if (p === undefined) {
+            p = skillExemplar(this.ctx, anchor, this.guide);
+            this._spanShaped.set(anchor, p);
+        }
+        return p;
+    }
+    /** Every ranked anchor's classification at once, sharing the same
+     *  per-anchor cache as {@link spanShapedOf} — for a mechanism that
+     *  genuinely needs the full picture (not an early-exit scan).  Mixing
+     *  access patterns across mechanisms never duplicates work: whichever
+     *  anchors an early-exit consumer already asked for are reused here, and
+     *  whichever this computes first are reused by a later early-exit scan. */
+    async spanShapedAll() {
+        const { ranked } = await this.attention();
+        const out = new Map();
+        for (const cand of ranked) {
+            if (out.has(cand.anchor))
+                continue;
+            out.set(cand.anchor, await this.spanShapedOf(cand.anchor));
+        }
+        return out;
+    }
+}
+function computeWeave(ctx, query, pre, climb) {
+    const quantum = ctx.space.maxGroup;
+    const { ranked } = climb;
+    const rankedCapped = ranked.length > pre.k ? ranked.slice(0, pre.k) : ranked;
+    const depth = new Float64Array(query.length);
+    const points = [];
+    // WEAVE-SCALE anchors only: CAST transfers structure between things the
+    // QUERY weaves together — query-scale structures.  A context an order of
+    // magnitude beyond the query is not woven BY the query (the query can at
+    // most quote a fragment of it, and fragment-level evidence is exactly what
+    // recognition and the cover already handle); CAST's own comparison gate
+    // demands `ctx.length ≤ query.length` before it fires, and its
+    // substitution seats sit within a quantum of a context's start.  W is the
+    // perceptual quantum — the same scale multiplier the bridge's phrase-scale
+    // contract uses.  The prefix-capped read makes an oversized anchor cost a
+    // bounded read instead of reconstructing (and then canonically
+    // recognising) a corpus-sized deposit: profiled on a 17.7M-node store,
+    // uncapped weaves spent 5–8s per query recognising conversation-length
+    // anchors that could never form a weave point.
+    const capBytes = query.length * quantum;
+    for (const cand of rankedCapped) {
+        const ctxBytes = read(ctx, cand.anchor, capBytes + 1);
+        if (ctxBytes.length === 0 || ctxBytes.length > capBytes)
+            continue;
+        const raw = alignGraded(ctx, query, ctxBytes, pre.rec.sites);
+        if (raw.length === 0)
+            continue;
+        for (const r of raw) {
+            for (let i = r.qs; i < r.qe; i++)
+                depth[i] += r.weight;
+        }
+        const free = [];
+        for (const r of raw) {
+            let { qs, qe, cs, weight } = r;
+            for (const p of points) {
+                for (const o of p.runs) {
+                    if (qs >= qe)
+                        break;
+                    if (o.qe <= qs || o.qs >= qe)
+                        continue;
+                    const left = Math.max(0, o.qs - qs);
+                    const right = Math.max(0, qe - o.qe);
+                    if (left >= right)
+                        qe = qs + left;
+                    else {
+                        cs += qe - right - qs;
+                        qs = qe - right;
+                    }
+                }
+            }
+            if (qe - qs >= Math.min(quantum, ctxBytes.length)) {
+                free.push({ qs, qe, cs, weight });
+            }
+        }
+        if (free.length > 0) {
+            points.push({
+                anchor: cand.anchor,
+                vote: cand.vote,
+                ctx: ctxBytes,
+                runs: free,
+            });
+        }
+    }
+    return { points, depth };
+}

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

@@ -0,0 +1,20 @@
+import type { MindContext } from "./types.js";
+import { type PipelineMechanism } from "./pipeline-mechanism.js";
+export { resolveConcepts, resolveConnectors } from "./mechanisms/cover.js";
+export { aluToMechanism } from "./mechanisms/alu.js";
+export declare const defaultMechanisms: PipelineMechanism[];
+export type Provenance = "cast" | "join" | "cover" | "extract" | "recall" | "recall-echo";
+export interface Thought {
+    bytes: Uint8Array;
+    provenance: Provenance;
+}
+/** Think: a single lightest-derivation exploration of the Sema graph.
+ *
+ *  Every answer travels the same path:
+ *    1. Pre-computation — recognise, extension parse, guide; everything
+ *       expensive stays lazy on Precomputed until a mechanism asks.
+ *    2. Grounding — every mechanism yields candidates weighed in the one
+ *       cost ladder; the lightest grounding derivation wins.
+ *    3. Post-grounding — diagnostics (narrowDecision, thinGrounding),
+ *       reasoning (multi-hop), fusion (multi-topic). */
+export declare function think(ctx: MindContext, query: Uint8Array, mechs?: readonly PipelineMechanism[]): Promise<Thought | null>;