synartesis 0.6.12 → 0.6.13

package/CHANGELOG.md

@@ -2,6 +2,174 @@
 
 What changed, and why it mattered. Dates are release dates.
 
+## 0.6.13 — 2026-09-14
+
+Four things, all of them from one comment by a stranger on Reddit who had
+clearly built something like this before. Every one was real, and none of them
+would have announced itself.
+
+### Security
+
+- **The one remaining advisory is gone.** `esbuild` reached `pnpm audit`
+  through vite, in the renderer build only -- never in anything published, and
+  `--prod` was already clean. Pinned anyway, the same way as 0.6.12's three:
+  a low advisory nobody can reach is still a line of output that trains you to
+  ignore the tool.
+
+- **A server upgrade could silently invalidate the policy written for it.** A
+  policy is a claim about what a tool does, anchored to the tool's name -- and
+  a name is a weak anchor. A server can keep `write_file` and change what it
+  takes. The policy still says reversible, the snapshot still reads a field
+  that has moved, and the before-image captured no longer matches the write.
+  Nothing failed. The undo was produced later, on request, confidently, and was
+  wrong, which is worse than having no undo because somebody acted on it.
+
+  Startup already checked that the tools a policy names exist. It did not check
+  that they still have the shape the policy was written for.
+
+  A manifest may now pin that shape:
+
+  ```yaml
+  pins:
+    fs:
+      write_file: "sha256:ce17c85e8a58835..."
+  ```
+
+  `synartesis pin` prints the block for the servers you actually have. With it
+  in place, a tool whose shape has moved stops the proxy at startup and names
+  both fingerprints, instead of being quietly trusted.
+
+  It prints rather than rewriting the manifest: pinning is a person vouching
+  for what a tool does today, and a command that edited the policy for them
+  would let that happen with nobody reading it.
+
+  Pinning is per server and all-or-nothing. No pins means no checking, so every
+  manifest written before this keeps working. Any pins means that server is
+  checked in full -- a half-pinned server is the worst of both, because it
+  reads as protected and is not. Tools no policy matches need no pin; they are
+  already fail-closed as irreversible and gated.
+
+### Fixed
+
+- **Forward calls carried no idempotency key.** The key was minted for every
+  action and stored, and it was presented on the inverse -- but not on the
+  call going out. So a write that timed out in flight left the agent free to
+  retry, with nothing telling the server that the retry was the same intention.
+  Two side effects would sit behind one journal row, and undo would reverse one
+  of them and report success.
+
+  The key now rides out with the forward call as well, merged into `_meta`
+  rather than replacing it, so a client's own `progressToken` survives. It
+  remains advisory -- a server that ignores it gives no protection, which is
+  why the journal's state transitions are still the real guard.
+
+- **A compensable action could be undone over somebody's work, silently.** An
+  action whose undo is a compensating call -- a create offset by a delete --
+  has no before-image, because the thing did not exist before the call. So
+  there was nothing for undo to compare against: it compensated regardless and
+  marked the step `[unverified]`.
+
+  A policy may now declare a `verify` read, resolved *after* the call so it can
+  name a resource the call itself created:
+
+  ```yaml
+  verify:
+    tool: "memory.open_nodes"
+    args: { names: "$result.entities[].name" }
+  ```
+
+  Undo then halts on drift the way it does everywhere else. Measured against
+  the real `@modelcontextprotocol/server-memory`: an agent creates an entity, a
+  person adds an observation to it by hand, and undo is asked for. Before, it
+  deleted the entity, took the hand-written observation with it, and reported
+  `rolled_back`. Now it halts, prints the added line, and writes nothing.
+
+  It is consulted only where no read exists already, so it can never displace a
+  working pre-read with a differently shaped one -- which would leave the
+  post-state and the snapshot describing different things and make every later
+  comparison meaningless.
+
+  `memory.create_entities` gets one. Deleting an entity takes its observations
+  and relations with it, which is exactly the case worth refusing.
+
+- **Nothing said which policies had actually been run against a real server.**
+  Three of the four that ship were written against the live server; `github`
+  never has been, and its own header has said so in plain words since it was
+  written. Nothing in the code read that header. `check` did not mention it,
+  `install` adopted the policy without a word, and a held GitHub call looked
+  exactly as confident as a held filesystem one.
+
+  A server may now state it, and the four that ship do:
+
+  ```yaml
+  servers:
+    gh:
+      command: github-mcp-server
+      provenance: documented   # or: live
+  ```
+
+  Surfaced by `check`, by the proxy at every start -- before it connects, since
+  the untried adapter is the one whose server is least likely to be installed
+  -- and by `install` at the moment the policy is adopted. `init` writes the
+  claim into the manifest it generates, or the warning would go quiet exactly
+  when the policy starts being used.
+
+  Absent means no claim either way, which is right for a policy somebody wrote
+  themselves. All three states are printed: if silence meant "fine", an
+  ungraded policy and a known-untested one would look identical from here.
+
+- **A call somebody approved was reported as one they had refused.** When an
+  agent retries a held call, the approval moves onto the row that actually
+  runs and the original is retired -- stored as `denied`, with an error saying
+  where its approval went. `labelFor` existed to keep that out of the UI, and
+  three readers did not use it. `show` printed "denied by <name>" beside a call
+  that person had just approved and which had gone through; its footer counted
+  the row as a refusal; and `show --live` called it "never applied (denied)".
+  All three now go through `labelFor`, and the live view says what actually
+  happened: "its approval moved to the call that ran".
+
+- **Arguments are summarised for a terminal again.** A value with a newline in
+  it was printed verbatim, so writing two lines to a file broke the timeline
+  and left the second at column zero. A value over 48 characters was reduced to
+  a byte count -- which for a path is the one summary that answers nothing, so
+  every row of a filesystem session read `path 120 B` and named no file.
+  Values are flattened to one line, a long path keeps its end, and long prose
+  keeps its size, because the tail of a file tells you nothing.
+
+  The undo plan used raw truncated json for the same job and cut off mid-path;
+  it uses the same summary now, so a step reads
+  `would call fs.write_file path …/work/ledger.csv  content north,412800`.
+
+- **`synartesis close` treated a tidy journal as a usage error.** Nothing left
+  open is the ordinary state and the thing somebody runs the command to check.
+  It answered with exit 2 and forty lines of unrelated help. It now says
+  "nothing is open" and succeeds.
+
+  Separately, "there is no run to act on" and "no run matches <id>" stopped
+  reciting every command. They are facts about the journal rather than about
+  what was typed, and the command list buried the one sentence that mattered.
+  A mistyped command still gets the full list.
+
+- **`-v`, `version` and `help` answer.** `--version` worked and `synartesis
+  version` said "unknown command", which is a riddle rather than an answer.
+
+- **Listing sessions read every action of every run.** It needs a count and
+  three status tallies per run, and it was getting them by materialising every
+  row -- snapshots, results and inverses included, which is the bulk of the
+  table. So the cost of listing sessions grew with the size of the data those
+  sessions had touched rather than with how many there were. It is one grouped
+  query now, over a covering index. Measured on forty runs of five hundred
+  actions with two-kilobyte snapshots, a hundred-megabyte journal: **76ms to
+  2ms**.
+
+  The index is added the same way as the two in 0.6.12 and for the same reason:
+  no row changes, no meaning changes, and an older build opening the same file
+  neither notices nor cares.
+
+- `synartesis check` now says whether anything is pinned, either way. Silence
+  when nothing was would have left the safer state and the unchecked one
+  looking identical.
+
 ## 0.6.12 — 2026-09-13
 
 ### Security

