backpass 0.1.6 → 0.1.7

package/README.md

@@ -249,7 +249,24 @@ edit is not proposed again unless materially new evidence arrives.
 The live budget gauge is not just a readout. Apply rechecks the accepted subset against
 the same budget gate as synthesis: stay under the cap, or shrink if the file is already
 over. An incompatible set writes nothing and does not record rejections, so you can pick
-a compatible set and try again.
+a compatible set and try again. If the run shrinks the file but leaves it above the cap,
+that is progress, not a failure: it is written, and the remaining overage is printed.
+
+Apply preflights every accepted edit before writing. The proposal was measured against one
+exact version of your memory file, so apply first checks the file still exists and is still
+that version. If it was removed or changed since - you pulled, edited it by hand, or another
+agent did - the edits no longer describe what is on disk, so nothing is written and you are
+told to run `backpass` again to re-propose against the current file. Within a run every file
+is composed from one version: it takes every accepted edit or none of them.
+
+Skills are written only after every edit has composed, and before the memory file, so a
+write failure cannot leave the memory file pointing at a missing skill. If one skill write
+fails after another succeeded, apply names the unreferenced skill paths to remove before
+retrying.
+
+For compatibility, proposals created by older backpass versions that do not contain a
+memory-file hash skip the freshness check. Regenerate such a proposal before applying it if
+the repository may have changed.
 
 ```sh
 backpass apply --no-ui     # same decision, in the terminal

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backpass",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "packageManager": "pnpm@11.5.0",
   "description": "Gradient descent for your agent memory - analyzes past agent session transcripts and proposes evidence-backed edits to AGENTS.md / CLAUDE.md",
   "type": "module",

package/src/apply/writer.js

@@ -2,18 +2,19 @@ import fs from "node:fs";
 import path from "node:path";
 
 import { applyEdit, projectWithDecisions } from "../proposal.js";
-import { budgetGateKind, budgetStatus } from "../tokens.js";
+import { memoryTextHash } from "../memory.js";
+import { budgetGateKind, budgetStatus, formatTokens } from "../tokens.js";
 import { recordRejection } from "../state.js";
 import { writeSkill } from "../skills.js";
 
-function acceptedSubsetBudgetFailure({ proposal, accepted, repo, capTokens }) {
+function acceptedSubsetBudgetFailure({ proposal, accepted, repo, capTokens, memoryText }) {
   if (!accepted.length) return null;
 
   const relative = proposal.memoryFile.path;
   const absolute = path.join(repo.root, relative);
-  if (!fs.existsSync(absolute)) return null;
+  if (memoryText === null && !fs.existsSync(absolute)) return null;
 
-  const before = fs.readFileSync(absolute, "utf8");
+  const before = memoryText ?? fs.readFileSync(absolute, "utf8");
   const { budget } = projectWithDecisions(
     before,
     accepted,
@@ -41,14 +42,75 @@ function acceptedSubsetBudgetFailure({ proposal, accepted, repo, capTokens }) {
   return null;
 }
 
+/**
+ * Freshness before mutation.
+ *
+ * Every hunk was cut from one exact image of the memory file, and the proposal records
+ * that image's hash. If the file has disappeared or changed since - an upstream merge,
+ * a hand edit, another agent - then the hunks describe text that may no longer exist, and the ones
+ * that still happen to match would leave the file half-descended: part of a shrink plan
+ * applied against a file the plan was never measured against. So the run is refused
+ * before it writes anything, and the fix is to re-measure, not to salvage.
+ *
+ * A proposal saved before this field existed carries no hash and is left alone.
+ */
+function memoryFileSnapshot(proposal, repo) {
+  const expected = proposal.memoryFile?.hash;
+  const relative = proposal.memoryFile?.path;
+  if (!relative) return { text: null };
+
+  const absolute = path.join(repo.root, relative);
+  if (!fs.existsSync(absolute)) {
+    if (!expected) return { text: null };
+    return {
+      text: null,
+      failure: {
+        file: relative,
+        error:
+          `${relative} no longer exists, so its edits no longer describe the file on disk; nothing was written. ` +
+          `Run \`backpass\` to re-propose against the current repository.`,
+      },
+    };
+  }
+
+  const text = fs.readFileSync(absolute, "utf8");
+  if (!expected) return { text };
+
+  const observed = memoryTextHash(text);
+  if (observed === expected) return { text };
+
+  return {
+    text,
+    failure: {
+      file: relative,
+      error:
+        `${relative} changed after this proposal was made (${expected} -> ${observed}), so its edits ` +
+        `no longer describe the file on disk; nothing was written. Run \`backpass\` to re-propose ` +
+        `against the current ${relative}.`,
+    },
+  };
+}
+
+function overBudgetWarning(relative, budget) {
+  return (
+    `${relative} is still ${formatTokens(budget.over)} tokens over the ${formatTokens(budget.capTokens)}-token ` +
+    "budget; run `backpass` again for the next shrink step"
+  );
+}
+
 /**
  * The only place in backpass that writes to the repo.
  *
  * Everything upstream is read-only analysis; a run only changes the weights here, after
- * a human accepted specific edits. The accepted subset is rechecked with the same
- * cap/shrink budget gate as the full proposal (`budgetGateKind`); a failing subset
- * returns with no writes and no rejection ledger. Writes are grouped per file so a
- * memory file is rewritten once, atomically, rather than edit by edit.
+ * a human accepted specific edits. Three gates run before the first byte is written:
+ * the memory file must still be the file the proposal was measured against
+ * (`memoryFileSnapshot`), the accepted subset must clear the same cap/shrink budget gate as
+ * the full proposal (`budgetGateKind`), and every accepted edit for a file must compose
+ * against that file's single pre-write image. Any of them failing writes nothing and
+ * records no rejection.
+ *
+ * A file is therefore applied all at once or not at all. Skills are written only after
+ * every accepted edit has composed, and before the files that reference them.
  */
 export function applyDecisions({ proposal, decisions, repo, state, config, dryRun = false }) {
   const accepted = proposal.edits.filter((e) => decisions[e.id] === "accepted");
@@ -65,11 +127,22 @@ export function applyDecisions({ proposal, decisions, repo, state, config, dryRu
     rejectionsRecorded: false,
   };
 
+  let memoryText = null;
+  if (accepted.length || rejected.length) {
+    const snapshot = memoryFileSnapshot(proposal, repo);
+    if (snapshot.failure) {
+      results.failed.push(snapshot.failure);
+      return results;
+    }
+    memoryText = snapshot.text;
+  }
+
   const budgetFailure = acceptedSubsetBudgetFailure({
     proposal,
     accepted,
     repo,
     capTokens: config.budgetTokens,
+    memoryText,
   });
   if (budgetFailure) {
     results.failed.push(budgetFailure);
@@ -81,6 +154,11 @@ export function applyDecisions({ proposal, decisions, repo, state, config, dryRu
     byFile.get(edit.file).push(edit);
   }
 
+  // Compose first, write later. Each file's accepted edits are applied to one immutable
+  // image of that file; only a set that composes completely earns a write.
+  const planned = [];
+  const landed = new Set();
+
   for (const [relative, edits] of byFile) {
     const absolute = path.join(repo.root, relative);
     if (!fs.existsSync(absolute)) {
@@ -88,38 +166,83 @@ export function applyDecisions({ proposal, decisions, repo, state, config, dryRu
       continue;
     }
 
-    const before = fs.readFileSync(absolute, "utf8");
+    const before =
+      relative === proposal.memoryFile?.path && memoryText !== null ? memoryText : fs.readFileSync(absolute, "utf8");
     let text = before;
     const applied = [];
+    const failures = [];
 
     for (const edit of edits) {
       try {
         text = applyEdit(text, edit);
         applied.push(edit.id);
       } catch (err) {
-        results.failed.push({ file: relative, edit: edit.id, error: err.message });
+        failures.push({ file: relative, edit: edit.id, error: err.message });
       }
     }
 
-    if (text === before) continue;
-
-    const budget = relative === proposal.memoryFile.path ? budgetStatus(before, text, config.budgetTokens) : null;
+    if (failures.length) {
+      results.failed.push(...failures);
+      if (applied.length) {
+        results.failed.push({
+          file: relative,
+          error: `${relative} was left unchanged: a file takes every accepted edit or none of them`,
+        });
+      }
+      continue;
+    }
 
-    if (!dryRun) fs.writeFileSync(absolute, text);
-    results.written.push({ file: relative, edits: applied, budget, dryRun });
+    if (text === before) continue;
+    planned.push({ relative, absolute, before, text, applied });
+    for (const id of applied) landed.add(id);
   }
 
+  if (results.failed.length) return results;
+
+  // Skills go in before the memory file. A skill nothing points at yet is inert, while a
+  // memory file pointing at a skill that is not there is actively wrong - so if a skill
+  // cannot be written, the files that would reference it are left alone.
+  const skillFailures = [];
+  const writtenSkillPaths = [];
   for (const edit of accepted) {
     if (edit.kind !== "extract" || !edit.skill) continue;
+    if (!landed.has(edit.id)) continue;
     try {
       const layout = dryRun ? { created: [], warnings: [] } : writeSkill(repo.root, edit.skill);
       results.skills.push({ path: edit.skill.path, dryRun, created: layout.created });
+      if (!dryRun) writtenSkillPaths.push(edit.skill.path);
       for (const w of layout.warnings) if (!results.warnings.includes(w)) results.warnings.push(w);
     } catch (err) {
-      results.failed.push({ file: edit.skill.path, edit: edit.id, error: err.message });
+      skillFailures.push({ file: edit.skill.path, edit: edit.id, error: err.message });
     }
   }
 
+  if (skillFailures.length) {
+    results.failed.push(...skillFailures);
+    if (writtenSkillPaths.length) {
+      results.failed.push({
+        error: `skill paths already written in this round: ${writtenSkillPaths.join(", ")}; remove them before retrying`,
+      });
+    }
+    for (const { relative } of planned) {
+      results.failed.push({
+        file: relative,
+        error: `${relative} was left unchanged: its edits point at a skill that could not be written`,
+      });
+    }
+    return results;
+  }
+
+  for (const { relative, absolute, before, text, applied } of planned) {
+    const budget = relative === proposal.memoryFile.path ? budgetStatus(before, text, config.budgetTokens) : null;
+
+    if (!dryRun) fs.writeFileSync(absolute, text);
+    results.written.push({ file: relative, edits: applied, budget, dryRun });
+
+    // Shrinking over several runs is the design, so this is a heading, not a failure.
+    if (budget && !budget.withinBudget) results.warnings.push(overBudgetWarning(relative, budget));
+  }
+
   // Rejections are remembered so the same edit is not re-proposed without new evidence.
   if (!dryRun && rejected.length) {
     const rejections = state.readRejections();

package/src/commands/apply.js

@@ -10,8 +10,8 @@ import { budgetBar, formatTokens } from "../tokens.js";
  *
  * By default it serves the shipped static template through lavish-axi and waits for one
  * structured decision vector; `--no-ui` keeps the same ACCEPT/REJECT decision in the
- * terminal. `applyDecisions` revalidates the accepted subset against the budget before
- * writing; a failing set records no rejections.
+ * terminal. `applyDecisions` owns the pre-write freshness, budget, and composition gates;
+ * a failing gate records no rejections.
  */
 export async function cmdApply(ctx) {
   const { config, repo } = ctx;

package/src/memory.js

@@ -116,6 +116,15 @@ export function parseMemoryUnits(text) {
   }));
 }
 
+/**
+ * The fingerprint of one memory file's exact bytes. It is written into the proposal and
+ * re-checked at apply, so it has exactly one definition: a proposal and the freshness
+ * check that guards it can never disagree about what "unchanged" means.
+ */
+export function memoryTextHash(text) {
+  return `sha256:${sha256(text).slice(0, 16)}`;
+}
+
 export function readMemoryFile(repoRoot, relativePath) {
   const absolute = path.join(repoRoot, relativePath);
   if (!fs.existsSync(absolute)) return null;
@@ -124,7 +133,7 @@ export function readMemoryFile(repoRoot, relativePath) {
     path: relativePath,
     absolute,
     text,
-    hash: `sha256:${sha256(text).slice(0, 16)}`,
+    hash: memoryTextHash(text),
     tokens: estimateTokens(text),
     units: parseMemoryUnits(text),
   };

package/src/tokens.js

@@ -47,9 +47,16 @@ export function budgetGateKind(budget) {
   return null;
 }
 
-/** Fixed-width ASCII gauge for `backpass status`. */
+/**
+ * Fixed-width ASCII gauge for `backpass status`.
+ *
+ * Over budget the `!!` marker gets its own cells rather than the leftover ones, because
+ * past 100% there are no leftover cells: a file at twice its cap must not render as a
+ * merely-full bar.
+ */
 export function budgetBar(status, width = 32) {
-  const filled = Math.min(width, Math.round(status.utilization * width));
-  const overflow = status.withinBudget ? 0 : Math.min(width - filled, 2);
-  return `[${"#".repeat(filled)}${"!".repeat(overflow)}${".".repeat(Math.max(0, width - filled - overflow))}]`;
+  const overflow = status.withinBudget ? 0 : Math.min(width, 2);
+  const cells = width - overflow;
+  const filled = Math.min(cells, Math.round(status.utilization * width));
+  return `[${"#".repeat(filled)}${"!".repeat(overflow)}${".".repeat(Math.max(0, cells - filled))}]`;
 }