@hviana/sema 0.8.3 → 0.8.5

package/src/mind/mechanisms/alu.ts

@@ -9,7 +9,6 @@
 
 import type { Alu } from "../../alu/src/alu.js";
 import { STEP } from "../graph-search.js";
-import { unexplainedLabel } from "../rationale.js";
 import type { PipelineMechanism } from "../pipeline-mechanism.js";
 
 /** Wrap the ALU as a {@link PipelineMechanism}. */
@@ -35,7 +34,6 @@ export function aluToMechanism(alu: Alu): PipelineMechanism {
         bytes: u.bytes,
         accounted: [[u.i, u.j]],
         moves: STEP,
-        unexplained: unexplainedLabel(query, [[u.i, u.j]]),
       }));
     },
   };

package/src/mind/mechanisms/cast.ts

@@ -30,15 +30,11 @@ import {
   sharedFrameStrengthOf,
 } from "../match.js";
 import { joinWithBridge } from "../resonance.js";
-import { restatesQuery } from "../reasoning.js";
 import { CONCEPT, STEP } from "../graph-search.js";
 import { concat2, indexOf } from "../../bytes.js";
 import { consensusFloor, dominates } from "../../geometry.js";
-import {
-  decodeText,
-  unexplainedLabel,
-  unexplainedSpans,
-} from "../rationale.js";
+import { decodeText } from "../rationale.js";
+import { restates, unexplainedSpans } from "../derivation.js";
 import { rItem, rNode } from "../trace.js";
 import { dismissedKnownContent } from "../bridge.js";
 import { leafIdRun } from "../canonical.js";
