synartesis 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 What changed, and why it mattered. Dates are release dates.
 
+## 0.8.0 — 2026-09-16
+
+### Added
+
+- **`expect: absent`, and `move_file` becomes undoable.** A pre-read normally
+  captures what a call is about to replace, so a read that finds nothing means
+  there is nothing to put back. For a few calls that is exactly backwards:
+  moving a file onto a free path is undone by moving it back, and it is finding
+  *something* there that puts the call beyond undo, because one inverse cannot
+  both move your file back and restore what it landed on.
+
+  Both halves were measured before anything was written. Declared plainly
+  `reversible`, the safe move came back `partial` with the file still moved —
+  the trivially reversible case was the one that could not be undone — and the
+  dangerous one came back `rolled_back` with the overwritten file gone, which
+  is the confident wrong undo this exists to prevent. `expect: absent` on the
+  snapshot swaps the two: finding nothing is reversible and the inverse runs;
+  finding something is held for a person and recorded with **no inverse**, so
+  undo says it cannot be undone rather than putting half of it back.
+
+  The shipped filesystem policy uses it, so moving a file to a fresh path is
+  now an ordinary undoable action instead of an approval prompt. A policy that
+  declares it on a non-`reversible` rule, on a `verify` read, or with an
+  inverse reading `$snapshot.` — which can never resolve, since nothing is
+  captured — is refused at load.
+
+  Worth recording: this server's own description of `move_file` says "If the
+  destination exists, the operation will fail." It does not; it renames over
+  the top, because that is what `rename(2)` does. Taking the documentation at
+  its word would have made the rule unconditionally reversible and the
+  overwrite both unrecoverable and unremarked.
+
 ## 0.7.0 — 2026-09-16
 
 A pass over everything, after an audit of the desktop app, the core and the

package/README.md

@@ -156,7 +156,15 @@ Every tool gets one of four classifications, written down in a manifest:
 
 A tool your manifest does not mention is treated as `irreversible`. That is
 deliberate: silently forwarding an unknown destructive call is the one failure
-worth avoiding most.
+worth avoiding most. `synartesis check` names them, so you meet that decision
+before your agent does.
+
+A few calls are reversible only when nothing is in the way — moving a file onto
+a free path is undone by moving it back, moving it onto an existing file
+destroys what was there. For those, `expect: absent` on the pre-read swaps the
+two: finding nothing is the reversible case, finding something is held for a
+person and recorded with no inverse, so undo says it cannot be undone rather
+than putting half of it back and calling that success.
 
 ## Has anybody touched it since?
 

package/dist/{chunk-FXSKWMNG.js → chunk-O3QDPYEL.js}

