@hviana/sema 0.2.3 → 0.2.4

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

@@ -5,8 +5,17 @@ import type { AncestorReach, Attention, AttentionRead, DFMode, MindContext, Regi
  *  attention — those that cleared commitVotes' significance floor. */
 export declare function climbAttention(ctx: MindContext, query: Uint8Array, k: number, mode?: DFMode): Promise<Attention[]>;
 /** Full read-out of one consensus climb: both the roots (dominant points of
- *  attention) and the entire ranked list.  Cached via ctx.climbMemo when
- *  ctx.trace is null. */
+ *  attention) and the entire ranked list.  Cached via ctx.climbMemo, ALWAYS —
+ *  see {@link recognise} for why this memo (and recognise()'s own) must
+ *  never be skipped while tracing: computeAttention's collectRegions walks
+ *  the query's perceived tree via the same foldTree whose subtree-resolution
+ *  fast path makes a second call on identical bytes non-idempotent once
+ *  ctx._resolvedSubtrees is warm (which a multi-turn conversation's shared
+ *  prefix subtrees guarantee by the second turn).  A cache hit still emits
+ *  a trace step — abbreviated, since the full per-sub-region voting detail
+ *  {@link traceAttention} builds isn't preserved by the cached read-out —
+ *  so a traced response is never silently blacked out for a repeated
+ *  query. */
 export declare function climbAttentionAll(ctx: MindContext, query: Uint8Array, k: number, mode?: DFMode): Promise<AttentionRead>;
 export declare function computeAttention(ctx: MindContext, query: Uint8Array, k: number, mode: DFMode): Promise<AttentionRead>;
 export declare function collectRegions(ctx: MindContext, query: Uint8Array): Region[];
@@ -42,6 +51,8 @@ export declare function poolVotes(ctx: MindContext, regionVotes: readonly Region
     /** Per-anchor SCALE-INVARIANT support: Σ RegionVote.absorbed over the
      *  distinct contributing regions — see Attention.breadth. */
     regionSupport: Map<number, number>;
+    /** Per-anchor contributing region spans — see Attention.clusters. */
+    regionSpans: Map<number, Array<[number, number]>>;
     steps: DerivationStep[];
 };
 export declare function commitVotes(ctx: MindContext, pooled: {
@@ -53,6 +64,7 @@ export declare function commitVotes(ctx: MindContext, pooled: {
         w: number;
     }>;
     regionSupport: Map<number, number>;
+    regionSpans: Map<number, Array<[number, number]>>;
     steps: DerivationStep[];
 }, sat: SaturationInfo, regions: readonly Region[], regionVoter: ReadonlyArray<{
     id: number;

package/dist/src/mind/attention.js

@@ -15,7 +15,7 @@ import { leafIdRun } from "./canonical.js";
 import { corpusN, edgeAncestors } from "./traverse.js";
 import { cachedRead, junctionContainersFrom, junctionSeeds, junctionSynonyms, walkCache, } from "./junction.js";
 import { indexOf } from "../bytes.js";
-import { rNode, traceDerivation } from "./trace.js";
+import { rItem, rNode, traceDerivation } from "./trace.js";
 // ── Public entry points ───────────────────────────────────────────────────
 /** Climb the query's perceived byte regions up the structural DAG via
  *  resonance, pool the evidence, and return only the ROOT points of
@@ -24,12 +24,21 @@ export async function climbAttention(ctx, query, k, mode = "inverse") {
     return (await climbAttentionAll(ctx, query, k, mode)).roots;
 }
 /** Full read-out of one consensus climb: both the roots (dominant points of
- *  attention) and the entire ranked list.  Cached via ctx.climbMemo when
- *  ctx.trace is null. */
+ *  attention) and the entire ranked list.  Cached via ctx.climbMemo, ALWAYS —
+ *  see {@link recognise} for why this memo (and recognise()'s own) must
+ *  never be skipped while tracing: computeAttention's collectRegions walks
+ *  the query's perceived tree via the same foldTree whose subtree-resolution
+ *  fast path makes a second call on identical bytes non-idempotent once
+ *  ctx._resolvedSubtrees is warm (which a multi-turn conversation's shared
+ *  prefix subtrees guarantee by the second turn).  A cache hit still emits
+ *  a trace step — abbreviated, since the full per-sub-region voting detail
+ *  {@link traceAttention} builds isn't preserved by the cached read-out —
+ *  so a traced response is never silently blacked out for a repeated
+ *  query. */
 export async function climbAttentionAll(ctx, query, k, mode = "inverse") {
     // Content-keyed memo — works for both single-turn respond() and multi-turn
-    // respondTurn().  Skipped while tracing.
-    if (ctx.climbMemo && !ctx.trace) {
+    // respondTurn().
+    if (ctx.climbMemo) {
         const contentKey = latin1Key(query);
         const modeKey = `${k}:${mode}`;
         let byRead = ctx.climbMemo.get(contentKey);
@@ -37,8 +46,11 @@ export async function climbAttentionAll(ctx, query, k, mode = "inverse") {
             ctx.climbMemo.set(contentKey, byRead = new Map());
         }
         const hit = byRead.get(modeKey);
-        if (hit !== undefined)
+        if (hit !== undefined) {
+            ctx.trace?.step("climbConsensus", [rItem(query, "query")], hit.roots.map((r) => rNode(ctx, r.anchor, "anchor", r.vote)), `(cached) consensus already computed for this query — ` +
+                `${hit.roots.length} point(s) of attention`);
             return hit;
+        }
         const read = await computeAttention(ctx, query, k, mode);
         byRead.set(modeKey, read);
         return read;
@@ -401,6 +413,7 @@ export function poolVotes(ctx, regionVotes, sat, N) {
     const votesIdf = new Map();
     const support = new Map();
     const regionSupport = new Map();
+    const regionSpans = new Map();
     const steps = [];
     let order = 0;
     for (const pc of pool.values()) {
@@ -409,6 +422,7 @@ export function poolVotes(ctx, regionVotes, sat, N) {
             const premises = [];
             const seenRi = new Set();
             let breadthSum = 0;
+            const spans = [];
             for (const c of pc.contributions) {
                 const p0 = c.premises[0].item;
                 if (p0.kind !== "region" || seenRi.has(p0.ri))
@@ -417,8 +431,10 @@ export function poolVotes(ctx, regionVotes, sat, N) {
                 const rv = regionVotes[p0.ri];
                 breadthSum += rv.absorbed ?? 1;
                 premises.push({ kind: "form", span: [rv.start, rv.end] });
+                spans.push([rv.start, rv.end]);
             }
             regionSupport.set(pc.item.id, breadthSum);
+            regionSpans.set(pc.item.id, spans);
             steps.push({
                 order: order++,
                 move: "pool-vote",
@@ -448,10 +464,39 @@ export function poolVotes(ctx, regionVotes, sat, N) {
             }
         }
     }
-    return { votes, votesIdf, support, regionSupport, steps };
+    return { votes, votesIdf, support, regionSupport, regionSpans, steps };
+}
+/** The number of DISTINCT clusters a root's contributing regions form —
+ *  see Attention.clusters.  Two regions belong to the same cluster iff the
+ *  gap between them is strictly less than one river-fold quantum W: at
+ *  that distance there is no room for a genuinely separate, independently
+ *  perceivable unit of content between them (the same "smallest meaningful
+ *  distinction" quantum {@link reachThreshold}'s own doc invokes).  A gap
+ *  of a full quantum or more means real, separate structure could sit
+ *  between the two spans, so they count as independent corroboration.
+ *  Strict `<` (not `<=`): verified against gap 3.1's own "gender equality"
+ *  root, whose two genuine clusters sit EXACTLY W bytes apart — `<= W`
+ *  would wrongly merge them into one and break that pinned requirement. */
+function countClusters(spans, W) {
+    if (spans.length === 0)
+        return 0;
+    const sorted = [...spans].sort((a, b) => a[0] - b[0]);
+    let clusters = 1;
+    let curEnd = sorted[0][1];
+    for (let i = 1; i < sorted.length; i++) {
+        const [s, e] = sorted[i];
+        if (s - curEnd < W) {
+            curEnd = Math.max(curEnd, e);
+        }
+        else {
+            clusters++;
+            curEnd = e;
+        }
+    }
+    return clusters;
 }
 export function commitVotes(ctx, pooled, sat, regions, regionVoter, N) {
-    const { votes, votesIdf, support, regionSupport, steps } = pooled;
+    const { votes, votesIdf, support, regionSupport, regionSpans, steps } = pooled;
     if (votes.size === 0) {
         traceAttention(ctx, regions, regionVoter, [], steps);
         return { roots: [], ranked: [] };
@@ -470,6 +515,7 @@ export function commitVotes(ctx, pooled, sat, regions, regionVoter, N) {
             start: s.start,
             end: s.end,
             breadth: (regionSupport.get(anchor) ?? 0) / totalRegions,
+            clusters: countClusters(regionSpans.get(anchor) ?? [], ctx.space.maxGroup),
         };
     })
         .sort((a, b) => b.vote - a.vote);

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

@@ -0,0 +1,30 @@
+import type { MindContext } from "./types.js";
+/** One accepted substitution: query span [qs,qe) stands in for the
+ *  candidate context's span — recorded for the rationale trace. */
+interface Substitution {
+    qs: number;
+    qe: number;
+    cs: number;
+    ce: number;
+}
+/** A bridged grounding proposal: the trained context to ground, the query
+ *  spans its alignment accounts for, and the substitutions that closed it. */
+export interface BridgeHit {
+    id: number;
+    accounted: Array<[number, number]>;
+    subs: Substitution[];
+}
+/** True when some query byte-range left UNACCOUNTED by `spans` contains a
+ *  STORED window — content the store has seen that the proposed reading
+ *  simply ignores.  The IGNORED-KNOWN principle: a span may be dismissed
+ *  only when the store itself has never seen it; known content the
+ *  alignment failed to account for is grounds for refusal, while genuinely
+ *  novel spans (an untrained word, stray punctuation) remain tolerable.
+ *  Shared by the substitution bridge's own acceptance and CAST's
+ *  frame-tier comparison gate (cast.ts).  Pure attestation — no
+ *  similarity, no constants. */
+export declare function dismissedKnownContent(ctx: MindContext, query: Uint8Array, spans: ReadonlyArray<readonly [number, number]>): boolean;
+/** Recall's corroborated-substitution bridge — see the module comment.
+ *  Returns the best bridged grounding proposal, or null. */
+export declare function substitutionBridge(ctx: MindContext, query: Uint8Array, proposed?: ReadonlyArray<number>): Promise<BridgeHit | null>;
+export {};