@rryando/arcs 3.0.0

package/dist/retrieval/graph-builder.js

@@ -0,0 +1,196 @@
+/**
+ * Builds an adjacency index (graph) from project metadata indexes.
+ */
+import { stat } from "node:fs/promises";
+import { join } from "node:path";
+import { getProjectDir } from "../utils/paths.js";
+import { listTasks, readKnowledgeIndex, readPlanIndex } from "../utils/project-memory.js";
+import { EDGE_WEIGHTS } from "./graph-types.js";
+const MAX_FILE_REFS_FOR_PAIRS = 10;
+function addNode(nodes, node) {
+    if (!nodes.has(node.id)) {
+        nodes.set(node.id, node);
+    }
+}
+function addEdge(edges, edge) {
+    const list = edges.get(edge.source);
+    if (list) {
+        list.push(edge);
+    }
+    else {
+        edges.set(edge.source, [edge]);
+    }
+}
+async function getMtime(filePath) {
+    try {
+        const s = await stat(filePath);
+        return s.mtimeMs;
+    }
+    catch {
+        return 0;
+    }
+}
+export async function buildAdjacencyIndex(slug) {
+    const projectDir = getProjectDir(slug);
+    const nodes = new Map();
+    const edges = new Map();
+    const fileIndex = new Map();
+    // Helper to register a file reference from a node
+    function registerFileRef(nodeId, filePath) {
+        addNode(nodes, { id: `file:${filePath}`, type: "file", title: filePath });
+        const refs = fileIndex.get(filePath);
+        if (refs) {
+            refs.push(nodeId);
+        }
+        else {
+            fileIndex.set(filePath, [nodeId]);
+        }
+    }
+    // 1. Knowledge
+    let knowledgeEntries = [];
+    try {
+        const idx = await readKnowledgeIndex(projectDir);
+        knowledgeEntries = idx.entries;
+    }
+    catch {
+        // graceful
+    }
+    for (const entry of knowledgeEntries) {
+        const nodeId = `knowledge:${entry.id}`;
+        addNode(nodes, { id: nodeId, type: "knowledge", title: entry.title, keywords: entry.keywords });
+        if (entry.sourceFiles) {
+            for (const sf of entry.sourceFiles) {
+                registerFileRef(nodeId, sf.path);
+                addEdge(edges, {
+                    source: nodeId,
+                    target: `file:${sf.path}`,
+                    relation: "knowledge_touches_file",
+                    weight: EDGE_WEIGHTS.knowledge_touches_file,
+                });
+            }
+        }
+    }
+    // 2. Plans
+    let planEntries = [];
+    try {
+        const idx = await readPlanIndex(projectDir);
+        planEntries = idx.plans;
+    }
+    catch {
+        // graceful
+    }
+    for (const plan of planEntries) {
+        const nodeId = `plan:${plan.id}`;
+        addNode(nodes, { id: nodeId, type: "plan", title: plan.title, keywords: plan.keywords });
+        if (plan.sourceFiles) {
+            for (const sf of plan.sourceFiles) {
+                registerFileRef(nodeId, sf.path);
+                addEdge(edges, {
+                    source: nodeId,
+                    target: `file:${sf.path}`,
+                    relation: "knowledge_touches_file",
+                    weight: EDGE_WEIGHTS.knowledge_touches_file,
+                });
+            }
+        }
+    }
+    // 3. Tasks
+    let taskEntries = [];
+    try {
+        taskEntries = await listTasks(projectDir);
+    }
+    catch {
+        // graceful
+    }
+    for (const task of taskEntries) {
+        const nodeId = `task:${task.id}`;
+        addNode(nodes, { id: nodeId, type: "task", title: task.title });
+        if (task.planId) {
+            const planNodeId = `plan:${task.planId}`;
+            addNode(nodes, { id: planNodeId, type: "plan" });
+            addEdge(edges, {
+                source: nodeId,
+                target: planNodeId,
+                relation: "task_belongs_to_plan",
+                weight: EDGE_WEIGHTS.task_belongs_to_plan,
+            });
+            addEdge(edges, {
+                source: planNodeId,
+                target: nodeId,
+                relation: "plan_contains_task",
+                weight: EDGE_WEIGHTS.plan_contains_task,
+            });
+        }
+        if (task.sourceFiles) {
+            for (const sf of task.sourceFiles) {
+                registerFileRef(nodeId, sf.path);
+                addEdge(edges, {
+                    source: nodeId,
+                    target: `file:${sf.path}`,
+                    relation: "knowledge_touches_file",
+                    weight: EDGE_WEIGHTS.knowledge_touches_file,
+                });
+            }
+        }
+    }
+    // 5. shares_source_file edges
+    fileIndex.forEach((refNodes) => {
+        if (refNodes.length < 2)
+            return;
+        const capped = refNodes.slice(0, MAX_FILE_REFS_FOR_PAIRS);
+        for (let i = 0; i < capped.length; i++) {
+            for (let j = i + 1; j < capped.length; j++) {
+                addEdge(edges, {
+                    source: capped[i],
+                    target: capped[j],
+                    relation: "shares_source_file",
+                    weight: EDGE_WEIGHTS.shares_source_file,
+                });
+                addEdge(edges, {
+                    source: capped[j],
+                    target: capped[i],
+                    relation: "shares_source_file",
+                    weight: EDGE_WEIGHTS.shares_source_file,
+                });
+            }
+        }
+    });
+    // 6. shares_keywords edges for knowledge entries
+    for (let i = 0; i < knowledgeEntries.length; i++) {
+        for (let j = i + 1; j < knowledgeEntries.length; j++) {
+            const a = knowledgeEntries[i];
+            const b = knowledgeEntries[j];
+            const shared = a.keywords.filter((kw) => b.keywords.includes(kw));
+            if (shared.length >= 2) {
+                const aId = `knowledge:${a.id}`;
+                const bId = `knowledge:${b.id}`;
+                addEdge(edges, {
+                    source: aId,
+                    target: bId,
+                    relation: "shares_keywords",
+                    weight: EDGE_WEIGHTS.shares_keywords,
+                });
+                addEdge(edges, {
+                    source: bId,
+                    target: aId,
+                    relation: "shares_keywords",
+                    weight: EDGE_WEIGHTS.shares_keywords,
+                });
+            }
+        }
+    }
+    // 7. sourceHashes
+    const sourceHashes = {
+        knowledge: await getMtime(join(projectDir, "knowledge", "index.json")),
+        plans: await getMtime(join(projectDir, "plans", "index.json")),
+        tasks: await getMtime(join(projectDir, "tasks", "index.json")),
+    };
+    return {
+        nodes,
+        edges,
+        fileIndex,
+        buildTime: new Date().toISOString(),
+        sourceHashes,
+    };
+}
+//# sourceMappingURL=graph-builder.js.map

