akm-cli 0.9.1 → 0.9.2-alpha.2

package/dist/commands/improve/eligibility.js

@@ -10,12 +10,13 @@ import { NotFoundError, rethrowIfTestIsolationError, UsageError } from "../../co
 import { readEvents } from "../../core/events.js";
 import { isPathAbsent } from "../../core/path-access.js";
 import { getDbPath } from "../../core/paths.js";
-import { deriveInstallations } from "../../indexer/installations.js";
-import { getWritableStashDirs, resolveSourceEntries } from "../../indexer/search/search-source.js";
+import { deriveInstallations, deriveWritableBundleIds } from "../../indexer/installations.js";
+import { resolveSourceEntries } from "../../indexer/search/search-source.js";
 import { resolveAssetPath } from "../../indexer/walk/path-resolver.js";
 import { closeDatabase, openExistingDatabase, openReadonlyExistingDatabase, } from "../../storage/repositories/index-connection.js";
 import { getAllEntries } from "../../storage/repositories/index-entries-repository.js";
 import { getUtilityScoresByIds } from "../../storage/repositories/index-utility-repository.js";
+import { SqliteReadSnapshotUnavailableError } from "../../storage/sqlite-read-snapshot.js";
 import { isDistillRefusedInputType } from "./distill.js";
 import { isStrategyFilteredForAllPasses } from "./improve-strategies.js";
 import { parseMemoryRef } from "./memory/derived-ref.js";
@@ -36,9 +37,37 @@ import { improveStateReadRefs } from "./source-identity.js";
  */
 function openEligibilityDb(readOnly) {
     if (readOnly)
-        return openReadonlyExistingDatabase();
+        return openReadonlyExistingDatabase(undefined, { isolatedSnapshot: true });
     return isPathAbsent(getDbPath()) ? undefined : openExistingDatabase();
 }
