undo#

Moves every ref an operation of op_log moved back to what it named before, by compare-and-swap in one transaction: all of them or none. A ref moved since stops it (E_CAS_MISMATCH, nothing written: undo the later operations first); an undo run again is a replay (already_applied). Changesets are never removed.

Metadata

Since: 0.1.0
Mutates: yes
Identity required: yes
Envelope op: undo
Cli command: swarmops op undo
Request type: UndoReq
Annotations: {"destructiveHint":true,"idempotentHint":true,"openWorldHint":false,"readOnlyHint":false}
Max result chars: null
CLI command: swarmops op undo

Input schema#

arguments is a UndoReq: swarmops schema UndoReq prints the type. A field the type does not know is ignored.

Field	Type	Required	Default	Description
`op`	integer	yes		The operation to undo: its `op` in the operation log.

JSON Schema#

As tools/list gives it: each $ref replaced by its definition, so that it stands alone.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "description": "`undo` (CLI `op undo`): restore every ref an operation moved to what it named before, by\ncompare-and-swap, in one transaction: all of them or none. Changesets are never removed.",
  "properties": {
    "op": {
      "description": "The operation to undo: its `op` in the operation log.",
      "format": "uint64",
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [
    "op"
  ],
  "title": "UndoReq",
  "type": "object"
}

Annotations#

It moves or deletes refs by compare-and-swap, changing what they name. Run again with the same arguments, it finds them as it asked (already_applied) or not as it expected (E_CAS_MISMATCH), and changes nothing more.

Annotation	Value	Meaning
`destructiveHint`	`true`	True: a tool that changes the store may overwrite or delete what is there, not only add to it.
`idempotentHint`	`true`	True: calling it again with the same arguments changes nothing more.
`openWorldHint`	`false`	True: it reaches beyond a closed set of things. Every tool here stays inside the store.
`readOnlyHint`	`false`	True: the tool does not change its environment, the store.

Its entry in tools/list carries no _meta.

CLI command#

swarmops op undo runs the same operation and prints the same envelope.

Examples#

{
  "id": 20,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "op": 6
    },
    "name": "undo"
  }
}

{
  "id": 20,
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "text": "{\"ok\":true,\"op\":\"undo\",\"api\":1,\"result\":{\"undone\":6,\"op\":7,\"ref_moves\":[{\"name\":\"release/v1\",\"new\":\"[c1]\",\"actor\":\"agent/worker-17\",\"at\":\"[at]\"}],\"already_applied\":false},\"meta\":{\"repo\":\"[tmp]/store\",\"elapsed_ms\":\"[elapsed_ms]\",\"resolved\":{},\"auth\":\"trust\"}}",
        "type": "text"
      }
    ],
    "isError": false,
    "structuredContent": {
      "api": 1,
      "meta": {
        "auth": "trust",
        "elapsed_ms": "[elapsed_ms]",
        "repo": "[tmp]/store",
        "resolved": {}
      },
      "ok": true,
      "op": "undo",
      "result": {
        "already_applied": false,
        "op": 7,
        "ref_moves": [
          {
            "actor": "agent/worker-17",
            "at": "[at]",
            "name": "release/v1",
            "new": "[c1]"
          }
        ],
        "undone": 6
      }
    }
  }
}

The server ran as swarmops mcp --repo [tmp]/store --as agent/worker-17, after initialize. Recorded by the MCP tests. A name in square brackets, such as [tmp] or [c1], stands for what differs from run to run: the test's temporary directory, an id, a time, the version.

Details#

op is an operation's number from op_log. It moves every ref that operation moved back to what it named before, by compare-and-swap in one transaction: all of them or none. A ref moved since stops it (E_CAS_MISMATCH, nothing written): undo the later operations first. An undo run again is a replay (already_applied). Changesets are never removed.

Return information#

A tool result: the envelope, whose op is undo, as structuredContent and again as the text of its one content block. isError is true exactly when the envelope's ok is false. On success the envelope's result is what swarmops op undo returns.

Errors#

A failed call is a tool result with isError: true; the envelope's error.code is one of the error codes.

E_INVALID_ARG: arguments that do not fit UndoReq, a field named twice among them included, or that break one of the server's own rules.
E_IDENTITY_REQUIRED: the server runs with no identity.
E_NOT_A_REPO: the server's store is not there; the server serves on.
E_INTERNAL: the operation panicked, a bug.

Then the errors of the operation, as swarmops op undo lists them.