package/dist/retrieval/graph-builder.js.map

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

package/dist/retrieval/graph-cache.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Mtime-based cache for graph adjacency indexes.
+ */
+import type { AdjacencyIndex } from "./graph-types.js";
+export interface GraphCacheOptions {
+    maxAge?: number;
+}
+export interface GraphCache {
+    get(slug: string): Promise<AdjacencyIndex | null>;
+    getOrBuild(slug: string): Promise<AdjacencyIndex>;
+    invalidate(slug: string): void;
+    invalidateAll(): void;
+}
+export declare function createGraphCache(options?: GraphCacheOptions): GraphCache;
+//# sourceMappingURL=graph-cache.d.ts.map

package/dist/retrieval/graph-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-cache.d.ts","sourceRoot":"","sources":["../../src/retrieval/graph-cache.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAClD,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAClD,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,aAAa,IAAI,IAAI,CAAC;CACvB;AAuBD,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,UAAU,CA0CxE"}

package/dist/retrieval/graph-cache.js

@@ -0,0 +1,66 @@
+/**
+ * Mtime-based cache for graph adjacency indexes.
+ */
+import { stat } from "node:fs/promises";
+import { buildAdjacencyIndex } from "./graph-builder.js";
+async function getMtimeMs(filePath) {
+    try {
+        const s = await stat(filePath);
+        return s.mtimeMs;
+    }
+    catch {
+        return -1;
+    }
+}
+async function isValid(index, maxAge) {
+    const age = Date.now() - new Date(index.buildTime).getTime();
+    if (age >= maxAge)
+        return false;
+    for (const [filePath, storedMtime] of Object.entries(index.sourceHashes)) {
+        const currentMtime = await getMtimeMs(filePath);
+        if (currentMtime === -1 || currentMtime !== storedMtime)
+            return false;
+    }
+    return true;
+}
+export function createGraphCache(options) {
+    const maxAge = options?.maxAge ?? 60_000;
+    const store = new Map();
+    const pending = new Map();
+    const cache = {
+        async get(slug) {
+            const cached = store.get(slug);
+            if (!cached)
+                return null;
+            if (await isValid(cached, maxAge))
+                return cached;
+            store.delete(slug);
+            return null;
+        },
+        async getOrBuild(slug) {
+            const cached = await cache.get(slug);
+            if (cached)
+                return cached;
+            const inflight = pending.get(slug);
+            if (inflight)
+                return inflight;
+            const promise = buildAdjacencyIndex(slug).then((index) => {
+                store.set(slug, index);
+                pending.delete(slug);
+                return index;
+            });
+            pending.set(slug, promise);
+            return promise;
+        },
+        invalidate(slug) {
+            store.delete(slug);
+            pending.delete(slug);
+        },
+        invalidateAll() {
+            store.clear();
+            pending.clear();
+        },
+    };
+    return cache;
+}
+//# sourceMappingURL=graph-cache.js.map

