Feature Explorer

Bounded reversible enforcement layer. Carries out human-approved governance actions inside declared policy budgets; every action is simulation-first with an explicit rollback handle.

ON

Approved actions execute through registered adapters inside the declared budget; each step is audited and carries a reversal handle.

OFF

No state-changing adapter call is dispatched; pending actions remain in the approvals queue.

FAILURE

Execution aborts at the adapter boundary, the partial result is written to the audit ledger with a FAILED outcome, and any prior side-effect is reverted via the rollback handle.

ROLLBACK

One-click reversal invokes the stored rollback handle; the reversal itself is audited and links to the original action.

src/services/enforcement/

Records the named human actor who authorised every binding governance state change. AI may draft and recommend; the gate refuses to mutate state without a human approver on the chain.

ON

Every state-changing route requires a recorded approver; the approval row is written to the audit ledger before the adapter is invoked.

OFF

Not applicable — the gate cannot be disabled in production; SAFE_MODE is the global stop instead.

FAILURE

The mutation is rejected with a 403/409 and an audit row recording the denied attempt.

ROLLBACK

Not applicable — the gate does not mutate state itself.

src/middleware/approvalChain.ts

Single switch that halts all new state-changing routes across the estate. Read paths and the audit ledger remain available; in-flight actions complete on their existing path.

ON

safeModeGuard rejects any non-idempotent route with 503; read endpoints, health, and the audit ledger remain reachable.

OFF

Normal operation; state-changing routes accept traffic subject to all other gates.

FAILURE

The guard fails closed — if the flag cannot be read, traffic is treated as if SAFE_MODE is engaged.

ROLLBACK

Toggle the flag back to OFF; no state was mutated while engaged.

src/middleware/safeModeGuard.ts

Append-only forensic ledger using SHA-256 integrity hashing across three distinct logs (audit_log, tenant_operation_log, operator_audit_events). Each ledger is made immutable by Postgres DO INSTEAD NOTHING rules.

ON

Every governance-relevant event writes one row whose hash chains to the previous row of the same ledger.

OFF

Not applicable — the ledger cannot be turned off in production; missing transport degrades to in-process buffering, not silent drop.

FAILURE

Write failures are surfaced through the operations logger and counted as integrity incidents; the chain is sealed at the last successful row.

ROLLBACK

Not applicable — the ledger is append-only by construction; corrections are new rows that reference the prior row.

src/services/audit/

Recomputes the hash chain end-to-end and writes the outcome of the replay back into the audit ledger. Establishes that the historical record has not been tampered with since the last verified row.

ON

Replay job recomputes each chain on a schedule; mismatches are written as integrity incidents.

OFF

Replay does not run automatically; the chain remains valid but unverified until the next manual replay.

FAILURE

A verifier crash is itself audited; the chain is not modified.

ROLLBACK

Not applicable — the verifier is read-only.

src/services/audit/replayVerifier.ts

Step-up elevation for internal operators. Combines an operators row, time-boxed sessions, recent-auth step-up, one-active-session-per-operator supersede, and per-capability gates orthogonal to the role-based authorize() gate.

ON

Elevation grants a time-boxed session; the ElevationBanner renders the time-remaining countdown on every /super-admin/* page.

OFF

No elevation present; requireOperatorElevation() returns 403 even for a fully role-gated super-admin.

FAILURE

Step-up timeout or stale recent-auth invalidates the session; the next protected request returns 401 and re-step-up is required.

ROLLBACK

Revoke the session via the active-sessions surface; revocation itself is audited.

src/middleware/operatorElevation.ts

Postgres Row-Level Security in STRICT mode plus a single hardened repository module whose raw client accessor is hard-thrown. Tenant isolation is structural, not advisory.

ON

Every tenant-scoped query carries the current tenant_id; cross-tenant rows are invisible at the database boundary.

OFF

Not applicable — STRICT mode is required in production; boot aborts if the policy cannot be installed.

FAILURE

A missing tenant context causes the query to return zero rows; the attempt is logged for forensic review.

ROLLBACK

Not applicable — RLS is a query-time gate, not a mutating operation.

src/db/tenant/

AI in Govula is recommendation-only. The intelligence layer may analyse, suggest, and draft. It may not approve, sign, publish, or mutate governance state. Recommendation pipelines that produce governance artefacts are audited.

ON

Prompts return recommendations attached to the originating signal; recommendation rows are written to the audit ledger.

OFF

The recommendation pipeline is suspended; existing recommendations remain visible but no new ones are produced.

FAILURE

Upstream API errors are surfaced as warnings on the originating signal; no governance state is mutated.

ROLLBACK

Recommendations themselves do not mutate state, so no rollback handle is required; the human approver simply declines.

src/services/aiService.ts

Investor Response Engine alerts the founder exactly once per session via an atomic UPDATE … WHERE alerted_at IS NULL claim. Missing transport configuration releases the claim so a later configuration heals retroactively.

ON

A matching investor session triggers exactly one alert email through Resend; the row is marked alerted.

OFF

No alert is sent; the session remains claimable when alerts are re-enabled.

FAILURE

Missing RESEND_API_KEY / ALERT_EMAIL_TO / EMAIL_FROM releases the claim and writes an audit row noting the deferral.

ROLLBACK

Not applicable — the alert is informational; recipients can disregard.

src/services/investorResponseEngine.ts

Per-tenant adoption mode (Observation / Guided / Enforced) that adjusts the friction of the approval gate without changing the underlying authority boundary. AI remains recommendation-only in every mode.

ON

Mode is read at the start of every protected route; the gate adjusts to the mode-specific policy.

OFF

Tenant defaults to Observation mode; no enforcement actions are taken automatically.

FAILURE

A mode-read failure falls back to the safest mode (Observation); the fallback is audited.

ROLLBACK

Mode changes are themselves auditable rows; reverting is one configuration update.

docs/architecture/governance-modes.md