State Lifecycles · In-Memory Defaults vs. Durable Stores · wiki/data-and-persistence.md
Know what lives in memory and what survives a restart.
Across the 18 ACGS repositories, durability is opt-in and component-specific. A default engine or mesh instance optimizes for low-overhead local evaluation unless you explicitly configure full audit logs, SQLite stores, or PostgreSQL repositories.
01 · Component State Lifecycles
How state moves through each runtime boundary.
01
ACGS-Lite · In-Process Receipts, Grants & Bundle Store
DecisionReceipt is an immutable in-memory dataclass. ExecutionAuthority.issue() mints a single-use ExecutionGrant authenticated with a per-instance secret HMAC and tracked in InProcessGrantLedger (STARTED, COMPLETED, FAILED, DENIED, CANCELLED, PARTIAL).
Restart & Durability Contract
ExecutionGrant capabilities and InProcessGrantLedger state are strictly process-local and reset on restart. Policy bundles can be persisted separately via sqlite_bundle_store.py (commit_bundle).
02
ACGS-Lite · Opt-In SQLite External-Effect Store (A3)
legitimacy/effects.py (commit 0cd5e56)
Runtime Flow
EffectStore persists fixed-amount EffectBudget reservations and per-key effect records (RESERVED, IN_FLIGHT, UNKNOWN, DONE, NOT_DONE) inside a transactional SQLite database.
Restart & Durability Contract
Survives process crashes and restarts. An UNKNOWN effect retains its budget reservation across restarts until EffectProvider.query_and_fence() confirms execution (DONE) or returns fenced=True (NOT_DONE).
03
ACGS Swarm · Peer Settlement & APCC Authority Store
ConstitutionalMesh coordinates signed peer votes; APCCService stages candidate state and commits atomically (COMMITTED, DENIED, CONFLICTED) with an outbox queue.
Restart & Durability Contract
ConstitutionalMesh has no settlement store by default (enabling JSONL or SQLite settlement persistence requires quorum >= 3 and distinct roles). APCC defaults to SQLite (sqlite_store.py) with an optional PostgreSQL 17 backend (postgres extra).
04
Enhanced Agent Bus · HTTP 202 Pipeline & Workflow Store
Accepts tenant-scoped messages over FastAPI (HTTP 202), evaluates governance rules, tracks IndependentValidationReceipts, and manages workflow state.
Restart & Durability Contract
Default receipt replay tracking uses an in-memory Python set that resets on restart, and production message-status lookup returns HTTP 501 unless a durable backend is wired. Workflow state supports PostgreSQL via postgres_repository.py.
02 · Complete Persistence Matrix
Default behavior vs. durable configuration.
Component
Artifact
Default Behavior
Durable Configuration
Restart & Replay Boundary
ACGS-Lite · AuditLog
AuditEntry (_chain_hash)
Engine defaults to aggregate 'fast' mode without individual entries or chain hashing; record() is best-effort.
Select audit_mode='full' with JSONLAuditBackend or custom backend and call record_durable() for fail-closed writes.
Local hash chains detect mid-file edits but require external root-hash anchoring to detect tail truncation.
ACGS-Lite · Grants & Attempt Ledger
ExecutionGrant & ExecutionAttemptRecord
InProcessGrantLedger tracks STARTED, COMPLETED, FAILED, DENIED, CANCELLED, and PARTIAL states in process memory.
Constitution bundles can be persisted separately via sqlite_bundle_store.py (commit_bundle).
ExecutionGrant HMAC secrets and single-use tracking are process-local and do not survive a process restart.
ACGS-Lite · External Effects (A3)
EffectStore & EffectBudget
Opt-in SQLite store (legitimacy/effects.py); not enabled by default on @governed callables.
SQLite transactional store holding EffectBudget reservations and per-key RESERVED, IN_FLIGHT, UNKNOWN, DONE, NOT_DONE states.
Survives process crash/restart in SQLite; resolving UNKNOWN to NOT_DONE requires EffectProvider.query_and_fence returning fenced=True.
ACGS Swarm · Mesh & APCC
Settlement records & APCC candidates
ConstitutionalMesh has no settlement store by default; APCC defaults to SQLite authority store (sqlite_store.py).
JSONL/SQLite settlement stores (requires quorum >= 3 and distinct roles); optional PostgreSQL 17 authority store (postgres extra).
Retain Ed25519 signing keys across restarts; pre-C32 APCC SQLite stores do not support in-place schema migration.
Enhanced Agent Bus
IndependentValidationReceipt & Workflows
Verifier tracks seen receipt IDs in an in-memory Python set; adjacent receipt store is scoped for dev/demo/test.
PostgreSQL workflow repository (persistence/postgres_repository.py) for configured workflow state.
In-memory receipt replay set resets on service restart; ProvMiddleware lineage stamping runs post-processing and fails open.
Enterprise AI Manager
Governed Recommendation rows
Blocked recommendations are rejected before database commit; accepted rows commit via async SQLAlchemy session.
PostgreSQL / SQLAlchemy configured database backend with rollback on commit failure.
Application-scoped table storage; does not establish a workspace-wide shared execution ledger.
03 · Audit Log Integrity
What a local hash chain proves—and what it cannot.
In acgs-lite/src/acgs_lite/audit.py, enabling audit_mode="full" links each AuditEntry via _chain_hash (sha256-v1).
By default, GovernanceEngine uses audit_mode="fast" (aggregate counters only). Even with audit_mode="full", standard AuditLog.record() logs backend write errors as warnings; call AuditLog.record_durable() when a persistence failure must halt execution.
2. Tail-truncation and full-chain rewrite boundary
AuditLog.verify_chain() detects mid-file tampering, insertion, or reordering. However, if an attacker with write access to the local JSONL file truncates the tail (or recomputes the entire chain from genesis), the remaining prefix still passes local verification unless the latest _chain_hash root is periodically anchored to an external append-only store.
Put one real workflow under your control.
Choose one tool. Define what it may do. Inspect what happens when a request crosses the boundary.