nodedex 0.1.0

package/dist/middleware/reflect/cost-pricing.js

@@ -0,0 +1,148 @@
+// ═══════════════════════════════════════════════════════════════════════════════
+// COST PRICING — per-pass $$ telemetry support  (D, 2026-05-25)
+//
+// Why this exists (system-level WHY before HOW per
+// feedback-systems-thinking-framework 2026-05-25 lesson):
+//
+//   PASS2-SPLIT-DESIGN.md §7: "The bet is unfalsifiable without measurement."
+//   Without per-pass $$ in the turn log, we can't:
+//     (a) verify the split lands in the Comfortable cost tier ($0.05-0.15/turn)
+//     (b) detect cost regressions before they reach the Warning tier
+//     (c) compare baseline-vs-split honestly when assessing flip readiness
+//     (d) attribute cost shifts (Pass 4 cheaper because Pass 2 is cleaner?
+//         or Pass 2c expensive because semantic wiring?)
+//
+//   This module converts the already-tracked token counts (reflectTokenStats
+//   in context.ts) into $$ per pass, written into the turn log per writeTurnLog
+//   in pipeline.ts. Together with splitAudit persistence, this closes the
+//   §7 measurement loop that the design declared non-negotiable.
+//
+// Universal framing (charter §5):
+//   - Keyed by `model_name: string` — works for ANY provider (Anthropic,
+//     Google, OpenAI, Mistral, DeepSeek, anything routed via OpenRouter)
+//   - Adding a new model = one entry to the table; no schema change
+//   - Returns null on unknown model — NEVER fabricates a cost (charter
+//     rule 6: guards catch failure, never override success). The turn log
+//     surfacing "we don't know what this costs" is the honest signal.
+//   - USD only — explicit in field names (`cost_usd`, `input_per_million`).
+//     Not aspirational about EUR/etc.
+//
+// Pricing source (point-in-time, verify against current provider docs):
+//   - Anthropic: https://www.anthropic.com/pricing (Haiku 4.5, Sonnet 4.6, Opus 4.7)
+//   - Google: https://ai.google.dev/pricing (Gemini 2.5 Flash, Pro)
+//   - OpenRouter dashboard: https://openrouter.ai/models (cross-provider rates)
+//   COST_PRICING_VERSION below is the safety valve — future agent should
+//   bump it when re-verifying rates.
+//
+// What this module does NOT do:
+//   - Per-attempt cost (escalations on truncation are billed at the model
+//     that ran). Today we use the FINAL successful model. Per-attempt
+//     fidelity is a follow-up if/when retry-cost-attribution becomes a
+//     validation question.
+//   - Reconcile with OpenRouter dashboard automatically — §7 wants ±10%
+//     reconciliation, that's a manual check until a separate tool exists.
+//   - Live-fetch rates — that would be a runtime dependency on an external
+//     API. Static table + version is the right tradeoff for now.
+// ═══════════════════════════════════════════════════════════════════════════════
+/**
+ * Bumped whenever the PRICING table below is re-verified against provider
+ * docs / OpenRouter dashboard. Surfaced in the turn log so a future agent
+ * (or future me) reading old turn logs can tell if the cost figures used
+ * stale rates.
+ */
+export const COST_PRICING_VERSION = "2026-06-22";
+/**
+ * Pricing table — model name string → per-million-token rates in USD.
+ *
+ * Add a new model = one entry. The key is the model name as it appears in
+ * provider.getName() / GenerateResult.model — these are the strings the
+ * pipeline already stamps into the turn log providers[] field. Stay
+ * verbatim to what providers emit so lookups are direct.
+ *
+ * Rates as of 2026-05-25. If you bump these, bump COST_PRICING_VERSION too
+ * so old turn-log readers can detect rate drift.
+ */
+export const PRICING = {
+    // ── Google Gemini (currently the primary pipeline model) ────────────────────
+    "google/gemini-2.5-flash": { input_per_million: 0.30, output_per_million: 2.50 },
+    "google/gemini-2.5-pro": { input_per_million: 1.25, output_per_million: 10.00 },
+    "gemini-2.5-flash": { input_per_million: 0.30, output_per_million: 2.50 },
+    "gemini-2.5-pro": { input_per_million: 1.25, output_per_million: 10.00 },
+    // ── Anthropic (target for multi-model routing per PASS2-SPLIT-DESIGN.md §7) ─
+    // Haiku for 2a/2b (structural); Sonnet/Opus for harder semantic work if needed.
+    // Both bare-name (direct Anthropic API) and "anthropic/" prefixed (OpenRouter
+    // routing) forms — these are the same models, the provider emits different
+    // model strings depending on the path. Multi-model routing in the orchestrator
+    // (NODEDEX_PASS2A_MODEL etc.) generally uses OpenRouter-prefix form because
+    // the production agent already routes via OpenRouter (see project-chat-proxy-built).
+    "claude-haiku-4-5-20251001": { input_per_million: 1.00, output_per_million: 5.00 },
+    "claude-haiku-4-5": { input_per_million: 1.00, output_per_million: 5.00 },
+    "claude-sonnet-4-6": { input_per_million: 3.00, output_per_million: 15.00 },
+    "claude-opus-4-7": { input_per_million: 15.00, output_per_million: 75.00 },
+    "anthropic/claude-haiku-4-5": { input_per_million: 1.00, output_per_million: 5.00 },
+    "anthropic/claude-haiku-4.5": { input_per_million: 1.00, output_per_million: 5.00 },
+    "anthropic/claude-sonnet-4-6": { input_per_million: 3.00, output_per_million: 15.00 },
+    "anthropic/claude-sonnet-4.6": { input_per_million: 3.00, output_per_million: 15.00 },
+    "anthropic/claude-opus-4-7": { input_per_million: 15.00, output_per_million: 75.00 },
+    "anthropic/claude-opus-4.7": { input_per_million: 15.00, output_per_million: 75.00 },
+    // ── Onboarding's recommended PAID option (so the cost panel doesn't show "?"
+    //    for a model a normal user is told to pick). Free models → FREE_MODELS below.
+    "openai/gpt-4o-mini": { input_per_million: 0.15, output_per_million: 0.60 },
+    "gpt-4o-mini": { input_per_million: 0.15, output_per_million: 0.60 },
+};
+/**
+ * Genuinely-FREE models ($0 at the provider). Kept OUT of PRICING — whose entries must be
+ * paid/non-zero (the "no accidental $0 lines" guard) — so a real free model is recognized as a
+ * known $0 rather than an "unknown model" (which would render as "?" in the cost panel). owl-alpha
+ * (the onboarding free option) is the case this fixes. Both OpenRouter-slug and bare forms.
+ */
+export const FREE_MODELS = new Set([
+    "openrouter/owl-alpha",
+    "owl-alpha",
+]);
+/**
+ * Compute USD cost for a token-usage record under the given model's rates.
+ *
+ * Returns `null` if the model is unknown to the pricing table. This is
+ * deliberate — fabricating a cost would mislead the validation work the
+ * design relies on. Logs once per unknown model so the gap is auditable.
+ *
+ * Returns 0 (not null) on empty usage with a known model — distinguishes
+ * "didn't run" (0) from "ran but we don't know what it cost" (null).
+ */
+const _warnedModels = new Set();
+export function computeCost(usage, model) {
+    if (!model) {
+        if (!_warnedModels.has("(undefined)")) {
+            _warnedModels.add("(undefined)");
+            console.warn("cost-pricing: computeCost called with undefined model — returning null");
+        }
+        return null;
+    }
+    if (FREE_MODELS.has(model))
+        return 0; // genuinely free → a KNOWN $0, not "unknown model" ("?")
+    const rate = PRICING[model];
+    if (!rate) {
+        if (!_warnedModels.has(model)) {
+            _warnedModels.add(model);
+            console.warn(`cost-pricing: no pricing entry for model "${model}" — returning null (add to PRICING table)`);
+        }
+        return null;
+    }
+    const input = usage?.input ?? 0;
+    const output = usage?.output ?? 0;
+    const thinking = usage?.thinking ?? 0;
+    // Thinking billed as output unless the provider specifies otherwise.
+    const thinkingRate = rate.thinking_per_million ?? rate.output_per_million;
+    const cost = (input / 1_000_000) * rate.input_per_million +
+        (output / 1_000_000) * rate.output_per_million +
+        (thinking / 1_000_000) * thinkingRate;
+    return cost;
+}
+/**
+ * Reset the warn-once memo. Useful for tests; not used in production code.
+ */
+export function _resetWarnings() {
+    _warnedModels.clear();
+}
+//# sourceMappingURL=cost-pricing.js.map