+function describeIndexSnapshot(readOnly, status) {
+    if (status === "ready") {
+        return {
+            status,
+            reason: readOnly ? "loaded a non-mutating point-in-time copy of the existing index" : "loaded the prepared index",
+        };
+    }
+    if (status === "missing") {
+        return {
+            status,
+            reason: readOnly
+                ? "index.db is missing; dry-run uses an empty snapshot and does not create it"
+                : "index.db is missing after index preparation; the selector uses an empty snapshot",
+        };
+    }
+    return {
+        status,
+        reason: readOnly
+            ? "index.db has no entries table; dry-run uses an empty snapshot and does not migrate it"
+            : "index.db has no entries table; the selector uses an empty snapshot",
+    };
+}
+function describeUnavailableSnapshot(error) {
+    return {
+        status: "incompatible",
+        reason: `index.db cannot provide a stable non-mutating snapshot (${error.message}); dry-run uses an empty snapshot`,
+    };
+}
 export function resolveImproveScope(scope) {
     const trimmed = scope?.trim();
     if (!trimmed)
@@ -95,17 +124,33 @@ export async function collectEligibleRefsReadOnly(scope, stashDir, improveProfil
 }
 async function collectEligibleRefsFromIndex(scope, stashDir, improveProfile, readOnly, configOverride) {
     const config = configOverride ?? loadConfig();
+    let sources;
+    try {
+        sources = resolveSourceEntries(stashDir, config);
+    }
+    catch {
+        return { plannedRefs: [], memorySummary: { eligible: 0, derived: 0 }, strategyFilteredRefs: [] };
+    }
+    if (sources.length === 0) {
+        return { plannedRefs: [], memorySummary: { eligible: 0, derived: 0 }, strategyFilteredRefs: [] };
+    }
+    const installations = deriveInstallations(sources);
+    const writableBundleIds = deriveWritableBundleIds(sources);
     if (scope.mode === "ref" && scope.value) {
-        const writableDirs = new Set(getWritableStashDirs(stashDir, config).map((dir) => path.resolve(dir)));
         let db;
         try {
             db = openEligibilityDb(readOnly);
             if (!db) {
-                return { plannedRefs: [], memorySummary: { eligible: 0, derived: 0 }, strategyFilteredRefs: [] };
+                return {
+                    plannedRefs: [],
+                    memorySummary: { eligible: 0, derived: 0 },
+                    strategyFilteredRefs: [],
+                    indexSnapshot: describeIndexSnapshot(readOnly, "missing"),
+                };
             }
+            const indexSnapshot = describeIndexSnapshot(readOnly, "ready");
             const entries = getAllEntries(db);
-            const entriesByItemRef = new Map(entries.flatMap((entry) => entry.bundleId && entry.conceptId ? [[`${entry.bundleId}//${entry.conceptId}`, entry]] : []));
-            const installations = deriveInstallations(resolveSourceEntries(stashDir, config));
+            const entriesByItemRef = new Map(entries.map((entry) => [entry.itemRef, entry]));
             const resolved = resolveRef(scope.value, {
                 defaultBundle: config.defaultBundle,
                 bundles: installations.map((installation) => ({
@@ -116,27 +161,46 @@ async function collectEligibleRefsFromIndex(scope, stashDir, improveProfile, rea
             const indexed = entriesByItemRef.get(`${resolved.bundle}//${resolved.conceptId}`);
             if (!indexed?.bundleId || !indexed.conceptId || !fs.existsSync(indexed.filePath)) {
                 if (await findAssetFilePath(scope.value, stashDir)) {
-                    return { plannedRefs: [], memorySummary: { eligible: 0, derived: 0 }, strategyFilteredRefs: [] };
+                    return {
+                        plannedRefs: [],
+                        memorySummary: { eligible: 0, derived: 0 },
+                        strategyFilteredRefs: [],
+                        indexSnapshot,
+                    };
                 }
                 throw new NotFoundError(`Asset not found in the selected writable source: ${scope.value}`, "ASSET_NOT_FOUND");
             }
-            if (!isEntryInScope(indexed.stashDir, indexed.filePath, stashDir) ||
-                !isEntryInWritableSource(indexed.stashDir, indexed.filePath, writableDirs)) {
-                return { plannedRefs: [], memorySummary: { eligible: 0, derived: 0 }, strategyFilteredRefs: [] };
+            if (!writableBundleIds.has(indexed.bundleId)) {
+                return { plannedRefs: [], memorySummary: { eligible: 0, derived: 0 }, strategyFilteredRefs: [], indexSnapshot };
             }
-            const itemRef = `${indexed.bundleId}//${indexed.conceptId}`;
             return {
-                plannedRefs: [{ ref: indexed.conceptId, itemRef, reason: "scope-ref", filePath: indexed.filePath }],
+                plannedRefs: [
+                    { ref: indexed.conceptId, itemRef: indexed.itemRef, reason: "scope-ref", filePath: indexed.filePath },
+                ],
                 memorySummary: {
                     eligible: indexed.entry.type === "memory" ? 1 : 0,
                     derived: indexed.entry.type === "memory" && indexed.entry.name.endsWith(".derived") ? 1 : 0,
                 },
                 strategyFilteredRefs: [],
+                indexSnapshot,
             };
         }
         catch (error) {
+            if (readOnly && error instanceof SqliteReadSnapshotUnavailableError) {
+                return {
+                    plannedRefs: [],
+                    memorySummary: { eligible: 0, derived: 0 },
+                    strategyFilteredRefs: [],
+                    indexSnapshot: describeUnavailableSnapshot(error),
+                };
+            }
             if (error instanceof Error && /no such table:\s*entries/i.test(error.message)) {
-                return { plannedRefs: [], memorySummary: { eligible: 0, derived: 0 }, strategyFilteredRefs: [] };
+                return {
+                    plannedRefs: [],
+                    memorySummary: { eligible: 0, derived: 0 },
+                    strategyFilteredRefs: [],
+                    indexSnapshot: describeIndexSnapshot(readOnly, "incompatible"),
+                };
             }
             throw error;
         }
@@ -145,39 +209,19 @@ async function collectEligibleRefsFromIndex(scope, stashDir, improveProfile, rea
                 closeDatabase(db);
         }
     }
-    let sources;
-    try {
-        sources = resolveSourceEntries(stashDir, config);
-    }
-    catch {
-        return { plannedRefs: [], memorySummary: { eligible: 0, derived: 0 }, strategyFilteredRefs: [] };
-    }
-    if (sources.length === 0) {
-        return { plannedRefs: [], memorySummary: { eligible: 0, derived: 0 }, strategyFilteredRefs: [] };
-    }
-    // Only operate on writable sources — never mutate read-only registry caches
-    // or remote stashes that the user did not mark writable.
-    let writableDirs;
-    try {
-        writableDirs = getWritableStashDirs(stashDir, config);
-    }
-    catch {
-        writableDirs = sources.slice(0, 1).map((s) => s.path); // fallback: primary only
-    }
-    const writableDirSet = new Set(writableDirs.map((d) => path.resolve(d)));
     let db;
     try {
         db = openEligibilityDb(readOnly);
         if (!db) {
-            return { plannedRefs: [], memorySummary: { eligible: 0, derived: 0 }, strategyFilteredRefs: [] };
+            return {
+                plannedRefs: [],
+                memorySummary: { eligible: 0, derived: 0 },
+                strategyFilteredRefs: [],
+                indexSnapshot: describeIndexSnapshot(readOnly, "missing"),
+            };
         }
-        const entries = getAllEntries(db, scope.mode === "type" ? scope.value : undefined).filter((indexed) => {
-            // First apply the existing stashDir-scope filter (no-op when stashDir is unset).
-            if (!isEntryInScope(indexed.stashDir, indexed.filePath, stashDir))
-                return false;
-            // Then restrict to writable sources only.
-            return isEntryInWritableSource(indexed.stashDir, indexed.filePath, writableDirSet);
-        });
+        const indexSnapshot = describeIndexSnapshot(readOnly, "ready");
+        const entries = getAllEntries(db, scope.mode === "type" ? scope.value : undefined).filter((indexed) => writableBundleIds.has(indexed.bundleId));
         const planned = new Map();
         const strategyFiltered = new Map();
         let memoryEligible = 0;
@@ -198,7 +242,7 @@ async function collectEligibleRefsFromIndex(scope, stashDir, improveProfile, rea
             }
             // Derive the durable item_ref from indexed provenance without another query.
             // A provenance-free row uses the short conceptId ref for improve state.
-            const itemRef = indexed.bundleId && indexed.conceptId ? `${indexed.bundleId}//${indexed.conceptId}` : undefined;
+            const itemRef = indexed.itemRef;
             const isDerived = indexed.entry.name.endsWith(".derived");
             // `.derived` memories are LLM-inferred and intentionally skip reflect
             // (see the synthetic `derived-memory-reflect-skipped` branch in the
@@ -242,13 +286,27 @@ async function collectEligibleRefsFromIndex(scope, stashDir, improveProfile, rea
             plannedRefs: [...planned.values()],
             memorySummary: { eligible: memoryEligible, derived: memoryDerived },
             strategyFilteredRefs: [...strategyFiltered.values()],
+            indexSnapshot,
         };
     }
     catch (error) {
         // Empty-stash setup paths can open index.db before its schema exists.
         rethrowIfTestIsolationError(error);
+        if (readOnly && error instanceof SqliteReadSnapshotUnavailableError) {
+            return {
+                plannedRefs: [],
+                memorySummary: { eligible: 0, derived: 0 },
+                strategyFilteredRefs: [],
+                indexSnapshot: describeUnavailableSnapshot(error),
+            };
+        }
         if (error instanceof Error && /no such table:\s*entries/i.test(error.message)) {
-            return { plannedRefs: [], memorySummary: { eligible: 0, derived: 0 }, strategyFilteredRefs: [] };
+            return {
+                plannedRefs: [],
+                memorySummary: { eligible: 0, derived: 0 },
+                strategyFilteredRefs: [],
+                indexSnapshot: describeIndexSnapshot(readOnly, "incompatible"),
+            };
         }
         throw error;
     }
@@ -257,33 +315,6 @@ async function collectEligibleRefsFromIndex(scope, stashDir, improveProfile, rea
             closeDatabase(db);
     }
 }
-export function isEntryInScope(entryStashDir, filePath, stashDir) {
-    if (!stashDir)
-        return true;
-    const resolvedEntryStashDir = path.resolve(entryStashDir);
-    const resolvedFilePath = path.resolve(filePath);
-    const resolvedScopeStashDir = path.resolve(stashDir);
-    return (resolvedEntryStashDir === resolvedScopeStashDir ||
-        resolvedEntryStashDir.startsWith(`${resolvedScopeStashDir}${path.sep}`) ||
-        resolvedFilePath.startsWith(`${resolvedScopeStashDir}${path.sep}`));
-}
-/**
- * Return true when the indexed entry belongs to one of the writable source
- * directories. Entries from read-only registry caches or remote stashes that
- * the user has not marked writable must never enter the improve/distill loop.
- */
-export function isEntryInWritableSource(entryStashDir, filePath, writableDirSet) {
-    const resolvedEntryStashDir = path.resolve(entryStashDir);
-    const resolvedFilePath = path.resolve(filePath);
-    for (const writableDir of writableDirSet) {
-        if (resolvedEntryStashDir === writableDir ||
-            resolvedEntryStashDir.startsWith(`${writableDir}${path.sep}`) ||
-            resolvedFilePath.startsWith(`${writableDir}${path.sep}`)) {
-            return true;
-        }
-    }
-    return false;
-}
 export function memoryCleanupParentRef(scope, stashDir) {
     if (scope.mode !== "ref" || !scope.value)
         return undefined;
@@ -381,13 +412,13 @@ export function shouldDistillMemoryRef(ref, stashDir) {
  * metadata events are ignored so a stray `akm feedback <ref>` invocation
  * without a flag doesn't trigger downstream re-processing.
  */
-export function buildLatestFeedbackTsMap(refs, sinceIso, itemRefByRef) {
+export function buildLatestFeedbackTsMap(refs, sinceIso, itemRefByRef, eventsCtx) {
     const out = new Map();
     if (refs.length === 0)
         return out;
     // Correlate item_ref-keyed events and conceptId-keyed direct invocations.
     const refByDurableKey = new Map(refs.flatMap((ref) => improveStateReadRefs(ref, itemRefByRef?.get(ref)).map((key) => [key, ref])));
-    const { events } = readEvents({ type: "feedback", since: sinceIso });
+    const { events } = readEvents({ type: "feedback", since: sinceIso }, eventsCtx);
     for (const e of events) {
         const ref = e.ref ? refByDurableKey.get(e.ref) : undefined;
         if (!ref)
@@ -411,14 +442,14 @@ export function buildLatestFeedbackTsMap(refs, sinceIso, itemRefByRef) {
  * lesson/knowledge ref, not the source memory — joining back through the
  * payload would be fragile.
  */
-export function buildLatestProposalTsMap(refs, source, itemRefByRef) {
+export function buildLatestProposalTsMap(refs, source, itemRefByRef, eventsCtx) {
     const out = new Map();
     if (refs.length === 0)
         return out;
     // Correlate item_ref-keyed events and conceptId-keyed direct invocations.
     const refByDurableKey = new Map(refs.flatMap((ref) => improveStateReadRefs(ref, itemRefByRef?.get(ref)).map((key) => [key, ref])));
     const eventType = source === "reflect" ? "reflect_invoked" : "distill_invoked";
-    const { events } = readEvents({ type: eventType });
+    const { events } = readEvents({ type: eventType }, eventsCtx);
     for (const e of events) {
         const ref = e.ref ? refByDurableKey.get(e.ref) : undefined;
         if (!ref)
@@ -489,14 +520,16 @@ export function shouldAnalyzeMemoryCleanup(scope, eligibleMemories, primaryStash
         return false;
     return parseRefInput(scope.value).type === "memory";
 }
-export function buildUtilityMap(refs) {
+export function buildUtilityMap(refs, readOnly = false) {
     const map = new Map();
     if (refs.length === 0)
         return map;
     const refSet = new Set(refs.map((r) => r.ref));
     let db;
     try {
-        db = openExistingDatabase();
+        db = readOnly ? openReadonlyExistingDatabase(undefined, { isolatedSnapshot: true }) : openExistingDatabase();
+        if (!db)
+            return map;
         const allDbEntries = getAllEntries(db);
         const idToRef = new Map();
         for (const indexed of allDbEntries) {
@@ -526,11 +559,11 @@ export function buildUtilityMap(refs) {
     }
     return map;
 }
-export async function findAssetFilePath(ref, stashDir, writableDirSet) {
+export async function findAssetFilePath(ref, stashDir, writableBundleIds) {
     return resolveAssetPath(ref, {
         stashDir,
         mode: "disk-only",
-        writableDirSet,
+        writableBundleIds,
         directoryIndexNames: ["SKILL.md"],
         preserveDirectNameFallback: true,
         honorOrigin: true,

package/dist/commands/improve/execution.js

@@ -0,0 +1,57 @@
+// 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 { deepMergeConfig } from "../../core/config/deep-merge.js";
+import { ConfigError } from "../../core/errors.js";
+import { lowerResolvedExecutionRequest } from "../../integrations/agent/execution-lowering.js";
+import { prepareInlineExecution } from "../../integrations/agent/inline-execution.js";
+function own(value, key) {
+    return value !== undefined && Object.hasOwn(value, key);
+}
+function cascadeDefaults(layer) {
+    if (!layer)
+        return {};
+    return {
+        ...(own(layer, "engine") ? { engine: layer.engine } : {}),
+        ...(own(layer, "model") ? { model: layer.model } : {}),
+        ...(own(layer, "llm") ? { inference: layer.llm } : {}),
+        ...(own(layer, "timeoutMs") ? { timeout: layer.timeoutMs ?? null } : {}),
+    };
+}
+function mergeDefaults(farther, nearer) {
+    return deepMergeConfig(farther, nearer);
+}
+/**
+ * Resolve improve-owned model work through the canonical execution cascade.
+ * The legacy improve precedence is preserved exactly:
+ * defaults.llmEngine -> strategy -> process -> current invocation.
+ */
+export function resolveImproveExecution(options) {
+    const defaultEngine = options.config.defaults?.llmEngine;
+    const profileDefaults = cascadeDefaults(options.profile);
+    const processDefaults = cascadeDefaults(options.process);
+    const currentDefaults = cascadeDefaults(options.current);
+    const selectedEngine = currentDefaults.engine ?? processDefaults.engine ?? profileDefaults.engine ?? defaultEngine;
+    if (selectedEngine === undefined || selectedEngine === null)
+        return null;
+    const invocationDefaults = mergeDefaults(defaultEngine ? { engine: defaultEngine } : {}, profileDefaults);
+    const current = mergeDefaults(processDefaults, currentDefaults);
+    const prepared = prepareInlineExecution({
+        content: `improve ${options.processName} execution selection`,
+        config: options.config,
+        invocationKind: "direct",
+        invocationDefaults,
+        current,
+    });
+    const lowered = lowerResolvedExecutionRequest(prepared.request, prepared.config);
+    return Object.freeze({ runner: lowered.runner, notices: lowered.notices });
+}
+export function resolveImproveLlmExecution(options) {
+    const resolved = resolveImproveExecution(options);
+    if (!resolved)
+        return null;
+    if (resolved.runner.kind !== "llm") {
+        throw new ConfigError(`Engine ${JSON.stringify(resolved.runner.engine ?? "unknown")} is not an LLM engine.`, "INVALID_CONFIG_FILE");
+    }
+    return { runner: resolved.runner, notices: resolved.notices };
+}

package/dist/commands/improve/extract-cli.js

@@ -7,11 +7,11 @@
  * see src/commands/proposal/proposal-cli.ts for its registration).
  *
  * Examples:
- *   akm proposal extract --type claude-code --session-id <id>
- *   akm proposal extract --type claude-code --since 24h
+ *   akm proposal extract --type claude --session-id <id>
+ *   akm proposal extract --type claude --since 24h
  *   akm proposal extract --type opencode --since 7d --dry-run
  *   akm proposal extract --auto                 # iterate all available harnesses
- *   akm proposal extract --type claude-code --location /custom/path --session-id <id>
+ *   akm proposal extract --type claude --location /custom/path --session-id <id>
  *
  * Output is the AkmExtractResult JSON envelope (or an aggregated one when
  * `--auto` runs multiple harnesses).
@@ -25,12 +25,12 @@ import { akmExtract, resolveStandaloneExtractPlan } from "./extract.js";
 export const extractCommand = defineJsonCommand({
     meta: {
         name: "extract",
-        description: "Extract durable insights from native session files (claude-code, opencode) and queue them as proposals.",
+        description: "Extract durable insights from native session files (claude, opencode) and queue them as proposals.",
     },
     args: {
         type: {
             type: "string",
-            description: "Harness name (claude-code, opencode). Required unless --auto.",
+            description: "Harness name (claude, opencode). Required unless --auto.",
         },
         "session-id": {
             type: "string",

package/dist/commands/improve/extract-prompt.js

@@ -15,6 +15,7 @@
  * the model emits get dropped before we parse.
  */
 import promptTemplate from "../../assets/prompts/extract-session.md" with { type: "text" };
+import { escapeJsonStringControls, stripCodeFences, stripThinkBlocks } from "../../core/parse.js";
 const EXTRACT_CANDIDATE_NAME_PATTERN = "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:/[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)?$";
 const EXTRACT_CANDIDATE_NAME_RE = new RegExp(EXTRACT_CANDIDATE_NAME_PATTERN);
 /**
@@ -163,6 +164,57 @@ export function buildExtractPrompt(input) {
         .replace("{{STANDARDS}}", standards)
         .replace("{{TRANSCRIPT}}", `${TRANSCRIPT_FENCE_BEGIN}\n${formatTranscript(input.events)}\n${TRANSCRIPT_FENCE_END}`);
 }
+function failedExtractPayload(code, message) {
+    return { candidates: [], rationale_if_empty: message, parseFailure: { code, message } };
+}
+function parseFirstJsonObject(stdout) {
+    const text = escapeJsonStringControls(stripCodeFences(stripThinkBlocks(stdout)));
+    try {
+        return { objectFound: text.startsWith("{"), value: JSON.parse(text) };
+    }
+    catch {
+        // Continue with the first object embedded in prose. Once an opening brace
+        // is found, never descend into a nested object if that outer object is
+        // malformed or truncated: doing so can turn a broken candidate into a
+        // superficially valid top-level payload.
+    }
+    const start = text.indexOf("{");
+    if (start < 0)
+        return { objectFound: false };
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    for (let index = start; index < text.length; index++) {
+        const char = text[index];
+        if (inString) {
+            if (escaped)
+                escaped = false;
+            else if (char === "\\")
+                escaped = true;
+            else if (char === '"')
+                inString = false;
+            continue;
+        }
+        if (char === '"') {
+            inString = true;
+            continue;
+        }
+        if (char === "{")
+            depth += 1;
+        else if (char === "}") {
+            depth -= 1;
+            if (depth !== 0)
+                continue;
+            try {
+                return { objectFound: true, value: JSON.parse(text.slice(start, index + 1)) };
+            }
+            catch {
+                return { objectFound: true };
+            }
+        }
+    }
+    return { objectFound: true };
+}
 /**
  * Parse the LLM's JSON response into a structured {@link ExtractPayload}.
  * Defensive — drops candidates that violate the shape rather than failing
@@ -170,32 +222,22 @@ export function buildExtractPrompt(input) {
  */
 export function parseExtractPayload(stdout) {
     if (!stdout || stdout.trim().length === 0) {
-        return { candidates: [], rationale_if_empty: "LLM returned empty response" };
+        return failedExtractPayload("empty_response", "LLM returned an empty response");
     }
-    let parsed;
-    try {
-        parsed = JSON.parse(stdout);
+    const parsed = parseFirstJsonObject(stdout);
+    if (parsed.value === undefined) {
+        return parsed.objectFound
+            ? failedExtractPayload("invalid_json_object", "JSON object was found but could not be parsed")
+            : failedExtractPayload("no_json_object", "LLM response: no JSON object found");
     }
-    catch {
-        // Tolerate prose preamble/postamble by extracting the first balanced
-        // top-level JSON object.
-        const start = stdout.indexOf("{");
-        const end = stdout.lastIndexOf("}");
-        if (start === -1 || end <= start) {
-            return { candidates: [], rationale_if_empty: `LLM response was not parseable JSON` };
-        }
-        try {
-            parsed = JSON.parse(stdout.slice(start, end + 1));
-        }
-        catch {
-            return { candidates: [], rationale_if_empty: `LLM response was not parseable JSON` };
-        }
+    if (!parsed.value || typeof parsed.value !== "object" || Array.isArray(parsed.value)) {
+        return failedExtractPayload("invalid_payload", "LLM response JSON was not an object");
     }
-    if (!parsed || typeof parsed !== "object") {
-        return { candidates: [], rationale_if_empty: "LLM response was not an object" };
+    const obj = parsed.value;
+    if (!Array.isArray(obj.candidates)) {
+        return failedExtractPayload("invalid_payload", "LLM response JSON did not contain a candidates array");
     }
-    const obj = parsed;
-    const rawCandidates = Array.isArray(obj.candidates) ? obj.candidates : [];
+    const rawCandidates = obj.candidates;
     const candidates = [];
     for (const raw of rawCandidates) {
         if (!raw || typeof raw !== "object")