@hviana/sema 0.8.9 → 0.9.1

package/dist/src/mind/recognition.js

@@ -5,10 +5,11 @@
 //               that leads somewhere (has a continuation edge or a halo).
 //   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 { canonResolve, foldTree, gistOf, perceive, resolve, } from "./primitives.js";
 import { atomIsHub, bearsEdge, corpusN, leadsSomewhere } from "./traverse.js";
 import { chainReach, leafIdAt, leafIdRun } from "./canonical.js";
 import { canonHash } from "../canon.js";
+import { latin1 } from "../bytes.js";
 import { isChunk } from "../sema.js";
 /** Decompose a byte stream into every stored form that leads somewhere
  *  (has a continuation edge or a halo).  Two complementary readings:
@@ -77,7 +78,7 @@ export function recognise(ctx, bytes) {
     // not silent), so it is emitted here directly rather than only inside
     // recogniseImpl.
     if (ctx.recogniseMemo) {
-        const key = latin1Key(bytes);
+        const key = latin1(bytes);
         const hit = ctx.recogniseMemo.get(key);
         if (hit !== undefined) {
             if (ctx.meter)
@@ -483,9 +484,21 @@ function recogniseImpl(ctx, bytes) {
             // encoding is the identity, so the span's bytes ARE the branch key.
             // `subarray` is a view — this allocates nothing per probe, and the
             // bloom filter answers the misses without touching the database.
-            const flatProbe = (start, end) => store.findFlatBranch
-                ? store.findFlatBranch(bytes.subarray(start, end))
-                : store.findBranch(allLeafIds.slice(start, end));
+            //
+            // Through ONE span prober (Store.flatSpans), because hashing the key was
+            // itself the quadratic: every probe hashed its span from the start, and
+            // the interior pass below sweeps up to `reach` ends past each endpoint —
+            // O(n · reach²) bytes hashed.  Measured on the 31.7M-node store, one
+            // composition-regime response (#97 of the battery) probed 2,079,400
+            // spans and hashed 251,660,406 bytes for them.  The prober extends each
+            // start's hash instead, so the same probes, answered identically, cost
+            // O(n · reach).
+            const spans = store.flatSpans?.(bytes) ?? null;
+            const flatProbe = (start, end) => spans !== null
+                ? spans(start, end)
+                : store.findFlatBranch
+                    ? store.findFlatBranch(bytes.subarray(start, end))
+                    : store.findBranch(allLeafIds.slice(start, end));
             // THE TWO ROUTES COST DIFFERENT THINGS, SO THEY ARE PRICED SEPARATELY.
             //
             // The exact route is a bloom-gated hash over a subarray VIEW: no
@@ -518,7 +531,17 @@ function recogniseImpl(ctx, bytes) {
                 // emitted, so a caller can retry a trimmed edge on the miss path only.
                 if (end - start < W)
                     return false;
-                if (flatProbe(start, end) === null) {
+                // The byte-exact route is a BLOOM, so a non-null answer means MAYBE: it can neither
+                // decide (that is `resolveSpan`'s job) nor deny (that is `canonAdmits`').  Reading it
+                // as a YES made a false positive both drop the span and skip the decider, because the
+                // canon route ran only on a null.  Measured on the trained corpus: 280 spans where the
+                // bloom claimed and the identity refused.  A bloom HIT that resolves still emits
+                // without touching the canon route, which is what keeps the cheap path cheap.
+                const flat = flatProbe(start, end);
+                let id = flat === null ? null : resolveSpan(start, end);
+                if (id === null) {
+                    if (flat !== null && ctx.meter)
+                        ctx.meter.bloomFalsePositives++;
                     if (!canonBudget) {
                         if (ctx.meter)
                             ctx.meter.canonProbesDenied++;
@@ -526,8 +549,8 @@ function recogniseImpl(ctx, bytes) {
                     }
                     if (!canonAdmits(start, end))
                         return false;
+                    id = resolveSpan(start, end);
                 }
-                const id = resolveSpan(start, end);
                 if (id === null)
                     return false;
                 emit(start, end, id);
@@ -600,77 +623,37 @@ function recogniseImpl(ctx, bytes) {
             // keeps this off the quadratic path the budget note above describes (that
             // one had no span bound at all).
             {
-                // The span bound is W^2, the chain's own limit, PLUS the slack the endpoint set already grants: every endpoint
-                // sits within `radius` of a cut, so a pair that names one form may straddle cuts and still be a single form's
-                // span.  Measured on the composite fixture: W=4 (reach 16), radius 8, and the useful [7,32) is 25 bytes with its
-                // edges 2 bytes from cuts 5 and 30 — already IN `ordered`, and excluded only by the upper bound.  Both terms are
+                // The span bound is the chain's own limit PLUS the slack the endpoint set already grants: every endpoint sits
+                // within `radius` of a cut, so a pair that names one form may straddle cuts and still be a single form's span.
+                // Measured on the composite fixture: W=4 (reach 16), radius 8, and the useful [7,32) is 25 bytes with its edges
+                // 2 bytes from cuts 5 and 30 — already IN `ordered`, and excluded only by the upper bound.  Both terms are
                 // derived (W and the seat count); no new constant enters.
-                const reach = chainReach(W) + 2 * radius;
+                //
+                // The chain term is W^2 * W = W^4, for a form embedded in the MIDDLE of a longer query.  Measured on the
+                // trained corpus, the SAME real contexts in three positions: opening 12/17, MIDDLE 0/17, end 12/17.  The two
+                // edge scans reach only prefixes and suffixes, so the interior pass is the only tier that could name it, and
+                // at W^2 it could not.  WHAT KEEPS THIS LINEAR IS THE BOUND BEING A CONSTANT — each endpoint pairs only with
+                // the partners inside a fixed window, so the work stays O(n).  Measured against a cut-pair enumeration with
+                // ±W trims (an earlier, 43-line attempt): that one reached the same 136 B at 70 888 probes, this one at
+                // 84 169 (x1.19 more) — and BOTH pass test/14, which gates the CLASS (linear) and not the constant.  The
+                // simpler form won on that measurement.
+                const reach = chainReach(W) * W * W + 2 * radius;
                 if (ctx.meter)
                     ctx.meter.recogniseInteriorGaps += ordered.length;
+                // Each end pairs only with the starts in [end − reach, end − W], in
+                // ascending order — the pairs, and the order the budget is spent in,
+                // of the all-pairs scan, without its O(n²) enumeration.
+                let lo = 0;
                 for (const end of ordered) {
-                    for (const start of ordered) {
-                        if (start >= end)
-                            continue;
-                        const span = end - start;
-                        if (span < W || span > reach)
-                            continue;
-                        if (ctx.meter)
-                            ctx.meter.recogniseInteriorPairs++;
-                        spend(start, end);
-                    }
-                }
-                // ── THE MIDDLE WAS BLIND: a CUT-PAIR probe, BOUNDED so it stays LINEAR ──────────────
-                // A stored form embedded in the MIDDLE of a longer query was named by NO tier: the two
-                // edge scans probe only prefixes and suffixes, and the loop above is capped at
-                // `reach` = W^2 + 2*radius.  Measured on the trained corpus, the SAME real contexts in
-                // three positions: opening 12/17, MIDDLE 0/17, end 12/17.  Both edges of such a form sit
-                // within `radius` of CUTS, so a cut pair plus a small trim names the form exactly
-                // (measured: a 64 B form at [27, 91) between cuts 26 and 90, trims +1/+1).
-                //
-                // THE BOUND IS WHAT KEEPS IT LINEAR.  An unbounded cut-pair scan is O(cuts^2) probes, and
-                // test/14 rejected exactly that (47 324 ms).  Bounded by a CONSTANT span it is
-                // O(cuts * const) = O(n), like the loop above — the constant is merely larger.  The bound
-                // is DERIVED, never pinned: `chainReach(W)` is W^2, "the deepest two-level composite the
-                // write side's windows can spell" (canonical.ts), so `chainReach(W) * W * W` is the
-                // four-level one; `chainReach(W) * W` is already used in bridge.ts.
-                //
-                // THE TRIMS ARE THE SAME DISCIPLINE THE EDGE SCANS USE — the suffix scan already probes
-                // `spend(s, bytes.length - 1)`, so ±W is a wider version of an existing rule, not a new
-                // threshold.  Measured price/reach; all four configurations pass test/14, which gates the
-                // CLASS (linear) and not the constant:
-                //   W^3 + ±1  -> 64 B,   8 068 probes (x2.02)
-                //   W^4 + ±W  -> 136 B, 70 888 probes (x6.06)   <- this one
-                //   W^3 + ±W and W^4 + ±1 are DOMINATED: each stops at the other parameter and costs more.
-                // The loop above stays, so no candidate that produces a site today is lost.  Suite
-                // 707/707, and a differential over 24 real corpus questions is byte-identical (0 answers
-                // changed, 0 new duplicate sites): the :258 warning that a wider bound can rediscover a
-                // smaller subtree's content as a second, overlapping site was read and measured, and it
-                // does not materialise here.
-                const deepReach = chainReach(W) * W * W;
-                for (let ci = 0; ci + 1 < startList.length; ci++) {
-                    for (let cj = ci + 1; cj < startList.length; cj++) {
-                        if (startList[cj] - startList[ci] > deepReach + 2 * radius)
+                    while (ordered[lo] < end - reach)
+                        lo++;
+                    for (let i = lo; i < ordered.length; i++) {
+                        const start = ordered[i];
+                        if (end - start < W)
                             break;
-                        // The EXACT cut pair first.  Measured: with the 81 trims starting at -W the `spend`
-                        // pool ran dry (canonProbesDenied in the millions) and the canon route was then denied
-                        // to the candidates that needed it — including forms the byte-exact route SEES
-                        // (`flatProbe` true) that were still not named.  Probing (ci, cj) before any trim puts
-                        // the common case in front of the famine.
                         if (ctx.meter)
                             ctx.meter.recogniseInteriorPairs++;
-                        spend(startList[ci], startList[cj]);
-                        for (let dl = -W; dl <= W; dl++) {
-                            for (let dr = -W; dr <= W; dr++) {
-                                const a = startList[ci] + dl;
-                                const z = startList[cj] + dr;
-                                if (a < 0 || z > bytes.length || z - a < W)
-                                    continue;
-                                if (ctx.meter)
-                                    ctx.meter.recogniseInteriorPairs++;
-                                spend(a, z);
-                            }
-                        }
+                        spend(start, end);
                     }
                 }
             }
@@ -706,8 +689,7 @@ function recogniseImpl(ctx, bytes) {
     // arithmetic, not evidence.  Removing it wholesale was measured and
     // REVERTED: it also drops legitimate multi-byte chains (the 12-byte
     // "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.
+    // trust it stood in for is real; the replacement signal follows.
     //
     // THE REPLACEMENT SIGNAL (2026-08-13): `leadsSomewhere` on the BYTE-EXACT
     // branch the chain already found.  The blanket off-boundary suppression is

package/dist/src/mind/resonance.js

@@ -6,7 +6,7 @@
 import { rItem } from "./trace.js";
 import { cosine } from "../vec.js";
 import { mergeThreshold } from "../geometry.js";
-import { concat2, concatBytes, indexOf } from "../bytes.js";
+import { concat2, concatBytes, indexOf, latin1 } from "../bytes.js";
 import { gistOf, read, resolve, walkTree } from "./primitives.js";
 import { perceive } from "./primitives.js";
 import { argmaxCosine, candidateGist, hubBound } from "./traverse.js";
@@ -107,16 +107,6 @@ function junctionEdges(ctx, left, right, maxContainer) {
     }
     return out;
 }
-/** A byte string as a string, ONE code unit per byte — injective, so it is
- *  safe to build a cache key from.  Chunked to keep the spread within the
- *  engine's argument limit on long contexts. */
-function latin1(b) {
-    let s = "";
-    for (let i = 0; i < b.length; i += 4096) {
-        s += String.fromCharCode(...b.subarray(i, i + 4096));
-    }
-    return s;
-}
 /** Per-response memo of bridge results, keyed by the response's lifecycle
  *  object (ctx.climbMemo — created fresh by respond() and nulled after, so
  *  entries can never outlive the read-only window they are valid in).  The

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

@@ -58,9 +58,9 @@ export declare function atomIsHub(ctx: MindContext, contextCount: number): boole
  *  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 (cover.md): a form
- * that
+/** Whether a node LEADS SOMEWHERE — the store's admission predicate
+ * ({@link Store.leadsSomewhere}: edge or halo) with its edge tier memoised for
+ * the response.  Recognition filters sites with it (cover.md): a form that
  * leads nowhere contributes nothing to any derivation. Runs once per candidate
  * span on the recognition hot path — `hasNext` is cached per response (the same
  * flat-branch ids are probed across prefix variants by canonicalChunkId).

package/dist/src/mind/traverse.js

@@ -432,9 +432,9 @@ export function atomIsHub(ctx, contextCount) {
 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 (cover.md): a form
- * that
+/** Whether a node LEADS SOMEWHERE — the store's admission predicate
+ * ({@link Store.leadsSomewhere}: edge or halo) with its edge tier memoised for
+ * the response.  Recognition filters sites with it (cover.md): a form that
  * leads nowhere contributes nothing to any derivation. Runs once per candidate
  * span on the recognition hot path — `hasNext` is cached per response (the same
  * flat-branch ids are probed across prefix variants by canonicalChunkId).

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

@@ -157,7 +157,13 @@ export interface Attention {
      *  a genuine further topic is named in its own distinctive wording
      *  somewhere the query's scaffolding does not reach, always a SEPARATE
      *  cluster from whatever else corroborates it.  See
-     *  test/37-cluster-dispersion-fusion.test.mjs. */
+     *  test/37-cluster-dispersion-fusion.test.mjs.
+     *
+     *  Read from the VOTES, this is a lossy witness: a region votes once, for its
+     *  top anchor, so a place can be lost to a tie or won through an accident.
+     *  Fusion therefore also asks the root's CONTEXT the same question at window
+     *  scale (reasoning.ts `sharedPlaces`) and trusts a root that either reading
+     *  finds in two places. */
     clusters: number;
 }
 /** Both read-outs of one consensus climb. */

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

