@mseep/open-computer-use 1.0.0

package/docs/architecture/components/07-audit-pipeline.md

@@ -0,0 +1,110 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+---
+status: draft
+last-reviewed: 2026-06-06
+owner: "@Wide-Moat/architects"
+applies-to: next/v1
+compliance: []
+threat-model: 06-threat-model.md
+contract: contracts/audit/audit-fanin.asyncapi.yaml
+adr: [0009]
+---
+
+Internal design of the Audit pipeline container: how host-attested source events fan into one hash-linked durable store and reach a customer-owned sink. Audience: engineers and security reviewers on the audit path.
+
+## Purpose
+
+The Compliance Evidence container that turns each source's OCSF event into a durable, ordered, tamper-evident record and forwards it to a customer sink ([`05-c4-container.md`](../05-c4-container.md) §3). Ingest is the trust boundary: the OCSF `source` field is the host-attested identity of the connecting channel ([NFR-SEC-09](../manifesto/02-nfrs.md)), never a value read from the payload, so a compromised source can author events only as itself.
+
+## Boundaries
+
+The inter-container fan-in edge (F10, defined in [`05-c4-container.md`](../05-c4-container.md) §4) carries events from the producer containers into this box. This section names the components inside the box and the calls between them.
+
+### Internal components
+
+```mermaid
+flowchart LR
+    EXT[5 external sources<br/>F10 fan-in, per-source mTLS] -->|OCSF + envelope| ING[Ingest face<br/>verify peer, fairness]
+    SELF[self-emit<br/>metering · saturation] --> ING
+    ING -->|admitted event| BUS[Durable bus<br/>ordered, append-only]
+    BUS --> CHAIN[Chain writer<br/>per-source hash-link + seq]
+    CHAIN --> STORE[(Audit store D2<br/>hot → cold WORM)]
+    CHAIN --> ANCHOR[Merkle-head accumulator]
+    STORE --> FANOUT[Sink fan-out<br/>FS sink · SIEM bridge]
+    ANCHOR -->|daily envelope| TLOG[transparency log]
+    FANOUT --> SINK[customer SIEM / FS]
+```
+
+The pipeline receives over five channels: four external host-attested producer channels — control-plane (carrying both MCP-gateway and Control/operator-API events), storage-broker, session-sandbox, egress-edge — each an mTLS-terminated peer, plus the pipeline's own self-emit channel for compute-metering and saturation events.
+
+- **Ingest face** terminates the five external channels (one address per source), verifies the per-source mTLS peer identity, binds the OCSF `source` to that verified identity, and discards any payload-supplied source claim. The self-emit metering/saturation channel is internally originated, not an mTLS-terminated wire peer. Per-source ingest fairness is applied before admission.
+- **Durable bus** holds admitted events ordered and append-only; an event is committed here before the source's publish is acknowledged.
+- **Chain writer** assigns per-source hash linkage over the bus-committed stream, deriving chain order from the source's monotonic `sequence` envelope field, and writes to the store.
+- **Merkle-head accumulator** batches the chain and produces the daily head submitted to the transparency log; it signs only the submission envelope.
+- **Sink fan-out** drives the always-present file-system sink and the opt-in SIEM bridge, replaying from the store on recovery.
+
+### Owned state
+
+The container is sole custodian of the **audit store** (threat-model element D2) — the hash-linked append-only log and its hot/cold tiers — and of the **Merkle-head accumulator** and the **envelope signing key**. The store is write-once from the chain writer's view: no internal path rewrites or deletes a committed record.
+
+It holds **no upstream credential, no kill-switch route, and no session-mutation path**. The fan-in contract models every source operation as `receive` and the SIEM fan-out as a separate `send` surface, so no event admitted here can issue a control-plane or egress action (Invariant 1). The hash-chain linkage (`prev_hash`/`chain_hash`) is authored at ingest, not part of any source's publish payload, so a source cannot pre-compute or forge chain position.
+
+### Wire surface
+
+The fan-in contract is [`contracts/audit/audit-fanin.asyncapi.yaml`](../../../contracts/audit/audit-fanin.asyncapi.yaml); field types, the shared `MessageEnvelope`, and the OCSF class `$ref`s are fixed there and not restated. The schema does not encode where work happens: the ingest face terminates the per-source mTLS channel and binds source identity; the chain writer (not the source) authors `prev_hash`/`chain_hash`; the durable-bus substrate is named by role only (the protocol token in the contract is a default binding, the product is an ADR — Open questions). The two self-emitted payloads (compute metering, saturation) carry a stable channel and envelope but an open payload schema — no OCSF v1.x class fits (Open questions).
+
+Source-to-pipeline calls authenticate with the **Generic internal token** class from [`02-trust-boundaries.md`](../02-trust-boundaries.md) §8; TTLs are owned there, not repeated here.
+
+## Invariants
+
+1. **Source identity is host-attested at ingest, never payload-derived.** No admitted event carries an OCSF `source` value read from its payload; the value is the verified mTLS channel identity, and the contract surface is `receive`-only with no source-issued `send`. *(property-test on the ingest decoder asserting a payload `source` claim is discarded + AsyncAPI lint asserting zero source-side `send` operations; [NFR-SEC-09](../manifesto/02-nfrs.md), [NFR-SEC-47](../manifesto/02-nfrs.md))*
+2. **A source may publish only to its own channel.** An event addressed to another source's channel from a given peer identity is rejected. *(integration test driving one source's credential against every other channel; [NFR-SEC-09](../manifesto/02-nfrs.md))*
+3. **Chain linkage is pipeline-authored and append-only.** `prev_hash`/`chain_hash` are never accepted from a publish payload; no internal path rewrites or deletes a committed record; the chain has zero breaks. *(schema-validation rejecting payload-supplied chain fields + chain-continuity check; [NFR-SEC-03](../manifesto/02-nfrs.md))*
+4. **Every event commits to the durable bus before its publish is acknowledged.** No source receives an ack for an event not yet committed; no synchronous database write sits on the critical path. *(chaos test asserting bus-on-path for every event; [NFR-REL-12](../manifesto/02-nfrs.md))*
+5. **Chain order derives from the per-source monotonic sequence and the host-side trusted-time floor, not wall-clock.** Ordering uses the source's monotonic `sequence`; the wall-clock value is a recorded field, not the ordering key. *(red-team clock-rollback harness; [NFR-SEC-48](../manifesto/02-nfrs.md))*
+6. **No single source starves co-tenant sources at the fan-in.** A source exceeding its provisioned ingest share is rate-shaped (not dropped), counted, and emits a saturation event; co-tenant sources keep headroom and the chain stays unbroken. *(chaos test flooding one source against its share; [NFR-SEC-56](../manifesto/02-nfrs.md), [NFR-PERF-10](../manifesto/02-nfrs.md))*
+7. **The daily Merkle head is submitted to a transparency log; the pipeline signs only the submission envelope.** The chain produces a head each day; the log operator signs the head, the pipeline signs the submission envelope. *(daily transparency-log probe; [NFR-SEC-03](../manifesto/02-nfrs.md))*
+8. **Every event carries the mandatory envelope out-of-band of its OCSF payload.** The `MessageEnvelope` required fields are present and validated independent of the OCSF class, so the record survives transform to CEF/ECS/UDM. *(schema-conformance gate against the `MessageEnvelope` in [`contracts/audit/audit-fanin.asyncapi.yaml`](../../../contracts/audit/audit-fanin.asyncapi.yaml); [NFR-MAINT-AUDIT-SCHEMA](../manifesto/02-nfrs.md))*
+
+## Failure modes
+
+Each row traces to one Layer 7 STRIDE row ([`06-threat-model.md`](../06-threat-model.md) §3) by element-ID and repeats that row's controlling NFR. The primary reaching actor is A1, the in-sandbox guest, acting through the session-sandbox source channel; A2/A3 rows are marked.
+
+| Pn-Xn | Trigger | Container-internal behaviour | Controlling NFR |
+|---|---|---|---|
+| **P7-S1** (A1) | A compromised source forges an OCSF `source` claiming another, trusted source. | Fail-closed at the ingest face: the event is admitted only under the verified channel identity; a payload `source` mismatching the channel is rejected, not re-tagged. Residual: guest-self-audit / out-of-band capture, [#181](https://github.com/Wide-Moat/open-computer-use/issues/181). | [NFR-SEC-47](../manifesto/02-nfrs.md) |
+| **P7-R2** (A1) | The guest, its own source for purely in-sandbox actions, omits or falsifies events before fan-in. | The pipeline records faithfully what it receives and cannot detect origin-side suppression; corroboration is against the host-authored sources (egress, broker file-op, control-plane RPC, runtime-monitor) arriving on their own channels. Residual: purely in-sandbox actions with no host-side side-effect, [#181](https://github.com/Wide-Moat/open-computer-use/issues/181). | [NFR-SEC-47](../manifesto/02-nfrs.md) |
+| **P7-D1** (A1) | The downstream sink slows or is unreachable; backpressure fills the durable bus. | Fail-closed against loss, not against availability: events commit to the durable bus and the always-present file-system sink before ack; the SIEM bridge is decoupled and replays from the store on recovery rather than dropping or blocking sources. Residual: no measurable end-to-end backpressure / saturation-spill target, [#150](https://github.com/Wide-Moat/open-computer-use/issues/150), [#188](https://github.com/Wide-Moat/open-computer-use/issues/188). | [NFR-REL-12](../manifesto/02-nfrs.md) |
+| **P7-D2** (A1) | A compromised guest floods well-formed OCSF to exhaust collector ingest or dilute true events. | Per-source ingest fairness keyed to the host-attested source ([NFR-SEC-56](../manifesto/02-nfrs.md)) rate-shapes the over-share (not dropped), counts it, and emits a saturation event; co-tenant sources keep headroom and the chain stays unbroken under the aggregate no-drop budget. Residual: per-source retention-budget cap and forensic-dilution-within-budget, [#188](https://github.com/Wide-Moat/open-computer-use/issues/188). | [NFR-PERF-10](../manifesto/02-nfrs.md) |
+| **P7-T2** (A3) | Clock rollback backdates events or stalls/forges the daily Merkle cadence so a tampered batch lands in a legitimate signing window. | Chain order and the Merkle cadence key off the per-source monotonic sequence and the host-side trusted-time floor, not the wall clock; on resume the wall clock is corrected before any time-bound check runs ([NFR-SEC-63](../manifesto/02-nfrs.md)). Residual: trusted-time anchor for the cadence, [#185](https://github.com/Wide-Moat/open-computer-use/issues/185). | [NFR-SEC-48](../manifesto/02-nfrs.md) + [SEC-63](../manifesto/02-nfrs.md) |
+| **P7-R3** (A3+A2) | A privileged operator/SOAR action beyond tier-downgrade reaches the pipeline without a mandatory record. | The pipeline is the fail-closed sink for the enumerated privileged-action set: a privileged action is denied at its source if its chain-linked OCSF event cannot be written here. The pipeline enforces the write-before-ack contract; it does not originate the action. Residual: mandatory audit of the full enumerated set, [#186](https://github.com/Wide-Moat/open-computer-use/issues/186). | [NFR-SEC-45](../manifesto/02-nfrs.md) |
+| **P7-T3** (A3) | A snapshot/hibernation image of the audit/forensic state captures a live session token at rest. | A live token is cleaned before stop and excluded from image scope ([NFR-SEC-44](../manifesto/02-nfrs.md)); snapshot artifacts are encrypted and integrity-authenticated at rest, and restore rejects an unauthenticated image ([NFR-SEC-61](../manifesto/02-nfrs.md)). Residual: snapshot live-secret at rest, [#184](https://github.com/Wide-Moat/open-computer-use/issues/184). | [NFR-SEC-44](../manifesto/02-nfrs.md) + [SEC-61](../manifesto/02-nfrs.md) |
+
+Element rows already MITIGATED in [`06-threat-model.md`](../06-threat-model.md) §4 are not relisted as live.
+
+## Operational concerns
+
+This container is the F10 fan-in consumer ([`05-c4-container.md`](../05-c4-container.md) §4): it receives OCSF from the source containers and is the enforcement point for the write-before-ack property of [NFR-SEC-03](../manifesto/02-nfrs.md), [NFR-SEC-45](../manifesto/02-nfrs.md), and [NFR-SEC-72](../manifesto/02-nfrs.md) (system-initiated lifecycle transitions).
+
+| Concern | Detail | Target / anchor |
+|---|---|---|
+| Config surface | five external source-channel addresses + per-source mTLS trust; self-emit channel; per-source ingest share; retention tier; sink bindings (FS always-on, SIEM opt-in); transparency-log endpoint | [NFR-COMP-01](../manifesto/02-nfrs.md), [NFR-MAINT-AUDIT-SCHEMA](../manifesto/02-nfrs.md) |
+| Observability | per-source ingest rate vs share, saturation events, bus depth / backpressure, chain-continuity, sink replay lag; self-emitted on its own channel | [NFR-PERF-10](../manifesto/02-nfrs.md), [NFR-COST-05](../manifesto/02-nfrs.md) |
+| Scaling axis | per-deployment (single durable bus + store); sources scale `[1..N]` independently; whether the store partitions per tenant is a deployment concern | [NFR-REL-12](../manifesto/02-nfrs.md) |
+| Capacity model | ingest headroom with no silent drop and zero chain breaks; hot tier then cold tier to the retention floor | [NFR-PERF-10](../manifesto/02-nfrs.md), [NFR-COMP-01](../manifesto/02-nfrs.md) |
+| Recovery | no event loss; the SIEM bridge replays from the durable store on recovery | [NFR-REL-03](../manifesto/02-nfrs.md) |
+| Upgrade / rotation | OCSF schema upgrade with N-1 backward-compat; envelope-signing-key rotation per the key-custody floor | [NFR-MAINT-AUDIT-SCHEMA](../manifesto/02-nfrs.md) |
+
+Backpressure behaviour is spill, not block: events commit to the durable bus and the file-system sink before ack, so a stalled SIEM sink fills the bus toward its bound and replays on recovery; sources are never blocked and events are never silently dropped. The measurable end-to-end saturation / spill target is open ([#150](https://github.com/Wide-Moat/open-computer-use/issues/150)).
+
+**Shelf delta** (from [`05-c4-container.md`](../05-c4-container.md) §5 and [`02-trust-boundaries.md`](../02-trust-boundaries.md) §10). Minimal shelf: file-system sink only; the Merkle-head submission envelope is signed with a host-local key. Full shelf: an opt-in OCSF bridge to a customer SIEM as a fan-out; the same envelope signed with an HSM-rooted key when customer KMS is wired. The boundary properties — host-attested source identity, hash-linked append-only chain, write-before-ack, per-source fairness — hold on both shelves; only the sink substrate and the envelope signer change. The durable-bus product and the WORM cold-tier substrate are pluggable seams behind the OCU-owned local commit, not decided in this component: [ADR-0009](../adr/0009-audit-pipeline-pluggable-by-contract.md) sets the build/buy boundary (each seam a contract with a solo-reference default), and the per-seam transport detail stays open ([#150](https://github.com/Wide-Moat/open-computer-use/issues/150), [#151](https://github.com/Wide-Moat/open-computer-use/issues/151)).
+
+## Open questions
+
+1. SIEM-bridge transport and end-to-end backpressure: the pluggable-sink contract needs a measurable transport and saturation-spill target — [#150](https://github.com/Wide-Moat/open-computer-use/issues/150).
+2. Transparency-log publishing path (auth, retry, RPO if the log is unreachable) and whether the minimal shelf publishes at all — [#151](https://github.com/Wide-Moat/open-computer-use/issues/151).
+3. Out-of-band evidence for in-sandbox actions and host-attested binding of the OCSF source at ingestion (the P7-S1 / P7-R2 residual) — [#181](https://github.com/Wide-Moat/open-computer-use/issues/181).
+4. Per-source retention-budget cap and forensic-dilution-within-budget at the audit fan-in — [#188](https://github.com/Wide-Moat/open-computer-use/issues/188).
+5. ComputeMetering / SaturationEvent payload schema: OCSF v1.x ships no metering or saturation class, so the channel surface is stable but the payload `$ref` is held TBD, split off [#150](https://github.com/Wide-Moat/open-computer-use/issues/150) so the Published-Language gap is tracked separately from SIEM-bridge transport ([#241](https://github.com/Wide-Moat/open-computer-use/issues/241)).

package/docs/architecture/diagrams/02-trust-boundaries.mmd

@@ -0,0 +1,111 @@
+%% SPDX-License-Identifier: FSL-1.1-Apache-2.0
+%% Copyright (c) 2025 Open Computer Use Contributors
+%% Canonical Layer 3 trust-zone diagram. Referenced from docs/architecture/02-trust-boundaries.md §5.
+%% Convention: solid subgraph border = always present; dashed border = optional configuration.
+%% Palette (project convention): red untrusted / amber semi-trusted / green trusted / blue isolated.
+
+%%{init: {"theme": "neutral"} }%%
+flowchart LR
+
+    %% ─── external actors (untrusted; rendered as plain nodes, not subgraphs) ───
+    MCPC[MCP client<br/>external actor]:::ext
+    IDP[Customer IdP<br/>OIDC]:::extOpt
+    LLM[LLM upstream]:::endpoint
+    OBJ[Customer object store]:::endpoint
+    CPROXY[Customer outbound proxy]:::extOpt
+    ICAP[Customer DLP-ICAP service]:::extOpt
+    SIEM[Customer SIEM]:::extOpt
+    KMS[Customer KMS / HSM]:::extOpt
+    SDS[SDS source<br/>static file solo · customer store enterprise]:::extOpt
+    SOAR[SOAR<br/>signed webhook + admin API]:::extOpt
+    OPER[Admin / Operator<br/>PAM-JIT human]:::ext
+    TLOG[Transparency log]:::extOpt
+
+    %% ─── our zones ───
+    %% Control plane is one trust-zone exposing two interfaces: an agent-facing
+    %% MCP surface (tool calls) and an operator/lifecycle surface (session
+    %% lifecycle, quota, kill-switch). The kill-switch is reachable only on the
+    %% operator surface — never over MCP. The two-container split is a Layer 6
+    %% concern; here they are one zone.
+    subgraph CP[Control plane]
+        ORCH[orchestrator + session lifecycle<br/>MCP interface · agent-facing<br/>operator interface · lifecycle + kill-switch<br/>kill-switch not reachable over MCP]
+    end
+
+    subgraph STORE[Storage broker]
+        SB[host-side storage broker<br/>guest speaks file ops, not the object-store protocol<br/>broker is the object-store client · signs its own requests<br/>holds the backend credential · guest holds no backend key<br/>content inspection here on plaintext, before signing]
+    end
+
+    subgraph COMPUTE[Compute plane]
+        VM[session sandbox<br/>guest agent PID 1<br/>runc minimal · gVisor full · microVM post-v1<br/>one per session · ephemeral<br/>rootfs + tooling = read-only, host-attached at boot/restore]
+    end
+
+    %% Posture is the §7 ladder, not two modes; injection at the egress-wide-bump rung. See ADR-0007.
+    subgraph EDGE[Egress trust-edge]
+        PROXY[egress proxy<br/>posture ladder: deny-all · transparent · egress-wide bump · external SDS<br/>bump default when an upstream credential is configured<br/>per-SNI leaf from per-deployment CA · Envoy data plane + SDS minter<br/>DLP-ICAP is a bump-rung config · egress allow-list · deny-by-default]
+    end
+
+    subgraph AUDIT[Audit pipeline]
+        BUS[durable bus + hash-chained store<br/>OCSF v1.x events<br/>host-local signing on minimal shelf<br/>HSM-rooted on full shelf<br/>compute-time metering]
+    end
+
+    %% ─── inbound edges ───
+    %% MCP arrives on the agent-facing interface; operator + SOAR arrive on the
+    %% operator/lifecycle interface. Distinct auth; the kill-switch lives only
+    %% on the latter.
+    MCPC -->|"MCP authz spec · agent-facing<br/>audience-validated"| ORCH
+    IDP -->|OIDC| ORCH
+    OPER -->|"PAM-JIT credential · operator interface<br/>NFR-COMP-29"| ORCH
+    SOAR <-->|"signed webhook + admin API · operator interface"| ORCH
+
+    %% ─── internal edges (encrypted in transit; NFR-SEC-37) ───
+    ORCH -->|"Session JWT on WS<br/>bound to container_name<br/>TTL ≤60min · rotated"| VM
+    ORCH -->|"session resource handle<br/>scopes the mount · NFR-SEC-25"| SB
+    SDS -->|"upstream credential over SDS<br/>source owns mint · rotate · revoke<br/>NFR-SEC-23 · ADR-0005 · ADR-0007"| PROXY
+
+    %% ─── storage-mount path (second guest-data boundary: in vs out) ───
+    %% Distinct from egress. The guest reads/writes mutable user-data through a
+    %% mount the broker serves; the guest holds only a session-scoped resource
+    %% handle (e.g. filesystem_id), never the storage backend credential. The
+    %% broker's own backend traffic leaves on a storage-dedicated lane at the
+    %% Egress trust-edge, distinct from the guest egress lane (NFR-SEC-85).
+    %% Mount substrate (FUSE / virtio-fs / 9p) is component-spec.
+    SB -->|"mount · session resource handle only<br/>no backend credential in guest<br/>NFR-SEC-25"| VM
+    SB -->|"backend traffic · broker-signed · storage lane (NFR-SEC-85)<br/>allow-list-only, no TLS termination<br/>signature stays intact"| PROXY
+
+    %% ─── revoke channel (denylist; independent of IdP reachability) ───
+    %% Compute plane gets a direct denylist check (Session JWT TTL ≤60min needs it);
+    %% Egress trust-edge revoke = the edge stops injecting upstream auth for a
+    %% revoked session; the SDS source owns the credential's own TTL, so no
+    %% direct ORCH→PROXY edge.
+    ORCH -.->|"revoke (denylist check)<br/>NFR-SEC-04 ≤5 min"| VM
+
+    %% ─── egress edges ───
+    VM -->|"single outbound path<br/>no long-lived upstream secret in request<br/>credential attached at edge on a presented scoped credential<br/>NFR-SEC-27 · ADR-0007"| PROXY
+    PROXY -->|"strict TLS validation<br/>upstream auth injected (SDS-delivered)<br/>fail-closed"| LLM
+    PROXY -->|"object-store leg is the broker's, not the guest's<br/>broker-signed · allow-list-only, no TLS termination<br/>signature intact · fail-closed"| OBJ
+    PROXY -.->|"chained-proxy contract<br/>optional"| CPROXY
+    PROXY -.->|"ICAP req-mod / resp-mod<br/>optional"| ICAP
+
+    %% ─── audit edges (every named zone emits OCSF events) ───
+    ORCH -->|OCSF events| BUS
+    SB -->|OCSF events| BUS
+    VM -->|OCSF events| BUS
+    PROXY -->|OCSF events| BUS
+
+    %% ─── audit egress ───
+    BUS -.->|"OCSF bridge<br/>optional"| SIEM
+    BUS -.->|"daily Merkle head<br/>submission envelope"| TLOG
+
+    %% ─── KMS path (optional, full-capability shelf only) ───
+    SB -.->|"PKCS#11 / KMIP"| KMS
+    BUS -.->|"PKCS#11 / KMIP<br/>signing on full shelf"| KMS
+
+    %% ─── styling (project palette: red untrusted / amber semi-trusted / green trusted / blue isolated) ───
+    classDef ext fill:#fdecea,stroke:#c0392b,stroke-width:1px;
+    classDef extOpt fill:#fdecea,stroke:#c0392b,stroke-dasharray: 5 5;
+    classDef endpoint fill:#fafafa,stroke:#9e9e9e,stroke-dasharray: 2 2;
+    style CP fill:#e8f5e9,stroke:#1e7e34,stroke-width:1px;
+    style STORE fill:#e8f5e9,stroke:#1e7e34,stroke-width:1px;
+    style COMPUTE fill:#e3f2fd,stroke:#0d47a1,stroke-width:3px;
+    style EDGE fill:#fff4e5,stroke:#b8860b,stroke-width:1px;
+    style AUDIT fill:#e8f5e9,stroke:#1e7e34,stroke-width:1px;

package/docs/architecture/diagrams/06-threat-model.mmd

@@ -0,0 +1,41 @@
+%% SPDX-License-Identifier: FSL-1.1-Apache-2.0
+%% Copyright (c) 2025 Open Computer Use Contributors
+%% Layer 7 STRIDE overlay on the Layer 6 container DFD. Referenced from docs/architecture/06-threat-model.md.
+%% Residual (PARTIAL) threats annotated per element; the DFD itself is canonical in c4-container.mmd (not redrawn).
+%%{init: {"theme": "neutral"} }%%
+flowchart LR
+    PEER["MCP caller"]:::ext
+    OPER["Operator"]:::ext
+    DPC["Data-plane client<br/>(SPA / headless)"]:::ext
+    SDS["SDS source<br/>(static file / customer store)"]:::ext
+    subgraph OCU["Open Computer Use — STRIDE overlay"]
+        MCPG["MCP gateway"]
+        CTRL["Control / operator API"]
+        STORE["Storage broker"]
+        VM["Session sandbox [1..N]"]
+        EDGE["Egress trust-edge proxy"]
+        AUD["Audit pipeline"]
+    end
+    PEER --> MCPG
+    OPER --> CTRL
+    MCPG --> CTRL
+    CTRL --> VM
+    STORE --> VM
+    DPC -->|"north face (F11)"| STORE
+    VM --> EDGE
+    SDS -->|"credential over SDS"| EDGE
+    STORE --> EDGE
+    VM -.OCSF.-> AUD
+    EDGE -.OCSF.-> AUD
+
+    PEND["NFR specified, impl tracked<br/>#148 #149 #150 #176 #181 #182<br/>#183 #184 #185 #186 #187 #188<br/>#197 #217 #218"]:::pend
+    MCPG -. P1-I1 P1-E2 .-> PEND
+    CTRL -. P2-R1 .-> PEND
+    STORE -. "P4-D1 (south) · P4-S3 P4-T3 P4-I3 P4-D3 P4-R2 P4-E3 (north)" .-> PEND
+    VM -. P5-T1 P5-I1 P5-I2 P5-I3 P5-R1 .-> PEND
+    EDGE -. P6-I1 P6-I2 P6-D1 P6-D3 P6-E2 P6-E3 .-> PEND
+    AUD -. P7-S1 P7-R2 P7-T2 P7-R3 P7-T3 .-> PEND
+
+    classDef ext fill:#fdecea,stroke:#c0392b,stroke-width:1px;
+    classDef pend fill:#fff8e1,stroke:#f39c12,stroke-width:2px,color:#7a5c00;
+    style OCU fill:#e8f5e9,stroke:#1e7e34,stroke-width:3px;

package/docs/architecture/diagrams/08-contracts.mmd

@@ -0,0 +1,47 @@
+%% SPDX-License-Identifier: FSL-1.1-Apache-2.0
+%% Copyright (c) 2025 Open Computer Use Contributors
+%% Layer 8 (Contracts) overlay. Referenced from docs/architecture/08-contracts.md.
+%% Same six containers as diagrams/c4-container.mmd; edge labels carry the CONTRACT FORMAT
+%% on each crossing, not the token/protocol. Zone shading is not redrawn — see Layer 3/6.
+%% Solid = OCU-defined or conform-inbound; dashed = external party owns the wire format.
+
+%%{init: {"theme": "neutral"} }%%
+flowchart LR
+
+    PEER["MCP-speaking caller"]:::ext
+    OPER["Operator (PAM-JIT)"]:::ext
+    UPSTREAM["Outbound endpoints"]:::ext
+    SDS["SDS source<br/>(static file / customer store)"]:::extOpt
+    SINK["Customer SIEM / SOAR /<br/>transparency log"]:::extOpt
+    DPC["Data-plane client<br/>(SPA / headless)"]:::ext
+
+    subgraph OCU["Open Computer Use"]
+        MCPG["MCP gateway"]
+        CTRL["Control / operator API"]
+        STORE["Storage broker"]
+        VM["Session sandbox [1..N]"]
+        EDGE["Egress trust-edge"]
+        AUD["Audit pipeline"]
+    end
+
+    PEER -->|"MCP JSON-Schema"| MCPG
+    OPER -->|"OpenAPI 3.1"| CTRL
+    MCPG -->|"Protobuf / gRPC"| CTRL
+    CTRL -->|"WebSocket (PTY+CDP)"| VM
+    STORE -->|"file-op mount (HTTP+JSON)"| VM
+    DPC -->|"OpenAPI 3.1 (file/artifact API)"| STORE
+    VM -->|"network policy"| EDGE
+    SDS -.->|"Envoy SDS (gRPC xDS)"| EDGE
+    STORE -->|"network policy"| EDGE
+    EDGE -.->|"external backend protocol"| UPSTREAM
+
+    MCPG -->|"AsyncAPI 3.0 / OCSF"| AUD
+    CTRL -->|"AsyncAPI 3.0 / OCSF"| AUD
+    STORE -->|"AsyncAPI 3.0 / OCSF"| AUD
+    VM -->|"AsyncAPI 3.0 / OCSF"| AUD
+    EDGE -->|"AsyncAPI 3.0 / OCSF"| AUD
+    AUD -.->|"AsyncAPI 3.0 / OCSF"| SINK
+
+    classDef ext fill:#fdecea,stroke:#c0392b,stroke-width:1px;
+    classDef extOpt fill:#fdecea,stroke:#c0392b,stroke-dasharray: 5 5;
+    style OCU fill:#e8f5e9,stroke:#1e7e34,stroke-width:3px;

package/docs/architecture/diagrams/c4-container.mmd

@@ -0,0 +1,59 @@
+%% SPDX-License-Identifier: FSL-1.1-Apache-2.0
+%% Copyright (c) 2025 Open Computer Use Contributors
+%% Canonical Layer 6 (C4 Container) diagram. Referenced from docs/architecture/05-c4-container.md.
+%% Role names only — no technology names (per CLAUDE.md Diagrams). Tech choice lands in component specs under components/.
+%% Six containers across five Layer-3 trust zones: the Control plane splits into an agent-facing
+%% MCP gateway and an operator/lifecycle API (the kill-switch lives only on the latter); the other
+%% four zones map 1:1. Substrate differs by shelf (see 05-c4-container.md §5); the count does not.
+%% Palette (project convention): red untrusted / green trusted. Amber/blue trust-zone shading is Layer 3 only.
+
+%%{init: {"theme": "neutral"} }%%
+flowchart LR
+
+    %% ─── external (drawn for orientation; contracts in 03-c4-context.md §4) ───
+    PEER["MCP-speaking caller<br/>(runs the loop)"]:::ext
+    OPER["Operator<br/>(PAM-JIT human)"]:::ext
+    FILE["Data-plane client<br/>(OCU SPA · file/artifact API)"]:::extOpt
+    UPSTREAM["Outbound endpoints<br/>(LLM · object store · internal API)"]:::ext
+    SINK["Customer SIEM / SOAR /<br/>transparency log"]:::extOpt
+    SDS["SDS source<br/>(static file solo · customer store enterprise)"]:::extOpt
+
+    %% ─── containers inside the system under design ───
+    subgraph OCU["Open Computer Use"]
+        MCPG["MCP gateway<br/>agent-facing tool-calls · metadata-only"]
+        CTRL["Control / operator API<br/>lifecycle · quota · kill-switch"]
+        STORE["Storage broker<br/>object-store client · signs own requests<br/>guest mount (south) + SPA · file/artifact API · preview (north)"]
+        VM["Session sandbox [1..N]<br/>guest agent = PID 1 · one per session"]
+        EDGE["Egress trust-edge proxy<br/>single outbound path · allow-list<br/>edge-inject via Envoy SDS (Envoy data plane + SDS minter)"]
+        AUD["Audit pipeline<br/>durable bus · hash-chained store"]
+    end
+
+    %% ─── inbound (two distinct surfaces of the Control plane) ───
+    PEER -->|"MCP authz spec"| MCPG
+    OPER -->|"PAM-JIT credential · operator-only ingress"| CTRL
+    MCPG -->|"session create / status<br/>service identity"| CTRL
+
+    %% ─── control + storage reach the guest host-side (host dials, guest listens; NFR-SEC-43) ───
+    CTRL -->|"Session JWT bound to container_name<br/>rotated · host dials guest"| VM
+    STORE -->|"mount · resource handle (filesystem_id)"| VM
+    FILE -.->|"SPA · file/artifact API (north)<br/>embed token → first-party session · bytes direct"| STORE
+
+    %% ─── egress: guest carries no long-lived upstream secret; on injection-needing legs the edge
+    %%     receives the credential over SDS and injects at the egress-wide-bump rung (see 05 §3, §6; ADR-0007) ───
+    VM -->|"single outbound · no long-lived upstream secret"| EDGE
+    SDS -->|"upstream credential over SDS<br/>source owns mint/rotate/revoke (bump rung)"| EDGE
+    STORE -->|"backend request · broker-signed · storage lane (NFR-SEC-85)<br/>allow-list-only · signature intact"| EDGE
+    EDGE -->|"injection-needing leg: upstream auth injected (bump rung)"| UPSTREAM
+
+    %% ─── audit fan-in (every source container emits OCSF; the pipeline is the sink) ───
+    MCPG -->|OCSF| AUD
+    CTRL -->|OCSF| AUD
+    STORE -->|OCSF| AUD
+    VM -->|OCSF| AUD
+    EDGE -->|OCSF| AUD
+    AUD -.->|"OCSF bridge<br/>full shelf"| SINK
+
+    %% ─── styling (project palette) ───
+    classDef ext fill:#fdecea,stroke:#c0392b,stroke-width:1px;
+    classDef extOpt fill:#fdecea,stroke:#c0392b,stroke-dasharray: 5 5;
+    style OCU fill:#e8f5e9,stroke:#1e7e34,stroke-width:3px;

package/docs/architecture/diagrams/c4-context.mmd

@@ -0,0 +1,46 @@
+%% SPDX-License-Identifier: FSL-1.1-Apache-2.0
+%% Copyright (c) 2025 Open Computer Use Contributors
+%% Canonical Layer 4 (C4 Context) diagram. Referenced from docs/architecture/03-c4-context.md.
+%% Convention: solid border = present on the minimal-capability shelf; dashed border = not on the minimal shelf by default (per-actor optionality in 03-c4-context.md §4).
+%% Palette (project convention): red untrusted / green trusted (amber + blue zones apply at Layer 3 only).
+
+%%{init: {"theme": "neutral"} }%%
+flowchart LR
+
+    %% ─── inbound peers (any MCP-speaking caller; REST is a fallback) ───
+    PEER[MCP-speaking peer<br/>n8n · Open WebUI · custom MCP client]:::ext
+    OPER[Admin / Operator<br/>PAM-JIT human]:::ext
+    FILE[Data-plane client<br/>OCU SPA · file/artifact API]:::extOpt
+
+    %% ─── the system under design ───
+    subgraph OCU[Open Computer Use]
+        BOX[Open Computer Use<br/>in-perimeter tool-execution platform]
+    end
+
+    %% ─── customer infrastructure (full-capability shelf; IdP required there, the rest optional) ───
+    IDP[Customer IdP<br/>SAML / OIDC]:::extOpt
+    KMS[Customer KMS / HSM<br/>PKCS#11 / KMIP]:::extOpt
+    SIEM[Customer SIEM]:::extOpt
+    CPROXY[Customer outbound proxy]:::extOpt
+    ICAP[Customer DLP-ICAP service]:::extOpt
+
+    %% ─── operations and assurance ───
+    SOAR[SOAR<br/>signed webhook + admin API]:::extOpt
+    TLOG[Transparency log]:::extOpt
+
+    %% ─── edges ───
+    PEER -->|"MCP authz spec<br/>audience-validated"| OCU
+    OPER -->|"PAM-JIT credential<br/>NFR-COMP-29"| OCU
+    FILE -.->|"embed UI · file/artifact API<br/>identity-bound · bytes direct"| OCU
+    SOAR <-.->|signed webhook + admin API| OCU
+    IDP -.->|SAML / OIDC| OCU
+    OCU -.->|"OCSF v1.x bridge<br/>optional"| SIEM
+    OCU -.->|"PKCS#11 / KMIP<br/>full-capability shelf"| KMS
+    OCU -.->|"chained-proxy contract<br/>optional"| CPROXY
+    OCU -.->|"ICAP req-mod / resp-mod<br/>optional"| ICAP
+    OCU -.->|"daily Merkle head<br/>submission envelope"| TLOG
+
+    %% ─── styling (project palette) ───
+    classDef ext fill:#fdecea,stroke:#c0392b,stroke-width:1px;
+    classDef extOpt fill:#fdecea,stroke:#c0392b,stroke-dasharray: 5 5;
+    style OCU fill:#e8f5e9,stroke:#1e7e34,stroke-width:3px;

package/docs/architecture/glossary.md

@@ -0,0 +1,172 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+---
+status: draft
+last-reviewed: 2026-05-30
+owner: "@Wide-Moat/architects"
+applies-to: next/v1
+---
+
+Canonical definitions for terms used across this architecture. Define a term here once; link to it from anywhere else. A term lands here when it appears in ≥ 2 documents.
+
+## Control plane
+
+Orchestrator and session lifecycle, exposing two interfaces of one zone: an agent-facing MCP interface (tool calls) and an operator/lifecycle interface (lifecycle, quota, kill-switch). The kill-switch is reachable only on the operator interface, never over MCP. Single instance per deployment. Holds no customer payload; metadata-only by design. Outbound to LLM and other upstream goes through the Egress trust-edge — the Control plane is not a model proxy. The agent-facing / operator split becomes two containers at Layer 6.
+
+Used in: [`02-trust-boundaries.md`](./02-trust-boundaries.md) §2, [`manifesto/02-nfrs.md`](./manifesto/02-nfrs.md).
+
+## Compute plane
+
+The session sandbox zone — one sandbox per session, lifecycle bound to the session, guest agent as PID 1. Substrate is set by the [Sandbox tier](#sandbox-tier) — `runc`, gVisor, or microVM — selected by `workload_trust_profile`, orthogonal to the [shelf](#capability-shelf): both shelves carry every tier the host supports. Cross-session network reachability disabled.
+
+Used in: [`02-trust-boundaries.md`](./02-trust-boundaries.md) §2, [`manifesto/02-nfrs.md`](./manifesto/02-nfrs.md).
+
+## Storage broker
+
+Host-side broker for the guest's mutable user-data mount. The guest speaks a file-operation interface (open / read / write / list) to the broker, not the object-store protocol; the broker is the object-store client and signs its own backend requests, so no middlebox rewrites a request signature. Holds the backend credential; the guest holds only a session-scoped resource handle (a `filesystem_id`), never the backend key. The broker's backend traffic traverses a storage-dedicated lane on the Egress trust-edge, distinct from the guest egress lane (NFR-SEC-85), in allow-list-only mode (no TLS termination) so the signature stays intact; content inspection, when required, runs at the broker on plaintext, before signing. It has a guest-facing interface (the mount) and governs an inbound data path, where the Egress trust-edge governs only outbound. Mount substrate (FUSE / virtio-fs / 9p) is a component-spec choice. The broker has two faces on one object-store client: a [south face](#south-face--north-face) (the guest mount) and a [north face](#south-face--north-face) (the file-artifact data plane for a [Data-plane client](#data-plane-client)).
+
+Used in: [`02-trust-boundaries.md`](./02-trust-boundaries.md) §2 / §7.1, [`manifesto/02-nfrs.md`](./manifesto/02-nfrs.md) NFR-SEC-25.
+
+## Data-plane client
+
+An external caller that reaches OCU's file-artifact data plane — the [Storage broker](#storage-broker) [north face](#south-face--north-face) — to upload, list, download, or preview-render files. It is either OCU's own authenticated SPA (embeddable cross-origin) or a headless caller of the file-artifact API; bytes flow client↔OCU directly, never through a calling peer and never to the object store. Distinct from the MCP caller (which drives the control plane) and the Operator (CLI / PAM-JIT). Absent in headless deployments.
+
+Used in: [`03-c4-context.md`](./03-c4-context.md) §4, [`05-c4-container.md`](./05-c4-container.md) §3-§4, [`06-threat-model.md`](./06-threat-model.md) §2, [`08-contracts.md`](./08-contracts.md) §1.
+
+## South face / north face
+
+The two faces of the one [Storage broker](#storage-broker) object-store client. The **south face** is the guest mount — a file-operation interface (open / read / write / list) the sandbox speaks, scoped by `filesystem_id`. The **north face** is the file-artifact data plane — OCU's HTTP file/artifact API and embeddable SPA, served on a dedicated file/UI ingress for a [Data-plane client](#data-plane-client), not the MCP listener. Both faces share the one backend credential and the one storage-lane backend leg (NFR-SEC-85); neither the guest nor the data-plane client holds a backend credential.
+
+Used in: [`02-trust-boundaries.md`](./02-trust-boundaries.md) §2, [`04-bounded-contexts.md`](./04-bounded-contexts.md) §3, [`05-c4-container.md`](./05-c4-container.md) §3-§4, [`08-contracts.md`](./08-contracts.md) §1.
+
+## Downloadable
+
+The third storage-authorization axis (beyond scope and intent): a per-object disposition the broker resolves at read, separating "may read" from "may remove from the sandbox." A non-downloadable object is readable or previewable in-session but yields no egress-eligible artifact; the disposition reaches the Egress trust-edge as a deny signal. The preview-not-download exfiltration control.
+
+Used in: [`02-trust-boundaries.md`](./02-trust-boundaries.md) §2, [`06-threat-model.md`](./06-threat-model.md) §3, [`08-contracts.md`](./08-contracts.md) §3, [`manifesto/02-nfrs.md`](./manifesto/02-nfrs.md) NFR-SEC-73.
+
+## Embed token
+
+A signed short-TTL token (OIDC-asserted, `exp ≤ 120 s`) the calling peer's backend mints so its already-authenticated user opens OCU's embeddable SPA cross-origin without re-entering credentials. The [north face](#south-face--north-face) verifies the token signature and expiry, then sets a first-party session; OCU mints nothing and no OCU upstream secret enters the browser.
+
+Used in: [`05-c4-container.md`](./05-c4-container.md) §3, [`06-threat-model.md`](./06-threat-model.md) §3, [`08-contracts.md`](./08-contracts.md) §3, [`manifesto/02-nfrs.md`](./manifesto/02-nfrs.md) NFR-SEC-82.
+
+## Egress trust-edge
+
+The single outbound zone. Every outbound request from the Compute plane goes through here. The guest holds no long-lived upstream secret (it may hold a short-lived session-scoped handle to a host-side mediator); the edge attaches the upstream authorization, received over Envoy SDS from a static file (solo) or a customer store (enterprise), on the re-originated leg at the egress-wide-bump rung (see [Egress posture](#egress-posture)). Injection is gated on a presented scoped credential carried by the request, never on network origin — a request presenting none receives none ([ADR-0007](./adr/0007-egress-auth-mechanism.md), the P6-E2 anti-pattern). Fail-closed: proxy unreachable → outbound traffic dropped.
+
+Used in: [`02-trust-boundaries.md`](./02-trust-boundaries.md) §2, [`manifesto/02-nfrs.md`](./manifesto/02-nfrs.md). Spelled `egress proxy` when referring to the component implementation; `Egress trust-edge` when referring to the zone.
+
+## Audit pipeline
+
+Durable bus + hash-chained store + bridges to customer sinks. Mandatory in code; sinks are pluggable. Distinct retention floor, RPO, and tamper-evidence properties from the Control plane, which is why it is drawn as its own zone.
+
+Used in: [`02-trust-boundaries.md`](./02-trust-boundaries.md) §2, [`manifesto/02-nfrs.md`](./manifesto/02-nfrs.md).
+
+## Capability shelf
+
+A configuration profile of one product. Two shelves:
+
+- **Minimal-capability shelf** — single-tenant, host-local Ed25519 signing keys, auto-generated self-signed CA, file-system audit sink, host-rooted local operator credential. The one-click solo install path. Spelled **solo / dev tier** in some Layer 3 prose and NFR rows; the two names denote the same shelf.
+- **Full-capability shelf** — customer HSM rooted, per-tenant SPIFFE trust domain, customer-CA-rooted egress, OCSF bridges to customer SIEM, customer-IdP-asserted operator identity. Spelled **hardened tier and above** in some Layer 3 prose and NFR rows; same shelf.
+
+Both shelves run the same binary; the difference is configuration plus presence of customer-supplied facilities (HSM, CA, SIEM bridge, IdP). Not a SKU split. The shelf is one axis; the [Sandbox tier](#sandbox-tier) (runtime) and the [Isolation tier](#isolation-tier-t0t3) (tenancy shape) are orthogonal axes — selecting a shelf does not pick the runtime.
+
+Used in: [`02-trust-boundaries.md`](./02-trust-boundaries.md) §2 / §8 / §10, [`manifesto/02-nfrs.md`](./manifesto/02-nfrs.md).
+
+## Isolation tier (T0…T3)
+
+Per-tenant deployment shape menu. Picks the substrate, not the invariants — boundary properties hold for every tier.
+
+- T0 logical — row-level filter, shared kernel.
+- T1 namespace — Kubernetes namespace + NetworkPolicy + RBAC + ResourceQuota.
+- T2 VPC / VNet — per-tenant VPC, no peering.
+- T3 dedicated cluster — dedicated control plane per tenant.
+
+Higher isolation tiers (dedicated hardware, customer-owned cage) are tracked as candidates in open question `arch/cross-tenant-isolation-grading`; promote when a named workload requires them.
+
+Used in: [`02-trust-boundaries.md`](./02-trust-boundaries.md) §4.
+
+## Sandbox tier
+
+The sandbox runtime ladder, picked by the workload's `workload_trust_profile`, never by data classification (AP-13). Distinct from the [Isolation tier](#isolation-tier-t0t3) (tenancy shape) and the [Capability shelf](#capability-shelf) (key custody / CA / sink).
+
+- `runc` — shared-kernel container; v1 default for the `trusted_operator` profile (one-click solo install).
+- `gVisor` (`runsc`) — user-space-kernel isolation; v1 hardened default for the `internal_workforce` profile.
+- microVM (hardware-virt; named example Firecracker) — post-v1, for the `untrusted` profile; tracked at [#161](https://github.com/Wide-Moat/open-computer-use/issues/161).
+
+Used in: [`manifesto/02-nfrs.md`](./manifesto/02-nfrs.md) §"Sandbox tier — workload-driven selection", [`02-trust-boundaries.md`](./02-trust-boundaries.md) §2.
+
+## Egress posture
+
+A ladder of rungs the Egress trust-edge runs at, chosen by what the deployment needs ([ADR-0007](./adr/0007-egress-auth-mechanism.md)):
+
+- **deny-all** — no outbound need; egress off.
+- **transparent pass-through** — proxy in path, does not terminate TLS, no CA; reaches unauthenticated endpoints only.
+- **egress-wide bump** — proxy terminates TLS at a per-deployment CA (auto-generated, public cert auto-injected into the sandbox trust store at start) and attaches the upstream credential on the re-originated leg; enables in-path content inspection (DLP-ICAP). The default rung once an upstream credential is configured.
+- **external SDS source** — enterprise: the credential lifecycle is owned by a customer store off-box.
+
+Bump is the default only when an upstream credential is configured, never imposed on a deployment that needs none, so the one-click solo path holds at every rung. DLP-ICAP is a configuration of the bump rung, not a separate rung.
+
+Used in: [`02-trust-boundaries.md`](./02-trust-boundaries.md) §7, [`manifesto/02-nfrs.md`](./manifesto/02-nfrs.md) NFR-FLEX-15.
+
+## Session JWT
+
+Per-session session-identity token issued by the Control plane to the guest agent, bound to `container_name`, TTL ≤ 60 min and rotated while the session is active. It proves session identity to the Control plane; it is not an upstream credential and never leaves toward an upstream. The only token the guest holds. The TTL is an anti-replay window, not a session length — session idle (≤15 min, NFR-SEC-40) and absolute (≤12 h, NFR-SEC-41) limits are separate. Distinct from the SDS-delivered upstream credential (attached by the Egress trust-edge, never the guest) and the generic internal RPC token (TTL ≤ 60 min, inter-component, host-side).
+
+Used in: [`02-trust-boundaries.md`](./02-trust-boundaries.md) §5 / §8 / §8.1, [`manifesto/02-nfrs.md`](./manifesto/02-nfrs.md) NFR-SEC-10/23/29.
+
+## Generic internal token
+
+Host-side service-to-service RPC token authenticating one internal component to another (Control plane ↔ Audit pipeline), TTL ≤ 60 min. It never reaches the guest and carries no operator scope or upstream credential. Distinct from the [Session JWT](#session-jwt) (guest-held, per session) and the SDS-delivered upstream credential (attached by the Egress trust-edge).
+
+Used in: [`02-trust-boundaries.md`](./02-trust-boundaries.md) §8, [`manifesto/02-nfrs.md`](./manifesto/02-nfrs.md) NFR-SEC-23.
+
+## OCSF
+
+Open Cybersecurity Schema Framework, v1.x JSON. The canonical audit-event schema we emit on the Audit pipeline. Bridges to SIEM transforms emit CEF / Elastic ECS / Chronicle UDM downstream.
+
+Used in: [`02-trust-boundaries.md`](./02-trust-boundaries.md) §5 / §10, [`manifesto/02-nfrs.md`](./manifesto/02-nfrs.md) NFR-MAINT-AUDIT-SCHEMA.
+
+## Transparency log
+
+External append-only log that the customer chooses (public, customer-private, or a Certificate-Transparency-style instance). The Audit pipeline submits the daily Merkle head of the hash-chained audit store; the log operator signs the Merkle head, we sign only the submission envelope. Provides tamper-evidence the customer can verify against an operator they trust.
+
+Used in: [`02-trust-boundaries.md`](./02-trust-boundaries.md) §3 / §8.1 / §10 / §12, [`manifesto/02-nfrs.md`](./manifesto/02-nfrs.md) NFR-SEC-03.
+
+## Bounded context
+
+A slice of the domain with its own consistent model and language. Distinct from a trust zone ([`02-trust-boundaries.md`](./02-trust-boundaries.md) §2 — a deploy / protection slice): a bounded context answers "which domain model is consistent here," a trust zone answers "where does it run and under what protection." The two do not map one-to-one. Classified core (built in-house, carries competitive value), supporting (built, not differentiating), or generic (integrated, not built).
+
+Used in: [`04-bounded-contexts.md`](./04-bounded-contexts.md).
+
+## Anti-corruption layer
+
+A translation boundary that keeps an external model from leaking into a context's own model. Lets a generic integration (customer IdP, secrets store, policy engine) be swapped without changing the core domain model. Spelled out in full; not abbreviated to "ACL" in diagrams, which collides with Access Control List.
+
+Used in: [`04-bounded-contexts.md`](./04-bounded-contexts.md).
+
+## Published Language
+
+A shared, documented schema two contexts agree on at their boundary; the emitter conforms to the schema, not to the consumer's internals. The OCSF event between Agent Execution and Compliance Evidence is the canonical instance ([OCSF](#ocsf)). Distinct from Conformist, where one context accepts an upstream's model without negotiation (the MCP authorization spec).
+
+Used in: [`04-bounded-contexts.md`](./04-bounded-contexts.md).
+
+## Customer/Supplier
+
+An upstream/downstream relationship where the downstream's needs shape the upstream's contract through negotiation — distinct from Conformist (no negotiation) and Anti-corruption layer (defensive translation). The Operator → Agent Execution PAM-JIT path is the instance: the operator's access needs are met by a negotiated contract, not by adopting an external model wholesale.
+
+Used in: [`04-bounded-contexts.md`](./04-bounded-contexts.md).
+
+## Open Host Service
+
+A context that publishes a protocol or endpoint through which many producers and consumers integrate, typically carrying a [Published Language](#published-language). Compliance Evidence is the canonical instance — fan-in of OCSF events from five trust zones, fan-out to multiple customer SIEMs. The Open Host Service is the door; the Published Language is the vocabulary.
+
+Used in: [`04-bounded-contexts.md`](./04-bounded-contexts.md).
+
+## Compute-time metering
+
+Per-session billing primitives emitted as audit events: CPU-min, RAM-GB-min, storage-GB-day, egress bytes, MCP-call count. Live on the Audit pipeline because they are part of the same hash-chained record stream.
+
+Used in: [`02-trust-boundaries.md`](./02-trust-boundaries.md) §2, [`manifesto/02-nfrs.md`](./manifesto/02-nfrs.md) NFR-COST-05.