nodedex 0.1.0

package/dist/middleware/reflect/pass1.js

@@ -0,0 +1,241 @@
+import { reflectTokenStats } from "./context.js";
+import { getThinkingBudget, modelForPass } from "./config.js";
+import { withOverride } from "./promptOverride.js";
+// ═══════════════════════════════════════════════════════════════════════════════
+// PASS 1 — EXTRACT
+// Job: find every discrete piece of information in the agent's output.
+// Assigns provisional types using scene card APPROACHES context as primary signal.
+// Runs BACKWARD TRACE and CONTRAST CHECK after every decision extraction.
+// Tuned for recall — a missed item is gone forever; a wrong type is fixable in Pass 2.
+// ═══════════════════════════════════════════════════════════════════════════════
+export const PASS1_PROMPT = withOverride("NODEDEX_TEST_PROMPT_PASS1", `You receive raw agent output — thinking and final response from an AI assistant.
+For each passage, read it in two steps, then decide whether to keep it.
+
+── STATE CONVENTION ─────────────────────────────────────────────────────────
+"State" in this prompt = text in marked regions below (SCENE CARD, RECENTLY SAVED,
+OPEN BLUEPRINTS, AGENT THINKING, AGENT OUTPUT). Your training knowledge and
+"what's commonly known" are NOT state. When you skip an item as redundant with
+RECENTLY SAVED, you must be able to quote the matching entry. Familiarity ≠ recorded.
+
+── THINKING vs OUTPUT ──────────────────────────────────────────────────────
+Same session, two angles. If the same event appears in both → extract ONCE from OUTPUT.
+Only extract from thinking when it contains information NOT present in output.
+Ask: "Does the output already capture this event, even in different words?"
+  YES → skip. NO → extract from thinking.
+
+── SCENE CARD CONTEXT (if provided) ────────────────────────────────────────
+The scene card describes what was observed — it does not assign types.
+The scene card is NOT a substitute for extraction. Every discrete claim in the
+transcript must still be extracted as its own item — the scene card provides context
+for classification (engagement level, source tagging), not content to be saved.
+Use it as INPUT CONTEXT when answering the classification tree below:
+  APPROACHES descriptions → consult at Q3b for engagement level.
+  REPLACEMENTS → predecessors have confirmed engagement (Q3b = YES).
+  UNCHANGED entries / resolved APPROACHES → source = "recap".
+  TASKS entries → extract as task. CAUSAL LINKS → consult at backward trace.
+  OPEN BLUEPRINTS → if passage shows one completing → extract as decision.
+When scene card conflicts with transcript text → trust the transcript.
+
+── GATE ────────────────────────────────────────────────────────────────────
+"Would a future agent reading only this block learn something that changes
+what they should do or avoid?"
+  YES → enter the classification tree.
+  NO  → skip this passage entirely.
+Core types (decision, dead_end, constraint, blueprint, preference) always pass.
+Tasks pass IF: "Would a future agent's approach change knowing this exists?"
+
+── CLASSIFICATION TREE — Q1 through Q7 ────────────────────────────────────
+Answer YES or NO from passage text alone. Stop at the first YES.
+Write the full Q1…Qn trace in extraction_reasoning before provisional_type.
+
+Q1: Are two values of the same measured quantity named — a starting state and a
+    later state — where the CHANGE between them is what is being reported?
+    YES → metric (always its own item, even co-located with a decision).
+    NO  → Q2.
+
+Q2: Is something stated as an expected answer or proposed mechanism that had
+    not yet been confirmed or denied when put forward?
+    YES → hypothesis (extract even if same passage reports the outcome).
+    NO  → Q3.
+
+Q3: Is something recorded as closed off, committed to, or imposed from outside?
+    YES → Q3a–Q3d in order, stop at first YES:
+
+      Q3a: Closure set by something outside those involved (rule, law, policy)?
+           YES → constraint.
+
+      Q3b: Were resources committed INSIDE this approach before it was closed?
+           Test: "If I removed the closing event, would there be active work to stop?"
+           The scene card's APPROACHES section states each approach's engagement
+           level. Actual use, a trial, or a structured evaluation count as
+           committed resources. A suggestion raised and dropped without any trial
+           does not. Judge from the engagement the APPROACHES entry describes.
+           YES → dead_end. NO → Q3c.
+
+      Q3c: Was a specific outcome selected, AND IS THIS ITEM the selected outcome
+           (not a competing alternative that was considered and rejected)?
+           YES → decision. (Pending implementation ≠ unmade choice.)
+           NO  → Q3d. An item naming a rejected/considered alternative is NOT a
+                 decision even if a decision was made elsewhere this session.
+                 If engagement existed for this alternative, Q3b above would have
+                 caught it as dead_end. If no engagement, it falls through to Q7
+                 (fact). REDUNDANCY check at KEEP OR SKIP applies after the tree.
+
+      Q3d: Was a specific path committed to, but destination still unknown?
+           YES → blueprint. (Brainstorming/non-binding → Q4.)
+
+      Q3a–Q3d all NO → Q4.
+    NO  → Q4.
+
+Q4: Something left open and unresolved, no path committed to resolving it?
+    YES → question. (Pure affirmation with no subject → skip.)
+    NO  → Q5.
+
+Q5: Specific work actively assigned or already underway right now?
+    YES → task. NO → Q6.
+
+Q6: A standing direction that shapes repeated situations, not a one-time choice?
+    YES → preference. NO → Q7.
+
+Q7: Q7a: Discrete occurrence at a specific point in time? YES → event.
+    Q7b: Conclusion combining 2+ things not directly connected before? YES → insight.
+    Otherwise → fact.
+
+── POST-TYPE RULES — implied additional roles ──────────────────────────────
+
+A single passage can carry multiple distinct claims that play different roles
+in agent reasoning. After assigning the primary type, check whether the passage
+also carries a second role; if so, extract a second item for that role and link
+it with based_on. Different roles → different blocks, related by causality.
+
+type = decision:
+  BACKWARD TRACE (mandatory): "What was in active use before this?"
+    Check scene card CAUSAL LINKS. Produce one of:
+      Predecessor + engagement confirmed → extract dead_end
+      Predecessor + engagement unclear → extract dead_end (uncertain = true)
+      Greenfield (no replacement language) → nothing
+  CONTRAST CHECK: "Competing path genuinely weighed but not chosen?"
+    YES + engagement → dead_end. YES + speculative → fact. YES + unclear → dead_end (uncertain).
+  TWO-LEVEL: "Also describes HOW?" YES → extract detail item (extends_id = this item).
+
+type = dead_end:
+  ENGAGEMENT: "Work done INSIDE this path?" No → reclassify as fact. From REPLACEMENTS → skip check.
+  "Also ruled out by external rule?" YES → also extract constraint.
+
+type = blueprint: "Also announces a committed outcome?" YES → also extract decision.
+type = hypothesis: "Same passage reports the finding?" YES → also extract fact.
+type = constraint: "Excluded option also previously tried?" YES → also extract dead_end.
+
+type = fact OR insight:
+  IMPLIED-CONSTRAINT CHECK (mandatory):
+  "If the project accepted this item as true, does it make any choice the
+   project could otherwise have made unavailable — or force a specific choice
+   that would otherwise have been open?"
+
+    YES → also extract constraint, linked to this item via based_on.
+          Fill unique{} per the constraint schema, drawing the limit, reason,
+          and source from the item's content as stated.
+    NO → no additional item.
+
+── KEEP OR SKIP ────────────────────────────────────────────────────────────
+REDUNDANCY: "Can this content be recovered from another item?" YES → skip.
+Always keep: core types (decision, dead_end, constraint, blueprint, preference).
+Always keep: state snapshots with concrete measured values.
+fact → keep if specific value/finding. Skip if vague. question → keep if unresolved.
+Skip: agent narration, pure logistics, exact re-statements of RECENTLY SAVED
+  (same claim AND same values). If a value has CHANGED → extract as new item.
+
+SKIP EVIDENCE: A skip claim that cites RECENTLY SAVED must reference the
+matching label/value visible in that section. If RECENTLY SAVED is empty or
+the claim cannot be quoted from it, you may NOT skip on that grounds.
+
+── EXTRACTION RULES ────────────────────────────────────────────────────────
+1. One outcome = one item. "X failed, adopted Y" → TWO items.
+2. Two-level: commitment + detail → two items. extends_id test:
+   "If I deleted Item A, would Item B make sense standalone?" NO → extends_id.
+3. Preserve exact quotes, names, numbers verbatim.
+4. source: "output" | "thinking" (from thinking only) | "recap" (UNCHANGED/resolved).
+5. Item IDs: item_1, item_2, … Never block-label format.
+6. uncertain = true for core types with incomplete context. Never on fact/question/task.
+7. extraction_reasoning — REQUIRED. Format:
+     "<Q-tree trace> → <Q-tree type>. [post-type rules]: <fired rule(s) + verdict, or 'none'>. [final]: <type>."
+   Example: "Q1=NO. Q2=NO. Q3=YES. Q3b=YES → dead_end. [post-type rules]: ENGAGEMENT=no → revise to fact. [final]: fact."
+8. provisional_type = the [final] type from the trace — NOT the Q-tree's intermediate output.
+   Post-type rules can REVISE this item's type (e.g. dead_end ENGAGEMENT check → fact).
+   Post-type rules that ADD SEPARATE items (BACKWARD TRACE → separate predecessor dead_end,
+   IMPLIED-CONSTRAINT → separate companion constraint, CONTRAST → separate dead_end, etc.)
+   produce ADDITIONAL items with their own provisional_type; they do NOT alter THIS item's
+   provisional_type. Read each post-type rule carefully: "extract X" with a SEPARATE subject
+   means add an item; "revise to X" or "reclassify as X" means change this item's type.
+`);
+const PASS1_SCHEMA = {
+    type: "object",
+    properties: {
+        items: {
+            type: "array",
+            items: {
+                type: "object",
+                properties: {
+                    id: { type: "string" },
+                    text: { type: "string" },
+                    source: { type: "string" },
+                    excerpt: { type: "string" },
+                    extraction_reasoning: { type: "string" },
+                    provisional_type: { type: "string" },
+                    extends_id: { type: "string" },
+                    uncertain: { type: "boolean" },
+                },
+                required: ["id", "text", "source", "excerpt", "extraction_reasoning", "provisional_type"],
+            },
+        },
+    },
+    required: ["items"],
+};
+// Appended ONLY when a USER turn is present (NODEDEX_EXTRACT_ALL_SOURCES on). Frames
+// the user's turn for PASS 1's job — RECALL is source-agnostic; the user is a source
+// of claims (decisions/constraints/preferences/lived attempts), equal to the agent.
+const PASS1_TWO_PARTY_SUFFIX = `
+
+── TWO-PARTY INPUT (a USER turn is present) ────────────────────────────────
+Extract claims from BOTH the USER turn and the AGENT turn — recall is source-agnostic.
+The USER turn is frequently where a decision, constraint, preference, or lived attempt
+ORIGINATES ("use X not Y", "must be Z", "I tried W and it failed"); the agent's reply
+often only elaborates or confirms it. Do not privilege the agent's wording. Attribute
+each item to what was actually said, and put the verbatim source span in the excerpt
+field regardless of which party said it.`;
+export async function callPass1LLM(provider, agentThinking, agentOutput, recentSaves, sceneCard, openBlueprints = [], userMessage = "") {
+    const sceneCardSection = sceneCard
+        ? `SCENE CARD (use to guide extraction):\n${sceneCard}\n\n---\n\n`
+        : "";
+    const recentSection = recentSaves
+        ? `RECENTLY SAVED THIS SESSION (do not re-extract these):\n${recentSaves}\n\n---\n\n`
+        : "";
+    const blueprintSection = openBlueprints.length > 0
+        ? `OPEN BLUEPRINTS (from graph — if any appear as completed or deployed in this session, extract as decision and include the blueprint label in item text for Pass 2 to set supersedes_ref):\n${openBlueprints.map(b => `- ${b.label}: "${b.essence}"`).join("\n")}\n\n---\n\n`
+        : "";
+    const thinkingSection = agentThinking
+        ? `AGENT THINKING:\n${agentThinking}\n\n---\n\n`
+        : "";
+    const userSection = userMessage && userMessage.trim()
+        ? `USER:\n${userMessage}\n\n---\n\n`
+        : "";
+    const userInput = `${sceneCardSection}${recentSection}${blueprintSection}${userSection}${thinkingSection}AGENT OUTPUT:\n${agentOutput}`;
+    const p1Prompt = userSection ? PASS1_PROMPT + PASS1_TWO_PARTY_SUFFIX : PASS1_PROMPT;
+    const r = await provider.generateStructured(p1Prompt, userInput, PASS1_SCHEMA, { thinkingBudget: getThinkingBudget(1024), maxOutputTokens: 16384, modelOverride: modelForPass("pass1") });
+    if (r.result) {
+        reflectTokenStats.pass1.input += r.usage?.input ?? 0;
+        reflectTokenStats.pass1.thinking += r.usage?.thinking ?? 0;
+        reflectTokenStats.pass1.output += r.usage?.output ?? 0;
+        reflectTokenStats.pass1.calls += 1;
+        const tag = provider.getName() !== "gemini" ? ` [${provider.getName()}]` : "";
+        console.log(`Auto-Reflect Pass 1: ${r.result.items.length} item(s) extracted | tokens: ${r.usage?.input ?? "?"}→${r.usage?.output ?? "?"}${tag}`);
+        for (const item of r.result.items) {
+            console.log(`  [Pass 1 item] ${item.id} provisional_type=${item.provisional_type} text="${item.text.slice(0, 80)}"`);
+        }
+    }
+    else {
+        console.error(`Auto-Reflect Pass 1: ${r.rateLimited ? "rate limited" : "failed"} [${provider.getName()}]`);
+    }
+    return { result: r.result, thinking: r.thinking ?? "", rateLimited: r.rateLimited, model: r.model, attempts: r.attempts };
+}
+//# sourceMappingURL=pass1.js.map

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

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