package/dist/middleware/reflect/cost-pricing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-pricing.js","sourceRoot":"","sources":["../../../src/middleware/reflect/cost-pricing.ts"],"names":[],"mappings":"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"}

package/dist/middleware/reflect/cross-group-link.d.ts

@@ -0,0 +1,61 @@
+import type { Pass2Item } from "./types.js";
+import type { LLMProvider } from "../../engine/ai-provider.js";
+export declare function crossGroupLinkEnabled(): boolean;
+/** Orphan-aware linking (default OFF, NODEDEX_V2_CROSSLINK_ORPHAN_AWARE): mark the blocks
+ *  that have no link yet (⚠ UNLINKED) in the linker's input so it targets those gaps
+ *  instead of re-deriving blindly — the recall fix for the residual islands. Empirical
+ *  (could it over-link a genuinely-standalone block?), so opt-in + A/B-able. Off → the
+ *  linker input is byte-identical to before. */
+export declare function orphanAwareLinkEnabled(): boolean;
+export interface CrossGroupLink {
+    from: string;
+    to: string;
+    type: string;
+    reasoning?: string;
+}
+export declare const CROSS_GROUP_LINK_PROMPT = "You are given knowledge blocks from ONE work session, already grouped into THREADS,\nwith each thread's INTERNAL links already drawn. Your only job: add the links that\ncross BETWEEN threads \u2014 where a block in one thread stands in a real relationship to\na block in another. The same kinds of relationships that hold within a thread hold\nacross them.\n\nDecide by reasoning about MEANING \u2014 what actually relates to what across the\nthreads, whether or not any connecting word is present.\n\nEach link is {from, to, type}, where \"from\" holds the relationship. Use the block\nids EXACTLY as given. Choose the type whose MEANING matches:\n  prompted_by \u00B7 based_on \u00B7 extends \u00B7 supersedes \u00B7 resolves \u00B7 supports \u00B7\n  contradicts \u00B7 related_to \u00B7 derived_from \u00B7 affects\nReach for the SHARPEST relation the meaning supports; related_to and affects are a\nlast resort. The link type MUST be exactly one of these ten.\n\nLook especially for the connections that orphan a block otherwise \u2014 these are easy to\nmiss across threads, for ANY block type: a block in one thread that REPLACED\n(supersedes) an earlier approach, value, or state in another, or that was TRIGGERED BY\n(prompted_by) an event or failure in another \u2014 not only where one thread's block is\nEVIDENCE for another's. A superseded or triggering block left unlinked is the gap to close.\n\nBlocks the input marks \u26A0 UNLINKED have NO link at all yet \u2014 they are the ones most\nlikely to be wrongly orphaned. Give each marked block a deliberate pass: find its\ncross-thread connection (what caused it, what it depends on, what it replaced or\nanswers), or judge it genuinely standalone.\n\nAdd ONLY links whose two blocks are in DIFFERENT threads \u2014 do NOT re-draw links\nwithin a thread, those are already present. Do NOT invent blocks or ids. If no\ngenuine cross-thread relationship exists, return an empty list.";
+/** Block ids that currently have NO link at all — no outgoing causal ref AND no in-set
+ *  block points at them. These are the islands the cross-group pass should target: the
+ *  linker sees every block but, without this, can't tell which are already connected, so
+ *  it re-derives blindly and misses a few. Considers the within-thread links already on
+ *  the items (based_on/triggered_by/extends/supersedes/resolves/relations). Refs to
+ *  out-of-set labels (existing-graph) count as "connected". Pure / testable. */
+export declare function unlinkedIds(items: Pass2Item[]): Set<string>;
+/** Render the blocks grouped by thread, each as `id [type] essence`, so the model sees
+ *  the cluster structure and references blocks by their exact id. Islands (no link yet)
+ *  are marked ⚠ UNLINKED so the linker prioritises closing those gaps. */
+export declare function buildCrossGroupLinkInput(items: Pass2Item[], groupByItemId: Record<string, string>): string;
+export interface CrossGroupLinkCallResult {
+    links: CrossGroupLink[] | null;
+    rateLimited: boolean;
+    usage?: {
+        input: number;
+        thinking: number;
+        output: number;
+    };
+}
+export declare function callCrossGroupLinkLLM(provider: LLMProvider, items: Pass2Item[], groupByItemId: Record<string, string>, thinkingBudget?: number): Promise<CrossGroupLinkCallResult>;
+/**
+ * Apply cross-group links onto the items' causal fields (via the shared
+ * applyLinkToPass2Item). Pure-ish: MUTATES the matched items. Every guard a
+ * cross-thread link must pass: both ids resolve, not a self-link, the two blocks
+ * are in DIFFERENT groups (within-thread links already exist), and the type is one
+ * of the ten relations. Anything failing a guard is skipped (never throws).
+ */
+export declare function applyCrossGroupLinks(items: Pass2Item[], links: CrossGroupLink[], groupByItemId: Record<string, string>): {
+    added: number;
+    skipped: number;
+};
+export interface CrossGroupLinkResult {
+    items: Pass2Item[];
+    added: number;
+    skipped: number;
+    llm_calls: number;
+}
+/**
+ * Run the cross-group linker over the converted items. Default OFF → passthrough.
+ * No-op when there are <2 threads (nothing can be cross-group). One bounded LLM
+ * call; never blocks the pipeline (any failure → 0 links added).
+ */
+export declare function runCrossGroupLink(provider: LLMProvider, items: Pass2Item[], groupByItemId: Record<string, string>): Promise<CrossGroupLinkResult>;
+//# sourceMappingURL=cross-group-link.d.ts.map

