akm-cli 0.9.17-alpha.2 → 0.9.17-alpha.4

package/dist/execution/source.js

@@ -1,102 +1,38 @@
 // 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 { bundleRefToString, isBundleSlug, parseBundleRef } from "../core/asset/asset-ref.js";
-import { cloneExecutionJson, cloneExecutionJsonObject, } from "./json.js";
-import { assertSnapshotKeys, snapshotStrictRecord } from "./record.js";
+import { cloneExecutionJson, cloneExecutionJsonObject } from "./json.js";
 export const EXECUTION_SOURCE_SCHEMA_VERSION = 1;
 /** Current internal adapter identifiers are lowercase kebab-case registry keys. */
 export const EXECUTION_ADAPTER_ID_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
-const CONTROL_OR_LINE_SEPARATOR_PATTERN = /[\p{Cc}\p{Zl}\p{Zp}]/u;
-const FORMAT_CHARACTER_PATTERN = /\p{Cf}/u;
-const WINDOWS_DRIVE_PREFIX_PATTERN = /^[A-Za-z]:/;
-const RESERVED_EXTENSION_OWNERS = new Set(["__proto__", "constructor", "prototype", "tostring"]);
-const renderedSourceBrand = Symbol("akm.adapter-rendered-execution-source");
-const renderedSourceInstances = new WeakSet();
 function requireRecord(value, path) {
-    return snapshotStrictRecord(value, path);
-}
-function assertOnlyKeys(value, allowed, path) {
-    assertSnapshotKeys(value, allowed, path);
-}
-function validateExtensionOwner(owner) {
-    const normalized = owner.toLowerCase();
-    if (!EXECUTION_ADAPTER_ID_PATTERN.test(owner) || RESERVED_EXTENSION_OWNERS.has(normalized)) {
-        throw new TypeError(`extension owner must be a canonical, non-reserved adapter identifier: ${owner}`);
-    }
-}
-function frozenNullPrototypeMap(entries) {
-    const out = Object.create(null);
-    for (const [key, value] of entries) {
-        Object.defineProperty(out, key, { value, enumerable: true, configurable: false, writable: false });
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new TypeError(`${path} must be an object`);
     }
-    return Object.freeze(out);
-}
-function cloneExtensionEntry(value, index) {
-    const path = `extension entry ${index}`;
-    const cloned = cloneExecutionJson(value, path);
-    if (!Array.isArray(cloned) || cloned.length !== 2) {
-        throw new TypeError(`${path} must be a two-element [owner, values] array`);
-    }
-    const [owner, values] = cloned;
-    if (typeof owner !== "string")
-        throw new TypeError(`${path} owner must be a string`);
-    if (values === null || Array.isArray(values) || typeof values !== "object") {
-        throw new TypeError(`${path} values must be a JSON object`);
-    }
-    return [owner, values];
+    return value;
 }
 export function createAdapterExtensions(first, second, ...rest) {
-    const rawEntries = typeof first === "string"
+    const entries = typeof first === "string"
         ? [[first, second]]
         : [first, ...(second === undefined ? [] : [second]), ...rest];
-    const seen = new Set();
-    const cloned = [];
-    for (const [index, rawEntry] of rawEntries.entries()) {
-        const [owner, values] = cloneExtensionEntry(rawEntry, index);
-        validateExtensionOwner(owner);
-        if (seen.has(owner))
-            throw new TypeError(`duplicate extension owner: ${owner}`);
-        seen.add(owner);
-        cloned.push([owner, cloneExecutionJsonObject(values, `extensions.${owner}`)]);
-    }
-    return frozenNullPrototypeMap(cloned);
+    const out = {};
+    for (const [owner, values] of entries)
+        out[owner] = cloneExecutionJsonObject(values, `extensions.${owner}`);
+    return Object.freeze(out);
 }
 export function cloneAdapterExtensions(value, path) {
-    const record = requireRecord(value, path);
-    const entries = Object.entries(record).map(([owner, fields]) => [owner, cloneExecutionJsonObject(fields, `${path}.${owner}`)]);
-    const [first, ...rest] = entries;
-    return first ? createAdapterExtensions(first, ...rest) : frozenNullPrototypeMap([]);
-}
-function requireCanonicalString(value, path) {
-    if (typeof value !== "string" ||
-        value.length === 0 ||
-        !isWellFormedUnicode(value) ||
-        value.normalize("NFC") !== value) {
-        throw new TypeError(`${path} must be a non-empty NFC string`);
-    }
-    if (hasUnsafeIdentityCharacter(value)) {
-        throw new TypeError(`${path} must not contain Unicode control or dangerous format characters`);
+    const out = {};
+    for (const [owner, fields] of Object.entries(requireRecord(value, path))) {
+        out[owner] = cloneExecutionJsonObject(fields, `${path}.${owner}`);
     }
-    return value;
+    return Object.freeze(out);
 }
-/**
- * Validate a selector/layer identifier that may cross the durable execution
- * boundary. Keep this shared with the cascade planner so resume cannot admit a
- * selector the live planner would reject.
- */
+/** A selector or layer identifier that may cross the durable execution boundary. */
 export function requireStableExecutionSelector(value, path) {
-    let selector;
-    try {
-        selector = requireCanonicalString(value, path);
+    if (typeof value !== "string" || value.length === 0 || value.trim() !== value) {
+        throw new TypeError(`${path} must be a non-empty stable identifier`);
     }
-    catch (cause) {
-        throw new TypeError(`${path} must be a non-empty stable NFC identifier`, { cause });
-    }
-    if (selector.length > 512 || selector.trim() !== selector) {
-        throw new TypeError(`${path} must be a non-empty stable NFC identifier`);
-    }
-    return selector;
+    return value;
 }
 export function isPortableExecutionAgentSelector(value) {
     return /^(?:[^/]+\/\/)?agents\/[^/]/.test(value);
@@ -104,118 +40,61 @@ export function isPortableExecutionAgentSelector(value) {
 export function executionPersonaMatchesSelector(selector, personaRef) {
     return selector.includes("//") ? selector === personaRef : personaRef.endsWith(`//${selector}`);
 }
-function hasUnsafeIdentityCharacter(value) {
-    for (const character of value) {
-        if (CONTROL_OR_LINE_SEPARATOR_PATTERN.test(character))
-            return true;
-        // Join controls are meaningful in emoji and several writing systems. All
-        // other format controls are rejected because they can conceal identity.
-        if (FORMAT_CHARACTER_PATTERN.test(character) && character !== "\u200C" && character !== "\u200D")
-            return true;
-    }
-    return false;
-}
-function isWellFormedUnicode(value) {
-    for (let index = 0; index < value.length; index += 1) {
-        const code = value.charCodeAt(index);
-        if (code >= 0xd800 && code <= 0xdbff) {
-            const next = value.charCodeAt(index + 1);
-            if (!(next >= 0xdc00 && next <= 0xdfff))
-                return false;
-            index += 1;
-        }
-        else if (code >= 0xdc00 && code <= 0xdfff) {
-            return false;
-        }
-    }
-    return true;
-}
-function validateCanonicalIdentity(input, path) {
-    assertOnlyKeys(input, ["ref", "bundle", "adapter", "file", "hash"], path);
-    const ref = requireCanonicalString(input.ref, `${path}.ref`);
-    const bundle = requireCanonicalString(input.bundle, `${path}.bundle`);
-    const adapter = requireCanonicalString(input.adapter, `${path}.adapter`);
-    const file = requireCanonicalString(input.file, `${path}.file`);
-    const hash = requireCanonicalString(input.hash, `${path}.hash`);
-    let parsed;
-    try {
-        parsed = parseBundleRef(ref);
-    }
-    catch (cause) {
-        throw new TypeError(`${path}.ref is not a canonical bundle ref`, { cause });
-    }
-    if (parsed.bundle === undefined ||
-        parsed.bundle !== bundle ||
-        parsed.fragment !== undefined ||
-        !isBundleSlug(bundle) ||
-        bundleRefToString(parsed) !== ref) {
-        throw new TypeError(`${path}.ref must round-trip as the same fully-qualified bundle ref without a fragment`);
-    }
-    if (!EXECUTION_ADAPTER_ID_PATTERN.test(adapter)) {
-        throw new TypeError(`${path}.adapter must use the current lowercase kebab-case adapter identifier grammar`);
-    }
-    const segments = file.split("/");
-    if (file.startsWith("/") ||
-        WINDOWS_DRIVE_PREFIX_PATTERN.test(file) ||
-        file.includes("\\") ||
-        segments.some((segment) => !segment || segment === "." || segment === "..")) {
-        throw new TypeError(`${path}.file must be a normalized relative POSIX path`);
+const IDENTITY_KEYS = ["ref", "bundle", "adapter", "file", "hash"];
+function identityFrom(value, path) {
+    const record = requireRecord(value, path);
+    const out = {};
+    for (const key of IDENTITY_KEYS) {
+        const field = record[key];
+        if (typeof field !== "string" || field.length === 0)
+            throw new TypeError(`${path}.${key} must be a non-empty string`);
+        out[key] = field;
     }
-    if (!/^[a-f0-9]{64}$/.test(hash))
-        throw new TypeError(`${path}.hash must be a SHA-256 hex digest`);
-    return { ref, bundle, adapter, file, hash };
+    return Object.freeze(out);
 }
-/** Validate, clone, and freeze an identity produced by an adapter renderer. */
+/** Copy and freeze an identity produced by an adapter renderer. */
 export function createExecutionSourceIdentity(input) {
-    return Object.freeze(validateCanonicalIdentity(requireRecord(input, "execution source identity"), "execution source identity"));
+    return identityFrom(input, "execution source identity");
 }
-/** Validate and freeze a source identity read back from a frozen request. */
+/** Read a source identity back from a frozen request. */
 export function decodeExecutionSourceIdentity(value, path = "execution source identity") {
-    return Object.freeze(validateCanonicalIdentity(requireRecord(value, path), path));
+    return identityFrom(value, path);
 }
+/** Type-check the common frontmatter defaults; unknown keys are ignored. */
 export function cloneUnresolvedExecutionDefaults(input, path = "execution source defaults") {
     const record = requireRecord(input, path);
-    assertOnlyKeys(record, [
-        "agent",
-        "engine",
-        "model",
-        "inference",
-        "outputSchema",
-        "tools",
-        "timeout",
-        "workspace",
-        "environment",
-        "runtime",
-    ], path);
-    const json = { ...cloneExecutionJsonObject(record, path) };
+    const present = (key) => Object.hasOwn(record, key) && record[key] !== undefined;
+    const out = {};
     for (const key of ["agent", "engine", "model", "workspace"]) {
-        const value = json[key];
-        if (value !== undefined && value !== null && typeof value !== "string") {
+        if (!present(key))
+            continue;
+        const value = record[key];
+        if (value !== null && typeof value !== "string")
             throw new TypeError(`${path}.${key} must be a string or null`);
-        }
+        out[key] = value;
     }
-    const timeout = json.timeout;
-    if (timeout !== undefined && timeout !== null && typeof timeout !== "string" && typeof timeout !== "number") {
-        throw new TypeError(`${path}.timeout must be a string, number, or null`);
+    if (present("timeout")) {
+        const timeout = record.timeout;
+        if (timeout !== null && typeof timeout !== "string" && typeof timeout !== "number") {
+            throw new TypeError(`${path}.timeout must be a string, number, or null`);
+        }
+        out.timeout = timeout;
     }
     for (const key of ["inference", "outputSchema", "runtime"]) {
-        const value = json[key];
-        if (value !== undefined && value !== null && (Array.isArray(value) || typeof value !== "object")) {
-            throw new TypeError(`${path}.${key} must be an object or null`);
-        }
+        if (!present(key))
+            continue;
+        out[key] = record[key] === null ? null : cloneExecutionJsonObject(record[key], `${path}.${key}`);
     }
-    const environment = json.environment;
-    if (environment !== undefined && environment !== null) {
-        if (Array.isArray(environment) || typeof environment !== "object") {
-            throw new TypeError(`${path}.environment must be an object or null`);
-        }
-        if (Object.values(environment).some((value) => typeof value !== "string")) {
+    if (present("environment")) {
+        const environment = record.environment === null ? null : cloneExecutionJsonObject(record.environment, `${path}.environment`);
+        if (environment !== null && Object.values(environment).some((value) => typeof value !== "string")) {
             throw new TypeError(`${path}.environment values must be strings`);
         }
+        out.environment = environment;
     }
-    if (Object.hasOwn(json, "tools"))
-        json.tools = cloneToolSelection(json.tools, `${path}.tools`);
-    return Object.freeze(json);
+    if (present("tools"))
+        out.tools = cloneToolSelection(record.tools, `${path}.tools`);
+    return Object.freeze(out);
 }
 export function cloneToolSelection(value, path = "tools") {
     if (value === null || typeof value === "string")
@@ -229,92 +108,19 @@ export function cloneToolSelection(value, path = "tools") {
     return cloneExecutionJsonObject(cloned, path);
 }
 export function createAdapterRenderedExecutionSource(input) {
-    const record = requireRecord(input, "adapter-rendered execution source");
-    assertOnlyKeys(record, ["kind", "content", "identity", "defaults", "extensions"], "adapter-rendered execution source");
-    const kind = record.kind;
-    const content = record.content;
+    const { kind, content } = input;
     if (kind !== "command" && kind !== "persona")
         throw new TypeError("execution source kind is invalid");
     if (typeof content !== "string")
         throw new TypeError("execution source content must be a string");
-    const defaults = Object.hasOwn(record, "defaults") ? record.defaults : {};
-    if (defaults === undefined) {
-        throw new TypeError("execution source defaults must be omitted or be an object");
-    }
-    const source = {
+    return Object.freeze({
         schemaVersion: EXECUTION_SOURCE_SCHEMA_VERSION,
         kind,
         content,
-        defaults: cloneUnresolvedExecutionDefaults(defaults),
-        identity: createExecutionSourceIdentity(record.identity),
-    };
-    if (Object.hasOwn(record, "extensions")) {
-        source.extensions = cloneAdapterExtensions(record.extensions, "execution source extensions");
-    }
-    Object.defineProperty(source, renderedSourceBrand, { value: true, enumerable: false });
-    const frozen = Object.freeze(source);
-    renderedSourceInstances.add(frozen);
-    return frozen;
-}
-function isAdapterRenderedSource(value, kind) {
-    if (typeof value !== "object" || value === null)
-        return false;
-    if (!renderedSourceInstances.has(value))
-        return false;
-    if (Object.getPrototypeOf(value) !== Object.prototype || !Object.isFrozen(value))
-        return false;
-    if (!Object.hasOwn(value, renderedSourceBrand))
-        return false;
-    const required = new Set(["schemaVersion", "kind", "content", "defaults", "identity"]);
-    const optional = new Set(["extensions"]);
-    for (const key of Reflect.ownKeys(value)) {
-        if (key === renderedSourceBrand)
-            continue;
-        if (typeof key !== "string" || (!required.delete(key) && !optional.has(key)))
-            return false;
-        const descriptor = Object.getOwnPropertyDescriptor(value, key);
-        if (!descriptor || !("value" in descriptor) || !descriptor.enumerable)
-            return false;
-    }
-    if (required.size > 0)
-        return false;
-    const brand = Object.getOwnPropertyDescriptor(value, renderedSourceBrand);
-    const source = value;
-    if (brand?.value !== true ||
-        brand.enumerable !== false ||
-        brand.configurable !== false ||
-        brand.writable !== false ||
-        source.schemaVersion !== EXECUTION_SOURCE_SCHEMA_VERSION ||
-        source.kind !== kind ||
-        typeof source.content !== "string" ||
-        typeof source.defaults !== "object" ||
-        source.defaults === null ||
-        !Object.isFrozen(source.defaults) ||
-        typeof source.identity !== "object" ||
-        source.identity === null ||
-        Object.getPrototypeOf(source.identity) !== Object.prototype ||
-        !Object.isFrozen(source.identity)) {
-        return false;
-    }
-    if (Object.hasOwn(source, "extensions")) {
-        if (typeof source.extensions !== "object" ||
-            source.extensions === null ||
-            Object.getPrototypeOf(source.extensions) !== null ||
-            !Object.isFrozen(source.extensions)) {
-            return false;
-        }
-    }
-    try {
-        decodeExecutionSourceIdentity(source.identity);
-    }
-    catch {
-        return false;
-    }
-    return true;
-}
-export function isAdapterRenderedCommandSource(value) {
-    return isAdapterRenderedSource(value, "command");
-}
-export function isAdapterRenderedPersonaSource(value) {
-    return isAdapterRenderedSource(value, "persona");
+        defaults: cloneUnresolvedExecutionDefaults(input.defaults ?? {}),
+        identity: createExecutionSourceIdentity(input.identity),
+        ...(input.extensions
+            ? { extensions: cloneAdapterExtensions(input.extensions, "execution source extensions") }
+            : {}),
+    });
 }

package/dist/execution/target-ref.js

@@ -23,7 +23,7 @@
  * Explicit non-goals (binding, spec §4.1): no GitHub locator grammar, no
  * `akm/command` builtin special case, no resolution, no filesystem access, no
  * guessing. Callers layer builtin detection on top (see
- * `classifyWorkflowSourceUses` in src/workflows/source-ir/uses.ts).
+ * `classifyWorkflowStepUses` in src/workflows/source-semantics.ts).
  */
 import { bundleRefToString, parseBundleRef } from "../core/asset/asset-ref.js";
 import { UsageError } from "../core/errors.js";

package/dist/indexer/bundle-identity-guard.js

@@ -34,7 +34,7 @@ import { rethrowIfTestIsolationError } from "../core/errors.js";
 import { getDbPath } from "../core/paths.js";
 import { warn } from "../core/warn.js";
 import { closeDatabase, openReadonlyExistingDatabase } from "../storage/repositories/index-connection.js";
-import { isCanonicalIndexGeneration } from "../storage/repositories/index-entry-schema.js";
+import { hasCurrentEntriesTable } from "../storage/repositories/index-entry-schema.js";
 let guardSettled = false;
 /** TEST-ONLY: re-arm the once-per-process guard between cases. */
 export function resetBundleIdentityGuardForTests() {
@@ -49,7 +49,7 @@ function indexedBundlePaths(dbPath) {
         db = openReadonlyExistingDatabase(dbPath);
         if (!db)
             return undefined;
-        if (!isCanonicalIndexGeneration(db))
+        if (!hasCurrentEntriesTable(db))
             return undefined;
         return db
             .prepare("SELECT DISTINCT bundle_id AS bundleId, file_path AS filePath FROM entries " +

package/dist/indexer/db/graph-db.js

@@ -29,16 +29,93 @@ function uniqueSorted(values) {
 function normalizeEntity(value) {
     return value.trim().toLowerCase();
 }
+/** Child rows joined to their file row, the same join the loaders read through. */
+const STORED_ENTITIES = `graph_file_entities e
+  JOIN graph_files gf ON gf.stash_root = e.stash_root AND gf.file_path = e.file_path AND gf.body_hash = e.body_hash
+  WHERE gf.stash_root = ?`;
+const STORED_RELATIONS = `graph_file_relations r
+  JOIN graph_files gf ON gf.stash_root = r.stash_root AND gf.file_path = r.file_path AND gf.body_hash = r.body_hash
+  WHERE gf.stash_root = ?`;
+/** One comparable key for a file's extraction: its entities and relations, in order. */
+function extractionKey(entities, relations) {
+    return JSON.stringify([entities, relations.map((r) => [r.from, r.to, r.type ?? null, r.confidence ?? null])]);
+}
+const EMPTY_EXTRACTION_KEY = extractionKey([], []);
+/** The extraction key of every stored file under a root that has child rows. */
+function readStoredExtractionKeys(db, stashRoot) {
+    const entityRows = db
+        .prepare(`SELECT e.file_path AS file_path, e.entity AS entity FROM ${STORED_ENTITIES} ORDER BY e.file_path, e.entity_order`)
+        .all(stashRoot);
+    const relationRows = db
+        .prepare(`SELECT r.file_path AS file_path, r.from_entity AS from_entity, r.to_entity AS to_entity,
+              r.relation_type AS relation_type, r.confidence AS confidence
+         FROM ${STORED_RELATIONS} ORDER BY r.file_path, r.relation_order`)
+        .all(stashRoot);
+    const byPath = new Map();
+    const bucket = (filePath) => {
+        let entry = byPath.get(filePath);
+        if (!entry) {
+            entry = { entities: [], relations: [] };
+            byPath.set(filePath, entry);
+        }
+        return entry;
+    };
+    for (const row of entityRows)
+        bucket(row.file_path).entities.push(row.entity);
+    for (const row of relationRows) {
+        bucket(row.file_path).relations.push({
+            from: row.from_entity,
+            to: row.to_entity,
+            ...(row.relation_type !== null ? { type: row.relation_type } : {}),
+            ...(row.confidence !== null ? { confidence: row.confidence } : {}),
+        });
+    }
+    return new Map([...byPath].map(([filePath, stored]) => [filePath, extractionKey(stored.entities, stored.relations)]));
+}
+function roundMetric(value) {
+    return Number(value.toFixed(4));
+}
+/**
+ * The graph_meta counts, derived from the stored rows of one root. Each field
+ * has one meaning (see {@link GraphQualityTelemetry}): files are graph_files
+ * rows, entities are distinct case-folded names, relations are distinct
+ * case-folded (from, to, type) triples.
+ */
+function readStoredGraphQuality(db, stashRoot) {
+    const count = (sql) => db.prepare(sql).get(stashRoot).n;
+    const storedFiles = count("SELECT COUNT(*) AS n FROM graph_files WHERE stash_root = ?");
+    const filesWithEntities = count(`SELECT COUNT(DISTINCT gf.file_path) AS n FROM ${STORED_ENTITIES}`);
+    const entityCount = count(`SELECT COUNT(DISTINCT e.entity_norm) AS n FROM ${STORED_ENTITIES}`);
+    const relationCount = count(`SELECT COUNT(*) AS n FROM (
+       SELECT DISTINCT r.from_entity_norm, r.to_entity_norm, lower(coalesce(r.relation_type, '')) FROM ${STORED_RELATIONS}
+     )`);
+    const maxEdges = entityCount > 1 ? (entityCount * (entityCount - 1)) / 2 : 0;
+    return {
+        consideredFiles: storedFiles,
+        extractedFiles: filesWithEntities,
+        entityCount,
+        relationCount,
+        extractionCoverage: storedFiles > 0 ? roundMetric(filesWithEntities / storedFiles) : 0,
+        density: maxEdges > 0 ? roundMetric(relationCount / maxEdges) : 0,
+    };
+}
 /**
  * Persist (or update) a graph snapshot for a stash root.
  *
  * #624-P1: keyed on (stash_root, file_path, body_hash) — NOT entries.id. Graph
  * rows are self-keyed by path, so they survive an entries delete + reinsert
- * (a reindex) when body_hash is unchanged. Unchanged files (matching body_hash)
- * only have their file-meta refreshed; files whose body_hash changed have their
- * old row + child rows deleted and the new content inserted; files in DB but
- * absent from the new snapshot are deleted. There is no entry_id resolution and
- * no orphan-skip — a graph file no longer needs a matching entries row.
+ * (a reindex) when body_hash is unchanged. A file whose body_hash is unchanged
+ * keeps its row; its entity and relation rows are rewritten only when they
+ * differ from the snapshot's (a re-extraction of the same body, e.g. after a
+ * model or prompt change or a failed first attempt, must land). Files whose
+ * body_hash changed have their old row + child rows deleted and the new content
+ * inserted; files in DB but absent from the new snapshot are deleted. There is
+ * no entry_id resolution and no orphan-skip — a graph file no longer needs a
+ * matching entries row.
+ *
+ * graph_meta records the snapshot's schema version, time and run telemetry;
+ * its counts are derived from the rows as stored after the write, never from
+ * the caller's in-memory graph.
  */
 export function replaceStoredGraph(db, graph) {
     const upsertMeta = db.prepare(`INSERT INTO graph_meta (
@@ -94,16 +171,15 @@ export function replaceStoredGraph(db, graph) {
     const insertRelation = db.prepare(`INSERT INTO graph_file_relations (
        stash_root, file_path, body_hash, relation_order, from_entity_norm, from_entity, to_entity_norm, to_entity, relation_type, confidence
      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
-    const quality = graph.quality;
     const telemetry = graph.telemetry;
     db.transaction(() => {
-        upsertMeta.run(graph.stashRoot, graph.schemaVersion, graph.generatedAt, quality?.consideredFiles ?? graph.files.length, quality?.extractedFiles ?? graph.files.length, quality?.entityCount ?? graph.entities?.length ?? 0, quality?.relationCount ?? graph.relations?.length ?? 0, quality?.extractionCoverage ?? 0, quality?.density ?? 0, telemetry?.extractorId ?? null, telemetry?.extractionRunId ?? null, telemetry?.model ?? null, telemetry?.promptVersion ?? null, telemetry?.batchSize ?? null, telemetry?.cacheHits ?? 0, telemetry?.cacheMisses ?? 0, telemetry?.truncationCount ?? 0, telemetry?.failureCount ?? 0);
         // Build a snapshot of existing rows for incremental compare. The unique
         // index idx_graph_files_path guarantees at most one row per file_path.
         const existingRows = selectExisting.all(graph.stashRoot);
         const existingByPath = new Map();
         for (const row of existingRows)
             existingByPath.set(row.file_path, row);
+        const storedKeys = readStoredExtractionKeys(db, graph.stashRoot);
         const presentPaths = new Set();
         for (const [fileOrder, node] of graph.files.entries()) {
             // body_hash is part of the PK; default to a sentinel for inputs (test
@@ -112,22 +188,32 @@ export function replaceStoredGraph(db, graph) {
             // correct behaviour for "unknown" bodies. Distinct files in one stash
             // are still keyed apart by file_path, so the empty sentinel is safe.
             const bodyHash = node.bodyHash && node.bodyHash.length > 0 ? node.bodyHash : "";
+            const status = node.status ?? (node.entities.length > 0 ? "extracted" : "empty");
+            const reason = node.reason ?? (node.entities.length > 0 ? "none" : "no_graph_content");
+            const runId = node.extractionRunId ?? telemetry?.extractionRunId ?? null;
             presentPaths.add(node.path);
             const existing = existingByPath.get(node.path);
             if (existing && existing.body_hash === bodyHash) {
-                // Body unchanged — only fix up file_order/confidence in case they drifted.
-                updateFileMeta.run(fileOrder, node.type, node.confidence ?? null, node.status ?? (node.entities.length > 0 ? "extracted" : "empty"), node.reason ?? (node.entities.length > 0 ? "none" : "no_graph_content"), node.extractionRunId ?? telemetry?.extractionRunId ?? null, graph.stashRoot, node.path, bodyHash);
-                continue;
+                // Body unchanged — refresh the file meta, and rewrite the child rows
+                // only when this snapshot's extraction differs from the stored one.
+                updateFileMeta.run(fileOrder, node.type, node.confidence ?? null, status, reason, runId, graph.stashRoot, node.path, bodyHash);
+                const storedKey = storedKeys.get(node.path) ?? EMPTY_EXTRACTION_KEY;
+                if (storedKey === extractionKey(node.entities, node.relations))
+                    continue;
+                deleteEntities.run(graph.stashRoot, node.path, bodyHash);
+                deleteRelations.run(graph.stashRoot, node.path, bodyHash);
             }
-            if (existing) {
-                // Stale row (different body_hash for this path). Delete the old row by
-                // its OLD body_hash; child rows cascade, but explicit DELETE keeps the
-                // order deterministic and is safe regardless of the FK pragma.
-                deleteEntities.run(graph.stashRoot, existing.file_path, existing.body_hash);
-                deleteRelations.run(graph.stashRoot, existing.file_path, existing.body_hash);
-                deleteFile.run(graph.stashRoot, existing.file_path, existing.body_hash);
+            else {
+                if (existing) {
+                    // Stale row (different body_hash for this path). Delete the old row by
+                    // its OLD body_hash; child rows cascade, but explicit DELETE keeps the
+                    // order deterministic and is safe regardless of the FK pragma.
+                    deleteEntities.run(graph.stashRoot, existing.file_path, existing.body_hash);
+                    deleteRelations.run(graph.stashRoot, existing.file_path, existing.body_hash);
+                    deleteFile.run(graph.stashRoot, existing.file_path, existing.body_hash);
+                }
+                insertFile.run(graph.stashRoot, node.path, fileOrder, node.type, bodyHash, node.confidence ?? null, status, reason, runId);
             }
-            insertFile.run(graph.stashRoot, node.path, fileOrder, node.type, bodyHash, node.confidence ?? null, node.status ?? (node.entities.length > 0 ? "extracted" : "empty"), node.reason ?? (node.entities.length > 0 ? "none" : "no_graph_content"), node.extractionRunId ?? telemetry?.extractionRunId ?? null);
             for (const [entityOrder, entity] of node.entities.entries()) {
                 insertEntity.run(graph.stashRoot, node.path, bodyHash, entityOrder, normalizeEntity(entity), entity);
             }
@@ -144,6 +230,8 @@ export function replaceStoredGraph(db, graph) {
                 deleteFile.run(graph.stashRoot, row.file_path, row.body_hash);
             }
         }
+        const quality = readStoredGraphQuality(db, graph.stashRoot);
+        upsertMeta.run(graph.stashRoot, graph.schemaVersion, graph.generatedAt, quality.consideredFiles, quality.extractedFiles, quality.entityCount, quality.relationCount, quality.extractionCoverage, quality.density, telemetry?.extractorId ?? null, telemetry?.extractionRunId ?? null, telemetry?.model ?? null, telemetry?.promptVersion ?? null, telemetry?.batchSize ?? null, telemetry?.cacheHits ?? 0, telemetry?.cacheMisses ?? 0, telemetry?.truncationCount ?? 0, telemetry?.failureCount ?? 0);
     })();
 }
 export function deleteStoredGraph(db, stashPath) {
@@ -191,34 +279,6 @@ export function enqueueGraphExtraction(db, stashRoot, filePath, bodyHash, priori
         rethrowIfTestIsolationError(err);
     }
 }
-/**
- * #624-P3 — drain up to `limit` queued files for a stash, highest-priority
- * first (then oldest queued_at). The returned rows are DELETED from the queue
- * in the SAME transaction (SELECT-then-DELETE-by-PK), so a drain is exactly
- * once. Tolerant of a missing table / db error (returns []), but never masks
- * the bun-test isolation guard.
- */
-export function drainExtractionQueue(db, stashRoot, limit) {
-    try {
-        return db.transaction(() => {
-            const rows = db
-                .prepare(`SELECT file_path, body_hash, priority
-             FROM graph_extraction_queue
-             WHERE stash_root = ?
-             ORDER BY priority DESC, queued_at ASC
-             LIMIT ?`)
-                .all(stashRoot, limit);
-            const del = db.prepare("DELETE FROM graph_extraction_queue WHERE stash_root = ? AND file_path = ?");
-            for (const row of rows)
-                del.run(stashRoot, row.file_path);
-            return rows.map((row) => ({ filePath: row.file_path, bodyHash: row.body_hash, priority: row.priority }));
-        })();
-    }
-    catch (err) {
-        rethrowIfTestIsolationError(err);
-        return [];
-    }
-}
 /** Read queued graph work without claiming or deleting it. */
 export function peekExtractionQueue(db, stashRoot, limit) {
     try {