{
  "format": 1,
  "part": "registry",
  "description": "The verbs and events every registry seat shares, written once so the four cannot drift (design 51, design 26). Who may call each verb is the holder's trusted config value listing its callers (ADR 0363's form), checked against the caller the tool runner proved.",
  "verbs": [
    {
      "name": "publish",
      "description": "Open a transfer, naming the artifact and the digest of every part; answers the digests the holder lacks, which the caller then sends by publish-part. A transfer already open answers the parts held, so a cut transfer goes on from there. With no parts and a version, the held digest is published under that version and nothing is stored (the trunk's claim).",
      "callers": "the build modules",
      "input": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "the package's, image's, bundle's or archive's name"
          },
          "version": {
            "type": "string",
            "description": "the version the builder gave it (design 51 *The versions*); empty for a bundle or archive published by its digest alone"
          },
          "kind": {
            "type": "string",
            "enum": [
              "package",
              "image",
              "bundle",
              "archive",
              "upstream"
            ],
            "description": "what it is"
          },
          "tag": {
            "type": "string",
            "description": "the tag it carries, for a tagged version"
          },
          "digest": {
            "type": "string",
            "description": "its digest, sha256:<hex> (a Go package's h1: hash beside it in the version's record)"
          },
          "fingerprint": {
            "type": "string",
            "description": "the build's fingerprint"
          },
          "commit": {
            "type": "string",
            "description": "the source commit it was built from"
          },
          "transfer": {
            "type": "string",
            "description": "the transfer's name, the caller's own; the same name opens the same transfer again"
          },
          "parts": {
            "type": "array",
            "items": {
              "$ref": "#/defs/Part"
            },
            "description": "every part's digest and size; none when the digest is already held"
          }
        },
        "required": [
          "transfer",
          "name",
          "kind",
          "digest"
        ]
      },
      "answer": {
        "type": "object",
        "properties": {
          "transfer": {
            "type": "string",
            "description": "the transfer"
          },
          "lacks": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "the digests of the parts the holder lacks, to send by publish-part"
          },
          "held": {
            "type": "boolean",
            "description": "the digest is held already: nothing to send; the outcome follows as an event"
          }
        },
        "required": [
          "transfer"
        ]
      },
      "optional": true
    },
    {
      "name": "publish-part",
      "description": "Send one chunk of one part of an open transfer; the last chunk of the last part ends the transfer, and the holder hashes what it received, asks builder_versions, stores it and says published or refused. A chunk's message stays under the bus's largest message (1 MiB), so at most 760 KiB of data, base64.",
      "callers": "the build modules, and only the proved caller that opened the transfer",
      "input": {
        "type": "object",
        "properties": {
          "transfer": {
            "type": "string",
            "description": "the transfer"
          },
          "part": {
            "type": "string",
            "description": "the part's digest"
          },
          "sequence": {
            "type": "integer",
            "description": "the chunk's place in its part, from 0"
          },
          "last": {
            "type": "boolean",
            "description": "this chunk is the part's last"
          },
          "data": {
            "type": "string",
            "description": "the chunk's bytes, base64 (at most 760 KiB before encoding)"
          }
        },
        "required": [
          "transfer",
          "part",
          "sequence",
          "last",
          "data"
        ]
      },
      "answer": {
        "type": "object",
        "properties": {
          "transfer": {
            "type": "string",
            "description": "the transfer"
          },
          "part": {
            "type": "string",
            "description": "the part"
          },
          "received": {
            "type": "integer",
            "description": "the chunks of the part held so far"
          },
          "complete": {
            "type": "boolean",
            "description": "the part is whole and its bytes match its digest"
          }
        },
        "required": [
          "transfer",
          "part"
        ]
      },
      "optional": true
    },
    {
      "name": "versions",
      "description": "The versions the seat holds of one name, newest first: each one's version, tag, digest, kind and when it was published.",
      "callers": "any caller whose role grants it",
      "input": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "the name"
          },
          "kind": {
            "type": "string",
            "description": "narrowed to one kind (optional)"
          }
        },
        "required": [
          "name"
        ]
      },
      "answer": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "the name"
          },
          "versions": {
            "type": "array",
            "items": {
              "$ref": "#/defs/Artifact"
            },
            "description": "newest first"
          }
        },
        "required": [
          "name",
          "versions"
        ]
      },
      "optional": true
    },
    {
      "name": "remove",
      "description": "Remove one tagged version; the holder refuses an untagged one but for the retention removal of a bundle, archive or copied base by the artifact sweep's holder. Every removal emits removed with its reason.",
      "callers": "the builder, for a tagged version; the artifact sweep's holder, for retention",
      "input": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "the name"
          },
          "version": {
            "type": "string",
            "description": "the version"
          },
          "tag": {
            "type": "string",
            "description": "the tag (for a tagged version)"
          },
          "digest": {
            "type": "string",
            "description": "the digest (for a bundle, archive or copied base)"
          },
          "reason": {
            "type": "string",
            "enum": [
              "tag-gone",
              "retention"
            ],
            "description": "why it goes"
          }
        },
        "required": [
          "name",
          "reason"
        ]
      },
      "answer": {
        "type": "object",
        "properties": {
          "removed": {
            "type": "boolean",
            "description": "it is gone"
          },
          "artifact": {
            "$ref": "#/defs/Artifact"
          }
        },
        "required": [
          "removed"
        ]
      },
      "optional": true
    }
  ],
  "events": [
    {
      "name": "published",
      "body": {
        "$ref": "#/defs/Outcome"
      }
    },
    {
      "name": "refused",
      "body": {
        "$ref": "#/defs/Outcome"
      }
    },
    {
      "name": "removed",
      "body": {
        "$ref": "#/defs/Outcome"
      }
    }
  ],
  "defs": {
    "Artifact": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "the package's, image's, bundle's or archive's name"
        },
        "version": {
          "type": "string",
          "description": "the version the builder gave it (design 51 *The versions*); empty for a bundle or archive published by its digest alone"
        },
        "kind": {
          "type": "string",
          "enum": [
            "package",
            "image",
            "bundle",
            "archive",
            "upstream"
          ],
          "description": "what it is"
        },
        "tag": {
          "type": "string",
          "description": "the tag it carries, for a tagged version"
        },
        "digest": {
          "type": "string",
          "description": "its digest, sha256:<hex> (a Go package's h1: hash beside it in the version's record)"
        },
        "fingerprint": {
          "type": "string",
          "description": "the build's fingerprint"
        },
        "commit": {
          "type": "string",
          "description": "the source commit it was built from"
        }
      },
      "required": [
        "name",
        "kind",
        "digest"
      ],
      "description": "one published thing, as every registry event and answer names it"
    },
    "Part": {
      "type": "object",
      "properties": {
        "digest": {
          "type": "string",
          "description": "the part's digest, sha256:<hex>: an image's layer or config, a package's file, a bundle's blob"
        },
        "size": {
          "type": "integer",
          "description": "its size in bytes"
        }
      },
      "required": [
        "digest",
        "size"
      ],
      "description": "one part of a transfer"
    },
    "Outcome": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "the package's, image's, bundle's or archive's name"
        },
        "version": {
          "type": "string",
          "description": "the version the builder gave it (design 51 *The versions*); empty for a bundle or archive published by its digest alone"
        },
        "kind": {
          "type": "string",
          "enum": [
            "package",
            "image",
            "bundle",
            "archive",
            "upstream"
          ],
          "description": "what it is"
        },
        "tag": {
          "type": "string",
          "description": "the tag it carries, for a tagged version"
        },
        "digest": {
          "type": "string",
          "description": "its digest, sha256:<hex> (a Go package's h1: hash beside it in the version's record)"
        },
        "fingerprint": {
          "type": "string",
          "description": "the build's fingerprint"
        },
        "commit": {
          "type": "string",
          "description": "the source commit it was built from"
        },
        "holder": {
          "type": "string",
          "description": "the module holding the seat that said it"
        },
        "transfer": {
          "type": "string",
          "description": "the transfer it ends, when it ended one"
        },
        "reference": {
          "type": "string",
          "description": "the reference the seat answers: <registry>/<module>/<artifact>@sha256:<digest>, or <name>@<version> for a package (ADR 0605 §9)"
        },
        "reason": {
          "type": "string",
          "description": "why: a refusal's cause, or a removal's (retention, tag-gone, by-hand)"
        }
      },
      "required": [
        "name",
        "kind",
        "digest",
        "holder"
      ],
      "description": "the body of published, refused and removed"
    }
  }
}