nodedex 0.1.0

package/dist/middleware/reflect/stage-d-resolve-graph.d.ts

@@ -0,0 +1,87 @@
+import type { LLMProvider } from "../../engine/ai-provider.js";
+import type { WorkspaceDB } from "../../store/database.js";
+import type { Pass2Item } from "./types.js";
+import type { RetrievalCandidate, EntityQuery } from "./retrieve-graph-slice.js";
+export declare const STAGE_D_RESOLVE_PROMPT = "You receive ONE entity resolved from a single conversation arc, and a set of\nCANDIDATE blocks already in the graph that a retrieval step found potentially\nrelated. For each candidate, decide whether the arc entity is the SAME entity\nalready present, or a NEW entity to record separately.\n\n\u2500\u2500 STATE CONVENTION \u2500\u2500\n\"State\" = the arc entity and the candidate blocks shown below. Your training\nknowledge and what is \"commonly true\" about any domain are NOT state. An entity\nexists in the graph ONLY if a candidate block shows it. Familiarity is not record.\n\n\u2500\u2500 SCOPE BOUNDARY \u2500\u2500\nYou decide MATCH-or-NEW only. You do not name, wire relations, merge, or write.\nYour output is a resolution judgment the naming step consumes.\n\n\u2500\u2500 TWO INDEPENDENT QUESTIONS (answer SEPARATELY \u2014 collapsing them is the failure mode) \u2500\u2500\n\nQ1 \u2014 IDENTITY: Do the arc entity and the candidate describe the same underlying\nthing, or two different things that merely share a name or topic?\n  Inspect the identity-bearing content \u2014 the specific recorded values and claims,\n  not the label. A shared label with divergent content is NOT identity. Divergent\n  labels carrying the same specific content IS identity.\n\nQ2 \u2014 SCOPE: If Q1 is yes \u2014 is this the same instance under the same owner/context,\nor the same KIND of thing under a DIFFERENT owner/context?\n  Inspect the scope evidence each carries (its parent/owner, the surrounding\n  context that places it). Ask whether the scope difference reflects a genuinely\n  different owner, or whether both could be one thing recorded under two\n  organizational labels. Do not treat a difference in the scope field as decisive\n  by itself \u2014 reason about what the scope MEANS from the evidence shown. A scope\n  marked as a catch-all / unspecified bucket is owner-UNKNOWN, not owner-different.\n\n\u2500\u2500 COST ASYMMETRY AND DEFAULT \u2500\u2500\nA false MATCH fuses two distinct things into one node \u2014 it mixes owners and is\ncostly to reverse. A false NEW leaves a duplicate a later audit can still merge.\nThe directions are NOT equal. Therefore: when Q1 or Q2 cannot be answered from the\ncontent shown, default to NEW. Treat \"same entity\" as a claim you must EARN from\nthe evidence, not assume from resemblance.\n\n\u2500\u2500 FALSIFIABILITY \u2500\u2500\nEvery \"same entity\" or \"same scope\" judgment must cite the SPECIFIC content that\nsupports it \u2014 the overlapping value, the specific shared claim, the scope evidence.\nA judgment that says only \"they seem related\" without citing what overlapped fails.\n\n\u2500\u2500 DECISION \u2500\u2500\n  Q1 yes + Q2 same-scope       -> match_existing  (reuse the candidate's identity)\n  Q1 yes + Q2 different-scope   -> new_entity      (same kind, different owner)\n  Q1 yes + Q2 owner-unknown     -> match_existing  (let the naming step / review decide ownership)\n  Q1 no                         -> new_entity\n  Q1 or Q2 unanswerable         -> new_entity      (the conservative default above)\n\n\u2500\u2500 OUTPUT \u2500\u2500\nReturn JSON matching the schema: your two-axis judgment and the verdict, each with\nthe specific evidence that supports it.";
+export type StageDDecision = "attach_existing" | "new_entity" | "flag_for_review";
+export interface StageDEntityResult {
+    canonical_name: string;
+    decision: StageDDecision;
+    /** Set when decision='attach_existing' — the graph block to reuse. */
+    matched_block_id?: string;
+    matched_block_label?: string;
+    /** How the decision was reached — CODE (exact identity) or LLM (judgment). */
+    resolved_by: "code_exact" | "llm" | "no_candidates";
+    /** Why — falsifiability/audit trail. */
+    reasoning: string;
+    /** When flagged: the scope situation that triggered review. */
+    flag_reason?: string;
+}
+export declare function buildStageDInput(entity: EntityQuery, candidate: RetrievalCandidate): string;
+interface ResolverLLMOutput {
+    same_entity: boolean;
+    identity_evidence: string;
+    same_scope: "same" | "different" | "owner_unknown";
+    scope_evidence: string;
+    verdict: "match_existing" | "new_entity";
+    reasoning: string;
+}
+export declare function callStageDResolver(provider: LLMProvider, entity: EntityQuery, candidate: RetrievalCandidate): Promise<{
+    result: ResolverLLMOutput | null;
+    model?: string;
+    rateLimited: boolean;
+}>;
+export declare function decideFromResolution(same_entity: boolean, same_scope: "same" | "different" | "owner_unknown", candidate: RetrievalCandidate): {
+    decision: StageDDecision;
+    flag_reason?: string;
+};
+export interface ResolveEntityOpts {
+    db: WorkspaceDB;
+    provider: LLMProvider;
+    entity: EntityQuery;
+    /** The arc entity's own scope (the project it's being filed under this arc) —
+     *  used to decide same/different when resolving in code. */
+    arc_scope?: string;
+    k?: number;
+    /** When true, never call the LLM (verify harness / cost-free dry run). The
+     *  code-exact path still resolves; ambiguous cases return 'new_entity' with
+     *  resolved_by='code_exact' note. */
+    codeOnly?: boolean;
+    /** COST GATE: only spend an LLM call when the top candidate's identity_score
+     *  is at least this. Below it, there's no plausible duplicate worth judging →
+     *  return new_entity for free. Bounds cost to items that actually have a
+     *  candidate. Default 0.5 (a partial token-overlap ≥0.5, or any exact match). */
+    minIdentityForLLM?: number;
+}
+export declare function resolveArcEntity(opts: ResolveEntityOpts): Promise<StageDEntityResult>;
+export interface BatchResolveOpts {
+    db: WorkspaceDB;
+    provider: LLMProvider;
+    items: Pass2Item[];
+    /** Exclude items whose own (about-to-be-created) labels would self-match.
+     *  Pass the set of this-arc item labels so retrieval doesn't flag an item
+     *  against its own freshly-written sibling. */
+    thisArcItemValues?: Set<string>;
+    k?: number;
+    minIdentityForLLM?: number;
+    codeOnly?: boolean;
+}
+export interface BatchResolveEntry {
+    item_id: string;
+    decision: StageDDecision;
+    matched_block_id?: string;
+    matched_block_label?: string;
+    resolved_by: "code_exact" | "llm" | "no_candidates";
+    reasoning: string;
+    flag_reason?: string;
+}
+export interface BatchResolveResult {
+    entries: BatchResolveEntry[];
+    items_resolved: number;
+    llm_calls: number;
+    attached: number;
+    flagged: number;
+}
+export declare function resolveArcEntitiesForItems(opts: BatchResolveOpts): Promise<BatchResolveResult>;
+export {};
+//# sourceMappingURL=stage-d-resolve-graph.d.ts.map

