akm-cli 0.10.261009-beta → 0.10.261010-beta

package/dist/indexer/index-writer-lock.js

@@ -138,7 +138,11 @@ export async function withAssetMutationLease(purpose, run) {
         return run();
     const context = inherited ?? new Set();
     const execute = async () => {
-        const lease = await acquireAssetMutationLease({ purpose });
+        const lease = await acquireAssetMutationLease({
+            purpose,
+            // #956: say who is in the way instead of waiting silently, as the sync path does.
+            onWait: ({ waitedMs }) => warn(`waiting for ${describeAssetMutationHolder(lockPath)} — ${Math.round(waitedMs / 1000)}s`),
+        });
         if (!lease)
             throw new Error(`asset mutation lease unavailable for ${purpose}`);
         context.add(lockPath);

package/dist/indexer/passes/memory-inference.js

@@ -64,6 +64,12 @@ const FM_INFERRED = "inferred";
 const FM_INFERENCE_PROCESSED = "inferenceProcessed";
 const FM_SOURCE = "source";
 const FM_CAPTURE_MODE = "captureMode";
+/**
+ * Cache namespace for this pass. Bump it when the cached response semantics
+ * change (v3: a cached row may be an explicit no-change decision); rows under an
+ * older namespace are never read again, which is a disposable cache miss.
+ */
+const MEMORY_INFERENCE_CACHE_VARIANT = "memory-inference-v3";
 function validateDerivedMemoryDraft(raw) {
     if (!raw || typeof raw !== "object")
         return undefined;
@@ -79,6 +85,10 @@ function validateDerivedMemoryDraft(raw) {
         ? { title, description, tags, searchHints, content }
         : undefined;
 }
+/** Cache validator: a recognised no-change decision, a complete draft, or `undefined` (unusable → recompute). */
+function validateMemoryInferDecision(raw) {
+    return memoryInfer.isMemoryInferNoChange(raw) ? memoryInfer.MEMORY_INFER_NO_CHANGE : validateDerivedMemoryDraft(raw);
+}
 function planPendingMemoryRecord(record, ctx) {
     if (ctx.signal?.aborted)
         return { kind: "aborted", record };
@@ -86,11 +96,11 @@ function planPendingMemoryRecord(record, ctx) {
         return { kind: "existing-child", record };
     if (ctx.db && !ctx.reEnrich) {
         const cached = bestEffort(() => {
-            const entry = getLlmCacheEntry(ctx.db, record.filePath, computeBodyHash(record.body), "memory-inference-v2");
-            return entry ? validateDerivedMemoryDraft(JSON.parse(entry.resultJson)) : undefined;
+            const entry = getLlmCacheEntry(ctx.db, record.filePath, computeBodyHash(record.body), MEMORY_INFERENCE_CACHE_VARIANT);
+            return entry ? validateMemoryInferDecision(JSON.parse(entry.resultJson)) : undefined;
         }, "memory inference cache read corrupt — fall through to recompute");
         if (cached)
-            return { kind: "cache-hit", record, derived: cached };
+            return { kind: "cache-hit", record, decision: cached };
     }
     return { kind: "model", record };
 }
@@ -132,11 +142,11 @@ async function inferPendingMemoryRecord(plan, ctx) {
         retryAttempts += 1;
     };
     const infer = () => compressMemoryToDerivedMemory(llmRunner, record.body, signal, featureConfig, (event) => warn(`[akm] LLM fallback for ${event.feature}: ${event.reason}`), inferTelemetry, onRetryAttempt, onNotices);
-    let derived = plan.kind === "cache-hit" ? plan.derived : undefined;
+    let derived = plan.kind === "cache-hit" ? plan.decision : undefined;
     try {
         if (plan.kind === "model") {
             derived = db
-                ? await withLlmCache(db, record.filePath, record.body, reEnrich ?? false, infer, validateDerivedMemoryDraft, undefined, "memory-inference-v2", {
+                ? await withLlmCache(db, record.filePath, record.body, reEnrich ?? false, infer, validateMemoryInferDecision, undefined, MEMORY_INFERENCE_CACHE_VARIANT, {
                     onCacheHit: () => {
                         fromCache = true;
                     },
@@ -153,6 +163,12 @@ async function inferPendingMemoryRecord(plan, ctx) {
     }
     if (!derived)
         return { skipped: true, fromCache, retryAttempts };
+    // An explicit decision, not a failure. The parent is left exactly as it is: stamping it
+    // `inferenceProcessed` would hide every later edit, and the cached decision already
+    // stops the retry for as long as the effective input is unchanged.
+    if (memoryInfer.isMemoryInferNoChange(derived)) {
+        return { skipped: false, splitParent: false, written: 0, noChange: true, fromCache, retryAttempts };
+    }
     const writeOutcome = await writeDerivedMemory(record, derived);
     if (writeOutcome.written > 0) {
         markParentProcessed(record);
@@ -209,6 +225,7 @@ async function runMemoryInferencePassBody(ctx, provenance) {
         retryAttempts: 0,
         splitParents: 0,
         writtenFacts: 0,
+        noChange: 0,
         skippedNoFacts: 0,
         skippedChildExists: 0,
         skippedAborted: 0,
@@ -273,7 +290,7 @@ async function runMemoryInferencePassBody(ctx, provenance) {
         assertRunnerCredentials(llmRunner);
     let processed = 0;
     const total = pending.length;
-    onProgress?.({ processed, total, writtenFacts: 0, skippedNoFacts: 0 });
+    onProgress?.({ processed, total, writtenFacts: 0, noChange: 0, skippedNoFacts: 0 });
     let configFailure;
     const perRecordResults = await concurrentMap(plans, (plan) => inferPendingMemoryRecord(plan, {
         config,
@@ -305,6 +322,7 @@ async function runMemoryInferencePassBody(ctx, provenance) {
                 processed,
                 total,
                 writtenFacts: result.writtenFacts,
+                noChange: result.noChange,
                 skippedNoFacts: result.skippedNoFacts,
                 currentRef: pending[i]?.ref,
             });
@@ -321,6 +339,9 @@ async function runMemoryInferencePassBody(ctx, provenance) {
             // Intentionally NOT marked processed — a transient LLM failure should
             // be retried on the next index run.
         }
+        else if ("noChange" in res && res.noChange) {
+            result.noChange += 1;
+        }
         else if (res.splitParent) {
             result.splitParents += 1;
             result.writtenFacts += res.written;
@@ -349,6 +370,7 @@ async function runMemoryInferencePassBody(ctx, provenance) {
             processed,
             total,
             writtenFacts: result.writtenFacts,
+            noChange: result.noChange,
             skippedNoFacts: result.skippedNoFacts,
             currentRef: pending[i]?.ref,
         });

package/dist/llm/memory-infer.js

@@ -34,35 +34,40 @@ const PROMPT_PLACEHOLDERS = new Set([
     "search phrase 2",
     "2-3 sentence compressed body preserving key facts verbatim",
 ]);
+export const MEMORY_INFER_NO_CHANGE = Object.freeze({ noChange: true });
+export function isMemoryInferNoChange(value) {
+    return typeof value === "object" && value !== null && value.noChange === true;
+}
 /**
  * Strict JSON Schema for the derived-memory payload. Sent as `response_format`
  * unless the engine sets `supportsJsonSchema: false`; the client drops it once
  * for a provider that rejects it.
  *
- * Extends the responseSchema lift (PR 1, asset-writers-investigation §5) to
- * the memory-inference path. Mirrors the validation gate below
- * (title/description/content + non-empty tags/searchHints) so a
- * schema-compliant response is guaranteed to pass the downstream check
- * — no more "incomplete derived memory payload from LLM; skipping memory"
- * for shape-only failures.
+ * Every property is required (a strict provider refuses otherwise), so the
+ * explicit no-change decision is `noChange: true` with the other fields empty.
+ * That also means the schema cannot demand non-empty fields: the parser below
+ * is the gate that requires a complete payload whenever `noChange` is false.
  */
 export const DERIVED_MEMORY_JSON_SCHEMA = {
     type: "object",
     properties: {
-        title: { type: "string", minLength: 1 },
-        description: { type: "string", minLength: 1 },
-        content: { type: "string", minLength: 1 },
-        tags: { type: "array", items: { type: "string" }, minItems: 1, maxItems: 8 },
-        searchHints: { type: "array", items: { type: "string" }, minItems: 1, maxItems: 6 },
+        noChange: { type: "boolean" },
+        title: { type: "string" },
+        description: { type: "string" },
+        content: { type: "string" },
+        tags: { type: "array", items: { type: "string" }, maxItems: 8 },
+        searchHints: { type: "array", items: { type: "string" }, maxItems: 6 },
     },
-    required: ["title", "description", "content", "tags", "searchHints"],
+    required: ["noChange", "title", "description", "content", "tags", "searchHints"],
     additionalProperties: false,
 };
 /**
  * Compress a single memory body into one derived memory via the configured LLM.
  *
- * Returns `undefined` on any failure (timeout, invalid JSON, empty response).
- * Errors are logged via `warn()` but never thrown — a failed split for one memory
+ * Returns the draft, or {@link MEMORY_INFER_NO_CHANGE} when the model explicitly
+ * decides the memory needs no derived memory. Returns `undefined` on any failure
+ * (timeout, invalid JSON, empty or incomplete response, HTML, abort, disabled
+ * pass), which is never the same thing as no-change. Errors are logged via `warn()` but never thrown — a failed split for one memory
  * must not abort the rest of the index pass.
  *
  * Routes through `callStructured({ feature: "memory_inference", ... })` so the
@@ -105,6 +110,10 @@ export async function compressMemoryToDerivedMemory(llmRunner, body, signal, akm
                 warn("memory inference: invalid JSON response from LLM; skipping memory.");
                 return undefined;
             }
+            // Only a literal boolean `true` is a decision; anything else falls through
+            // to the complete-payload checks, so a malformed reply is never restraint.
+            if (parsed.noChange === true)
+                return MEMORY_INFER_NO_CHANGE;
             const title = typeof parsed.title === "string" ? parsed.title.trim() : "";
             const description = typeof parsed.description === "string" ? parsed.description.trim() : "";
             const content = typeof parsed.content === "string" ? parsed.content.trim() : "";

package/dist/scripts/akm-migrate-node.js

@@ -28296,7 +28296,7 @@ function renderRunsDetailMd(runs) {
     "refl_ok/fail/cd/skip",
     "distill_q/llm-fail/judge/validator/cfg/skip",
     "cons_proc/promo/merge/del",
-    "mem_cons/written/skip",
+    "mem_cons/written/nochange/skip",
     "orphans",
     "lint_f/fl",
     "result_status"
@@ -28311,7 +28311,7 @@ function renderRunsDetailMd(runs) {
       `${r.actions.reflect.ok}/${r.actions.reflect.failed}/${r.actions.reflect.cooldown}/${r.actions.reflect.skipped}`,
       `${r.actions.distill.queued}/${r.actions.distill.llmFailed}/${r.actions.distill.judgeRejected}/${r.actions.distill.validatorRejected}/${r.actions.distill.configDisabled}/${r.actions.distill.skipped}`,
       `${r.consolidation.processed}/${r.consolidation.promoted}/${r.consolidation.merged}/${r.consolidation.deleted}`,
-      `${r.memoryInference.considered}/${r.memoryInference.written}/${r.memoryInference.skippedNoFacts}`,
+      `${r.memoryInference.considered}/${r.memoryInference.written}/${r.memoryInference.noChange}/${r.memoryInference.skippedNoFacts}`,
       String(r.orphansPurged),
       `${r.lintFixed}/${r.lintFlagged}`,
       r.resultStatus ?? "valid"
@@ -44342,14 +44342,18 @@ function parseMarkdownToc(content) {
   const headings = [];
   const parsed = parseFrontmatter(content);
   const start = parsed.frontmatter ? parsed.bodyStartLine - 1 : 0;
-  let inFence = false;
+  let fence;
   for (let i = start;i < lines.length; i++) {
-    if (/^\s*(`{3,}|~{3,})/.test(lines[i])) {
-      inFence = !inFence;
+    const [, run = "", rest = ""] = lines[i].match(/^ {0,3}(`{3,}|~{3,})(.*)$/) ?? [];
+    if (fence) {
+      if (run[0] === fence.char && run.length >= fence.length && !rest.trim())
+        fence = undefined;
       continue;
     }
-    if (inFence)
+    if (run && !(run[0] === "`" && rest.includes("`"))) {
+      fence = { char: run[0], length: run.length };
       continue;
+    }
     const match = lines[i].match(/^(#{1,6})\s+(.+)$/);
     if (match) {
       headings.push({
@@ -44975,7 +44979,9 @@ function parseSteps(ctx, raw) {
       return;
     }
     const label = typeof rawStep.id === "string" && rawStep.id !== "" ? `Step "${rawStep.id}"` : `Step ${index + 1}`;
-    checkUnknownKeys(ctx, rawStep, path27, STEP_KEYS, label);
+    const isMapStep = rawStep.map !== undefined;
+    const unitKeyHome = isMapStep ? "map.unit:" : "unit:";
+    checkUnknownKeys(ctx, rawStep, path27, STEP_KEYS, label, (key) => UNIT_KEYS.includes(key) ? ` (this belongs under "${unitKeyHome}")` : "");
     let id = "";
     if (typeof rawStep.id !== "string" || rawStep.id === "") {
       ctx.err([...path27, "id"], `${label} requires a non-empty string "id".`);
@@ -44990,7 +44996,6 @@ function parseSteps(ctx, raw) {
         seenIds.set(id, index);
       }
     }
-    const isMapStep = rawStep.map !== undefined;
     if (isMapStep && rawStep.unit !== undefined) {
       ctx.err(path27, `${label} is a map step; the per-item dispatch-override bag belongs at "map.unit", not top-level "unit".`);
     }
@@ -45002,6 +45007,9 @@ function parseSteps(ctx, raw) {
     const step = { id, source: ctx.refAt(path27) };
     if (unit)
       step.unit = unit;
+    if (output !== undefined && !isMapStep && unit?.output === undefined && unit?.workflow === undefined) {
+      step.unit = { ...unit ?? { source: step.source }, output };
+    }
     if (map)
       step.map = map;
     if (inputs)
@@ -45448,10 +45456,10 @@ function checkReferenceSyntax(ctx, text, path27, label) {
   if (!result.ok)
     ctx.err(path27, `${label}: ${result.message}`);
 }
-function checkUnknownKeys(ctx, obj, path27, allowed, label) {
+function checkUnknownKeys(ctx, obj, path27, allowed, label, hint = () => "") {
   for (const key of Object.keys(obj)) {
     if (!allowed.includes(key)) {
-      ctx.err([...path27, key], `Unknown ${label} key "${key}". Allowed keys: ${allowed.join(", ")}.`);
+      ctx.err([...path27, key], `Unknown ${label} key "${key}"${hint(key)}. Allowed keys: ${allowed.join(", ")}.`);
     }
   }
 }

package/dist/scripts/akm-migrate.js

@@ -27624,7 +27624,7 @@ function renderRunsDetailMd(runs) {
     "refl_ok/fail/cd/skip",
     "distill_q/llm-fail/judge/validator/cfg/skip",
     "cons_proc/promo/merge/del",
-    "mem_cons/written/skip",
+    "mem_cons/written/nochange/skip",
     "orphans",
     "lint_f/fl",
     "result_status"
@@ -27639,7 +27639,7 @@ function renderRunsDetailMd(runs) {
       `${r.actions.reflect.ok}/${r.actions.reflect.failed}/${r.actions.reflect.cooldown}/${r.actions.reflect.skipped}`,
       `${r.actions.distill.queued}/${r.actions.distill.llmFailed}/${r.actions.distill.judgeRejected}/${r.actions.distill.validatorRejected}/${r.actions.distill.configDisabled}/${r.actions.distill.skipped}`,
       `${r.consolidation.processed}/${r.consolidation.promoted}/${r.consolidation.merged}/${r.consolidation.deleted}`,
-      `${r.memoryInference.considered}/${r.memoryInference.written}/${r.memoryInference.skippedNoFacts}`,
+      `${r.memoryInference.considered}/${r.memoryInference.written}/${r.memoryInference.noChange}/${r.memoryInference.skippedNoFacts}`,
       String(r.orphansPurged),
       `${r.lintFixed}/${r.lintFlagged}`,
       r.resultStatus ?? "valid"
@@ -43670,14 +43670,18 @@ function parseMarkdownToc(content) {
   const headings = [];
   const parsed = parseFrontmatter(content);
   const start = parsed.frontmatter ? parsed.bodyStartLine - 1 : 0;
-  let inFence = false;
+  let fence;
   for (let i = start;i < lines.length; i++) {
-    if (/^\s*(`{3,}|~{3,})/.test(lines[i])) {
-      inFence = !inFence;
+    const [, run = "", rest = ""] = lines[i].match(/^ {0,3}(`{3,}|~{3,})(.*)$/) ?? [];
+    if (fence) {
+      if (run[0] === fence.char && run.length >= fence.length && !rest.trim())
+        fence = undefined;
       continue;
     }
-    if (inFence)
+    if (run && !(run[0] === "`" && rest.includes("`"))) {
+      fence = { char: run[0], length: run.length };
       continue;
+    }
     const match = lines[i].match(/^(#{1,6})\s+(.+)$/);
     if (match) {
       headings.push({
@@ -44303,7 +44307,9 @@ function parseSteps(ctx, raw) {
       return;
     }
     const label = typeof rawStep.id === "string" && rawStep.id !== "" ? `Step "${rawStep.id}"` : `Step ${index + 1}`;
-    checkUnknownKeys(ctx, rawStep, path27, STEP_KEYS, label);
+    const isMapStep = rawStep.map !== undefined;
+    const unitKeyHome = isMapStep ? "map.unit:" : "unit:";
+    checkUnknownKeys(ctx, rawStep, path27, STEP_KEYS, label, (key) => UNIT_KEYS.includes(key) ? ` (this belongs under "${unitKeyHome}")` : "");
     let id = "";
     if (typeof rawStep.id !== "string" || rawStep.id === "") {
       ctx.err([...path27, "id"], `${label} requires a non-empty string "id".`);
@@ -44318,7 +44324,6 @@ function parseSteps(ctx, raw) {
         seenIds.set(id, index);
       }
     }
-    const isMapStep = rawStep.map !== undefined;
     if (isMapStep && rawStep.unit !== undefined) {
       ctx.err(path27, `${label} is a map step; the per-item dispatch-override bag belongs at "map.unit", not top-level "unit".`);
     }
@@ -44330,6 +44335,9 @@ function parseSteps(ctx, raw) {
     const step = { id, source: ctx.refAt(path27) };
     if (unit)
       step.unit = unit;
+    if (output !== undefined && !isMapStep && unit?.output === undefined && unit?.workflow === undefined) {
+      step.unit = { ...unit ?? { source: step.source }, output };
+    }
     if (map)
       step.map = map;
     if (inputs)
@@ -44776,10 +44784,10 @@ function checkReferenceSyntax(ctx, text, path27, label) {
   if (!result.ok)
     ctx.err(path27, `${label}: ${result.message}`);
 }
-function checkUnknownKeys(ctx, obj, path27, allowed, label) {
+function checkUnknownKeys(ctx, obj, path27, allowed, label, hint = () => "") {
   for (const key of Object.keys(obj)) {
     if (!allowed.includes(key)) {
-      ctx.err([...path27, key], `Unknown ${label} key "${key}". Allowed keys: ${allowed.join(", ")}.`);
+      ctx.err([...path27, key], `Unknown ${label} key "${key}"${hint(key)}. Allowed keys: ${allowed.join(", ")}.`);
     }
   }
 }

package/dist/workflows/exec/environment.js

@@ -26,15 +26,11 @@ export function materializeFrozenWorkflowEnvironment(descriptors, options = {})
                 sensitive.add(descriptor.value);
             continue;
         }
-        if (descriptor.kind === "pass-through") {
-            const value = options.readPassThrough ? options.readPassThrough(descriptor.name) : process.env[descriptor.name];
-            if (value !== undefined) {
-                values[descriptor.name] = value;
-                if (value)
-                    sensitive.add(value);
-            }
+        // `pass_env` names reach the exec child through its allowlist
+        // (`execAllowlist`, exec-unit.ts), not as bindings. Their values are
+        // deliberately not redacted, so they are neither read nor marked sensitive here.
+        if (descriptor.kind === "pass-through")
             continue;
-        }
         const source = options.readEnvFile ? options.readEnvFile(descriptor) : readEnvFile(descriptor.owner);
         const parsed = dotenv.parse(typeof source === "string" ? source : Buffer.from(source));
         const keys = Object.keys(parsed).sort(compareCodePoints);

package/dist/workflows/parser.js

@@ -588,7 +588,9 @@ function parseSteps(ctx, raw) {
             return;
         }
         const label = typeof rawStep.id === "string" && rawStep.id !== "" ? `Step "${rawStep.id}"` : `Step ${index + 1}`;
-        checkUnknownKeys(ctx, rawStep, path, STEP_KEYS, label);
+        const isMapStep = rawStep.map !== undefined;
+        const unitKeyHome = isMapStep ? "map.unit:" : "unit:";
+        checkUnknownKeys(ctx, rawStep, path, STEP_KEYS, label, (key) => UNIT_KEYS.includes(key) ? ` (this belongs under "${unitKeyHome}")` : "");
         let id = "";
         if (typeof rawStep.id !== "string" || rawStep.id === "") {
             ctx.err([...path, "id"], `${label} requires a non-empty string "id".`);
@@ -608,7 +610,6 @@ function parseSteps(ctx, raw) {
                 seenIds.set(id, index);
             }
         }
-        const isMapStep = rawStep.map !== undefined;
         if (isMapStep && rawStep.unit !== undefined) {
             ctx.err(path, `${label} is a map step; the per-item dispatch-override bag belongs at "map.unit", not top-level "unit".`);
         }
@@ -620,6 +621,14 @@ function parseSteps(ctx, raw) {
         const step = { id, source: ctx.refAt(path) };
         if (unit)
             step.unit = unit;
+        // A solo step's `output` is also its unit's contract. Only `unit.output`
+        // makes the dispatch ask for, parse and re-request JSON, so without this a
+        // step-level schema met a raw text reply and could never pass. A map
+        // step's `output` describes the collected/reduced value, and a child
+        // workflow unit's result is the child's own, so both keep the step-only meaning.
+        if (output !== undefined && !isMapStep && unit?.output === undefined && unit?.workflow === undefined) {
+            step.unit = { ...(unit ?? { source: step.source }), output };
+        }
         if (map)
             step.map = map;
         if (inputs)
@@ -1149,10 +1158,10 @@ function checkReferenceSyntax(ctx, text, path, label) {
     if (!result.ok)
         ctx.err(path, `${label}: ${result.message}`);
 }
-function checkUnknownKeys(ctx, obj, path, allowed, label) {
+function checkUnknownKeys(ctx, obj, path, allowed, label, hint = () => "") {
     for (const key of Object.keys(obj)) {
         if (!allowed.includes(key)) {
-            ctx.err([...path, key], `Unknown ${label} key "${key}". Allowed keys: ${allowed.join(", ")}.`);
+            ctx.err([...path, key], `Unknown ${label} key "${key}"${hint(key)}. Allowed keys: ${allowed.join(", ")}.`);
         }
     }
 }

package/docs/architecture/0.10-process-rules.md

@@ -539,9 +539,9 @@ All paths are relative to the `rules-010` worktree. Citation form is `path:line`
 
 - **Only the default akm bundle is written** — Read-only caches (git, npm, website) are untouched. The pass takes the source whose `isDefault` flag is true, never `sources[0]` (fixed in this PR, #8), in line with `AGENTS.md` ("Never infer the default/trusted bundle from array position"). With no default bundle it warns `memory inference: skipped — no default bundle among the sources…`, and with a default bundle that is not an `akm` adapter bundle it warns and names the path; either way it writes nothing. The write target is still hardcoded `name: "stash"`. *Why:* inferred children written to caches "would be clobbered by the next sync()"; a skipped pass should say so (the gate's "never silent" rule). (`src/indexer/passes/memory-inference.ts:440-455,660-675`, `autonomy-gate.ts:26`)
 
-- **What is written: one derived memory per parent** — The LLM compresses the memory body into one derived memory: `title`, a one-sentence `description`, `content` (2–3 sentences), `tags` (3–8 in the prompt; schema min 1, max 8) and `searchHints` (3–6; schema min 1, max 6). It keeps names, versions, paths and config keys verbatim. The whole body is sent, because the 4000-char `MAX_BODY_CHARS` truncation was removed (otherwise the derived memory "looked complete" while the model saw a fraction). The temperature is the engine's or process's configured one, else 0.1. *Why:* compress a memory into a higher-signal memory for later retrieval. (`src/llm/memory-infer.ts:77-88,123-139`; `src/assets/prompts/memory-infer-user.md`; CHANGELOG 0.9.2x ("Memory inference uses the configured temperature") and "Content and memory bodies are no longer silently truncated")
+- **What is written: one derived memory per parent** — The LLM compresses the memory body into one derived memory: `title`, a one-sentence `description`, `content` (2–3 sentences), `tags` (3–8 in the prompt; schema max 8) and `searchHints` (3–6; schema max 6; the parser requires at least one of each unless the reply is a no-change). It keeps names, versions, paths and config keys verbatim. The whole body is sent, because the 4000-char `MAX_BODY_CHARS` truncation was removed (otherwise the derived memory "looked complete" while the model saw a fraction). The temperature is the engine's or process's configured one, else 0.1. *Why:* compress a memory into a higher-signal memory for later retrieval. (`src/llm/memory-infer.ts:77-88,123-139`; `src/assets/prompts/memory-infer-user.md`; CHANGELOG 0.9.2x ("Memory inference uses the configured temperature") and "Content and memory bodies are no longer silently truncated")
 
-- **Reply validation** — The reply is skipped (returns nothing and warns) if it is invalid JSON, if any of title, description, content, tags or searchHints is missing or empty, or if it is a prompt placeholder echoed back ("short title string", "tag1", etc.). Tags are trimmed and capped at 8, hints at 6. *Why:* "never return field descriptions or placeholder values". (`src/llm/memory-infer.ts:36-44,140-177`)
+- **Reply validation** — A reply with `noChange: true` is the no-change result (see "No change is a successful result"). Otherwise the reply is skipped (returns nothing and warns) if it is invalid JSON, if any of title, description, content, tags or searchHints is missing or empty, or if it is a prompt placeholder echoed back ("short title string", "tag1", etc.). Tags are trimmed and capped at 8, hints at 6. *Why:* "never return field descriptions or placeholder values". (`src/llm/memory-infer.ts:36-44,140-177`)
 
 - **Derived file shape and naming** — The child is `memories/<parent>.derived.md` with frontmatter `inferred: true`, `captureMode: background`, `source: memories/<parent>`, `derivedFrom`, `description`, `tags`, `searchHints`, `title` and `updated`. The body is `# Title` plus the content. It is written through `writeAssetToSource`. The child carries no `createdAt`, so memory cleanup anchors relative dates on its file mtime. *Why:* `.derived` is a provenance marker on the same identity. (`src/indexer/passes/memory-inference.ts:659-717`; `.derived` inputs are skipped by `eligibility.ts:283-285`, `distill-promotion-policy.ts:129-131` and `memory/derived-ref.ts:46-47`; #882 in CHANGELOG)
 
@@ -551,10 +551,12 @@ All paths are relative to the `rules-010` worktree. Citation form is `path:line`
 
 - **Child-exists pre-check (#588, #550)** — Before any LLM or cache call, if `<parent>.derived.md` already exists on disk, the parent is marked processed and no attempt is used (`skippedChildExists`). A child that appears mid-flight, or a write throw, also counts there. A genuine write failure leaves the parent unmarked for retry. *Why:* #588: about 55% of the inference budget was spent rediscovering children that already existed. #550: parents were re-queued every run (about 37 wasted LLM calls per run on one stash). (`src/indexer/passes/memory-inference.ts:204-210,265-285,343-358,663-700`; CHANGELOG #588/#550)
 
-- **Caching** — Results are cached in the index DB keyed by the parent's file path, a body hash and variant `memory-inference-v2`. An unchanged body gets a validated cache hit with no LLM call (`cacheHits`). `reEnrich` bypasses it (the improve step passes `false`). A corrupt cache entry falls through to recompute. *Why:* skip re-processing unchanged content; cache hits are tracked separately so the yield rate does not drift as the cache warms. (`src/indexer/passes/memory-inference.ts:210-221,304-332`; `src/indexer/db/llm-cache.ts:53-86`)
+- **Caching** — Results are cached in the index DB keyed by the parent's file path, a body hash and variant `memory-inference-v3` (bumped from v2 when a cached row could become an explicit no-change decision; older rows are never read, a disposable miss). An unchanged body gets a validated cache hit with no LLM call (`cacheHits`). The cached value is a derived memory or `{ "noChange": true }`; an unrecognised value falls through to recompute. `reEnrich` bypasses it (the improve step passes `false`). A corrupt cache entry falls through to recompute. *Why:* skip re-processing unchanged content; cache hits are tracked separately so the yield rate does not drift as the cache warms. (`src/indexer/passes/memory-inference.ts:210-221,304-332`; `src/indexer/db/llm-cache.ts:53-86`)
 
 - **Retries** — The LLM client retries once on a retryable transient failure, after a jittered backoff of 200–800 ms. The retry is skipped if 90% of the timeout was already used. The retry counts as `retryAttempts`, not a failure. *Why:* "a single bounded retry for transient failures". (`src/llm/client.ts:144-182,300-330`; `src/indexer/passes/memory-inference.ts:289-291`)
 
+- **No change is a successful result (#1208)** — The model may reply `noChange: true` (the other fields empty) when a derived memory would add nothing: a tool-count or checkpoint note, or a note already short and specific. Only a literal boolean `true` counts. The pass counts it in `noChange` (fresh or cached, also in `cacheHits` when cached), writes no child, and leaves the parent untouched: it is NOT stamped `inferenceProcessed`, because that flag is checked before the body hash and would hide a later edit. The decision is cached like any result, so an unchanged body makes no further call and does not mutate the parent; an edited body (the cache key is the body hash, the whole input the model sees) or `reEnrich` asks the model again. `noChange` never feeds `skippedNoFacts`, `htmlErrorCount` or `unaccounted`. Anything that is not a clean reply (invalid or incomplete JSON, HTML, timeout, abort, transport error, disabled pass) stays `undefined`, is never cached, and is retried. Without a database the decision is reported but not remembered. The count is `improve` result `memoryInference.noChange` and health `memoryInference.noChange`; health `yieldRate` is unchanged (`written / freshAttempts`) and measures child yield, which restraint lowers by design. *Why:* the prompt demanded a child for every note, so an unusable reply was a failure that cost a model call on every run. (`src/llm/memory-infer.ts`; `src/indexer/passes/memory-inference.ts`)
+
 - **Skips leave the parent pending** — If the LLM returns nothing usable (timeout, invalid, incomplete or placeholder reply), `skippedNoFacts` counts it and the parent is NOT marked processed, so it is retried on the next run. An HTML reply is counted in `htmlErrorCount`. The per-call failure never throws. An abort signal skips unstarted parents (`skippedAborted`). Credentials are checked up front only if at least one parent will dispatch to the model, so cache-only batches work offline. *Why:* "a transient LLM failure should be retried on the next index run". (`src/indexer/passes/memory-inference.ts:341,516-519,464-465`; `src/llm/memory-infer.ts:178-188`)
 
 - **Concurrency and enablement layers** — The pass runs with the engine connection's `concurrency` or 1. The live gates are autonomy, then `processes.memoryInference.enabled`, then `minPendingCount`, then a resolvable runner; any off makes it a no-op. `index.memory.enabled` has no effect in 0.10: the only caller passes a runner, which forces it on, so there is no standalone `akm index` path. Existing derived children are never deleted. *Why:* "A pass runs iff both layers allow it." (`src/indexer/passes/memory-inference.ts:22-30,425-435,472-492`; `src/llm/feature-gate.ts:54`)

package/docs/architecture/internals/storage-locations.md

@@ -275,7 +275,7 @@ Incremental indexing cache. Directory skipped if hash + mtime unchanged.
 | Column | Type | Notes |
 |---|---|---|
 | `asset_ref` | TEXT NOT NULL | Absolute file path |
-| `cache_variant` | TEXT NOT NULL | Extractor/cache fingerprint. Memory inference uses a version-tagged variant (`memory-inference-v2`). |
+| `cache_variant` | TEXT NOT NULL | Extractor/cache fingerprint. Memory inference uses a version-tagged variant (`memory-inference-v3`). |
 | `body_hash` | TEXT NOT NULL | SHA-256 hex digest of file body |
 | `result_json` | TEXT NOT NULL | Serialized LLM enrichment result |
 | `updated_at` | INTEGER NOT NULL | Unix ms timestamp |