nodedex 0.1.0

package/dist/middleware/reflect/recognize-root.js

@@ -0,0 +1,204 @@
+// ═══════════════════════════════════════════════════════════════════════════════
+// Recognition Layer — STEP 2: THE RECOGNIZER ("Stage D for roots")
+// ═══════════════════════════════════════════════════════════════════════════════
+//
+// Design: docs/PIPELINE-RECOGNITION-LAYER-DESIGN.md §2 (LLM-primary spine) + §3.
+//
+// JOB: for each NEW project-root candidate an arc would create, decide — does
+// this cluster of new knowledge actually belong to an EXISTING root? One LLM
+// judgment over (the new cluster's content) + (the candidate roots' DESCRIPTIONS
+// + scope). Verdict: attach / new / uncertain.
+//
+// HOOK: runs in pipeline.ts right after applyArcEntityCanonicalNames (the seam
+// where Stage C's canonical names are written onto items, BEFORE Pass 3). On a
+// confident ATTACH it rewrites the cluster's items' .project to the existing
+// root's EXACT label → Pass 3's root-create exact-match finds it → blocks attach,
+// no fork. Default OFF (NODEDEX_RECOGNIZER_ENABLED=1), arc-mode only.
+//
+// THE 6 GUARDS (§2 — non-negotiable; without them this is a silent-merge risk):
+//   1. judges against the root DESCRIPTION (essence), not the raw label string
+//   2. SCOPE/OWNER is an explicit axis — same domain AND same owner to attach
+//   3. cite EVIDENCE in reasoning (auditable, not a vibe)
+//   4. bias hard to NOT-attach — anything short of a confident same-owner fit
+//      keeps the new root (a FORK is the safe failure; §1). Enforced
+//      deterministically in decideAction(), not left to the prompt alone.
+//   5. judge against the description (members are not dumped here)
+//   6. attach must NAME the shared subject-matter (shared_subject) — shared
+//      MANNER (both involve the speaker reasoning/remembering/planning) names no
+//      subject, so it can never justify an attach. Added 2026-06-11 after a
+//      transcript test where a process-narration root became an attractor and
+//      absorbed an unrelated domain. Enforced in decideAction().
+//
+// v1 SCOPE: ACT on ATTACH only (the value-add: stop the fork by attaching when
+// confident). "new" and "uncertain" both → keep the new root (the safe fork).
+// At-ingest flag-to-agent is deferred to the AUDIT-heal pass (step 4): blocks
+// don't exist yet at this pre-Pass-3 seam, so a fork is created and the post-hoc
+// project_dup_candidate detector surfaces the pair for the agent/user.
+import { intFromEnv } from "./config.js";
+// ─── Config ──────────────────────────────────────────────────────────────────
+export function recognizerEnabled() {
+    // DEFAULT ON since 2026-06-12 (v2's cross-session root matching — without it the
+    // default engine fragments roots across sessions). =0 opts out.
+    return process.env.NODEDEX_RECOGNIZER_ENABLED !== "0";
+}
+function maxCandidateRoots() {
+    return intFromEnv("NODEDEX_RECOGNIZER_MAX_ROOTS", 40); // bound prompt size; scale-prefilter = TODO
+}
+function maxItemsInCluster() {
+    return intFromEnv("NODEDEX_RECOGNIZER_MAX_ITEMS", 30);
+}
+// ─── Pure decision (guard #4 enforced in code, not just the prompt) ────────────
+/**
+ * Map an LLM verdict → an action. ATTACH only when the model is confident
+ * (decision==="attach"), names a root that ACTUALLY EXISTS, confirms same
+ * owner, AND names the shared subject-matter (guard #6 — an attach must carry
+ * its falsifiable evidence; an unevidenced attach is a contract violation, so
+ * the safe direction is fork). Everything else → keep. Pure / testable.
+ */
+export function decideAction(verdict, knownRootLabels) {
+    if (verdict.decision === "attach" &&
+        verdict.same_owner === true &&
+        typeof verdict.matched_root === "string" &&
+        verdict.matched_root.length > 0 &&
+        knownRootLabels.has(verdict.matched_root) &&
+        typeof verdict.shared_subject === "string" &&
+        verdict.shared_subject.trim().length > 0) {
+        return { action: "attach", root: verdict.matched_root };
+    }
+    return { action: "keep" };
+}
+/** Distinct project names among items that are NOT existing roots = the
+ *  new-root candidates the recognizer should judge. Pure / testable. */
+export function newRootCandidateNames(items, knownRootLabels) {
+    const seen = new Set();
+    const out = [];
+    for (const it of items) {
+        const p = it.project;
+        if (!p || knownRootLabels.has(p) || seen.has(p))
+            continue;
+        seen.add(p);
+        out.push(p);
+    }
+    return out;
+}
+// ─── Prompt + schema ────────────────────────────────────────────────────────
+export const RECOGNIZE_ROOT_PROMPT = `A knowledge graph is about to create a NEW project root for a cluster of new
+knowledge. Decide whether that cluster actually belongs to an EXISTING project
+instead — so related knowledge COMPOUNDS onto one project rather than fragmenting.
+
+You are given:
+  - NEW CLUSTER: the new knowledge (its proposed project name + member items).
+  - EXISTING PROJECTS: each as a one-line DESCRIPTION (domain + owner).
+
+Decide ONE:
+  - "attach"    — the cluster clearly belongs to one EXISTING project: SAME DOMAIN
+                  AND SAME OWNER. Set matched_root to that project's exact label and
+                  shared_subject to the specific subject-matter they share.
+  - "new"       — no existing project fits; this is genuinely a new project.
+  - "uncertain" — plausibly related to an existing project but you are NOT confident
+                  (e.g. similar domain but unclear/different owner, or a weak fit).
+
+RULES (read carefully):
+  - Judge on the DESCRIPTION's meaning, NOT on label string similarity. Two similar
+    names can be different projects; two different names can be the same project.
+  - SAME OWNER is required for "attach". Same domain but a DIFFERENT or UNKNOWN owner
+    (e.g. one customer's data vs another's) is NOT the same project → "new" or "uncertain".
+  - "attach" requires a NAMEABLE SHARED SUBJECT: shared_subject must name the specific
+    thing both bodies of work are ABOUT. A shared MANNER is not a subject — that both
+    involve someone remembering, reasoning, or planning a response names no subject,
+    because every conversation involves those. If you cannot name what they are both
+    about, the fit is not real → "new" or "uncertain", with shared_subject "".
+  - When the fit is merely plausible, choose "uncertain", NOT "attach". A wrong attach
+    silently merges two real projects (hard to undo); a fork is recoverable. Bias to caution.
+  - reasoning MUST cite the specific evidence (which description, which overlapping
+    content) — not "they seem related".`;
+const RECOGNIZE_ROOT_SCHEMA = {
+    type: "object",
+    properties: {
+        decision: { type: "string", enum: ["attach", "new", "uncertain"] },
+        matched_root: { type: "string" },
+        same_owner: { type: "boolean" },
+        shared_subject: { type: "string" },
+        reasoning: { type: "string" },
+    },
+    required: ["decision", "matched_root", "same_owner", "shared_subject", "reasoning"],
+};
+export function buildRecognizeInput(newProjectName, clusterItems, candidateRoots, itemCap, rootCap) {
+    const roots = candidateRoots.slice(0, rootCap)
+        .map((r) => `  - ${r.label}: "${r.essence || "(no description)"}"`)
+        .join("\n");
+    const members = clusterItems.slice(0, itemCap).map((it) => {
+        const t = it.type ?? "?";
+        const txt = (it.text ?? "").toString().slice(0, 160);
+        return `  - [${t}] ${txt}`;
+    }).join("\n");
+    return (`NEW CLUSTER (proposed project: ${newProjectName}):\n${members || "  (no items)"}\n\n` +
+        `EXISTING PROJECTS:\n${roots || "  (none)"}`);
+}
+// ─── LLM judgment (one cluster) ───────────────────────────────────────────────
+export async function recognizeClusterRoot(provider, newProjectName, clusterItems, candidateRoots) {
+    const userInput = buildRecognizeInput(newProjectName, clusterItems, candidateRoots, maxItemsInCluster(), maxCandidateRoots());
+    const r = await provider.generateStructured(RECOGNIZE_ROOT_PROMPT, userInput, RECOGNIZE_ROOT_SCHEMA, { thinkingBudget: 1024, maxOutputTokens: 1024 });
+    return { verdict: r.result ?? null, rateLimited: r.rateLimited, usage: r.usage };
+}
+/**
+ * For each new-root candidate cluster, ask the recognizer "attach to an existing
+ * root?" and collect the confident-attach rewrites. Caller applies the remap to
+ * item.project (then Pass 3 + root-create attach to the existing root). Does NOT
+ * mutate items itself (pure-ish: returns the remap). LLM-bounded (one call per
+ * new-root candidate). NO knownRoots → nothing to attach to → empty remap.
+ */
+export async function recognizeRootsForArc(opts) {
+    const result = {
+        remap: [], candidates: 0, attached: 0, llm_calls: 0, rate_limited: 0, errors: 0,
+    };
+    if (opts.knownRoots.length === 0)
+        return result; // nothing to recognize against
+    const knownLabels = new Set(opts.knownRoots.map((r) => r.label));
+    const candidates = newRootCandidateNames(opts.items, knownLabels);
+    result.candidates = candidates.length;
+    for (const name of candidates) {
+        const clusterItems = opts.items.filter((it) => it.project === name);
+        try {
+            result.llm_calls += 1;
+            const { verdict, rateLimited } = await recognizeClusterRoot(opts.provider, name, clusterItems, opts.knownRoots);
+            if (rateLimited) {
+                result.rate_limited += 1;
+                continue;
+            }
+            if (!verdict)
+                continue;
+            const action = decideAction(verdict, knownLabels);
+            if (action.action === "attach" && action.root) {
+                result.remap.push({ from: name, to: action.root });
+                result.attached += 1;
+                console.log(`[recognizer] attach "${name}" → "${action.root}" (same_owner=${verdict.same_owner}, shared_subject="${verdict.shared_subject}"): ${verdict.reasoning.slice(0, 140)}`);
+            }
+            else {
+                console.log(`[recognizer] keep "${name}" (decision=${verdict.decision}, same_owner=${verdict.same_owner}): ${verdict.reasoning.slice(0, 120)}`);
+            }
+        }
+        catch (e) {
+            result.errors += 1;
+            console.warn(`[recognizer] cluster "${name}" threw: ${e?.message ?? e}`);
+        }
+    }
+    return result;
+}
+/** Apply a remap (from recognizeRootsForArc) to items' .project — returns a NEW
+ *  array (shallow-copies only the rewritten items). Pure / testable. */
+export function applyRootRemap(items, remap) {
+    if (remap.length === 0)
+        return { items, rewritten: 0 };
+    const map = new Map(remap.map((r) => [r.from, r.to]));
+    let rewritten = 0;
+    const out = items.map((it) => {
+        const to = map.get(it.project);
+        if (!to)
+            return it;
+        rewritten += 1;
+        return { ...it, project: to };
+    });
+    return { items: out, rewritten };
+}
+//# sourceMappingURL=recognize-root.js.map