package/dist/middleware/reflect/cross-group-link.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-group-link.d.ts","sourceRoot":"","sources":["../../../src/middleware/reflect/cross-group-link.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAE/D,wBAAgB,qBAAqB,IAAI,OAAO,CAG/C;AAED;;;;gDAIgD;AAChD,wBAAgB,sBAAsB,IAAI,OAAO,CAEhD;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,uBAAuB,+5DA6B4B,CAAC;AAsBjE;;;;;gFAKgF;AAChF,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC,CAsB3D;AAED;;0EAE0E;AAC1E,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,SAAS,EAAE,EAClB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACpC,MAAM,CAqBR;AAED,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,cAAc,EAAE,GAAG,IAAI,CAAC;IAC/B,WAAW,EAAE,OAAO,CAAC;IACrB,KAAK,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7D;AAED,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,WAAW,EACrB,KAAK,EAAE,SAAS,EAAE,EAClB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACrC,cAAc,SAAO,GACpB,OAAO,CAAC,wBAAwB,CAAC,CAOnC;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,SAAS,EAAE,EAClB,KAAK,EAAE,cAAc,EAAE,EACvB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACpC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAapC;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,WAAW,EACrB,KAAK,EAAE,SAAS,EAAE,EAClB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACpC,OAAO,CAAC,oBAAoB,CAAC,CAc/B"}

