{
  "service": "dawn",
  "contract": "2026-09-19",
  "doc": "The operation table of ulab-standard/API.md for the dawn surface: one row per surface verb and one per operational route of OPERATIONS.md, rendered from api.Operations. Kind is the grant kind an operation needs (read, publish, declare, provision) or operational. Parameters travel in the HTTP query (a path as a repeated `path` parameter) and as members of a socket envelope's params by the same names. Surface calls carry a Dawn-Auth header over HTTP and an auth member in a socket envelope; operational routes carry none. The prose contract is SURFACE.md. Drift tests compare generated descriptions, routes, schemas and embedded files; semantic conformance checks observable behavior against that contract.",
  "surface": "SURFACE.md",
  "bindings": {
    "http": "HTTP.md",
    "ws": "WS.md"
  },
  "operations": [
    {
      "name": "livez",
      "kind": "operational",
      "doc": "the process is up and can answer; never 503; empty checks",
      "params": [],
      "response": "Health",
      "errors": [],
      "http": {
        "method": "GET",
        "path": "/livez"
      },
      "ws": false
    },
    {
      "name": "health",
      "kind": "operational",
      "doc": "the service can serve its contract: journal and bytes answer; 503 otherwise",
      "params": [],
      "response": "Health",
      "errors": [],
      "http": {
        "method": "GET",
        "path": "/healthz"
      },
      "ws": false
    },
    {
      "name": "describe",
      "kind": "operational",
      "doc": "who this is, which contract, build, identity, bindings, operations, refusals and served files",
      "params": [],
      "response": "Describe",
      "errors": [],
      "http": {
        "method": "GET",
        "path": "/describe"
      },
      "ws": false
    },
    {
      "name": "describe_file",
      "kind": "operational",
      "doc": "one committed contract file, verbatim, with its media type",
      "params": [
        {
          "name": "file",
          "kind": "string",
          "required": true,
          "doc": "a file name listed by describe"
        }
      ],
      "errors": [
        "not_found"
      ],
      "http": {
        "method": "GET",
        "path": "/describe/{file...}"
      },
      "ws": false
    },
    {
      "name": "resolve",
      "kind": "read",
      "grant": "read",
      "doc": "the space at a path, or null when the path is unoccupied",
      "params": [
        {
          "name": "path",
          "kind": "strings",
          "required": true,
          "doc": "the path, one label per entry, below the world"
        }
      ],
      "response": "ResolveResult",
      "errors": [
        "not_found",
        "unavailable"
      ],
      "http": {
        "method": "GET",
        "path": "/v1/resolve"
      },
      "ws": true
    },
    {
      "name": "children",
      "kind": "read",
      "grant": "read",
      "doc": "the readable children of a space at a fixed cutoff, in creation order; without a path, the world's",
      "params": [
        {
          "name": "path",
          "kind": "strings",
          "required": false,
          "doc": "the path, one label per entry, below the world; omitted selects the world itself"
        },
        {
          "name": "through",
          "kind": "int",
          "required": false,
          "doc": "a cutoff of the selected journal; omitted captures its committed cutoff once; a continuation resends it"
        },
        {
          "name": "cursor",
          "kind": "string",
          "required": false,
          "doc": "a continuation cursor from the previous page"
        },
        {
          "name": "limit",
          "kind": "int",
          "required": false,
          "doc": "page size, 1..128, default 64"
        }
      ],
      "response": "ChildrenPage",
      "errors": [
        "not_found",
        "invalid_cursor",
        "limit_exceeded",
        "unavailable"
      ],
      "http": {
        "method": "GET",
        "path": "/v1/children"
      },
      "ws": true
    },
    {
      "name": "entries",
      "kind": "read",
      "grant": "read",
      "doc": "a journal's entries over a fixed prefix, ascending, one page at a time",
      "params": [
        {
          "name": "path",
          "kind": "strings",
          "required": true,
          "doc": "the path, one label per entry, below the world"
        },
        {
          "name": "after",
          "kind": "int",
          "required": false,
          "doc": "the position a page continues after; omitted starts at the beginning"
        },
        {
          "name": "through",
          "kind": "int",
          "required": false,
          "doc": "a cutoff of the selected journal; omitted captures its committed cutoff once; a continuation resends it"
        },
        {
          "name": "limit",
          "kind": "int",
          "required": false,
          "doc": "page size, 1..128, default 64"
        }
      ],
      "response": "EntriesPage",
      "errors": [
        "not_found",
        "invalid_cursor",
        "limit_exceeded",
        "unavailable"
      ],
      "http": {
        "method": "GET",
        "path": "/v1/entries"
      },
      "ws": true
    },
    {
      "name": "get",
      "kind": "read",
      "grant": "read",
      "doc": "one exact occurrence by its reference, read at a valid covering cutoff; the reference is resolved to its actual path before authorization",
      "params": [
        {
          "name": "root_id",
          "kind": "string",
          "required": true,
          "doc": "the Journal root the occurrence lies in"
        },
        {
          "name": "space_id",
          "kind": "string",
          "required": true,
          "doc": "the exact space the occurrence lies in"
        },
        {
          "name": "position",
          "kind": "int",
          "required": true,
          "doc": "the occurrence's position in its journal"
        }
      ],
      "response": "RecordRead",
      "errors": [
        "not_found",
        "unavailable"
      ],
      "http": {
        "method": "GET",
        "path": "/v1/get"
      },
      "ws": true
    },
    {
      "name": "fetch",
      "kind": "stream",
      "grant": "read",
      "doc": "the bytes of retained content the path's journal names, streamed and verified before completion",
      "params": [
        {
          "name": "path",
          "kind": "strings",
          "required": true,
          "doc": "the path, one label per entry, below the world"
        },
        {
          "name": "bytes",
          "kind": "string",
          "required": true,
          "doc": "the hash of the retained bytes"
        }
      ],
      "response": "bytes",
      "errors": [
        "not_found",
        "unresolved",
        "unavailable"
      ],
      "http": {
        "method": "GET",
        "path": "/v1/fetch"
      },
      "ws": false
    },
    {
      "name": "snapshot",
      "kind": "read",
      "grant": "read",
      "doc": "capture an explicit manifest of the scope and its selected descendants, retained in bytes and cited by digest",
      "params": [
        {
          "name": "path",
          "kind": "strings",
          "required": false,
          "doc": "the path, one label per entry, below the world; omitted selects the world itself"
        },
        {
          "name": "depth",
          "kind": "int",
          "required": false,
          "doc": "how many levels below the scope to select; omitted selects every descendant"
        }
      ],
      "response": "Snapshot",
      "errors": [
        "not_found",
        "limit_exceeded",
        "unavailable"
      ],
      "http": {
        "method": "GET",
        "path": "/v1/snapshot"
      },
      "ws": true
    },
    {
      "name": "retain",
      "kind": "mutation",
      "grant": "publish",
      "doc": "retain bytes under a declared interpretation; nothing is named yet; verified against the hash before the artifact is reported",
      "params": [
        {
          "name": "path",
          "kind": "strings",
          "required": true,
          "doc": "the path, one label per entry, below the world"
        },
        {
          "name": "type",
          "kind": "string",
          "required": true,
          "doc": "the interpretation hash the bytes are retained under"
        }
      ],
      "request": "bytes",
      "response": "RetainResult",
      "errors": [
        "invalid_record",
        "unavailable"
      ],
      "http": {
        "method": "PUT",
        "path": "/v1/retain"
      },
      "ws": false
    },
    {
      "name": "publish",
      "kind": "mutation",
      "grant": "publish",
      "doc": "publish a record at a path: validate, retain, append the record fact to the leaf journal with its admission provenance, recovering an earlier admission of the same request",
      "params": [],
      "request": "PublishRequest",
      "response": "PublishResult",
      "errors": [
        "not_found",
        "exists",
        "conflict",
        "idempotency_mismatch",
        "invalid_record",
        "unresolved",
        "structural",
        "limit_exceeded",
        "unavailable"
      ],
      "http": {
        "method": "POST",
        "path": "/v1/publish"
      },
      "ws": true
    },
    {
      "name": "create_artifact",
      "kind": "mutation",
      "grant": "publish",
      "doc": "create an artifact space with its one immutable content fact and its declarations space",
      "params": [],
      "request": "CreateArtifactRequest",
      "response": "ArtifactResult",
      "errors": [
        "not_found",
        "exists",
        "conflict",
        "idempotency_mismatch",
        "invalid_record",
        "unresolved",
        "structural",
        "limit_exceeded",
        "unavailable"
      ],
      "http": {
        "method": "POST",
        "path": "/v1/artifacts"
      },
      "ws": true
    },
    {
      "name": "declare",
      "kind": "mutation",
      "grant": "declare",
      "doc": "append an immutable attributed declaration about an artifact's exact content, retaining the signed envelope and its frame and recovering the first admission on retry",
      "params": [],
      "request": "DeclareRequest",
      "response": "DeclareResult",
      "errors": [
        "not_found",
        "exists",
        "conflict",
        "idempotency_mismatch",
        "invalid_record",
        "unresolved",
        "structural",
        "limit_exceeded",
        "unavailable"
      ],
      "http": {
        "method": "POST",
        "path": "/v1/declarations"
      },
      "ws": true
    },
    {
      "name": "compose",
      "kind": "mutation",
      "grant": "publish",
      "doc": "compose a view from exact occurrence selections and publish it under views/",
      "params": [],
      "request": "ComposeRequest",
      "response": "PublishResult",
      "errors": [
        "not_found",
        "exists",
        "conflict",
        "idempotency_mismatch",
        "invalid_record",
        "unresolved",
        "structural",
        "limit_exceeded",
        "unavailable"
      ],
      "http": {
        "method": "POST",
        "path": "/v1/compose"
      },
      "ws": true
    },
    {
      "name": "apply",
      "kind": "mutation",
      "grant": "publish",
      "doc": "run a configured tool on a valuation of its input roles and record the application: admit the attempt, create the output artifacts, append the application batch and attest the run; recover an earlier admission of the same request",
      "params": [],
      "request": "ApplyRequest",
      "response": "ApplyResult",
      "errors": [
        "not_found",
        "exists",
        "conflict",
        "idempotency_mismatch",
        "invalid_record",
        "unresolved",
        "structural",
        "limit_exceeded",
        "unavailable"
      ],
      "http": {
        "method": "POST",
        "path": "/v1/applications"
      },
      "ws": true
    },
    {
      "name": "query",
      "kind": "read",
      "grant": "read",
      "doc": "records of a view matching filters, with the view, coverage and limits; four outcomes kept apart",
      "params": [],
      "request": "QueryRequest",
      "response": "QueryResult",
      "errors": [
        "not_found",
        "unresolved",
        "invalid_cursor",
        "unavailable"
      ],
      "http": {
        "method": "POST",
        "path": "/v1/query"
      },
      "ws": true
    },
    {
      "name": "explain",
      "kind": "read",
      "grant": "read",
      "doc": "an admitted assertion at a view: which declaration defined it, which selection adopted it, what disagreed",
      "params": [],
      "request": "ExplainRequest",
      "response": "ExplainResult",
      "errors": [
        "not_found",
        "unresolved",
        "unavailable"
      ],
      "http": {
        "method": "POST",
        "path": "/v1/explain"
      },
      "ws": true
    },
    {
      "name": "create_project",
      "kind": "mutation",
      "grant": "provision",
      "doc": "create a project space with its organizing spaces",
      "params": [],
      "request": "CreateProjectRequest",
      "response": "SpaceResult",
      "errors": [
        "not_found",
        "exists",
        "conflict",
        "idempotency_mismatch",
        "structural",
        "limit_exceeded",
        "unavailable"
      ],
      "http": {
        "method": "POST",
        "path": "/v1/projects"
      },
      "ws": true
    },
    {
      "name": "provision_worker",
      "kind": "mutation",
      "grant": "provision",
      "doc": "create a worker space under its project, write its state record and issue its grants to the workspace's public key",
      "params": [],
      "request": "ProvisionWorkerRequest",
      "response": "ProvisionWorkerResult",
      "errors": [
        "not_found",
        "exists",
        "conflict",
        "idempotency_mismatch",
        "structural",
        "limit_exceeded",
        "unavailable"
      ],
      "http": {
        "method": "POST",
        "path": "/v1/workers"
      },
      "ws": true
    },
    {
      "name": "retire_worker",
      "kind": "mutation",
      "grant": "provision",
      "doc": "record that a worker's window is closed",
      "params": [],
      "request": "RetireWorkerRequest",
      "response": "PublishResult",
      "errors": [
        "not_found",
        "exists",
        "conflict",
        "idempotency_mismatch",
        "structural",
        "limit_exceeded",
        "unavailable"
      ],
      "http": {
        "method": "POST",
        "path": "/v1/workers/retire"
      },
      "ws": true
    },
    {
      "name": "create_campaign",
      "kind": "mutation",
      "grant": "provision",
      "doc": "create a campaign space over a project with its state record",
      "params": [],
      "request": "CreateCampaignRequest",
      "response": "PublishResult",
      "errors": [
        "not_found",
        "exists",
        "conflict",
        "idempotency_mismatch",
        "structural",
        "limit_exceeded",
        "unavailable"
      ],
      "http": {
        "method": "POST",
        "path": "/v1/campaigns"
      },
      "ws": true
    },
    {
      "name": "assign",
      "kind": "mutation",
      "grant": "provision",
      "doc": "publish an assignment: pinned inputs and intended outputs for a worker",
      "params": [],
      "request": "AssignRequest",
      "response": "PublishResult",
      "errors": [
        "unresolved",
        "not_found",
        "exists",
        "conflict",
        "idempotency_mismatch",
        "structural",
        "limit_exceeded",
        "unavailable"
      ],
      "http": {
        "method": "POST",
        "path": "/v1/assignments"
      },
      "ws": true
    },
    {
      "name": "export",
      "kind": "read",
      "grant": "provision",
      "doc": "a complete traversal of the world or a subtree: every selected journal prefix and child observation, retained in bytes and cited by digest, with explicit incomplete coverage",
      "params": [
        {
          "name": "path",
          "kind": "strings",
          "required": false,
          "doc": "the path, one label per entry, below the world; omitted selects the world itself"
        },
        {
          "name": "cursor",
          "kind": "string",
          "required": false,
          "doc": "a continuation cursor from the previous page"
        }
      ],
      "response": "Export",
      "errors": [
        "not_found",
        "invalid_cursor",
        "limit_exceeded",
        "unavailable"
      ],
      "http": {
        "method": "GET",
        "path": "/v1/export"
      },
      "ws": true
    },
    {
      "name": "subscribe",
      "kind": "session",
      "grant": "read",
      "doc": "open a subscription over a scope: from the reply on, every journal under it that advances is reported once with its new cutoff, advances of one journal superseding each other, with a gap for a journal whose cutoff could not be kept",
      "params": [],
      "request": "SubscribeRequest",
      "response": "SubscribeResult",
      "errors": [
        "not_found",
        "invalid",
        "limit_exceeded",
        "unavailable"
      ],
      "ws": true
    },
    {
      "name": "unsubscribe",
      "kind": "session",
      "grant": "read",
      "doc": "close a subscription this connection opened; its authority is ownership of the subscription, never a path grant, because it confers and discloses nothing",
      "params": [
        {
          "name": "subscription",
          "kind": "string",
          "required": true,
          "doc": "the subscription this connection opened"
        }
      ],
      "response": "UnsubscribeResult",
      "errors": [
        "not_found"
      ],
      "ws": true
    }
  ],
  "refusals": [
    {
      "name": "not_found",
      "http": 404,
      "meaning": "the path, space, occurrence, record or file is not here; shared with Journal"
    },
    {
      "name": "exists",
      "http": 409,
      "meaning": "a child of that key already exists under the parent, or the record identity is occupied; shared with Journal"
    },
    {
      "name": "conflict",
      "http": 409,
      "meaning": "an expected cutoff did not hold; carries the expected and actual cutoffs; shared with Journal"
    },
    {
      "name": "idempotency_mismatch",
      "http": 409,
      "meaning": "the operation ID was accepted before with a different semantic request; shared with Journal"
    },
    {
      "name": "invalid",
      "http": 400,
      "meaning": "a value is outside its grammar, limit or structural rule, or a cutoff is inside a batch or in the future"
    },
    {
      "name": "invalid_cursor",
      "http": 400,
      "meaning": "a malformed cursor, or one of another enumeration, traversal or query"
    },
    {
      "name": "limit_exceeded",
      "http": 413,
      "meaning": "a declared resource bound would be exceeded: a value, a batch, a page, a manifest or a continuation; shared with Journal"
    },
    {
      "name": "unavailable",
      "http": 503,
      "meaning": "a backend, a selected journal or a required observation cannot currently be served; recovery data that cannot be read is unavailable, never absent"
    },
    {
      "name": "unverified",
      "http": 401,
      "meaning": "the signature, freshness, audience or key admissibility failed; nothing was evaluated"
    },
    {
      "name": "denied",
      "http": 403,
      "meaning": "no grant chain reaches the principal for this kind on this path; whether the path exists is not revealed"
    },
    {
      "name": "invalid_record",
      "http": 400,
      "meaning": "the record does not validate against its interpretation profile, or an occurrence violates dawn-facts-v2; carries the field"
    },
    {
      "name": "unresolved",
      "http": 409,
      "meaning": "a record or request refers to content or an occurrence that does not resolve; carries the reference"
    },
    {
      "name": "structural",
      "http": 400,
      "meaning": "a user label collides with the layout's structural labels at that position, or a write targets a protected space"
    }
  ]
}