package/dist/middleware/reflect/recognize-root.js.map

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

package/dist/middleware/reflect/render-agent-flag.d.ts

@@ -0,0 +1,25 @@
+import type Database from "better-sqlite3";
+import type { PipelineFlag } from "./types.js";
+export interface RenderedAgentFlag {
+    id: string;
+    question: string;
+    you_are_recording: {
+        what: string;
+        value: string;
+        owner: string;
+        source: string | null;
+    };
+    existing_uncertain: {
+        what: string;
+        value: string;
+        owner: string;
+        source: string | null;
+    } | null;
+    routed_reason: string | null;
+}
+/**
+ * Render an owner-unknown flag as a plain-English question. Returns null if
+ * block_a is gone (stale flag — skip it).
+ */
+export declare function renderAgentFlag(raw: Database.Database, flag: PipelineFlag): RenderedAgentFlag | null;
+//# sourceMappingURL=render-agent-flag.d.ts.map

package/dist/middleware/reflect/render-agent-flag.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-agent-flag.d.ts","sourceRoot":"","sources":["../../../src/middleware/reflect/render-agent-flag.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAI3C,OAAO,KAAK,EAAE,YAAY,EAAuB,MAAM,YAAY,CAAC;AAEpE,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IACzF,kBAAkB,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;IACjG,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,QAAQ,CAAC,QAAQ,EAAE,IAAI,EAAE,YAAY,GAAG,iBAAiB,GAAG,IAAI,CAepG"}

