Wide-Moat
diff --git a/‎.gitignore‎
Lines changed: 5 additions & 0 deletions b/‎.gitignore‎
Lines changed: 5 additions & 0 deletions
diff --git a/‎docs/architecture/02-trust-boundaries.md‎
Lines changed: 192 additions & 0 deletions b/‎docs/architecture/02-trust-boundaries.md‎
Lines changed: 192 additions & 0 deletions
diff --git a/‎docs/architecture/adr/0001-layer-0-gate-legacy-exclusion.md‎
Lines changed: 2 additions & 0 deletions b/‎docs/architecture/adr/0001-layer-0-gate-legacy-exclusion.md‎
Lines changed: 2 additions & 0 deletions
diff --git a/‎docs/architecture/diagrams/02-trust-boundaries.mmd‎
Lines changed: 90 additions & 0 deletions b/‎docs/architecture/diagrams/02-trust-boundaries.mmd‎
Lines changed: 90 additions & 0 deletions
diff --git a/‎docs/architecture/glossary.md‎
Lines changed: 90 additions & 3 deletions b/‎docs/architecture/glossary.md‎
Lines changed: 90 additions & 3 deletions
@@ -120,4 +120,9 @@ docs/future-architecture/research/REVIEW-*.md
 docs/future-architecture/research/CROSS-REVIEW-*.md
 docs/future-architecture/research/PLAN-CHECK-*.md
 docs/future-architecture/research/CONTRADICTION-CHECK-*.md
+docs/future-architecture/research/ADVISOR-*.md
+docs/future-architecture/research/NYQUIST-AUDIT-*.md
+docs/future-architecture/research/PATTERN-MAP-*.md
+docs/future-architecture/research/CONSOLIDATED-*.md
 docs/future-architecture/research/nfr-*.md
+docs/future-architecture/research/layer*.md
@@ -62,6 +62,8 @@ None directly. The legacy code's threats (root containers, XXE, SSRF via `urllib
 
 ## Amendments
 
+Each amendment names the discovery commit and the affected exclusion entries.
+
 ### 2026-05-24 — initial exclusion-list completion
 
 The first version of `.semgrepignore` shipped in commit `709db53` missed three legacy areas that the SAST gate scans:
 
@@ -0,0 +1,90 @@
+%% 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/>SAML / 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
+    SOAR[SOAR<br/>signed webhook + admin API]:::extOpt
+    OPER[Admin / Operator<br/>PAM-JIT human]:::ext
+    TLOG[Transparency log]:::extOpt
+
+    %% ─── our zones ───
+    subgraph CP[Control plane]
+        ORCH[orchestrator + RPC<br/>MCP server<br/>session lifecycle]
+    end
+
+    subgraph BROKER[Credential broker]
+        BR[per-VM secrets-injection<br/>HOST-side<br/>loopback / vsock / UDS<br/>delegated STS on full shelf]
+    end
+
+    subgraph COMPUTE[Compute plane]
+        VM[session sandbox<br/>guest agent PID 1<br/>container minimal · microVM full<br/>one per session · ephemeral]
+    end
+
+    subgraph EDGE[Egress trust-edge]
+        PROXY[egress proxy<br/>transparent pass-through default<br/>MITM customer-CA opt-in<br/>DLP-ICAP is MITM config<br/>MCP allow-list enforcement]
+    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 ───
+    MCPC -->|"MCP authz spec<br/>audience-validated"| ORCH
+    IDP -->|SAML / OIDC| ORCH
+    OPER -->|PAM-JIT SAML attr<br/>NFR-COMP-29| ORCH
+    SOAR <-->|signed webhook + admin API| ORCH
+
+    %% ─── internal edges (encrypted in transit; NFR-SEC-37) ───
+    ORCH -->|"Generic internal token<br/>host-side RPC<br/>session policy + scope<br/>TTL ≤60 min"| BR
+    ORCH -->|"Egress JWT on WS<br/>bound to container_name<br/>TTL ≤4h"| VM
+    BR -->|"Broker scoped-JWT<br/>vsock / UDS / loopback<br/>TTL ≤15 min"| VM
+
+    %% ─── revoke channel (denylist; independent of IdP reachability) ───
+    %% Compute plane gets a direct denylist check (Egress JWT TTL ≤4h needs it);
+    %% Egress trust-edge revoke is indirect via Credential broker scoped-JWT
+    %% non-reissue (TTL ≤15 min caps propagation), so no direct ORCH→PROXY edge.
+    ORCH -.->|"revoke (denylist check)<br/>NFR-SEC-04 ≤5 min"| VM
+
+    %% ─── egress edges ───
+    VM -->|"single outbound path<br/>network-bound identity<br/>NFR-SEC-27"| PROXY
+    PROXY -->|"strict TLS validation<br/>broker-issued credential<br/>fail-closed"| LLM
+    PROXY -->|"strict TLS validation<br/>broker-issued credential<br/>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
+    BR -->|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) ───
+    BR -.->|"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 BROKER 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;
@@ -2,12 +2,99 @@
 <!-- Copyright (c) 2025 Open Computer Use Contributors -->
 
 ---