package/dist/middleware/reflect/stage-d-resolve-graph.d.ts.map

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

package/dist/middleware/reflect/stage-d-resolve-graph.js

@@ -0,0 +1,256 @@
+// ═══════════════════════════════════════════════════════════════════════════════
+// DEBT 5 Slice 3 (Stage D) — Part 2: RESOLVE + Part 3: DECIDE
+// ═══════════════════════════════════════════════════════════════════════════════
+//
+// For each arc entity (post Stage C), decide: does it already EXIST in the graph
+// (attach), is it a NEW thing (create), or is it AMBIGUOUS (flag for review)?
+//
+// Two orthogonal axes — kept SEPARATE (the flag-reviewer Finding-C lesson: a
+// single blunt "different scope = leave" rule collapsed them and mis-fired):
+//   Q1 IDENTITY — same underlying thing? (judged on unique{} content, not label)
+//   Q2 SCOPE    — same owner, or same KIND under a DIFFERENT owner?
+//
+// Match-to-competence (Rule 3):
+//   - EXACT identity (normalized unique{} primary value equal) + decidable scope
+//     → resolved in CODE, no LLM (the "only call the model when ambiguous" saver).
+//   - Otherwise → the LLM resolver (spike-validated prompt, docs/PIPELINE-STAGE-D-
+//     SPIKE-DESIGN.md §3 — 5/6 real pairs correct).
+//
+// Catch-all scope (spike pair-5 lesson): a candidate under a catch-all dump
+// (scope.is_catch_all, detected STRUCTURALLY in retrieve-graph-slice.ts) is
+// "owner UNKNOWN", not "owner different" → DECIDE routes same-identity + catch-all
+// to FLAG, never auto-NEW.
+//
+// This module RESOLVES + DECIDES only. It does not name, write, or mutate the
+// graph — its output is consumed by the Pass 3 seam (Part 4 wiring) + the flag
+// table. (Mirrors flag-reviewer.ts's structure: input builder → LLM call →
+// telemetry → orchestrator; here the orchestrator also holds the code-first gate.)
+import { retrieveGraphSlice, normalizePrimaryValue, scopeSegmentOfLabel } from "./retrieve-graph-slice.js";
+import { extractPrimaryValue, extractPrimaryValueFromUnique } from "./dedup-by-source-and-value.js";
+import { reflectTokenStats } from "./context.js";
+import { getThinkingBudget } from "./config.js";
+const STAGE_D_MODEL_OVERRIDE = process.env.NODEDEX_STAGE_D_MODEL ?? null;
+// ─── The resolver prompt (docs/PIPELINE-STAGE-D-SPIKE-DESIGN.md §3, spike-validated) ──
+export const STAGE_D_RESOLVE_PROMPT = `You receive ONE entity resolved from a single conversation arc, and a set of
+CANDIDATE blocks already in the graph that a retrieval step found potentially
+related. For each candidate, decide whether the arc entity is the SAME entity
+already present, or a NEW entity to record separately.
+
+── STATE CONVENTION ──
+"State" = the arc entity and the candidate blocks shown below. Your training
+knowledge and what is "commonly true" about any domain are NOT state. An entity
+exists in the graph ONLY if a candidate block shows it. Familiarity is not record.
+
+── SCOPE BOUNDARY ──
+You decide MATCH-or-NEW only. You do not name, wire relations, merge, or write.
+Your output is a resolution judgment the naming step consumes.
+
+── TWO INDEPENDENT QUESTIONS (answer SEPARATELY — collapsing them is the failure mode) ──
+
+Q1 — IDENTITY: Do the arc entity and the candidate describe the same underlying
+thing, or two different things that merely share a name or topic?
+  Inspect the identity-bearing content — the specific recorded values and claims,
+  not the label. A shared label with divergent content is NOT identity. Divergent
+  labels carrying the same specific content IS identity.
+
+Q2 — SCOPE: If Q1 is yes — is this the same instance under the same owner/context,
+or the same KIND of thing under a DIFFERENT owner/context?
+  Inspect the scope evidence each carries (its parent/owner, the surrounding
+  context that places it). Ask whether the scope difference reflects a genuinely
+  different owner, or whether both could be one thing recorded under two
+  organizational labels. Do not treat a difference in the scope field as decisive
+  by itself — reason about what the scope MEANS from the evidence shown. A scope
+  marked as a catch-all / unspecified bucket is owner-UNKNOWN, not owner-different.
+
+── COST ASYMMETRY AND DEFAULT ──
+A false MATCH fuses two distinct things into one node — it mixes owners and is
+costly to reverse. A false NEW leaves a duplicate a later audit can still merge.
+The directions are NOT equal. Therefore: when Q1 or Q2 cannot be answered from the
+content shown, default to NEW. Treat "same entity" as a claim you must EARN from
+the evidence, not assume from resemblance.
+
+── FALSIFIABILITY ──
+Every "same entity" or "same scope" judgment must cite the SPECIFIC content that
+supports it — the overlapping value, the specific shared claim, the scope evidence.
+A judgment that says only "they seem related" without citing what overlapped fails.
+
+── DECISION ──
+  Q1 yes + Q2 same-scope       -> match_existing  (reuse the candidate's identity)
+  Q1 yes + Q2 different-scope   -> new_entity      (same kind, different owner)
+  Q1 yes + Q2 owner-unknown     -> match_existing  (let the naming step / review decide ownership)
+  Q1 no                         -> new_entity
+  Q1 or Q2 unanswerable         -> new_entity      (the conservative default above)
+
+── OUTPUT ──
+Return JSON matching the schema: your two-axis judgment and the verdict, each with
+the specific evidence that supports it.`;
+const STAGE_D_RESOLVE_SCHEMA = {
+    type: "object",
+    properties: {
+        same_entity: { type: "boolean" },
+        identity_evidence: { type: "string" },
+        same_scope: { type: "string", enum: ["same", "different", "owner_unknown"] },
+        scope_evidence: { type: "string" },
+        verdict: { type: "string", enum: ["match_existing", "new_entity"] },
+        reasoning: { type: "string" },
+    },
+    required: ["same_entity", "identity_evidence", "same_scope", "scope_evidence", "verdict", "reasoning"],
+};
+// ─── Input builder (mirrors flag-reviewer.buildReviewerInput) ──────────────────
+function formatCandidate(c) {
+    const b = c.block;
+    let primaryVal = "";
+    try {
+        const content = typeof b.content === "string" ? JSON.parse(b.content) : (b.content || {});
+        primaryVal = extractPrimaryValueFromUnique(b.type, content.unique || {});
+    }
+    catch { /* leave blank */ }
+    return [
+        `  candidate_block_id: ${b.id}`,
+        `  label: ${b.label}`,
+        `  type: ${b.type}`,
+        `  identity_value (unique{}): ${primaryVal || "(none)"}`,
+        `  essence: ${b.essence}`,
+        `  scope/owner: ${c.scope.value}${c.scope.is_catch_all ? " [CATCH-ALL — owner unknown, not a distinct owner]" : ""}`,
+        `  source_excerpt (evidence only): ${b.source_excerpt ?? "(none)"}`,
+    ].join("\n");
+}
+export function buildStageDInput(entity, candidate) {
+    return `── ARC ENTITY (newly resolved, seeking match) ──
+  canonical_name: ${entity.canonical_name}
+  identity_value(s) (unique{}): ${entity.primary_values.join(" | ") || "(none)"}
+  concepts: [${entity.concepts.join(", ")}]
+
+── CANDIDATE (already in graph) ──
+${formatCandidate(candidate)}
+
+Resolve per the two questions (identity, then scope). Cite specific overlap.`;
+}
+export async function callStageDResolver(provider, entity, candidate) {
+    const userInput = buildStageDInput(entity, candidate);
+    const r = await provider.generateStructured(STAGE_D_RESOLVE_PROMPT, userInput, STAGE_D_RESOLVE_SCHEMA, { thinkingBudget: getThinkingBudget(1024), maxOutputTokens: 2048, modelOverride: STAGE_D_MODEL_OVERRIDE ?? undefined });
+    if (r.usage) {
+        reflectTokenStats.pass_d_resolve.input += r.usage.input ?? 0;
+        reflectTokenStats.pass_d_resolve.thinking += r.usage.thinking ?? 0;
+        reflectTokenStats.pass_d_resolve.output += r.usage.output ?? 0;
+    }
+    reflectTokenStats.pass_d_resolve.calls += 1;
+    return { result: r.result, model: r.model, rateLimited: r.rateLimited };
+}
+// ─── DECIDE (Part 3) — map (identity, scope) → one outcome ─────────────────────
+//
+// The 3-way rule. Pure given the resolver output (or the code-exact path).
+// Catch-all scope is the load-bearing branch: same-identity under a catch-all is
+// "owner unknown" → FLAG (let review/naming decide), never auto-NEW (would
+// duplicate) and never silent-attach (would guess the owner).
+export function decideFromResolution(same_entity, same_scope, candidate) {
+    if (!same_entity)
+        return { decision: "new_entity" };
+    // same_entity === true below
+    if (same_scope === "same")
+        return { decision: "attach_existing" };
+    if (same_scope === "different")
+        return { decision: "new_entity" };
+    // owner_unknown (incl. catch-all candidate): don't guess — flag for review.
+    return {
+        decision: "flag_for_review",
+        flag_reason: candidate.scope.is_catch_all
+            ? `Same identity as ${candidate.block.label}, but its scope is a catch-all (owner unknown) — needs review to assign the real owner.`
+            : `Same identity as ${candidate.block.label}, but scope ownership is undetermined — needs review.`,
+    };
+}
+export async function resolveArcEntity(opts) {
+    const { db, provider, entity } = opts;
+    const candidates = retrieveGraphSlice(db, entity, { k: opts.k ?? 20 });
+    if (candidates.length === 0) {
+        return { canonical_name: entity.canonical_name, decision: "new_entity", resolved_by: "no_candidates",
+            reasoning: "No candidate blocks retrieved — this entity is new to the graph." };
+    }
+    const top = candidates[0];
+    const normEntityValues = entity.primary_values.map(normalizePrimaryValue).filter(Boolean);
+    // ── Code-first gate: exact identity + decidable real-owner scope ──
+    if (top.identity_score >= 1.0 && !top.scope.is_catch_all && opts.arc_scope) {
+        const sameScope = top.scope.value === opts.arc_scope;
+        return {
+            canonical_name: entity.canonical_name,
+            decision: sameScope ? "attach_existing" : "new_entity",
+            matched_block_id: sameScope ? top.block.id : undefined,
+            matched_block_label: sameScope ? top.block.label : undefined,
+            resolved_by: "code_exact",
+            reasoning: `Exact unique{} identity match with ${top.block.label}; scope ${sameScope ? `same (${opts.arc_scope})` : `differs (${opts.arc_scope} vs ${top.scope.value})`} — resolved without LLM.`,
+        };
+    }
+    // ── COST GATE: no plausible duplicate → new_entity for free, no LLM ──
+    const minForLLM = opts.minIdentityForLLM ?? 0.5;
+    if (top.identity_score < minForLLM) {
+        return { canonical_name: entity.canonical_name, decision: "new_entity", resolved_by: "no_candidates",
+            reasoning: `Top candidate ${top.block.label} identity_score ${top.identity_score.toFixed(2)} < ${minForLLM} — no plausible duplicate; new_entity without LLM.` };
+    }
+    // ── Ambiguous → LLM resolver (unless codeOnly) ──
+    if (opts.codeOnly) {
+        return { canonical_name: entity.canonical_name, decision: "new_entity", resolved_by: "code_exact",
+            reasoning: `codeOnly: top candidate ${top.block.label} not an exact-identity+real-scope match (identity=${top.identity_score.toFixed(2)}, catch_all=${top.scope.is_catch_all}); deferred to new_entity.` };
+    }
+    const r = await callStageDResolver(provider, entity, top);
+    if (!r.result) {
+        return { canonical_name: entity.canonical_name, decision: "new_entity", resolved_by: "llm",
+            reasoning: `Resolver ${r.rateLimited ? "rate-limited" : "failed"} — conservative default new_entity (false-NEW is recoverable, false-MATCH is not).` };
+    }
+    const { decision, flag_reason } = decideFromResolution(r.result.same_entity, r.result.same_scope, top);
+    // Carry the matched candidate for BOTH attach AND flag — in both, top.block is the
+    // existing block this item resolved against. attach_existing → the block to reuse;
+    // flag_for_review → the ambiguous match the agent/reviewer must adjudicate. Only
+    // new_entity has no meaningful match (left undefined). Before this, flag_for_review
+    // dropped the match → Touchpoint B wrote block_id_b=null → the flag was un-actionable
+    // (reviewer/agent had nothing to compare the new block against).
+    const matched = decision === "attach_existing" || decision === "flag_for_review";
+    return {
+        canonical_name: entity.canonical_name,
+        decision,
+        matched_block_id: matched ? top.block.id : undefined,
+        matched_block_label: matched ? top.block.label : undefined,
+        resolved_by: "llm",
+        reasoning: r.result.reasoning,
+        flag_reason,
+    };
+}
+export async function resolveArcEntitiesForItems(opts) {
+    const result = { entries: [], items_resolved: 0, llm_calls: 0, attached: 0, flagged: 0 };
+    const callsBefore = reflectTokenStats.pass_d_resolve.calls;
+    for (const item of opts.items) {
+        result.items_resolved += 1;
+        const primaryVal = extractPrimaryValue(item);
+        if (!primaryVal)
+            continue; // no identity value → nothing to resolve (e.g. project rows)
+        const arcScope = item.project ? scopeSegmentOfLabel(`${item.project}_x_y`) : undefined; // {project} as discrete owner
+        const entity = {
+            canonical_name: item.project ?? "",
+            primary_values: [primaryVal],
+            // Concepts for the FINDING step: cheap token set from the item text + value.
+            concepts: Array.from(new Set(`${item.project ?? ""} ${primaryVal}`.toLowerCase().split(/[^a-z0-9]+/).filter(t => t.length > 3))).slice(0, 12),
+        };
+        const res = await resolveArcEntity({
+            db: opts.db, provider: opts.provider, entity, arc_scope: arcScope,
+            k: opts.k, minIdentityForLLM: opts.minIdentityForLLM, codeOnly: opts.codeOnly,
+        });
+        // Only attach/flag outcomes produce a flag at Touchpoint B; new_entity is the no-op default.
+        if (res.decision === "attach_existing" || res.decision === "flag_for_review") {
+            result.entries.push({
+                item_id: item.id,
+                decision: res.decision,
+                matched_block_id: res.matched_block_id,
+                matched_block_label: res.matched_block_label,
+                resolved_by: res.resolved_by,
+                reasoning: res.reasoning,
+                flag_reason: res.flag_reason,
+            });
+            if (res.decision === "attach_existing")
+                result.attached += 1;
+            else
+                result.flagged += 1;
+        }
+    }
+    result.llm_calls = reflectTokenStats.pass_d_resolve.calls - callsBefore;
+    return result;
+}
+//# sourceMappingURL=stage-d-resolve-graph.js.map

