@hviana/sema 0.5.7 → 0.5.9

package/dist/src/mind/reasoning.js

@@ -39,7 +39,6 @@ export async function reason(ctx, query, answer, preConsumed, pre, voiced = [])
     const qId = pre.queryResolved;
     if (qId !== null && ctx.store.prevCount(qId) > 0)
         return answer;
-    const consumed = new Set();
     // Consume a node and its neighbours for pivot-cycle prevention — CAPPED at
     // the hub bound, via the store's LIMITed edge reads: a common continuation's
     // reverse fan-in (and a hub context's forward fan-out) is corpus-sized, and
@@ -48,11 +47,64 @@ export async function reason(ctx, query, answer, preConsumed, pre, voiced = [])
     // read order); a pivot suppressed only by a beyond-cap neighbour may now
     // fire — the same visibility trade chooseNext documents.
     const bound = hubBound(ctx);
-    const consumeNode = (id) => {
+    // ANSWERED DIRECTLY — the echo guard's other half, and the same principle:
+    // the QUERY's own position in the graph, not the answer's content, says the
+    // read-out is complete.  Above: the query is itself a learnt CONTINUATION.
+    // Here: the query is a learnt CONTEXT and the grounded answer is one of ITS
+    // OWN continuations.  Either way the question was answered directly and there
+    // is nothing left to chain for.
+    //
+    // Every stopping condition in the loop below judges the ANSWER (`consumed` /
+    // `restatesQuery` / `bytesEqual`); none asks whether the QUESTION was
+    // satisfied.  So a single-hop question whose answer happens to name another
+    // learnt context extends past a correct answer and REPLACES it:
+    //
+    //   asked  "<subj> father"
+    //   hop 1  "The father of <subj> is Ernest I of Anhalt-Dessau."   <- correct
+    //   pivot  "Ernest I of Anhalt-Dessau"                <- a learnt context too
+    //   got    "The date of death of Ernest I of Anhalt-Dessau is 12 June 1516."
+    //
+    // Any store holding a bare-entity context alongside a relation fact has that
+    // shape; it is not exotic.
+    //
+    // Checked ONCE, before the loop, and ahead of BOTH extension branches:
+    // `absorbForward` extends the answer too, and nothing about the defect is
+    // specific to pivoting, so a guard between them would gate one arbitrary half
+    // of the same step.  Hop 0 is also the only hop at which the question can be
+    // answered directly at all — after a hop, `cur` is no longer the query's own
+    // continuation, so re-testing per hop could only cost reads.
+    //
+    // Read from the ANSWER's side (`prevFirst`) rather than the query's
+    // (`nextFirst`).  Same relation, but a CONTEXT's fan-out is hub-sized while
+    // this is one answer's establishing-context fan-in.  Both the resolve and the
+    // reverse read are exactly what hop 0 of the loop below would perform, so
+    // they are computed ONCE here and handed down (`groundedId`, `groundedPrev`)
+    // — the guard then costs nothing when it does not fire.  Stated because the
+    // naive placement does NOT: `resolve` re-folds the answer bytes on every call
+    // (no memo) and `prevFirst` is a direct read (no memo), so a guard that
+    // recomputed them would add one fold plus one √N-bounded read per ask.
+    // The √N cap carries the file-wide visibility trade, and fails SAFE in the
+    // direction that matters: a missed guard costs an over-extended answer, never
+    // a suppressed chain.
+    //
+    // A genuine multi-hop query is not a deposited context at all ("What is the
+    // capital of the country of Eiffel Tower?" resolves to nothing), so this can
+    // never gate a real chain.
+    const groundedId = resolve(ctx, answer);
+    const groundedPrev = groundedId === null
+        ? null
+        : ctx.store.prevFirst(groundedId, bound);
+    if (qId !== null && groundedPrev !== null && groundedPrev.includes(qId)) {
+        return answer;
+    }
+    const consumed = new Set();
+    /** `prev` lets a caller hand in an already-read reverse-edge list — hop 0
+     *  reuses the guard's, above, instead of re-reading it. */
+    const consumeNode = (id, prev) => {
         if (id === null)
             return;
         consumed.add(id);
-        for (const p of ctx.store.prevFirst(id, bound))
+        for (const p of prev ?? ctx.store.prevFirst(id, bound))
             consumed.add(p);
     };
     const consumeAll = (id) => {
@@ -92,8 +144,10 @@ export async function reason(ctx, query, answer, preConsumed, pre, voiced = [])
     let t;
     const startedFrom = answer;
     for (let hop = 0; hop < ctx.cfg.recallQueryK; hop++) {
-        const curId = resolve(ctx, cur);
-        consumeNode(curId);
+        // Hop 0's `cur` IS `answer`, so the guard above already resolved it and
+        // read its reverse edges — reuse both rather than repeat them.
+        const curId = hop === 0 ? groundedId : resolve(ctx, cur);
+        consumeNode(curId, hop === 0 ? groundedPrev ?? undefined : undefined);
         // Forward-absorb: follow only UNCONSUMED continuations.  The gate below
         // checks an unconsumed edge EXISTS, but follow()'s chooseNext knows
         // nothing of `consumed` and may still walk to a consumed fixpoint —

package/dist/src/mind/recognition.js

@@ -6,7 +6,7 @@
 //   segment   — leaf-parent segmentation using the geometry's own groupings.
 import { rItem } from "./trace.js";
 import { canonResolve, foldTree, gistOf, latin1Key, perceive, resolve, } from "./primitives.js";
-import { atomIsHub, corpusN, leadsSomewhere } from "./traverse.js";
+import { atomIsHub, bearsEdge, corpusN, leadsSomewhere } from "./traverse.js";
 import { chainReach, leafIdAt, leafIdRun } from "./canonical.js";
 import { canonHash } from "../canon.js";
 import { isChunk } from "../sema.js";
@@ -585,6 +585,31 @@ function recogniseImpl(ctx, bytes) {
     // "Eiffel Tower" site vanished with it).  The premise is wrong but the
     // trust it stood in for is real; a replacement signal is still open work.
     // See bench/README.md.
+    //
+    // THE REPLACEMENT SIGNAL (2026-08-13): `leadsSomewhere` on the BYTE-EXACT
+    // branch the chain already found.  The blanket off-boundary suppression is
+    // a decision that CHANGES WITH CORPUS SIZE — `atomsAreHubs` flips at
+    // N = 4096 (atomReach = ⌈N·W/256⌉ exceeds √N there) — so a store crossing
+    // that point silently loses interior sites it used to have.  Measured: with
+    // the two-hop chain deposited, `recognise("The country of Eiffel Tower is
+    // France.")` yields 4 sites including `France` at N = 3920 and 2 sites
+    // without it at N = 4227; the pivot dies with the site and multi-hop goes
+    // silent from there up (the trained store is N = 325,615).
+    //
+    // The honest gate is the one `emit` already applies, moved EARLIER and paid
+    // for with existence probes instead of a fold: `findBranch` has already
+    // proved these bytes are a stored branch, so the only remaining question is
+    // whether that branch is a deposited whole (bears an edge or a halo) or an
+    // interned fragment.  "hi" out of "W[hi]ch" leads nowhere and is still
+    // suppressed; `France` bears both and is admitted.  Structural, not scalar
+    // — no constant enters and nothing reads N, so the verdict no longer moves
+    // when the corpus grows.
+    //
+    // COST: `bearsEdge` is the response-MEMOISED edge probe, not the full
+    // `leadsSomewhere` — its uncached `hasHalo` tier took haloProbes from 922 to
+    // 9,144 on a nine-query battery over the trained store, which is not a price
+    // this pass may charge.  `emit` still applies the full predicate, so this is
+    // a pre-filter that never widens what is admitted.
     const tryChain = (p, maxIds, boundary) => {
         const first = leafFrom(p);
         if (!first)
@@ -599,9 +624,10 @@ function recogniseImpl(ctx, bytes) {
                 break;
             ids.push(nx.id);
             pos = nx.end;
-            if (store.findBranch(ids) === null)
+            const branch = store.findBranch(ids);
+            if (branch === null)
                 continue;
-            if (!boundary && atomsAreHubs)
+            if (!boundary && atomsAreHubs && !bearsEdge(ctx, branch))
                 continue;
             const id = resolveSpan(p, pos);
             if (id === null || id === prevId)

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

@@ -42,6 +42,22 @@ export declare function atomReach(ctx: MindContext, contextCount: number): numbe
  *  atom votes and is recognised exactly as any stored form; above it the
  *  alphabet is scaffolding everywhere and abstains. */
 export declare function atomIsHub(ctx: MindContext, contextCount: number): boolean;
+/** Cached "does this node bear a continuation edge?" — the CHEAP half of
+ *  {@link leadsSomewhere}, exported for hot paths that must PRE-FILTER a
+ *  candidate before paying for a fold and cannot afford the halo tier.
+ *
+ *  `leadsSomewhere`'s second tier (`hasHalo`) is deliberately uncached — one
+ *  indexed point probe per candidate, which is right where candidates are
+ *  already few.  On recognition's off-boundary chain pass they are not few:
+ *  using the full predicate there took haloProbes from 922 to 9,144 on a
+ *  nine-query battery over the trained store.  The edge tier alone is memoised
+ *  for the response, so it is ~free, and a node bearing an edge is exactly the
+ *  "deposited whole, not an interned fragment" claim that pass needs.
+ *
+ *  Strictly NARROWER than `leadsSomewhere` — a halo-only node reads false — so
+ *  it is sound as a pre-filter before a consumer that applies the full
+ *  predicate, and never as a replacement for it. */
+export declare function bearsEdge(ctx: MindContext, id: number): boolean;
 /** Whether a node LEADS SOMEWHERE — it bears a continuation edge or a halo.
  *  The admission predicate recognition filters sites with (HOW_IT_WORKS
  *  §15.3): a form that leads nowhere contributes nothing to any derivation.
@@ -80,6 +96,24 @@ export declare function hubCap<T>(ctx: MindContext, ids: readonly T[]): readonly
  *  descent.  Used by articulation to keep a voice from revoicing a fragment
  *  OF that voice. */
 export declare function contains(ctx: MindContext, ancestor: number, descendant: number): boolean;
+/** Whether a continuation edge joins the two forms, in either direction —
+ *  the EXACT half's veto on calling them synonyms.
+ *
+ *  Halos measure company, and the strongest company any two forms can keep is
+ *  standing next to each other: a question and its answer co-occur in every
+ *  episode that taught the pair, so their halos SHOULD be similar, and on a
+ *  conversational store they are (measured on the CONV fixture: consecutive
+ *  turns at 0.809 against a 0.516 concept threshold).  A gate reading halo
+ *  cosine alone therefore reads adjacency as synonymy and revoices an answer
+ *  in the words of the question it answers — "it hangs in madrid" spliced back
+ *  into "where is it kept now".  The distributional layer cannot tell the two
+ *  relations apart, because to it they are the same observation; the exact
+ *  half can, for free, because it stored the edge.  §4.1's division of labour
+ *  exactly: approximate proposes, exact decides.
+ *
+ *  Read LIMITed in both directions at the hub bound — a common continuation's
+ *  fan-in is corpus-sized, and no single decision may scale with it. */
+export declare function answers(ctx: MindContext, a: number, b: number): boolean;
 /** The best-scoring item by cosine against `query`, among items scoring at
  *  or above `threshold` — the shared arg-max every Pattern-A "which of these
  *  resonates best" decision reduces to.  `strict` picks the tie-break a

package/dist/src/mind/traverse.js

@@ -407,6 +407,24 @@ export function atomReach(ctx, contextCount) {
 export function atomIsHub(ctx, contextCount) {
     return atomReach(ctx, contextCount) > boundFor(contextCount);
 }
+/** Cached "does this node bear a continuation edge?" — the CHEAP half of
+ *  {@link leadsSomewhere}, exported for hot paths that must PRE-FILTER a
+ *  candidate before paying for a fold and cannot afford the halo tier.
+ *
+ *  `leadsSomewhere`'s second tier (`hasHalo`) is deliberately uncached — one
+ *  indexed point probe per candidate, which is right where candidates are
+ *  already few.  On recognition's off-boundary chain pass they are not few:
+ *  using the full predicate there took haloProbes from 922 to 9,144 on a
+ *  nine-query battery over the trained store.  The edge tier alone is memoised
+ *  for the response, so it is ~free, and a node bearing an edge is exactly the
+ *  "deposited whole, not an interned fragment" claim that pass needs.
+ *
+ *  Strictly NARROWER than `leadsSomewhere` — a halo-only node reads false — so
+ *  it is sound as a pre-filter before a consumer that applies the full
+ *  predicate, and never as a replacement for it. */
+export function bearsEdge(ctx, id) {
+    return cachedHasNext(ctx, id, getStructCache(ctx));
+}
 /** Whether a node LEADS SOMEWHERE — it bears a continuation edge or a halo.
  *  The admission predicate recognition filters sites with (HOW_IT_WORKS
  *  §15.3): a form that leads nowhere contributes nothing to any derivation.
@@ -490,6 +508,30 @@ export function contains(ctx, ancestor, descendant) {
     }
     return false;
 }
+/** Whether a continuation edge joins the two forms, in either direction —
+ *  the EXACT half's veto on calling them synonyms.
+ *
+ *  Halos measure company, and the strongest company any two forms can keep is
+ *  standing next to each other: a question and its answer co-occur in every
+ *  episode that taught the pair, so their halos SHOULD be similar, and on a
+ *  conversational store they are (measured on the CONV fixture: consecutive
+ *  turns at 0.809 against a 0.516 concept threshold).  A gate reading halo
+ *  cosine alone therefore reads adjacency as synonymy and revoices an answer
+ *  in the words of the question it answers — "it hangs in madrid" spliced back
+ *  into "where is it kept now".  The distributional layer cannot tell the two
+ *  relations apart, because to it they are the same observation; the exact
+ *  half can, for free, because it stored the edge.  §4.1's division of labour
+ *  exactly: approximate proposes, exact decides.
+ *
+ *  Read LIMITed in both directions at the hub bound — a common continuation's
+ *  fan-in is corpus-sized, and no single decision may scale with it. */
+export function answers(ctx, a, b) {
+    const bound = hubBound(ctx);
+    if (ctx.store.hasNext(a) && ctx.store.nextFirst(a, bound).includes(b)) {
+        return true;
+    }
+    return ctx.store.hasNext(b) && ctx.store.nextFirst(b, bound).includes(a);
+}
 // ── Edge disambiguation (Section 6) ──────────────────────────────────────
 /** The best-scoring item by cosine against `query`, among items scoring at
  *  or above `threshold` — the shared arg-max every Pattern-A "which of these

package/dist/src/store-sqlite.d.ts

@@ -46,6 +46,8 @@ export declare class SQliteStore extends AbstractStore implements Store {
     private _insCanon;
     private _selCanon;
     private _cntCanon;
+    private _insSketch;
+    private _selSketch;
     private _selContentFrom;
     private _delMeta;
     private _insSnapshot;
@@ -136,6 +138,8 @@ export declare class SQliteStore extends AbstractStore implements Store {
     protected _dbDeleteMeta(key: string): void;
     canonAdd(h: number, id: number): void;
     canonFind(h: number): number[];
+    sketchGet(id: number): number[] | null;
+    sketchPut(id: number, ids: readonly number[]): void;
     canonCount(): number;
     eachContent(cb: (id: number, bytes: Uint8Array) => void, fromId?: number): void;
     protected _dbSaveSnapshot(bytes: Uint8Array): void;

package/dist/src/store-sqlite.js

@@ -124,6 +124,20 @@ CREATE TABLE IF NOT EXISTS canon (
   id INTEGER NOT NULL,
   PRIMARY KEY (h, id)
 ) WITHOUT ROWID;
+-- CONSTITUENT SKETCH (Store.sketchGet/sketchPut): the bottom-k minimal
+-- constituents of a node's subtree, k = √D, chosen by identity hash.  The blob is
+-- a packed int32 little-endian run, already in hash order; an EMPTY blob is a
+-- real answer (a minimal unit has no constituents) and a MISSING ROW means
+-- "not yet computed" — the two must stay distinguishable, which is why absence
+-- is a missing row rather than an empty blob sentinel.  (node:sqlite binds a
+-- zero-length Uint8Array as NULL, so the column is nullable and a NULL blob
+-- reads back as the empty sketch — the ROW is what records "computed".)
+-- Measured on the trained
+-- store: 80.8% of nodes sketch EMPTY, mean 1.14 ids, ~72 MB over 15.7M nodes.
+CREATE TABLE IF NOT EXISTS sketch (
+  id  INTEGER PRIMARY KEY,
+  ids BLOB
+);
 CREATE TABLE IF NOT EXISTS snapshot (
   id INTEGER PRIMARY KEY CHECK (id = 1),
   data BLOB NOT NULL
@@ -227,6 +241,8 @@ export class SQliteStore extends AbstractStore {
     _insCanon = null;
     _selCanon = null;
     _cntCanon = null;
+    _insSketch = null;
+    _selSketch = null;
     _selContentFrom = null;
     _delMeta = null;
     _insSnapshot = null;
@@ -829,6 +845,37 @@ export class SQliteStore extends AbstractStore {
         }
         return this._selCanon.all(h).map((r) => r.id);
     }
+    // -- Constituent sketch (Store optional capability) --
+    sketchGet(id) {
+        if (!this._selSketch) {
+            this._selSketch = this.sqlite.prepare("SELECT ids FROM sketch WHERE id = ?");
+        }
+        const row = this._selSketch.get(id);
+        if (row === undefined)
+            return null; // never computed — NOT the same as []
+        const b = row.ids;
+        if (b === null || b.byteLength === 0)
+            return []; // computed, no constituents
+        const out = [];
+        const dv = new DataView(b.buffer, b.byteOffset, b.byteLength);
+        for (let i = 0; i + 4 <= b.byteLength; i += 4) {
+            out.push(dv.getInt32(i, true));
+        }
+        return out;
+    }
+    sketchPut(id, ids) {
+        if (!this._insSketch) {
+            this._insSketch = this.sqlite.prepare("INSERT OR REPLACE INTO sketch (id, ids) VALUES (?, ?)");
+        }
+        const b = new Uint8Array(ids.length * 4);
+        const dv = new DataView(b.buffer);
+        for (let i = 0; i < ids.length; i++)
+            dv.setInt32(i * 4, ids[i], true);
+        // Join the deferred write transaction (committed by flush/commit), like
+        // canonAdd — a training run writes these in bulk.
+        this._dbBeginTx();
+        this._insSketch.run(id, b);
+    }
     canonCount() {
         if (!this._cntCanon) {
             this._cntCanon = this.sqlite.prepare("SELECT count(*) AS c FROM canon");

package/dist/src/store.d.ts

@@ -324,6 +324,13 @@ export interface Store {
      *  restricts the scan to ids ≥ fromId, so an index refresh after further
      *  training only visits the new rows. */
     eachContent?(cb: (id: NodeId, bytes: Uint8Array) => void, fromId?: NodeId): void;
+    /** The stored sketch of `id`, or null when it has never been computed.
+     *  An empty array is a REAL answer (a minimal unit has no constituents) and
+     *  must be distinguished from null. */
+    sketchGet?(id: NodeId): NodeId[] | null;
+    /** Record `ids` as the sketch of `id`.  Idempotent; ids are already sorted
+     *  by the caller's identity hash. */
+    sketchPut?(id: NodeId, ids: readonly NodeId[]): void;
     size(): Promise<number>;
     saveSnapshot(bytes: Uint8Array): Promise<void>;
     loadSnapshot(): Promise<Uint8Array | null>;