@hviana/sema 0.4.2 → 0.4.3

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

@@ -0,0 +1,414 @@
+import type { DerivationStep } from "./graph-search.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";
+import type { Vec } from "../vec.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";
+/** The best DIFFERENT-conclusion rival the contrastive-margin gate found
+ *  while scanning an ordinary (approximate) region's ANN hits — spec §1.
+ *  Its roots/saturation/contextsReached are already available through
+ *  `reaches` (serialiseReaches) for `node`; not duplicated here. */
+export interface ConsensusContrastiveRivalTrace {
+    node: number;
+    rank: number;
+    score: number;
+}
+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;
+    contrastiveRival?: ConsensusContrastiveRivalTrace;
+    mutualWeight?: number;
+    voteWeightPerRoot?: number;
+    focusWeightPerRoot?: number;
+    ordinaryVoteProduced: boolean;
+    superseded: boolean;
+}
+export interface ConsensusReachTrace {
+    node: number;
+    roots: number[];
+    contextsReached: number;
+    saturated: boolean;
+    saturation?: SaturationStop;
+    /** Nodes the climb processed — see {@link AncestorReach.visited}.  Absent
+     *  on payloads recorded before this field existed. */
+    visited?: number;
+    /** Maximum ascent distance — see {@link AncestorReach.maxDepth}. */
+    maxDepth?: number;
+}
+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;
+    /** Zero-based index into `crossRegion.probes` — the probe this vote was
+     *  produced from (spec §8). */
+    probe: number;
+    confidence: number;
+    /** "Evidence bytes" — the container-coverage byte count (the existing
+     *  `bestCov` variable at the push site). */
+    evidenceBytes: number;
+    mutualWeight: number;
+    voteWeightPerRoot: number;
+}
+/** Whether one DAG/synonym tier attempt was even made for a probe, and how
+ *  many candidate containers it returned — spec §2/§3. */
+export interface CrossRegionTierAttemptTrace {
+    attempted: boolean;
+    candidatesReturned: number;
+}
+/** Aggregate outcome of the container-selection loop for a DAG/synonym tier
+ *  that returned at least one container — spec §4.  Only aggregate counts
+ *  and the final outcome are recorded, never every candidate. */
+export interface CrossRegionStructuralTrace {
+    tier: "exact" | "single-synonym" | "double-synonym";
+    selfEvidenceRejected: number;
+    contradictionRejected: number;
+    passedGuards: number;
+    selectedNode?: number;
+    outcome: "all-rejected" | "saturated" | "no-roots" | "nonpositive-idf" | "accepted";
+}
+/** One retained structural-resonance variant that actually issued its own
+ *  ANN query — spec §5. */
+export interface StructuralResonanceVariantTrace {
+    kind: StructuralVariant["kind"];
+    semanticConfidence: number;
+    leftSiblingId?: number;
+    rightSiblingId?: number;
+    annHitsReturned: number;
+}
+/** One merged structural-resonance proposal actually examined via
+ *  edgeAncestors — spec §5.  Retains node/variant/scores, but NOT
+ *  roots/saturation/contextsReached/idf (already in `reaches`). */
+export interface StructuralResonanceCandidateTrace {
+    node: number;
+    variant: StructuralVariant["kind"];
+    leftSiblingId?: number;
+    rightSiblingId?: number;
+    annScore: number;
+    semanticConfidence: number;
+    effectiveScore: number;
+    outcome: "saturated" | "no-roots" | "nonpositive-idf" | "same-as-endpoint" | "same-as-selected" | "selected" | "contrastive-rival";
+}
+export interface StructuralResonanceTrace {
+    variantBudget: number;
+    variants: StructuralResonanceVariantTrace[];
+    mergedProposals: number;
+    examined: StructuralResonanceCandidateTrace[];
+    contrastiveMargin?: number;
+    noiseFloor: number;
+    outcome: "ineligible" | "empty" | "no-valid-proposal" | "margin-rejected" | "accepted";
+    ineligibleReasons?: Array<"between-region" | "not-both-strong" | "not-both-known" | "gap-too-large">;
+}
+/** One cross-region pair the ladder actually probed — spec §2.  Exactly one
+ *  of these is pushed per pair that incremented `probes`. */
+export interface CrossRegionProbeTrace {
+    leftRegionIndex: number;
+    rightRegionIndex: number;
+    betweenRegionIndices: number[];
+    exact: CrossRegionTierAttemptTrace;
+    singleSynonym: CrossRegionTierAttemptTrace;
+    doubleSynonym: CrossRegionTierAttemptTrace;
+    structural?: CrossRegionStructuralTrace;
+    resonance?: StructuralResonanceTrace;
+    outcome: "accepted" | "structural-rejected" | "resonance-ineligible" | "resonance-rejected";
+}
+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;
+        probes: CrossRegionProbeTrace[];
+        stopReason: "insufficient-regions" | "probe-limit" | "pairs-exhausted";
+    };
+    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;
+        stopReason?: "insufficient-regions" | "probe-limit" | "pairs-exhausted";
+    };
+    crossRegionProbes: CrossRegionProbeTrace[];
+    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. */
+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, 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[];
+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<{
+        id: number;
+        score: number;
+        w: number;
+    } | null>;
+}>;
+/** The consensus vote as EVIDENCE POOLING, not shortest path: each surviving
+ *  region is an axiom; it contributes to every root it climbed to (or, for a
+ *  terminal answer node, to the contexts that lead to it) by a `combine:
+ *  "sum"` rule, so independent regions corroborating the same anchor ADD
+ *  rather than compete to be the cheapest route (see {@link Rule.combine} in
+ *  derive/src/deduction.ts).  Run through the very engine {@link
+ *  GraphSearch} covers with — `lightestDerivation` — so a pooled-evidence
+ *  decision is, like a followed edge or a spliced connector, one weighted
+ *  rule of the SAME deduction system, not a separate hand-rolled tally that
+ *  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, td?: TraceDraft): {
+    votes: Map<number, number>;
+    votesIdf: Map<number, number>;
+    support: Map<number, {
+        start: number;
+        end: number;
+        w: number;
+    }>;
+    /** 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: {
+    votes: Map<number, number>;
+    votesIdf: Map<number, number>;
+    support: Map<number, {
+        start: number;
+        end: number;
+        w: number;
+    }>;
+    regionSupport: Map<number, number>;
+    regionSpans: Map<number, Array<[number, number]>>;
+    steps: DerivationStep[];
+}, sat: SaturationInfo, regions: readonly Region[], regionVoter: ReadonlyArray<{
+    id: number;
+    score: number;
+    w: number;
+} | null>, N: number, td?: TraceDraft, cfg?: ClimbConsensusCfg): AttentionRead;
+export declare function detectSaturated(ctx: MindContext, regions: ReadonlyArray<{
+    start: number;
+    end: number;
+    chunk?: boolean;
+}>, 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;
+}
+/** A sibling gist cached in the shared, climb-wide memo alongside the
+ *  COMPLETE stored byte length it was reconstructed from — the length is
+ *  required to tell whether a cache hit is still valid under a probe whose
+ *  `maxSiblingBytes` bound is smaller than the one that first cached it. */
+interface CachedSiblingGist {
+    gist: Vec;
+    length: 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.
+ *  Variant selection is entirely lightweight (see {@link
+ *  buildStructuralVariantSpecs}); a sibling's bytes are read and perceived
+ *  only for specs actually retained, and at most once per sibling id per
+ *  climb via `siblingGistMemo`. */
+export declare function buildStructuralVariants(ctx: MindContext, ra: Region, rb: Region, sides: JunctionSynonymSides, siblingGistMemo: Map<number, CachedSiblingGist>): {
+    variants: StructuralVariant[];
+    exactLeft: StructuralPart;
+    exactRight: StructuralPart;
+};
+export declare function structuralResonance(ctx: MindContext, query: Uint8Array, ra: Region, rb: Region, sides: JunctionSynonymSides, siblingGistMemo: Map<number, CachedSiblingGist>, 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, trace?: StructuralResonanceTrace): 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;
+}>, regionVoter: ReadonlyArray<{
+    id: number;
+    score: number;
+    w: number;
+} | null>, roots: ReadonlyArray<Attention>, steps?: ReadonlyArray<DerivationStep>, td?: TraceDraft, cfg?: ClimbConsensusCfg, ranked?: ReadonlyArray<Attention>): void;
+export {};