package/dist/middleware/reflect/render-agent-flag.js

@@ -0,0 +1,39 @@
+// render-agent-flag.ts — turn an owner-unknown pipeline_flag into a PLAIN-ENGLISH
+// question for the agent. SINGLE SOURCE OF TRUTH for that rendering, used by BOTH:
+//   • the REST surface   (routes/flags.ts  → GET /api/flags/agent-pending)
+//   • the MCP pull surface (tools/flag-surface.ts → workspace_stats.flags)
+//
+// Extracted from routes/flags.ts so the two surfaces can't drift. The agent never
+// sees ids/schema/verdict vocabulary — just "same thing? whose?" — and answers from
+// its conversation context (or asks the user), then it's applied via the review path.
+//
+// Only owner-unknown dup flags are routed to the agent today (the reviewer's
+// markFlagPendingClarification path); this renderer is shaped for them.
+import { loadBlockSnapshot } from "./flag-reviewer.js";
+import { extractPrimaryValueFromUnique } from "./dedup-by-source-and-value.js";
+import { scopeSegmentOfLabel } from "./retrieve-graph-slice.js";
+/**
+ * Render an owner-unknown flag as a plain-English question. Returns null if
+ * block_a is gone (stale flag — skip it).
+ */
+export function renderAgentFlag(raw, flag) {
+    const a = loadBlockSnapshot(raw, flag.block_id_a);
+    if (!a)
+        return null;
+    const b = flag.block_id_b ? loadBlockSnapshot(raw, flag.block_id_b) : null;
+    const describe = (s) => {
+        let value = "";
+        try {
+            value = extractPrimaryValueFromUnique(s.type, (JSON.parse(s.content)?.unique) || {});
+        }
+        catch { /* leave blank */ }
+        return { what: s.essence, value, owner: scopeSegmentOfLabel(s.label), source: s.source ?? null };
+    };
+    const you = describe(a);
+    const existing = b ? describe(b) : null;
+    const question = existing
+        ? `You're recording (owner: ${you.owner}): "${you.value || you.what}". An existing entry is already on file with an UNCERTAIN owner (${existing.owner}): "${existing.value || existing.what}". Are these the same thing, and does the existing one belong to ${you.owner}? If you can't tell from context, ask the user. (The existing one was captured from: ${existing.source || "no source recorded"}.)`
+        : `An existing entry needs an owner assigned: "${you.value || you.what}" (owner: ${you.owner}). Who does it belong to? If unsure, ask the user.`;
+    return { id: flag.id, question, you_are_recording: you, existing_uncertain: existing, routed_reason: flag.review_reason };
+}
+//# sourceMappingURL=render-agent-flag.js.map