package/dist/middleware/reflect/cross-group-link.js

@@ -0,0 +1,212 @@
+// ═══════════════════════════════════════════════════════════════════════════════
+// PIPELINE v2 — CROSS-GROUP LINKER (the INTEGRATE cross-thread step; design §15.4)
+// ═══════════════════════════════════════════════════════════════════════════════
+//
+// Per-group PRODUCE wires links only WITHIN each thread (it never sees the other
+// threads' blocks). This step runs AFTER all blocks exist (post-convert) and adds
+// the sparse links that cross BETWEEN threads — e.g. a decision in one cluster
+// grounded in a fact established in another. One bounded LLM call over the block
+// essences (output is just links → can't run away).
+//
+// MEANING-FIRST / GATE-5 (no new vocabulary):
+//   - relation types  = the SAME 10 (COMPREHEND_LINK_RELS).
+//   - fields targeted = the SAME Pass2Item causal fields, via the SHARED
+//     applyLinkToPass2Item helper (comprehend.ts) — the converter and this linker
+//     never drift on which field a relation lands in.
+//   - block identity  = the qualified item.id ({group}::{local}); no new id scheme.
+//
+// SCOPE: this builds CROSS-THREAD LINKING only. Cross-thread DEDUP (the duplicate
+// blocks two PRODUCE calls extract from shared transcript) is a separate concern
+// served by the existing block-dedup layer (dedupBySourceAndValue / stage-audit
+// block_dup), not re-implemented here.
+//
+// Default OFF: NODEDEX_V2_CROSSLINK=1 (only meaningful under v2). When off → pure
+// passthrough (no LLM). Reuse-not-rewrite: this IS the §15.4 INTEGRATE linker, now
+// concretely targeted (the roaster↔dark-roast cross-thread edges Run 10/11 missed).
+import { getThinkingBudget } from "./config.js";
+import { COMPREHEND_LINK_RELS, applyLinkToPass2Item, comprehendModel } from "./comprehend.js";
+export function crossGroupLinkEnabled() {
+    // DEFAULT ON since 2026-06-12 (part of the validated v2 stack). =0 opts out.
+    return process.env.NODEDEX_V2_CROSSLINK !== "0";
+}
+/** Orphan-aware linking (default OFF, NODEDEX_V2_CROSSLINK_ORPHAN_AWARE): mark the blocks
+ *  that have no link yet (⚠ UNLINKED) in the linker's input so it targets those gaps
+ *  instead of re-deriving blindly — the recall fix for the residual islands. Empirical
+ *  (could it over-link a genuinely-standalone block?), so opt-in + A/B-able. Off → the
+ *  linker input is byte-identical to before. */
+export function orphanAwareLinkEnabled() {
+    return process.env.NODEDEX_V2_CROSSLINK_ORPHAN_AWARE === "1";
+}
+export const CROSS_GROUP_LINK_PROMPT = `You are given knowledge blocks from ONE work session, already grouped into THREADS,
+with each thread's INTERNAL links already drawn. Your only job: add the links that
+cross BETWEEN threads — where a block in one thread stands in a real relationship to
+a block in another. The same kinds of relationships that hold within a thread hold
+across them.
+
+Decide by reasoning about MEANING — what actually relates to what across the
+threads, whether or not any connecting word is present.
+
+Each link is {from, to, type}, where "from" holds the relationship. Use the block
+ids EXACTLY as given. Choose the type whose MEANING matches:
+  prompted_by · based_on · extends · supersedes · resolves · supports ·
+  contradicts · related_to · derived_from · affects
+Reach for the SHARPEST relation the meaning supports; related_to and affects are a
+last resort. The link type MUST be exactly one of these ten.
+
+Look especially for the connections that orphan a block otherwise — these are easy to
+miss across threads, for ANY block type: a block in one thread that REPLACED
+(supersedes) an earlier approach, value, or state in another, or that was TRIGGERED BY
+(prompted_by) an event or failure in another — not only where one thread's block is
+EVIDENCE for another's. A superseded or triggering block left unlinked is the gap to close.
+
+Blocks the input marks ⚠ UNLINKED have NO link at all yet — they are the ones most
+likely to be wrongly orphaned. Give each marked block a deliberate pass: find its
+cross-thread connection (what caused it, what it depends on, what it replaced or
+answers), or judge it genuinely standalone.
+
+Add ONLY links whose two blocks are in DIFFERENT threads — do NOT re-draw links
+within a thread, those are already present. Do NOT invent blocks or ids. If no
+genuine cross-thread relationship exists, return an empty list.`;
+const CROSS_GROUP_LINK_SCHEMA = {
+    type: "object",
+    properties: {
+        links: {
+            type: "array",
+            items: {
+                type: "object",
+                properties: {
+                    from: { type: "string" },
+                    to: { type: "string" },
+                    type: { type: "string" },
+                    reasoning: { type: "string" },
+                },
+                required: ["from", "to", "type"],
+            },
+        },
+    },
+    required: ["links"],
+};
+/** Block ids that currently have NO link at all — no outgoing causal ref AND no in-set
+ *  block points at them. These are the islands the cross-group pass should target: the
+ *  linker sees every block but, without this, can't tell which are already connected, so
+ *  it re-derives blindly and misses a few. Considers the within-thread links already on
+ *  the items (based_on/triggered_by/extends/supersedes/resolves/relations). Refs to
+ *  out-of-set labels (existing-graph) count as "connected". Pure / testable. */
+export function unlinkedIds(items) {
+    const idSet = new Set(items.map((it) => it.id));
+    const hasOut = new Set(); // blocks with >=1 outgoing causal ref
+    const isTarget = new Set(); // in-set blocks something points at
+    for (const it of items) {
+        const refs = [
+            ...(it.based_on_items ?? []),
+            ...(it.triggered_by_items ?? []),
+            it.extends_item,
+            it.supersedes_ref,
+            it.resolved_ref,
+            ...((it.relations ?? []).map((r) => r?.target)),
+        ];
+        for (const r of refs) {
+            if (!r)
+                continue;
+            hasOut.add(it.id);
+            if (idSet.has(r))
+                isTarget.add(r);
+        }
+    }
+    const out = new Set();
+    for (const it of items)
+        if (!hasOut.has(it.id) && !isTarget.has(it.id))
+            out.add(it.id);
+    return out;
+}
+/** Render the blocks grouped by thread, each as `id [type] essence`, so the model sees
+ *  the cluster structure and references blocks by their exact id. Islands (no link yet)
+ *  are marked ⚠ UNLINKED so the linker prioritises closing those gaps. */
+export function buildCrossGroupLinkInput(items, groupByItemId) {
+    const islands = orphanAwareLinkEnabled() ? unlinkedIds(items) : new Set();
+    const byGroup = new Map();
+    for (const it of items) {
+        const g = groupByItemId[it.id] ?? "?";
+        let arr = byGroup.get(g);
+        if (!arr) {
+            arr = [];
+            byGroup.set(g, arr);
+        }
+        arr.push(it);
+    }
+    const parts = [];
+    for (const [g, its] of byGroup) {
+        parts.push(`[thread: ${g}]`);
+        for (const it of its) {
+            const mark = islands.has(it.id) ? " ⚠ UNLINKED" : "";
+            parts.push(`  - ${it.id} [${it.type}]${mark} ${(it.text ?? "").replace(/\s+/g, " ").slice(0, 140)}`);
+        }
+    }
+    const islandNote = islands.size > 0
+        ? `\n\n${islands.size} block(s) are marked ⚠ UNLINKED — give each a deliberate pass (see prompt).`
+        : "";
+    return `THREADS (each block's within-thread links are already drawn; add ONLY links BETWEEN threads):\n\n${parts.join("\n")}${islandNote}`;
+}
+export async function callCrossGroupLinkLLM(provider, items, groupByItemId, thinkingBudget = 2048) {
+    const userInput = buildCrossGroupLinkInput(items, groupByItemId);
+    const r = await provider.generateStructured(CROSS_GROUP_LINK_PROMPT, userInput, CROSS_GROUP_LINK_SCHEMA, { thinkingBudget: getThinkingBudget(thinkingBudget), maxOutputTokens: 4096, modelOverride: comprehendModel() });
+    return { links: r.result?.links ?? null, rateLimited: r.rateLimited, usage: r.usage };
+}
+/**
+ * Apply cross-group links onto the items' causal fields (via the shared
+ * applyLinkToPass2Item). Pure-ish: MUTATES the matched items. Every guard a
+ * cross-thread link must pass: both ids resolve, not a self-link, the two blocks
+ * are in DIFFERENT groups (within-thread links already exist), and the type is one
+ * of the ten relations. Anything failing a guard is skipped (never throws).
+ */
+export function applyCrossGroupLinks(items, links, groupByItemId) {
+    const byId = new Map(items.map((it) => [it.id, it]));
+    let added = 0, skipped = 0;
+    for (const link of links ?? []) {
+        const from = byId.get(link?.from);
+        if (!from || !byId.has(link?.to)) {
+            skipped++;
+            continue;
+        } // unknown id
+        if (link.from === link.to) {
+            skipped++;
+            continue;
+        } // self-link
+        if (groupByItemId[link.from] === groupByItemId[link.to]) {
+            skipped++;
+            continue;
+        } // SAME thread → not cross-group
+        if (!COMPREHEND_LINK_RELS.has(link.type)) {
+            skipped++;
+            continue;
+        } // unknown relation type
+        applyLinkToPass2Item(from, link.type, link.to, link.reasoning);
+        added++;
+    }
+    return { added, skipped };
+}
+/**
+ * Run the cross-group linker over the converted items. Default OFF → passthrough.
+ * No-op when there are <2 threads (nothing can be cross-group). One bounded LLM
+ * call; never blocks the pipeline (any failure → 0 links added).
+ */
+export async function runCrossGroupLink(provider, items, groupByItemId) {
+    if (!crossGroupLinkEnabled())
+        return { items, added: 0, skipped: 0, llm_calls: 0 };
+    const groupCount = new Set(Object.values(groupByItemId)).size;
+    if (groupCount < 2 || items.length < 2)
+        return { items, added: 0, skipped: 0, llm_calls: 0 };
+    try {
+        const r = await callCrossGroupLinkLLM(provider, items, groupByItemId);
+        if (!r.links)
+            return { items, added: 0, skipped: 0, llm_calls: 1 };
+        const { added, skipped } = applyCrossGroupLinks(items, r.links, groupByItemId);
+        console.log(`[cross-group-link] added ${added} cross-thread link(s), skipped ${skipped} — 1 LLM call`);
+        return { items, added, skipped, llm_calls: 1 };
+    }
+    catch (e) {
+        console.warn(`[cross-group-link] threw (${e?.message ?? e}) — 0 links added`);
+        return { items, added: 0, skipped: 0, llm_calls: 1 };
+    }
+}
+//# sourceMappingURL=cross-group-link.js.map

