@hviana/sema 0.3.0 → 0.4.1

package/src/mind/mind.ts

@@ -155,6 +155,9 @@ import { aluToMechanism, defaultMechanisms, think } from "./pipeline.js";
 import { articulate } from "./articulation.js";
 import { ingest } from "./learning.js";
 import { rItem } from "./trace.js";
+// The work meter is exported from src/index.ts (via src/meter.ts) — the one
+// definition; the Mind only consumes it.
+import { type CostReport, Meter } from "../meter.js";
 
 // ── MindOptions ───────────────────────────────────────────────────────────
 
@@ -174,6 +177,15 @@ export interface MindOptions {
   mechanismFactories?: ((
     host: import("../extension.js").ExtensionHost,
   ) => import("./pipeline-mechanism.js").PipelineMechanism)[];
+  /** Measure the computational usage of every inference call — see
+   *  src/meter.ts.  Off by default and free when off (one null check per
+   *  store read); on, each `respond`/`respondTurn` leaves a {@link
+   *  Mind.lastCost} report behind.  Counters are deterministic, so two runs
+   *  of the same query on the same store are diffable; the millisecond
+   *  fields are not.  Profiling NEVER changes an answer — but note that
+   *  attaching a RATIONALE does (traced responses bypass the ctx memos,
+   *  AGENTS §2.11), so profile without a trace. */
+  profile?: boolean;
   /** Content canonicalizer applied to EVERY response (any modality) for
    *  equivalence-class resolution — see src/canon.ts.  Text entry points
    *  ({@link Mind.respondText}, {@link Mind.respondTurnText}) inject the
@@ -215,6 +227,22 @@ export class Mind implements MindContext {
    *  point decide (text entry points inject {@link textCanon}). */
   private _canonOpt: Canon | false | null = null;
 
+  /** The work accumulator for the inference call in flight — see
+   *  {@link MindContext.meter}.  Non-null only between beginResponse and
+   *  endResponse, and only when the Mind was constructed with
+   *  `{ profile: true }`. */
+  meter: Meter | null = null;
+
+  /** Whether {@link MindOptions.profile} was set. */
+  private _profile = false;
+
+  /** The computational-usage report of the LAST completed inference call, or
+   *  null when profiling is off (or nothing has been asked yet).  Overwritten
+   *  by every `respond`/`respondTurn`; copy it if you are aggregating.  See
+   *  {@link import("../meter.js").CostReport} and `sumReports`/`formatReport`
+   *  for battery-level aggregation. */
+  lastCost: CostReport | null = null;
+
   /** Memo of the consensus climb — content-keyed.  See {@link MindContext.climbMemo}. */
   climbMemo: Map<string, Map<string, AttentionRead>> | null = null;
 
@@ -326,9 +354,11 @@ export class Mind implements MindContext {
         mechanisms: userMechs,
         mechanismFactories: userFacts,
         canon: optsCanon,
+        profile: optsProfile,
         ...rest
       } = (optsOrCfg ?? {}) as MindOptions;
       this._canonOpt = optsCanon ?? null;
+      this._profile = optsProfile === true;
       this.cfg = resolveConfig(rest as Partial<MindConfig>);
       this.store = optsStore ?? new SQliteStore({
         maxGroup: this.cfg.geometry.maxGroup,
@@ -417,19 +447,48 @@ export class Mind implements MindContext {
     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. */
+  /** Open one response's transient state — the tracer, the per-response
+   *  memos, the work meter.  The ONE place this state is created, and it
+   *  serves BOTH entry points: `respond` takes fresh per-response memos,
+   *  `respondTurn` passes its conversation, whose memos persist across turns
+   *  (content-keyed, so the previous turn's results are found by this turn's
+   *  sub-span calls) and whose `resolvedSubtrees` makes foldTree O(suffix)
+   *  instead of O(context).  respondTurn used to inline its own copy of this
+   *  and of {@link endResponse}; the two drifted (a memo added to one was
+   *  silently absent from the other), so there is exactly one pair now. */
   private beginResponse(
     inspectRationale?: InspectRationale,
     canon?: Canon | null,
+    conv?: ConversationData,
   ): void {
     this.trace = inspectRationale ? new Rationale(inspectRationale) : null;
-    this.climbMemo = new Map();
-    this.recogniseMemo = new Map();
-    this.perceiveMemo = new Map();
+    this.climbMemo = conv ? conv.climbMemo : new Map();
+    this.recogniseMemo = conv ? conv.recogniseMemo : new Map();
+    this.perceiveMemo = conv ? conv.perceiveMemo : new Map();
+    this._resolvedSubtrees = conv ? conv.resolvedSubtrees : null;
     this.canon = canon ?? null;
     this.canonMemo = canon ? new Map() : null;
+    this._beginMeter();
+  }
+
+  /** Open (or leave closed) the response's work accumulator.  Separate from
+   *  {@link beginResponse} because {@link respondTurn} keeps its own
+   *  conversation-scoped lifecycle and must not create fresh per-response
+   *  memos — but it DOES meter, through this same pair. */
+  private _beginMeter(): void {
+    if (!this._profile) return;
+    this.meter = new Meter();
+    this.store.meter = this.meter;
+  }
+
+  /** Close the accumulator and publish its report.  Detaching from the store
+   *  matters: a Mind that shares a store with another Mind must not keep
+   *  charging that store's reads to a finished response. */
+  private _endMeter(queryBytes: number): void {
+    if (this.meter === null) return;
+    this.lastCost = this.meter.report(queryBytes);
+    this.store.meter = null;
+    this.meter = null;
   }
 
   /** The canonicalizer a response should carry: the Mind-level option when
@@ -441,12 +500,20 @@ export class Mind implements MindContext {
   }
 
   /** Close one response's transient state — every per-response field, incl.
-   *  the edge guide/choices `think` sets mid-flight. */
-  private endResponse(): void {
+   *  the edge guide/choices `think` sets mid-flight, and the meter's report.
+   *
+   *  A conversation's memo MAPS were mutated in place, so `data.*` still
+   *  points at them and there is nothing to save back.  Clearing the Mind's
+   *  references is what matters: a concurrently-started `respond()` swaps its
+   *  own fresh maps into these pointers, and copying back from them here
+   *  would inject a foreign response's memos into the conversation. */
+  private endResponse(queryBytes: number): void {
+    this._endMeter(queryBytes);
     this.trace = null;
     this.climbMemo = null;
     this.recogniseMemo = null;
     this.perceiveMemo = null;
+    this._resolvedSubtrees = null;
     this.canon = null;
     this.canonMemo = null;
     this._edgeGuide = null;
@@ -464,30 +531,51 @@ export class Mind implements MindContext {
   ): Promise<Response> {
     this.beginResponse(inspectRationale, canon);
     try {
-      const top = this.trace?.enter(traceLabel, [
-        rItem(queryBytes, "query"),
-      ]);
-      const thought = await think(this, queryBytes, 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, queryBytes);
-      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,
-      };
+      return await this._groundAndVoice(queryBytes, traceLabel);
     } finally {
-      this.endResponse();
+      this.endResponse(queryBytes.length);
     }
   }
 
+  /** The ONE path from query bytes to a voiced answer: ground (think), then
+   *  re-voice in the asker's words (articulate).  Both entry points run
+   *  exactly this — they differ only in the LIFECYCLE around it (fresh
+   *  per-response memos vs. a conversation's persistent ones) and in what
+   *  they do with the answer afterwards.  It must be called between
+   *  {@link beginResponse} and {@link endResponse}. */
+  private async _groundAndVoice(
+    queryBytes: Uint8Array,
+    traceLabel: string,
+  ): Promise<Response> {
+    const top = this.trace?.enter(traceLabel, [rItem(queryBytes, "query")]);
+    const meter = this.meter;
+    const thought = meter
+      ? await meter.time(
+        "think",
+        () => think(this, queryBytes, this.mechanisms),
+      )
+      : await think(this, queryBytes, 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 = meter
+      ? await meter.time(
+        "articulate",
+        () => articulate(this, thought.bytes, queryBytes),
+      )
+      : await articulate(this, thought.bytes, queryBytes);
+    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,
+    };
+  }
+
   async respond(
     input: Input,
     inspectRationale?: InspectRationale,
@@ -642,55 +730,30 @@ export class Mind implements MindContext {
 
     const turnBytes = inputBytes(this, turn);
     // Incremental perception — O(turn) instead of O(context).
-    const tree = this._growContext(data, turnBytes);
+    this._growContext(data, turnBytes);
     const newContext = data.bytes;
 
-    // Swap in the conversation's persistent state so the inference
-    // pipeline does not re-process the prefix from scratch.
-    //   perceiveMemo / recogniseMemo / climbMemo — content-keyed;
-    //     the prefix's results from the previous turn are found by
-    //     the current turn's sub-span calls.
-    //   _resolvedSubtrees — Sema-node-keyed; when the pyramid reuses
-    //     prefix subtrees (identical objects), foldTree returns their
-    //     ids immediately — O(suffix) instead of O(context).
-    this.perceiveMemo = data.perceiveMemo;
-    this.recogniseMemo = data.recogniseMemo;
-    this.climbMemo = data.climbMemo;
-    this._resolvedSubtrees = data.resolvedSubtrees;
-    this.trace = inspectRationale ? new Rationale(inspectRationale) : null;
-    // A string turn is text by nature — carry the text equivalence, same as
+    // The conversation's persistent memos and subtree cache are swapped in
+    // by beginResponse (see there) — the SAME lifecycle respond() uses, so a
+    // memo added in one place can never be missing from the other.  A string
+    // turn is text by nature and carries the text equivalence, same as
     // respond() (see _canonFor).
-    this.canon = this._canonFor(typeof turn === "string" ? textCanon : null);
-    this.canonMemo = this.canon ? new Map() : null;
+    //
+    // No recognise-memo pre-seeding here: that used to be necessary because
+    // the flat/positional fold lost visibility into an earlier turn's own
+    // structure once later bytes shifted its position (foldTree no longer
+    // visited the turn's root node).  The STABLE-PREFIX fold (see {@link
+    // ConversationData}) makes every turn's subtree independent of what
+    // follows it by construction, so recognise() finds it correctly on its
+    // own, first-touch, exactly once per turn.
+    this.beginResponse(
+      inspectRationale,
+      this._canonFor(typeof turn === "string" ? textCanon : null),
+      data,
+    );
 
     try {
-      // No recognise-memo pre-seeding here: that used to be necessary
-      // because the flat/positional fold lost visibility into an earlier
-      // turn's own structure once later bytes shifted its position
-      // (foldTree no longer visited the turn's root node).  The
-      // STABLE-PREFIX fold (see {@link ConversationData}) makes every
-      // turn's subtree independent of what follows it by construction, so
-      // recognise() finds it correctly on its own, first-touch, exactly
-      // once per turn — no workaround needed, and none pre-empting
-      // recognise()'s own memo with a partial result.
-      const top = this.trace?.enter("respondTurn", [
-        rItem(newContext, "query"),
-      ]);
-
-      const thought = await think(this, newContext, this.mechanisms);
-      if (thought === null) {
-        top?.done([], "nothing to perceive or an empty store — no answer");
-        return {
-          response: { v: null, bytes: new Uint8Array(0) },
-          state: this.conversationState(conv)!,
-        };
-      }
-
-      const voiced = await articulate(this, thought.bytes, newContext);
-      top?.done(
-        [rItem(voiced, "answer", resolveImpl(this, voiced) ?? undefined)],
-        "the answer, re-voiced in the asker's words",
-      );
+      const response = await this._groundAndVoice(newContext, "respondTurn");
 
       // The REPLY joins the accumulated context the same way a turn does
       // ({@link addTurn}): raw byte append plus a boundary offset — never a
@@ -698,33 +761,11 @@ export class Mind implements MindContext {
       // the cumulative continuous shape multi-turn training deposits, so a
       // later turn can refer to what was ANSWERED ("which of those two…"),
       // not only to what was asked.
-      if (voiced.length > 0) this.addTurn(conv, voiced);
-
-      return {
-        response: {
-          v: gistOf(this, voiced),
-          bytes: voiced,
-          provenance: thought.provenance,
-        },
-        state: this.conversationState(conv)!,
-      };
+      if (response.bytes.length > 0) this.addTurn(conv, response.bytes);
+
+      return { response, state: this.conversationState(conv)! };
     } finally {
-      // No save-back: the conversation's memo MAPS were mutated in place —
-      // `data.*` still points at them.  Re-assigning from the Mind-level
-      // pointers here was a no-op in the single-flight case and, under a
-      // concurrently-started respond() (which swaps its own fresh maps into
-      // those pointers), would inject a FOREIGN response's memos into this
-      // conversation.  Clear Mind references — non-conversation respond()
-      // calls get fresh per-response memos.
-      this.trace = null;
-      this.perceiveMemo = null;
-      this.recogniseMemo = null;
-      this.climbMemo = null;
-      this.canon = null;
-      this.canonMemo = null;
-      this._resolvedSubtrees = null;
-      this._edgeGuide = null;
-      this._edgeChoice.clear();
+      this.endResponse(newContext.length);
     }
   }
 

package/src/mind/pipeline-mechanism.ts

@@ -17,11 +17,13 @@ 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 { indexOf } from "../bytes.js";
+import { dominates } from "../geometry.js";
 import { windowIds } from "./canonical.js";
 import { read, resolve } from "./primitives.js";
-import { alignGraded, type GradedRun } from "./match.js";
+import { alignGraded, type GradedRun, skillExemplar } from "./match.js";
 import { climbAttentionAll } from "./attention.js";
-import { skillExemplar } from "./mechanisms/extraction.js";
+import { sharedReachMemo } from "./traverse.js";
 
 // ── Precomputed ──────────────────────────────────────────────────────────────
 //
@@ -94,9 +96,16 @@ export class Precomputed {
   }
 
   /** 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 = new Map<number, AncestorReach>();
+   *  ancestor reach is a pure function of the read-only store, so one memo
+   *  serves every mechanism that prices commonality — AND the consensus
+   *  climb, which is the largest consumer and used to build its own.  The
+   *  ONE definition of its lifetime lives in traverse.ts
+   *  ({@link sharedReachMemo}): response-scoped for respond(),
+   *  conversation-scoped across turns, always cold under a trace. */
+  private _reach?: Map<number, AncestorReach>;
+  get reachMemo(): Map<number, AncestorReach> {
+    return this._reach ??= sharedReachMemo(this.ctx);
+  }
 
   // ── Expensive lazy analyses ───────────────────────────────────────────
   //
@@ -105,16 +114,26 @@ export class Precomputed {
   // mechanism MUST check its cheap floor gates and the pipeline's
   // `worthRunning` predicate before first-touching one of these.
 
+  /** Charge a lazily-shared analysis to its OWN phase rather than to the
+   *  mechanism that happened to first-touch it.  Without this the profile
+   *  reads as "cast.floor costs 2 s" when what actually cost 2 s is the
+   *  consensus climb — which cast merely paid for on everyone's behalf, and
+   *  which every later consumer then got free.  Attribution must follow the
+   *  work, not the caller. */
+  private shared<T>(phase: string, fn: () => Promise<T>): Promise<T> {
+    const meter = this.ctx.meter;
+    return meter ? meter.time(phase, fn) : fn();
+  }
+
   private _attention?: Promise<AttentionRead>;
   /** 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> {
-    return this._attention ??= climbAttentionAll(
-      this.ctx,
-      this.query,
-      this.k,
+    return this._attention ??= this.shared(
+      "attention",
+      () => climbAttentionAll(this.ctx, this.query, this.k),
     );
   }
 
@@ -124,7 +143,10 @@ export class Precomputed {
    *  mechanism doing analogical transfer. */
   weave(): Promise<WeaveInfo> {
     return this._weave ??= this.attention().then((climb) =>
-      computeWeave(this.ctx, this.query, this, climb)
+      this.shared(
+        "weave",
+        async () => computeWeave(this.ctx, this.query, this, climb),
+      )
     );
   }
 
@@ -140,7 +162,10 @@ export class Precomputed {
   spanShapedOf(anchor: number): Promise<SkillInfo | null> {
     let p = this._spanShaped.get(anchor);
     if (p === undefined) {
-      p = skillExemplar(this.ctx, anchor, this.guide);
+      p = this.shared(
+        "spanShaped",
+        () => skillExemplar(this.ctx, anchor, this.guide),
+      );
       this._spanShaped.set(anchor, p);
     }
     return p;
@@ -192,6 +217,7 @@ function computeWeave(
   const rankedCapped = ranked.length > pre.k ? ranked.slice(0, pre.k) : ranked;
   const depth = new Float64Array(query.length);
   const points: WeaveInfo["points"] = [];
+  const byAnchor = new Map<number, WeaveInfo["points"][number]>();
 
   // WEAVE-SCALE anchors only: CAST transfers structure between things the
   // QUERY weaves together — query-scale structures.  A context an order of
@@ -207,6 +233,38 @@ function computeWeave(
   // uncapped weaves spent 5–8s per query recognising conversation-length
   // anchors that could never form a weave point.
   const capBytes = query.length * quantum;
+  // EXCLUSIVITY IS ARBITRATED BY THE CLIMB'S VOTE ORDER, DELIBERATELY.  A query
+  // byte can only be independent evidence for ONE point, so points are built in
+  // ranked order and each new point's runs are trimmed against every point
+  // already accepted; a point left with no run of a full quantum drops out of
+  // the weave.
+  //
+  // That reads like first-come-wins — a point that merely ranked higher taking
+  // a span from the point that actually explains it — and arbitrating by LOCAL
+  // evidence instead (ownership of each byte to the longest covering run, then
+  // the heavier weight, then rank) was implemented and MEASURED: test/29 went
+  // 9/2 to 7/4, and the new failures name the reason. CAST requires the weave
+  // to touch a COMMITTED point of attention ("2 aligned structure(s), but none
+  // is one of the climb's 1 committed root(s)"), and it was precisely the vote
+  // order that kept the committed root's own point alive in the weave. Local
+  // run length knows nothing about what the climb settled on, so it evicted the
+  // root's evidence and left CAST refusing on its own consistency check.
+  //
+  // So the vote order here is not an accident of construction — it is what
+  // holds the weave and the climb to the same conclusion. Weave-local
+  // measures decide what is FRAME inside the weave (see the frame gates in
+  // cast.ts); which structures are in the weave at all stays the climb's call.
+  //
+  // TWO PASSES.  `depth` — how much of the weave agrees on each query byte, and
+  // therefore what counts as FRAME — must be the whole weave's, not "whatever
+  // has been processed so far": read in one pass it made a candidate's own
+  // frame reading depend on its rank, and the proposed-run gate below needs the
+  // real thing.
+  const cands: Array<{
+    cand: (typeof rankedCapped)[number];
+    ctxBytes: Uint8Array;
+    raw: GradedRun[];
+  }> = [];
   for (const cand of rankedCapped) {
     const ctxBytes = read(ctx, cand.anchor, capBytes + 1);
     if (ctxBytes.length === 0 || ctxBytes.length > capBytes) continue;
@@ -215,6 +273,9 @@ function computeWeave(
     for (const r of raw) {
       for (let i = r.qs; i < r.qe; i++) depth[i] += r.weight;
     }
+    cands.push({ cand, ctxBytes, raw });
+  }
+  for (const { cand, ctxBytes, raw } of cands) {
     const free: GradedRun[] = [];
     for (const r of raw) {
       let { qs, qe, cs, weight } = r;
@@ -236,12 +297,122 @@ function computeWeave(
       }
     }
     if (free.length > 0) {
-      points.push({
+      const pt = {
         anchor: cand.anchor,
         vote: cand.vote,
         ctx: ctxBytes,
         runs: free,
-      });
+      };
+      byAnchor.set(cand.anchor, pt);
+      points.push(pt);
+    }
+  }
+
+  // A byte is FRAME when more than half the weave shares it, and a SPAN is
+  // frame when more than half its bytes are — the same two-level
+  // half-dominance reading cast.ts's own frame gate uses, over the same
+  // `depth`.  Read against the accepted POINTS (as cast.ts does), so it is
+  // only meaningful once phase 1 has run.
+  const framed = (from: number, to: number): boolean => {
+    let n = 0;
+    for (let i = from; i < to; i++) if (dominates(depth[i], points.length)) n++;
+    return dominates(n, to - from);
+  };
+  // PHASE 2 — THE CLIMB'S OWN CONCLUSION IS AN ALIGNMENT THE LITERAL MATCHER
+  // CANNOT SEE.  `alignRuns` seeds on W-grams, so two forms differing by a
+  // single byte share no run at all: on `How is ice like steel?` against a
+  // store holding `Ice is cold`, the query's `ice` and the stored `Ice` agree
+  // on only `ce ` — three bytes, never seeded — so that structure entered the
+  // weave carrying nothing but the ` is ` scaffolding every exemplar shares,
+  // lost it to the first point that claimed it, and vanished.  The climb had
+  // ALREADY identified it: its resonance elected `Ice is cold` from the query
+  // span `ce l` and `Steel is hard` from `stee`, two disjoint spans each naming
+  // its own structure, weighed through the region's contrastive margin and its
+  // IDF — gates the aligner has no equivalent of.
+  //
+  // So the climb PROPOSES the pairing (which structure, which query span) and
+  // bytes DECIDE its terms (§2.3).  Three gates, each one measured:
+  //
+  //   • it may only take query bytes NO literal run claimed.  Run inline with
+  //     phase 1 this did the opposite of "exact decides" — a higher-ranked
+  //     candidate's proposal trimmed a lower-ranked candidate's byte-for-byte
+  //     match out of existence (`he W`, proposed for `a nickname meaning the
+  //     divine one`, cut the literal `The ` out of `The Starry Night was
+  //     painted by Vincent van Gogh.` and CAST's redirection lost its
+  //     dominant — test/29 C4).  Hence a second pass, after every literal run
+  //     is placed.
+  //   • the literal agreement must DOMINATE the span.  A climb vote is not by
+  //     itself an alignment: on `The Persistence of Memory was painted by
+  //     Salvador Dali.` the climb elects `The Starry Night…` from the span
+  //     ` Dali.`, which shares barely a byte with it — the resonance was
+  //     carried by the frame those exemplars share.  Admitting it let CAST
+  //     weave points out of pure scaffolding and out-account the correct
+  //     extraction (test/00, test/24).  Where the proposal is real the
+  //     agreement is overwhelming: both C1 spans agree on three of four bytes.
+  //   • and the span must not be FRAME.  Literal dominance alone is too weak
+  //     at this scale — a 4-byte span agrees three-of-four with half the
+  //     corpus by accident (`he W` against `a nickname meaning the divine
+  //     one`).  Frame is the weave-local measure of exactly that.
+  const claimed = new Uint8Array(query.length);
+  for (const p of points) {
+    for (const r of p.runs) claimed.fill(1, r.qs, r.qe);
+  }
+  for (const { cand, ctxBytes } of cands) {
+    if (cand.end > cand.start) {
+      let qs = cand.start;
+      let qe = cand.end;
+      while (qs < qe && claimed[qs]) qs++;
+      while (qe > qs && claimed[qe - 1]) qe--;
+      let clear = true;
+      for (let i = qs; i < qe; i++) if (claimed[i]) clear = false;
+      if (clear && qe - qs >= Math.min(quantum, ctxBytes.length)) {
+        // The gate only asks whether the agreement DOMINATES the span, so
+        // search DOWNWARD from the whole span and stop at the first hit: the
+        // first length found is both the longest agreement and, by
+        // construction, already past the dominance bar.  At most O(W²) bounded
+        // substring probes — a span is one segment (≤ 2W) — where a full
+        // longest-common-substring scan would be O(|span|² · |ctx|) against a
+        // context that may be W× the query.
+        const span = query.subarray(qs, qe);
+        const bar = Math.floor(span.length / 2) + 1; // dominates(bar, length)
+        let bestLen = 0;
+        let bestCs = 0;
+        for (let len = span.length; len >= bar && bestLen === 0; len--) {
+          for (let off = 0; off + len <= span.length; off++) {
+            const at = indexOf(ctxBytes, span.subarray(off, off + len), 0);
+            if (at < 0) continue;
+            bestLen = len;
+            // Where the span's FIRST byte lands, so `cs` means the same thing
+            // it does for a literal run: the context offset the run starts at.
+            bestCs = Math.max(0, at - off);
+            break;
+          }
+        }
+        if (bestLen > 0 && !framed(qs, qe)) {
+          const run = {
+            qs,
+            qe,
+            cs: bestCs,
+            weight: bestLen / (qe - qs),
+            proposed: true,
+          };
+          claimed.fill(1, qs, qe);
+          const pt = byAnchor.get(cand.anchor);
+          if (!pt) {
+            const made = {
+              anchor: cand.anchor,
+              vote: cand.vote,
+              ctx: ctxBytes,
+              runs: [run],
+            };
+            byAnchor.set(cand.anchor, made);
+            points.push(made);
+          } else {
+            pt.runs.push(run);
+            pt.runs.sort((x, y) => x.qs - y.qs);
+          }
+        }
+      }
     }
   }
   return { points, depth };
@@ -277,6 +448,25 @@ export interface MechanismResult {
   /** Override the mechanism's default provenance for this result.
    *  When absent, the pipeline uses `mech.provenance`. */
   provenance?: string;
+
+  /** This grounding is a COMPLETE trained answer — post-grounding must not
+   *  extend it.  Declared by the mechanism about its own result, exactly like
+   *  `accounted`/`used`/`unexplained`; the decider honours the property and
+   *  never asks which mechanism set it, so the market stays uniform.
+   *
+   *  Set it only when the answer is a stored form's OWN continuation reached
+   *  through an identity claim about the query — i.e. the query IS some
+   *  trained context, so its continuation is the whole read-out and a further
+   *  multi-hop pivot would chain PAST the fact that produced the answer.
+   *  That is the same reasoning `reason`'s echo guard already applies to a
+   *  query that resolves exactly (see reasoning.ts); this carries the claim
+   *  for the mechanisms that establish the identity by another route.
+   *
+   *  Observed without it: the correct "What is the process of
+   *  photosynthesis?" grounding was pivoted forward four times, out of the
+   *  fact that answered it and into an unrelated "Hello! How can I assist you
+   *  today?" conversational turn. */
+  complete?: boolean;
 }
 
 // ── PipelineMechanism ────────────────────────────────────────────────────────