package/dist/middleware/reflect/render-agent-flag.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-agent-flag.js","sourceRoot":"","sources":["../../../src/middleware/reflect/render-agent-flag.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,mFAAmF;AACnF,2EAA2E;AAC3E,2EAA2E;AAC3E,EAAE;AACF,kFAAkF;AAClF,oFAAoF;AACpF,sFAAsF;AACtF,EAAE;AACF,6EAA6E;AAC7E,wEAAwE;AAGxE,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,6BAA6B,EAAE,MAAM,gCAAgC,CAAC;AAC/E,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAWhE;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,GAAsB,EAAE,IAAkB;IACxE,MAAM,CAAC,GAAG,iBAAiB,CAAC,GAAG,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;IAClD,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpB,MAAM,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,iBAAiB,CAAC,GAAG,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC3E,MAAM,QAAQ,GAAG,CAAC,CAAsB,EAAE,EAAE;QAC1C,IAAI,KAAK,GAAG,EAAE,CAAC;QACf,IAAI,CAAC;YAAC,KAAK,GAAG,6BAA6B,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC,CAAC,iBAAiB,CAAC,CAAC;QACzH,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,mBAAmB,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,IAAI,IAAI,EAAE,CAAC;IACnG,CAAC,CAAC;IACF,MAAM,GAAG,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;IACxB,MAAM,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACxC,MAAM,QAAQ,GAAG,QAAQ;QACvB,CAAC,CAAC,4BAA4B,GAAG,CAAC,KAAK,OAAO,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,IAAI,oEAAoE,QAAQ,CAAC,KAAK,OAAO,QAAQ,CAAC,KAAK,IAAI,QAAQ,CAAC,IAAI,oEAAoE,GAAG,CAAC,KAAK,wFAAwF,QAAQ,CAAC,MAAM,IAAI,oBAAoB,IAAI;QAC3Y,CAAC,CAAC,+CAA+C,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,IAAI,aAAa,GAAG,CAAC,KAAK,oDAAoD,CAAC;IACnJ,OAAO,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,QAAQ,EAAE,iBAAiB,EAAE,GAAG,EAAE,kBAAkB,EAAE,QAAQ,EAAE,aAAa,EAAE,IAAI,CAAC,aAAa,EAAE,CAAC;AAC5H,CAAC"}