package/dist/retrieval/graph-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-cache.js","sourceRoot":"","sources":["../../src/retrieval/graph-cache.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACxC,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAczD,KAAK,UAAU,UAAU,CAAC,QAAgB;IACxC,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC/B,OAAO,CAAC,CAAC,OAAO,CAAC;IACnB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,CAAC,CAAC;IACZ,CAAC;AACH,CAAC;AAED,KAAK,UAAU,OAAO,CAAC,KAAqB,EAAE,MAAc;IAC1D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC;IAC7D,IAAI,GAAG,IAAI,MAAM;QAAE,OAAO,KAAK,CAAC;IAEhC,KAAK,MAAM,CAAC,QAAQ,EAAE,WAAW,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,EAAE,CAAC;QACzE,MAAM,YAAY,GAAG,MAAM,UAAU,CAAC,QAAQ,CAAC,CAAC;QAChD,IAAI,YAAY,KAAK,CAAC,CAAC,IAAI,YAAY,KAAK,WAAW;YAAE,OAAO,KAAK,CAAC;IACxE,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,OAA2B;IAC1D,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,IAAI,MAAM,CAAC;IACzC,MAAM,KAAK,GAAG,IAAI,GAAG,EAA0B,CAAC;IAChD,MAAM,OAAO,GAAG,IAAI,GAAG,EAAmC,CAAC;IAE3D,MAAM,KAAK,GAAe;QACxB,KAAK,CAAC,GAAG,CAAC,IAAY;YACpB,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAC/B,IAAI,CAAC,MAAM;gBAAE,OAAO,IAAI,CAAC;YACzB,IAAI,MAAM,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC;gBAAE,OAAO,MAAM,CAAC;YACjD,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YACnB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,KAAK,CAAC,UAAU,CAAC,IAAY;YAC3B,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACrC,IAAI,MAAM;gBAAE,OAAO,MAAM,CAAC;YAE1B,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACnC,IAAI,QAAQ;gBAAE,OAAO,QAAQ,CAAC;YAE9B,MAAM,OAAO,GAAG,mBAAmB,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE;gBACvD,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;gBACvB,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;gBACrB,OAAO,KAAK,CAAC;YACf,CAAC,CAAC,CAAC;YACH,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;YAC3B,OAAO,OAAO,CAAC;QACjB,CAAC;QAED,UAAU,CAAC,IAAY;YACrB,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YACnB,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACvB,CAAC;QAED,aAAa;YACX,KAAK,CAAC,KAAK,EAAE,CAAC;YACd,OAAO,CAAC,KAAK,EAAE,CAAC;QAClB,CAAC;KACF,CAAC;IAEF,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/retrieval/graph-invalidate.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Graph cache invalidation hook.
+ *
+ * Decoupled from graph-retrieval to avoid circular imports.
+ * graph-retrieval registers its cache here at module load;
+ * write paths call invalidateGraphCache() after mutations.
+ */
+export type InvalidateFn = (slug: string) => void;
+/**
+ * Called by graph-retrieval at module load to register the singleton cache's invalidate method.
+ */
+export declare function registerGraphCacheInvalidator(fn: InvalidateFn): void;
+/**
+ * Invalidate the graph cache for a project slug.
+ * No-op if the graph module hasn't been loaded yet.
+ */
+export declare function invalidateGraphCache(slug: string): void;
+//# sourceMappingURL=graph-invalidate.d.ts.map

