Normative Vocabulary · acgs-lite/GLOSSARY.md @ 5a012c5 · wiki/concepts.md
Across the 18 ACGS repositories, terms like receipt, hash, grant, and MACI refer to specific data structures with bounded guarantees. This glossary pins every term to its defining Python symbol and source file.
01 · Versioned Evidence Identities (Slice A1)
Implemented in acgs-lite commit 16dc5d0, versioned URN strings distinguish a policy digest from a decision receipt, a signed envelope pointer, a process-local grant correlation ID, and a provider effect key.
| URN Format | Producer Symbol | What It Commits | What It Does Not Establish |
|---|---|---|---|
| acgs:policy:v1:sha256:<64-hex> | PolicyBinding.digest (legitimacy/invocation.py) | Domain prefix acgs-policy-v1\x00 + canonical JSON of the full loaded constitution (including patterns, conditions, and enabled flags). | Distinct from Constitution.hash (16-hex version label) and _meta.py CONSTITUTIONAL_HASH ('608508a9bd224290' fixed package stamp). |
| acgs:receipt:v1:sha256:<64-hex> | DecisionReceipt.evidence_identity (legitimacy/receipt.py) | Pre-execution decision fields addressed by receipt_hash; verifiable via DecisionReceipt.verify_hash(). | Does not carry a cryptographic signature (SignedReceipt) or grant execution capability (ExecutionGrant). |
| acgs:signed-envelope:v1:<64-hex> | SignedReceipt.signed_envelope_identity() (legitimacy/signing.py) | Evidence pointer hashing envelope metadata (including key_id and signed_at). | Pointer only; authenticity requires verifying the Ed25519 signature bytes against a caller-trusted public key. |
| acgs:local-grant:v1:<issuer_id>:<grant_id> | ExecutionGrant.local_grant_identity (legitimacy/authorization.py) | Process-local issuer identifier and single-use grant UUID for correlating attempt records. | Omits the secret binding_mac; possessing the identity string alone confers zero execution authority. |
| acgs:effect:v1:<64-hex> | EffectStore.reserve() (legitimacy/effects.py) | Domain prefix acgs-provider-effect-v1\x00 + canonical JSON of [provider_id, grant_identity, action_digest]. | Maps one grant_identity permanently to one external-effect key; requires EffectProvider.query_and_fence() to resolve UNKNOWN. |
02 · Bounded-Context Distinctions
Surface A
Constitution.hash is a 16-hex-character short hash omitting regex patterns, enabled flags, and condition blocks. CONSTITUTIONAL_HASH ('608508a9bd224290') is a static constant in _meta.py.
Surface B
PolicyBinding.digest (acgs:policy:v1:sha256:...) is the full domain-separated SHA-256 over the entire canonical constitution used by ExecutionGrant and legitimacy records.
Surface A
DecisionReceipt is a hash-addressed record of a policy evaluation. SignedReceipt wraps that commitment in an Ed25519 signature (default scope='receipt').
Surface B
ExecutionGrant is a process-local, single-use HMAC capability minted by ExecutionAuthority.issue() that binds the callable, argument digest, and expiry.
Surface A
AttemptStatus.PARTIAL (legitimacy/ledger.py) is an in-process terminal observation recorded when a post-call exception occurs after side effects may have started.
Surface B
EffectState.UNKNOWN (legitimacy/effects.py) is a durable SQLite state holding reserved EffectBudget until EffectProvider.query_and_fence() reconciles the outcome.
Surface A
acgs-lite defines 4 roles (PROPOSER, VALIDATOR, EXECUTOR, OBSERVER) where OBSERVER is strictly read-only and self-validation is forbidden.
Surface B
enhanced-agent-bus defines a 7-role vocabulary (projecting MONITOR to observer); acgs-enterprise-ai-manager uses MACI to mean Monitor-Approve-Control-Inspect.
Surface A
Engine construction defaults to audit_mode='fast' (aggregate counters only). In full mode, AuditLog.record() logs persistence backend errors as warnings.
Surface B
AuditLog.record_durable() raises on persistence failure (fail-closed) so callers can halt execution if the audit trail cannot be written.
03 · Complete Reference Table
PolicyBinding.digest · acgs:policy:v1:sha256:<digest>
acgs-lite/src/acgs_lite/legitimacy/invocation.py
Definition & Boundary
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 & Boundary
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 & Boundary
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 & Boundary
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 & Boundary
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 & Boundary
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 & Boundary
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 & Boundary
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 & Boundary
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 & Boundary
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.
Choose one tool. Define what it may do. Inspect what happens when a request crosses the boundary.