@@ -1155,7 +1155,11 @@ var templateValue = z2.lazy(
 var callTemplate = z2.strictObject({
   tool: z2.string().min(1),
   args: z2.record(z2.string(), templateValue).default({}),
-  absent_when: z2.union([z2.string().min(1), z2.array(z2.string().min(1)).min(1)]).optional()
+  absent_when: z2.union([z2.string().min(1), z2.array(z2.string().min(1)).min(1)]).optional(),
+  // Only `absent` for now. `present` would mean "refuse unless something is
+  // already here", which is a different feature nobody has asked for, and a
+  // value with no meaning behind it is worse than one that is missing.
+  expect: z2.literal("absent").optional()
 });
 var toolPolicy = z2.strictObject({
   match: z2.string().min(1),
@@ -1304,12 +1308,25 @@ function validate(source, manifest) {
     if (policy.class === "readonly" && policy.snapshot !== void 0) {
       source.fail([...path, "snapshot"], "a readonly tool must not declare a snapshot");
     }
+    const expectsAbsent = policy.snapshot?.expect === "absent";
+    if (policy.verify?.expect !== void 0) {
+      source.fail(
+        [...path, "verify", "expect"],
+        "expect belongs on a snapshot; a verify read runs after the call, when there is nothing left to expect"
+      );
+    }
+    if (expectsAbsent && policy.class !== "reversible") {
+      source.fail(
+        [...path, "snapshot", "expect"],
+        `expect: absent says this call is reversible exactly when the read finds nothing, which only means something for a reversible tool, not a ${policy.class} one`
+      );
+    }
     if (policy.snapshot !== void 0) {
       checkCall(source, [...path, "snapshot"], policy.snapshot, servers, ["$."]);
     }
     if (policy.inverse !== void 0) {
       const allowed = ["$.", "$result."];
-      if (policy.snapshot !== void 0) {
+      if (policy.snapshot !== void 0 && !expectsAbsent) {
         allowed.push("$snapshot.");
       }
       checkCall(source, [...path, "inverse"], policy.inverse, servers, allowed);
@@ -1329,7 +1346,8 @@ function withGate(policy) {
     args: call.args,
     ...call.absent_when === void 0 ? {} : {
       absentWhen: typeof call.absent_when === "string" ? [call.absent_when] : [...call.absent_when]
-    }
+    },
+    ...call.expect === void 0 ? {} : { expect: call.expect }
   });
   const gate = policy.gate ?? (policy.class === "irreversible" ? "always" : "never");
   return {
@@ -1993,4 +2011,4 @@ export {
   observeState,
   connectStdioUpstream
 };
-//# sourceMappingURL=chunk-FXSKWMNG.js.map
+//# sourceMappingURL=chunk-O3QDPYEL.js.map

package/dist/cli.js

@@ -38,7 +38,7 @@ import {
   verifyAgainstServers,
   warnUntested,
   wasRefused
-} from "./chunk-FXSKWMNG.js";
+} from "./chunk-O3QDPYEL.js";
 import {
   DriftConflict,
   ManifestError,

package/dist/proxy.js

@@ -25,7 +25,7 @@ import {
   verifyAgainstServers,
   warnUntested,
   withIdempotencyKey
-} from "./chunk-FXSKWMNG.js";
+} from "./chunk-O3QDPYEL.js";
 import {
   SnapshotError,
   UpstreamError,
@@ -709,18 +709,39 @@ function createProxyServer(options) {
         let snapshot;
         let verify;
         let probe;
-        let missingPriorState;
+        let noWayBack;
+        let foundNothing = false;
+        const expectsAbsent = policy.snapshot?.expect === "absent";
         if (policy.snapshot !== void 0) {
           try {
             verify = planRead(policy.snapshot, { args });
             probe = verify;
             snapshot = await runRead(router, verify, extra.signal);
-            journal.attachSnapshot(pending.actionId, snapshot);
+            if (expectsAbsent) {
+              noWayBack = {
+                asked: `something is already there, so this cannot be undone \u2014 putting back what this call moves would leave nothing where the old contents were`,
+                recorded: `the pre-read expected nothing and found something, so this call overwrote it and no single inverse can put both back`
+              };
+              verify = void 0;
+            } else {
+              journal.attachSnapshot(pending.actionId, snapshot);
+            }
           } catch (error) {
             const reason = describe(error);
             if (error instanceof SnapshotError && error.absent) {
-              missingPriorState = reason;
-              verify = void 0;
+              foundNothing = true;
+              if (expectsAbsent) {
+                log?.debug(
+                  { seq: pending.seq, tool: route.tool },
+                  "pre-read found nothing, which is what makes this reversible"
+                );
+              } else {
+                noWayBack = {
+                  asked: `nothing was captured to restore, so this cannot be undone \u2014 the read said: ${reason}`,
+                  recorded: `no prior state existed, so there is nothing to restore: ${reason}`
+                };
+                verify = void 0;
+              }
             } else {
               journal.markFailed(pending.actionId, reason);
               log?.error(
@@ -734,8 +755,8 @@ function createProxyServer(options) {
             }
           }
         }
-        const priorState = probe === void 0 || missingPriorState !== void 0 ? { present: false } : { present: true, value: snapshot };
-        if (missingPriorState !== void 0 && !askedAlready) {
+        const priorState = probe === void 0 || foundNothing ? { present: false } : { present: true, value: snapshot };
+        if (noWayBack !== void 0 && !askedAlready) {
           const standing = journal.findApproval({
             server: route.upstream.name,
             tool: route.tool,
@@ -743,18 +764,14 @@ function createProxyServer(options) {
             notBefore: new Date(Date.now() - APPROVAL_WINDOW_MS).toISOString()
           });
           if (standing === void 0) {
-            await decide(
-              `nothing was captured to restore, so this cannot be undone \u2014 the read said: ${missingPriorState}`
-            );
+            await decide(noWayBack.asked);
           } else if (journal.adoptApproval(pending.actionId, standing)) {
             log?.info(
               { action: pending.actionId, by: standing.approvedBy, from: standing.runId },
               "proceeding on a standing approval"
             );
           } else {
-            await decide(
-              `nothing was captured to restore, so this cannot be undone \u2014 the read said: ${missingPriorState}`
-            );
+            await decide(noWayBack.asked);
           }
         }
         const forwarded = {
@@ -800,13 +817,11 @@ function createProxyServer(options) {
           if (inferred !== void 0) {
             warnings.push(inferred);
           }
-          if (missingPriorState !== void 0) {
-            warnings.push(
-              `no prior state existed, so there is nothing to restore: ${missingPriorState}`
-            );
+          if (noWayBack !== void 0) {
+            warnings.push(noWayBack.recorded);
           }
           let inverse;
-          if (policy.inverse !== void 0 && missingPriorState === void 0) {
+          if (policy.inverse !== void 0 && noWayBack === void 0) {
             try {
               inverse = planInverse(policy.inverse, context);
             } catch (error) {
@@ -857,7 +872,7 @@ function createProxyServer(options) {
               const recovered = recoverInverse(
                 policy,
                 { args, snapshot },
-                missingPriorState !== void 0
+                noWayBack !== void 0
               );
               journal.markApplied(pending.actionId, {
                 result: void 0,

package/manifests/filesystem.yaml

@@ -88,16 +88,46 @@ tools:
         path: "$.path"
         content: "$snapshot.content"
 
-  # Only reversible when the destination did not exist. Moving onto a file
-  # that did overwrites it, and moving back afterwards restores the source and
-  # leaves nothing where the destination's contents were: undo reports success
-  # while the file it destroyed stays destroyed. There is no pre-read that
-  # would tell the two cases apart -- a snapshot that finds nothing is how this
-  # policy says "cannot be undone", which is backwards here, since finding
-  # nothing is the safe case. So it asks.
+  # Reversible exactly when the destination did not exist, which is what
+  # `expect: absent` says.
+  #
+  # Moving onto a path where nothing is, is undone by moving the file back:
+  # the state this replaces is absence, and moving it off restores absence
+  # exactly. Moving onto a file that does exist overwrites it, and one inverse
+  # cannot both move the file back and restore what it landed on -- undo would
+  # report success over a file it had destroyed.
+  #
+  # Both cases were gated before, because the machinery read "the pre-read
+  # found nothing" as "there is nothing to put back" -- true of a write, and
+  # precisely backwards here, where finding nothing is the safe case. Measured
+  # both ways against the real server: as a plain reversible rule the safe move
+  # came back `partial` with the file still moved, and the dangerous one came
+  # back `rolled_back` with the overwritten file gone.
+  #
+  # And the pre-read is load-bearing, not belt and braces. This server's own
+  # description of move_file says "If the destination exists, the operation
+  # will fail" -- it does not. It renames over the top, silently, because
+  # that is what rename(2) does on POSIX. Taking the description at its word
+  # would have made this rule unconditionally reversible and the overwrite
+  # unrecoverable and unremarked. tests/expect-absent.test.ts pins the real
+  # behaviour so a version that starts matching its documentation is a
+  # failing test rather than a surprise.
   - match: "fs.move_file"
-    class: irreversible
-    gate: always
+    class: reversible
+    snapshot:
+      tool: "fs.read_text_file"
+      args:
+        path: "$.destination"
+      # Same reasoning as the two writes above: anything that is not absence
+      # is a failed read, not an empty destination, and a destination that
+      # exists but cannot be read must not be treated as a free space.
+      absent_when: ["ENOENT", "no such file"]
+      expect: absent
+    inverse:
+      tool: "fs.move_file"
+      args:
+        source: "$.destination"
+        destination: "$.source"
 
   # No rmdir exists on this server, so a directory once created stays.
   - match: "fs.create_directory"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synartesis",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "An undo layer for AI agents.",
   "type": "module",
   "private": false,