package/dist/middleware/reflect/stage-d-resolve-graph.js.map

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

package/dist/middleware/reflect/synthesizeFromSceneCard.d.ts

@@ -0,0 +1,15 @@
+import type { Pass0Result, Pass1Item } from "./types.js";
+export interface SynthesizeOptions {
+    /** ID prefix — defaults to "syn" so synthesized items are traceable in logs. */
+    idPrefix?: string;
+}
+/**
+ * Translate each Pass 0 `replacements[]` entry into one synthesized `dead_end`
+ * Pass-1 item — the half the LLM drops.
+ *
+ * Deterministic. No LLM. Output is a flat array; caller merges it with the LLM's
+ * Pass 1 items into a single Pass1Result before handing to Pass 2. The matching
+ * `decision` is left entirely to the LLM, so the two producers never overlap.
+ */
+export declare function synthesizeFromSceneCard(sceneCard: Pass0Result, agentOutput: string, opts?: SynthesizeOptions): Pass1Item[];
+//# sourceMappingURL=synthesizeFromSceneCard.d.ts.map

package/dist/middleware/reflect/synthesizeFromSceneCard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"synthesizeFromSceneCard.d.ts","sourceRoot":"","sources":["../../../src/middleware/reflect/synthesizeFromSceneCard.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AA2CzD,MAAM,WAAW,iBAAiB;IAChC,gFAAgF;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,WAAW,EACtB,WAAW,EAAE,MAAM,EACnB,IAAI,GAAE,iBAAsB,GAC3B,SAAS,EAAE,CAwBb"}

