sphica 0.6.36 → 0.6.37

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "sphica",
-  "version": "0.6.36",
+  "version": "0.6.37",
   "description": "Records Claude Code and Codex sessions on your machine and keeps past implementation and decisions, with their sources, for your agent to find.",
   "author": {
     "name": "iroha924",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "sphica",
-  "version": "0.6.36",
+  "version": "0.6.37",
   "description": "Records Claude Code and Codex sessions on your machine and keeps past implementation and decisions, with their sources, for your agent to find.",
   "author": {
     "name": "iroha924",

package/dist/mcp-record.js

@@ -46274,6 +46274,20 @@ async function inTransaction(db, fn) {
     }
   });
 }
+async function inRolledBack(db, fn) {
+  return db.connection().execute(async (c) => {
+    await sql`begin immediate`.execute(c);
+    let out;
+    try {
+      out = await fn(c);
+    } catch (e) {
+      await sql`rollback`.execute(c).catch(() => {});
+      throw e;
+    }
+    await sql`rollback`.execute(c);
+    return out;
+  });
+}
 var iso = (d) => {
   const t = new Date(d);
   if (Number.isNaN(t.getTime()))
@@ -48691,9 +48705,7 @@ async function checkRecord(db, target, raw, facts = prepareRecord(target.root, r
     ...new Set(record4.units.flatMap((u) => [...u.supersedes ? [u.supersedes] : [], ...u.conflicts]))
   ];
   const others = new Map((linked.length ? await db.selectFrom("unit as o").select(["o.id", "o.key", "o.kind", "o.lifecycle"]).where("o.project_id", "=", target.projectId).where("o.key", "in", linked).execute() : []).map((u) => [u.key, u]));
-  const holders = new Map((others.size ? await db.selectFrom("unit_replacement as h").innerJoin("unit as n", "n.id", "h.from_unit").select(["h.to_unit", "n.key", "n.lifecycle"]).where("h.ended_at", "is", null).where("h.to_unit", "in", [...others.values()].map((o) => o.id)).execute() : []).map((h) => [h.to_unit, h]));
   const units = [];
-  const claimed = new Set;
   for (const [i, u] of record4.units.entries()) {
     const key = keys[i] ?? "";
     const quarantine = [];
@@ -48851,23 +48863,14 @@ async function checkRecord(db, target, raw, facts = prepareRecord(target.root, r
     let supersedes = null;
     if (u.supersedes) {
       const old = others.get(u.supersedes);
-      const implemented = () => evidence.some((e) => e.role === "implements" && (["commit_message", "file_excerpt"].includes(sources.get(e.source)?.kind ?? "") || anchors.some((a) => a.role === "evidence" && (a.commit || a.observation !== null && sources.get(e.source)?.session_id === target.sessionId)))) || anchors.some((a) => a.role === "evidence" && a.commit);
-      const takes = ["decision", "constraint"].includes(u.kind) ? adoption.some((x) => x.route !== "agent") : u.kind !== "implementation" || implemented();
       if (!old)
         errors3.push(`${key}: supersedes ${u.supersedes}, which is not a record of this project`);
       else if (!["active", "candidate"].includes(old.lifecycle))
         errors3.push(`${key}: ${u.supersedes} is already ${old.lifecycle}`);
-      else if (claimed.has(old.id) && !quarantine.length && takes)
-        errors3.push(`${key}: another record in this save already supersedes ${u.supersedes}`);
       else if (!replaceable(u.kind, old.kind))
         errors3.push(`${key}: a ${u.kind} cannot supersede ${u.supersedes}, a ${old.kind} (a record supersedes one of its own kind; a decision and a constraint can replace each other)`);
-      else if (holders.has(old.id) && !quarantine.length && takes) {
-        const h = holders.get(old.id);
-        errors3.push(`${key}: ${u.supersedes} already has a successor, ${h?.key} (${h?.lifecycle}); withdraw it first, or supersede it instead`);
-      } else
+      else
         supersedes = old.id;
-      if (supersedes !== null && !quarantine.length && takes)
-        claimed.add(supersedes);
     }
     const conflicts = u.conflicts.flatMap((k) => {
       const other = others.get(k);
@@ -49001,12 +49004,20 @@ var contentHash = (u) => sha256(JSON.stringify([
   u.revisit_when ?? null,
   u.options.map((o) => o.reconsider_when === undefined ? [o.text, o.outcome, o.why ?? null] : [o.text, o.outcome, o.why ?? null, o.reconsider_when])
 ]));
+
+class SaveRefused extends Error {
+}
 async function settleSaved(trx, runId, saved, more = {}) {
   const written = new Map(saved.written.map((w) => [w.id, w]));
   const settled2 = await reconcile(trx, [...written.keys(), ...more.seeds ?? []], { runId }, {
     hints: new Map(saved.written.map((w) => [w.id, w.hint])),
     withdraw: more.withdraw
   });
+  const mine = new Set([...written.keys(), ...more.adopted ?? []]);
+  const key = (id) => settled2.keys.get(id) ?? `u${id}`;
+  for (const [id, [to, holder]] of settled2.held)
+    if (mine.has(id))
+      throw new SaveRefused(mine.has(holder) ? `${key(id)}: another record in this save already supersedes ${key(to)}` : `${key(id)}: ${key(to)} already has a successor, ${key(holder)} (in effect); withdraw it first, or supersede it instead`);
   const now = new Map(settled2.changes.map((c) => [c.id, c.after]));
   for (const w of saved.written) {
     if (saved.quarantined.some((q) => q.startsWith(`${w.key} (`)))
@@ -49179,7 +49190,6 @@ ${checked.errors.map((e) => `  ${e}`).join(`
     saved.written.push({
       id,
       key: p.key,
-      adopted: p.adoption.length > 0,
       hint: {
         reason: p.adoption.length ? "evidence and adoption found" : "evidence found",
         source: p.adoption[0]?.source ?? p.evidence[0]?.source ?? null
@@ -49477,9 +49487,6 @@ async function checkGlean(db, target, raw, facts = prepareGlean(target.root, raw
         errors3.push(`${what}: the merge does not adopt a proposal`);
       else if (got && got.s.author_kind !== "owner" && !MAINTAINERS2.has(got.s.author_association ?? ""))
         errors3.push(`${what}: only the owner or a maintainer can adopt`);
-      const held = await db.selectFrom("unit_link as l").innerJoin("unit_replacement as r", (j) => j.onRef("r.to_unit", "=", "l.to_unit").on("r.ended_at", "is", null)).innerJoin("unit as h", "h.id", "r.from_unit").innerJoin("unit as t", "t.id", "l.to_unit").where("l.from_unit", "=", u.id).where("l.kind", "=", "supersedes").where("r.from_unit", "!=", u.id).select(["h.key as holder", "t.key as replaced"]).executeTakeFirst();
-      if (held && !parsed.data.ops.some((o) => o.op === "withdraw" && o.unit === held.holder))
-        errors3.push(`${what}: ${held.replaced} already has a successor, ${held.holder} (in effect); withdraw it first, or supersede it instead`);
     }
     if (op.op === "anchor" && !repoPath(op.path))
       errors3.push(`${what}: the path is not inside the repository`);
@@ -49773,16 +49780,11 @@ ${c.errors.map((e) => `  ${e}`).join(`
   }
   const settled2 = await settleSaved(trx, runId, units, {
     seeds: [...touched.keys(), ...withdraw.keys()],
-    withdraw
+    withdraw,
+    adopted
   });
   for (const id of settled2.redundant)
     changed2.push(`${settled2.keys.get(id)}: superseded by a record of this save, so not withdrawn`);
-  for (const w of units.written)
-    if (w.adopted)
-      adopted.add(w.id);
-  for (const [id, [to, holder]] of settled2.held)
-    if (adopted.has(id))
-      throw new Error(`${settled2.keys.get(id)}: ${settled2.keys.get(to)} already has a successor, ${settled2.keys.get(holder)} (in effect); withdraw it first, or supersede it instead`);
   const written = new Set(units.written.map((w) => w.id));
   for (const ch of settled2.changes) {
     if (written.has(ch.id))
@@ -50243,42 +50245,43 @@ function contextOnly(id, items, c) {
     ...c.work && !c.units.length ? ["work: an automatic run updates work only beside a record of the messages it traces"] : []
   ];
 }
-async function checkText(db, id, projectId2, root, record4, call) {
-  const run = await bound(db, id, projectId2);
-  const { target, items } = await scopeOf(db, run, root);
-  target.agent = await agentRun(db, run, call);
-  const c = run.origin === "glean" ? await checkGlean(db, target, record4) : await checkRecord(db, target, record4);
-  if (!("ops" in c))
-    c.errors.push(...contextOnly(id, items, c));
-  const units = "ops" in c ? c.units.units : c.units;
-  const lines = [
-    ...c.errors.map((e) => `✗ ${e}`),
-    ...c.problems.map((p) => `△ ${p}`),
-    ...units.filter((u) => u.quarantine.length).map((u) => `△ ${u.key} will be quarantined: ${u.quarantine.join("; ")}`)
-  ];
-  const summary = c.errors.length ? `✗ ${plural2(c.errors.length, "error")}; fix the record and check again` : `✓ ${plural2(units.length, "record")}${"ops" in c ? ` and ${plural2(c.ops.length, "change")}` : ""} can be saved`;
-  return { ok: c.errors.length === 0, text: [...lines, summary].join(`
-`) };
-}
-async function saveText(db, id, projectId2, root, record4, probe, call) {
+async function prepare2(db, id, projectId2, root, record4, probe, call) {
   const begun = await bound(db, id, projectId2);
   if (call !== undefined && begun.begin_call_id !== null)
     await sameCaller(db, begun.begin_call_id, call);
-  const glean = begun.origin === "glean";
-  const gleanFacts = glean ? prepareGlean(root, record4, probe) : undefined;
-  const facts = gleanFacts ?? prepareRecord(root, record4, probe);
-  const text3 = await inTransaction(db, async (trx) => {
-    const run = await bound(trx, id, projectId2);
-    const scope = await scopeOf(trx, run, root);
-    scope.target.agent = await agentRun(trx, run, call);
-    const lines = [];
-    const notes = [];
-    const saved = run.origin === "glean" ? await saveGlean(trx, scope.target, run.id, await checkGlean(trx, scope.target, record4, gleanFacts)).then((g) => {
-      lines.push(...g.changed.map((c) => `✓ ${c}`));
-      return g.units;
-    }) : await checkRecord(trx, scope.target, record4, facts).then((checked) => {
-      checked.errors.push(...contextOnly(id, scope.items, checked));
-      notes.push(...checked.problems);
+  const gleanFacts = begun.origin === "glean" ? prepareGlean(root, record4, probe) : undefined;
+  return { facts: gleanFacts ?? prepareRecord(root, record4, probe), gleanFacts };
+}
+async function validate2(trx, id, projectId2, root, record4, prepared, call) {
+  const run = await bound(trx, id, projectId2);
+  const scope = await scopeOf(trx, run, root);
+  scope.target.agent = await agentRun(trx, run, call);
+  const quarantine = (units) => units.filter((u) => u.quarantine.length).map((u) => `${u.key} will be quarantined: ${u.quarantine.join("; ")}`);
+  if (run.origin === "glean") {
+    const c = await checkGlean(trx, scope.target, record4, prepared.gleanFacts);
+    return {
+      run,
+      errors: c.errors,
+      problems: c.problems,
+      quarantine: quarantine(c.units.units),
+      units: c.units.units.length,
+      ops: c.ops.length,
+      write: async (w) => {
+        const g = await saveGlean(w, scope.target, run.id, c);
+        return { saved: g.units, changed: g.changed };
+      }
+    };
+  }
+  const checked = await checkRecord(trx, scope.target, record4, prepared.facts);
+  checked.errors.push(...contextOnly(id, scope.items, checked));
+  return {
+    run,
+    errors: checked.errors,
+    problems: checked.problems,
+    quarantine: quarantine(checked.units),
+    units: checked.units.length,
+    ops: null,
+    write: async (w) => {
       const shown = shownTo.get(id)?.sources ?? new Set;
       const cited = new Set([
         ...checked.units.flatMap((u) => [
@@ -50289,17 +50292,62 @@ async function saveText(db, id, projectId2, root, record4, probe, call) {
         ]),
         ...checked.fieldDefs
       ].map((q) => q.source));
-      return saveRecord(trx, scope.target, run.id, checked, scope.looked.filter((s) => shown.has(s) || cited.has(s)));
-    });
-    await finishRun(trx, run.id);
+      const saved = await saveRecord(w, scope.target, run.id, checked, scope.looked.filter((s) => shown.has(s) || cited.has(s)));
+      return { saved, changed: [] };
+    }
+  };
+}
+async function checkText(db, id, projectId2, root, record4, call, probe) {
+  const prepared = await prepare2(db, id, projectId2, root, record4, probe, call);
+  const { v, done, refused } = await inRolledBack(db, async (trx) => {
+    const v2 = await validate2(trx, id, projectId2, root, record4, prepared, call);
+    if (v2.errors.length)
+      return { v: v2, done: null, refused: null };
+    try {
+      const done2 = await v2.write(trx);
+      await finishRun(trx, v2.run.id);
+      return { v: v2, done: done2, refused: null };
+    } catch (e) {
+      if (!(e instanceof SaveRefused))
+        throw e;
+      return { v: v2, done: null, refused: e.message };
+    }
+  });
+  const errors3 = [...v.errors, ...refused === null ? [] : [refused]];
+  const lines = [
+    ...errors3.map((e) => `✗ ${e}`),
+    ...[...new Set(v.problems)].map((p) => `△ ${p}`),
+    ...done ? [
+      ...done.saved.active.map((k) => `✓ would be active: ${k}`),
+      ...done.saved.superseded.map((k) => `✓ would be superseded: ${k}`),
+      ...done.saved.candidates.map((c) => `△ would stay a candidate: ${c.key}: ${c.why}`),
+      ...done.saved.quarantined.map((q) => `△ would be quarantined: ${q}`),
+      ...[...new Set(done.saved.anchorProblems)].filter((a) => !v.problems.some((p) => p === a || p.endsWith(` ${a}`))).map((a) => `△ ${a}`),
+      ...done.changed.map((c) => `✓ would: ${c}`)
+    ] : v.quarantine.map((q) => `△ ${q}`)
+  ];
+  const summary = errors3.length ? `✗ ${plural2(errors3.length, "error")}; fix the record and check again` : `✓ ${plural2(v.units, "record")}${v.ops === null ? "" : ` and ${plural2(v.ops, "change")}`} can be saved`;
+  return { ok: errors3.length === 0, text: [...lines, summary].join(`
+`) };
+}
+async function saveText(db, id, projectId2, root, record4, probe, call) {
+  const prepared = await prepare2(db, id, projectId2, root, record4, probe, call);
+  const text3 = await inTransaction(db, async (trx) => {
+    const v = await validate2(trx, id, projectId2, root, record4, prepared, call);
+    if (v.errors.length)
+      throw new Error(`The record is not valid:
+${v.errors.map((e) => `  ${e}`).join(`
+`)}`);
+    const { saved, changed: changed2 } = await v.write(trx);
+    await finishRun(trx, v.run.id);
     return [
       ...saved.active.map((k) => `✓ ${k} active`),
       ...saved.superseded.map((k) => `✓ ${k} superseded`),
       ...saved.candidates.map((c) => `△ ${c.key} candidate: ${c.why}`),
       ...saved.quarantined.map((q) => `△ ${q} quarantined`),
       ...saved.anchorProblems.map((a) => `△ ${a}`),
-      ...notes.map((n) => `△ ${n}`),
-      ...lines,
+      ...v.ops === null ? v.problems.map((n) => `△ ${n}`) : [],
+      ...changed2.map((c) => `✓ ${c}`),
       "✓ saved"
     ].join(`
 `);
@@ -50598,7 +50646,7 @@ server.registerTool("record_context", {
 }));
 server.registerTool("record_check", {
   title: "Check a record",
-  description: "Checks a record against the run's retained text without saving it.",
+  description: "Checks a record by running the save in a transaction that rolls back: it refuses what record_save would refuse and says what would become of each record (would be active, would stay a candidate, would be superseded), writing nothing.",
   inputSchema: exports_external.object({ run: RUN, record: RECORD, cwd: CWD }).strict(),
   annotations: READ
 }, async (a, extra) => tool(async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sphica",
-  "version": "0.6.36",
+  "version": "0.6.37",
   "description": "Records Claude Code and Codex sessions on your machine and keeps past implementation and decisions, with their sources, for your agent to find.",
   "license": "MIT",
   "type": "module",

package/skills/glean/SKILL.md

@@ -49,8 +49,9 @@ read tools `search` and `read`. Pass the repository root as `cwd` to every tool.
    the owner's message that quotes it
 5. **Read**: `record_context` with the run: the owner's messages in this session with their refs. When a page ends with
    `call record_context with after: "s<N>"`, call it again with that `after`
-6. **Check**: `record_check` with the run and the record below. Fix errors and check again. A note to ask the owner for a source means
-   step 2 is not done
+6. **Check**: `record_check` with the run and the record below. It runs the save in a transaction that rolls back, so it refuses what the
+   save would refuse and lists what would change (`would be active`, `would: <change>`) without writing it. Fix errors and check again. A
+   note to ask the owner for a source means step 2 is not done
 7. **Save**: `record_save`. **Report** what changed, copying save's lines
 
 ## The record

package/skills/harvest/SKILL.md

@@ -37,7 +37,8 @@ as `cwd` to every tool.
    sources an earlier harvest already looked at: what they decided may already be saved, so search before recording it again. Read all of it before writing:
    when a page ends with `call record_context with after: "s<N>"`, call it again with that `after`, until the last page
 4. **Check**: `record_check` with the run and the record as `record`. The shape and fields are trace's ([../trace/SKILL.md](../trace/SKILL.md),
-   "The record"), with `work` left out. Keys are saved as `harvest:<number>/<key>`. Fix and check again until there are no errors.
+   "The record"), with `work` left out. Keys are saved as `harvest:<number>/<key>`. As in trace, check runs the save in a transaction that
+   rolls back and says what would become of each record (`would be active`, ...). Fix and check again until there are no errors.
    A file the pull request touched may have moved since: on a warning that a path is not in the working tree, give the commit that holds it,
    or anchor where the code is now
 5. **Save**: `record_save` with the same run and record

package/skills/trace/SKILL.md

@@ -41,7 +41,9 @@ Everything goes through Sphica's `record` MCP server (its tools are `trace_pendi
    the last page (the one with the live records). Saving marks as looked at only the messages you were shown and those you quote; the
    rest stay pending.
    Use `search` and `read` to look at older records this session may replace
-4. **Check**: `record_check` with the run and the record below as `record`. Errors refuse the save; fix and check again. Warnings say what will be
+4. **Check**: `record_check` with the run and the record below as `record`. It runs the save in a transaction that rolls back, so nothing is
+   written: it refuses what the save would refuse, and says what would become of each record (`would be active`, `would stay a candidate` with
+   the reason, `would be superseded`, `would be quarantined`). Errors refuse the save; fix and check again. Warnings say what will be
    left out, quarantined, or kept as a candidate, and why. An anchor warning (a path not in the working tree, with near paths; a directory; a
    symbol not in the file) means fix the anchor and check again; keep it only when you know it is right
 5. **Save**: `record_save` with the same run and record. A run saves once