package/dist/middleware/reflect/retrieve-graph-slice.d.ts

@@ -0,0 +1,54 @@
+import type { WorkspaceDB, Block } from "../../store/database.js";
+export interface CandidateScope {
+    /** The owner/scope value (label {project} segment or project_id resolved to it). */
+    value: string;
+    /** True when the scope is a catch-all dump ("owner unknown"), not a real owner. */
+    is_catch_all: boolean;
+}
+export interface RetrievalCandidate {
+    block: Block;
+    identity_score: number;
+    scope: CandidateScope;
+    semantic_score: number;
+    rank_score: number;
+    why: string;
+}
+/** What Part 1 needs about the arc entity it's finding matches for. Derived from
+ *  a Stage C cluster, but kept as a plain shape so callers/tests can build it
+ *  without a full ArcEntityResolveResult. */
+export interface EntityQuery {
+    canonical_name: string;
+    /** Identity-bearing primary values of the entity's member items (the thing to
+     *  match on — Signal 1). Often one, but a cluster can carry several. */
+    primary_values: string[];
+    /** Concept tags for candidate FINDING (recall) + partial signal. */
+    concepts: string[];
+    /** Optional query embedding for Signal 3. Omit to skip semantic. */
+    embedding?: number[] | null;
+}
+/** Normalize a primary value for comparison: lowercase, collapse whitespace,
+ *  strip surrounding backticks/quotes/trailing punctuation. Identity compares on
+ *  MEANING-bearing text, so cosmetic punctuation must not split a true match. */
+export declare function normalizePrimaryValue(v: string): string;
+/** The {project} (owner) segment of a strict label {project}_{type}_{concept}.
+ *  Read STRUCTURALLY (split on the `_` dimension separator) — never word-soup. */
+export declare function scopeSegmentOfLabel(label: string): string;
+/** Token-overlap (Jaccard) of two primary values — the partial-identity signal
+ *  for paraphrase, where exact normalized match fails. */
+export declare function primaryValueTokenOverlap(a: string, b: string): number;
+export declare function isCatchAllScope(scopeValue: string, projectRootEssenceByLabel?: Map<string, string>): boolean;
+export interface RetrieveOpts {
+    k?: number;
+    /** Pass an embedding-getter to enable Signal 3; omit to skip (pure identity+scope). */
+    embeddingFor?: (block: Block) => number[] | null;
+}
+/**
+ * Retrieve the top-k candidate blocks for an arc entity, ranked identity-first.
+ *
+ * Recall step: union of keywordSearch(canonical_name + primary values) +
+ * conceptSearch(concepts). Cross-scope candidates are INCLUDED (the resolver's
+ * Q2 needs them). Ranking: Signal 1 (identity) dominates; Signal 2 (scope) is
+ * carried as evidence, not a filter; Signal 3 (semantic) is a capped booster.
+ */
+export declare function retrieveGraphSlice(db: WorkspaceDB, entity: EntityQuery, opts?: RetrieveOpts): RetrievalCandidate[];
+//# sourceMappingURL=retrieve-graph-slice.d.ts.map

