Skip to content

API Reference

Engine

The main entry point for all Aevum operations.

Engine wires together the episodic ledger, consent ledger, graph store, policy bridge, complication registry, and the five governed functions.

aevum.core.engine.Engine

The Aevum context kernel — governed membrane between raw data and AI consumers.

Every ingest/query/review/commit/replay call passes through the five unconditional barriers (barriers.py) before any graph write or policy check. Barriers are unconditional and non-configurable; the policy engine is configurable. Evaluation order: unconditional barriers → policy engine → knowledge graph

Default component selection on construction

graph_store: InMemoryGraphStore (warns — use oxigraph/postgres for persistence) sigchain: Sigchain() with InProcessSigner (Ed25519 in-process key; see ADR-004) consent_ledger: ConsentLedger (production) or DevModeConsentLedger (AEVUM_DEV=1) policy_engine: CedarPolicyEngine if [cedar] extra present, else NullPolicyEngine ledger: InMemoryLedger wrapping the sigchain

See THREAT_MODEL.md — Assumption 4 for the in-memory storage risk statement.

Functions

ingest(*, data, provenance, purpose, subject_id, actor, idempotency_key=None, episode_id=None, correlation_id=None, model_context=None, session=None)

RELATE — write data through the governed membrane to the knowledge graph.

Evaluation order (barriers fire before any graph write): 1. Barrier 5 (Provenance): deny if provenance.source_id is absent or empty. 2. Barrier 3 (Consent): deny if no active consent grant for this subject/operation. 3. Barrier 1 (Crisis): halt if payload contains crisis keywords. 4. Policy engine: Cedar/OPA permission check. 5. Knowledge graph write. 6. Episodic ledger append.

Provenance fires before consent because chain-of-custody must be established before Cedar can evaluate data-origin attributes in a consent policy expression.

Returns:

Type Description
OutputEnvelope

OutputEnvelope — status "ok" on success, "error" on barrier/policy denial,
OutputEnvelope

"crisis" if Barrier 1 fired. Never raises on denial; inspect envelope.status.

query(*, purpose, subject_ids, actor, constraints=None, classification_max=0, episode_id=None, correlation_id=None, model_context=None, capture_witness=True, session=None)

NAVIGATE — traverse the knowledge graph for a declared purpose.

Evaluation order
  1. Barrier 1 (Crisis): halt if the query purpose contains crisis keywords.
  2. Barrier 3 (Consent): deny if no active consent grant for this subject/operation.
  3. Policy engine (Cedar/OPA): ABAC check for action="navigate".
  4. Barrier 2 (Classification Ceiling): BLOCK the whole query if any requested subject EXISTS and exceeds the actor's clearance (classification_max). Absent subjects are not a barrier event — they yield no rows.
  5. Graph traversal — every returned subject is within clearance by construction.
  6. Optional: Witness capture seals the result hash against the consent ledger sequence at query time, protecting against TOCTOU revocation.

Returns:

Type Description
OutputEnvelope

OutputEnvelope — status "ok" (full results), "error" with
OutputEnvelope

error_code="classification_blocked" (Barrier 2 block), "error" with
OutputEnvelope

error_code="consent_required" (Barrier 3 denial), or "crisis". Never raises.

review(*, audit_id, actor, action=None, episode_id=None, correlation_id=None, session=None)

GOVERN — present a pending action for human review at a checkpoint.

review() implements the veto-as-default contract: a pending action that is not explicitly approved is treated as vetoed. Timeout = veto, not approval. This is the primary defence against OWASP ASI06 (Human-in-the-Loop Bypass): the system defaults to the safe path (halt) rather than the permissive path (proceed).

S-15 (AUTOMATION_BIAS_WARNING): every consequential or irreversible GOVERN checkpoint must emit the automation bias warning. This friction is intentional — the ICLR 2025 finding (84.30% mixed-attack success, humans correct ~50% under automation bias) is the justification.

action=None means "present for review"; action="approve" or "veto" resolves it. Resolving a review resets the AgentComplication consecutive-action counter.

Returns:

Type Description
OutputEnvelope

OutputEnvelope — status "ok" on present/approve/veto, "error" if audit_id
OutputEnvelope

not found or action is invalid. Never raises on policy denial.

commit(*, event_type, payload, actor, witness=None, idempotency_key=None, episode_id=None, correlation_id=None, principal_identity=None, principal_claims=None, commitment_key_id=None)

REMEMBER — append an event to the episodic ledger (the sigchain directly).

commit() is the low-level ledger write, distinct from Session._remember() which seals a full episode. Use commit() when you need to record a single discrete event without the full session lifecycle (e.g., a standalone policy decision, a break-glass activation, or a system health checkpoint).

After commit() returns, the event is signed, chained, and immutable (I1-APPEND_ONLY). Any idempotency_key provided causes a cached envelope to be returned for duplicate calls, preventing double-writes in at-least-once delivery scenarios.

principal_identity / principal_claims / commitment_key_id bind this event to a verified external credential identity (P2-IDENTITY-V2) — pass these only when the underlying ledger was constructed with a CommitmentKeyStore (see aevum.core.audit.commitment_key_store). The raw commitment key never crosses this method's signature; only commitment_key_id does (HO-G-PLUMB SR1).

Returns:

