@hviana/sema 0.2.6 → 0.2.8

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

@@ -0,0 +1,23 @@
+import type { MindContext } from "./types.js";
+/** The connector that belongs BETWEEN two adjacent results — the graded
+ *  junction ladder described in the module note above.  Returns null when
+ *  the graph holds no evidence that the two ever ran together. */
+export declare function bridge(ctx: MindContext, left: Uint8Array, right: Uint8Array, interiorAllowance?: number): Promise<Uint8Array | null>;
+/** Join two spans with the learnt connector between them, when one exists —
+ *  the composition step every out-of-search assembly (multi-topic fusion,
+ *  CAST's substitution and comparison) shares.  A miss joins the pieces BARE
+ *  and is never silent: it emits the same `bridgeMiss` trace step everywhere,
+ *  so a degraded join is visible in the rationale regardless of which
+ *  mechanism paid it.  (The in-search connector splice in graph-search.ts is
+ *  the same concept inside the deduction, where the join is a costed rule.) */
+export declare function joinWithBridge(ctx: MindContext, left: Uint8Array, right: Uint8Array): Promise<Uint8Array>;
+/** The pivot a produced answer bridges through: the longest UNCONSUMED learnt
+ *  CONTEXT (a node bearing a continuation edge) whose bytes `answer` literally
+ *  contains.  Candidates are gathered by resonating the answer's sub-regions
+ *  (breadth-first, leaves skipped, probes capped by branch count), then
+ *  confirmed by exact byte containment — a near-resonance alone never hops. */
+export declare function pivotInto(ctx: MindContext, answer: Uint8Array, consumed: ReadonlySet<number>): Promise<number | null>;
+export declare function meaningOf(ctx: MindContext, bytes: Uint8Array, anchors: ReadonlyArray<{
+    name: string;
+    form: Uint8Array;
+}>): Promise<string | null>;

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

@@ -0,0 +1,15 @@
+import type { MindContext } from "./types.js";
+import type { DerivationStep } from "./graph-search.js";
+import type { RationaleItem } from "./rationale.js";
+export declare function rItem(bytes: Uint8Array, role?: string, node?: number, span?: [number, number]): RationaleItem;
+export declare function rNode(ctx: MindContext, id: number, role?: string, score?: number): RationaleItem;
+export declare function rDeriv(ctx: MindContext, it: DerivationStep["conclusion"], role?: string): RationaleItem;
+/** The standard FALL-THROUGH closer every self-gating mechanism ends with:
+ *  close the open scope with no outputs and the reason, and return null so
+ *  the caller can `return fail("…")` in one expression.  `t` is the scope an
+ *  enclosing `ctx.trace?.enter(...)` returned (undefined when not tracing). */
+export declare function traceFail(t: {
+    done(outputs: RationaleItem[], note?: string): void;
+} | undefined): (note: string) => null;
+export declare const MOVE_NOTE: Record<string, string>;
+export declare function traceDerivation(ctx: MindContext, steps: ReadonlyArray<DerivationStep>): void;

package/dist/src/mind/trace.js

