@hviana/sema 0.1.0

package/src/mind/mechanisms/confluence.ts

@@ -0,0 +1,268 @@
+// 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 type { MindContext } from "../types.js";
+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 type { PipelineMechanism, Precomputed } from "../pipeline-mechanism.js";
+import { rItem, rNode } from "../trace.js";
+
+/** A join answer plus its elementary evidence for think's grounding decider:
+ *  `accounted` — the query spans whose votes carried the two constraint
+ *  streams; `moves` — the ladder cost of the acts performed (two constraint
+ *  matches and one meet, STEP each).  `used` carries the pair's exemplar
+ *  anchors so the reasoning stage does not re-speak them. */
+export interface JoinResult {
+  bytes: Uint8Array;
+  used: ReadonlySet<number>;
+  accounted: Array<[number, number]>;
+  moves: number;
+  /** A human-readable label for the query bytes the meet left unexplained —
+   *  purely diagnostic, never priced. */
+  unexplained: string;
+}
+
+/** 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: MindContext,
+  query: Uint8Array,
+  pre: Precomputed,
+): Promise<JoinResult | null> {
+  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: number) => 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());
+
+  // ── Constraint streams: which query content does each anchor CONTAIN ──
+  // An anchor is a constraint of the query spans whose windows it holds BY
+  // IDENTITY — and only DISCRIMINATIVE windows bind (scaffolding like
+  // " is " is contained everywhere and constrains nothing; the same
+  // half-dominance reading of the structural IDF as the meet's gate).
+  // This is exact where a vote span is approximate: a resonance-voted
+  // anchor that contains none of the query's discriminative windows is no
+  // constraint at all.
+  interface Stream {
+    anchor: number;
+    vote: number;
+    ids: Set<number>;
+    /** Merged [start, end) query spans whose DISCRIMINATIVE windows this
+     *  anchor holds — what the constraint BINDS (disjointness reads this). */
+    cover: Array<[number, number]>;
+    /** Merged [start, end) query spans this anchor holds AT ALL, scaffolding
+     *  included — what the evidence EXPLAINS (the decider's accounted reads
+     *  this: a contained " is " does not bind a constraint, but it is
+     *  genuinely matched content, the same way the cover search counts a
+     *  recognised common form). */
+    held: Array<[number, number]>;
+  }
+  const streams: Stream[] = [];
+  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: Array<[number, number]> = [];
+    const held: Array<[number, number]> = [];
+    let curC: [number, number] | null = null;
+    let curH: [number, number] | null = 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) {
+      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: Stream, b: Stream): boolean =>
+    a.cover.every(([as, ae]) =>
+      b.cover.every(([bs, be]) => be <= as || bs >= ae)
+    );
+
+  interface Meet {
+    bytes: Uint8Array;
+    reach: number;
+    len: number;
+    a: Stream;
+    b: Stream;
+  }
+  let met: Meet | null = 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: Array<[number, number]> = [];
+      let cur: [number, number] | null = 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: Array<[number, number]> = [
+    ...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: PipelineMechanism = {
+  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/src/mind/mechanisms/cover.ts

@@ -0,0 +1,248 @@
+// 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 type { MindContext } from "../types.js";
+import type { ComputedResult, Site } from "../graph-search.js";
+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 type { RationaleItem } from "../rationale.js";
+import { rItem, rNode, traceDerivation } from "../trace.js";
+import type { PipelineMechanism } from "../pipeline-mechanism.js";
+
+// ── Concept / connector pre-resolution ──────────────────────────────────────
+
+export async function resolveConcepts(
+  ctx: MindContext,
+  sites: Site[],
+): Promise<Map<number, number>> {
+  const target = new Map<number, number>();
+  const visited = new Set<number>();
+  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: MindContext,
+  sites: ReadonlyArray<Site>,
+): Promise<Map<string, Uint8Array>> {
+  const links = new Map<string, Uint8Array>();
+  const ordered = [...sites].sort((a, b) => a.start - b.start);
+  const answerOf = (n: number) => guidedFirst(ctx, n) ?? n;
+  const bridgePair = async (l: number, r: number) => {
+    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: Array<{ node: number; bytes: Uint8Array }> = [];
+  const seenN = new Set<number>();
+  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",
+      } as RationaleItem)),
+      "the bytes the graph splices between adjacent answers (asked of the gist space)",
+    );
+  }
+  return links;
+}
+
+// ── Pipeline mechanism ──────────────────────────────────────────────────────
+
+export const coverMechanism: PipelineMechanism = {
+  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 is number => x !== undefined);
+
+    // Convert ComputedSpan[] to ComputedResult[] for the graph search.
+    const computedResults: ComputedResult[] = 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: Array<[number, number]> = 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),
+    }];
+  },
+};