@@ -28,6 +28,20 @@ export declare class SQliteStore extends AbstractStore implements Store {
     private _bloom;
     /** Dedup probes answered by the filter alone this session (observability). */
     bloomSkips: number;
+    /** The same negative filter over the CANON index's key hashes.  Recognition's
+     *  canonical admission and the join's canonical entity scan ask `canonFind`
+     *  once per probed span, and almost every answer is "no such key" — on an
+     *  index that is often EMPTY (it is built only by `buildCanonIndex`).
+     *  Loaded on first use from `canon_bloom` when its stamp matches the meta,
+     *  else built by one sequential scan of the h column; kept exact on
+     *  `canonAdd` (rebuilt bigger from the table, uncommitted rows included,
+     *  when growth saturates it) and persisted with the commit that wrote the
+     *  rows.  The canon table is never deleted from, so the filter can never
+     *  hold a false negative: a miss it reports is a miss the query would have
+     *  returned. */
+    private _canonBloom;
+    /** The in-memory canon filter differs from the persisted one. */
+    private _canonBloomDirty;
     private _insertNode;
     private _insertKid;
     private _selContain;
@@ -79,6 +93,9 @@ export declare class SQliteStore extends AbstractStore implements Store {
     protected _dbGetNode(id: NodeId): NodeRec | null;
     protected _dbFindLeaf(h: number, bytes: Uint8Array): NodeId | null;
     protected _dbFindBranchByLeaf(h: number, bytes: Uint8Array): NodeId | null;
+    /** The node filter alone: never a false negative (every inserted hash is
+     *  added before any probe can see it), so `false` is exact. */
+    protected _dbFlatMayExist(h: number, bytes: Uint8Array): boolean;
     protected _dbFindBranchByKids(h: number, packed: Uint8Array): NodeId | null;
     protected _dbInsertKid(child: NodeId, parent: NodeId): void;
     protected _dbGetParents(id: NodeId): NodeId[];
@@ -137,6 +154,14 @@ export declare class SQliteStore extends AbstractStore implements Store {
     protected _dbSetMeta(key: string, val: string): void;
     protected _dbDeleteMeta(key: string): void;
     canonAdd(h: number, id: number): void;
+    /** The canon filter: the persisted one when its stamp matches the meta,
+     *  else built from the index as it stands. */
+    private _canonFilter;
+    private _canonScan;
+    /** What a persisted canon filter is stamped with: the incremental build's
+     *  cursor, which every canon writer advances in the transaction it writes. */
+    private _canonStamp;
+    private _canonBloomPersist;
     canonFind(h: number): number[];
     sketchGet(id: number): number[] | null;
     sketchPut(id: number, ids: readonly number[]): void;

package/dist/src/store-sqlite.js

@@ -124,6 +124,17 @@ CREATE TABLE IF NOT EXISTS canon (
   id INTEGER NOT NULL,
   PRIMARY KEY (h, id)
 ) WITHOUT ROWID;
+-- The canon index's negative filter, persisted so an open does not rescan the
+-- h column (seconds on a trained store).  Written in the SAME transaction as
+-- the canon rows it covers, stamped with the meta 'canon.upto' of that commit;
+-- a stamp that disagrees with the meta (rows a writer added without it) makes
+-- the filter stale, and it is rebuilt from the table instead.
+CREATE TABLE IF NOT EXISTS canon_bloom (
+  id   INTEGER PRIMARY KEY CHECK (id = 1),
+  bits BLOB NOT NULL,
+  n    INTEGER NOT NULL,
+  upto TEXT NOT NULL
+);
 -- 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
@@ -223,6 +234,20 @@ export class SQliteStore extends AbstractStore {
     _bloom = null;
     /** Dedup probes answered by the filter alone this session (observability). */
     bloomSkips = 0;
+    /** The same negative filter over the CANON index's key hashes.  Recognition's
+     *  canonical admission and the join's canonical entity scan ask `canonFind`
+     *  once per probed span, and almost every answer is "no such key" — on an
+     *  index that is often EMPTY (it is built only by `buildCanonIndex`).
+     *  Loaded on first use from `canon_bloom` when its stamp matches the meta,
+     *  else built by one sequential scan of the h column; kept exact on
+     *  `canonAdd` (rebuilt bigger from the table, uncommitted rows included,
+     *  when growth saturates it) and persisted with the commit that wrote the
+     *  rows.  The canon table is never deleted from, so the filter can never
+     *  hold a false negative: a miss it reports is a miss the query would have
+     *  returned. */
+    _canonBloom = null;
+    /** The in-memory canon filter differs from the persisted one. */
+    _canonBloomDirty = false;
     _insertNode = null;
     _insertKid = null;
     _selContain = null;
@@ -453,8 +478,10 @@ export class SQliteStore extends AbstractStore {
             "n = excluded.n, upto = excluded.upto").run(this._bloom.bits, this._bloom.n, this._nextId);
     }
     _dbClose() {
-        if (this.sqlite)
+        if (this.sqlite) {
             this._bloomPersist();
+            this._canonBloomPersist();
+        }
         if (this.content) {
             this.content.close();
             this.content = null;
@@ -478,6 +505,8 @@ export class SQliteStore extends AbstractStore {
     _dbCommitTx() {
         if (!this._inTx || !this.sqlite)
             return;
+        // The canon filter commits WITH the rows it covers — see canon_bloom.
+        this._canonBloomPersist();
         this._inTx = false; // clear first so a throw can't wedge us mid-commit
         this.sqlite.exec("COMMIT");
     }
@@ -534,6 +563,16 @@ export class SQliteStore extends AbstractStore {
         const row = this._selFlat.get(h, bytes);
         return row ? row.id : null;
     }
+    /** The node filter alone: never a false negative (every inserted hash is
+     *  added before any probe can see it), so `false` is exact. */
+    _dbFlatMayExist(h, bytes) {
+        if (this._bloom === null)
+            return super._dbFlatMayExist(h, bytes);
+        if (this._bloom.mightContain(h))
+            return true;
+        this.bloomSkips++;
+        return false;
+    }
     _dbFindBranchByKids(h, packed) {
         if (this._bloom && !this._bloom.mightContain(h)) {
             this.bloomSkips++;
@@ -855,8 +894,57 @@ export class SQliteStore extends AbstractStore {
         // bulk index build coalesces instead of paying autocommit per row.
         this._dbBeginTx();
         this._insCanon.run(h, id);
+        const b = this._canonFilter();
+        b.add(h);
+        // Rebuilt bigger at once, from the table as THIS connection sees it — the
+        // persisted filter cannot stand in, it lacks this transaction's rows.
+        if (b.saturated)
+            this._canonBloom = this._canonScan();
+        this._canonBloomDirty = true;
+    }
+    /** The canon filter: the persisted one when its stamp matches the meta,
+     *  else built from the index as it stands. */
+    _canonFilter() {
+        if (this._canonBloom === null) {
+            const row = this.sqlite.prepare("SELECT bits, n, upto FROM canon_bloom WHERE id = 1").get();
+            if (row !== undefined && row.upto === this._canonStamp()) {
+                const b = new NodeBloom(31 - Math.clz32(row.bits.length * 8));
+                b.bits.set(row.bits);
+                b.n = row.n;
+                this._canonBloom = b;
+            }
+            else {
+                this._canonBloom = this._canonScan();
+                this._canonBloomDirty = true;
+            }
+        }
+        return this._canonBloom;
+    }
+    _canonScan() {
+        const b = new NodeBloom(bloomLog2For(this.canonCount()));
+        const scan = this.sqlite.prepare("SELECT h FROM canon");
+        scan.setReturnArrays(true);
+        for (const r of scan.iterate())
+            b.add(r[0]);
+        return b;
+    }
+    /** What a persisted canon filter is stamped with: the incremental build's
+     *  cursor, which every canon writer advances in the transaction it writes. */
+    _canonStamp() {
+        return this._dbGetMeta("canon.upto") ?? "";
+    }
+    _canonBloomPersist() {
+        const b = this._canonBloom;
+        if (b === null || !this._canonBloomDirty || !this.sqlite)
+            return;
+        this.sqlite.prepare("INSERT INTO canon_bloom (id, bits, n, upto) VALUES (1, ?, ?, ?) " +
+            "ON CONFLICT(id) DO UPDATE SET bits = excluded.bits, " +
+            "n = excluded.n, upto = excluded.upto").run(b.bits, b.n, this._canonStamp());
+        this._canonBloomDirty = false;
     }
     canonFind(h) {
+        if (!this._canonFilter().mightContain(h))
+            return [];
         if (!this._selCanon) {
             this._selCanon = this.sqlite.prepare("SELECT id FROM canon WHERE h = ?");
         }

package/dist/src/store.d.ts

@@ -1,5 +1,5 @@
 import { Vec } from "./vec.js";
-import { type StoreConfig } from "./config.js";
+import type { StoreConfig } from "./config.js";
 import type { Meter } from "./meter.js";
 /** A node id: a dense, non-negative integer assigned in creation order. */
 export type NodeId = number;
@@ -166,6 +166,20 @@ export interface Store {
      *  bytes — the allocation-free probe span scanners use.  Optional: a store
      *  without it is simply probed through `findBranch`. */
     findFlatBranch?(bytes: Uint8Array): NodeId | null;
+    /** Whether a flat branch with these bytes MAY exist.  `false` is EXACT — no
+     *  such node exists, and a {@link findFlatBranch} would return null; `true`
+     *  means only that a lookup is needed.  The existence half of the probe,
+     *  without its verification: a caller that will resolve the bytes anyway
+     *  (and so verify them) asks this to refuse a miss without paying for the
+     *  lookup a hit would repeat.  Optional, like the probe it answers for. */
+    flatBranchMayExist?(bytes: Uint8Array): boolean;
+    /** A {@link findFlatBranch} over spans of ONE buffer: `probe(start, end)`
+     *  answers exactly `findFlatBranch(bytes.subarray(start, end))`, but a span's
+     *  content hash extends the one its start was last probed at, so a scanner
+     *  that sweeps ends upward per start pays O(1) per probe instead of
+     *  O(span).  The buffer must not change while the prober is used.
+     *  Optional, like the probe it accelerates. */
+    flatSpans?(bytes: Uint8Array): (start: number, end: number) => NodeId | null;
     /** The branch nodes that list `id` among their children — the reverse of
      *  `get(id).kids`. Lets the structural DAG be climbed upward, from a
      *  recognised fragment to the larger learned forms that contain it. */
@@ -314,6 +328,12 @@ export interface Store {
      *  the search's fuse guard) must ask this instead: one row read, a mass
      *  compare, no decode. */
     hasHalo(id: NodeId): boolean;
+    /** THE ADMISSION PREDICATE — whether `id` LEADS SOMEWHERE: it bears a
+     *  continuation edge ({@link hasNext}) or a halo ({@link hasHalo}).  A form
+     *  that leads nowhere contributes nothing to any derivation.  This is the ONE
+     *  raw definition; `traverse.ts`'s `leadsSomewhere` is the same predicate with
+     *  its edge tier memoised for the response.  Two point probes at most. */
+    leadsSomewhere(id: NodeId): boolean;
     /** How many episode signatures were poured into `id`'s halo — the DIRECT
      *  measure of distributional evidence (each training pair pours once, so
      *  repetition counts, unlike {@link prevCount}, which counts DISTINCT
@@ -507,6 +527,9 @@ export declare abstract class AbstractStore implements Store {
     /** Exact-content dedup: content-key → node id. Intrinsic compression. */
     protected readonly _leafKey: BoundedMap<string, NodeId>;
     protected readonly _branchKey: BoundedMap<string, NodeId>;
+    /** {@link findFlatBranch}'s hits, keyed by the bytes themselves (latin1 —
+     *  exact, unlike the hash keys above). */
+    protected readonly _flatKey: BoundedMap<string, NodeId>;
     /** Reconstructed-bytes read cache (regenerable), keyed by node id. */
     protected readonly _bytesCache: BoundedMap<NodeId, Uint8Array>;
     /** contentLen memo — content is immutable, so entries never invalidate. */
@@ -643,10 +666,29 @@ export declare abstract class AbstractStore implements Store {
      *  answers most of those with no I/O at all, so the allocations dominated.
      *
      *  Pass a subarray: it is a view, so a caller scanning spans of a query
-     *  allocates nothing per probe.  Deliberately NOT memoized — its callers
-     *  probe many spans that miss, and a key string per probe is the cost this
-     *  exists to remove. */
+     *  allocates nothing per probe that misses.  HITS ARE MEMOIZED, MISSES ARE
+     *  NOT: the negative filter answers first, so a span that is not stored
+     *  builds no key; one that may be pays a key and then usually skips the
+     *  lookup — the spans the identity fold names are segments, a few bytes
+     *  each, asked over and over by every span that contains them.  A node, once
+     *  minted, keeps its bytes and its id, so a cached hit never goes stale. */
     findFlatBranch(bytes: Uint8Array): NodeId | null;
+    /** {@link Store.flatSpans}.  Each start keeps the hash of the span it was
+     *  last probed to, plus the hash one byte short of it; a probe ending at or
+     *  past that end extends it, one ending one byte short of it reuses the
+     *  second, and any other probe hashes from the start.  `hashOf` is FNV-1a,
+     *  a left fold over the bytes, so an extended hash IS the span's hash —
+     *  same key, same filter answer, same lookup. */
+    flatSpans(bytes: Uint8Array): (start: number, end: number) => NodeId | null;
+    /** {@link findFlatBranch} past the hash: `h` must be `hashOf(bytes)`. */
+    private _findFlatHashed;
+    /** {@link Store.flatBranchMayExist} — the backend's negative filter when it
+     *  keeps one ({@link _dbFlatMayExist}), else the lookup itself. */
+    flatBranchMayExist(bytes: Uint8Array): boolean;
+    /** Default: no filter, so anything MAY exist and the lookup decides.  A
+     *  backend with a negative filter over node hashes overrides this to answer
+     *  from the filter alone. */
+    protected _dbFlatMayExist(_h: number, _bytes: Uint8Array): boolean;
     findBranch(kids: NodeId[]): NodeId | null;
     parents(id: NodeId): NodeId[];
     parentsFirst(id: NodeId, limit: number): NodeId[];
@@ -792,6 +834,8 @@ export declare abstract class AbstractStore implements Store {
     /** {@link Store.hasHalo} — MUST mirror {@link halo}'s null condition
      *  exactly (row present AND mass ≥ minHaloMass), minus the decode. */
     hasHalo(id: NodeId): boolean;
+    /** {@link Store.leadsSomewhere} — edge first (the cheaper, commoner probe). */
+    leadsSomewhere(id: NodeId): boolean;
     pourHalo(id: NodeId, add: Vec): Promise<void>;
     resonateHalo(v: Vec, k: number): Promise<Hit[]>;
     private pending;