package/dist/middleware/reflect/retrieve-graph-slice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retrieve-graph-slice.d.ts","sourceRoot":"","sources":["../../../src/middleware/reflect/retrieve-graph-slice.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAC;AAkBlE,MAAM,WAAW,cAAc;IAC7B,oFAAoF;IACpF,KAAK,EAAE,MAAM,CAAC;IACd,mFAAmF;IACnF,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,KAAK,CAAC;IACb,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,cAAc,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;6CAE6C;AAC7C,MAAM,WAAW,WAAW;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB;4EACwE;IACxE,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,oEAAoE;IACpE,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,oEAAoE;IACpE,SAAS,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;CAC7B;AAID;;iFAEiF;AACjF,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAMvD;AAED;kFACkF;AAClF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGzD;AAMD;0DAC0D;AAC1D,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAMrE;AAUD,wBAAgB,eAAe,CAC7B,UAAU,EAAE,MAAM,EAClB,yBAAyB,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAC9C,OAAO,CAOT;AAID,MAAM,WAAW,YAAY;IAC3B,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,uFAAuF;IACvF,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,MAAM,EAAE,GAAG,IAAI,CAAC;CAClD;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,WAAW,EACf,MAAM,EAAE,WAAW,EACnB,IAAI,GAAE,YAAiB,GACtB,kBAAkB,EAAE,CAsEtB"}

package/dist/middleware/reflect/retrieve-graph-slice.js

