@hviana/sema 0.1.9 → 0.2.1

package/dist/src/mind/mechanisms/confluence.js

@@ -0,0 +1,225 @@
+// confluence.ts — Confluence Join (Section 4 of the mind).
+//
+// THE CLASS THIS SOLVES: conjunctive queries — answers that are stored in NO
+// single fact and exist only as the INTERSECTION of independent evidence
+// streams.  "Which material is translucent and featherlight?"  No learnt form
+// contains the answer; each constraint reaches its own set of exemplars, and
+// the entity satisfying both lives exactly where those sets MEET.  Every
+// other mechanism produces its answer by following ONE evidence path (a
+// chain, a reverse step, a halo hop, one aligned frame); the consensus climb
+// SUMS votes, fusion CONCATENATES topics, CAST COMPARES two seats — none of
+// them intersects, so this class was previously answered wrong (fusion pairs
+// one fact per constraint, from DIFFERENT entities).
+//
+// THE MEET IS NATIVE, NOT A BYTE SCAN.  The store is content-addressed: any
+// content two deposits share IS the same node id, interned once at write
+// time (hash-consing) — so "what do these two facts have in common?" is a
+// SET INTERSECTION OF IDENTITIES the write side already computed, asked
+// through the canonical window read (leafIdRun/findBranch — the same
+// write/read contract recognition runs on).  Three identity/structure tests
+// make the whole mechanism:
+//
+//   • constraint streams — the consensus climb's ranked anchors, each bound
+//     to the query spans whose DISCRIMINATIVE windows it holds by identity
+//     (a resonance-voted anchor holding none of the query's discriminative
+//     content is no constraint at all); two streams are independent when
+//     the content they bind is disjoint;
+//   • the meet — window ids present in BOTH anchors and ABSENT from the
+//     query: shared-with-query windows are the constraint being re-named
+//     (or its scaffolding), so subtracting the query's own window ids
+//     leaves exactly the content the question asks FOR — the open seat;
+//   • the filler/scaffolding separator — the same structural IDF the climb
+//     derives (edgeAncestors' contextsReached): shared content reaching a
+//     corpus minority of contexts is an entity, content reaching a majority
+//     is frame scaffolding.  No statistics, no learning — the same global-
+//     quantity-from-capped-local-probes reading that makes the climb's IDF
+//     work, pointed at a new question.
+//
+// HONESTY: the meet can only ever name content that structurally exists in
+// two independently learnt exemplars — an empty intersection yields null and
+// the ordinary pipeline decides.  Confluence cannot fabricate.
+import { read } from "../primitives.js";
+import { corpusN, reachOf } from "../traverse.js";
+import { dominates } from "../../geometry.js";
+import { STEP } from "../graph-search.js";
+import { unexplainedLabel } from "../rationale.js";
+import { rItem, rNode } from "../trace.js";
+/** The main confluence entry point.  Given a query, detect whether it weaves
+ *  two or more INDEPENDENT constraints (ranked anchors supported by disjoint
+ *  query spans), intersect the constraints' evidence by content-addressed
+ *  identity, and return the discriminative content the streams share — the
+ *  entity that satisfies all constraints at once.  Null when the query is
+ *  not conjunctive or nothing lies in the intersection. */
+export async function confluenceJoin(ctx, query, pre) {
+    const W = ctx.space.maxGroup;
+    if (query.length < 2 * W || ctx.store.edgeSourceCount() === 0)
+        return null;
+    const { ranked } = await pre.attention();
+    if (ranked.length < 2)
+        return null;
+    const N = corpusN(ctx);
+    // Response-scoped shared memos: the anchor-window identities and the
+    // structural-IDF reach live on Precomputed, so any other identity-based
+    // mechanism in the same response reuses them.
+    const reachMemo = pre.reachMemo;
+    const windowsOfAnchor = (anchor) => pre.windowsOf(anchor);
+    // The query's own window identities, offset → id (the canonical
+    // content-addressed read, canonical.windowIds): whatever the meet shares
+    // with the query is the CONSTRAINT being re-named (or its scaffolding),
+    // never the open seat the question asks for — subtracted by identity,
+    // below.
+    const queryWin = pre.queryWindows;
+    const queryIds = new Set(queryWin.values());
+    // A constraint must bind a CONSTITUENT, not a shard.  A genuinely shared
+    // form weaves a contiguous RUN of shared discriminative windows — its
+    // merged cover span is the form's own length, beyond one perception
+    // quantum (2W: the same "two quanta of structure" bar the conjunctive
+    // precondition `query.length < 2W` and CAST's weave live under).  A long
+    // stored document holds thousands of W-windows and will hold a FEW of any
+    // query's by accident, but accidental sharing is one window (a merged
+    // span of W, at most ~W+overlap bytes: "ow ma", "ys a", "ías " —
+    // observed), never a run ("​ translucent", " featherlight" — the genuine
+    // constraints).  Shard-bound streams are no constraints, and their meets
+    // are connective debris (". Sure,", "ngul" — observed).
+    const bindsAConstituent = (cover) => cover.some(([cs, ce]) => ce - cs >= 2 * W);
+    const streams = [];
+    const rankedCapped = ranked.length > pre.k ? ranked.slice(0, pre.k) : ranked;
+    for (const cand of rankedCapped) {
+        if (streams.some((s) => s.anchor === cand.anchor))
+            continue;
+        const ids = new Set(windowsOfAnchor(cand.anchor).values());
+        if (ids.size === 0)
+            continue;
+        const cover = [];
+        const held = [];
+        let curC = null;
+        let curH = null;
+        for (const [off, wid] of queryWin) {
+            if (!ids.has(wid))
+                continue;
+            if (curH !== null && off <= curH[1])
+                curH[1] = off + W;
+            else
+                held.push(curH = [off, off + W]);
+            if (dominates(reachOf(ctx, wid, N, reachMemo), N))
+                continue; // scaffolding never binds
+            if (curC !== null && off <= curC[1])
+                curC[1] = off + W;
+            else
+                cover.push(curC = [off, off + W]);
+        }
+        if (cover.length > 0 && bindsAConstituent(cover)) {
+            streams.push({ anchor: cand.anchor, vote: cand.vote, ids, cover, held });
+        }
+    }
+    if (streams.length < 2)
+        return null;
+    // Two streams are INDEPENDENT constraints when the query content they
+    // hold is disjoint — each answers a different part of what was asked.
+    const disjoint = (a, b) => a.cover.every(([as, ae]) => b.cover.every(([bs, be]) => be <= as || bs >= ae));
+    let met = null;
+    for (let i = 0; i < streams.length; i++) {
+        for (let j = i + 1; j < streams.length; j++) {
+            const a = streams[i];
+            const b = streams[j];
+            if (!disjoint(a, b))
+                continue;
+            const wa = windowsOfAnchor(a.anchor);
+            const wb = b.ids;
+            // ── The MEET: in both anchors, not in the query ────────────────────
+            // Offsets of A whose window id is shared with B and absent from the
+            // query — merged into maximal contiguous spans (windows overlap, so
+            // consecutive shared offsets weave one span).
+            const spans = [];
+            let cur = null;
+            for (const [off, wid] of wa) {
+                const inMeet = wb.has(wid) && !queryIds.has(wid);
+                if (inMeet) {
+                    if (cur !== null && off <= cur[1])
+                        cur[1] = off + W;
+                    else
+                        spans.push(cur = [off, off + W]);
+                }
+            }
+            if (spans.length === 0)
+                continue;
+            const aBytes = read(ctx, a.anchor);
+            for (const [s, e] of spans) {
+                // Scaffolding gate: the span's MOST discriminative window decides.
+                // Content reaching a corpus MAJORITY of contexts discriminates
+                // nothing (the same half-dominance convention every wrapper test
+                // uses); the query-subtraction above already removed everything the
+                // question names, so what survives here is a genuine open-seat
+                // entity.
+                let reach = Infinity;
+                for (let off = s; off + W <= e; off++) {
+                    const wid = wa.get(off);
+                    if (wid !== undefined && wb.has(wid) && !queryIds.has(wid)) {
+                        reach = Math.min(reach, reachOf(ctx, wid, N, reachMemo));
+                    }
+                }
+                if (!isFinite(reach) || dominates(reach, N))
+                    continue;
+                const len = e - s;
+                if (met === null || reach < met.reach ||
+                    (reach === met.reach && len > met.len)) {
+                    met = { bytes: aBytes.subarray(s, e), reach, len, a, b };
+                }
+            }
+        }
+    }
+    if (met === null)
+        return null;
+    const t = ctx.trace?.enter("confluence", [rItem(query, "query")]);
+    ctx.trace?.step("intersectEvidence", [
+        rNode(ctx, met.a.anchor, "constraint", met.a.vote),
+        rNode(ctx, met.b.anchor, "constraint", met.b.vote),
+    ], [rItem(met.bytes, "meet")], `the discriminative content BOTH constraints' evidence shares, by content-addressed identity (reach ${met.reach} of ${N} contexts)`);
+    t?.done([rItem(met.bytes, "answer")], "conjunctive join — the entity where the independent evidence streams meet");
+    // Evidence: the query spans whose content the two streams hold by
+    // identity (scaffolding included — held, not just the binding cover);
+    // the acts were two constraint matches and one meet.
+    const accounted = [
+        ...met.a.held,
+        ...met.b.held,
+    ];
+    return {
+        bytes: met.bytes,
+        used: new Set([met.a.anchor, met.b.anchor]),
+        accounted,
+        moves: 3 * STEP,
+        unexplained: unexplainedLabel(query, accounted),
+    };
+}
+// ── Pipeline mechanism ──────────────────────────────────────────────────────
+export const confluenceMechanism = {
+    name: "confluence",
+    provenance: "join",
+    async floor(_ctx, query, pre, worthRunning) {
+        const W = _ctx.space.maxGroup;
+        if (query.length < 2 * W || _ctx.store.edgeSourceCount() === 0)
+            return null;
+        // Confluence's floor is always exactly 3*STEP when it exists — same
+        // investment discipline as CAST's (see cast.ts): when the bound already
+        // cannot beat the incumbent, return it UNINVESTED (never first-touch the
+        // climb just to be pruned) and let the pipeline record the truthful
+        // "cannot beat incumbent" note.
+        if (!worthRunning(3 * STEP))
+            return 3 * STEP;
+        if ((await pre.attention()).ranked.length < 2)
+            return null;
+        return 3 * STEP;
+    },
+    async run(ctx, query, pre) {
+        const met = await confluenceJoin(ctx, query, pre);
+        if (!met)
+            return [];
+        return [{
+                bytes: met.bytes,
+                accounted: met.accounted,
+                moves: met.moves,
+                used: met.used,
+                unexplained: met.unexplained,
+            }];
+    },
+};

