@hviana/sema 0.2.6 → 0.2.7

package/dist/src/mind/canonical.js

@@ -0,0 +1,88 @@
+// canonical.ts — THE canonical-segmentation convention, defined once.
+//
+// The store's canonical reading of a byte stream — "the id of each single-byte
+// leaf, chained into flat branches" — is a WRITE/READ CONTRACT split across
+// four consumers that previously each re-implemented the chaining loop:
+//
+//   WRITE side (training):
+//     • learning.indexSubSpans — interns sliding windows of the two
+//       {@link canonicalWindows} lengths over the stream's leaf ids;
+//     • learning.deposit — interns the WHOLE stream as one flat branch
+//       (via {@link leafIdPrefix}) so every deposit has a byte-level identity.
+//   READ side (inference):
+//     • recognition's canonical pass — chains leaf ids from every position and
+//       probes each growing prefix as a flat branch, up to {@link chainReach};
+//     • attention.canonicalChunkId — reads a chunk's window of leaf ids
+//       (via {@link leafIdRun}) and probes its prefixes for the best anchor.
+//   (geometry.knownPrefixLength is the same convention below the store layer,
+//    expressed through injected `leafAt`/`lookup` capabilities — it cannot
+//    import this module without inverting the dependency spine, so its header
+//    cross-references this file instead.)
+//
+// If the write side's windows or the read side's reach ever change, they must
+// change HERE — a drift between them silently makes recognition stop finding
+// what training indexed, which no type checker catches.
+/** The two sliding-window lengths the WRITE side interns over a stream's leaf
+ *  ids: W−1 and W (the river's grouping quantum and its off-by-one neighbour,
+ *  so a form straddling a group boundary is reachable from either cut). */
+export function canonicalWindows(W) {
+    return [W - 1, W];
+}
+/** The READ side's chain reach: how many leaf ids a canonical chain may grow
+ *  to from one position — W², the deepest two-level composite the write side's
+ *  windows can spell. */
+export function chainReach(W) {
+    return W * W;
+}
+/** The id of the single-byte leaf at position `p`, or null when that byte was
+ *  never interned. */
+export function leafIdAt(ctx, bytes, p) {
+    return ctx.store.findLeaf(bytes.subarray(p, p + 1));
+}
+/** The leaf ids of the window `[from, to)`, or null the moment ANY byte in it
+ *  is unknown — the all-or-nothing read {@link canonicalChunkId} anchors on. */
+export function leafIdRun(ctx, bytes, from, to) {
+    const ids = [];
+    for (let i = from; i < to; i++) {
+        const lid = leafIdAt(ctx, bytes, i);
+        if (lid === null)
+            return null;
+        ids.push(lid);
+    }
+    return ids;
+}
+/** The leaf ids of the LONGEST KNOWN PREFIX of `bytes` — stops at the first
+ *  unknown byte and returns what it has (possibly empty).  The caller decides
+ *  what a partial prefix means (deposit only interns the whole-stream flat
+ *  branch when the prefix covers everything). */
+export function leafIdPrefix(ctx, bytes) {
+    const ids = [];
+    for (let i = 0; i < bytes.length; i++) {
+        const lid = leafIdAt(ctx, bytes, i);
+        if (lid === null)
+            break;
+        ids.push(lid);
+    }
+    return ids;
+}
+/** The canonical W-window node ids of a byte stream, offset → id — the
+ *  CONTENT-ADDRESSED IDENTITY of every W-sized slice, under which any content
+ *  two deposits share IS the same node (hash-consing paid the comparison at
+ *  write time).  The read side of the {@link canonicalWindows} contract asked
+ *  at every offset: a window over unknown bytes, or one never interned as a
+ *  flat branch, has no identity and is skipped.  Confluence's meet and CAST's
+ *  frame detection both read shared/common content through this — never
+ *  through a byte scan. */
+export function windowIds(ctx, bytes) {
+    const W = ctx.space.maxGroup;
+    const out = new Map();
+    for (let off = 0; off + W <= bytes.length; off++) {
+        const ids = leafIdRun(ctx, bytes, off, off + W);
+        if (ids === null)
+            continue;
+        const wid = ctx.store.findBranch(ids);
+        if (wid !== null)
+            out.set(off, wid);
+    }
+    return out;
+}

