Skip to content
OWP

9. The Audit Envelope (Detailed)

This section specifies the Audit Envelope structure in detail. The Envelope is the protocol’s principal mechanism for accountability. Its integrity, completeness, and tamper-evidence are non-negotiable conformance requirements.

9.1 Event Types

An Audit Envelope is a sequence of events of the following types. Implementations MUST emit all applicable events; implementations MAY define additional event types but MUST NOT redefine the meaning of types specified here.

  • EnvelopeOpened. Emitted on creation of the Envelope.
  • IntentGenerated. A Worker generated an Intent.
  • IntentDispatched. A generated Intent was dispatched to a target.
  • IntentAccepted. A Worker accepted an Intent.
  • IntentRefused. A Worker refused a Dispatch.
  • IntentReassigned. The runtime reassigned an Intent (e.g. due to Worker decommissioning).
  • SignalReceived. A subscribed Worker received a Signal.
  • CapabilityInvoked. A Worker invoked a Capability. Includes the Cost Record.
  • CapabilityCompleted. A Capability returned (synchronously, asynchronously, or via stream-final).
  • CapabilityFailed. A Capability invocation failed.
  • EscalationRaised. An Intent was escalated.
  • EscalationResolved. An escalated Intent was resolved.
  • IntentResolved. An Intent reached a terminal state.
  • AuthorityViolationAttempted. The runtime refused an outbox action.
  • ComplianceConstraintApplied. A Compliance Profile constrained an action.
  • EvaluationCommissioned. An Evaluation (§12.2) was requested by an Operator, by a cadence trigger, or by a Compliance Profile threshold.
  • EvaluationCompleted. An Evaluation envelope was signed and persisted.
  • RecalibrationProposed. A Recalibration (§12.4) was signed by an Operator and (where required) co-signed by an Architect.
  • RecalibrationApplied. The runtime effected a Recalibration; the event records outcome: applied | failed.
  • WorkerDecommissioned. A Worker reached terminal lifecycle state per §12.5.
  • IntentReassignedOnDecommission. An open Intent was reassigned during a Worker’s decommissioning per §12.5.2.
  • KnowledgeBaseRegistered. A new Knowledge Base (§3.7) was registered with the runtime. Signed by the owning Workforce’s Architect.
  • KnowledgeBaseVersionCreated. A new immutable version was materialised on a Knowledge Base. Signed by the acting author (Architect, contributing Worker, or curator on contribution acceptance).
  • KnowledgeBaseCurrentPointerMoved. The Knowledge Base’s mutable current pointer was moved to a different version. Signed by the moving actor.
  • KnowledgeContributionProposed. A Worker proposed a contribution to a Knowledge Base. Signed by the Worker.
  • KnowledgeContributionAccepted. A proposed contribution was accepted into a Knowledge Base, producing a new version. Signed by the accepting curator (Architect or designated Human Role with curation authority).
  • KnowledgeBaseRetentionPolicyChanged. The Knowledge Base’s retention class was changed. Signed by the owning Workforce’s Architect. MUST NOT apply retroactively to versions older than the change.
  • KnowledgeBaseRetired. A Knowledge Base was retired (§3.7.7). Terminal for the Base; signed by the owning Workforce’s Architect.
  • EnvelopeClosed. Emitted on closure of the Envelope.

Each event is a structured record. The schema for events is deferred to a companion document, but every event MUST include the fields specified in §9.2.

9.2 Event Common Schema