@@ -92,7 +88,6 @@ export interface CastResult {
   /** A human-readable label for the query bytes this schema left
    *  unexplained — purely diagnostic, never priced (see the module's
    *  Task 2 note in pipeline.ts's Candidate interface). */
-  unexplained: string;
 }
 
 /** The seat that establishes a node's role in an analogical comparison:
@@ -129,7 +124,7 @@ export interface CastResult {
  *  describes id ("...painted by Leonardo da Vinci." contains "Leonardo da
  *  Vinci").  An incidental adjacency predecessor never does — it merely
  *  preceded id in some unrelated document without ever mentioning it.  No
- *  new tuned constant: containment is the same primitive `restatesQuery`
+ *  new tuned constant: containment is the same primitive `restates`
  *  and `dominates`-style checks already use throughout this codebase.
  *
  *  `allowForward` (default true) gates the FORWARD branch specifically —
@@ -499,7 +494,6 @@ export async function counterfactualTransfer(
       used: used ?? new Set(),
       accounted,
       moves,
-      unexplained: unexplainedLabel(query, accounted),
     });
   };
   ctx.trace?.step(
@@ -613,7 +607,7 @@ export async function counterfactualTransfer(
     const fwd = await follow(ctx, proj.anchor, qv);
     if (
       fwd !== null && indexOf(answer, fwd, 0) < 0 &&
-      !restatesQuery(query, fwd)
+      !restates(query, fwd, 0, { proper: true })
     ) {
       // THROUGH THE SHARED JOINER, not a bare concatenation.
       //
@@ -695,7 +689,7 @@ export async function counterfactualTransfer(
   // cap the test reads "none of the established continuations appears".
   const domNext = ctx.store.nextFirst(dominant.anchor, hubBound(ctx));
   const displaced = domNext
-    .every((n) => indexOf(query, read(ctx, n), 0) < 0);
+    .every((n) => !restates(query, read(ctx, n), 0));
   // The SUBSTITUTE is what redirection speaks — the answer IS `project(last)`,
   // its own fact — so the same bar applies.  The displaced structure is only
   // recognised as the slot being overridden and is never voiced, so it is
@@ -791,7 +785,7 @@ export async function counterfactualTransfer(
       queryScale(p.ctx.length) &&
       indexOf(dominant.ctx, p.ctx, 0) < 0 &&
       indexOf(p.ctx, dominant.ctx, 0) < 0 &&
-      indexOf(query, p.ctx, 0) < 0
+      !restates(query, p.ctx, 0)
     ) {
       analogs.push({ anchor: p.anchor, point: p, src: p });
     }
@@ -810,7 +804,7 @@ export async function counterfactualTransfer(
         !queryScale(nctx.length) ||
         indexOf(dominant.ctx, nctx, 0) >= 0 ||
         indexOf(nctx, dominant.ctx, 0) >= 0 ||
-        indexOf(query, nctx, 0) >= 0
+        restates(query, nctx, 0)
       ) continue;
       analogs.push({ anchor: nid, point: null, src: p });
     }
@@ -1286,13 +1280,16 @@ export async function counterfactualTransfer(
     // consulting it here is the same fallback `resolve` already makes when an
     // exact content lookup misses, and it keeps this mechanism from carrying
     // any idea of its own about what a character is.
-    const echoesQuery = (x: Uint8Array): boolean => {
-      if (restatesQuery(query, x)) return true;
-      const canon = ctx.canon;
-      if (canon === null) return false;
-      const cq = canon(query), cx = canon(x);
-      return cx.length < cq.length && indexOf(cq, cx, 0) >= 0;
-    };
+    // TWO WITNESSES, ONE LAW: the byte reading, and — when the response carries
+    // one — the same reading under the response's own equivalence.  Asked twice
+    // rather than branched on, because the equivalence is a property of the
+    // injected canonicalizer (a substring-monotone function is the usual case,
+    // not a guarantee), and the two readings are OR-ed here exactly as they were
+    // before this became one definition.
+    const echoesQuery = (x: Uint8Array): boolean =>
+      restates(query, x, 0, { proper: true }) ||
+      (ctx.canon !== null &&
+        restates(query, x, 0, { equate: ctx.canon, proper: true }));
     if (echoesQuery(b)) {
       const fwd = await follow(ctx, bestAnalog.anchor, qv);
       if (fwd !== null && fwd.length > 0 && !echoesQuery(fwd)) b = fwd;
@@ -1406,7 +1403,6 @@ export const castMechanism: PipelineMechanism = {
       accounted: c.accounted,
       moves: c.moves,
       used: c.used,
-      unexplained: c.unexplained,
     }));
   },
 };

package/src/mind/mechanisms/confluence.ts

@@ -44,7 +44,7 @@ import { read } from "../primitives.js";
 import { corpusN, reachOf } from "../traverse.js";
 import { dominates } from "../../geometry.js";
 import { STEP } from "../graph-search.js";
-import { unexplainedLabel } from "../rationale.js";
+import { insideAnsweredTurn } from "../derivation.js";
 import type { PipelineMechanism, Precomputed } from "../pipeline-mechanism.js";
 import { rItem, rNode } from "../trace.js";
 
@@ -58,9 +58,6 @@ export interface JoinResult {
   used: ReadonlySet<number>;
   accounted: Array<[number, number]>;
   moves: number;
-  /** A human-readable label for the query bytes the meet left unexplained —
-   *  purely diagnostic, never priced. */
-  unexplained: string;
 }
 
 /** The main confluence entry point.  Given a query, detect whether it weaves
@@ -98,14 +95,9 @@ export async function confluenceJoin(
   // Recognition and attention still see the full transcript; only this
   // mechanism's constraint population excludes answered spans.
   const queryWin = new Map<number, number>();
-  let answered = 0;
+  const answered = { at: 0 };
   for (const [off, id] of pre.queryWindows) {
-    while (
-      answered < ctx.answeredSpans.length &&
-      ctx.answeredSpans[answered][1] <= off
-    ) answered++;
-    const span = ctx.answeredSpans[answered];
-    if (span && span[0] <= off && off + W <= span[1]) continue;
+    if (insideAnsweredTurn(ctx.answeredSpans, answered, off, off + W)) continue;
     queryWin.set(off, id);
   }
   const queryIds = new Set(queryWin.values());
@@ -315,7 +307,6 @@ export async function confluenceJoin(
     used: new Set([met.a.anchor, met.b.anchor]),
     accounted,
     moves: 3 * STEP,
-    unexplained: unexplainedLabel(query, accounted),
   };
 }
 
@@ -344,7 +335,6 @@ export const confluenceMechanism: PipelineMechanism = {
       accounted: met.accounted,
       moves: met.moves,
       used: met.used,
-      unexplained: met.unexplained,
     }];
   },
 };

package/src/mind/mechanisms/cover.ts

@@ -16,7 +16,8 @@ import { guidedFirst, hubBound } from "../traverse.js";
 import { conceptHop } from "../match.js";
 import { bridge } from "../resonance.js";
 import { liftAnswer, liftedScaffolding, segRestatesQuery } from "../types.js";
-import { decodeText, unexplainedLabel } from "../rationale.js";
+import { decodeText } from "../rationale.js";
+import { insideAnsweredTurn, restates } from "../derivation.js";
 import { indexOf } from "../../bytes.js";
 import type { RationaleItem } from "../rationale.js";
 import { rItem, rNode, traceDerivation } from "../trace.js";
@@ -62,16 +63,13 @@ export async function resolveConnectors(
   // discarded — a semantically neutral gate (it removes work whose product
   // liftAnswer throws away), and a cumulative (multi-turn) query is exactly
   // where such already-answered continuations recur.
-  let answered = 0;
+  const answered = { at: 0 };
   const ordered = [...sites]
     .sort((a, b) => a.start - b.start)
     .filter((s) => {
-      while (
-        answered < ctx.answeredSpans.length &&
-        ctx.answeredSpans[answered][1] <= s.start
-      ) answered++;
-      const span = ctx.answeredSpans[answered];
-      if (span && span[0] <= s.start && s.end <= span[1]) return false;
+      if (insideAnsweredTurn(ctx.answeredSpans, answered, s.start, s.end)) {
+        return false;
+      }
       if (query === undefined || ctx.answeredSpans.length === 0) return true;
       const continuations = ctx.store.nextFirst(s.payload, hubBound(ctx));
       return !continuations.some((answer) => {
@@ -93,7 +91,11 @@ export async function resolveConnectors(
         // 3 bytes this reads 4 bytes per candidate instead of the ~231 it
         // averaged before.
         const bytes = read(ctx, answer, query.length + 1);
-        return bytes.length <= query.length && indexOf(query, bytes, 0) >= 0;
+        // THE CONTENT READING of the same exclusion: the site's own
+        // continuation already occurs in the query, so voicing it back adds
+        // nothing.  It is the restatement law with no `proper` flag — the
+        // containment reading that also admits the whole query.
+        return restates(query, bytes, 0);
       });
     });
   const bridgePair = async (l: number, r: number) => {
@@ -210,18 +212,11 @@ export const coverMechanism: PipelineMechanism = {
       )
       : await resolveConnectors(ctx, sites, query);
     let splits = rec.splits;
-    let starts = rec.starts;
     if (computed.length > 0) {
       splits = new Set(rec.splits);
-      starts = new Set(rec.starts);
       for (const u of computed) {
         splits.add(u.i);
         splits.add(u.j);
-        // A computation's own boundaries carry the same fold-level evidence
-        // a chunk boundary does — "computation always wins" (see the header
-        // comment) extends to being trusted ground for cross-leaf recovery.
-        starts.add(u.i);
-        starts.add(u.j);
       }
     }
     const concepts = ctx.meter
@@ -262,7 +257,6 @@ export const coverMechanism: PipelineMechanism = {
       concepts,
       rec.leaves,
       splits,
-      starts,
       undefined,
       connectors,
       computedResults,
@@ -330,9 +324,12 @@ export const coverMechanism: PipelineMechanism = {
     return [{
       bytes: composed,
       accounted,
-      moves: 0,
-      weight: solved!.cost, // A*LD derivation's g-value IS the weight
-      unexplained: unexplainedLabel(query, accounted),
+      // The derivation's DISCRETE work.  The bytes the chart could not
+      // recognise are NOT priced here: they are exactly the spans `accounted`
+      // leaves uncovered, and the pipeline's one formula charges them at PASS —
+      // the same formula that prices every other mechanism's candidate.  No
+      // mechanism spells a cost of its own.
+      moves: solved!.moves,
       // How much of the composed answer is the asker's own unexplained words
       // (the spans the liftAnswer trace above labels "scaffolding").  Cover is
       // the mechanism that can carry them, because a PASS span still lands in

package/src/mind/mechanisms/extraction.ts

@@ -11,7 +11,7 @@ import type { MindContext } from "../types.js";
 import { read } from "../primitives.js";
 import { follow, isSpanShaped, locate, skillExemplar } from "../match.js";
 import { concatBytes, indexOf } from "../../bytes.js";
-import { decodeText, unexplainedLabel } from "../rationale.js";
+import { decodeText } from "../rationale.js";
 import type {
   PipelineMechanism,
   Precomputed,
@@ -46,7 +46,6 @@ export async function extractBySkill(
   {
     bytes: Uint8Array;
     accounted: Array<[number, number]>;
-    unexplained: string;
   } | null
 > {
   const t = ctx.trace?.enter("extractBySkill", [
@@ -102,6 +101,12 @@ export async function extractBySkill(
   const searched = ranked.slice(0, pre.k);
   let shapeMisses = 0;
   let subQuantum = 0;
+  // A SECOND refusal counter, because the note below used to call an UNANCHORED
+  // read "sub-quantum" — which is false, and it is the kind of instrumentation
+  // defect AGENTS §6 says to close where it lives: a reader could not tell from
+  // the trace which of the two gates refused.  Neither counter reaches a
+  // decision (meter.ts contract 1); they exist so the refusal is legible.
+  let unanchored = 0;
   for (const cand of searched) {
     const exemplar = await pre.spanShapedOf(cand.anchor);
     if (!exemplar) {
@@ -137,22 +142,23 @@ export async function extractBySkill(
     // Here the field is this mechanism's own output and carries its documented
     // meaning, so the test is sound exactly where the convention does not reach.
     if (built.accounted.length === 0) {
-      subQuantum++;
+      unanchored++;
       continue;
     }
-    if (shapeMisses > 0 || subQuantum > 0) {
+    if (shapeMisses > 0 || subQuantum > 0 || unanchored > 0) {
       ctx.trace?.step(
         "trySkillAnchors",
         [
           rItem(
             query.subarray(0, 0),
-            `skipped ${shapeMisses + subQuantum}`,
+            `skipped ${shapeMisses + subQuantum + unanchored}`,
           ),
           rNode(ctx, cand.anchor, "chosen"),
         ],
         [],
-        `skipped ${shapeMisses} non-exemplar and ${subQuantum} sub-quantum ` +
-          `anchor(s) before one yielded a usable extraction`,
+        `skipped ${shapeMisses} non-exemplar, ${subQuantum} sub-quantum and ` +
+          `${unanchored} unanchored anchor(s) before one yielded a usable ` +
+          `extraction`,
       );
     }
     t?.done(
@@ -170,7 +176,6 @@ export async function extractBySkill(
     return {
       bytes: built.bytes,
       accounted: built.accounted,
-      unexplained: unexplainedLabel(query, built.accounted),
     };
   }
   if (shapeMisses === searched.length) {
@@ -403,7 +408,6 @@ export const extractionMechanism: PipelineMechanism = {
       bytes: ex.bytes,
       accounted: ex.accounted,
       moves: CONCEPT + STEP * ex.accounted.length,
-      unexplained: ex.unexplained,
     }];
   },
 };

package/src/mind/mechanisms/prefix-completion.ts

@@ -300,7 +300,6 @@ export const prefixMechanism: PipelineMechanism = {
       // IDENTITY bridge takes.
       accounted: [[0, query.length]],
       moves: STEP,
-      unexplained: "",
       // NOT complete: the query is a proper PREFIX, so the form may carry more
       // past the remainder this voiced.
     }];

package/src/mind/mechanisms/recall.ts

@@ -24,7 +24,7 @@ import {
   voicesDisplacedFiller,
 } from "../match.js";
 import { CONCEPT, STEP } from "../graph-search.js";
-import { unexplainedLabel } from "../rationale.js";
+import { restates as lawRestates } from "../derivation.js";
 import type { PipelineMechanism, Precomputed } from "../pipeline-mechanism.js";
 import { rItem, rNode } from "../trace.js";
 import { substitutionBridge } from "../bridge.js";
@@ -35,7 +35,6 @@ export interface RecallResult {
   echoed: boolean;
   accounted: Array<[number, number]>;
   moves: number;
-  unexplained: string;
   /** See {@link import("../pipeline-mechanism.js").MechanismResult.complete}
    *  — set by the IDENTITY-bridge tier alone. */
   complete?: boolean;
