@hviana/sema 0.8.0 → 0.8.1

package/src/mind/mechanisms/reference.ts

@@ -2,8 +2,8 @@
 // bytes (Grounding IV).
 //
 // This file is a CONFIGURATION of the shared frame reading in match.ts, not a
-// pipeline of its own.  The three parts it configures live where §2.5 puts
-// them and are reachable by any mechanism:
+// pipeline of its own. The three parts it configures live where
+// match-project.md puts them and are reachable by any mechanism:
 //
 //   matcher     Precomputed.frames() — the frame INVENTORY: which ranked
 //               candidates read as instances of the query's own frame, and
@@ -29,10 +29,10 @@
 // candidate's continuation UNSUBSTITUTED, so admitting a slot-gap there would
 // voice the corpus's filler for the asker's referent — the misreference
 // measured live on the trained store ("How do you say 'flurbish' in French?"
-// answered "the way to say hello is \"Bonjour\"").  Nor is CAST rewired: its
+// answered "the way to say hello is \"Bonjour\""). Nor is CAST rewired: its
 // frame gate is WEAVE-local while a slot is COHORT-local, and substituting one
-// population for the other is the error §2.7 names.  The notion is made
-// AVAILABLE, never imposed.
+// population for the other is the error commonality.md names. The notion is
+// made AVAILABLE, never imposed.
 
 import type { MindContext } from "../types.js";
 import type { FrameInstance } from "../match.js";
@@ -52,16 +52,16 @@ import { rItem, rNode, traceFail } from "../trace.js";
  *  agrees with nothing, so no carriage is attested — the same "two or no
  *  constituent" reading frame-filler's contentRuns applies.
  *
- *  THIS IS ALSO THE MECHANISM'S REACH.  Evidence comes from the shared top-k
- *  resonance, so a frame the corpus instantiates only ONCE within k is not
- *  reachable here.  Measured on the trained store: `How do you say 'flurbish'
- *  in French?` finds one instance of its frame in the top 24 — the rest are
- *  `How do you make …`, a different frame — so this abstains and recall's
- *  scaffolding-dominated tier answers with the CORPUS's filler.  That
- *  misreference is recall's, and widening the supply is not the fix: the
- *  exhaustive √N list recall's refusal path builds costs hundreds of
- *  milliseconds and this runs before it.  Abstaining on thin evidence is the
- *  honest reading (§2.13). */
+ *  THIS IS ALSO THE MECHANISM'S REACH. Evidence comes from the shared top-k
+ * resonance, so a frame the corpus instantiates only ONCE within k is not
+ * reachable here. Measured on the trained store: `How do you say 'flurbish' in
+ * French?` finds one instance of its frame in the top 24 — the rest are `How do
+ * you make …`, a different frame — so this abstains and recall's
+ * scaffolding-dominated tier answers with the CORPUS's filler. That
+ * misreference is recall's, and widening the supply is not the fix: the
+ * exhaustive √N list recall's refusal path builds costs hundreds of
+ * milliseconds and this runs before it. Abstaining on thin evidence is the
+ * honest reading (INVARIANTS.md). */
 const MIN_INSTANCES = 2;
 
 /** THE VOICING GATES — this mechanism's own reading of a pairing, applied here
@@ -135,7 +135,7 @@ function electFrame(
   let best: FrameInstance[] = [];
   for (const group of bySignature.values()) {
     // Ties keep the FIRST group in insertion order, which is resonance rank —
-    // corpus-determined, like every other tie-break here (§2.1).
+    // corpus-determined, like every other tie-break here (determinism.md).
     if (group.length > best.length) best = group;
   }
   return best;

package/src/mind/mind.ts

@@ -211,13 +211,12 @@ export interface MindOptions {
     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. */
+   *  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 attaching a RATIONALE does: a traced response
+   * bypasses the ctx memos (memoization.md), 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

package/src/mind/pipeline-mechanism.ts

@@ -5,7 +5,7 @@
 // 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):