Type Description
OutputEnvelope

OutputEnvelope — status "ok" with the signed AuditEvent audit_id in data,
OutputEnvelope

or "error" if the ledger write failed. Never raises on policy denial.

replay(*, audit_id, actor, scope=None, episode_id=None, correlation_id=None, model_context=None)

Reconstruct any past decision faithfully from the episodic ledger.

replay() is the primary forensic tool. It reads the signed AuditEvent identified by audit_id from the episodic ledger and returns its full context — the payload, the actor, the consent state at that time, and the cryptographic proof of integrity.

replay() does NOT re-execute side effects (no graph writes, no LLM calls, no TSA requests). It reconstructs the record as it was signed at the time of the original decision. This is what makes aevum "replay-first": any past decision can be reconstructed and verified by an independent investigator without trusting the operator's current state.

Consent is checked before returning the replay — an actor cannot replay a record for a subject they are not currently consented to query.

Returns:

Type Description
OutputEnvelope

OutputEnvelope — status "ok" with the reconstructed decision in data,
OutputEnvelope

"error" if audit_id not found or consent denied. Never raises on denial.

verify_sigchain()

install_complication(instance, *, auto_approve=False)

Install a complication: validate manifest, check conflicts, register.

Parameters:

Name Type Description Default
instance Any

A Complication instance.

 required
auto_approve bool

If True, immediately approve (for testing / trusted installs).

 False

Raises:

Type Description
ComplicationError

if manifest is invalid or capability conflicts exist.

approve_complication(name, *, approved_by='aevum-core')

Admin approval: PENDING → APPROVED → ACTIVE.

suspend_complication(name, *, suspended_by='aevum-core', reason='')

Admin suspension: ACTIVE → SUSPENDED.

resume_complication(name, *, resumed_by='aevum-core')

Admin resume: SUSPENDED → ACTIVE.

list_complications()

complication_state(name)

register_webhook(webhook_id, url, secret, events=None)

deregister_webhook(webhook_id)

create_review(*, proposed_action, reason, actor, autonomy_level=1, risk_assessment='', deadline_iso=None)

ledger_count()

OutputEnvelope

Every function returns exactly one OutputEnvelope. No exceptions.

Always check result.status before accessing result.data. The audit_id is always present, even on error.

aevum.core.envelope.models.OutputEnvelope

Bases: BaseModel

The mandatory return type of all five functions. Spec Section 05.

aevum.core.envelope.models.ProvenanceRecord

Bases: BaseModel

aevum.core.envelope.models.ReviewContext

Bases: BaseModel

aevum.core.envelope.models.UncertaintyAnnotation

Bases: BaseModel

aevum.core.envelope.models.SourceHealthSummary

Bases: BaseModel

aevum.core.envelope.models.ReasoningTrace

Bases: BaseModel

aevum.core.envelope.models.ReasoningStep

Bases: BaseModel

ConsentGrant

The unit of permission. Every ingest, query, and replay operation requires an active, non-expired ConsentGrant for the subject and operation.

Valid operations: "ingest", "query", "replay", "export"

aevum.core.consent.models.ConsentGrant

Bases: BaseModel

Immutable consent grant record. Frozen so it cannot be altered after construction.

Fields

grant_id: Unique identifier — used for individual revocation. subject_id: The data subject who is granting consent. grantee_id: The principal (agent, user, service) receiving access. operations: List of permitted operations (subset of VALID_OPERATIONS). purpose: Specific, auditable purpose statement — vague values rejected. classification_max: Maximum data classification level accessible under this grant. granted_at: ISO 8601 timestamp when consent was given. expires_at: ISO 8601 expiry — grants do not auto-renew; must be re-issued. authorization_ref: Optional reference to an external legal basis document. revocation_status: "active", "revoked", or "expired" — lifecycle state.

AuditEvent

The 18-field immutable episodic ledger entry. Every operation appends exactly one AuditEvent to urn:aevum:provenance. This is the information stored in each chain entry — the raw material for verifiable decision records.

aevum.core.audit.event.AuditEvent dataclass

Immutable episodic ledger entry. 19 signed fields (16 base + key_scheme + sig_format_version + hash_alg) plus optional Phase 1 dual-sig attachment fields (mldsa65_sig, mldsa65_pub, tsa_url, tsa_token, receipt_cbor).

P2-IDENTITY-V2 (spec aevum-signing-v2.md): sig_format_version == 2 entries sign three additional NULLABLE fields — principal_binding, principal_commitment, principal_commitment_key_id — that bind the event to a verified external credential identity without exposing it in plaintext. See signing_fields_from_event() for the per-version field-set dispatch (DD4).

Frozen so that field values cannot change after construction — hash_event_for_chain() must produce identical bytes every time for chain verification to hold.

Functions

hash_event_for_chain(event) staticmethod

Compute the SHA3-256 chain hash for an event — stored as prior_hash in the next entry.

Covers the same signing fields as new_event() built for this event's own sig_format_version (the "compute once" property, DD4 per-entry dispatch): chain hash = sha3_256(DOMAIN_PREFIX + rfc8785.dumps(signing_fields)).hexdigest() = Ed25519 signed digest (as hex)

The signature field is excluded to avoid circular dependency; chain traversal and signature verification are independent proofs that converge on the same digest.

See also