package/dist/middleware/reflect/cross-group-link.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-group-link.js","sourceRoot":"","sources":["../../../src/middleware/reflect/cross-group-link.ts"],"names":[],"mappings":"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"}

package/dist/middleware/reflect/dedup-by-source-and-value.d.ts

@@ -0,0 +1,70 @@
+import type { Pass2Item } from "./types.js";
+/**
+ * Core extractor: given a block TYPE + its unique{} object, return the canonical
+ * "what is this block" primary value. The identity-bearing field per type
+ * (per [[feedback-identity-is-unique-not-label]] — identity is unique{} content,
+ * NOT label/essence). Returns "" when no primary value found.
+ *
+ * Exported so OTHER producers that hold a (type, unique) pair rather than a
+ * Pass2Item — e.g. Stage AUDIT's scope_disagreement detector, which works off
+ * persisted Block rows — extract the SAME identity value (Rule 5: one notion of
+ * "block identity value," one implementation).
+ */
+export declare function extractPrimaryValueFromUnique(type: string, unique: Record<string, unknown>): string;
+/**
+ * Extract the canonical primary value for a Pass2Item, used as the second
+ * tuple element in dedup. Returns "" when no primary value found (the item
+ * then dedups only on source_excerpt, which is conservative).
+ */
+export declare function extractPrimaryValue(item: Pass2Item): string;
+export interface DedupResult {
+    /**
+     * Items list returned to the caller. Sub-step 1.4 semantics: kept ALWAYS
+     * equals input items (no drop). Pre-1.4 this auto-dropped duplicates;
+     * post-1.4 the caller writes pipeline_flags rows for an async LLM
+     * reviewer (Slice 2) to decide merge/leave/split with full graph context.
+     *
+     * Until Slice 2 lands, the graph may accumulate duplicate atomic blocks.
+     * That's the trade-off versus auto-drop, which violated the flag-not-merge
+     * principle the user established in PIPELINE-AUDIT-DEPENDENCY-MAP.md §2.
+     */
+    kept: Pass2Item[];
+    /**
+     * Duplicate-candidate pairs detected. The caller (pipeline.ts) resolves
+     * these item_ids to block_ids after Pass 3 createBlock loop, then calls
+     * writePipelineFlag with flag_type='atomic_dup_candidate'.
+     */
+    duplicates: Array<{
+        id: string;
+        duplicate_of: string;
+        key: string;
+    }>;
+}
+/**
+ * Detect candidate duplicate items by (source_excerpt, primary_value).
+ *
+ * Sub-step 1.4 change: this function NO LONGER drops items. Returns input
+ * unchanged + the duplicate-pair list. See DedupResult.kept comment for
+ * full rationale.
+ *
+ * RULES (unchanged from prior behavior):
+ *   - Two items are duplicate-CANDIDATES iff:
+ *       a) Both have non-empty excerpt AND
+ *       b) Both have non-empty primary value AND
+ *       c) Both tuples match exactly (case-sensitive — Pass 1 deterministically
+ *          extracts from transcript, so case should be stable)
+ *   - First occurrence is the "winner" for FK target purposes in the flag.
+ *   - NULL/empty excerpt items NEVER detected (treated as pre-Debt-5 atomic —
+ *     can't determine sameness without source pin).
+ *   - Empty primary value items NEVER detected (defensive — risk false-positive
+ *     on unrelated items that happen to share a source line).
+ *
+ * Returns:
+ *   - kept: ALL input items (never drops; same array reference)
+ *   - duplicates: list of {id, duplicate_of, key} for downstream flag writing
+ *
+ * Function name preserved (dedupBySourceAndValue) for backward compat with
+ * callers, but semantics flipped from "dedup" to "detect duplicates."
+ */
+export declare function dedupBySourceAndValue(items: Pass2Item[]): DedupResult;
+//# sourceMappingURL=dedup-by-source-and-value.d.ts.map