-status: stub
+status: draft
 last-reviewed: 2026-05-24
 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. If a term is used in ≥ 2 documents, it belongs here.
+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.
 
-Terms are added when first used in two or more architecture documents, per the decision tree in `CLAUDE.md`.
+## Control plane
+
+Orchestrator, RPC surface, session lifecycle, MCP server. 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.
+
+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 container on the minimal-capability shelf, microVM on the full-capability shelf. Cross-session network reachability disabled.
+
+Used in: [`02-trust-boundaries.md`](./02-trust-boundaries.md) §2, [`manifesto/02-nfrs.md`](./manifesto/02-nfrs.md).
+
+## Credential broker
+
+Per-VM secrets-injection service. Host-side. Bound to loopback / vsock / UDS only. Holds the real upstream credentials; the guest never does. Issues scoped, short-lived tokens to the guest. Distinct from a customer PAM tool — when §02 NFR-COMP-29 says "PAM brokers", it means the customer's privileged-access-management tool, not this component.
+
+Used in: [`02-trust-boundaries.md`](./02-trust-boundaries.md) §2, [`manifesto/02-nfrs.md`](./manifesto/02-nfrs.md).
+
+## Egress trust-edge
+
+The single outbound zone. Every outbound request from the Compute plane goes through here. Network-bound identity (NFR-SEC-27): the fact that traffic arrived from the sandbox at all is the identity. Fail-closed: proxy unreachable → outbound traffic dropped, never bypassed. Configurable posture per [Egress posture](#egress-posture) entry.
+
+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. The one-click solo install path.
+- **Full-capability shelf** — customer HSM rooted, per-tenant SPIFFE trust domain, customer-CA-rooted egress, OCSF bridges to customer SIEM.
+
+Both shelves run the same binary; the difference is configuration plus presence of customer-supplied facilities (HSM, CA, SIEM bridge). Not a SKU split.
+
+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.
+
+## Egress posture
+
+The mode the Egress trust-edge runs in. Two modes:
+
+- **Transparent pass-through** — proxy in path, does not terminate TLS, no customer CA needed. Default.
+- **MITM-inspecting** — proxy terminates TLS at the customer-CA root; required for any in-path content inspection (DLP-ICAP, prompt-content classification). Opt-in.
+
+DLP-ICAP is a configuration of the MITM mode, not a third mode.
+
+Used in: [`02-trust-boundaries.md`](./02-trust-boundaries.md) §7, [`manifesto/02-nfrs.md`](./manifesto/02-nfrs.md) NFR-FLEX-15.
+
+## Egress JWT
+
+Per-session bearer token issued by the Control plane to the guest agent, bound to `container_name`, TTL ≤ 4 h. Distinct from the broker scoped-JWT (TTL ≤ 15 min, per-resource) and the generic internal RPC token (TTL ≤ 60 min, inter-component). The three TTL classes are independent commitments.
+
+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.
+
+## 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.
+
+## 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.