ref_delete#

Removes a ref by compare-and-swap, if it still holds expected_old, the full 64-hex changeset id it held when you read it; a ref name or a relative revision is refused, since it is read when the call runs instead of pinning the id you read, and so is an id prefix, which stops resolving once another changeset shares it.

Metadata

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

Input schema#

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

Field	Type	Required	Default	Description
`expected_old`	string	yes		The target the caller last saw, by its full changeset id; if the ref holds another, the delete fails with `E_CAS_MISMATCH`. A ref name or a relative revision is read from the store when the delete runs instead of pinning the id the caller read: the ref's own name always matches, so the compare-and-swap protects nothing, and `main~1` on `main` never matches. An id prefix pins the id the caller read only until another changeset shares it; then it is `E_AMBIGUOUS_ID`. `swarmops mcp` refuses all three (`E_INVALID_ARG`), and the CLI's `--expect` help warns against them.
`name`	string	yes		The ref.

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": "`ref delete`: remove a ref by compare-and-swap.",
  "properties": {
    "expected_old": {
      "description": "The target the caller last saw, by its full changeset id; if the ref holds another, the\ndelete fails with `E_CAS_MISMATCH`. A ref name or a relative revision is read from the\nstore when the delete runs instead of pinning the id the caller read: the ref's own name\nalways matches, so the compare-and-swap protects nothing, and `main~1` on `main` never\nmatches. An id prefix pins the id the caller read only until another changeset shares\nit; then it is `E_AMBIGUOUS_ID`. `swarmops mcp` refuses all three (`E_INVALID_ARG`), and\nthe CLI's `--expect` help warns against them.",
      "pattern": "^[0-9a-fA-F]{64}$",
      "type": "string"
    },
    "name": {
      "description": "The ref.",
      "type": "string"
    }
  },
  "required": [
    "name",
    "expected_old"
  ],
  "title": "RefDeleteReq",
  "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 ref delete runs the same operation and prints the same envelope.

Examples#

{
  "id": 18,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "expected_old": "[c1]",
      "name": "release/v1"
    },
    "name": "ref_delete"
  }
}

{
  "id": 18,
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "text": "{\"ok\":true,\"op\":\"ref_delete\",\"api\":1,\"result\":{\"name\":\"release/v1\",\"old\":\"[c1]\",\"already_applied\":false},\"meta\":{\"repo\":\"[tmp]/store\",\"elapsed_ms\":\"[elapsed_ms]\",\"resolved\":{\"[c1]\":\"[c1]\"},\"auth\":\"trust\"}}",
        "type": "text"
      }
    ],
    "isError": false,
    "structuredContent": {
      "api": 1,
      "meta": {
        "auth": "trust",
        "elapsed_ms": "[elapsed_ms]",
        "repo": "[tmp]/store",
        "resolved": {
          "[c1]": "[c1]"
        }
      },
      "ok": true,
      "op": "ref_delete",
      "result": {
        "already_applied": false,
        "name": "release/v1",
        "old": "[c1]"
      }
    }
  }
}

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#

expected_old is the full 64-hex changeset id the ref held when you read it; the server refuses a ref name, a relative revision and an id prefix there (E_INVALID_ARG), for the reasons ref_set gives. A ref that no longer holds it is E_CAS_MISMATCH, and the ref stays.

Return information#

A tool result: the envelope, whose op is ref_delete, 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 ref delete 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 RefDeleteReq, 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 ref delete lists them.