package/dist/src/mind/mechanisms/cover.d.ts

@@ -0,0 +1,6 @@
+import type { MindContext } from "../types.js";
+import type { Site } from "../graph-search.js";
+import type { PipelineMechanism } from "../pipeline-mechanism.js";
+export declare function resolveConcepts(ctx: MindContext, sites: Site[]): Promise<Map<number, number>>;
+export declare function resolveConnectors(ctx: MindContext, sites: ReadonlyArray<Site>): Promise<Map<string, Uint8Array>>;
+export declare const coverMechanism: PipelineMechanism;

package/dist/src/mind/mechanisms/cover.js

@@ -0,0 +1,179 @@
+// mechanisms/cover.ts — Cover (Grounding II): the query's own decomposition
+// composes an answer through ONE lightest-derivation search.
+//
+// Cover consumes recognition directly (its axioms are the query's own
+// decomposition) plus the computed spans any parse()-bearing mechanism
+// contributed: computed spans MASK colliding recognised sites and enter the
+// search at zero cost ("computation always wins", §16.3) — which is also why
+// cover runs FIRST in defaultMechanisms: a computed-backed cover becomes a
+// near-zero-cost incumbent that prunes the other mechanisms through the
+// ordinary admissible-floor check, with no extension special-case anywhere.
+import { read, resolve } from "../primitives.js";
+import { guidedFirst } from "../traverse.js";
+import { conceptHop } from "../match.js";
+import { bridge } from "../resonance.js";
+import { liftAnswer } from "../types.js";
+import { decodeText, unexplainedLabel } from "../rationale.js";
+import { rItem, rNode, traceDerivation } from "../trace.js";
+// ── Concept / connector pre-resolution ──────────────────────────────────────
+export async function resolveConcepts(ctx, sites) {
+    const target = new Map();
+    const visited = new Set();
+    for (const { payload: n } of sites) {
+        if (visited.has(n))
+            continue;
+        visited.add(n);
+        if (ctx.store.hasNext(n))
+            continue;
+        const hop = await conceptHop(ctx, n);
+        if (hop !== null)
+            target.set(n, hop);
+    }
+    if (target.size > 0) {
+        ctx.trace?.step("resolveConcepts", [...target.keys()].map((n) => rNode(ctx, n, "edgeless-form")), [...target.values()].map((h) => rNode(ctx, h, "concept-sibling")), "borrow a synonym's continuation edge for each edge-less form (a concept/halo hop)");
+    }
+    return target;
+}
+export async function resolveConnectors(ctx, sites) {
+    const links = new Map();
+    const ordered = [...sites].sort((a, b) => a.start - b.start);
+    const answerOf = (n) => guidedFirst(ctx, n) ?? n;
+    const bridgePair = async (l, r) => {
+        if (l === r || links.has(l + "," + r))
+            return;
+        const link = await bridge(ctx, read(ctx, l), read(ctx, r));
+        if (link !== null)
+            links.set(l + "," + r, link);
+    };
+    for (let i = 0; i + 1 < ordered.length; i++) {
+        if (ordered[i].end !== ordered[i + 1].start)
+            continue;
+        const lefts = [ordered[i].payload, answerOf(ordered[i].payload)];
+        const rights = [ordered[i + 1].payload, answerOf(ordered[i + 1].payload)];
+        for (const l of new Set(lefts)) {
+            for (const r of new Set(rights)) {
+                await bridgePair(l, r);
+                await bridgePair(r, l);
+            }
+        }
+    }
+    const orderedNodes = [];
+    const seenN = new Set();
+    for (const s of ordered) {
+        const node = guidedFirst(ctx, s.payload) ?? s.payload;
+        if (seenN.has(node))
+            continue;
+        seenN.add(node);
+        orderedNodes.push({ node, bytes: read(ctx, node) });
+    }
+    if (orderedNodes.length >= 3) {
+        const first = orderedNodes[0];
+        const W = ctx.space.maxGroup;
+        let middleBytes = 0; // Σ bytes of the answers BETWEEN first and m-th
+        for (let m = 1; m < orderedNodes.length; m++) {
+            const key = first.node + "," + orderedNodes[m].node;
+            if (links.has(key)) {
+                middleBytes += orderedNodes[m].bytes.length;
+                continue;
+            }
+            // The N-ary interior legitimately holds every intermediate answer
+            // plus one W-quantum of glue per joint — pass that allowance so the
+            // bridge's phrase-scale cap admits the whole learnt run.
+            const allowance = middleBytes + (m + 1) * W;
+            const interior = await bridge(ctx, first.bytes, orderedNodes[m].bytes, allowance);
+            if (interior !== null)
+                links.set(key, interior);
+            middleBytes += orderedNodes[m].bytes.length;
+        }
+    }
+    if (links.size > 0) {
+        ctx.trace?.step("resolveConnectors", ordered.map((s) => rItem(read(ctx, s.payload), "answer", s.payload)), [...links.entries()].map(([pair, bytes]) => ({
+            text: `${pair}: "${decodeText(bytes)}"`,
+            role: "connector",
+        })), "the bytes the graph splices between adjacent answers (asked of the gist space)");
+    }
+    return links;
+}
+// ── Pipeline mechanism ──────────────────────────────────────────────────────
+export const coverMechanism = {
+    name: "cover",
+    provenance: "cover",
+    async floor(_ctx, _query, _pre, _worthRunning) {
+        return 0;
+    },
+    async run(ctx, query, pre) {
+        const { rec, computed } = pre;
+        // Masking: computed spans are authoritative.  Remove recognised sites
+        // that overlap any computed span before building the cover search.
+        const sites = computed.length === 0
+            ? rec.sites
+            : rec.sites.filter((s) => !computed.some((u) => s.start < u.j && u.i < s.end));
+        if (computed.length > 0 && sites.length < rec.sites.length) {
+            ctx.trace?.step("maskByComputation", rec.sites.map((s) => rItem(query.subarray(s.start, s.end), "form", s.payload, [
+                s.start,
+                s.end,
+            ])), sites.map((s) => rItem(query.subarray(s.start, s.end), "form", s.payload, [
+                s.start,
+                s.end,
+            ])), "a computation always wins: recognised forms overlapping a computed span are dropped");
+        }
+        if (sites.length === 0 && computed.length === 0)
+            return [];
+        const connectors = await resolveConnectors(ctx, sites);
+        let splits = rec.splits;
+        if (computed.length > 0) {
+            splits = new Set(rec.splits);
+            for (const u of computed) {
+                splits.add(u.i);
+                splits.add(u.j);
+            }
+        }
+        const concepts = await resolveConcepts(ctx, sites);
+        const coverDeps = [
+            ctx.trace?.lastIndex("recognise"),
+            ctx.trace?.lastIndex("computeExtensions"),
+            ctx.trace?.lastIndex("resolveConcepts"),
+            ctx.trace?.lastIndex("resolveConnectors"),
+        ].filter((x) => x !== undefined);
+        // Convert ComputedSpan[] to ComputedResult[] for the graph search.
+        const computedResults = computed.map((u) => ({
+            i: u.i,
+            j: u.j,
+            bytes: u.bytes,
+            node: resolve(ctx, u.bytes) ?? undefined,
+        }));
+        const tCover = ctx.trace?.enter("cover", [
+            ...sites.map((s) => rItem(query.subarray(s.start, s.end), "form", s.payload, [
+                s.start,
+                s.end,
+            ])),
+            ...computedResults.map((u) => rItem(u.bytes, "computed")),
+        ], coverDeps.length ? coverDeps : undefined);
+        const solved = ctx.search.cover(query.length, sites, concepts, rec.leaves, splits, undefined, connectors, computedResults, ctx.trace ? (steps) => traceDerivation(ctx, steps) : undefined);
+        const segs = solved && solved.segs;
+        tCover?.done(segs === null
+            ? []
+            : segs.map((s) => rItem(s.bytes, s.rec ? "chosen" : "bridge", s.node, [s.i, s.j])), segs === null
+            ? "no cover of the query composed"
+            : "lightest derivation: the chosen spans, left to right");
+        if (segs === null)
+            return [];
+        const composed = liftAnswer(segs, query.length);
+        if (composed === null)
+            return [];
+        ctx.trace?.step("liftAnswer", segs.map((s) => rItem(s.bytes, s.rec ? "chosen" : "scaffolding", s.node, [s.i, s.j])), [rItem(composed, "answer", resolve(ctx, composed) ?? undefined)], "lift the recognised region out of the asker's framing", tCover ? [tCover.index] : undefined);
+        // accounted = RECOGNISED cover spans only — PASS-carried bytes
+        // are priced in cost already; the diagnostic label reflects the
+        // same distinction.
+        const accounted = segs
+            .filter((s) => s.rec)
+            .map((s) => [s.i, s.j]);
+        return [{
+                bytes: composed,
+                accounted,
+                moves: 0,
+                weight: solved.cost, // A*LD derivation's g-value IS the weight
+                unexplained: unexplainedLabel(query, accounted),
+            }];
+    },
+};