package/dist/src/mind/graph-search.d.ts

@@ -0,0 +1,285 @@
+import type { Store } from "../store.js";
+import type { GraphSearchHost } from "./types.js";
+/** A recognised form: a span of the query that names a node already in the
+ *  store. `payload` is that node id. */
+export interface Site {
+    start: number;
+    end: number;
+    payload: number;
+}
+/** A perceived leaf of the query tree, carrying the node id it resolves to. */
+export interface Leaf {
+    start: number;
+    end: number;
+    bytes: Uint8Array;
+    node: number | null;
+}
+/** A COMPUTED span: the result of applying a manual rule (an extension's
+ *  operation — e.g. the `alu` extension's arithmetic) to a recognised stretch
+ *  of the query.  Every
+ *  bit of the intelligence — recognising the operator (literally or by
+ *  resonance), parsing the operands, evaluating the operation — is done by the
+ *  caller (src/mind/pipeline.ts), which hands the search the finished result span; the search
+ *  treats it exactly like any other recognised completion (a learned fact that
+ *  happens to be computed rather than stored).  `node` is the canonical id of
+ *  the result bytes when the store already holds them, else undefined. */
+export interface ComputedResult {
+    i: number;
+    j: number;
+    bytes: Uint8Array;
+    node?: number;
+}
+export type GItem = {
+    kind: "cover";
+    p: number;
+} | {
+    kind: "form";
+    i: number;
+    j: number;
+    node: number;
+    via: boolean;
+    /** Set when this form was born by RECOMPOSING rewritten parts into a deeper
+     *  learned whole (the fuse of ≥2 recognised completions that names an
+     *  edge-bearing node).  Its onward continuation is charged at MICRO, not
+     *  STEP: once parts are recomposed into a learned form, following that form
+     *  to its grounded answer is the recomposition completing — so the
+     *  consolidated, more-explanatory reading wins over leaving the parts split.
+     *  See {@link GraphSearch.fuse} and {@link GraphSearch.formRules}. */
+    rcmp?: boolean;
+} | {
+    kind: "out";
+    i: number;
+    j: number;
+    bytes: Uint8Array;
+    cover: boolean;
+    rec: boolean;
+    node?: number;
+    /** Set only for a {@link ComputedResult} axiom (an extension's derived
+     *  value, e.g. ALU arithmetic) — as opposed to a genuinely RECOGNISED
+     *  learned form.  Both set `rec: true` (a computation bridges the cover
+     *  exactly like a learned terminal answer), but they mean different
+     *  things for `i..j`'s WIDTH: a recognised form's query-span width is
+     *  real evidence of how much of the query's meaning it accounts for
+     *  (liftAnswer's half-dominance framing decision); a computed span's
+     *  width is operand digit-count, uncorrelated with meaning ("1000 - 421"
+     *  is wider than "15 * 7" only because the numbers are bigger, not
+     *  because subtraction is more "the point" of its query).  See
+     *  {@link liftAnswer}. */
+    computed?: boolean;
+};
+export declare const STEP = 1;
+export declare const CONCEPT = 10;
+export declare const PASS = 1000;
+/** The cheapest local cost in the ladder: a recognised completion bridging into
+ *  the cover.  Far below STEP, so connecting two recognised spans never disturbs
+ *  the ordering — and, being the minimum per-position cost, it is the per-byte
+ *  unit of the admissible search heuristic (see {@link GraphSearch.buildSearch}). */
+export declare const MICRO = 0.001;
+/** One chosen span of the cover, left to right.  `node` is the graph node the
+ *  span resolved to (when known) — for a recognised completion it is the chain's
+ *  terminal node, the foothold the bridge walks edges from. */
+export interface Seg {
+    i: number;
+    j: number;
+    bytes: Uint8Array;
+    rec: boolean;
+    node?: number;
+    /** See the `computed` field of the "out" {@link GItem} — set only for an
+     *  extension's derived value, never a genuinely recognised learned form. */
+    computed?: boolean;
+}
+/** One rule application inside the cover's lightest derivation — the FINEST
+ *  grain of Sema's core reasoning, one node of the adapted A*LD proof tree.  `move`
+ *  names which deduction rule fired (the reasoning act); `premises` and
+ *  `conclusion` are the items it consumed and produced, each rendered as a
+ *  positioned, possibly-node-bearing span; `cost` is the rule's local weight
+ *  (STEP for a learned edge, CONCEPT for a synonym hop, 0 for a free fuse, …);
+ *  `order` is its post-order position so a tracer can replay the proof in the
+ *  order it was built (premises before conclusion). */
+export interface DerivationStep {
+    order: number;
+    move: DerivationMove;
+    premises: DerivationItem[];
+    conclusion: DerivationItem;
+    cost: number;
+    /** The `order`s of the steps that produced this one's premises — the EXACT
+     *  data-flow edges of the proof tree (a `bridge` names the `ground` whose
+     *  `out` it crossed and the earlier `cover` it extended).  A premise that is
+     *  an axiom (a seed leaf/form/computed result, never a rule conclusion) has no
+     *  producer and contributes no edge, so this lists only the derived premises —
+     *  the finest dependency structure the inference holds. */
+    producers: number[];
+}
+/** A premise or conclusion of a {@link DerivationStep}, flattened from a {@link
+ *  GItem} into the fields a rationale cares about. */
+export interface DerivationItem {
+    kind: "cover" | "form" | "out";
+    /** `[i, j)` span for a form/out; for a cover item, `[p, p]`. */
+    span: [number, number];
+    /** The bytes an `out` carries (the only item kind that holds output bytes). */
+    bytes?: Uint8Array;
+    /** The graph node a form/out resolves to, when known. */
+    node?: number;
+}
+/** The reasoning act a derivation rule performs — the human name for which of
+ *  {@link GraphSearch}'s rules fired, recovered from the rule's premise/
+ *  conclusion shape (the rules carry no label, so this classifies by structure,
+ *  the single place that maps rule geometry to a name). */
+export type DerivationMove = "axiom" | "follow-edge" | "concept-hop" | "voice" | "ground" | "splice-connector" | "split" | "fuse" | "recompose" | "bridge" | "pool-vote" | "step";
+/** The lightest-derivation search over the Sema graph.  One instance binds the
+ *  store, `maxGroup` (the fusible span ceiling), and the canonical
+ *  {@link resolve} callback; {@link cover} then solves one query. */
+export declare class GraphSearch {
+    private readonly store;
+    private readonly maxGroup;
+    /** The host whose capabilities the search consults: resolve (canonical node
+     *  id of a byte span), recogniseSpan (content-addressed graph lookup for
+     *  recursive completion), and chooseNext (distributional-evidence edge
+     *  disambiguation when a recognised form has multiple continuations). */
+    private readonly host;
+    constructor(store: Store, maxGroup: number, 
+    /** The host whose capabilities the search consults: resolve (canonical node
+     *  id of a byte span), recogniseSpan (content-addressed graph lookup for
+     *  recursive completion), and chooseNext (distributional-evidence edge
+     *  disambiguation when a recognised form has multiple continuations). */
+    host: GraphSearchHost);
+    /** Explore the Sema graph for the lightest cover of the query and return its
+     *  chosen spans left-to-right — WITH the derivation's total weight (the g
+     *  value of the goal item, in the exported cost ladder), which think's
+     *  grounding decider compares against the other mechanisms' candidates —
+     *  or null if the query cannot be covered.
+     *
+     *  The search runs on the query's tree leaves, not flat bytes — leaf-level
+     *  cover axioms, recognised forms as graph entry points — and discovers
+     *  cross-leaf forms by fusing adjacent fragments on demand (the only
+     *  byte-processing it does, and only where a derivation needs it).  When
+     *  `substitutions` is given, recognised forms emit substitute bytes directly
+     *  (cost 0) — articulation splicing the asker's wording in.
+     *
+     *  Any learnt connector between two rewrites is spliced IN by the in-search
+     *  connector rule (see {@link outRules}), so the returned spans already carry
+     *  it — there is no post-pass. */
+    cover(queryLen: number, sites: ReadonlyArray<Site>, conceptTarget: ReadonlyMap<number, number>, leaves: ReadonlyArray<Leaf>, splits: ReadonlySet<number>, starts: ReadonlySet<number>, substitutions?: ReadonlyMap<number, Uint8Array>, connectors?: ReadonlyMap<string, Uint8Array>, computedResults?: ReadonlyArray<ComputedResult>, 
+    /** When given, receives the lightest derivation's rule applications — the
+     *  full adapted A*LD proof tree as classified {@link DerivationStep}s — for the TOP
+     *  cover only (a recursive recompletion solves its own sub-cover and is not
+     *  reported here, to keep the trace one layer per think).  Off by default,
+     *  so the search pays nothing when no one inspects. */
+    onDerivation?: (steps: DerivationStep[]) => void): {
+        segs: Seg[];
+        cost: number;
+    } | null;
+    /** Build the deduction system for one span and return its lightest cover's
+     *  chosen spans — the SINGLE routine the query and every produced composite
+     *  run through.  `recognition` carries the span's recognised forms; the query
+     *  brings its own (with pre-resolved concepts/connectors), a recursive
+     *  completion re-recognises the produced bytes (edge/fuse only).
+     *
+     *  No depth limit governs nesting — convergence is INTRINSIC, exactly as in the
+     *  adapted A*LD chart and {@link completeForward}: a completion only recurses into a
+     *  node it has not already entered ({@link recompleteNode}'s cycle guard), and
+     *  the node ids are finite, so the recursion must terminate on its own.  A
+     *  decomposition may therefore run as deep as the graph licenses — three
+     *  decomposes, two recomposes, any mix — and stops only when it reaches a node
+     *  that leads nowhere new, never at an arbitrary count. */
+    private solve;
+    /** The weighted deduction system the graph exploration solves (the four
+     *  reductions of adapted A*LD live in {@link lightestDerivation}; this only states the
+     *  items, axioms, goal, and rules — see {@link GItem} for the item kinds).
+     *
+     *  Forms that span across leaves are discovered BY the rules, which fuse
+     *  adjacent fragments toward a known leaf (findLeaf) or branch (findBranch);
+     *  a completion fused with its neighbour may spell a deeper learned form the
+     *  flat probes can't name, recovered canonically by {@link resolve}. */
+    private buildSearch;
+    /** cover(p): the BRIDGE rule — extend the cover across any coverable out that
+     *  begins at p, stepping the frontier from p to that out's end.
+     *
+     *  This is what links the rewritten parts of a multi-form answer.  An out is
+     *  either a recognised completion (`rec`, free) or a literal span the query
+     *  carried between known forms — the connective: a space, comma, period,
+     *  newline, or any run of bytes that was never recognised.  Bridging a literal
+     *  costs PASS per byte (so the search still prefers to recognise), but it is
+     *  the cheapest — indeed only — way to cross a gap that has no learned form,
+     *  and it KEEPS that connective in the cover chain, so the asker's own linking
+     *  material reappears when it still coheres ("ice, fire" → "cold, hot", not
+     *  "coldhot").  A recognised completion bridges for a tiny ε (1e-3, far below
+     *  STEP), so a single connected span beats two separate ones on coherence
+     *  without disturbing the cost ladder's ordering.
+     *
+     *  Marks p finalised so the symmetric out-side bridge ({@link outRules}) can
+     *  fire for outs that arrive after their start position is covered. */
+    private coverRules;
+    /** The BRIDGE rule, built once for its two arrival orders (cover-first in
+     *  {@link coverRules}, out-first in {@link outRules}): ε for a recognised
+     *  completion; PASS per byte for a literal connective — kept in the cover
+     *  so the asker's own connector survives where it fits.  ONE definition of
+     *  the cost expression, so the ladder's application cannot drift between
+     *  the two sides. */
+    private bridgeRule;
+    /** The connector-SPLICE rule for an oriented (l, r) pair, or null when the
+     *  pair does not qualify — the ONE body behind {@link outRules}' two
+     *  mirror loops (this-as-left over resolved right partners, this-as-right
+     *  over resolved left partners).  Fires only when both sides are
+     *  recognised, r starts at or after l ends, and the gap between them is
+     *  empty or wholly recognised — never across the asker's own literal
+     *  separator. */
+    private trySplice;
+    /** form(i,j,node,via): follow the graph out of `node`, or (in articulation)
+     *  emit its substitute voice directly. */
+    private formRules;
+    /** Complete a node that an edge produced but that bears no further whole-edge,
+     *  by COVERING ITS OWN BYTES — the very same operation the top query runs.
+     *  Completion is not a special pass: a produced composite ("p1 p2") is just
+     *  another span to cover, and covering it re-applies recognition, edge-follow,
+     *  fusion and recomposition to discover that its parts continue (p1→R1, p2→R2)
+     *  and recompose into a deeper learnt form (→ FINAL).  This is why a single
+     *  edge-target needs no bespoke logic — it routes back through {@link solve}.
+     *
+     *  Re-recognition (not the node's tree children) is what surfaces the learnt
+     *  parts: content-defined chunking may cut "p1 p2" as "p1 p"|"2", so only
+     *  recognising the bytes recovers p1 and p2 as the forms the graph knows.
+     *
+     *  The recovered answer is accepted only when it MOVED and names a LEARNT node
+     *  ({@link resolve}) — the graph itself gates against re-expanding a contained
+     *  form ("ice is cold" ⊅→ "ice is cold is cold").
+     *
+     *  Termination is INTRINSIC, not a depth limit: a node already on the
+     *  completion stack ({@link recompleteOpen}) is not re-entered — a self-
+     *  referential recomposition is a cycle that can yield nothing new, so it
+     *  stops there, exactly as {@link completeForward} stops on a revisited edge.
+     *  Distinct node ids are finite and each finished completion is memoised, so a
+     *  legitimate chain runs as deep as the graph licenses and no further. */
+    private recompleteNode;
+    /** Per-cover memo of each produced node's completion (so the many terminal
+     *  outs of a long query re-cover each distinct node at most once); reset at the
+     *  top of {@link cover}. */
+    private recompleteMemo;
+    /** The nodes currently being re-completed — the recursion stack.  A node in
+     *  this set is not re-entered, so a cyclic recomposition terminates naturally
+     *  (the same cycle guard {@link completeForward} uses), with no depth cap. */
+    private recompleteOpen;
+    /** out(i,j,bytes,…): index it for the binary rules, then offer splicing a
+     *  learnt connector (the in-search bridge), splitting (at a sub-leaf form
+     *  boundary), bridging (cover(i) ∧ this → cover(j)), and fusing with an
+     *  adjacent finalised out. */
+    private outRules;
+    /** Whether the query span [from, to) is wholly covered by RECOGNISED outs —
+     *  the test that lets a connector jump across INTERIOR answers (an N-ary whole)
+     *  but never across the asker's own unrecognised framing (a space or comma the
+     *  asker wrote between parts).  Empty span (from === to, the adjacent case) is
+     *  trivially recognised.  Otherwise step right-to-left: from `to`, find a
+     *  recognised out ending there and continue from its start, until reaching
+     *  `from`.  Greedy-longest is sufficient here — the spans in play are the few
+     *  recognised answers of one query, not a general interval cover. */
+    private gapRecognised;
+    /** Fuse two adjacent finalised outs — the search's own discovery of forms
+     *  that cross leaf boundaries.  The concatenation may be a known leaf
+     *  (findLeaf, when short enough), or — when both sides resolved — their pair a
+     *  known branch (findBranch); a completion fused with its neighbour may spell
+     *  a deeper learned form, recovered canonically by {@link resolve} (gated on a
+     *  completion being present, so it only runs along chains).  The fused span
+     *  lives on as an intermediate out while it could still grow into a form, and
+     *  enters the graph as a form the moment it names a node. */
+    private fuse;
+}