package/dist/retrieval/graph-invalidate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-invalidate.d.ts","sourceRoot":"","sources":["../../src/retrieval/graph-invalidate.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;AAIlD;;GAEG;AACH,wBAAgB,6BAA6B,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CAEpE;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAEvD"}

package/dist/retrieval/graph-invalidate.js

@@ -0,0 +1,23 @@
+/**
+ * Graph cache invalidation hook.
+ *
+ * Decoupled from graph-retrieval to avoid circular imports.
+ * graph-retrieval registers its cache here at module load;
+ * write paths call invalidateGraphCache() after mutations.
+ */
+let _invalidate = null;
+/**
+ * Called by graph-retrieval at module load to register the singleton cache's invalidate method.
+ */
+export function registerGraphCacheInvalidator(fn) {
+    _invalidate = fn;
+}
+/**
+ * Invalidate the graph cache for a project slug.
+ * No-op if the graph module hasn't been loaded yet.
+ */
+export function invalidateGraphCache(slug) {
+    if (_invalidate)
+        _invalidate(slug);
+}
+//# sourceMappingURL=graph-invalidate.js.map

package/dist/retrieval/graph-invalidate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-invalidate.js","sourceRoot":"","sources":["../../src/retrieval/graph-invalidate.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,IAAI,WAAW,GAAwB,IAAI,CAAC;AAE5C;;GAEG;AACH,MAAM,UAAU,6BAA6B,CAAC,EAAgB;IAC5D,WAAW,GAAG,EAAE,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAY;IAC/C,IAAI,WAAW;QAAE,WAAW,CAAC,IAAI,CAAC,CAAC;AACrC,CAAC"}

package/dist/retrieval/graph-retrieval.d.ts

@@ -0,0 +1,24 @@
+/**
+ * High-level graph retrieval API — combines graph building, traversal,
+ * and result hydration into a single call.
+ */
+import type { NodeType } from "./graph-types.js";
+export interface RelatedResult {
+    id: string;
+    type: NodeType;
+    title: string;
+    summary?: string;
+    score: number;
+    relation: string;
+}
+export interface RetrieveRelatedOptions {
+    limit?: number;
+    types?: NodeType[];
+    audience?: string;
+}
+/**
+ * Retrieves entities related to a given start node via graph traversal,
+ * hydrating results with metadata (titles, summaries).
+ */
+export declare function retrieveRelated(slug: string, startNodeId: string, options?: RetrieveRelatedOptions): Promise<RelatedResult[]>;
+//# sourceMappingURL=graph-retrieval.d.ts.map

package/dist/retrieval/graph-retrieval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-retrieval.d.ts","sourceRoot":"","sources":["../../src/retrieval/graph-retrieval.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAcH,OAAO,KAAK,EAAkB,QAAQ,EAAc,MAAM,kBAAkB,CAAC;AAM7E,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,sBAAsB;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,QAAQ,EAAE,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAqDD;;;GAGG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,aAAa,EAAE,CAAC,CA2G1B"}

package/dist/retrieval/graph-retrieval.js