package/dist/middleware/reflect/dedup-by-source-and-value.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dedup-by-source-and-value.d.ts","sourceRoot":"","sources":["../../../src/middleware/reflect/dedup-by-source-and-value.ts"],"names":[],"mappings":"AA2CA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AA+B5C;;;;;;;;;;GAUG;AACH,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,MAAM,CAeR;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAE3D;AAID,MAAM,WAAW,WAAW;IAC1B;;;;;;;;;OASG;IACH,IAAI,EAAE,SAAS,EAAE,CAAC;IAClB;;;;OAIG;IACH,UAAU,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACtE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,WAAW,CAqBrE"}

package/dist/middleware/reflect/dedup-by-source-and-value.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dedup-by-source-and-value.js","sourceRoot":"","sources":["../../../src/middleware/reflect/dedup-by-source-and-value.ts"],"names":[],"mappings":"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"}

package/dist/middleware/reflect/describe-roots.d.ts

@@ -0,0 +1,58 @@
+import type { WorkspaceDB, Block } from "../../store/database.js";
+import type { LLMProvider } from "../../engine/ai-provider.js";
+export interface RootDescribeInput {
+    root: Block;
+    memberCount: number;
+    /** content.last_described_member_count; null = never described. */
+    lastDescribedCount: number | null;
+}
+/** Returns the reason a root needs (re)describing, or false. Pure. */
+export declare function rootNeedsDescription(inp: {
+    memberCount: number;
+    lastDescribedCount: number | null;
+}, opts: {
+    minMembers: number;
+    growthThreshold: number;
+}): false | "never" | "grew";
+export declare function selectRootsNeedingDescription(inputs: RootDescribeInput[], opts: {
+    minMembers: number;
+    growthThreshold: number;
+}): Array<RootDescribeInput & {
+    reason: "never" | "grew";
+}>;
+export declare const DESCRIBE_ROOT_PROMPT = "You are writing a one-line SURFACE description of a project root in a knowledge graph.\nIts ONLY job: let a later step decide \"does a new piece of knowledge belong in THIS project?\"\n\nCapture TWO things in one line:\n  1. DOMAIN \u2014 what this project is about (the topic).\n  2. OWNER / SCOPE \u2014 whose it is (a client/customer name, a system name, or \"personal\")\n     IF the members reveal one. Omit only if genuinely unknown.\n\nRULES:\n  - SIGNPOST, not table-of-contents. Do NOT list the individual members/decisions/facts.\n  - Surface only. ONE line, <= 140 characters.\n  - Base it ONLY on the MEMBERS shown. Never invent a domain or owner the members don't evidence.\n  - Plain language. No label syntax, no underscores.";
+export declare function buildDescribeInput(root: Block, members: Block[], cap: number): string;
+export declare function describeRoot(provider: LLMProvider, root: Block, members: Block[]): Promise<{
+    description: string | null;
+    rateLimited: boolean;
+    usage?: {
+        input?: number;
+        thinking?: number;
+        output?: number;
+    };
+}>;
+export interface DescriberTickResult {
+    roots_total: number;
+    roots_needing: number;
+    described: number;
+    llm_calls: number;
+    rate_limited: number;
+    errors: number;
+    wall_ms: number;
+}
+/**
+ * One describer tick: find roots needing a (re)description, describe up to
+ * `limit` of them, write essence + the lazy marker. Async (LLM). Bounded.
+ */
+export declare function runDescriberTick(opts: {
+    db: WorkspaceDB;
+    provider: LLMProvider;
+    limit?: number;
+}): Promise<DescriberTickResult>;
+/** Start the describer timer. Idempotent; returns true if started. Default OFF. */
+export declare function startDescriberTimer(db: WorkspaceDB): boolean;
+/** Stop the describer timer. Used on shutdown + by tests. */
+export declare function stopDescriberTimer(): void;
+/** For tests only — reports whether the timer is currently running. */
+export declare function _isDescriberTimerRunningForTests(): boolean;
+//# sourceMappingURL=describe-roots.d.ts.map