@@ -0,0 +1,173 @@
+// ═══════════════════════════════════════════════════════════════════════════════
+// DEBT 5 Slice 3 (Stage D) — Part 1: RETRIEVE — identity-ranked candidate finder
+// ═══════════════════════════════════════════════════════════════════════════════
+//
+// Job (docs/PIPELINE-STAGE-D-PART1-RETRIEVAL-DESIGN.md):
+//   Narrow the graph to ~k candidate blocks the Stage D resolver (Part 2) should
+//   judge for "same entity? same scope?". ONLY duty = high RECALL (never miss a
+//   real same-entity match). Precision is the resolver's job.
+//
+// Why this is NOT just "reuse recall-smart" (the meaning-first audit, 2026-06-01):
+//   recall-smart's SEMANTIC half fingerprints [label, essence, concepts] — TOPIC,
+//   not identity. It omits unique{} (the system's identity basis) and FLATTENS the
+//   label's {project} segment (the OWNER) into word-soup. For an IDENTITY check
+//   that's the wrong signal. So we keep the candidate-FINDING plumbing
+//   (keywordSearch/conceptSearch) but rebuild the RANKING on three SEPARATE
+//   signals, identity-first:
+//
+//   Signal 1 IDENTITY  — unique{} primary value (via extractPrimaryValueFromUnique,
+//                        the SAME extractor D2 + AUDIT use — Rule 5). DOMINANT.
+//   Signal 2 SCOPE     — label {project} segment read as a DISCRETE dimension (not
+//                        blended); catch-all scopes tagged "unknown" (spike pair-5
+//                        lesson). Does NOT filter — cross-scope candidates are
+//                        WANTED (resolver's Q2 needs them).
+//   Signal 3 SEMANTIC  — existing cosine, DE-WEIGHTED (≤0.2). A weak recall-net for
+//                        paraphrases Signal 1 missed; never the identity basis.
+//
+// source_excerpt: carried as EVIDENCE to the resolver, NOT a match key (cross-arc
+// the same entity comes from different conversations → excerpts differ).
+import { cosineSim } from "../../engine/vector-math.js";
+import { extractPrimaryValueFromUnique } from "./dedup-by-source-and-value.js";
+// ─── Weights (identity dominates; semantic is a weak booster) ──────────────────
+const W_IDENTITY_EXACT = 1.0; // exact normalized unique{} primary-value match
+const W_IDENTITY_PARTIAL = 0.5; // token overlap of primary values (paraphrase net)
+const W_SEMANTIC_MAX = 0.2; // cosine contribution ceiling (recall booster only)
+// Scopes that are catch-all dumping grounds, not real owners. Detected
+// STRUCTURALLY below (a project root with few/no real members) — this constant
+// is only the well-known explicit marker, NOT an exhaustive sentinel list (that
+// would be the signal-word anti-pattern). See isCatchAllScope().
+const EXPLICIT_CATCH_ALL = "unspecified-project";
+// ─── Pure helpers (no DB — unit-testable) ──────────────────────────────────────
+/** Normalize a primary value for comparison: lowercase, collapse whitespace,
+ *  strip surrounding backticks/quotes/trailing punctuation. Identity compares on
+ *  MEANING-bearing text, so cosmetic punctuation must not split a true match. */
+export function normalizePrimaryValue(v) {
+    return (v ?? "")
+        .toLowerCase()
+        .replace(/[`"'.]/g, "")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+/** The {project} (owner) segment of a strict label {project}_{type}_{concept}.
+ *  Read STRUCTURALLY (split on the `_` dimension separator) — never word-soup. */
+export function scopeSegmentOfLabel(label) {
+    const i = (label ?? "").indexOf("_");
+    return i === -1 ? (label ?? "") : label.slice(0, i);
+}
+function tokenize(s) {
+    return normalizePrimaryValue(s).split(" ").filter(t => t.length > 2);
+}
+/** Token-overlap (Jaccard) of two primary values — the partial-identity signal
+ *  for paraphrase, where exact normalized match fails. */
+export function primaryValueTokenOverlap(a, b) {
+    const ta = new Set(tokenize(a)), tb = new Set(tokenize(b));
+    if (ta.size === 0 || tb.size === 0)
+        return 0;
+    let inter = 0;
+    for (const t of ta)
+        if (tb.has(t))
+            inter += 1;
+    return inter / (ta.size + tb.size - inter);
+}
+// ─── Scope: catch-all detection (structural, not a sentinel list) ──────────────
+//
+// A scope is "catch-all" when it's a dumping ground rather than a real owner. We
+// detect this STRUCTURALLY: the explicit well-known marker, OR a project root that
+// owns blocks spanning many unrelated concept clusters with a generic essence.
+// For now (small graph) the explicit marker + a low-cohesion heuristic; the
+// heuristic is the extensible part (NOT a hard-coded list of names).
+export function isCatchAllScope(scopeValue, projectRootEssenceByLabel) {
+    if (scopeValue === EXPLICIT_CATCH_ALL)
+        return true;
+    // Structural signal: a project root whose essence advertises "items without a
+    // specified project" / "miscellaneous" — read from the root block's own essence,
+    // NOT a name list. Extensible: future cohesion metric plugs in here.
+    const essence = projectRootEssenceByLabel?.get(scopeValue)?.toLowerCase() ?? "";
+    return /without a specified project|miscellaneous|uncategorized|catch-?all|unspecified/.test(essence);
+}
+/**
+ * Retrieve the top-k candidate blocks for an arc entity, ranked identity-first.
+ *
+ * Recall step: union of keywordSearch(canonical_name + primary values) +
+ * conceptSearch(concepts). Cross-scope candidates are INCLUDED (the resolver's
+ * Q2 needs them). Ranking: Signal 1 (identity) dominates; Signal 2 (scope) is
+ * carried as evidence, not a filter; Signal 3 (semantic) is a capped booster.
+ */
+export function retrieveGraphSlice(db, entity, opts = {}) {
+    const k = opts.k ?? 20;
+    // Project-root essences for structural catch-all detection (cheap; small set).
+    const rootEssence = new Map();
+    for (const b of db.getAllBlocks()) {
+        if (b.type === "project")
+            rootEssence.set(b.label, b.essence ?? "");
+    }
+    // ── Recall (FINDING): union keyword + concept candidates ──
+    const queryString = [entity.canonical_name.replace(/-/g, " "), ...entity.primary_values].join(" ");
+    const kw = db.keywordSearch(queryString, 200);
+    const conceptHits = entity.concepts.length
+        ? [...db.conceptSearch(entity.concepts).values()].map(v => v.block)
+        : [];
+    const pool = new Map();
+    for (const b of [...kw, ...conceptHits]) {
+        if (b && b.id && b.status === "active")
+            pool.set(b.id, b);
+    }
+    const normEntityValues = entity.primary_values.map(normalizePrimaryValue).filter(Boolean);
+    // ── Rank ──
+    const scored = [];
+    for (const block of pool.values()) {
+        if (block.type === "project")
+            continue; // entities resolve against atomic blocks, not roots
+        // Signal 1 — IDENTITY (unique{} primary value)
+        let content = {};
+        try {
+            content = typeof block.content === "string" ? JSON.parse(block.content) : (block.content || {});
+        }
+        catch {
+            content = {};
+        }
+        const candVal = extractPrimaryValueFromUnique(block.type, content.unique || {});
+        const candNorm = normalizePrimaryValue(candVal);
+        let identity = 0;
+        const whyParts = [];
+        if (candNorm) {
+            if (normEntityValues.includes(candNorm)) {
+                identity = W_IDENTITY_EXACT;
+                whyParts.push(`identity:exact(${candNorm.slice(0, 40)})`);
+            }
+            else {
+                const best = Math.max(0, ...normEntityValues.map(v => primaryValueTokenOverlap(v, candNorm)));
+                if (best > 0) {
+                    identity = W_IDENTITY_PARTIAL * best;
+                    whyParts.push(`identity:partial(${best.toFixed(2)})`);
+                }
+            }
+        }
+        // Signal 2 — SCOPE (discrete; carried, not filtered)
+        const scopeVal = scopeSegmentOfLabel(block.label);
+        const scope = { value: scopeVal, is_catch_all: isCatchAllScope(scopeVal, rootEssence) };
+        if (scope.is_catch_all)
+            whyParts.push("scope:catch-all");
+        // Signal 3 — SEMANTIC (capped booster)
+        let semantic = 0;
+        if (entity.embedding && opts.embeddingFor) {
+            const vec = opts.embeddingFor(block);
+            if (vec) {
+                semantic = cosineSim(entity.embedding, vec);
+                if (semantic > 0.01)
+                    whyParts.push(`semantic:${semantic.toFixed(2)}`);
+            }
+        }
+        const rank = identity + Math.min(semantic, 1) * W_SEMANTIC_MAX;
+        // Keep anything with ANY identity OR a strong semantic hit (recall net).
+        if (rank <= 0 && semantic < 0.5)
+            continue;
+        scored.push({
+            block, identity_score: identity, scope, semantic_score: semantic,
+            rank_score: rank, why: whyParts.join(" "),
+        });
+    }
+    scored.sort((a, b) => b.rank_score - a.rank_score);
+    return scored.slice(0, k);
+}
+//# sourceMappingURL=retrieve-graph-slice.js.map

package/dist/middleware/reflect/retrieve-graph-slice.js.map

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

package/dist/middleware/reflect/root-relatedness.d.ts

@@ -0,0 +1,31 @@
+import type { WorkspaceDB } from "../../store/database.js";
+export type RelatednessCategory = "dependency" | "containment" | "evolution" | "conflict" | "loose";
+export interface MinBlock {
+    id: string;
+    label: string;
+    type: string;
+    project_id: string | null;
+}
+export interface RootEdge {
+    source_id: string;
+    target_id: string;
+    type: string;
+}
+export interface RelatedPair {
+    root_a: string;
+    root_b: string;
+    categories: Partial<Record<RelatednessCategory, number>>;
+    total: number;
+    /** Label of the root the other sits under (most subordinating edges point here), or null. */
+    parent: string | null;
+    parent_subordinating_edges: number;
+}
+export interface RootRelatedness {
+    pairs: RelatedPair[];
+    standalone: string[];
+}
+/** Pure: classify cross-root edges into a meaning-categorized relatedness map. Testable. */
+export declare function classifyRootRelatedness(blocks: MinBlock[], edges: RootEdge[]): RootRelatedness;
+/** DB wrapper: read blocks + active relations, classify. */
+export declare function deriveRootRelatedness(db: WorkspaceDB): RootRelatedness;
+//# sourceMappingURL=root-relatedness.d.ts.map

package/dist/middleware/reflect/root-relatedness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-relatedness.d.ts","sourceRoot":"","sources":["../../../src/middleware/reflect/root-relatedness.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,WAAW,EAAS,MAAM,yBAAyB,CAAC;AAElE,MAAM,MAAM,mBAAmB,GAAG,YAAY,GAAG,aAAa,GAAG,WAAW,GAAG,UAAU,GAAG,OAAO,CAAC;AAgBpG,MAAM,WAAW,QAAQ;IAAG,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAAE;AACjG,MAAM,WAAW,QAAQ;IAAG,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;CAAE;AAEjF,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,OAAO,CAAC,MAAM,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAAC,CAAC;IACzD,KAAK,EAAE,MAAM,CAAC;IACd,6FAA6F;IAC7F,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,0BAA0B,EAAE,MAAM,CAAC;CACpC;AACD,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,4FAA4F;AAC5F,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,QAAQ,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,eAAe,CAwC9F;AAED,4DAA4D;AAC5D,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,WAAW,GAAG,eAAe,CAOtE"}