@@ -0,0 +1,73 @@
+// trace.ts — trace instrumentation + persistence (Section 9 of the mind).
+//
+//   rItem, rNode, rDeriv — build RationaleItems from bytes/nodes/derivations
+//   traceDerivation        — trace a full derivation proof tree
+//   MOVE_NOTE              — human-readable names for each derivation move
+import { read } from "./primitives.js";
+import { decodeText } from "./rationale.js";
+export function rItem(bytes, role, node, span) {
+    return {
+        text: decodeText(bytes),
+        role,
+        node: node ?? undefined,
+        span,
+    };
+}
+export function rNode(ctx, id, role, score) {
+    return {
+        text: decodeText(read(ctx, id)),
+        node: id,
+        role,
+        score,
+    };
+}
+export function rDeriv(ctx, it, role) {
+    const text = it.bytes
+        ? decodeText(it.bytes)
+        : it.node !== undefined
+            ? decodeText(read(ctx, it.node))
+            : it.kind === "cover"
+                ? `cover@${it.span[0]}`
+                : `[${it.span[0]},${it.span[1]})`;
+    return { text, role: role ?? it.kind, node: it.node, span: it.span };
+}
+/** The standard FALL-THROUGH closer every self-gating mechanism ends with:
+ *  close the open scope with no outputs and the reason, and return null so
+ *  the caller can `return fail("…")` in one expression.  `t` is the scope an
+ *  enclosing `ctx.trace?.enter(...)` returned (undefined when not tracing). */
+export function traceFail(t) {
+    return (note) => {
+        t?.done([], note);
+        return null;
+    };
+}
+export const MOVE_NOTE = {
+    "follow-edge": "follow a learned continuation edge — 'what follows what'",
+    "concept-hop": "jump a concept (halo) link — a synonym's edge",
+    "voice": "emit the asker's own wording for this form (articulation)",
+    "ground": "a chain reached its terminal answer",
+    "splice-connector": "splice a learnt connector between two rewrites",
+    "split": "cut a span at a sub-leaf form boundary so a form can be reached",
+    "fuse": "fuse adjacent fragments toward a deeper learned form",
+    "recompose": "recompose fused parts into a learned whole that leads on",
+    "bridge": "advance the cover frontier across this span",
+    "pool-vote": "pool independent regions' evidence for a shared anchor (sum, not shortest path)",
+    "axiom": "a seed: a perceived leaf, recognised form, or computed result",
+    "step": "a derivation step",
+};
+export function traceDerivation(ctx, steps) {
+    const t = ctx.trace;
+    if (!t)
+        return;
+    const indexOfOrder = new Map();
+    for (const s of steps) {
+        const note = MOVE_NOTE[s.move] ?? s.move;
+        const deps = s.producers
+            .map((o) => indexOfOrder.get(o))
+            .filter((x) => x !== undefined);
+        const premises = s.premises.map((p) => rDeriv(ctx, p));
+        const conclusion = [rDeriv(ctx, s.conclusion)];
+        const index = t.step(s.move, premises, conclusion, s.cost > 0 ? `${note} (cost ${s.cost})` : note, deps.length > 0 ? deps : undefined);
+        indexOfOrder.set(s.order, index);
+    }
+}

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