package/dist/middleware/reflect/describe-roots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-roots.d.ts","sourceRoot":"","sources":["../../../src/middleware/reflect/describe-roots.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAC;AAElE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AA4B/D,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,KAAK,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAED,sEAAsE;AACtE,wBAAgB,oBAAoB,CAClC,GAAG,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EAC/D,IAAI,EAAE;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,CAAA;CAAE,GACpD,KAAK,GAAG,OAAO,GAAG,MAAM,CAK1B;AAED,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,iBAAiB,EAAE,EAC3B,IAAI,EAAE;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,CAAA;CAAE,GACpD,KAAK,CAAC,iBAAiB,GAAG;IAAE,MAAM,EAAE,OAAO,GAAG,MAAM,CAAA;CAAE,CAAC,CAOzD;AAID,eAAO,MAAM,oBAAoB,yuBAYoB,CAAC;AAQtD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAerF;AAID,wBAAsB,YAAY,CAChC,QAAQ,EAAE,WAAW,EACrB,IAAI,EAAE,KAAK,EACX,OAAO,EAAE,KAAK,EAAE,GACf,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,WAAW,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC,CAc/H;AAID,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,EAAE,EAAE,WAAW,CAAC;IAChB,QAAQ,EAAE,WAAW,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAgF/B;AAwCD,mFAAmF;AACnF,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,WAAW,GAAG,OAAO,CAa5D;AAED,6DAA6D;AAC7D,wBAAgB,kBAAkB,IAAI,IAAI,CAKzC;AAED,uEAAuE;AACvE,wBAAgB,gCAAgC,IAAI,OAAO,CAE1D"}