CitusIO
Operations / Operations

Governed commands

Treat HTTP acceptance as admission. Completion requires backend reconciliation and audit evidence.

Enterprise mutations; fail-closed on lower lanes

Enterprise can submit a small set of governed mutations through the operator console and admin API. Free, Pro, and Max package the same console but keep controlled writes requested off, so these workflows fail closed.

HTTP success means the command was accepted. It does not mean drain finished, a bundle exists, or configuration changed.

Available workflows

Workflow Role Endpoint Intent
controlled_drain operator_admin POST /api/v1/admin/drain Stop new route assignment and reconcile drain readiness.
bridge_drain operator_admin POST /api/v1/admin/bridges/{id}/drain Drain delivery for a named sink.
config_preflight config_admin POST /api/v1/admin/config/preflight Validate config and generation before activation.
support_bundle_create operator_admin POST /api/v1/admin/support/bundle Create a redacted support artifact.

The browser never assigns the role. The trusted edge injects a verified principal. Placeholder path segments such as {id} must match the intended sink or resource.

Gates that must all be open

  • contract compatible and mutationsAllowed: true
  • workflow catalog marks the workflow runtime: true
  • backend capability flag is true
  • governance, HTTP binding, principal binding, audit, and status reconciliation are ready
  • authorized role and principal from the trusted edge
  • generation and readiness checks pass
  • dashboard quality is ok and data is fresh

If any gate is closed, the console shows a blocked preflight reason. Do not bypass it with a raw curl against an untrusted listener.

Submission procedure

  1. Confirm env live, the correct node, contract compatibility, quality ok, freshness, and mutations enabled.
  2. Confirm workflow role, endpoint scope, and expected generation.
  3. Review readiness and audit implications on Overview or Command Center.
  4. Submit preflight once.
  5. Record the returned command ID and audit ID.
  6. Wait while state is accepted_pending. The console polls command status.
  7. Treat reconciled as success. Treat rejected, failed, or blocked as terminal non-success.
  8. Verify the owning page and Audit after reconciliation.

Do not resubmit with a new idempotency key to force progress. That creates a second command.

Lifecycle states

State Meaning
draft Intent exists; nothing was accepted.
preflight Gates allow a submission attempt.
approval_required Backend requires an additional approval step.
accepted_pending Accepted; completion evidence is still pending.
rejected Preflight, RBAC, generation, readiness, or policy refused the request.
failed Accepted, then backend evidence reported failure.
blocked A runtime, contract, capability, or governance gate prevented submission.
reconciled Status and audit evidence prove terminal success.

Routine uses

Start-of-shift check. Overview readiness, every route-to-node gate, alerts, HA proof, bridge backlog, and Observe unexpected_errors.

Validate a client. Devices → Broker sessions/subscriptions → Reconnect storm or ACL denies triage → Audit. Do not request payload capture.

Bridge outage. Bridges state filter → retry versus dead-letter counts → Bridge outage triage → incident-scoped support bundle → bridge_drain only after target, role, generation, and audit impact are confirmed.

Config change. Resolve drift and invalid directives first, then config_preflight with a config_admin principal. Reopen Config and Audit before activation.

Implementation authority

This page is a customer-oriented guide. The source contract remains authoritative for exact behavior and release evidence.

../nginz-iot-panel/OPERATION_GUIDE.md