@hviana/sema 0.2.4 → 0.2.5

package/dist/src/geometry.d.ts

@@ -1,3 +1,4 @@
+import { Vec } from "./vec.js";
 import { Sema, Space } from "./sema.js";
 import { Alphabet } from "./alphabet.js";
 /** The store's geometric identity bar: cosine ≥ 1 − 1/√D is the similarity at
@@ -144,6 +145,31 @@ export declare function stablePrefixFoldIncremental(space: Space, alphabet: Alph
     tree: Sema;
     fold: StableFold;
 };
+/** Plain river fold WITHOUT the final root normalize — the segment-level
+ *  building block of {@link stablePrefixFold} (interiors must keep their
+ *  byte-proportional magnitude; only the whole perception's root is ever
+ *  normalized).  Exported so callers that COMPOSE already-existing structural
+ *  parts into a hypothetical synthetic root (see {@link composeStructuralGist})
+ *  can feed the same raw primitive instead of duplicating its mathematics. */
+export declare function riverFoldRaw(space: Space, row: Folded[]): Folded;
+/** One already-existing structural vector to compose, paired with the byte
+ *  span (query-slot) length it stands in for.  `len`, not the vector's own
+ *  magnitude, is what {@link composeStructuralGist} restores — the composed
+ *  slot's NATURAL span, exactly as the linear river fold would carry it. */
+export interface StructuralPart {
+    v: Vec;
+    len: number;
+}
+/** Synthesize a hypothetical internal structure from already-existing
+ *  structural vectors — NOT from bytes.  This is the raw positional
+ *  composition the linear river fold already uses (see the folding header
+ *  above): each part is positionally bound into its own seat, its natural
+ *  span magnitude is preserved, the parts are linearly superposed, and only
+ *  the final synthetic root is normalized.  It never calls {@link gistOf}
+ *  (there is no `gistOf` here — geometry.ts has no store), never perceives a
+ *  concatenated byte string, and never interns or stores a new node: the
+ *  result is an opaque, ungrounded Vec for an ANN probe only. */
+export declare function composeStructuralGist(space: Space, parts: readonly StructuralPart[]): Vec;
 /** The PLAIN fold's full level pyramid — every level's item list, bottom
  *  (leaves) to top (root).  Left-grouped folding is RADIX-ALIGNED: the item
  *  at level L, index i, covers exactly bytes [i·mg^L, (i+1)·mg^L) whenever

package/dist/src/geometry.js

@@ -6,7 +6,7 @@
 //      that cross the stable-prefix boundary are split so the prefix folds
 //      identically regardless of what follows — pure structural stability.
 //   3. The same rule recurses level after level until one root remains.
-import { normalize } from "./vec.js";
+import { addInto, copy, normalize, zeros } from "./vec.js";
 import { sema } from "./sema.js";
 // ---- geometric constants ----
 //
@@ -374,8 +374,10 @@ function fold2(space, a, b) {
 /** Plain river fold WITHOUT the final root normalize — the segment-level
  *  building block of {@link stablePrefixFold} (interiors must keep their
  *  byte-proportional magnitude; only the whole perception's root is ever
- *  normalized). */
-function riverFoldRaw(space, row) {
+ *  normalized).  Exported so callers that COMPOSE already-existing structural
+ *  parts into a hypothetical synthetic root (see {@link composeStructuralGist})
+ *  can feed the same raw primitive instead of duplicating its mathematics. */
+export function riverFoldRaw(space, row) {
     if (row.length === 0) {
         const z = new Float32Array(space.D);
         return { tree: sema(z, new Uint8Array(0), null), len: 0 };
@@ -390,6 +392,33 @@ function riverFoldRaw(space, row) {
     }
     return level[0];
 }
+/** Synthesize a hypothetical internal structure from already-existing
+ *  structural vectors — NOT from bytes.  This is the raw positional
+ *  composition the linear river fold already uses (see the folding header
+ *  above): each part is positionally bound into its own seat, its natural
+ *  span magnitude is preserved, the parts are linearly superposed, and only
+ *  the final synthetic root is normalized.  It never calls {@link gistOf}
+ *  (there is no `gistOf` here — geometry.ts has no store), never perceives a
+ *  concatenated byte string, and never interns or stores a new node: the
+ *  result is an opaque, ungrounded Vec for an ANN probe only. */
+export function composeStructuralGist(space, parts) {
+    const foldedParts = [];
+    for (const part of parts) {
+        if (part.len <= 0)
+            continue;
+        const direction = copy(part.v);
+        normalize(direction);
+        const scaled = zeros(space.D);
+        addInto(scaled, direction, Math.sqrt(part.len));
+        foldedParts.push({ tree: sema(scaled), len: part.len });
+    }
+    if (foldedParts.length === 0)
+        return zeros(space.D);
+    const rawRoot = riverFoldRaw(space, foldedParts);
+    const result = copy(rawRoot.tree.v);
+    normalize(result);
+    return result;
+}
 /** Plain bytes→tree (identical to capability-less {@link bytesToTree}) that
  *  also RETURNS its pyramid, reusing `prev` — the pyramid of a PROPER
  *  prefix of `bytes` (caller guarantees content match and

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

@@ -1,5 +1,181 @@
 import type { DerivationStep } from "./graph-search.js";
-import type { AncestorReach, Attention, AttentionRead, DFMode, MindContext, Region, RegionVote, SaturationInfo } from "./types.js";
+import type { AncestorReach, Attention, AttentionRead, DFMode, MindContext, Region, RegionVote, SaturationInfo, SaturationStop } from "./types.js";
+import { type StructuralPart } from "../geometry.js";
+import { type JunctionSynonymSides } from "./junction.js";
+/** How the newly-added graded junction ladder (junction.ts / attention.ts's
+ *  {@link CrossRegionTier}) is reported on a `junctionVotes` entry.  The
+ *  instrumentation spec this implements predates that ladder and only knew
+ *  two tiers ("exact" | "synonym"); with the richer `CrossRegionTier` now
+ *  the real shape of a junction vote's provenance, `junctionVotes[].tier`
+ *  reports it DIRECTLY (the tier as-is: "exact" | "single-synonym" |
+ *  "double-synonym" | "structural-resonance") rather than collapsing every
+ *  non-exact tier into a lossy "synonym" bucket — the whole point of
+ *  exposing `tier` here is to let a debugger tell a halo-sibling
+ *  substitution apart from a structural-resonance ANN guess, which the
+ *  spec's original two-value type cannot do. */
+export type ClimbConsensusJunctionTier = CrossRegionTier;
+export type RegionOutcome = "voted" | "no-ann-hit" | "no-structural-reach" | "saturated-abstention" | "nonpositive-df-weight" | "contrastive-margin-rejection";
+export interface ConsensusRegionTrace {
+    index: number;
+    source: "perceived" | "recognised";
+    span: [number, number];
+    chunk: boolean;
+    known: boolean;
+    canonicalId?: number;
+    canonicalUsable: boolean;
+    canonicalFailed: boolean;
+    annQueried: boolean;
+    annHitsReturned: number;
+    annHitsExamined: number;
+    selected?: {
+        source: "canonical" | "ann";
+        node: number;
+        rank?: number;
+        score: number;
+        fallback?: "orphan" | "saturated-tie";
+    };
+    reachNode?: number;
+    outcome: RegionOutcome;
+    idf?: number;
+    dfWeight?: number;
+    contrastiveMargin?: number;
+    contrastiveNoiseFloor?: number;
+    mutualWeight?: number;
+    voteWeightPerRoot?: number;
+    focusWeightPerRoot?: number;
+    ordinaryVoteProduced: boolean;
+    superseded: boolean;
+}
+export interface ConsensusReachTrace {
+    node: number;
+    roots: number[];
+    contextsReached: number;
+    saturated: boolean;
+    saturation?: SaturationStop;
+}
+export type AnchorRejectionReason = "below-natural-break" | "below-consensus-floor" | "leading-saturation";
+export interface ConsensusAnchorTrace {
+    anchor: number;
+    rank: number;
+    pooledVote: number;
+    idfVote: number;
+    candidateBreadth: number;
+    contributingVotes: number;
+    contributingEvidence: number;
+    breadth: number;
+    contributingSpans: Array<[number, number]>;
+    clusters: number;
+    commit: {
+        status: "root" | "overlap" | "rejected";
+        dominant: boolean;
+        passesNaturalBreak?: boolean;
+        passesConsensusFloor?: boolean;
+        pastLeadingSaturation?: boolean;
+        rejectionReasons: AnchorRejectionReason[];
+    };
+}
+export interface JunctionVoteTrace {
+    container: number;
+    span: [number, number];
+    roots: number[];
+    sourceRegionIndices: number[];
+    explainedAwayRegionIndices: number[];
+    absorbed: number;
+    tier?: ClimbConsensusJunctionTier;
+}
+export interface ClimbConsensusData {
+    version: 1;
+    cache: {
+        hit: boolean;
+        detailAvailable: boolean;
+    };
+    config: {
+        annK: number;
+        crossRegionProbeLimit: number;
+        mode: DFMode;
+        corpusN?: number;
+        dimension?: number;
+        hubBound?: number;
+        estimatorNoise?: number;
+        naturalBreak?: number;
+        consensusFloor?: number;
+    };
+    candidates: {
+        perceived: number;
+        recognised: number;
+        total: number;
+    };
+    regions?: ConsensusRegionTrace[];
+    reaches?: ConsensusReachTrace[];
+    crossRegion?: {
+        eligibleRegions: number;
+        maximalRegions: number;
+        probeLimit: number;
+        probesAttempted: number;
+        junctionVotes: JunctionVoteTrace[];
+        supersededOrdinaryVotes: number;
+    };
+    saturation?: {
+        regionIntervals: Array<{
+            start: number;
+            end: number;
+        }>;
+        hasLeading: boolean;
+        leadingEnd: number;
+    };
+    pooling?: {
+        inputVotes: number;
+        eligibleVotes: number;
+        saturationMaskedVotes: number;
+    };
+    anchors?: ConsensusAnchorTrace[];
+    result: AttentionRead;
+}
+/** The mutable collection buffers threaded through one traced consensus
+ *  climb — allocated exactly once, in {@link computeAttention}, only when
+ *  `ctx.trace` is set.  Every field mirrors a `ClimbConsensusData` array/map,
+ *  built incrementally as the pipeline runs so commit-time decisions (in
+ *  particular) are recorded LIVE, not reconstructed afterward. */
+interface TraceDraft {
+    perceivedCount: number;
+    regions: ConsensusRegionTrace[];
+    crossRegionJunctionVotes: JunctionVoteTrace[];
+    crossRegionSummary?: {
+        eligibleRegions: number;
+        maximalRegions: number;
+        probeLimit: number;
+        probesAttempted: number;
+    };
+    supersededOrdinaryVotes: number;
+    saturation?: {
+        regionIntervals: Array<{
+            start: number;
+            end: number;
+        }>;
+        hasLeading: boolean;
+        leadingEnd: number;
+    };
+    pooling?: {
+        inputVotes: number;
+        eligibleVotes: number;
+        saturationMaskedVotes: number;
+    };
+    anchors: ConsensusAnchorTrace[];
+}
+/** The config/corpus context {@link traceAttention} needs to fill in
+ *  `ClimbConsensusData.config` and `.result` at whichever exit fires —
+ *  threaded down from {@link computeAttention} rather than re-derived, so
+ *  every emission point reports the SAME numbers the real climb used. */
+interface ClimbConsensusCfg {
+    k: number;
+    mode: DFMode;
+    perceivedCount: number;
+    totalRegions: number;
+    N?: number;
+    reachMemo?: ReadonlyMap<number, AncestorReach>;
+    naturalBreak?: number;
+    consensusFloor?: number;
+}
 /** Climb the query's perceived byte regions up the structural DAG via
  *  resonance, pool the evidence, and return only the ROOT points of
  *  attention — those that cleared commitVotes' significance floor. */
@@ -19,7 +195,7 @@ export declare function climbAttention(ctx: MindContext, query: Uint8Array, k: n
 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[];
-export declare function voteRegions(ctx: MindContext, query: Uint8Array, regions: readonly Region[], k: number, mode: DFMode, N: number, reachMemo?: Map<number, AncestorReach>): Promise<{
+export declare function voteRegions(ctx: MindContext, query: Uint8Array, regions: readonly Region[], k: number, mode: DFMode, N: number, reachMemo?: Map<number, AncestorReach>, td?: TraceDraft): Promise<{
     votes: RegionVote[];
     saturated: boolean[];
     voters: Array<{
@@ -40,7 +216,7 @@ export declare function voteRegions(ctx: MindContext, query: Uint8Array, regions
  *  merely logs alongside it.  `votesIdf`/`support` are the same two
  *  read-outs {@link commitVotes} always gated on; only how they accumulate
  *  changed. */
-export declare function poolVotes(ctx: MindContext, regionVotes: readonly RegionVote[], sat: SaturationInfo, N: number): {
+export declare function poolVotes(ctx: MindContext, regionVotes: readonly RegionVote[], sat: SaturationInfo, N: number, td?: TraceDraft): {
     votes: Map<number, number>;
     votesIdf: Map<number, number>;
     support: Map<number, {
@@ -70,7 +246,7 @@ export declare function commitVotes(ctx: MindContext, pooled: {
     id: number;
     score: number;
     w: number;
-} | null>, N: number): AttentionRead;
+} | null>, N: number, td?: TraceDraft, cfg?: ClimbConsensusCfg): AttentionRead;
 export declare function detectSaturated(ctx: MindContext, regions: ReadonlyArray<{
     start: number;
     end: number;
@@ -78,6 +254,56 @@ export declare function detectSaturated(ctx: MindContext, regions: ReadonlyArray
 }>, saturated: ReadonlyArray<boolean>): SaturationInfo;
 export declare function canonicalChunkId(ctx: MindContext, regionBytes: Uint8Array, N: number, reachMemo?: Map<number, AncestorReach>): number | null;
 export declare function naturalBreak(votes: number[]): number;
+export type CrossRegionTier = "exact" | "single-synonym" | "double-synonym" | "structural-resonance";
+export interface StructuralVariant {
+    left: StructuralPart;
+    right: StructuralPart;
+    kind: "exact-exact" | "left-synonym" | "right-synonym" | "double-synonym";
+    semanticConfidence: number;
+    leftSiblingId?: number;
+    rightSiblingId?: number;
+}
+export interface StructuralResonanceProposal {
+    id: number;
+    annScore: number;
+    semanticConfidence: number;
+    effectiveScore: number;
+    variant: StructuralVariant["kind"];
+    leftSiblingId?: number;
+    rightSiblingId?: number;
+}
+/** Build, bound and order every mandatory structural variant (§7-8): the
+ *  exact/exact composition is always kept; up to `ctx.cfg.haloQueryK`
+ *  synonym variants (single- and double-synonym combined, one shared
+ *  budget) are appended, ordered by confidence, then kind, then sibling id. */
+export declare function buildStructuralVariants(ctx: MindContext, ra: Region, rb: Region, sides: JunctionSynonymSides): {
+    variants: StructuralVariant[];
+    exactLeft: StructuralPart;
+    exactRight: StructuralPart;
+};
+/** The final approximate tier: compose every retained structural variant,
+ *  ANN-query each, merge proposals by candidate id, and validate the winner
+ *  through the SAME structural gates every other tier answers to (saturation,
+ *  roots, IDF, contrastive margin).  Returns null when nothing survives. */
+export declare function structuralResonance(ctx: MindContext, query: Uint8Array, ra: Region, rb: Region, sides: JunctionSynonymSides, k: number, N: number, reachMemo: Map<number, AncestorReach>, 
+/** Each side's OWN individual climb roots (from voteRegions), when it cast
+ *  one — the self-evidence backstop structural-resonance needs and the
+ *  exact tier gets for free from literal byte containment (§11's whole
+ *  premise: recover a JOINT context neither side votes for alone).  A
+ *  candidate whose reach is exactly one side's own conclusion is not new
+ *  evidence of a joint whole; it is that side's resonance rediscovering
+ *  itself through a synthetic gist still dominated by its own direction. */
+ownRootsA: readonly number[] | undefined, ownRootsB: readonly number[] | undefined): Promise<{
+    proposal: StructuralResonanceProposal;
+    reach: AncestorReach;
+    idf: number;
+} | null>;
+/** Emit the "climbConsensus" step — the human-readable note this always
+ *  produced, now paired (when `ctx.trace` and `cfg` are both present) with
+ *  the structured {@link ClimbConsensusData} payload on the SAME step's
+ *  `data` field.  Every exit of {@link computeAttention} funnels through
+ *  here, so instrumentation and the existing rationale text can never drift
+ *  apart — see the instrumentation spec's §9 "every exit path". */
 export declare function traceAttention(ctx: MindContext, regions: ReadonlyArray<{
     start: number;
     end: number;
@@ -85,4 +311,5 @@ export declare function traceAttention(ctx: MindContext, regions: ReadonlyArray<
     id: number;
     score: number;
     w: number;
-} | null>, roots: ReadonlyArray<Attention>, steps?: ReadonlyArray<DerivationStep>): void;
+} | null>, roots: ReadonlyArray<Attention>, steps?: ReadonlyArray<DerivationStep>, td?: TraceDraft, cfg?: ClimbConsensusCfg, ranked?: ReadonlyArray<Attention>): void;
+export {};