@@ -0,0 +1,113 @@
+import { Vec } from "../vec.js";
+import type { AncestorReach, MindContext } from "./types.js";
+/** Climb the structural DAG from a node to its edge-bearing ancestor contexts.
+ *  Ascent stops at hub nodes (parents > √N) — their reach is non-discriminative.
+ *  When the start node has no structural parents, climbs from containment parents
+ *  (sub-span flat branches inheriting their chunks' context).
+ *
+ *  `memo`, when given, caches whole climbs by start id for the duration of ONE
+ *  query (the store is read-only while a query is in flight, so a climb is a
+ *  pure function of the id).  The consensus pipeline climbs the SAME anchors
+ *  repeatedly — regions sharing a chunk, and canonicalChunkId probing each
+ *  chunk's prefixes — so without the memo every repeat re-pays the full
+ *  fan-out reads. */
+export declare function edgeAncestors(ctx: MindContext, id: number, contextCount: number, memo?: Map<number, AncestorReach>): AncestorReach;
+/** Convenience: forward edges of a node. */
+export declare function nextOf(ctx: MindContext, id: number): number[];
+/** Convenience: reverse edges of a node. */
+export declare function prevOf(ctx: MindContext, id: number): number[];
+/** The uniform-expectation floor on a byte atom's corpus commonality: N
+ *  learnt contexts, each at least one perception chunk of up to W of the 256
+ *  possible byte values, contain a given atom in ≥ N·W/256 contexts on
+ *  average.  An atom's TRUE containment is unmeasurable (atoms carry no
+ *  kid/contain links by construction), so this floor is the honest stand-in:
+ *  derived entirely from the corpus scale N, the perception window W, and
+ *  the alphabet size — never tuned. */
+export declare function atomReach(ctx: MindContext, contextCount: number): number;
+/** Whether a byte atom is a hub at this corpus scale — its commonality floor
+ *  {@link atomReach} exceeds the hub bound √N.  Below it (small stores) an
+ *  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;
+/** 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.
+ *  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).  `hasHalo` is not cached: it's a single
+ *  indexed point probe per candidate, and the candidates that reach this
+ *  check have already been filtered by hasNext above in edgeAncestors. */
+export declare function leadsSomewhere(ctx: MindContext, id: number): boolean;
+/** The structural IDF read of ONE node: how many distinct learnt contexts
+ *  its containment/edge climb reaches, or Infinity when it reaches none or
+ *  saturates (no usable identity evidence).  The number every
+ *  discriminative-vs-scaffolding decision derives from — paired with the
+ *  half-dominance convention (geometry.dominates(reach, N)): content
+ *  reaching a corpus MINORITY of contexts discriminates (an entity, a
+ *  filler); content reaching a majority is frame scaffolding. */
+export declare function reachOf(ctx: MindContext, id: number, contextCount: number, memo?: Map<number, AncestorReach>): number;
+/** The corpus scale N — the count of DISTINCT learnt contexts, floored at 2
+ *  so its derived readings (ln N in the consensus floor, √N in the hub bound)
+ *  stay meaningful on a near-empty store.  The one definition every consumer
+ *  of "how big is this corpus?" reads. */
+export declare function corpusN(ctx: MindContext): number;
+/** The hub bound √N itself (≥ 2 always, since N is floored at 2) — for
+ *  consumers that pass it to the store's LIMITed reads instead of capping a
+ *  materialised list.  {@link hubCap} is the list-side reading of the same
+ *  convention. */
+export declare function hubBound(ctx: MindContext): number;
+/** Cap a candidate list at the hub bound √N (insertion order) — the ONE
+ *  fan-out convention every walk and disambiguation uses (see HOW_IT_WORKS
+ *  §8.6).  A node connected to more than √N others is a hub whose individual
+ *  connections carry ~no discriminative information; materialising or scoring
+ *  them all would make single decisions scale with the corpus. */
+export declare function hubCap<T>(ctx: MindContext, ids: readonly T[]): readonly T[];
+/** Whether `descendant` lies within `ancestor`'s subtree — a structural DAG
+ *  relation read off the hash-consed `kids` lists, by a bounded explicit-stack
+ *  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;
+/** 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
+ *  caller needs: `true` keeps the first-seen leader on a tie (`>`), the
+ *  default lets a later equal score take it (`>=`). */
+export declare function argmaxBy<T>(items: Iterable<T>, scoreOf: (item: T) => number, threshold: number, strict?: boolean): {
+    item: T;
+    score: number;
+} | null;
+export declare function argmaxCosine<T>(query: Vec, items: Iterable<T>, vecOf: (item: T) => Vec | null | undefined, threshold: number, strict?: boolean): {
+    item: T;
+    score: number;
+} | null;
+/** The guided-or-first continuation of a node, as answer-shaped bytes source:
+ *  chooseNext under the response guide, falling back to the FIRST-inserted
+ *  edge — the one no-guide convention chooseNext, project() and the search's
+ *  formRules all share.  undefined when the node has no continuation. */
+export declare function guidedFirst(ctx: MindContext, id: number): number | undefined;
+export declare function guidedNext(ctx: MindContext, node: number): number | undefined;
+/** Disambiguate among a node's learnt continuations by distributional
+ *  support.  NOTE the `guide` contract: its VALUE is deliberately unused —
+ *  only its PRESENCE gates disambiguation (a null guide means no query is in
+ *  flight, so structural walkers keep plain first-edge behaviour).  The
+ *  gist-cosine of short answer candidates against a query guide is dominated
+ *  by accidental byte-pattern correlations, not semantic relatedness, so the
+ *  evidence consulted is structural: each candidate's reverse-edge support
+ *  count (see below).  Contrast {@link chooseAmong}, the REVERSE-direction
+ *  disambiguator, whose candidates are whole learnt contexts — long enough
+ *  that their perceived gists ARE semantically meaningful — and which
+ *  therefore scores by guide cosine.  The two directions consult different
+ *  halves of the evidence on purpose. */
+export declare function chooseNext(ctx: MindContext, id: number, guide?: Vec | null): number | undefined;
+/** The perceived gist of a candidate node, through the session gist cache.
+ *  Re-gisting a candidate is a full river fold of its bytes — the measured
+ *  recall bottleneck (a hub context offers up to √N continuations, EACH
+ *  re-perceived per pick).  A node's bytes are immutable and perception is
+ *  pure, so the cached gist is valid for the store's lifetime.  Exported for
+ *  every "score node ids against a guide" decision (chooseAmong here, the
+ *  bridge's junction pick) so they share ONE cache and one convention. */
+export declare function candidateGist(ctx: MindContext, c: number): Vec | null;
+export declare function chooseAmong(ctx: MindContext, candidates: readonly number[], guide: Vec): {
+    id: number;
+    score: number;
+};