@@ -0,0 +1,165 @@
+/**
+ * High-level graph retrieval API — combines graph building, traversal,
+ * and result hydration into a single call.
+ */
+import { getProjectDir } from "../utils/paths.js";
+import { listTasks, readKnowledgeIndex, readPlanIndex, } from "../utils/project-memory.js";
+import { createGraphCache } from "./graph-cache.js";
+import { registerGraphCacheInvalidator } from "./graph-invalidate.js";
+import { traverseFrom } from "./graph-traverse.js";
+// Module-level singleton cache
+const graphCache = createGraphCache();
+registerGraphCacheInvalidator((slug) => graphCache.invalidate(slug));
+/**
+ * Derives a human-readable relation string from the traversal path and graph.
+ */
+function deriveRelation(scored, index) {
+    const { path } = scored;
+    // Walk the path and find meaningful edges
+    for (let i = 0; i < path.length - 1; i++) {
+        const fromId = path[i];
+        const toId = path[i + 1];
+        const fromNode = index.nodes.get(fromId);
+        const toNode = index.nodes.get(toId);
+        // If path goes through a file node
+        if (toNode?.type === "file") {
+            const filePath = toNode.title ?? toId.replace("file:", "");
+            return `shares file ${filePath}`;
+        }
+        if (fromNode?.type === "file") {
+            const filePath = fromNode.title ?? fromId.replace("file:", "");
+            return `shares file ${filePath}`;
+        }
+        // Check edge relation
+        const edges = index.edges.get(fromId);
+        if (edges) {
+            const edge = edges.find((e) => e.target === toId);
+            if (edge) {
+                if (edge.relation === "task_belongs_to_plan" || edge.relation === "plan_contains_task") {
+                    return "same plan";
+                }
+                if (edge.relation === "shares_keywords") {
+                    // Find shared keywords between start and result
+                    const fromKw = fromNode?.keywords ?? [];
+                    const toKw = index.nodes.get(scored.node.id)?.keywords ?? [];
+                    const shared = fromKw.filter((kw) => toKw.includes(kw));
+                    if (shared.length > 0) {
+                        return `shares keywords [${shared.join(", ")}]`;
+                    }
+                    return "shares keywords";
+                }
+                if (edge.relation === "shares_source_file") {
+                    return `shares file`;
+                }
+            }
+        }
+    }
+    return "related";
+}
+/**
+ * Retrieves entities related to a given start node via graph traversal,
+ * hydrating results with metadata (titles, summaries).
+ */
+export async function retrieveRelated(slug, startNodeId, options) {
+    const limit = options?.limit ?? 10;
+    const types = options?.types ?? ["knowledge", "plan", "task"];
+    const audience = options?.audience;
+    // 1. Build/get graph
+    let index;
+    try {
+        index = await graphCache.getOrBuild(slug);
+    }
+    catch {
+        return [];
+    }
+    // 2. Verify start node exists
+    if (!index.nodes.has(startNodeId)) {
+        return [];
+    }
+    // 3. Traverse — exclude file nodes from results, over-fetch for post-filtering
+    const scored = traverseFrom(index, startNodeId, {
+        excludeTypes: ["file"],
+        limit: limit * 2,
+    });
+    // 4. Hydrate — load metadata indexes
+    const projectDir = getProjectDir(slug);
+    const knowledgeMap = new Map();
+    const planMap = new Map();
+    const taskMap = new Map();
+    try {
+        const kIdx = await readKnowledgeIndex(projectDir);
+        for (const e of kIdx.entries)
+            knowledgeMap.set(e.id, e);
+    }
+    catch {
+        // graceful
+    }
+    try {
+        const pIdx = await readPlanIndex(projectDir);
+        for (const p of pIdx.plans)
+            planMap.set(p.id, p);
+    }
+    catch {
+        // graceful
+    }
+    try {
+        const tasks = await listTasks(projectDir);
+        for (const t of tasks)
+            taskMap.set(t.id, t);
+    }
+    catch {
+        // graceful
+    }
+    // 5. Build results
+    const results = [];
+    for (const s of scored) {
+        const node = s.node;
+        const rawId = node.id.replace(/^(task|plan|knowledge|file):/, "");
+        // Type filter
+        if (!types.includes(node.type))
+            continue;
+        // Hydrate
+        let title = node.title ?? rawId;
+        let summary;
+        if (node.type === "knowledge") {
+            const meta = knowledgeMap.get(rawId);
+            if (meta) {
+                title = meta.title;
+                summary = meta.summary || undefined;
+                // Audience filter
+                if (audience &&
+                    meta.audience &&
+                    meta.audience !== audience &&
+                    meta.audience !== "universal") {
+                    continue;
+                }
+            }
+        }
+        else if (node.type === "plan") {
+            const meta = planMap.get(rawId);
+            if (meta) {
+                title = meta.title;
+                summary = meta.summary || undefined;
+            }
+        }
+        else if (node.type === "task") {
+            const meta = taskMap.get(rawId);
+            if (meta) {
+                title = meta.title;
+            }
+        }
+        const relation = deriveRelation(s, index);
+        results.push({
+            id: rawId,
+            type: node.type,
+            title,
+            summary,
+            score: s.score,
+            relation,
+        });
+        if (results.length >= limit)
+            break;
+    }
+    return results;
+}
+//# sourceMappingURL=graph-retrieval.js.map