Every event in an Audit Envelope MUST include:

  • event_id — unique within the Envelope.
  • envelope_id — identifier of the Envelope.
  • event_kind — one of the types in §9.1 (or an implementation extension).
  • wallclock_at — ISO 8601 timestamp.
  • logical_at — monotonic logical clock value, used for ordering across distributed runtime instances.
  • actor — the Worker, human principal, or runtime service responsible for the event.
  • role — the Role under which the actor acted, if applicable. For Worker-attributed events, this is the Worker’s currently-bound Role per §3.2.1 (Workers are bound to exactly one Role at any moment). For human-attributed events, this is the specific Human Role under which the human acted, since a single human MAY concurrently hold multiple Human Roles per §7 and the audit chain MUST disambiguate which Role the action was taken under.
  • role_version — the version of the Role’s Charter declaration under which the actor acted, if applicable. REQUIRED whenever role is set; enables per-Role-version evaluation per §12.2.1.
  • authority_clause — the clause of the Authority Grant under which the action was permitted, if applicable.
  • function_version — the version of the Function under which the actor acted. REQUIRED for all Worker-attributed events; enables per-Function-version evaluation per §12.2.1.
  • worker_instance_seq — a monotonic instance counter, distinct from Worker ID, identifying which instantiation of the Role this Worker represents. REQUIRED for all Worker-attributed events; enables per-Worker-instance evaluation per §12.2.1 in Roles where Workers are spawned and decommissioned over time.
  • deployment_context — opaque key/value structure carrying the dimensions the Function declares as evaluation slices (e.g. tenant, region, customer segment). REQUIRED for all Worker-attributed events where the Function declares evaluation contexts; enables per-Role-context evaluation per §12.2.1.
  • payload — event-specific structured data.
  • previous_event_hash — the hash of the previous event in the Envelope, forming a hash chain.
  • signature — a signature by the actor over the event content.

Events that retrieve from a Knowledge Base (CapabilityInvoked with a Knowledge Capability per §3.5.3) MUST additionally include in their payload:

  • knowledge_base_id — the URI of the target Knowledge Base (§3.7.2).
  • knowledge_base_version — the monotonic version resolved by the Provider at retrieval time. REQUIRED whether the invocation targeted current or an explicit version.
  • retrieved_content_hash — the cryptographic hash of the content returned to the Worker. REQUIRED. Together with knowledge_base_id and knowledge_base_version, this field guarantees that a re-fetch at the same (kb_id, version) is bit-identical.
  • provenance_ref — for cross-Workforce reads (§3.7.5), a reference to the owning Workforce’s envelope and source event that materialised the version. REQUIRED on cross-Workforce reads.
  • synced_at and kb_version_at_sync — for retrievals served from a replica (§3.7.5), the wall-clock time of the last replica sync and the version held at that sync. REQUIRED on retrievals served from a replica; absent on direct retrievals.

The hash chain (previous_event_hash) provides tamper-evidence: any modification to a prior event invalidates all subsequent hashes.

9.3 Hash Chaining and Signing

Events in an Envelope form a hash chain. The first event (EnvelopeOpened) has a previous_event_hash of a well-known initial value (specified in a companion document). Each subsequent event’s previous_event_hash is the cryptographic hash of the previous event’s full serialised content, including its signature.

The signature on each event MUST be produced by the actor’s cryptographic identity (Worker key, Human Role key, or runtime key, as applicable). The signature covers all fields of the event except the signature itself.

9.4 Closure and Sealing

When the root Intent of an Envelope reaches a terminal state, the runtime MUST:

  • Emit a final IntentResolved event for the root Intent.
  • Emit an EnvelopeClosed event containing the Merkle root of all Envelope events.
  • Sign the EnvelopeClosed event with the runtime’s identity.

The sealed Envelope is immutable. Subsequent attempts to append events MUST be refused. Replay of the Envelope from any external store (e.g. archival) MUST be verifiable by recomputing the hash chain and the Merkle root, and verifying signatures.

9.5 Federation

Where work is federated across Workforces, an Audit Envelope in one Workforce MAY refer to an Envelope in another. The protocol does not yet specify federation in detail; it specifies only that:

  • Cross-Workforce references MUST use full URIs (§2.3).
  • Receiving Workforces MUST verify the signing identity of the source Envelope.
  • Federated work creates linked Envelopes; the union of linked Envelopes constitutes the full audit record for the federated work.

Detailed federation semantics are out of scope for this draft.