Developers · Architecture & Bounded Contexts · 18 Repositories
The ACGS workspace is organized as 18 independent repositories rather than a single monolithic control plane. Each repository enforces a specific, source-pinned boundary—from in-process rule evaluation and callable-bound grants in acgs-lite to multi-agent quorum commits in Acgs-Swarm and FastAPI message routing in enhanced-agent-bus.
Workspace Snapshot · 2026-10-27
01 · Workspace Topology
There is no single monorepo runtime or shared cross-repository database. Packages depend on acgs-lite where declared in their pyproject.toml, while Acgs-Swarm and enhanced-agent-bus maintain independent package trees and release cadences.
gove-zone==1.0.0rc2) is documented on /products/gove-zone/ from its published PyPI artifact; its source lives outside this 18-repository workspace.Entry points: GovernanceEngine (engine/core.py#L37) · GovernedAgent (governed.py#L113) · EffectStore (legitimacy/effects.py)
Core constitutional rule engine, MACI role separation, versioned evidence identities (A1), observer-authority rules (A2), and opt-in SQLite external-effect lifecycle (A3).
Boundary: Default fast audit mode is aggregate-only. ExecutionGrants are process-local. Unreleased post-3.0.1 commits on main (A1–A3) are in source and CI-verified.
Entry points: governed_handoff (governed_handoff.py#L1075) · APCCService (apcc/service.py#L27) · ConstitutionalMesh (mesh/core.py)
Orchestrator-free multi-agent coordination with signed vote envelopes, quorum settlement, APCC atomic commit boundary, and 1,621 lines of TLA+ specifications in specs/.
Boundary: Do not use unpinned pip install constitutional-swarm for 1.1.0 source workflows; PyPI 0.1.1 predates the 0.2.0 signer/agent API split. Persistent settlement requires quorum >= 3.
Entry points: EnhancedAgentBus (bus/core.py#L267) · MessageProcessor (message_processor/__init__.py#L850)
Self-hosted FastAPI service for governed inter-agent messaging and workflow endpoints, registering 14 core routers, IndependentValidationReceipts, and W3C-style ProvLabels.
Boundary: HTTP 202 indicates message acceptance, not tool execution authorization. Seen-receipt replay tracking in the default verifier is in-memory; ProvMiddleware stamps fail-open.
Thirteen framework-specific packages published on PyPI (0.1.0–0.1.3, Apache-2.0, Development Status: Alpha) that pin acgs-lite>=3.0.1,<4. Five call-owning middlewares wrap downstream call_next dispatch; eight pre-tool hooks veto before execution.
Entry points: create_app (agent.py#L504) · main.py#L32 · validate_clinical.py
Starlette A2A JSON-RPC prototype combining model-assisted clinical assessment, a 20-rule Healthcare AI Constitution on ACGS-Lite, and a 10-of-18 HIPAA Safe Harbor pattern checker.
Boundary: Healthcare prototype only; not clinically validated. Provider order: ANTHROPIC_API_KEY, local pi RPC binary, then rule-only fallback. Unset CLINICALGUARD_API_KEY leaves auth disabled; default audit path is /tmp/clinicalguard_audit.json.
Entry points: FastAPI app factory (backend/main.py#L82) · recommendations API (backend/api/recommendations.py#L99) · Vue frontend
FastAPI + async SQLAlchemy backend and Vue frontend application that evaluates AI recommendations against configured governance rules before committing accepted records.
Boundary: Unreleased sample application. If acgs-lite is absent in the environment, acgs_integration.py logs a warning and falls back to the local RulesEngine (fail_closed=True).
02 · Canonical Vocabulary & Bounded Contexts
Derived from acgs-lite/GLOSSARY.md (commit 5a012c5) and wiki/concepts.md. When reviewing receipts, grants, or audit logs, verify which artifact and repository boundary is actually in play.
PolicyBinding.digest · acgs:policy:v1:sha256:<digest>
acgs-lite/src/acgs_lite/legitimacy/invocation.py
Definition & Guarantee
Full, domain-separated SHA-256 digest computed over the acgs-policy-v1\x00 domain prefix and the canonical JSON of the entire constitution.
Content identity for policy bindings, grants, and attempt records. Distinct from Constitution.hash (a 16-hex-character version label that omits patterns, enabled flags, and conditions).
Resolved Ambiguity
CONSTITUTIONAL_HASH = '608508a9bd224290' in _meta.py is a fixed package stamp, not a digest computed from a loaded constitution.
DecisionReceipt · acgs:receipt:v1:sha256:<hash>
acgs-lite/src/acgs_lite/legitimacy/receipt.py#L32
Definition & Guarantee
Frozen, replayable pre-execution decision record addressed by receipt_hash over canonical fields. verify_hash() recomputes and validates the commitment.
Hash-addressed evidence of what policy decided before execution. It is not a cryptographic signature (SignedReceipt), not live execution authority (ExecutionGrant), and not proof that an external tool ran.
Resolved Ambiguity
A DecisionReceipt records a decision and grants nothing on its own; execution authority requires an ExecutionGrant or verified executor gate.
SignedReceipt · acgs:signed-envelope:v1:<hash>
acgs-lite/src/acgs_lite/legitimacy/signing.py#L169
Definition & Guarantee
Asymmetric Ed25519 signature envelope over a DecisionReceipt commitment, with signature_scope set to 'receipt' (default) or 'execution'.
Authenticity requires a caller-trusted public key. Under scope 'receipt', it attests the decision record rather than authorizing execution.
Resolved Ambiguity
signed_envelope_identity() hashes key_id and signed_at (outside the signature payload), serving as an evidence pointer rather than standalone proof of authenticity.
ExecutionGrant · acgs:local-grant:v1:<issuer_id>:<grant_id>
acgs-lite/src/acgs_lite/legitimacy/authorization.py#L83
Definition & Guarantee
Process-local capability minted by ExecutionAuthority.issue() that binds the receipt, method, argument digest, policy digest, scope, subjects, context, expiry, and single-use UUID.
Authenticated by a binding_mac keyed with a per-instance secret. Verifiable only by the issuing ExecutionAuthority instance within the same process.
Resolved Ambiguity
Grants do not survive process restarts and are not portable cross-process tokens. local_grant_identity excludes the capability MAC and authorizes nothing by itself.
PROPOSER · VALIDATOR · EXECUTOR · OBSERVER
acgs-lite/src/acgs_lite/maci/roles.py
Definition & Guarantee
Four-role separation-of-powers enum in acgs-lite. A verb is permitted only if present in the role's allow set and absent from its deny set; OBSERVER is strictly read/query/export/observe.
Enforces proposer != validator (check_no_self_validation). Distinct from enhanced-agent-bus's 7-role vocabulary, which projects MONITOR to observer outside the execution triple.
Resolved Ambiguity
approve is a denied verb on self-validation rather than a fifth role; OBSERVER cannot propose, validate, or execute.
EffectStore · EffectState (RESERVED | IN_FLIGHT | UNKNOWN | DONE | NOT_DONE)
acgs-lite/src/acgs_lite/legitimacy/effects.py
Definition & Guarantee
Opt-in SQLite lifecycle (commit 0cd5e56) tracking fixed-amount external dispatches from atomic budget reservation through send(), per-key UNKNOWN on exception/timeout, and query_and_fence reconciliation.
Durable state and budget conservation for side effects after authority is checked. It is not an authorization boundary and is not wired into decorators by default.
Resolved Ambiguity
In-process AttemptStatus.PARTIAL in ledger.py is a terminal observation on the local attempt ledger and is distinct from EffectState.UNKNOWN.
acgs:effect:v1:<sha256> · EffectBudget
acgs-lite/src/acgs_lite/legitimacy/effects.py
Definition & Guarantee
Grant-bound provider key derived over acgs-provider-effect-v1\x00 and canonical JSON of [provider_id, grant_identity, action_digest], paired with an atomic integer hold on EffectBudget.
One grant_identity maps to one effect key permanently; DONE settles the reserved amount and NOT_DONE (when fenced=True) releases it.
Resolved Ambiguity
EffectBudget tracks side-effect capacity (capacity - settled - reserved), separate from CostBudget compute accounting.
AuditLog.record() vs AuditLog.record_durable()
acgs-lite/src/acgs_lite/audit.py#L390
Definition & Guarantee
Hash-chained governance log entry with _chain_hash and _format_version (sha256-v1). Engine construction defaults to aggregate 'fast' mode unless 'full' or an explicit AuditLog is supplied.
record() logs backend write failures as warnings (best-effort); record_durable() fails closed when persistence fails.
Resolved Ambiguity
A local hash chain detects mid-stream tampering but can retain a valid prefix after tail truncation unless the latest root hash is anchored externally.
APCCService.commit() · COMMITTED | DENIED | CONFLICTED
Acgs-Swarm/src/constitutional_swarm/apcc/service.py#L27
Definition & Guarantee
Atomic Proposal & Constitutional Commit service in Acgs-Swarm separating candidate staging and evidence assembly from atomic store commit (SQLite default, optional PostgreSQL 17).
Governs stageable state commits and post-commit outbox delivery (specs/apcc.tla). A COMMITTED candidate state is not an arbitrary external provider effect.
Resolved Ambiguity
Persistent settlement in ConstitutionalMesh requires quorum >= 3, distinct assigner/voter/producer/settlement-signer roles, and TLS off loopback.
FENCEABLE · BOUNDED · UNBOUNDED · STAGEABLE
reports/tla/effect_unknown.tla · effect_unknown_bounded.tla
Definition & Guarantee
Formal TLA+ classifications for resolving UNKNOWN effects after timeout: FENCEABLE (idempotent key + atomic query-and-fence) and BOUNDED (delivery cutoff D + status query after D + skew ε).
TLC model-checked invariants (I1 at-most-once, I2 state safety, I3 budget conservation) hold only when the external provider satisfies the stated contract assumptions.
Resolved Ambiguity
Model checking verifies protocol logic under explicit assumptions; it does not certify third-party API behavior.
03 · Post-Decision Execution & TLA+ Models
A pre-execution policy check answers whether a proposed action is permitted to start. Once an agent dispatches an HTTP call or tool invocation over a lossy network, a timeout or exception leaves the caller in an indeterminate state: the provider may have executed the effect, queued it, or dropped it.
In acgs-lite commit 0cd5e56 (slice A3), legitimacy/effects.py implements an opt-in SQLite EffectStore and EffectBudget modeled after TLC-checked TLA+ specifications.
SQLite EffectStore State Machine · legitimacy/effects.py (0cd5e56)
[Grant Issued]
│
▼ reserve(grant_identity, provider_id, action_digest, amount)
RESERVED (atomic hold on EffectBudget; 1 grant_identity -> 1 effect_key)
│
▼ dispatch(effect_key, provider)
IN_FLIGHT ──(SendAck: provider confirms receipt)──────────────► DONE
│ (budget settled)
└──(SendNak / Timeout / Exception)──► UNKNOWN
│
reconcile(effect_key) │ calls provider.query_and_fence()
├──(executed=True)────────────► DONE
├──(executed=False, fenced=True)► NOT_DONE (budget released)
└──(executed=False, fenced=False)► stays UNKNOWNSafety invariant: an UNKNOWN effect never transitions to NOT_DONE unless the provider returns fenced=True, preventing retry double-execution while an unconfirmed request could still land.
Requires provider idempotency key support plus an atomic query_and_fence(key) contract that either reports prior execution or permanently blocks late arrival of the key. Verifies invariants I1 (at-most-once per grant), I2 (no false NOT_DONE), and I3 (budget conservation).
For providers without an explicit cancel/fence API that enforce a strict server-side delivery cutoff D (for example, signed request expiry) and status lookup by key. Waiting until t_send + D + ε (clock skew bound) before querying status acts as a time-based fence.
Separates candidate staging and constitutional evidence assembly from atomic store commit (COMMITTED | DENIED | CONFLICTED) and post-commit outbox delivery across 1,621 lines of TLA+ specifications in Acgs-Swarm/specs/.
04 · Persistence & Durability Matrix
Durability in ACGS is opt-in and component-specific. Review default behaviors and restart limits before relying on logs or receipts for compliance or incident replay.
Explore full state lifecycles & audit hash-chain contract| 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. |
05 · Codebase Graph Provenance
Architectural documentation across /architecture/, /adapters/, and /evidence/ is cross-checked against a structural codebase graph (graphify-out/) and verified directly against repository source files, pyproject.toml manifests, and test suites.
Graphify Snapshot · 2026-10-27 (Graphify 0.9.95)
Tracked across 18 repositories + workspace reports
600 Leiden communities (62 with ≥100 nodes)
269,172 extracted (81.9%) · 59,391 inferred (18.1%)
Verification rule: Graph node degree and community clustering reflect symbol and test density (for example, MessageProcessor, GovernanceEngine, and ConstitutionalMesh), not runtime call frequency. Every normative claim on this site is verified against actual source lines rather than inferred graph edges.
Choose one tool. Define what it may do. Inspect what happens when a request crosses the boundary.