package/dist/middleware/reflect/pass2-quarantine.d.ts

@@ -0,0 +1,129 @@
+import type Database from "better-sqlite3";
+/**
+ * Full quarantine entry shape per PASS2-SPLIT-DESIGN.md §3.
+ *
+ * Origin fields (from Pass 1): immutable after first write.
+ * 2a fields: populated by Pass 2a's classify attempt.
+ * 2b fields: populated by Pass 2b's fill attempt.
+ * Retry fields: filled if the seam tried route-back to 2a.
+ * Enrichment fields: managed by future debt 2 work.
+ * agent_clarification: reserved for debt 2b (agent-in-the-loop).
+ */
+export interface QuarantineEntry {
+    id: string;
+    pass1_text: string;
+    pass1_provisional_type: string;
+    pass1_reasoning: string | null;
+    pass1_excerpt: string | null;
+    pass2a_classified: string;
+    pass2a_reasoning: string;
+    pass2a_alternatives: string[];
+    pass2b_attempted: Record<string, unknown>;
+    pass2b_failure_reason: string;
+    retry_attempted: boolean;
+    retry_2a_classified: string | null;
+    retry_outcome: "success" | "different_type_quarantined" | "same_type_quarantined" | null;
+    batch_id: string;
+    source_session_id: string;
+    quarantined_at: string;
+    siblings_promoted: string[];
+    queued_for_enrichment: boolean;
+    enrichment_attempts: Array<{
+        when: string;
+        pass_used: string;
+        outcome: string;
+    }>;
+    promotion_blocked_until: string | null;
+    agent_clarification: {
+        resolved_at: string;
+        agent_verdict: string;
+        agent_notes: string;
+    } | null;
+}
+/**
+ * Filter parameters for `getQuarantineEntries`. All optional; AND-combined.
+ */
+export interface QuarantineFilters {
+    project?: string;
+    failure_reason?: string;
+    batch_id?: string;
+    source_session_id?: string;
+    queued_for_enrichment?: boolean;
+}
+/**
+ * Create the quarantine table if it doesn't exist. Safe to call repeatedly
+ * (CREATE IF NOT EXISTS + indexes are idempotent).
+ *
+ * Caller responsibility: invoke once at server boot or test setup. Writers do
+ * NOT auto-create the table — they assume it exists. This keeps the call graph
+ * predictable (no silent side effects in hot paths).
+ *
+ * The audit-trail fields are stored as TEXT (JSON-serialized) so the shape can
+ * evolve without per-field column adds. SQLite JSON1 functions can query into
+ * them if we ever need composition analysis (debt-3 work).
+ */
+export declare function ensureQuarantineTable(db: Database.Database): void;
+/**
+ * Insert a new quarantine entry. Throws if `id` already exists (writes are
+ * additive — re-quarantining the same id is a logic error in the caller, not
+ * something this module silently handles).
+ *
+ * The caller (typically `pass2-seams.ts`) is responsible for assembling the
+ * full audit trail before calling this — see `QuarantineEntry` shape.
+ */
+export declare function writeQuarantineEntry(db: Database.Database, entry: QuarantineEntry): void;
+/**
+ * Record an enrichment attempt — appends to enrichment_attempts[] without
+ * touching other fields. Used by future debt 2a (pipeline self-enrichment).
+ */
+export declare function recordEnrichmentAttempt(db: Database.Database, id: string, attempt: {
+    when: string;
+    pass_used: string;
+    outcome: string;
+}, options?: {
+    newQueuedFlag?: boolean;
+    newBlockedUntil?: string | null;
+}): void;
+/**
+ * Mark a quarantine entry as PROMOTED — caller has already created a live
+ * block from this candidate. Future enrichment will not pick it up again.
+ *
+ * Does NOT delete the row — the audit trail stays for inspection.
+ * Records the promotion as the final enrichment_attempts entry with
+ * `outcome: "promoted_to:<block_id>"`.
+ */
+export declare function markQuarantinePromoted(db: Database.Database, id: string, promotedBlockId: string): void;
+/**
+ * Fetch a single quarantine entry by its Pass 1 item id. Returns `null` if
+ * not found.
+ */
+export declare function getQuarantineEntry(db: Database.Database, id: string): QuarantineEntry | null;
+/**
+ * List quarantine entries matching the given filters. All filters are optional
+ * and AND-combined. Sorted by `quarantined_at` DESC (most recent first).
+ *
+ * `failure_reason` is a SUBSTRING match (LIKE %term%) — useful for finding all
+ * entries with a specific failure pattern (e.g. "missing=[implication]") which
+ * is the debt-3 composition-shift signal from §3.
+ */
+export declare function getQuarantineEntries(db: Database.Database, filters?: QuarantineFilters): QuarantineEntry[];
+/**
+ * Count quarantine entries — cheap aggregate for the tier-based signal monitor
+ * referenced in §3. Returns total + grouped-by-failure_reason for composition
+ * analysis.
+ *
+ * NOTE: this is the lowest-level primitive. Tier interpretation (Watch / Notice
+ * / Investigate / Rollback per §3) lives in the telemetry layer, not here.
+ */
+export declare function summarizeQuarantine(db: Database.Database): {
+    total: number;
+    by_failure_reason: Array<{
+        reason: string;
+        count: number;
+    }>;
+    by_session: Array<{
+        session_id: string;
+        count: number;
+    }>;
+};
+//# sourceMappingURL=pass2-quarantine.d.ts.map

