Skip to content
Mint

Operations

Use this page for a running private Mint service.

Use configuration for settings and reload scope.

Use deployment for release activation.

Live health

Section titled “Live health”

Query the local health endpoint.

curl --fail http://127.0.0.1:4949/healthz

HTTP 200 means the live audit gate admits new effects.

HTTP 503 means the live broker does not admit new effects.

The response includes a declaration generation.

The response includes short value-free declaration fingerprints.

The response includes the Canary audit backlog count.

A 200 response does not prove an upstream call succeeds.

A 200 response does not prove every route has current policy.

A 200 response does not expose custody values.

The endpoint reports live process state.

Doctor versus live health

Section titled “Doctor versus live health”

Run doctor against the effective files.

mint doctor

Doctor checks policy, capabilities, authentication, call guards, bind syntax, custody construction, audit writability, disk pressure, reload semantics, and startup admission.

Doctor can run without a listening broker.

Doctor does not bind a socket.

Doctor does not prove a running process is healthy.

Doctor does not prove a caller can reach the service.

Pass --self-test-alias secret://service/name for a bounded custody resolution check.

Doctor reports that self-test as pass, fail, or skip.

Doctor never prints the resolved value.

Use health for live state.

Use doctor for offline startup evidence.

Reload

Section titled “Reload”

Change policy or capabilities in a prepared working copy.

Validate the policy before signaling the service.

mint policy check <policy-file>

Send one reload signal.

systemctl reload mint.service

Query health again.

curl --fail http://127.0.0.1:4949/healthz

A successful reload increments the declaration generation.

A rejected reload keeps the last-known-good generation.

A rejected reload adds a sanitized audit event.

Compare doctor fingerprints with the live health fingerprints.

A mismatch can mean a reload is pending or rejected.

Only policy and capabilities reload on SIGHUP.

SIGHUP also triggers one audit recovery retry.

Restart the service for startup-only settings.

Drain and shutdown

Section titled “Drain and shutdown”

Systemd stop sends the graceful termination signal.

The broker stops admitting new effects immediately.

Requests during the drain receive HTTP 503.

Existing effects can finish within the drain bound.

The broker writes an indeterminate deny terminal for work that exceeds the bound.

It never fabricates an upstream success.

Check health until the service exits.

systemctl stop mint.service

Start the service after the maintenance window.

systemctl start mint.service

Use the health endpoint before allowing traffic.

Audit ledger

Section titled “Audit ledger”

Mint durably records each prepared effect before vendor contact.

Early refusals attempt to append a secret-free event. If that append fails, the gate turns unhealthy and blocks later effects, but the refused request may be absent from the ledger.

Recorded events include actor, service, method, path, decision, phase, reason, and timing. They do not include credential values.

The ledger is append-only.

The ledger uses a hash chain.

The ledger can rotate closed segments when configured.

Tail recent events through the CLI.

mint audit tail --path "$AUDIT_LOG" -n 20

Filter before truncating to recent events for one actor.

mint audit tail --path "$AUDIT_LOG" --actor example-actor -n 20

List prepared effects without terminal records.

mint audit unresolved --path "$AUDIT_LOG"

Verify the complete surviving chain.

mint audit verify --path "$AUDIT_LOG"

Verification exits nonzero when the chain is damaged.

Read legacy history before migrating it.

Migration is explicit and one-time.

Run migration as the same operating-system user as the service.

mint audit migrate --path "$AUDIT_LOG" --reason reviewed-legacy --operator example-operator

Do not migrate a ledger while an old broker can append to it.

Reconcile only an effect that cannot still be running.

mint audit reconcile <effect-id> --path "$AUDIT_LOG" --reason operator-reconciled-no-safe-retry --operator example-operator

Reconciliation appends an indeterminate deny.

It never retries the upstream request.

It never records a fabricated success.

Audit gate

Section titled “Audit gate”

The audit gate controls admission.

A failed durable write marks the gate unhealthy.

New effects then receive HTTP 503.

The recovery loop retries at a fixed interval.

SIGHUP triggers an immediate retry.

Recovery requires a successful durable probe write.

Recovery does not close unresolved effects.

Resolve each unresolved effect separately.

Circuit breaker

Section titled “Circuit breaker”

The breaker tracks each upstream host independently.

Transport, connection, send, timeout, and body-read failures count.

HTTP 5xx responses count.

HTTP 4xx responses reset consecutive failures.

HTTP 2xx and 3xx responses reset consecutive failures.

The threshold comes from MINT_BREAKER_THRESHOLD.

The open interval comes from MINT_BREAKER_OPEN_SECS.

An open breaker returns HTTP 503.

An open breaker does not contact the upstream host.

Inspect audit events for the sanitized breaker reason.

Wait for the interval before testing recovery.

Do not retry a failing upstream in a tight loop.

Call guards

Section titled “Call guards”

Call guards are operational availability controls.

They match actor and service.

They enforce a maximum count in a positive time window.

They do not match methods or paths.

They do not express credentials, spend, approval, or task semantics.

The configured operations guard file is empty by default.

Legacy per-rule policy limits are a separate, deprecated compatibility path.

A legacy limit and an operational guard share the same in-memory counter and the same HTTP 429 exhaustion behavior.

Every deployed legacy limit currently declares a daily window_seconds: 86400.

No deployed legacy limit lasts the broker process lifetime.

The Canary report route keeps a distinct 700,000-call daily allowance sized to observed sustained load.

The in-memory counter resets when the process restarts.

A guard exhaustion returns HTTP 429.

Validate guard syntax through doctor.

Use observed load before adding a production threshold.

Release lifecycle

Section titled “Release lifecycle”

Build and stage one immutable candidate.

Run release preflight.

Validate the effective systemd contract.

Drain or stop the old service.

Activate the candidate with an expected previous target.

Wait for HTTP 200 health.

Check restart count and unresolved audit effects.

Keep the candidate only after all checks pass.

Restore the previous target when readiness fails.

See deployment for the complete sequence.

Source map

Section titled “Source map”