@@ -71,7 +70,6 @@ export async function recallByResonance(
       echoed,
       accounted,
       moves,
-      unexplained: unexplainedLabel(query, accounted),
       ...(complete ? { complete } : {}),
     };
   };
@@ -156,7 +154,7 @@ export async function recallByResonance(
       // conversation reads as if it were the next thing to say.
       if (
         g !== null && g.length > 0 &&
-        !(g.length < query.length && indexOf(query, g, 0) >= 0)
+        !lawRestates(query, g, 0, { proper: true })
       ) {
         return ground(
           g,
@@ -196,10 +194,11 @@ export async function recallByResonance(
   // same principle that keeps cast from voicing stored questions), and
   // projecting them forward is reverse recall's containment failure in the
   // other direction — "whatever followed these bytes in some document".
-  const qKey = ctx.canon ? ctx.canon(query) : query;
+  // THE EQUALITY READING of the restatement law: this tier rejects an answer
+  // that IS the question (an echo), and a proper fragment is handled by the
+  // tier's own subspan tests further down — so the law is asked with `whole`.
   const restates = (b: Uint8Array): boolean =>
-    bytesEqual(b, query) ||
-    (ctx.canon !== null && bytesEqual(ctx.canon(b), qKey));
+    lawRestates(query, b, 0, { equate: ctx.canon, whole: true });
   const idBar = identityBar(ctx.store.D, ctx.space.maxGroup, query.length);
   if (top.score >= idBar) {
     for (const h of whole) {
@@ -408,7 +407,7 @@ export async function recallByResonance(
       // — never an answer (the same principle as `restates` above, extended
       // to fragments).  Genuine anchor groundings — longer than the query,
       // or disjoint from it — pass untouched.
-      else if (g && !(g.length < query.length && indexOf(query, g, 0) >= 0)) {
+      else if (g && !lawRestates(query, g, 0, { proper: true })) {
         return ground(
           g,
           "scaffolding-dominated query — ground the consensus-climb anchor",
@@ -627,7 +626,6 @@ export const recallMechanism: PipelineMechanism = {
       bytes: r.bytes,
       accounted: r.accounted,
       moves: r.moves,
-      unexplained: r.unexplained,
       provenance: r.echoed ? "recall-echo" : "recall",
       used: new Set<number>(),
       ...(r.complete ? { complete: true } : {}),

package/src/mind/mechanisms/reference.ts

@@ -39,7 +39,7 @@ import type { FrameInstance } from "../match.js";
 import { carriesFillers, distinct, follow, substituteAll } from "../match.js";
 import { dominates } from "../../geometry.js";
 import { bytesEqual, indexOf } from "../../bytes.js";
-import { unexplainedLabel } from "../rationale.js";
+import { restates } from "../derivation.js";
 import { STEP } from "../graph-search.js";
 import type {
   MechanismResult,
@@ -231,7 +231,7 @@ export async function bindReference(
   if (bytes.length === 0) return fail("the binding produced nothing");
   // Answering with the question is not answering — the same restated-fragment
   // guard every recall tier applies.
-  if (bytes.length < query.length && indexOf(query, bytes, 0) >= 0) {
+  if (restates(query, bytes, 0, { proper: true })) {
     return fail("the binding restates part of the question");
   }
   const carried = !bytesEqual(bytes, first);
@@ -278,7 +278,6 @@ export async function bindReference(
     // binding claims strictly more than a one-slot binding, so where both are
     // licensed the smaller claim wins.
     moves: STEP * slots.length + STEP,
-    unexplained: unexplainedLabel(query, accounted),
     // NOT scaffolding.  That field counts answer bytes carried through BECAUSE
     // NOTHING EXPLAINED THEM; a referent is carried because the frame's slot
     // explains it, and it is accounted above.  Reporting it would make every

package/src/mind/pipeline-mechanism.ts

@@ -677,15 +677,12 @@ export interface MechanismResult {
   moves: number;
   /** WHAT THIS ANSWER SPEAKS FOR — the anchors it voices, and therefore the
    *  content the reasoner must not pivot back through.  Declared by the
-   *  mechanism about its OWN result, exactly like `accounted`/`unexplained`/
+   *  mechanism about its OWN result, exactly like `accounted`/`used`/
    *  `complete`: post-grounding honours the property and NEVER ASKS WHICH
    *  MECHANISM SET IT, so the market stays uniform.  An EMPTY set is a real
    *  declaration — "this answer voices nothing" (recall) — and withholds
    *  nothing; omit the field and the pipeline re-recognises the answer. */
   used?: ReadonlySet<number>;
-  unexplained: string;
-  /** Explicit weight override.  When absent, weight = moves + PASS·unaccounted. */
-  weight?: number;
   /** Bytes of `bytes` that came from spans nothing recognised — the asker's
    *  own words carried through verbatim rather than derived (see
    *  {@link liftedScaffolding}).  Reported, not priced: the ladder prices what