journal · 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 |
ManagementDescribe | invalid | ||
describe_file | operational | GET /describe/{file...} |
file: string (required) | invalid, not_found |
Refusals
| Code | HTTP | Meaning |
|---|---|---|
invalid | 400 | a management request has invalid shape |
not_found | 404 | the management route or requested contract file does not exist |
internal | 500 | an unexpected implementation failure occurred |
Files served
- HTTP.md
- SURFACE.md
- openapi.json
- operations.json
- schema/Error.schema.json
- schema/Health.schema.json
- schema/ManagementDescribe.schema.json
SURFACE.md
Journal management surface
Status: initial management contract, 2026-09-11.
This surface reports whether this Journal process can answer and whether its durable store is ready, and describes its own contract. It is separate from the journal operations contract. It adds no journal creation, append, read, listing, statistics or payload interpretation.
Operations
| Operation | Result |
|---|---|
livez |
Process liveness; the standard health envelope with empty checks |
health |
Store and stable instance identity readiness checks |
describe |
This management surface's identity, build and contract inventory |
describe_file |
One listed, embedded management contract file verbatim |
Liveness never reports dependency failure. Readiness reports failing status when the store cannot answer or its instance identity is invalid or changed. Neither operation reads journal payloads. Instance identity identifies the store lineage and supplies no caller authority.
The management listener is independently configurable and cannot dispatch the journal operations. Management is intended for a private network in deployment; network exposure is an explicit deployment decision. There is no authentication or authorization added by this surface.
Refusals use the existing JSON error envelope: invalid for request shape,
not_found for an absent management route or description file, and internal
for an unexpected failure. Readiness failure is a health envelope, not a
domain refusal. Generated descriptions derive from journal.ManagementOperations.
HTTP.md
Journal management over HTTP
Status: primary binding of the 2026-09-11 management surface.
ulab-journal serve --management-listen 127.0.0.1:8093 binds the independently
configured management listener. The operations listener defaults to port 8092.
The management address precedence is --management-listen, then
ULAB_JOURNAL_MANAGEMENT_LISTEN, then 127.0.0.1:8093.
Both listeners must bind before the service reports readiness. Failure of either
listener ends the service; shutdown drains both before closing durable storage.
Routes below are native listener paths. ULab deployment mounts management at
/api/management and operations at /api/operations, stripping each prefix
before forwarding to its selected listener. These external paths follow the
family contract.
Every response, including method and route errors, carries:
Ulab-Service: journal
Ulab-Surface: management
Ulab-Contract: 2026-09-11
| Operation | Method and route | Success |
|---|---|---|
livez |
GET /livez |
200; standard Health, empty checks |
health |
GET /healthz |
200; standard Health, store and identity checks |
describe |
GET /describe |
200; ManagementDescribe |
describe_file |
GET /describe/{file} |
200; listed contract bytes |
All requests accept no body and no query parameters. Invalid request shape
returns 400 invalid; a wrong method returns 405 invalid with Allow: GET.
Unknown paths, including every /v1 journal operation, return 404 not_found.
Readiness returns 503 with the same health envelope if a dependency check fails.
Unexpected failure returns 500 internal.
Health uses the standard operational envelope:
status, service, contract, build, UTC time, checks, and optional
identity.journal_instance_id. Liveness remains 200 even when the store fails.
Describe contains service: journal, surface: management, this contract date,
build identity, HTTP binding prefix /, management operations and refusals,
the served file inventory, and optional instance identity. It never advertises
the journal operations as management operations.
GET /describe/{file} serves only the names in its own description:
SURFACE.md, HTTP.md, operations.json, openapi.json, and
schema/<Type>.schema.json. Files are embedded at build time. Markdown uses
text/markdown; charset=utf-8; JSON uses application/json. No host file path
is read. The operations listener's existing neutral introspection routes remain
backwards compatible and continue describing the operations contract.
The separate SDK constructor is ulabjournal.NewManagement(endpoint).
CLI commands management-health, management-livez and management-describe
use --management-server, then ULAB_JOURNAL_MANAGEMENT_SERVER, then
http://127.0.0.1:8093. There is no fallback to the operations endpoint.
Schemas
schema/Error.schema.json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"error": {
"type": "string"
},
"message": {
"type": "string"
},
"details": {
"type": "object"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"error",
"message"
],
"title": "Error",
"description": "Error is a refusal."
}
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"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"revision",
"dirty",
"go"
],
"description": "Build identifies the binary: the revision it was built from, whether that tree was dirty, and the Go version."
},
"Check": {
"properties": {
"name": {
"type": "string"
},
"status": {
"type": "string",
"description": "ok | failing"
},
"detail": {
"type": "string"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"name",
"status",
"detail"
],
"description": "Check is one dependency the service needs in order to serve its contract."
},
"Identity": {
"properties": {
"root_id": {
"type": "string"
},
"root_space_id": {
"type": "string"
},
"journal_instance_id": {
"type": "string"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"root_id",
"root_space_id",
"journal_instance_id"
],
"description": "Identity is the service-specific identity member of the health envelope and the describe document: the logical root, its space, and the store lineage."
}
},
"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"
}
]
}
},
"additionalProperties": false,
"type": "object",
"required": [
"status",
"service",
"contract",
"build",
"time",
"checks"
],
"title": "Health",
"description": "Health is the envelope of GET /livez and GET /healthz."
}
schema/ManagementDescribe.schema.json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$defs": {
"BindingHTTP": {
"properties": {
"prefix": {
"type": "string"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"prefix"
],
"description": "BindingHTTP describes the HTTP binding in the describe document."
},
"Bindings": {
"properties": {
"primary": {
"type": "string"
},
"http": {
"oneOf": [
{
"$ref": "#/$defs/BindingHTTP"
},
{
"type": "null"
}
]
}
},
"additionalProperties": false,
"type": "object",
"required": [
"primary"
],
"description": "Bindings names the primary binding and describes each offered one."
},
"Build": {
"properties": {
"revision": {
"type": "string"
},
"dirty": {
"type": "boolean"
},
"go": {
"type": "string"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"revision",
"dirty",
"go"
],
"description": "Build identifies the binary: the revision it was built from, whether that tree was dirty, and the Go version."
},
"HTTPBinding": {
"properties": {
"method": {
"type": "string"
},
"path": {
"type": "string"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"method",
"path"
],
"description": "HTTPBinding carries one operation over HTTP."
},
"Identity": {
"properties": {
"root_id": {
"type": "string"
},
"root_space_id": {
"type": "string"
},
"journal_instance_id": {
"type": "string"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"root_id",
"root_space_id",
"journal_instance_id"
],
"description": "Identity is the service-specific identity member of the health envelope and the describe document: the logical root, its space, and the store lineage."
},
"Operation": {
"properties": {
"name": {
"type": "string"
},
"kind": {
"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"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"name",
"kind",
"doc",
"params",
"errors"
],
"description": "Operation is the shared operation table row consumed by bindings and clients."
},
"Param": {
"properties": {
"name": {
"type": "string"
},
"kind": {
"type": "string"
},
"required": {
"type": "boolean"
},
"repeated": {
"type": "boolean"
},
"doc": {
"type": "string"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"name",
"kind",
"required",
"repeated",
"doc"
],
"description": "Param is a named input outside a JSON body."
},
"Refusal": {
"properties": {
"name": {
"type": "string"
},
"http": {
"type": "integer"
},
"meaning": {
"type": "string"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"name",
"http",
"meaning"
],
"description": "Refusal is one row of the refusal table: the surface's name for it, the status the HTTP binding maps it to, and its one-line 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"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"service",
"surface",
"contract",
"build",
"bindings",
"operations",
"refusals",
"files"
],
"title": "ManagementDescribe",
"description": "ManagementDescribe describes only the selected management listener."
}
OpenAPI
openapi.json (raw)
{
"components": {
"schemas": {
"BindingHTTP": {
"additionalProperties": false,
"description": "BindingHTTP describes the HTTP binding in the describe document.",
"properties": {
"prefix": {
"type": "string"
}
},
"required": [
"prefix"
],
"type": "object"
},
"Bindings": {
"additionalProperties": false,
"description": "Bindings names the primary binding and describes each offered one.",
"properties": {
"http": {
"oneOf": [
{
"$ref": "#/components/schemas/BindingHTTP"
},
{
"type": "null"
}
]
},
"primary": {
"type": "string"
}
},
"required": [
"primary"
],
"type": "object"
},
"Build": {
"additionalProperties": false,
"description": "Build identifies the binary: the revision it was built from, whether that tree was dirty, and the Go version.",
"properties": {
"dirty": {
"type": "boolean"
},
"go": {
"type": "string"
},
"revision": {
"type": "string"
}
},
"required": [
"revision",
"dirty",
"go"
],
"type": "object"
},
"Check": {
"additionalProperties": false,
"description": "Check is one dependency the service needs in order to serve its contract.",
"properties": {
"detail": {
"type": "string"
},
"name": {
"type": "string"
},
"status": {
"description": "ok | failing",
"type": "string"
}
},
"required": [
"name",
"status",
"detail"
],
"type": "object"
},
"Error": {
"additionalProperties": false,
"description": "Error is a refusal.",
"properties": {
"details": {
"type": "object"
},
"error": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"error",
"message"
],
"title": "Error",
"type": "object"
},
"HTTPBinding": {
"additionalProperties": false,
"description": "HTTPBinding carries one operation over HTTP.",
"properties": {
"method": {
"type": "string"
},
"path": {
"type": "string"
}
},
"required": [
"method",
"path"
],
"type": "object"
},
"Health": {
"additionalProperties": false,
"description": "Health is the envelope of GET /livez and GET /healthz.",
"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": {
"additionalProperties": false,
"description": "Identity is the service-specific identity member of the health envelope and the describe document: the logical root, its space, and the store lineage.",
"properties": {
"journal_instance_id": {
"type": "string"
},
"root_id": {
"type": "string"
},
"root_space_id": {
"type": "string"
}
},
"required": [
"root_id",
"root_space_id",
"journal_instance_id"
],
"type": "object"
},
"ManagementDescribe": {
"additionalProperties": false,
"description": "ManagementDescribe describes only the selected management listener.",
"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": "ManagementDescribe",
"type": "object"
},
"Operation": {
"additionalProperties": false,
"description": "Operation is the shared operation table row consumed by bindings and clients.",
"properties": {
"doc": {
"type": "string"
},
"errors": {
"items": {
"type": "string"
},
"type": "array"
},
"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"
}
},
"required": [
"name",
"kind",
"doc",
"params",
"errors"
],
"type": "object"
},
"Param": {
"additionalProperties": false,
"description": "Param is a named input outside a JSON body.",
"properties": {
"doc": {
"type": "string"
},
"kind": {
"type": "string"
},
"name": {
"type": "string"
},
"repeated": {
"type": "boolean"
},
"required": {
"type": "boolean"
}
},
"required": [
"name",
"kind",
"required",
"repeated",
"doc"
],
"type": "object"
},
"Refusal": {
"additionalProperties": false,
"description": "Refusal is one row of the refusal table: the surface's name for it, the status the HTTP binding maps it to, and its one-line meaning.",
"properties": {
"http": {
"type": "integer"
},
"meaning": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"name",
"http",
"meaning"
],
"type": "object"
}
}
},
"info": {
"description": "Generated from journal.ManagementOperations and management types. The management SURFACE.md and HTTP.md govern semantics.",
"title": "ulab-journal management",
"version": "2026-09-11"
},
"openapi": "3.1.0",
"paths": {
"/describe": {
"get": {
"operationId": "describe",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ManagementDescribe"
}
}
},
"description": "the result",
"headers": {
"Ulab-Contract": {
"required": true,
"schema": {
"const": "2026-09-11",
"type": "string"
}
},
"Ulab-Service": {
"required": true,
"schema": {
"const": "journal",
"type": "string"
}
},
"Ulab-Surface": {
"required": true,
"schema": {
"const": "management",
"type": "string"
}
}
}
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "invalid",
"headers": {
"Ulab-Contract": {
"required": true,
"schema": {
"const": "2026-09-11",
"type": "string"
}
},
"Ulab-Service": {
"required": true,
"schema": {
"const": "journal",
"type": "string"
}
},
"Ulab-Surface": {
"required": true,
"schema": {
"const": "management",
"type": "string"
}
}
}
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "invalid: unsupported method; Allow names the supported method",
"headers": {
"Ulab-Contract": {
"required": true,
"schema": {
"const": "2026-09-11",
"type": "string"
}
},
"Ulab-Service": {
"required": true,
"schema": {
"const": "journal",
"type": "string"
}
},
"Ulab-Surface": {
"required": true,
"schema": {
"const": "management",
"type": "string"
}
}
}
}
},
"summary": "the management identity, contract, build, binding, operations, refusals and files",
"tags": [
"operational"
]
}
},
"/describe/{file}": {
"get": {
"operationId": "describe_file",
"parameters": [
{
"description": "an exact management file name listed by describe",
"in": "path",
"name": "file",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
},
"text/markdown": {
"schema": {
"type": "string"
}
}
},
"description": "the file, verbatim",
"headers": {
"Ulab-Contract": {
"required": true,
"schema": {
"const": "2026-09-11",
"type": "string"
}
},
"Ulab-Service": {
"required": true,
"schema": {
"const": "journal",
"type": "string"
}
},
"Ulab-Surface": {
"required": true,
"schema": {
"const": "management",
"type": "string"
}
}
}
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "invalid",
"headers": {
"Ulab-Contract": {
"required": true,
"schema": {
"const": "2026-09-11",
"type": "string"
}
},
"Ulab-Service": {
"required": true,
"schema": {
"const": "journal",
"type": "string"
}
},
"Ulab-Surface": {
"required": true,
"schema": {
"const": "management",
"type": "string"
}
}
}
},
"404": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "not_found",
"headers": {
"Ulab-Contract": {
"required": true,
"schema": {
"const": "2026-09-11",
"type": "string"
}
},
"Ulab-Service": {
"required": true,
"schema": {
"const": "journal",
"type": "string"
}
},
"Ulab-Surface": {
"required": true,
"schema": {
"const": "management",
"type": "string"
}
}
}
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "invalid: unsupported method; Allow names the supported method",
"headers": {
"Ulab-Contract": {
"required": true,
"schema": {
"const": "2026-09-11",
"type": "string"
}
},
"Ulab-Service": {
"required": true,
"schema": {
"const": "journal",
"type": "string"
}
},
"Ulab-Surface": {
"required": true,
"schema": {
"const": "management",
"type": "string"
}
}
}
}
},
"summary": "one embedded management contract file, verbatim",
"tags": [
"operational"
]
}
},
"/healthz": {
"get": {
"operationId": "health",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Health"
}
}
},
"description": "the result",
"headers": {
"Ulab-Contract": {
"required": true,
"schema": {
"const": "2026-09-11",
"type": "string"
}
},
"Ulab-Service": {
"required": true,
"schema": {
"const": "journal",
"type": "string"
}
},
"Ulab-Surface": {
"required": true,
"schema": {
"const": "management",
"type": "string"
}
}
}
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "invalid",
"headers": {
"Ulab-Contract": {
"required": true,
"schema": {
"const": "2026-09-11",
"type": "string"
}
},
"Ulab-Service": {
"required": true,
"schema": {
"const": "journal",
"type": "string"
}
},
"Ulab-Surface": {
"required": true,
"schema": {
"const": "management",
"type": "string"
}
}
}
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "invalid: unsupported method; Allow names the supported method",
"headers": {
"Ulab-Contract": {
"required": true,
"schema": {
"const": "2026-09-11",
"type": "string"
}
},
"Ulab-Service": {
"required": true,
"schema": {
"const": "journal",
"type": "string"
}
},
"Ulab-Surface": {
"required": true,
"schema": {
"const": "management",
"type": "string"
}
}
}
},
"503": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Health"
}
}
},
"description": "a check is failing; the same envelope",
"headers": {
"Ulab-Contract": {
"required": true,
"schema": {
"const": "2026-09-11",
"type": "string"
}
},
"Ulab-Service": {
"required": true,
"schema": {
"const": "journal",
"type": "string"
}
},
"Ulab-Surface": {
"required": true,
"schema": {
"const": "management",
"type": "string"
}
}
}
}
},
"summary": "whether the durable store and instance identity are ready",
"tags": [
"operational"
]
}
},
"/livez": {
"get": {
"operationId": "livez",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Health"
}
}
},
"description": "the result",
"headers": {
"Ulab-Contract": {
"required": true,
"schema": {
"const": "2026-09-11",
"type": "string"
}
},
"Ulab-Service": {
"required": true,
"schema": {
"const": "journal",
"type": "string"
}
},
"Ulab-Surface": {
"required": true,
"schema": {
"const": "management",
"type": "string"
}
}
}
},
"400": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "invalid",
"headers": {
"Ulab-Contract": {
"required": true,
"schema": {
"const": "2026-09-11",
"type": "string"
}
},
"Ulab-Service": {
"required": true,
"schema": {
"const": "journal",
"type": "string"
}
},
"Ulab-Surface": {
"required": true,
"schema": {
"const": "management",
"type": "string"
}
}
}
},
"405": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "invalid: unsupported method; Allow names the supported method",
"headers": {
"Ulab-Contract": {
"required": true,
"schema": {
"const": "2026-09-11",
"type": "string"
}
},
"Ulab-Service": {
"required": true,
"schema": {
"const": "journal",
"type": "string"
}
},
"Ulab-Surface": {
"required": true,
"schema": {
"const": "management",
"type": "string"
}
}
}
}
},
"summary": "the process is up and can answer; empty checks and never 503",
"tags": [
"operational"
]
}
}
},
"servers": [
{
"description": "the standalone default listener",
"url": "http://127.0.0.1:8093"
}
]
}