package/dist/middleware/reflect/pass2-quarantine.d.ts.map

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

package/dist/middleware/reflect/pass2-quarantine.js

@@ -0,0 +1,272 @@
+// ═══════════════════════════════════════════════════════════════════════════════
+// PASS 2 AUDIT QUARANTINE — Week 1, debt #1 (2026-05-25)
+//
+// Role:  When Pass 2's split-mode seam validation (§3 of PASS2-SPLIT-DESIGN.md)
+//        cannot resolve a candidate into a valid block — after one retry — the
+//        candidate is preserved here with its full audit trail. NEVER lost,
+//        NEVER ships to the live graph as a flagged-block.
+//
+// Design choices (locked 2026-05-25):
+//   - SEPARATE TABLE `pass2_audit_quarantine`, not `blocks.status='quarantined'`.
+//     Reason: prevents silent leakage into existing `getAllBlocks()` and other
+//     unfiltered queries. Default agent navigation can ONLY reach quarantine via
+//     explicit `/api/quarantine` endpoints — the visibility contract from §3 is
+//     enforced structurally, not by remembering to add WHERE-clauses.
+//   - NO absolute size limit. Tier-based signal monitoring only (§3).
+//   - `agent_clarification` field is a RESERVED slot for debt 2b (future); writers
+//     leave it null. Future enrichment passes will populate it.
+//
+// What this module does NOT do:
+//   - It does NOT decide what to quarantine — that's `pass2-seams.ts`.
+//   - It does NOT call any LLM.
+//   - It does NOT mutate live blocks (`blocks` table).
+//   - It does NOT do composition analysis or tier-signal alerts — those live in
+//     a future telemetry layer; this module just stores and retrieves.
+//
+// Charter alignment:
+//   - Rule 2 (never delete vetted blocks): quarantine entries aren't blocks; they
+//     are candidates that failed the gate. The seam decides whether a candidate
+//     becomes a block. Quarantine preserves the rest.
+//   - Rule 6 (guards catch failure, never override success): writes are additive;
+//     existing blocks are never touched by quarantine code paths.
+//   - Rule 14 (store the path): the full audit trail (Pass 1 text, Pass 2a
+//     classification reasoning, Pass 2b attempt, failure reason, retry status)
+//     is preserved so a future session can reason about what happened.
+// ═══════════════════════════════════════════════════════════════════════════════
+// ─── Schema migration ──────────────────────────────────────────────────────────
+/**
+ * Create the quarantine table if it doesn't exist. Safe to call repeatedly
+ * (CREATE IF NOT EXISTS + indexes are idempotent).
+ *
+ * Caller responsibility: invoke once at server boot or test setup. Writers do
+ * NOT auto-create the table — they assume it exists. This keeps the call graph
+ * predictable (no silent side effects in hot paths).
+ *
+ * The audit-trail fields are stored as TEXT (JSON-serialized) so the shape can
+ * evolve without per-field column adds. SQLite JSON1 functions can query into
+ * them if we ever need composition analysis (debt-3 work).
+ */
+export function ensureQuarantineTable(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS pass2_audit_quarantine (
+      id                          TEXT PRIMARY KEY,
+      pass1_text                  TEXT NOT NULL,
+      pass1_provisional_type      TEXT NOT NULL,
+      pass1_reasoning             TEXT,
+      pass1_excerpt               TEXT,
+
+      pass2a_classified           TEXT NOT NULL,
+      pass2a_reasoning            TEXT NOT NULL,
+      pass2a_alternatives         TEXT NOT NULL DEFAULT '[]',  -- JSON array
+
+      pass2b_attempted            TEXT NOT NULL DEFAULT '{}',  -- JSON object
+      pass2b_failure_reason       TEXT NOT NULL,
+
+      retry_attempted             INTEGER NOT NULL DEFAULT 0,  -- boolean
+      retry_2a_classified         TEXT,
+      retry_outcome               TEXT,                        -- nullable enum
+
+      batch_id                    TEXT NOT NULL,
+      source_session_id           TEXT NOT NULL,
+      quarantined_at              TEXT NOT NULL,
+      siblings_promoted           TEXT NOT NULL DEFAULT '[]',  -- JSON array of block ids
+
+      queued_for_enrichment       INTEGER NOT NULL DEFAULT 1,  -- boolean
+      enrichment_attempts         TEXT NOT NULL DEFAULT '[]',  -- JSON array
+      promotion_blocked_until     TEXT,                        -- nullable ISO ts
+
+      agent_clarification         TEXT                         -- nullable JSON object
+    )
+  `);
+    db.exec(`CREATE INDEX IF NOT EXISTS idx_quarantine_batch       ON pass2_audit_quarantine(batch_id)`);
+    db.exec(`CREATE INDEX IF NOT EXISTS idx_quarantine_session     ON pass2_audit_quarantine(source_session_id)`);
+    db.exec(`CREATE INDEX IF NOT EXISTS idx_quarantine_queued      ON pass2_audit_quarantine(queued_for_enrichment)`);
+    db.exec(`CREATE INDEX IF NOT EXISTS idx_quarantine_quarantined ON pass2_audit_quarantine(quarantined_at)`);
+}
+// ─── Writers ───────────────────────────────────────────────────────────────────
+/**
+ * Insert a new quarantine entry. Throws if `id` already exists (writes are
+ * additive — re-quarantining the same id is a logic error in the caller, not
+ * something this module silently handles).
+ *
+ * The caller (typically `pass2-seams.ts`) is responsible for assembling the
+ * full audit trail before calling this — see `QuarantineEntry` shape.
+ */
+export function writeQuarantineEntry(db, entry) {
+    const stmt = db.prepare(`
+    INSERT INTO pass2_audit_quarantine (
+      id, pass1_text, pass1_provisional_type, pass1_reasoning, pass1_excerpt,
+      pass2a_classified, pass2a_reasoning, pass2a_alternatives,
+      pass2b_attempted, pass2b_failure_reason,
+      retry_attempted, retry_2a_classified, retry_outcome,
+      batch_id, source_session_id, quarantined_at, siblings_promoted,
+      queued_for_enrichment, enrichment_attempts, promotion_blocked_until,
+      agent_clarification
+    ) VALUES (
+      @id, @pass1_text, @pass1_provisional_type, @pass1_reasoning, @pass1_excerpt,
+      @pass2a_classified, @pass2a_reasoning, @pass2a_alternatives,
+      @pass2b_attempted, @pass2b_failure_reason,
+      @retry_attempted, @retry_2a_classified, @retry_outcome,
+      @batch_id, @source_session_id, @quarantined_at, @siblings_promoted,
+      @queued_for_enrichment, @enrichment_attempts, @promotion_blocked_until,
+      @agent_clarification
+    )
+  `);
+    stmt.run({
+        id: entry.id,
+        pass1_text: entry.pass1_text,
+        pass1_provisional_type: entry.pass1_provisional_type,
+        pass1_reasoning: entry.pass1_reasoning,
+        pass1_excerpt: entry.pass1_excerpt,
+        pass2a_classified: entry.pass2a_classified,
+        pass2a_reasoning: entry.pass2a_reasoning,
+        pass2a_alternatives: JSON.stringify(entry.pass2a_alternatives ?? []),
+        pass2b_attempted: JSON.stringify(entry.pass2b_attempted ?? {}),
+        pass2b_failure_reason: entry.pass2b_failure_reason,
+        retry_attempted: entry.retry_attempted ? 1 : 0,
+        retry_2a_classified: entry.retry_2a_classified,
+        retry_outcome: entry.retry_outcome,
+        batch_id: entry.batch_id,
+        source_session_id: entry.source_session_id,
+        quarantined_at: entry.quarantined_at,
+        siblings_promoted: JSON.stringify(entry.siblings_promoted ?? []),
+        queued_for_enrichment: entry.queued_for_enrichment ? 1 : 0,
+        enrichment_attempts: JSON.stringify(entry.enrichment_attempts ?? []),
+        promotion_blocked_until: entry.promotion_blocked_until,
+        agent_clarification: entry.agent_clarification
+            ? JSON.stringify(entry.agent_clarification)
+            : null,
+    });
+}
+/**
+ * Record an enrichment attempt — appends to enrichment_attempts[] without
+ * touching other fields. Used by future debt 2a (pipeline self-enrichment).
+ */
+export function recordEnrichmentAttempt(db, id, attempt, options) {
+    const row = getQuarantineEntry(db, id);
+    if (!row)
+        throw new Error(`recordEnrichmentAttempt: no quarantine entry ${id}`);
+    const updated = [...row.enrichment_attempts, attempt];
+    db.prepare(`
+    UPDATE pass2_audit_quarantine
+    SET enrichment_attempts      = @attempts,
+        queued_for_enrichment    = @queued,
+        promotion_blocked_until  = @blocked
+    WHERE id = @id
+  `).run({
+        id,
+        attempts: JSON.stringify(updated),
+        queued: (options?.newQueuedFlag ?? row.queued_for_enrichment) ? 1 : 0,
+        blocked: options?.newBlockedUntil ?? row.promotion_blocked_until,
+    });
+}
+/**
+ * Mark a quarantine entry as PROMOTED — caller has already created a live
+ * block from this candidate. Future enrichment will not pick it up again.
+ *
+ * Does NOT delete the row — the audit trail stays for inspection.
+ * Records the promotion as the final enrichment_attempts entry with
+ * `outcome: "promoted_to:<block_id>"`.
+ */
+export function markQuarantinePromoted(db, id, promotedBlockId) {
+    recordEnrichmentAttempt(db, id, { when: new Date().toISOString(), pass_used: "manual_or_enrichment", outcome: `promoted_to:${promotedBlockId}` }, { newQueuedFlag: false, newBlockedUntil: null });
+}
+function rowToEntry(row) {
+    return {
+        id: row.id,
+        pass1_text: row.pass1_text,
+        pass1_provisional_type: row.pass1_provisional_type,
+        pass1_reasoning: row.pass1_reasoning,
+        pass1_excerpt: row.pass1_excerpt,
+        pass2a_classified: row.pass2a_classified,
+        pass2a_reasoning: row.pass2a_reasoning,
+        pass2a_alternatives: JSON.parse(row.pass2a_alternatives || "[]"),
+        pass2b_attempted: JSON.parse(row.pass2b_attempted || "{}"),
+        pass2b_failure_reason: row.pass2b_failure_reason,
+        retry_attempted: row.retry_attempted === 1,
+        retry_2a_classified: row.retry_2a_classified,
+        retry_outcome: row.retry_outcome,
+        batch_id: row.batch_id,
+        source_session_id: row.source_session_id,
+        quarantined_at: row.quarantined_at,
+        siblings_promoted: JSON.parse(row.siblings_promoted || "[]"),
+        queued_for_enrichment: row.queued_for_enrichment === 1,
+        enrichment_attempts: JSON.parse(row.enrichment_attempts || "[]"),
+        promotion_blocked_until: row.promotion_blocked_until,
+        agent_clarification: row.agent_clarification ? JSON.parse(row.agent_clarification) : null,
+    };
+}
+/**
+ * Fetch a single quarantine entry by its Pass 1 item id. Returns `null` if
+ * not found.
+ */
+export function getQuarantineEntry(db, id) {
+    const row = db.prepare(`SELECT * FROM pass2_audit_quarantine WHERE id = ?`).get(id);
+    if (!row)
+        return null;
+    return rowToEntry(row);
+}
+/**
+ * List quarantine entries matching the given filters. All filters are optional
+ * and AND-combined. Sorted by `quarantined_at` DESC (most recent first).
+ *
+ * `failure_reason` is a SUBSTRING match (LIKE %term%) — useful for finding all
+ * entries with a specific failure pattern (e.g. "missing=[implication]") which
+ * is the debt-3 composition-shift signal from §3.
+ */
+export function getQuarantineEntries(db, filters = {}) {
+    const where = [];
+    const params = {};
+    if (filters.batch_id !== undefined) {
+        where.push("batch_id = @batch_id");
+        params.batch_id = filters.batch_id;
+    }
+    if (filters.source_session_id !== undefined) {
+        where.push("source_session_id = @session");
+        params.session = filters.source_session_id;
+    }
+    if (filters.queued_for_enrichment !== undefined) {
+        where.push("queued_for_enrichment = @queued");
+        params.queued = filters.queued_for_enrichment ? 1 : 0;
+    }
+    if (filters.failure_reason !== undefined) {
+        where.push("pass2b_failure_reason LIKE @reason");
+        params.reason = `%${filters.failure_reason}%`;
+    }
+    // `project` filter is intentionally NOT implemented yet — quarantine entries
+    // don't carry a project column. If we need this, add a project column to the
+    // entry shape (Pass 2a does emit a project — pipe it through). Defer until
+    // there's a real use case.
+    const whereSql = where.length > 0 ? `WHERE ${where.join(" AND ")}` : "";
+    const rows = db.prepare(`SELECT * FROM pass2_audit_quarantine ${whereSql} ORDER BY quarantined_at DESC`).all(params);
+    return rows.map(rowToEntry);
+}
+/**
+ * Count quarantine entries — cheap aggregate for the tier-based signal monitor
+ * referenced in §3. Returns total + grouped-by-failure_reason for composition
+ * analysis.
+ *
+ * NOTE: this is the lowest-level primitive. Tier interpretation (Watch / Notice
+ * / Investigate / Rollback per §3) lives in the telemetry layer, not here.
+ */
+export function summarizeQuarantine(db) {
+    const total = db.prepare(`SELECT COUNT(*) AS n FROM pass2_audit_quarantine`).get().n;
+    const byReason = db.prepare(`
+    SELECT pass2b_failure_reason AS reason, COUNT(*) AS n
+    FROM pass2_audit_quarantine
+    GROUP BY pass2b_failure_reason
+    ORDER BY n DESC
+  `).all();
+    const bySession = db.prepare(`
+    SELECT source_session_id AS session_id, COUNT(*) AS n
+    FROM pass2_audit_quarantine
+    GROUP BY source_session_id
+    ORDER BY n DESC
+  `).all();
+    return {
+        total,
+        by_failure_reason: byReason.map((r) => ({ reason: r.reason, count: r.n })),
+        by_session: bySession.map((r) => ({ session_id: r.session_id, count: r.n })),
+    };
+}
+//# sourceMappingURL=pass2-quarantine.js.map