Publication lifecycle

Saving changes a draft. Publishing accepts an immutable revision and queues its delivery.

draft ── publish ──> published ── edit ──> changed ── publish ──> published
                              └──────── archive ────────> archived

Draft states

State	Consumer behavior	Available action
draft	Not visible.	Finish the definition and publish it.
published	Last accepted revision is active after delivery.	Edit or archive.
changed	Consumers still use the previous delivered revision.	Publish the new draft or continue editing.
archived	No active revision.	Read history; the identity is not reused.

Publish

Open the saved definition and clear every item under Ready to publish?. Publishing requires the current expectedDraftVersion; a stale version returns 409 conflict.

The accepted revision appears immediately under Published revisions. Its ClickHouse publication moves through these states:

State	Meaning
pending	Waiting for a worker or scheduled retry.
delivering	A worker holds the delivery lease.
delivered	The revision is available to consumers.
failed	Delivery failed; inspect the sanitized error and retry schedule.
superseded	A newer revision was delivered first.

Do not ingest stored observations or events until the service publication is delivered.

Revise

Editing a published definition does not change the consumer contract. The form becomes changed; the last delivered revision remains active. Publish after the new draft passes readiness checks.

For a grouped time-series service, use this order:

1. Save the service definition.
2. Add its member time series.
3. Publish every member.
4. Publish the grouped service.

All members must expose the output fields declared by the grouped service contract.

Recover a failed publication

1. Open Operations → Publications and filter by failed.
2. Inspect the error code, sanitized summary, attempt count, and last delivered revision.
3. Correct the unavailable dependency or contract mismatch.
4. If automatic retries are exhausted, an operator selects Retry now.

Retry requeues the accepted revision. It does not create a revision, change the definition, or interrupt the last delivered version. Do not republish solely to retry delivery.

Archive

Archiving creates an inactive revision and keeps the definition, revision history, and audit trail. A referenced metric, unit, entity, binding, group, or contract cannot be archived until its active references are removed or archived.

An archived identity is retained. Create a new canonical identity for a different concept.