akm-cli 0.8.0-rc1 → 0.8.0

package/dist/commands/feedback-cli.js

@@ -0,0 +1,331 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import fs from "node:fs";
+import { defineCommand } from "citty";
+import { output, parseAllFlagValues, runWithJsonErrors } from "../cli/shared";
+import { parseAssetRef } from "../core/asset-ref";
+import { assembleAsset } from "../core/asset-serialize";
+import { writeFileAtomic } from "../core/common";
+import { FEEDBACK_FAILURE_MODES, loadConfig } from "../core/config";
+import { UsageError } from "../core/errors";
+import { appendEvent } from "../core/events";
+import { parseFrontmatter, parseFrontmatterBlock } from "../core/frontmatter";
+import { warn } from "../core/warn";
+import { applyFeedbackToUtilityScore, closeDatabase, findEntryIdByRef, openExistingDatabase } from "../indexer/db";
+import { ensureIndex } from "../indexer/ensure-index";
+import { resolveSourceEntries } from "../indexer/search-source";
+import { insertUsageEvent } from "../indexer/usage-events";
+// ── Tag validation ────────────────────────────────────────────────────────────
+const TAG_KEY_RE = /^[a-z_][a-z0-9_]*$/;
+const MAX_FEEDBACK_TAGS = 10;
+function validateFeedbackTags(raw) {
+    const seen = new Set();
+    const out = [];
+    for (const tag of raw) {
+        const parts = tag.split(":");
+        if (parts.length < 2 || parts[0] === "" || parts.slice(1).join("") === "") {
+            throw new UsageError(`Invalid tag "${tag}". Tags must be in key:value format where key matches [a-z_][a-z0-9_]* and value is non-empty.`, "INVALID_FLAG_VALUE");
+        }
+        const key = parts[0];
+        if (!TAG_KEY_RE.test(key)) {
+            throw new UsageError(`Invalid tag key "${key}" in "${tag}". Key must match [a-z_][a-z0-9_]*.`, "INVALID_FLAG_VALUE");
+        }
+        if (seen.has(tag))
+            continue;
+        seen.add(tag);
+        out.push(tag);
+    }
+    if (out.length > MAX_FEEDBACK_TAGS) {
+        throw new UsageError(`Too many tags: ${out.length}. Maximum is ${MAX_FEEDBACK_TAGS}.`, "INVALID_FLAG_VALUE");
+    }
+    return out;
+}
+// ── Lesson strength helper ────────────────────────────────────────────────────
+/**
+ * Phase 7A: append a feedback ref to a lesson's `lessonStrength[]`
+ * frontmatter array. Returns `{ strength }` (post-update count) on success,
+ * or `null` when the lesson cannot be located. Idempotent: if the ref is
+ * already credited, no write occurs.
+ *
+ * The function looks up the lesson's file via the indexer DB so the write
+ * targets the canonical on-disk location. Frontmatter is rewritten in
+ * place (no asset-spec round-trip) because we're modifying a single key on
+ * an existing asset — the same pattern memory-inference uses for
+ * `inferenceProcessed`.
+ */
+function appendLessonStrength(type, name, feedbackRef) {
+    const ref = `${type}:${name}`;
+    let filePath;
+    const db = openExistingDatabase();
+    try {
+        const entryId = findEntryIdByRef(db, ref);
+        if (entryId === undefined) {
+            warn(`[feedback] --applied-to: lesson ${ref} is not in the index.`);
+            return null;
+        }
+        const row = db.prepare("SELECT file_path FROM entries WHERE id = ?").get(entryId);
+        if (!row?.file_path) {
+            warn(`[feedback] --applied-to: cannot resolve file path for ${ref}.`);
+            return null;
+        }
+        filePath = row.file_path;
+    }
+    finally {
+        closeDatabase(db);
+    }
+    if (!filePath || !fs.existsSync(filePath)) {
+        warn(`[feedback] --applied-to: lesson file missing on disk for ${ref}.`);
+        return null;
+    }
+    const raw = fs.readFileSync(filePath, "utf8");
+    const parsed = parseFrontmatter(raw);
+    const data = { ...parsed.data };
+    const existing = data.lessonStrength;
+    const strengthList = Array.isArray(existing)
+        ? existing.filter((x) => typeof x === "string" && x.trim().length > 0).map((x) => x.trim())
+        : typeof existing === "string" && existing.trim().length > 0
+            ? [existing.trim()]
+            : [];
+    if (strengthList.includes(feedbackRef)) {
+        // Already credited — idempotent no-op.
+        return { strength: strengthList.length };
+    }
+    strengthList.push(feedbackRef);
+    data.lessonStrength = strengthList;
+    const block = parseFrontmatterBlock(raw);
+    const body = block?.content ?? raw;
+    const next = assembleAsset(data, body);
+    try {
+        // Preserve the existing file's permission bits (markdown assets are
+        // typically 0o644); writeFileAtomic defaults to 0o600 otherwise.
+        const mode = fs.statSync(filePath).mode & 0o777;
+        writeFileAtomic(filePath, next, mode);
+    }
+    catch (err) {
+        warn(`[feedback] --applied-to: failed to write ${filePath}: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+    return { strength: strengthList.length };
+}
+// ── Command definition ────────────────────────────────────────────────────────
+export const feedbackCommand = defineCommand({
+    meta: {
+        name: "feedback",
+        description: "Record positive or negative feedback for any indexed stash asset.\n\n" +
+            "Positive feedback boosts an asset's EMA utility score, making it rank higher\n" +
+            "in future searches without requiring a full reindex.\n\n" +
+            "Negative feedback records a negative signal in usage_events and state.db events.\n" +
+            "It does NOT immediately lower the asset's ranking — the EMA utility score is\n" +
+            "updated the next time `akm index` runs (incremental or full). Run `akm index`\n" +
+            "after recording negative feedback to have it reflected in search results.",
+    },
+    args: {
+        // Optional in citty so run() is invoked even when omitted; we re-validate
+        // and throw a structured UsageError below so exit code is 2 (USAGE) rather
+        // than citty's default 0 (help banner).
+        ref: { type: "positional", description: "Asset ref (type:name)", required: false },
+        positive: { type: "boolean", description: "Record positive feedback (boosts ranking immediately)", default: false },
+        negative: {
+            type: "boolean",
+            description: "Record negative feedback (suppresses ranking after next `akm index`). " +
+                "Reindexing is required for the signal to affect search results.",
+            default: false,
+        },
+        reason: {
+            type: "string",
+            description: "Reason for the feedback (required for negative feedback by default; used by distillation)",
+        },
+        note: { type: "string", description: "Alias for --reason (backward-compatible, prefer --reason)" },
+        "failure-mode": {
+            type: "string",
+            description: `Structured failure-mode taxonomy for negative feedback (F-3 / #384). ` +
+                `Accepted values: ${FEEDBACK_FAILURE_MODES.join(", ")}. ` +
+                "Stored alongside --reason in event metadata for aggregation by the distill pipeline.",
+        },
+        tag: {
+            type: "string",
+            description: "Tag to attach to the feedback (repeatable, e.g. --tag slice:train --tag team:platform)",
+        },
+        "applied-to": {
+            type: "string",
+            description: "Credit a lesson that helped resolve this task. Accepts a `lesson:<name>` ref. " +
+                "When combined with --positive, appends this feedback ref to the target lesson's " +
+                "`lessonStrength[]` frontmatter array (dedup, idempotent). Ignored on non-lesson targets.",
+        },
+    },
+    run({ args }) {
+        return runWithJsonErrors(async () => {
+            const ref = (args.ref ?? "").trim();
+            if (!ref) {
+                throw new UsageError("Asset ref is required. Usage: akm feedback <ref> --positive|--negative", "MISSING_REQUIRED_ARGUMENT", "Pass a ref like `skill:deploy` and either --positive or --negative.");
+            }
+            parseAssetRef(ref);
+            if (args.positive && args.negative) {
+                throw new UsageError("Specify either --positive or --negative, not both.");
+            }
+            if (!args.positive && !args.negative) {
+                throw new UsageError("Specify --positive or --negative.");
+            }
+            const signal = args.positive ? "positive" : "negative";
+            // `--note` is a deprecated back-compat alias for `--reason` (removed in
+            // 0.9.0). Warn on stderr when it is used as the sole source (i.e. without
+            // an explicit `--reason`). Warnings go to stderr only so JSON stdout
+            // consumers are unaffected.
+            if (args.note !== undefined && args.reason === undefined) {
+                warn("warning: '--note' is deprecated for 'akm feedback'; use '--reason'. Removed in 0.9.0.");
+            }
+            const reason = args.reason ?? args.note;
+            // F-3 / #384: Validate --failure-mode against the curated enum.
+            const failureMode = args["failure-mode"]?.trim() || undefined;
+            if (failureMode) {
+                if (args.positive) {
+                    throw new UsageError("--failure-mode is only valid for negative feedback.", "INVALID_FLAG_VALUE", "Remove --failure-mode or switch to --negative.");
+                }
+                const cfg = loadConfig();
+                const allowedModes = cfg.feedback?.allowedFailureModes ?? FEEDBACK_FAILURE_MODES;
+                if (allowedModes.length > 0 && !allowedModes.includes(failureMode)) {
+                    throw new UsageError(`Invalid --failure-mode "${failureMode}". Accepted values: ${allowedModes.join(", ")}.`, "INVALID_FLAG_VALUE", `Use one of: ${allowedModes.join(", ")}`);
+                }
+            }
+            if (args.negative === true && !reason?.trim()) {
+                // F-3 / #384: Default requireReason is now true. Load config to allow
+                // operators to opt out via feedback.requireReason: false in akm.json.
+                const cfg = loadConfig();
+                const requireReason = cfg.feedback?.requireReason ?? true; // Default: true (F-3 / #384)
+                if (requireReason) {
+                    throw new UsageError("Negative feedback requires --reason (structured failure signals are needed for distillation). " +
+                        "Use --failure-mode for a curated taxonomy or --reason for free text. " +
+                        "Set feedback.requireReason: false in akm.json to downgrade to a warning.", "MISSING_REQUIRED_ARGUMENT", `Hint: akm feedback ${ref} --negative --reason "..." [--failure-mode incorrect|outdated|dangerous|incomplete|redundant]`);
+                }
+                else {
+                    warn("Warning: negative feedback without --reason provides less distillation signal.");
+                }
+            }
+            const rawTags = parseAllFlagValues("--tag");
+            const validatedTags = validateFeedbackTags(rawTags);
+            const metadataObj = {
+                signal,
+                ...(reason?.trim() ? { reason: reason.trim() } : {}),
+                ...(failureMode ? { failureMode } : {}),
+                ...(validatedTags.length > 0 ? { tags: validatedTags } : {}),
+            };
+            const metadataStr = Object.keys(metadataObj).length > 1 ? JSON.stringify(metadataObj) : undefined;
+            // Auto-index when stale so the index is current before recording feedback.
+            const sources = resolveSourceEntries();
+            if (sources.length > 0) {
+                await ensureIndex(sources[0].path);
+            }
+            let utilityResult;
+            const db = openExistingDatabase();
+            try {
+                const entryId = findEntryIdByRef(db, ref);
+                if (entryId === undefined) {
+                    throw new UsageError(`Ref "${ref}" is not in the index. ` +
+                        "Run 'akm search' to verify the asset exists, then 'akm index' if it was recently added.");
+                }
+                // Persist the feedback signal into usage_events. For positive signals,
+                // the EMA utility score is updated immediately on the next read path.
+                // For negative signals, the score is adjusted the next time `akm index`
+                // runs — the signal is durable in the DB but does NOT suppress ranking
+                // in search results until after reindexing.
+                insertUsageEvent(db, {
+                    event_type: "feedback",
+                    entry_ref: ref,
+                    entry_id: entryId,
+                    signal,
+                    metadata: metadataStr,
+                });
+                // Apply feedback-derived utility score adjustment immediately so that
+                // positive/negative signals influence search ranking without requiring
+                // a full reindex. We query the total accumulated feedback counts from
+                // usage_events so the delta reflects the entire signal history.
+                // Uses MemRL bounded-step EMA (F-5 / #386, arXiv:2601.03192).
+                try {
+                    const counts = db
+                        .prepare(`SELECT
+                 SUM(CASE WHEN signal = 'positive' THEN 1 ELSE 0 END) AS pos,
+                 SUM(CASE WHEN signal = 'negative' THEN 1 ELSE 0 END) AS neg
+               FROM usage_events
+               WHERE event_type = 'feedback' AND entry_id = ?`)
+                        .get(entryId);
+                    const pos = counts?.pos ?? 0;
+                    const neg = counts?.neg ?? 0;
+                    utilityResult = applyFeedbackToUtilityScore(db, entryId, pos, neg);
+                }
+                catch {
+                    // best-effort — feedback recording succeeds even if utility update fails
+                }
+            }
+            finally {
+                closeDatabase(db);
+            }
+            appendEvent({
+                eventType: "feedback",
+                ref,
+                metadata: metadataObj,
+            });
+            // F-5 / #386: When a high-utility asset crosses below the review threshold,
+            // auto-create a review-needed escalation proposal so a human can confirm
+            // whether the negative feedback is valid before the asset falls out of
+            // the improve loop. Best-effort — failure is logged but does not fail the
+            // feedback command.
+            // Emit a structured event rather than a proposal so the review-needed
+            // signal is queryable via `akm events list --type improve_review_needed`
+            // without risking accidental asset overwrite if the proposal is accepted.
+            if (utilityResult?.crossedReviewThreshold) {
+                try {
+                    appendEvent({
+                        eventType: "improve_review_needed",
+                        ref,
+                        metadata: {
+                            previousUtility: utilityResult.previousUtility,
+                            nextUtility: utilityResult.nextUtility,
+                            reason: reason?.trim() ?? null,
+                            failureMode: failureMode ?? null,
+                        },
+                    });
+                }
+                catch (escalationErr) {
+                    warn(`[feedback] Could not emit review-needed event for ${ref}: ${escalationErr instanceof Error ? escalationErr.message : String(escalationErr)}`);
+                }
+            }
+            // Phase 7A / Advantage D4b: --applied-to credits a lesson. When the
+            // target is a `lesson:<name>` ref and the signal is positive, append
+            // the feedback ref to the target lesson's `lessonStrength[]`
+            // frontmatter array (dedup, idempotent). Non-lesson targets are
+            // ignored. Failures here are warnings — feedback recording is the
+            // primary contract and must not regress on lesson-write errors.
+            const appliedToRaw = args["applied-to"]?.trim();
+            let appliedToResult = null;
+            if (appliedToRaw && signal === "positive") {
+                try {
+                    const parsedApplied = parseAssetRef(appliedToRaw);
+                    if (parsedApplied.type === "lesson") {
+                        const updated = appendLessonStrength(parsedApplied.type, parsedApplied.name, ref);
+                        if (updated) {
+                            appliedToResult = { lessonRef: appliedToRaw, strength: updated.strength };
+                        }
+                    }
+                }
+                catch (err) {
+                    warn(`[feedback] --applied-to failed for ${appliedToRaw}: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            else if (appliedToRaw && signal !== "positive") {
+                warn("[feedback] --applied-to is ignored without --positive; lesson credit is only recorded on positive signals.");
+            }
+            output("feedback", {
+                ok: true,
+                ref,
+                signal,
+                reason: reason?.trim() ?? null,
+                failureMode: failureMode ?? null,
+                tags: validatedTags,
+                ...(appliedToResult
+                    ? { appliedTo: { ref: appliedToResult.lessonRef, lessonStrength: appliedToResult.strength } }
+                    : {}),
+            });
+        });
+    },
+});

package/dist/commands/graph.js

@@ -1,11 +1,17 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
 import path from "node:path";
 import { parseAssetRef } from "../core/asset-ref";
 import { loadConfig } from "../core/config";
 import { NotFoundError, UsageError } from "../core/errors";
-import { closeDatabase, openExistingDatabase } from "../indexer/db";
+import { getDbPath } from "../core/paths";
+import { warn } from "../core/warn";
+import { closeDatabase, findEntryIdByRef, getEntryById, openDatabase, openExistingDatabase } from "../indexer/db";
 import { listRelatedPathsForFile } from "../indexer/graph-boost";
 import { loadStoredGraphSnapshot } from "../indexer/graph-db";
+import { runGraphExtractionPass } from "../indexer/graph-extraction";
 import { lookup } from "../indexer/indexer";
 import { resolveAssetPath } from "../indexer/path-resolver";
 import { findSourceForPath, resolveSourceEntries } from "../indexer/search-source";
@@ -40,6 +46,7 @@ function loadGraph(source) {
                 entities: snapshot.entities,
                 relations: snapshot.relations,
                 ...(snapshot.quality ? { quality: snapshot.quality } : {}),
+                ...(snapshot.telemetry ? { telemetry: snapshot.telemetry } : {}),
             },
             stashPath,
             graphPath: snapshot.graphPath,
@@ -63,6 +70,29 @@ function countEntitiesByFile(nodes) {
     }
     return counts;
 }
+function aggregateEntityStats(nodes) {
+    const stats = new Map();
+    for (const node of nodes) {
+        const seen = new Set();
+        for (const entity of node.entities) {
+            if (seen.has(entity))
+                continue;
+            seen.add(entity);
+            const existing = stats.get(entity);
+            const nodeConf = typeof node.confidence === "number" && Number.isFinite(node.confidence) ? node.confidence : undefined;
+            if (existing) {
+                existing.fileCount += 1;
+                if (nodeConf !== undefined && (existing.confidence === undefined || nodeConf > existing.confidence)) {
+                    existing.confidence = nodeConf;
+                }
+            }
+            else {
+                stats.set(entity, { fileCount: 1, ...(nodeConf !== undefined ? { confidence: nodeConf } : {}) });
+            }
+        }
+    }
+    return stats;
+}
 export function akmGraphSummary(options) {
     const { graph, stashPath, graphPath } = loadGraph(options?.source);
     return {
@@ -77,6 +107,7 @@ export function akmGraphSummary(options) {
             ? graph.relations.length
             : graph.files.reduce((sum, node) => sum + node.relations.length, 0),
         ...(graph.quality ? { quality: graph.quality } : {}),
+        ...(graph.telemetry ? { telemetry: graph.telemetry } : {}),
     };
 }
 export function akmGraphEntities(options) {
@@ -85,9 +116,13 @@ export function akmGraphEntities(options) {
     if (limit !== undefined && (!Number.isFinite(limit) || limit <= 0)) {
         throw new UsageError("--limit must be a positive integer.", "INVALID_FLAG_VALUE");
     }
-    const counts = countEntitiesByFile(graph.files);
-    const entities = [...counts.entries()]
-        .map(([name, fileCount]) => ({ name, fileCount }))
+    const stats = aggregateEntityStats(graph.files);
+    const entities = [...stats.entries()]
+        .map(([name, info]) => ({
+        name,
+        fileCount: info.fileCount,
+        ...(info.confidence !== undefined ? { confidence: info.confidence } : {}),
+    }))
         .sort((a, b) => b.fileCount - a.fileCount || a.name.localeCompare(b.name));
     const sliced = typeof limit === "number" ? entities.slice(0, limit) : entities;
     return {
@@ -110,12 +145,22 @@ export function akmGraphRelations(options) {
     for (const node of graph.files) {
         for (const rel of node.relations) {
             const key = `${rel.from}\u0000${rel.to}\u0000${rel.type ?? ""}`;
+            const relConf = typeof rel.confidence === "number" && Number.isFinite(rel.confidence) ? rel.confidence : undefined;
             const existing = counts.get(key);
             if (existing) {
                 existing.count += 1;
+                if (relConf !== undefined && (existing.confidence === undefined || relConf > existing.confidence)) {
+                    existing.confidence = relConf;
+                }
             }
             else {
-                counts.set(key, { from: rel.from, to: rel.to, ...(rel.type ? { type: rel.type } : {}), count: 1 });
+                counts.set(key, {
+                    from: rel.from,
+                    to: rel.to,
+                    ...(rel.type ? { type: rel.type } : {}),
+                    count: 1,
+                    ...(relConf !== undefined ? { confidence: relConf } : {}),
+                });
             }
         }
     }
@@ -194,6 +239,216 @@ export async function akmGraphRelated(options) {
         ...(related.length === 0 ? { tip: "No related graph neighbors were found for this asset." } : {}),
     };
 }
+function normalizeGraphName(value) {
+    return value.trim().toLowerCase();
+}
+function buildRefByPath(stashRoot, db) {
+    const rows = db
+        .prepare("SELECT file_path, entry_json FROM entries WHERE stash_dir = ? OR file_path LIKE ?")
+        .all(stashRoot, `${stashRoot}%`);
+    const map = new Map();
+    for (const row of rows) {
+        if (map.has(row.file_path))
+            continue;
+        try {
+            const entry = JSON.parse(row.entry_json);
+            if (typeof entry.type === "string" && typeof entry.name === "string") {
+                map.set(row.file_path, { ref: `${entry.type}:${entry.name}`, type: entry.type });
+            }
+        }
+        catch {
+            // ignore corrupt entry_json
+        }
+    }
+    return map;
+}
+export function akmGraphEntity(options) {
+    const name = options.name?.trim();
+    if (!name) {
+        throw new UsageError("`akm graph entity` requires <name>.", "MISSING_REQUIRED_ARGUMENT");
+    }
+    const limit = options.limit;
+    if (limit !== undefined && (!Number.isFinite(limit) || limit <= 0)) {
+        throw new UsageError("--limit must be a positive integer.", "INVALID_FLAG_VALUE");
+    }
+    const { graph, stashPath, graphPath } = loadGraph(options.source);
+    const target = normalizeGraphName(name);
+    let db;
+    let refByPath;
+    try {
+        db = openExistingDatabase();
+        refByPath = buildRefByPath(stashPath, db);
+    }
+    finally {
+        if (db)
+            closeDatabase(db);
+    }
+    const matches = [];
+    for (const node of graph.files) {
+        const found = node.entities.some((entity) => normalizeGraphName(entity) === target);
+        if (!found)
+            continue;
+        const lookup = refByPath.get(node.path);
+        const conf = typeof node.confidence === "number" && Number.isFinite(node.confidence) ? node.confidence : undefined;
+        matches.push({
+            ...(lookup?.ref ? { ref: lookup.ref } : {}),
+            path: node.path,
+            type: node.type,
+            ...(conf !== undefined ? { confidence: conf } : {}),
+        });
+    }
+    matches.sort((a, b) => {
+        const ca = a.confidence ?? 0;
+        const cb = b.confidence ?? 0;
+        if (cb !== ca)
+            return cb - ca;
+        return a.path.localeCompare(b.path);
+    });
+    const sliced = typeof limit === "number" ? matches.slice(0, limit) : matches;
+    return {
+        schemaVersion: 1,
+        shape: "graph-entity",
+        stashPath,
+        graphPath,
+        generatedAt: graph.generatedAt,
+        entity: name,
+        total: matches.length,
+        matches: sliced,
+    };
+}
+export function akmGraphOrphans(options) {
+    const limit = options?.limit;
+    if (limit !== undefined && (!Number.isFinite(limit) || limit <= 0)) {
+        throw new UsageError("--limit must be a positive integer.", "INVALID_FLAG_VALUE");
+    }
+    const { graph, stashPath, graphPath } = loadGraph(options?.source);
+    let db;
+    let refByPath;
+    try {
+        db = openExistingDatabase();
+        refByPath = buildRefByPath(stashPath, db);
+    }
+    finally {
+        if (db)
+            closeDatabase(db);
+    }
+    const orphans = [];
+    for (const node of graph.files) {
+        if ((node.status ?? (node.entities.length > 0 ? "extracted" : "empty")) === "extracted")
+            continue;
+        const lookup = refByPath.get(node.path);
+        orphans.push({
+            ...(lookup?.ref ? { ref: lookup.ref } : {}),
+            path: node.path,
+            type: node.type,
+            ...(node.status ? { status: node.status } : {}),
+            ...(node.reason ? { reason: node.reason } : {}),
+        });
+    }
+    orphans.sort((a, b) => a.type.localeCompare(b.type) || a.path.localeCompare(b.path));
+    const sliced = typeof limit === "number" ? orphans.slice(0, limit) : orphans;
+    return {
+        schemaVersion: 1,
+        shape: "graph-orphans",
+        stashPath,
+        graphPath,
+        generatedAt: graph.generatedAt,
+        totalConsidered: graph.files.length,
+        total: orphans.length,
+        orphans: sliced,
+    };
+}
+/**
+ * Re-run graph extraction, optionally scoped to specific asset refs.
+ *
+ * When `refs` is provided, only those files are re-extracted (incremental).
+ * When no refs are given, the full eligible set is re-extracted.
+ */
+export async function akmGraphUpdate(options) {
+    const config = options.config ?? loadConfig();
+    const sources = resolveSourceEntries(options.stashDir, config);
+    if (sources.length === 0) {
+        throw new NotFoundError("No stash sources are configured.", "STASH_NOT_FOUND");
+    }
+    if (options.source && options.source !== "primary") {
+        const matched = sources.find((s) => s.registryId === options.source || s.path === options.source);
+        if (!matched) {
+            throw new NotFoundError(`Source not found: ${options.source}`, "SOURCE_NOT_FOUND", "Run `akm list` to see source names.");
+        }
+    }
+    const scoped = Array.isArray(options.refs) && options.refs.length > 0;
+    let candidatePaths;
+    if (scoped && options.refs) {
+        // Resolve each ref to an absolute file path via the index DB.
+        const dbPath = getDbPath();
+        let db;
+        const resolvedPaths = new Set();
+        try {
+            db = openDatabase(dbPath);
+            for (const ref of options.refs) {
+                const trimmed = ref.trim();
+                if (!trimmed)
+                    continue;
+                const entryId = findEntryIdByRef(db, trimmed);
+                if (entryId === undefined) {
+                    warn(`[graph] ref not found in index, skipping: ${trimmed}`);
+                    continue;
+                }
+                const row = getEntryById(db, entryId);
+                if (!row?.filePath) {
+                    warn(`[graph] could not resolve path for ref, skipping: ${trimmed}`);
+                    continue;
+                }
+                resolvedPaths.add(row.filePath);
+            }
+        }
+        finally {
+            if (db)
+                closeDatabase(db);
+        }
+        if (resolvedPaths.size === 0) {
+            warn("[graph] none of the provided refs resolved to indexed paths — no extraction performed.");
+            return {
+                shape: "graph-update",
+                ok: true,
+                filesExtracted: 0,
+                entitiesUpserted: 0,
+                relationsUpserted: 0,
+                durationMs: 0,
+                scoped: true,
+            };
+        }
+        candidatePaths = resolvedPaths;
+    }
+    const extractionFn = options.graphExtractionFn ?? runGraphExtractionPass;
+    const passOptions = candidatePaths ? { candidatePaths } : {};
+    let db;
+    const startMs = Date.now();
+    try {
+        db = openDatabase(getDbPath());
+        const onProgress = (event) => {
+            if (!event.currentPath)
+                return;
+            const file = path.basename(event.currentPath);
+            warn(`[graph] extracting ${event.processed}/${event.total} ${file}`);
+        };
+        const result = await extractionFn(config, sources, undefined, db, false, onProgress, passOptions);
+        const durationMs = Date.now() - startMs;
+        return {
+            shape: "graph-update",
+            ok: true,
+            filesExtracted: result.quality.extractedFiles,
+            entitiesUpserted: result.quality.entityCount,
+            relationsUpserted: result.quality.relationCount,
+            durationMs,
+            scoped,
+        };
+    }
+    finally {
+        if (db)
+            closeDatabase(db);
+    }
+}
 async function resolveGraphTarget(ref, source) {
     const parsedRef = parseAssetRef(ref);
     const filePath = (await resolveAssetPath(parsedRef, {