package/dist/src/mind/mechanisms/extraction.d.ts

@@ -0,0 +1,67 @@
+import type { Vec } from "../../vec.js";
+import type { MindContext } from "../types.js";
+import type { PipelineMechanism, Precomputed } from "../pipeline-mechanism.js";
+/** Find the first span-shaped skill exemplar among the ranked anchors from
+ *  climbAttentionAll and read the analogous span from the query.  Returns
+ *  the extracted bytes PLUS the query spans the skill ACCOUNTED FOR — the
+ *  located frames AND any read span BOUNDED by located frames on both
+ *  sides, the elementary evidence think's grounding decider weighs.  A
+ *  bounded read is explained: the skill located both its borders in the
+ *  query and emitted exactly what sits between them.  An OPEN-ENDED read
+ *  (the exemplar's answer reaches the context's end, so the query is read
+ *  to its own end with no located right border) remains a guess about where
+ *  the span stops — it stays unaccounted, priced by exclusion like the
+ *  cover's bridged bytes.  (Accounting frames only — the earlier convention
+ *  — let a CAST juxtaposition that merely echoed the query's exact site
+ *  outweigh a correct bounded extraction: the same span counted as
+ *  explained for one mechanism and not the other, and the asymmetry, not
+ *  the answers' merits, decided the grounding.)  Null when no skill
+ *  applies. */
+export declare function extractBySkill(ctx: MindContext, query: Uint8Array, pre: Precomputed): Promise<{
+    bytes: Uint8Array;
+    accounted: Array<[number, number]>;
+    unexplained: string;
+} | null>;
+/** Decompose an answer into substrings of its surrounding context, in order —
+ *  the STRONG span-shape reading (see the section note above).  Returns null
+ *  when no greedy longest-run decomposition exists.  Adjacent runs that
+ *  connect contiguously are merged. */
+export declare function answerRunsInContext(_ctx: MindContext, context: Uint8Array, answer: Uint8Array): Array<{
+    start: number;
+    end: number;
+    ansLen: number;
+}> | null;
+/** Check whether an anchor is a span-shaped skill exemplar: it represents a
+ *  fact whose context and answer together form a span-in-context pattern.
+ *  If the anchor has a nextOf continuation, that is the answer and the anchor
+ *  itself is the context.  Otherwise the anchor's prevOf parents provide
+ *  candidate contexts, and the longest one whose span is span-shaped wins. */
+export declare function skillExemplar(ctx: MindContext, anchor: number, guide?: Vec | null): Promise<{
+    contextBytes: Uint8Array;
+    answerBytes: Uint8Array;
+} | null>;
+/** Whether the answer is a SPARSE subsequence of the context (bytes in
+ *  order, arbitrary gaps) — the OPEN span-shape reading (see the section
+ *  note above).  This is what lets extraction validate a MULTI-PIECE
+ *  exemplar whose answer is stitched from several context runs — but it is
+ *  deliberately permissive, so it must never be used as evidence that one
+ *  span was "drawn from" another (see {@link containsSpan} for that).
+ *
+ *  There is deliberately NO containsSpan pre-check here: strict containment
+ *  IMPLIES the subsequence embedding (a contiguous run, or a resolved node —
+ *  whose content-addressed identity means its bytes occur contiguously — is
+ *  an in-order embedding with zero gaps), so the scan below decides alone,
+ *  with the same truth value.  The old pre-check re-perceived the context
+ *  (a full river fold) per CANDIDATE in skillExemplar's √N-capped loop —
+ *  pure cost, no discrimination. */
+export declare function isSpanShaped(_ctx: MindContext, context: Uint8Array, answer: Uint8Array): boolean;
+/** STRICT containment: the answer's resolved node appears in the context's
+ *  folded tree, or the answer occurs as one CONTIGUOUS byte run of the
+ *  context.  This is real evidence the answer was drawn from the context.
+ *  Fusion gates on this — the sparse-subsequence reading of
+ *  {@link isSpanShaped} is trivially satisfied by short answers over long
+ *  queries ("cold" is a gap-tolerant subsequence of most sentences holding
+ *  c…o…l…d in order), and gating fusion on it silently starved multi-topic
+ *  queries of their further points of attention. */
+export declare function containsSpan(ctx: MindContext, context: Uint8Array, answer: Uint8Array): boolean;
+export declare const extractionMechanism: PipelineMechanism;