dawn · management surface
Bindings
| Primary | http |
|---|---|
| HTTP | prefix / |
Operations
| Name | Kind | Binding | Request | Response | Parameters | Refusals |
|---|---|---|---|---|---|---|
livez | operational | GET /livez |
Health | invalid | ||
health | operational | GET /healthz |
Health | invalid | ||
describe | operational | GET /describe |
Describe | invalid | ||
describe_file | operational | GET /describe/{file...} |
file: string (required) | invalid, not_found |
Refusals
| Code | HTTP | Meaning |
|---|---|---|
invalid | 400 | Queries and request bodies are not accepted. |
not_found | 404 | No such management route or contract file. |
method_not_allowed | 405 | The route accepts GET only. |
Files served
- HTTP.md
- SURFACE.md
- openapi.json
- operations.json
- schema/Describe.schema.json
- schema/Error.schema.json
- schema/Health.schema.json
SURFACE.md
Dawn management surface
Status: implemented contract, 2026-09-12.
This surface observes the Dawn process. It is independent of the authenticated world operations in the core surface. Management access is determined by reachability of its separately configured listener. It carries no worker identity, grants, login operation or implicit authority to mutate a world. Deployments choose its network exposure; authentication is not added here.
Operations
| Operation | Result |
|---|---|
| livez | Process liveness, without contacting dependencies |
| health | Journal and Bytes readiness checks and available world identity |
| describe | Management service, surface, contract, build, identity, binding, operations, refusals and file inventory |
| describe_file | Exact embedded bytes of a named management contract file |
All operations are reads. They create no world records, grants or login offers. Cancellation leaves persistent state unchanged. Health is an observation made during the request, not a guarantee about a later world operation. Liveness does not establish dependency readiness. Identity contains only public world/root identifiers; no root key or environment configuration is exposed.
The health shape is the shared ULab health envelope. Its contract identifies
this management surface. The descriptor's surface is management. The listed
operations and files describe only this surface, with independent generated
schemas and operation table. Core operations and Archon login are unreachable
through this listener. Existing core health and description endpoints remain
available for compatibility and continue to describe the core contract.
Refusals and limits
invalid refuses input outside the binding grammar; not_found identifies an
unknown operation or contract file; method_not_allowed identifies a known
operation used with the wrong method. These are observations, never mutations.
Health dependency checks have a ten-second request deadline and report failing
checks when a dependency is unavailable. There is no WebSocket management binding.
See HTTP.md, operations.json and openapi.json. The Go operation table and types generate machine descriptions, held to these documents and served bytes by drift tests.
HTTP.md
Dawn management HTTP binding
This listener carries SURFACE.md, contract 2026-09-12, independently
from the authenticated operation listener. Every response, including refusals,
sets Ulab-Service: dawn, Ulab-Surface: management and
Ulab-Contract: 2026-09-12. No Dawn-Auth carriage or login is required or processed.
These native routes are relative to the management listener root. Deployment
mounts the listener under /api/management/ and strips /api/management before
forwarding. For example, an externally routed health request is
GET /api/management/healthz. The operations listener is separately mounted
under /api/operations/; management clients receive their own explicit base URL.
| Method | Route | Success |
|---|---|---|
| GET | /livez | 200 Health, empty checks, no dependency calls |
| GET | /healthz | 200 Health when ready; 503 with the same shape when failing |
| GET | /describe | 200 Describe for the management surface only |
| GET | /describe/{file...} | 200 exact embedded bytes of a listed file |
Only GET is accepted. Known routes with other methods return 405
method_not_allowed and Allow: GET; unknown routes return 404 not_found.
Every route rejects any query component, including empty, repeated or unknown
parameters, and rejects any request body (400 invalid). A trailing bare ?
is also refused. Request paths are exact: no redirect, path cleaning or fallback
to core dispatch is performed. A file path must exactly match the descriptor's
inventory; traversal paths and unknown files return 404.
Health and descriptions use application/json. Files use application/json
for JSON and text/markdown; charset=utf-8 for Markdown, with Content-Length.
Every JSON refusal has { "error": "code", "message": "explanation" } and may
have a details object. No request body is interpreted as a command.
The server gives dependency health checks a ten-second deadline. A cancelled
request can stop observation but has no persistent effect.
Example calls against the standalone management listener:
curl http://127.0.0.1:8094/healthz
curl http://127.0.0.1:8094/describe
curl http://127.0.0.1:8094/describe/SURFACE.md
curl 'http://127.0.0.1:8094/healthz?unexpected=1' # 400 invalid
curl http://127.0.0.1:8094/v1/children # 404 not_found
Schemas
schema/Describe.schema.json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$defs": {
"BindingHTTP": {
"properties": {
"prefix": {
"type": "string"
}
},
"type": "object",
"required": [
"prefix"
]
},
"BindingWS": {
"properties": {
"path": {
"type": "string"
},
"subprotocol": {
"type": "string"
}
},
"type": "object",
"required": [
"path",
"subprotocol"
]
},
"Bindings": {
"properties": {
"primary": {
"type": "string"
},
"http": {
"oneOf": [
{
"$ref": "#/$defs/BindingHTTP"
},
{
"type": "null"
}
]
},
"ws": {
"oneOf": [
{
"$ref": "#/$defs/BindingWS"
},
{
"type": "null"
}
]
}
},
"type": "object",
"required": [
"primary"
]
},
"Build": {
"properties": {
"revision": {
"type": "string"
},
"dirty": {
"type": "boolean"
},
"go": {
"type": "string"
}
},
"type": "object",
"required": [
"revision",
"dirty",
"go"
]
},
"HTTPBinding": {
"properties": {
"method": {
"type": "string"
},
"path": {
"type": "string"
}
},
"type": "object",
"required": [
"method",
"path"
]
},
"Identity": {
"properties": {
"root_id": {
"type": "string"
},
"world_space_id": {
"type": "string"
},
"journal_instance_id": {
"type": "string"
},
"world": {
"type": "string"
}
},
"type": "object",
"required": [
"root_id",
"world_space_id",
"journal_instance_id"
]
},
"Operation": {
"properties": {
"name": {
"type": "string"
},
"kind": {
"type": "string"
},
"grant": {
"type": "string"
},
"doc": {
"type": "string"
},
"params": {
"items": {
"$ref": "#/$defs/Param"
},
"type": "array"
},
"request": {
"type": "string"
},
"response": {
"type": "string"
},
"errors": {
"items": {
"type": "string"
},
"type": "array"
},
"http": {
"$ref": "#/$defs/HTTPBinding"
},
"ws": {
"type": "boolean"
}
},
"type": "object",
"required": [
"name",
"kind",
"doc",
"params",
"errors",
"ws"
]
},
"Param": {
"properties": {
"name": {
"type": "string"
},
"kind": {
"type": "string"
},
"required": {
"type": "boolean"
},
"doc": {
"type": "string"
}
},
"type": "object",
"required": [
"name",
"kind",
"required",
"doc"
]
},
"Refusal": {
"properties": {
"name": {
"type": "string"
},
"http": {
"type": "integer"
},
"meaning": {
"type": "string"
}
},
"type": "object",
"required": [
"name",
"http",
"meaning"
]
}
},
"properties": {
"service": {
"type": "string"
},
"surface": {
"type": "string"
},
"contract": {
"type": "string"
},
"build": {
"$ref": "#/$defs/Build"
},
"identity": {
"oneOf": [
{
"$ref": "#/$defs/Identity"
},
{
"type": "null"
}
]
},
"bindings": {
"$ref": "#/$defs/Bindings"
},
"operations": {
"items": {
"$ref": "#/$defs/Operation"
},
"type": "array"
},
"refusals": {
"items": {
"$ref": "#/$defs/Refusal"
},
"type": "array"
},
"files": {
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object",
"required": [
"service",
"surface",
"contract",
"build",
"bindings",
"operations",
"refusals",
"files"
],
"title": "Describe"
}
schema/Error.schema.json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"error": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object"
}
},
"type": "object",
"required": [
"error",
"message"
],
"title": "Error"
}
schema/Health.schema.json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$defs": {
"Build": {
"properties": {
"revision": {
"type": "string"
},
"dirty": {
"type": "boolean"
},
"go": {
"type": "string"
}
},
"type": "object",
"required": [
"revision",
"dirty",
"go"
]
},
"Check": {
"properties": {
"name": {
"type": "string"
},
"status": {
"type": "string"
},
"detail": {
"type": "string"
}
},
"type": "object",
"required": [
"name",
"status",
"detail"
]
},
"Identity": {
"properties": {
"root_id": {
"type": "string"
},
"world_space_id": {
"type": "string"
},
"journal_instance_id": {
"type": "string"
},
"world": {
"type": "string"
}
},
"type": "object",
"required": [
"root_id",
"world_space_id",
"journal_instance_id"
]
}
},
"properties": {
"status": {
"type": "string"
},
"service": {
"type": "string"
},
"contract": {
"type": "string"
},
"build": {
"$ref": "#/$defs/Build"
},
"time": {
"type": "string"
},
"checks": {
"items": {
"$ref": "#/$defs/Check"
},
"type": "array"
},
"identity": {
"oneOf": [
{
"$ref": "#/$defs/Identity"
},
{
"type": "null"
}
]
}
},
"type": "object",
"required": [
"status",
"service",
"contract",
"build",
"time",
"checks"
],
"title": "Health"
}
OpenAPI
openapi.json (raw)
{
"components": {
"schemas": {
"BindingHTTP": {
"properties": {
"prefix": {
"type": "string"
}
},
"required": [
"prefix"
],
"type": "object"
},
"BindingWS": {
"properties": {
"path": {
"type": "string"
},
"subprotocol": {
"type": "string"
}
},
"required": [
"path",
"subprotocol"
],
"type": "object"
},
"Bindings": {
"properties": {
"http": {
"oneOf": [
{
"$ref": "#/components/schemas/BindingHTTP"
},
{
"type": "null"
}
]
},
"primary": {
"type": "string"
},
"ws": {
"oneOf": [
{
"$ref": "#/components/schemas/BindingWS"
},
{
"type": "null"
}
]
}
},
"required": [
"primary"
],
"type": "object"
},
"Build": {
"properties": {
"dirty": {
"type": "boolean"
},
"go": {
"type": "string"
},
"revision": {
"type": "string"
}
},
"required": [
"revision",
"dirty",
"go"
],
"type": "object"
},
"Check": {
"properties": {
"detail": {
"type": "string"
},
"name": {
"type": "string"
},
"status": {
"type": "string"
}
},
"required": [
"name",
"status",
"detail"
],
"type": "object"
},
"Describe": {
"properties": {
"bindings": {
"$ref": "#/components/schemas/Bindings"
},
"build": {
"$ref": "#/components/schemas/Build"
},
"contract": {
"type": "string"
},
"files": {
"items": {
"type": "string"
},
"type": "array"
},
"identity": {
"oneOf": [
{
"$ref": "#/components/schemas/Identity"
},
{
"type": "null"
}
]
},
"operations": {
"items": {
"$ref": "#/components/schemas/Operation"
},
"type": "array"
},
"refusals": {
"items": {
"$ref": "#/components/schemas/Refusal"
},
"type": "array"
},
"service": {
"type": "string"
},
"surface": {
"type": "string"
}
},
"required": [
"service",
"surface",
"contract",
"build",
"bindings",
"operations",
"refusals",
"files"
],
"title": "Describe",
"type": "object"
},
"Error": {
"properties": {
"details": {
"type": "object"
},
"error": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error",
"message"
],
"title": "Error",
"type": "object"
},
"HTTPBinding": {
"properties": {
"method": {
"type": "string"
},
"path": {
"type": "string"
}
},
"required": [
"method",
"path"
],
"type": "object"
},
"Health": {
"properties": {
"build": {
"$ref": "#/components/schemas/Build"
},
"checks": {
"items": {
"$ref": "#/components/schemas/Check"
},
"type": "array"
},
"contract": {
"type": "string"
},
"identity": {
"oneOf": [
{
"$ref": "#/components/schemas/Identity"
},
{
"type": "null"
}
]
},
"service": {
"type": "string"
},
"status": {
"type": "string"
},
"time": {
"type": "string"
}
},
"required": [
"status",
"service",
"contract",
"build",
"time",
"checks"
],
"title": "Health",
"type": "object"
},
"Identity": {
"properties": {
"journal_instance_id": {
"type": "string"
},
"root_id": {
"type": "string"
},
"world": {
"type": "string"
},
"world_space_id": {
"type": "string"
}
},
"required": [
"root_id",
"world_space_id",
"journal_instance_id"
],
"type": "object"
},
"Operation": {
"properties": {
"doc": {
"type": "string"
},
"errors": {
"items": {
"type": "string"
},
"type": "array"
},
"grant": {
"type": "string"
},
"http": {
"$ref": "#/components/schemas/HTTPBinding"
},
"kind": {
"type": "string"
},
"name": {
"type": "string"
},
"params": {
"items": {
"$ref": "#/components/schemas/Param"
},
"type": "array"
},
"request": {
"type": "string"
},
"response": {
"type": "string"
},
"ws": {
"type": "boolean"
}
},
"required": [
"name",
"kind",
"doc",
"params",
"errors",
"ws"
],
"type": "object"
},
"Param": {
"properties": {
"doc": {
"type": "string"
},
"kind": {
"type": "string"
},
"name": {
"type": "string"
},
"required": {
"type": "boolean"
}
},
"required": [
"name",
"kind",
"required",
"doc"
],
"type": "object"
},
"Refusal": {
"properties": {
"http": {
"type": "integer"
},
"meaning": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"name",
"http",
"meaning"
],
"type": "object"
}
}
},
"info": {
"title": "Dawn management",
"version": "2026-09-12"
},
"openapi": "3.1.0",
"paths": {
"/describe": {
"get": {
"operationId": "describe",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Describe"
}
}
},
"description": "Successful observation.",
"headers": {
"Ulab-Contract": {
"schema": {
"const": "2026-09-12",
"type": "string"
}
},
"Ulab-Service": {
"schema": {
"const": "dawn",
"type": "string"
}
},
"Ulab-Surface": {
"schema": {
"const": "management",
"type": "string"
}
}
}
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "Queries and request bodies are not accepted.",
"headers": {
"Ulab-Contract": {
"schema": {
"const": "2026-09-12",
"type": "string"
}
},
"Ulab-Service": {
"schema": {
"const": "dawn",
"type": "string"
}
},
"Ulab-Surface": {
"schema": {
"const": "management",
"type": "string"
}
}
}
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "No such management route or contract file.",
"headers": {
"Ulab-Contract": {
"schema": {
"const": "2026-09-12",
"type": "string"
}
},
"Ulab-Service": {
"schema": {
"const": "dawn",
"type": "string"
}
},
"Ulab-Surface": {
"schema": {
"const": "management",
"type": "string"
}
}
}
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "The route accepts GET only.",
"headers": {
"Ulab-Contract": {
"schema": {
"const": "2026-09-12",
"type": "string"
}
},
"Ulab-Service": {
"schema": {
"const": "dawn",
"type": "string"
}
},
"Ulab-Surface": {
"schema": {
"const": "management",
"type": "string"
}
}
}
}
},
"summary": "Describe this management surface and its build."
}
},
"/describe/{file}": {
"get": {
"operationId": "describe_file",
"parameters": [
{
"in": "path",
"name": "file",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
},
"text/markdown": {
"schema": {
"type": "string"
}
}
},
"description": "Exact embedded contract file bytes.",
"headers": {
"Ulab-Contract": {
"schema": {
"const": "2026-09-12",
"type": "string"
}
},
"Ulab-Service": {
"schema": {
"const": "dawn",
"type": "string"
}
},
"Ulab-Surface": {
"schema": {
"const": "management",
"type": "string"
}
}
}
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "Queries and request bodies are not accepted.",
"headers": {
"Ulab-Contract": {
"schema": {
"const": "2026-09-12",
"type": "string"
}
},
"Ulab-Service": {
"schema": {
"const": "dawn",
"type": "string"
}
},
"Ulab-Surface": {
"schema": {
"const": "management",
"type": "string"
}
}
}
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "No such management route or contract file.",
"headers": {
"Ulab-Contract": {
"schema": {
"const": "2026-09-12",
"type": "string"
}
},
"Ulab-Service": {
"schema": {
"const": "dawn",
"type": "string"
}
},
"Ulab-Surface": {
"schema": {
"const": "management",
"type": "string"
}
}
}
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "The route accepts GET only.",
"headers": {
"Ulab-Contract": {
"schema": {
"const": "2026-09-12",
"type": "string"
}
},
"Ulab-Service": {
"schema": {
"const": "dawn",
"type": "string"
}
},
"Ulab-Surface": {
"schema": {
"const": "management",
"type": "string"
}
}
}
}
},
"summary": "Read an embedded management contract file verbatim."
}
},
"/healthz": {
"get": {
"operationId": "health",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Health"
}
}
},
"description": "Successful observation.",
"headers": {
"Ulab-Contract": {
"schema": {
"const": "2026-09-12",
"type": "string"
}
},
"Ulab-Service": {
"schema": {
"const": "dawn",
"type": "string"
}
},
"Ulab-Surface": {
"schema": {
"const": "management",
"type": "string"
}
}
}
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "Queries and request bodies are not accepted.",
"headers": {
"Ulab-Contract": {
"schema": {
"const": "2026-09-12",
"type": "string"
}
},
"Ulab-Service": {
"schema": {
"const": "dawn",
"type": "string"
}
},
"Ulab-Surface": {
"schema": {
"const": "management",
"type": "string"
}
}
}
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "No such management route or contract file.",
"headers": {
"Ulab-Contract": {
"schema": {
"const": "2026-09-12",
"type": "string"
}
},
"Ulab-Service": {
"schema": {
"const": "dawn",
"type": "string"
}
},
"Ulab-Surface": {
"schema": {
"const": "management",
"type": "string"
}
}
}
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "The route accepts GET only.",
"headers": {
"Ulab-Contract": {
"schema": {
"const": "2026-09-12",
"type": "string"
}
},
"Ulab-Service": {
"schema": {
"const": "dawn",
"type": "string"
}
},
"Ulab-Surface": {
"schema": {
"const": "management",
"type": "string"
}
}
}
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Health"
}
}
},
"description": "One or more dependencies are failing.",
"headers": {
"Ulab-Contract": {
"schema": {
"const": "2026-09-12",
"type": "string"
}
},
"Ulab-Service": {
"schema": {
"const": "dawn",
"type": "string"
}
},
"Ulab-Surface": {
"schema": {
"const": "management",
"type": "string"
}
}
}
}
},
"summary": "Check the Journal and Bytes dependencies and report world identity."
}
},
"/livez": {
"get": {
"operationId": "livez",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Health"
}
}
},
"description": "Successful observation.",
"headers": {
"Ulab-Contract": {
"schema": {
"const": "2026-09-12",
"type": "string"
}
},
"Ulab-Service": {
"schema": {
"const": "dawn",
"type": "string"
}
},
"Ulab-Surface": {
"schema": {
"const": "management",
"type": "string"
}
}
}
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "Queries and request bodies are not accepted.",
"headers": {
"Ulab-Contract": {
"schema": {
"const": "2026-09-12",
"type": "string"
}
},
"Ulab-Service": {
"schema": {
"const": "dawn",
"type": "string"
}
},
"Ulab-Surface": {
"schema": {
"const": "management",
"type": "string"
}
}
}
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "No such management route or contract file.",
"headers": {
"Ulab-Contract": {
"schema": {
"const": "2026-09-12",
"type": "string"
}
},
"Ulab-Service": {
"schema": {
"const": "dawn",
"type": "string"
}
},
"Ulab-Surface": {
"schema": {
"const": "management",
"type": "string"
}
}
}
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "The route accepts GET only.",
"headers": {
"Ulab-Contract": {
"schema": {
"const": "2026-09-12",
"type": "string"
}
},
"Ulab-Service": {
"schema": {
"const": "dawn",
"type": "string"
}
},
"Ulab-Surface": {
"schema": {
"const": "management",
"type": "string"
}
}
}
}
},
"summary": "Check whether the process answers without checking dependencies."
}
}
}
}