+// The four constraints of the free-will architecture (mechanism-market.md):
 //   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.
@@ -148,17 +148,17 @@ export class Precomputed {
     );
   }
 
-  // REMOVED — the WIDE exhaustive-√N resonance list (`wideResonance`).  It ran
+  // REMOVED — the WIDE exhaustive-√N resonance list (`wideResonance`). It ran
   // `resonate(guide, √N, exhaustive=true)` whenever the top hit cleared
-  // conceptThreshold, so consumers could look "past the top-k".  Every consumer
+  // conceptThreshold, so consumers could look "past the top-k". Every consumer
   // only ever needed ≤ 2·recallQueryK proposals (the substitution bridge's own
   // candidate cap) or a content-addressed answer (prefix completion's
-  // formsOpenedBy), and every proposal is byte-verified downstream (§2.3), so
-  // the exhaustive scan bought recall at O(index) cost for an O(k) need —
-  // measured: 244K annVectorReads per refusing query, ~1.5 s, every answer
-  // byte-identical to a top-k read.  The two consumers now read `resonance()`
-  // (the one top-k read) and the write side's window index respectively — see
-  // recall.ts and prefix-completion.ts.
+  // formsOpenedBy), and every proposal is byte-verified downstream
+  // (exact-vs-approximate.md), so the exhaustive scan bought recall at O(index)
+  // cost for an O(k) need — measured: 244K annVectorReads per refusing query,
+  // ~1.5 s, every answer byte-identical to a top-k read. The two consumers now
+  // read `resonance()` (the one top-k read) and the write side's window index
+  // respectively — see recall.ts and prefix-completion.ts.
 
   private _frames?: Promise<ReadonlyArray<FrameInstance>>;
   /** THE FRAME INVENTORY — every ranked candidate that reads as an instance of
@@ -166,14 +166,16 @@ export class Precomputed {
    *  ({@link FrameInstance}).  The one place the engine represents "a position
    *  whose occupant comes from the context rather than the corpus".
    *
-   *  AN INVENTORY, NOT AN ELECTION.  It reports every pairing and elects no
-   *  frame, deliberately: a slot is a property of a PAIRING, not of the query,
-   *  and different candidates put slots in different places.  Committing to one
-   *  reading here would push whichever consumer asked first onto everyone else
-   *  — the market's decoupling (§2.6) broken from inside the shared container,
-   *  and the population error §2.7 names.  Each consumer groups and commits
-   *  for its own question; reference elects the modal slot signature, and a
-   *  consumer wanting a different reading is not fighting this one.
+   * AN INVENTORY, NOT AN ELECTION. It reports every pairing and elects no
+   * frame,
+   * deliberately: a slot is a property of a PAIRING, not of the query, and
+   * different candidates put slots in different places. Committing to one
+   * reading here would push whichever consumer asked first onto everyone else —
+   * the market's decoupling (mechanism-market.md) broken from inside the shared
+   * container, and the population error commonality.md names. Each consumer
+   * groups and commits for its own question; reference elects the modal slot
+   * signature, and a consumer wanting a different reading is not fighting this
+   * one.
    *
    *  NO LICENCE EITHER.  Knowing a span is variable is safe for every consumer
    *  — it can only improve an alignment.  Knowing one may be VOICED through is
@@ -189,9 +191,10 @@ export class Precomputed {
       const capBytes = this.query.length * W;
       const out: FrameInstance[] = [];
       for (const h of await this.resonance()) {
-        // REJECT BY LENGTH BEFORE RECONSTRUCTING (§2.8): `contentLen` is an
-        // indexed read, `bytesPrefix` rebuilds a subtree.  ONLY the phrase-scale
-        // cap is applied — it is a bounded-read discipline, not a judgement.
+        // REJECT BY LENGTH BEFORE RECONSTRUCTING (bounded-reads.md):
+        // `contentLen` is an indexed read, `bytesPrefix` rebuilds a subtree.
+        // ONLY the phrase-scale cap is applied — it is a bounded-read
+        // discipline, not a judgement.
         //
         // A LOWER bound was here too (`dominates(len, query.length)`, on the
         // reasoning that a candidate shorter than half the query cannot supply
@@ -519,7 +522,8 @@ function computeWeave(
   // 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:
+  // bytes DECIDE its terms (exact-vs-approximate.md). 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

package/src/mind/pipeline.ts

@@ -130,15 +130,15 @@ export interface NarrowDecisionData {
 }
 
 /** Structured payload of the "regimePrediction" rationale step — the R8
- *  observation exposed as data.  After the first mechanism (cover, which §2.6
- *  runs first) grounds or abstains, the market's whole outcome is already
- *  determined by the one cost ladder: the consensus climb runs exactly when
- *  `worthRunning(2 * STEP)` is true — CAST (floor 2·STEP) is the cheapest
- *  mechanism that first-touches it, and confluence (3·STEP) / extraction
- *  (CONCEPT+STEP) are only reached after CAST is.  An incumbent at or below
- *  that floor prunes CAST and, with it, the climb (retrieval); anything above
- *  — or no incumbent — runs the full market and the climb (composition).
- *  Purely observational; never read by inference. */
+ *  observation exposed as data. After the first mechanism (cover, which
+ * mechanism-market.md runs first) grounds or abstains, the market's whole
+ * outcome is already determined by the one cost ladder: the consensus climb
+ * runs exactly when `worthRunning(2 * STEP)` is true — CAST (floor 2·STEP) is
+ * the cheapest mechanism that first-touches it, and confluence (3·STEP) /
+ * extraction (CONCEPT+STEP) are only reached after CAST is. An incumbent at or
+ * below that floor prunes CAST and, with it, the climb (retrieval); anything
+ * above — or no incumbent — runs the full market and the climb (composition).
+ * Purely observational; never read by inference. */
 export interface RegimePredictionData {
   version: 1;
   /** retrieval | composition — the two regimes R1 measured as a ~100× cost
@@ -187,13 +187,13 @@ export async function think(
   // ── Pre-computation ──────────────────────────────────────────────────
   const mechanisms = mechs ?? defaultMechanisms;
   const meter = ctx.meter;
-  // recognition is a shared analysis (§2.14 contract 5): it does the query's
+  // recognition is a shared analysis (meter.md contract 5): it does the query's
   // own store work (perceive → foldTree → resolve), which used to land in
   // `think` and in nothing narrower — the meter's one accounting surface must
   // charge it to itself, exactly as attention/weave/resonance are charged.
-  // SYNCHRONOUS phase: recognition is on the sync side of §2.10's seam, so it
-  // is timed with `timeSync` — wrapping it in a promise would make a profiled
-  // response await where an unprofiled one does not.
+  // SYNCHRONOUS phase: recognition is on the sync side of meter.md's seam, so
+  // it is timed with `timeSync` — wrapping it in a promise would make a
+  // profiled response await where an unprofiled one does not.
   const rec = meter
     ? meter.timeSync("recognise", () => recognise(ctx, query))
     : recognise(ctx, query);
@@ -225,15 +225,15 @@ export async function think(
     }
   }
 
-  // Phase 2: the shared pre-computation container.  Eager fields only
-  // (recognition, computed spans, guide) — every expensive analysis
-  // (consensus climb, weave, span-shape classification) is a lazily-cached
-  // method on Precomputed, first-touched by whichever mechanism's floor
-  // survives its cheap gates and the worthRunning check.  A query no
-  // mechanism climbs for (e.g. one an extension decided) never climbs.
-  // NOT phased: the constructor itself is trivial (it only derives `k`), so a
-  // phase here would add a zero-work entry to every profiled report — the meter
-  // attributes WORK (§2.14); the trace already represents structure.
+  // Phase 2: the shared pre-computation container. Eager fields only
+  // (recognition, computed spans, guide) — every expensive analysis (consensus
+  // climb, weave, span-shape classification) is a lazily-cached method on
+  // Precomputed, first-touched by whichever mechanism's floor survives its
+  // cheap gates and the worthRunning check. A query no mechanism climbs for
+  // (e.g. one an extension decided) never climbs. NOT phased: the constructor
+  // itself is trivial (it only derives `k`), so a phase here would add a
+  // zero-work entry to every profiled report — the meter attributes WORK
+  // (meter.md); the trace already represents structure.
   const pre = new Precomputed(ctx, query, rec, computed, ctx._edgeGuide);
 
   // ── Grounding: ONE lightest-derivation choice among the mechanisms ────
@@ -298,16 +298,17 @@ export async function think(
   const worthRunning = (floor: number) =>
     best === null || grade(floor) < grade(best.weight);
 
-  // REGIME PREDICTION (R8) — observational only.  Once the FIRST mechanism has
-  // had its turn (cover, which §2.6 places first and floors at 0), the market's
-  // outcome is already determined by the one cost ladder: the consensus climb
-  // runs exactly when `worthRunning(2 * STEP)` is true — CAST (floor 2·STEP) is
-  // the cheapest mechanism that first-touches it, so an incumbent at or below
-  // grade 2 prunes CAST and, with it, confluence (3·STEP) and extraction
-  // (CONCEPT+STEP) (retrieval); anything above — or no incumbent — runs the
-  // full market and the climb (composition).  The predicate is `worthRunning`,
-  // the same function the loop itself uses — nothing is computed here that the
-  // engine had not already computed, and nothing is read back by inference.
+  // REGIME PREDICTION (R8) — observational only. Once the FIRST mechanism has
+  // had its turn (cover, which mechanism-market.md places first and floors at
+  // 0), the market's outcome is already determined by the one cost ladder: the
+  // consensus climb runs exactly when `worthRunning(2 * STEP)` is true — CAST
+  // (floor 2·STEP) is the cheapest mechanism that first-touches it, so an
+  // incumbent at or below grade 2 prunes CAST and, with it, confluence (3·STEP)
+  // and extraction (CONCEPT+STEP) (retrieval); anything above — or no incumbent
+  // — runs the full market and the climb (composition). The predicate is
+  // `worthRunning`, the same function the loop itself uses — nothing is
+  // computed here that the engine had not already computed, and nothing is read
+  // back by inference.
   //
   // EMITTED BEFORE THE SECOND MECHANISM'S FLOOR, never after some mechanism's
   // run: a "prediction" published after the fact could assert "the climb will

package/src/mind/primitives.ts

@@ -59,11 +59,11 @@ export function perceiveKey(
 /** Perceive input into a content-defined tree (the river fold).
  *  Deterministic — identical bytes always produce an identical tree.
  *
- *  `boundaries` is an optional sorted list of proper byte offsets where the
- *  fold must split so that each prefix segment folds identically to how it
- *  folded when it was learned (§10.3 stable-prefix contract).  Only the
- *  CALLER — who assembled the multi-turn context — knows where those
- *  boundaries are; the geometry never guesses them from the bytes. */
+ * `boundaries` is an optional sorted list of proper byte offsets where the fold
+ * must split so that each prefix segment folds identically to how it folded
+ * when it was learned (fold-contract.md stable-prefix contract). Only the
+ * CALLER — who assembled the multi-turn context — knows where those boundaries
+ * are; the geometry never guesses them from the bytes. */
 export function perceive(
   ctx: MindContext,
   input: Input,

package/src/mind/recognition.ts

@@ -34,19 +34,20 @@ import type { Leaf, Site } from "./graph-search.js";
  *
  *  Both O(n · maxGroup) bounded O(1) probes — never a scan of the corpus.
  *
- *  ONE READING PER BYTE STREAM, deliberately: there is no "cheap mode" that
- *  skips the edge-trim fallbacks.  A `trimmed` variant was tried and REFUTED
- *  twice over.  Its premise — "the trims only recover misaligned FRAGMENTS, so
- *  a consumer whose gate rejects fragments loses nothing" — is false: the
- *  left/right trim loops below exist precisely to find WHOLE trained forms
- *  embedded at an offset the query's own fold did not cut, and such a form has
- *  no structural parents or containers, so it passes the pivot's fragment gate
- *  and is exactly the candidate a multi-hop chain steps through.  Skipping them
- *  narrows the pivot's evidence silently.  And a per-caller variant has to key
- *  the memo by the variant, which breaks the "computed at most once" property
- *  (§2.11): the pipeline recognises a grounded answer untrimmed for
- *  `preConsumed`, and the pivot then recognises the same bytes again — the
- *  saving inverts into a doubling on the path it was measured for. */
+ * ONE READING PER BYTE STREAM, deliberately: there is no "cheap mode" that
+ * skips
+ * the edge-trim fallbacks. A `trimmed` variant was tried and REFUTED twice
+ * over. Its premise — "the trims only recover misaligned FRAGMENTS, so a
+ * consumer whose gate rejects fragments loses nothing" — is false: the
+ * left/right trim loops below exist precisely to find WHOLE trained forms
+ * embedded at an offset the query's own fold did not cut, and such a form has
+ * no structural parents or containers, so it passes the pivot's fragment gate
+ * and is exactly the candidate a multi-hop chain steps through. Skipping them
+ * narrows the pivot's evidence silently. And a per-caller variant has to key
+ * the memo by the variant, which breaks the "computed at most once" property
+ * (memoization.md): the pipeline recognises a grounded answer untrimmed for
+ * `preConsumed`, and the pivot then recognises the same bytes again — the
+ * saving inverts into a doubling on the path it was measured for. */
 export function recognise(
   ctx: MindContext,
   bytes: Uint8Array,
@@ -180,16 +181,15 @@ function recogniseImpl(ctx: MindContext, bytes: Uint8Array): Recognition {
     // and read the answer from `starts`, which is exactly {0, W, 2W, …}
     // because riverFold groups fixed-arity — arithmetic, not evidence.
     //
-    // Measured on the 17.9M-node store, over the sites of 7 probes (1 good,
-    // 11 junk by hand-labelling, corrected for whole-query forms):
-    //     len >= W        rejects "hi"(2) "of"(2) "is"(2) "di"(2) "the"(3),
-    //                     admits  "Eiffel Tower"(12) and both whole-query forms
-    //     len >= W-1      admits "the" — W-1 is the write side's straddle
-    //                     neighbour for RETRIEVAL, never a claim about units
-    //     §2.7 saturation admits 11/11 junk: edgeAncestors on a site node
-    //                     reaches 1..48 contexts, so dominates(ctx, N) needs
-    //                     ctx > 162805 and never fires; every site reads DISC
-    //     rarity          does not separate: "hi" has 1 container, "the" 572
+    // Measured on the 17.9M-node store, over the sites of 7 probes (1 good, 11
+    // junk by hand-labelling, corrected for whole-query forms): len >= W
+    // rejects "hi"(2) "of"(2) "is"(2) "di"(2) "the"(3), admits "Eiffel
+    // Tower"(12) and both whole-query forms len >= W-1 admits "the" — W-1 is
+    // the write side's straddle neighbour for RETRIEVAL, never a claim about
+    // units commonality.md saturation admits 11/11 junk: edgeAncestors on a
+    // site node reaches 1..48 contexts, so dominates(ctx, N) needs ctx > 162805
+    // and never fires; every site reads DISC rarity does not separate: "hi" has
+    // 1 container, "the" 572
     //
     // A span covering the WHOLE query is exempt: then it is not a fragment of
     // something longer, it is the question ("hi" asked on its own).

package/src/mind/resonance.ts

@@ -380,15 +380,15 @@ export async function pivotInto(
   // Byte containment, longest wins — the answer literally contains the
   // pivot's bytes, and the biggest well-evidenced span is the real pivot.
   //
-  // REAL SATURATION, not a hard cap: the score IS the candidate's byte
-  // length, so the scan is DECIDED the moment the first candidate that passes
-  // every filter is found in DESCENDING length order — a shorter candidate can
-  // never outscore it.  `contentLen` (the prefix-capped length read, §2.8) is
-  // the cheap ordering key, and the first-inserted tie-break is made explicit
-  // (`a.index - b.index`) so equal lengths keep `scored`'s insertion order —
-  // exactly the tie argmaxBy(strict) used to keep.  The bytes of at most ONE
-  // winning candidate are read; every shorter candidate the probes proposed is
-  // skipped without reconstruction, where the old argmax read them all.
+  // REAL SATURATION, not a hard cap: the score IS the candidate's byte length,
+  // so the scan is DECIDED the moment the first candidate that passes every
+  // filter is found in DESCENDING length order — a shorter candidate can never
+  // outscore it. `contentLen` (the prefix-capped length read, bounded-reads.md)
+  // is the cheap ordering key, and the first-inserted tie-break is made
+  // explicit (`a.index - b.index`) so equal lengths keep `scored`'s insertion
+  // order — exactly the tie argmaxBy(strict) used to keep. The bytes of at most
+  // ONE winning candidate are read; every shorter candidate the probes proposed
+  // is skipped without reconstruction, where the old argmax read them all.
   const ranked = [...scored.keys()]
     .map((id, index) => ({
       id,
@@ -399,11 +399,11 @@ export async function pivotInto(
   let pivotId: number | null = null;
   for (const c of ranked) {
     const id = c.id;
-    // A ZERO-LENGTH candidate is not a pivot.  `argmaxBy(…, 0, strict)` used to
+    // A ZERO-LENGTH candidate is not a pivot. `argmaxBy(…, 0, strict)` used to
     // carry this floor in its threshold argument, and dropping it here would
     // admit an empty node: `indexOf(answer, <empty>)` returns 0, so every
-    // filter below passes and the chain would hop through nothing (§2.13 —
-    // empty bytes are truthy).
+    // filter below passes and the chain would hop through nothing
+    // (INVARIANTS.md — empty bytes are truthy).
     if (c.len === 0) continue;
     // A PIVOT MUST BE A THING THE CORPUS DEPOSITED, NOT A PIECE OF ONE.
     // "Longest wins" ranks candidates but never asks whether the winner is
@@ -439,15 +439,15 @@ export async function pivotInto(
     // a span that was never a fact on its own is not one to step through.
     // No constant enters — it is a structural predicate, not a threshold.
     if (ctx.store.hasParents(id) || ctx.store.hasContainers(id)) continue;
-    // A candidate whose bytes are LONGER than the answer cannot be a
-    // substring of it — `indexOf` would return −1 regardless.  Prune by
-    // length BEFORE reconstructing the bytes: `read` is an UNCAPPED read
-    // (AGENTS §2.8), and a resonated context far longer than the answer is
-    // exactly the candidate that makes it cost a whole deposit's worth of
-    // reconstruction for a containment test that must fail.  `contentLen`
-    // with the `answer.length + 1` cap is the prefix-capped length read the
-    // same contract prescribes; the prune is byte-identical to the old
-    // `indexOf` miss (it returns −1 for a needle longer than the haystack).
+    // A candidate whose bytes are LONGER than the answer cannot be a substring
+    // of it — `indexOf` would return −1 regardless. Prune by length BEFORE
+    // reconstructing the bytes: `read` is an UNCAPPED read (bounded-reads.md),
+    // and a resonated context far longer than the answer is exactly the
+    // candidate that makes it cost a whole deposit's worth of reconstruction
+    // for a containment test that must fail. `contentLen` with the
+    // `answer.length + 1` cap is the prefix-capped length read the same
+    // contract prescribes; the prune is byte-identical to the old `indexOf`
+    // miss (it returns −1 for a needle longer than the haystack).
     if (c.len > answer.length) continue;
     const bytes = read(ctx, id);
     if (indexOf(answer, bytes, 0) < 0) continue;