Module pds_admin 

cairn pds-admin {takedown, suspend, restore} (#99, Phase E) — manual escape hatch for the PDS-admin bridge (#87).

Production path is policy-automation + label-emission firing the bridge automatically (the writer’s post-commit dispatch per #87). This subcommand exists for testing the bridge during Phase B verification and for operator one-off escalations — and explicitly does NOT skip the strike accounting / audit chain.

Routing

HTTP-routed via tools.cairn.admin.{recordAction, revokeAction} against the running cairn serve. Same pattern as cairn moderator action / cairn moderator revoke. The writer task’s post-commit dispatch (introduced in #87) fires the OzoneBackend call automatically when the action_type is takedown / temp_suspension / indef_suspension.

Why HTTP not direct-DB: the bridge dispatch lives inside the writer task. Direct-DB would either bypass the dispatch (wrong semantics) or force the CLI to spawn a writer (heavyweight, and conflicts with a running cairn serve). HTTP routes the action through the canonical pipeline.

--config purpose

The CLI loads the operator config to:

1. Pre-flight check [pds_admin].enabled = true. Without this check, a misconfigured operator would issue a recordAction, have it succeed, and only learn the bridge was disabled when looking at logs — the CLI catches the case upfront.
2. Read the DB path for the post-call pds_admin_audit lookup (so the CLI can show the operator the bridge outcome).

The --config operator must point at the same config the running cairn serve is using; otherwise the pre-flight check is meaningless. v1.7 doesn’t enforce this — operator responsibility.

restore semantics

cairn-mod has no first-class “restore” action_type. Restoration is a revoke_action of the most recent unrevoked takedown / temp_suspension / indef_suspension. The CLI:

1. Reads the most-recent unrevoked active suspension row from subject_actions (direct DB).
2. Calls tools.cairn.admin.revokeAction with that row’s id via HTTP.
3. The writer’s post-commit dispatch fires OzoneBackend::restore_account.

Operators wanting a specific action_id (rather than “most recent”) should use cairn moderator revoke <action_id> — cairn pds-admin restore <did> is the convenience case.

Structs

PdsAdminAuditView

Wire-shaped projection of one pds_admin_audit row for CLI output. Hash-chain columns (prev_hash, row_hash) and internal book-keeping are omitted; this is operator-facing.

PdsAdminRestoreOutcome

Outcome of cairn pds-admin restore. Wraps the revokeAction response plus the pds_admin_audit row (when a bridge-driven restore_account call fired).

PdsAdminTakedownOutcome

Outcome of cairn pds-admin {takedown, suspend}. Wraps the recordAction response plus the just-fired pds_admin_audit row (when the bridge dispatch produced one).

Constants

PDS_ADMIN_DEFAULT_REASON_CODE

Reserved reason code recorded on every cairn pds-admin-driven recordAction. Operators must declare this in [moderation_reasons] if they want manual bridge escalations to succeed; otherwise the writer surfaces ReasonNotFound and the CLI prints the underlying error.

Functions

find_active_suspension_action_id

Fetch the most-recent unrevoked active-suspension subject_actions row for a subject. Used by restore to resolve the action_id to revoke.

find_pds_admin_audit_for_action

Look up the pds_admin_audit row matching the precipitating action_id. Returns Ok(None) when no audit row is found — either the bridge hasn’t dispatched yet (the CLI is racing the writer’s post-commit hook), or the bridge is disabled, or the dispatch produced an Unsupported outcome that wasn’t audit-logged.

format_restore_human

Human-readable two-line output for restore.

format_restore_json

Single-line JSON for restore (tooling).

format_takedown_human

Human-readable two-line output for takedown / suspend.

format_takedown_json

Single-line JSON for takedown / suspend (tooling).

restore

cairn pds-admin restore <did> — find the most-recent unrevoked takedown/suspension for the subject, revoke it via HTTP, then look up the bridge dispatch.

suspend

cairn pds-admin suspend <did> — record a temp_suspension (when --duration is set) or indef_suspension (otherwise) via HTTP. Same bridge-dispatch lookup as takedown.

takedown

cairn pds-admin takedown <did> — record a Takedown action via HTTP, then look up the bridge dispatch outcome.

verify_pds_admin_enabled

Verify [pds_admin].enabled = true in the loaded config. The CLI calls this before issuing the recordAction so a misconfigured operator gets a precise error pointing at the config block, rather than a successful recordAction with a silently-no-op bridge.