resolve_rev#

The full id of the changeset a revision names (a ref name, a full id or a unique prefix of 12 or more hex digits, then any ~N suffixes), resolved as every tool resolves one, and its kind: ref when the revision is exactly a ref's name, whose target moves with the ref, changeset otherwise. Its CLI command is swarmops resolve.

Metadata

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

Input schema#

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

Field	Type	Required	Default	Description
`rev`	string	yes		The revision to resolve. A revision as the caller wrote it, for the store to resolve: a ref name (`main`, `release/1.2`), a full 64-hex changeset id or a unique prefix of at least 12 hex digits, optionally followed by `~N` for the N-th first-parent ancestor.

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": "`resolve_rev` (CLI `resolve`): the changeset a revision names, as every operation resolves it.",
  "properties": {
    "rev": {
      "description": "The revision to resolve. A revision as the caller wrote it, for the store to resolve: a ref name (`main`,\n`release/1.2`), a full 64-hex changeset id or a unique prefix of at least 12 hex digits,\noptionally followed by `~N` for the N-th first-parent ancestor.",
      "type": "string"
    }
  },
  "required": [
    "rev"
  ],
  "title": "ResolveRevReq",
  "type": "object"
}

Annotations#

It only reads the store.

Annotation	Value	Meaning
`destructiveHint`	`false`	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`	`true`	True: the tool does not change its environment, the store.

Its entry in tools/list carries no _meta.

CLI command#

swarmops resolve runs the same operation and prints the same envelope.

Examples#

{
  "id": 7,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "rev": "main"
    },
    "name": "resolve_rev"
  }
}

{
  "id": 7,
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "text": "{\"ok\":true,\"op\":\"resolve_rev\",\"api\":1,\"result\":{\"id\":\"[c1]\",\"kind\":\"ref\"},\"meta\":{\"repo\":\"[tmp]/store\",\"elapsed_ms\":\"[elapsed_ms]\",\"resolved\":{\"main\":\"[c1]\"},\"auth\":\"trust\"}}",
        "type": "text"
      }
    ],
    "isError": false,
    "structuredContent": {
      "api": 1,
      "meta": {
        "auth": "trust",
        "elapsed_ms": "[elapsed_ms]",
        "repo": "[tmp]/store",
        "resolved": {
          "main": "[c1]"
        }
      },
      "ok": true,
      "op": "resolve_rev",
      "result": {
        "id": "[c1]",
        "kind": "ref"
      }
    }
  }
}

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#

rev is a ref name, a full 64-hex changeset id or a unique prefix of 12 or more hex digits, then any ~N suffixes, resolved as every tool resolves one. kind is ref when the revision is exactly a ref's name, whose target moves with the ref, and changeset otherwise.

Its id is the full id that ref_set and ref_delete take as expected_old, and commit as parent with advance: read the ref's head here, then name that id, so that the compare-and-swap protects what you read.

Return information#

A tool result: the envelope, whose op is resolve_rev, 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 resolve 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 ResolveRevReq, a field named twice among them included, or that break one of the server's own rules.
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 resolve lists them.