package/dist/retrieval/graph-retrieval.js.map

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

package/dist/retrieval/graph-traverse.d.ts

@@ -0,0 +1,3 @@
+import type { AdjacencyIndex, ScoredNode, TraversalOptions } from "./graph-types.js";
+export declare function traverseFrom(index: AdjacencyIndex, startNodeId: string, options?: TraversalOptions): ScoredNode[];
+//# sourceMappingURL=graph-traverse.d.ts.map

package/dist/retrieval/graph-traverse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-traverse.d.ts","sourceRoot":"","sources":["../../src/retrieval/graph-traverse.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAErF,wBAAgB,YAAY,CAC1B,KAAK,EAAE,cAAc,EACrB,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,gBAAgB,GACzB,UAAU,EAAE,CAyDd"}

package/dist/retrieval/graph-traverse.js

@@ -0,0 +1,53 @@
+export function traverseFrom(index, startNodeId, options) {
+    const maxDepth = options?.maxDepth ?? 3;
+    const minScore = options?.minScore ?? 0.2;
+    const limit = options?.limit ?? 10;
+    const excludeTypes = options?.excludeTypes ?? [];
+    const startNode = index.nodes.get(startNodeId);
+    if (!startNode)
+        return [];
+    const edges = index.edges.get(startNodeId);
+    if (!edges || edges.length === 0)
+        return [];
+    // Track best score and path for each node
+    const bestScores = new Map();
+    // BFS queue: [nodeId, currentScore, depth, path]
+    const queue = [];
+    queue.push([startNodeId, 1.0, 0, [startNodeId]]);
+    while (queue.length > 0) {
+        const [nodeId, score, depth, path] = queue.shift();
+        if (depth >= maxDepth)
+            continue;
+        const nodeEdges = index.edges.get(nodeId);
+        if (!nodeEdges)
+            continue;
+        for (const edge of nodeEdges) {
+            const childId = edge.target;
+            const childScore = score * edge.weight;
+            if (childScore < minScore)
+                continue;
+            const childNode = index.nodes.get(childId);
+            if (!childNode)
+                continue;
+            const childPath = [...path, childId];
+            const existing = bestScores.get(childId);
+            if (existing && existing.score >= childScore)
+                continue;
+            bestScores.set(childId, { score: childScore, path: childPath });
+            queue.push([childId, childScore, depth + 1, childPath]);
+        }
+    }
+    // Build results, excluding start node and excludeTypes
+    const results = [];
+    for (const [nodeId, { score, path }] of bestScores) {
+        if (nodeId === startNodeId)
+            continue;
+        const node = index.nodes.get(nodeId);
+        if (excludeTypes.includes(node.type))
+            continue;
+        results.push({ node, score, path });
+    }
+    results.sort((a, b) => b.score - a.score);
+    return results.slice(0, limit);
+}
+//# sourceMappingURL=graph-traverse.js.map

package/dist/retrieval/graph-traverse.js.map

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

package/dist/retrieval/graph-types.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Core types for ARCS's graph-based retrieval layer.
+ */
+export type NodeType = "task" | "plan" | "knowledge" | "file";
+export type EdgeRelation = "task_belongs_to_plan" | "shares_source_file" | "knowledge_touches_file" | "plan_contains_task" | "shares_keywords" | "project_depends_on";
+export interface GraphNode {
+    id: string;
+    type: NodeType;
+    title?: string;
+    keywords?: string[];
+}
+export interface GraphEdge {
+    source: string;
+    target: string;
+    relation: EdgeRelation;
+    weight: number;
+}
+export interface AdjacencyIndex {
+    nodes: Map<string, GraphNode>;
+    edges: Map<string, GraphEdge[]>;
+    fileIndex: Map<string, string[]>;
+    buildTime: string;
+    sourceHashes: Record<string, number>;
+}
+export interface TraversalOptions {
+    maxDepth?: number;
+    minScore?: number;
+    limit?: number;
+    excludeTypes?: NodeType[];
+}
+export interface ScoredNode {
+    node: GraphNode;
+    score: number;
+    path: string[];
+}
+export declare const EDGE_WEIGHTS: Record<EdgeRelation, number>;
+//# sourceMappingURL=graph-types.d.ts.map