package/dist/middleware/reflect/synthesizeFromSceneCard.js

@@ -0,0 +1,91 @@
+// Code-synthesis of the one Pass-1 item the LLM provably cannot produce reliably:
+// the dead_end half of a replacement.
+//
+// THE PROBLEM. "I went with PostgreSQL, replacing SQLite" is one sentence but two
+// events — a choice made (decision) AND a path abandoned (dead_end). Pass 1's
+// per-sentence chunking emits one item and drops the dead_end (observed
+// 2026-05-21, SQLite case). A prompt rule cannot beat chunking.
+//
+// THE SCOPE — deliberately one job. The LLM reliably extracts the *decision* half
+// of a replacement (an affirmative, single-chunk statement) and reliably *finds*
+// in-progress work. Its single proven blind spot is the dead_end half. So this
+// module synthesizes ONLY that:
+//
+//   each replacements[] entry  →  exactly one dead_end item
+//
+// It does NOT emit the decision (the LLM owns that) and does NOT emit tasks from
+// in_flight[] (the LLM finds those; Pass 2 re-verifies their type). Keeping the
+// synthesizer and the LLM on disjoint jobs is what makes duplication structurally
+// impossible — see docs/PIPELINE-REBUILD-PLAN.md, the seam-contract section.
+//
+// HONEST LIMIT. This is deterministic, but its input is not: replacements[] is
+// produced by Pass 0, an LLM. If Pass 0 mislabels an in-place update (e.g. a doc
+// revision) as a replacement, this module faithfully emits a nonsense dead_end.
+// Determinism bounds the transform, never the result. That residual is the
+// Pass 0 → synthesizer seam and is fixed upstream, not here.
+const EXCERPT_WINDOW = 150;
+const EXCERPT_PAD = Math.floor((EXCERPT_WINDOW - 60) / 2); // leave room for the matched term itself
+/**
+ * Find a ~150-char window of `agentOutput` that contains `needle` (case-insensitive).
+ * Returns the verbatim slice from the original casing. Falls back to "" if no match
+ * — acceptable per Pass1Item schema, and downstream still gets correct text/type.
+ */
+function liftExcerpt(agentOutput, needle) {
+    if (!agentOutput || !needle)
+        return "";
+    const hay = agentOutput.toLowerCase();
+    const n = needle.toLowerCase().trim();
+    if (n.length === 0)
+        return "";
+    const idx = hay.indexOf(n);
+    if (idx === -1)
+        return "";
+    const start = Math.max(0, idx - EXCERPT_PAD);
+    const end = Math.min(agentOutput.length, idx + n.length + EXCERPT_PAD);
+    let slice = agentOutput.slice(start, end);
+    if (slice.length > EXCERPT_WINDOW)
+        slice = slice.slice(0, EXCERPT_WINDOW);
+    return slice.trim();
+}
+/**
+ * Pick the most-likely-to-match needle for a replacements[] entry.
+ * Prefer the predecessor name (the abandoned thing this dead_end is about),
+ * then fall back to the replacement, then the function string.
+ */
+function pickReplacementExcerpt(agentOutput, predecessor, replacement, func) {
+    return (liftExcerpt(agentOutput, predecessor) ||
+        liftExcerpt(agentOutput, replacement) ||
+        liftExcerpt(agentOutput, func) ||
+        "");
+}
+/**
+ * Translate each Pass 0 `replacements[]` entry into one synthesized `dead_end`
+ * Pass-1 item — the half the LLM drops.
+ *
+ * Deterministic. No LLM. Output is a flat array; caller merges it with the LLM's
+ * Pass 1 items into a single Pass1Result before handing to Pass 2. The matching
+ * `decision` is left entirely to the LLM, so the two producers never overlap.
+ */
+export function synthesizeFromSceneCard(sceneCard, agentOutput, opts = {}) {
+    const items = [];
+    const prefix = opts.idPrefix ?? "syn";
+    let seq = 1;
+    // ── REPLACEMENTS → one dead_end each ────────────────────────────────────────
+    // The decision half is the LLM's job (it never misses it). Emitting it here too
+    // would duplicate. The dead_end is the LLM's blind spot — so it is ours, alone.
+    for (const r of sceneCard.replacements ?? []) {
+        if (!r?.predecessor || !r?.replacement || !r?.function)
+            continue;
+        const { predecessor, replacement, function: func } = r;
+        items.push({
+            id: `${prefix}_${seq++}`,
+            text: `${predecessor} was abandoned as the ${func}, replaced by ${replacement}`,
+            source: "output",
+            excerpt: pickReplacementExcerpt(agentOutput, predecessor, replacement, func),
+            provisional_type: "dead_end",
+            extraction_reasoning: "Synthesized from scene card replacements[] entry (predecessor abandoned in real use).",
+        });
+    }
+    return items;
+}
+//# sourceMappingURL=synthesizeFromSceneCard.js.map

package/dist/middleware/reflect/synthesizeFromSceneCard.js.map

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