package/README.md

@@ -179,6 +179,103 @@ answers. `l` in the screen does the same.
 If you decide the recorded value is the one worth keeping, `undo --force` prints
 every line it would write over and stops; `--force --yes` goes ahead.
 
+## What each policy has actually been tested against
+
+A policy that has met a real server and one written from its documentation are
+not the same kind of claim, and the difference only shows up at the moment
+somebody needs undo to work. So a policy can say which it is:
+
+```yaml
+servers:
+  gh:
+    command: github-mcp-server
+    provenance: documented   # or: live
+```
+
+Of the four that ship, three say `live` — they were written against the real
+server and corrected where it disagreed with its own docs. **`github` says
+`documented`**: it has never been run against a real account, and its own header
+has always said so. Now `check` says it, the proxy says it at every start, and
+`install` says it at the moment the policy is adopted — rather than leaving it in
+a file for you to find afterwards.
+
+Absent means no claim either way, which is the right default for a policy you
+wrote yourself: the tool has no business grading your work. Nothing is inferred
+from silence, and all three states are printed, because if silence meant "fine"
+then an ungraded policy and a known-untested one would look identical.
+
+## Undoing something that was never read first
+
+Most undo rides on a pre-read: the value before the write is captured, and
+before putting it back, undo reads the world again and refuses if it has moved.
+
+A compensable action has no such read. `create_entities` makes something that
+did not exist a moment earlier, so there is nothing to capture — it has a
+compensating action instead, a delete that offsets the create. Which means undo
+had nothing to compare against and compensated regardless. If you had added to
+that record in the meantime, the delete took your work with it and the run
+reported success.
+
+A policy can now declare a read used only for that check:
+
+```yaml
+- match: "memory.create_entities"
+  class: compensable
+  inverse:
+    tool: "memory.delete_entities"
+    args: { entityNames: "$result.entities[].name" }
+  verify:
+    tool: "memory.open_nodes"
+    args: { names: "$result.entities[].name" }
+```
+
+It is resolved *after* the call, so `$result` is available and it can name a
+resource the call itself created. Undo then halts on drift the same way it does
+everywhere else, and shows you the diff.
+
+It is consulted only where there is no read already, so it can never displace a
+working pre-read with a differently shaped one — which would make the post-state
+and the snapshot incomparable and every later comparison meaningless.
+
+## When the server changes underneath you
+
+A policy is a claim about what a tool does, and a tool's name is a weak place to
+anchor that claim. A server upgrade can keep `write_file` and add an argument to
+it. The policy still says reversible, the snapshot still reads a field that has
+moved, and the before-image captured no longer matches the write. Nothing fails.
+The undo is produced on request, confidently, and is wrong — which is worse than
+having no undo, because somebody acted on it.
+
+So you can pin the shape a tool had when you wrote its policy:
+
+```bash
+synartesis pin
+```
+
+It prints a block. Paste it into the manifest:
+
+```yaml
+pins:
+  fs:
+    write_file: "sha256:ce17c85e8a5883552a11555f9b893de497fadab965a5c7935c0cb8f3c55b91d6"
+    edit_file: "sha256:88459ef670b139a12a3e0335ae0a4584dd892f60f45f565b545e1004d7565dd5"
+```
+
+From then on, a tool whose shape has moved stops the proxy at startup and names
+both fingerprints, instead of quietly serving the old policy. Re-run `pin` when
+you have looked at what changed and decided the policy still holds.
+
+It prints rather than writes on purpose: pinning is you vouching for what a tool
+does today, and a command that silently rewrote your policy would let that happen
+without anyone reading it.
+
+Pinning is per server and all-or-nothing. A server with no pins is not checked,
+so every manifest written before this existed keeps working. A server with any
+pins is checked in full — a half-pinned server is the worst of both, because it
+reads as protected and is not. Tools that no policy matches need no pin: they are
+already fail-closed as irreversible and gated, so there is no classification for a
+schema change to corrupt.
+
 ## Commands
 
 `synartesis desktop` opens [the window](#the-desktop-window), and says where to
@@ -190,6 +287,7 @@ get it if it is not installed.
 | `install` / `uninstall` / `status` | Cover the clients on this machine, put them back, say what is covered |
 | `init <server> -- <cmd>` | Introspect a server and draft a manifest |
 | `check` | Load a manifest and verify it against the servers it names |
+| `pin` | Print the `pins:` block for the servers you have now |
 | `list` | Every recorded session |
 | `show <id>` | One session's timeline, with the undo for each step |
 | `show <id> --live` | The same, plus what has changed in the world since |
@@ -218,8 +316,11 @@ cannot start a process:** see the [user guide](docs/synartesis-user-guide.md).
 
 - **It cannot un-send what has been seen.** An email that has been read, a
   posted message, a file deleted with no backup. This is why the gate exists.
-- **Compensable actions cannot be checked for drift.** They declare no pre-read,
-  so undo compensates them and marks them `[unverified]`.
+- **Compensable actions can only be checked for drift if their policy declares a
+  `verify` read.** They have no pre-read — the thing they made did not exist
+  before the call — so without one, undo compensates them and marks them
+  `[unverified]`. With one, the resource is read back after the write and undo
+  halts rather than compensating over somebody else's edit.
 - **Undo halts on uncertainty, and steps over the merely permanent.** Drift, an
   unknown outcome, or a failed reversing call stop it. An action that simply
   cannot be undone is reported and left in place while everything else is