@mseep/open-computer-use 1.0.0

package/docs/future-architecture/gaps.md

@@ -0,0 +1,281 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+# Architecture Gap Analysis
+
+> **Pre-mortem inventory** of architecture topics that are either absent or only lightly addressed in [`architecture/`](./architecture/), [`adr/`](./adr/), and [`roadmap.md`](./roadmap.md). Captured **before** code meets reality, so each gap can be resolved (or explicitly deferred) on its own merits.
+>
+> This is **not** an ADR and **not** a roadmap edit. Phase pointers below are **suggestions**, not commitments. Tier-1 gaps are expected to graduate into their own ADRs / phase-research docs over time.
+
+## How to read this doc
+
+- **Status legend**
+  - **MISSING** — topic not addressed anywhere in the live spec.
+  - **LIGHT** — touched in one or two places but no architectural weight (no contract, no acceptance criteria, no rollback).
+  - **PRESENT** — explicitly named with a contract or acceptance hook in `architecture/` or `adr/`.
+- **Lands in phase** — the existing roadmap phase that is the most natural home for the work. Where no phase fits, the entry says so.
+- **Cross-cuts** — items that apply to every phase. They belong in invariants or CI policy, not a single phase row.
+- **External precedents** — projects worth studying before opening an ADR. These should turn into entries in [`references.md`](./references.md) and digests under [`research/`](./research/) when their gap is taken up.
+
+For phase context see [`roadmap.md`](./roadmap.md). For locked operational choices see [`antipatterns.md`](./antipatterns.md).
+
+---
+
+## A. Multi-tenancy beyond per-session
+
+The current isolation boundary is the **sandbox**. A tenant is an organisation that owns N users and M sessions. The tenant boundary is not defined.
+
+- **Tenant ≠ session.** Define the tenant model (org → users → sessions) as a first-class L4 entity.
+- **Fairness between tenants** on a shared cluster — noisy-neighbour case where one tenant drains every warm-pool slot.
+- **Per-tenant aggregate quotas** — concurrent sessions, MCP calls/min, storage GB, egress bytes/day. Per-sandbox quotas are insufficient.
+- **Per-tenant config overlay** — tenant A gets MCP tool set X with Chrome egress to `*.github.com`; tenant B gets set Y with egress only to `*.internal.bank`.
+- **Tenant-scoped audit** — auditor of bank A must not see events from bank B.
+
+**Status:** LIGHT. `architecture/02-layer4-control-plane.md` names `tenant_id` on the session router, per-tenant S3 buckets, and the k8s "namespace per tenant" idea, but org-level fairness, aggregate quotas, per-tenant tool overlays, and per-tenant audit scoping are not contracted.
+
+**Lands in phase:** deeper Phase 5 (`KubernetesProvider` is where tenant = namespace lives) with Phase-6 surface follow-ups (admin API for tenant CRUD, quotas).
+
+**External precedents:** Vault namespaces, Confluent Cloud multi-tenant model, Kubernetes Hierarchical Namespaces (HNC), Snowflake account model.
+
+---
+
+## B. Identity beyond OIDC
+
+OIDC is named in Phase 6. Enterprise-IT integration needs strictly more.
+
+- **SAML 2.0** — required by large enterprises. Distinct protocol, not free from OIDC.
+- **LDAP / Active Directory** direct — some legacy enterprises support nothing else.
+- **Service accounts** for machine-to-machine (customer CI/CD triggers our platform).
+- **RBAC granularity** — concrete roles (`template-admin`, `session-creator`, `audit-reader`, `secret-rotator`) and their permission matrices.
+- **Federated identity for self-hosted** — the customer's Keycloak / Okta / Ping is the IdP, we are only the consumer.
+- **Token caching & rotation policy** — explicit rotation cadence for access tokens, behaviour on revocation.
+
+**Status:** MISSING (SAML, LDAP/AD, service accounts, federated self-hosted, token-rotation policy) / LIGHT (RBAC granularity — listed as an L4 concern but no permission matrix exists; per-sandbox empty-RBAC ServiceAccount is documented in `architecture/07-security.md` but that is sandbox-scoped, not identity-scoped).
+
+**Lands in phase:** Phase 6 (Go control plane auth surface). RBAC matrix is a docs-only prerequisite that can land in Phase 0.5 follow-on.
+
+**External precedents:** Coder enterprise auth, GitLab self-hosted Omnibus, Authentik, Keycloak federation patterns.
+
+---
+
+## C. Compliance and audit immutability
+
+Audit append-only sink with ≥ 90 d retention is named in `architecture/07-security.md` and `architecture/10-observability.md`. Compliance posture is mentioned. Several pieces are still missing.
+
+- **Frameworks promised.** SOC 2 Type II, ISO 27001, HIPAA, PCI DSS — each carries distinct controls. Without an explicit choice this does not sell.
+- **Audit log immutability.** Write-once, no retroactive edit. S3 Object Lock / WORM storage. Phase 8 names the pipeline; immutability needs to be named with the same weight.
+- **Retention policy.** Financial sector ≥ 7 years; HIPAA ≥ 6 years; GDPR "no longer than necessary". The conflict has to be resolved explicitly.
+- **Data residency** as a hard guarantee. Tenant X data lives only in region Y. Architecturally this is **deployment topology**, not a template setting — a single control plane cannot serve tenants with different residency without full physical separation.
+- **Right to be forgotten (GDPR Art. 17)** — selective deletion of a user's data from every system **including the audit log** (conflicts with immutability — needs tombstoning).
+- **Session recording / lawful intercept** — a regulator may demand "show everything the agent did over period X" including screenshots, MCP calls, user input. A computed artefact.
+
+**Status:** PRESENT (SOC 2 / HIPAA / PCI named in `architecture/07-security.md`, append-only sink named in `07-security.md` + `10-observability.md`) / LIGHT (GDPR — ephemeral-by-default posture only, no Art. 17 deletion flow; ISO 27001 implied not mapped) / MISSING (data residency, retention-policy conflict resolution, lawful-intercept session recording).
+
+**Lands in phase:** first iteration in Phase 4 (secret broker — foundation for tenant-scoped secrets) and Phase 8 (audit immutability + retention). Data residency belongs in the future multi-region milestone (post Phase 10).
+
+**External precedents:** AWS GovCloud / FedRAMP boundary doc, Sentry Single Tenant compliance, Atlassian Trust Center as a public-facing template.
+
+---
+
+## D. Determinism and session replay
+
+- Can an agent session be **replayed 100 % accurately** for debugging? If the agent did something strange — full replay, or at least deterministic audit.
+- Persist every MCP call + screenshot in a format that **plays back** → 80 % of replay capability at a low cost.
+- **Time inside the sandbox** — does the agent see real wallclock or a frozen one? Some sandbox runtimes manipulate the clock for consistent caching and reproducibility.
+- **Random-seed control** — for skills that use randomness, fix the seed per session for replay.
+- **Audit-event ID** — UUIDv7 (timestamp-prefixed) is much easier for time-range queries than UUIDv4.
+
+**Status:** LIGHT. `architecture/07-security.md` covers CRNG reseed and wall-clock hardening on snapstart restore (anti-divergence), but session-replay debugging, deterministic time inside the sandbox, per-session random-seed control, and UUIDv7 audit IDs are not specified.
+
+**Lands in phase:** Phase 7 (Rust agent — capabilities + dual-port API are the natural home for replay primitives) + Phase 8 (audit pipeline — replay reads from this).
+
+**External precedents:** Mozilla rr (record/replay debugger), Replay.io, Antithesis (deterministic simulator), DVC for ML experiment determinism.
+
+---
+
+## E. Cost attribution and metering
+
+- **Per-session billing primitives** — CPU-min, RAM-GB-min, storage-GB-day, egress bytes, MCP-call count. Without these no internal showback and no external chargeback.
+- **Per-tenant aggregation** — realtime and period rollups.
+- **Cost annotation on every sandbox event** — for post-hoc analysis ("what burned Q3 budget").
+- **Threshold alerts** — tenant approaching quota → notification.
+
+**Status:** MISSING. `architecture/10-observability.md` only carries a RAM capacity-sizing formula. No billing primitives, no metering SDK, no cost tagging.
+
+**Lands in phase:** suggestion for a new **Phase 6.5** between Go control plane (Phase 6) and Rust agent (Phase 7). Not edited into `roadmap.md` in this PR.
+
+**External precedents:** Kubecost (k8s-native cost), AWS Cost Explorer API model, OpenCost (CNCF), Stripe metered-billing primitives.
+
+---
+
+## F. Disaster recovery — RTO/RPO explicit
+
+Phase 10 ships HA in a single region and multi-region foundations. The DR contract is not explicit.
+
+- **RTO (Recovery Time Objective)** — how long to come back up after a catastrophe? 5 minutes? An hour? A day?
+- **RPO (Recovery Point Objective)** — how much data can be lost on failover? Seconds? Minutes?
+- **Backup strategy for control-plane state** — KV snapshots, PostgreSQL backups, S3 versioning.
+- **Restore drills.** When was the last one. Without regular drills DR is fiction.
+- **Chaos engineering** — regular component kill, verify the system degrades rather than collapses.
+
+**Status:** LIGHT. Phase 10 snapshot/restore covers pause-resume and cross-AZ recovery; the DR runbook is mentioned but RTO/RPO targets, backup-strategy spec, drill cadence, and chaos engineering are not.
+
+**Lands in phase:** suggestion to rename Phase 10 to **"HA + DR"** with explicit RTO/RPO in the acceptance criteria. Not edited into `roadmap.md` in this PR.
+
+**External precedents:** Stripe DR game days (public write-ups), Netflix Chaos Monkey, AWS Well-Architected DR Pillar, Velero for k8s backups.
+
+---
+
+## G. Supply chain security
+
+- **SBOM (Software Bill of Materials)** for every image. Without an SBOM, US-government deployments under Executive Order 14028 are unreachable.
+- **Cosign / Sigstore signing** for every artefact — images, Helm charts, binary releases. Verify chain in kubectl admission.
+- **Continuous CVE scanning** — Trivy / Grype in CI per PR + daily against existing images.
+- **Reproducible builds** for the L1 agent — musl static-PIE, fixed timestamps, bit-by-bit identical builds. Rust fits well.
+- **Base-image hardening** — Chainguard / Wolfi distroless instead of Ubuntu. Order-of-magnitude fewer CVEs by default.
+
+**Status:** PRESENT (Cosign signing + admission verifier in `architecture/07-security.md`; templates reference by digest) / LIGHT (CVE risks per runtime listed but no automated scanning or IR flow; reproducible-build hints exist in `antipatterns.md` A22 — pinned versions + `SOURCE_DATE_EPOCH`, but not validated end-to-end) / MISSING (SBOM generation/distribution, base-image hardening).
+
+**Lands in phase:** cross-cut. Add to a Phase-0.5 follow-on as CI policy (SBOM emit, Trivy scan, reproducibility CI check). Base-image hardening fits Phase 7 (new image is rebuilt anyway).
+
+**External precedents:** SLSA framework, in-toto attestations, GUAC, CNCF TAG-Security guide.
+
+---
+
+## H. Air-gap and corporate networking
+
+- **Air-gapped deployment** — offline installer with a tarball of every image and chart. Must install with **no internet at all**.
+- **Corporate egress proxy** — `$HTTP_PROXY`, `$HTTPS_PROXY`, `$NO_PROXY` honoured everywhere. Custom CA bundle injection.
+- **Internal certificate authority** — customer supplies their own CA, our services accept it for mTLS.
+- **DNS via corp resolver** — cannot use `8.8.8.8`; must work with split-horizon DNS.
+- **Update channel in air-gap** — how patches are delivered. USB stick? Internal mirror registry?
+
+**Status:** MISSING.
+
+**Lands in phase:** suggestion for a dedicated future phase, gated on the first regulated-deployment customer. Not edited into `roadmap.md` in this PR.
+
+**External precedents:** Replicated KOTS (purpose-built for self-hosted), Anthos on-prem, GitLab Omnibus offline install, Anchore Enterprise.
+
+---
+
+## I. Operator UX (Day-2 ops)
+
+- **Synthetic transactions** — every deploy auto-runs a canary sandbox session with a known tool and checks the result. Fails the deploy if it does not work.
+- **Diagnostic bundle** — one command collects logs / configs / metrics / topology into a zip for support. Without it every support ticket is 3 hours of artefact gathering.
+- **SLO templates** — Prometheus rules + Grafana dashboards out of the box.
+- **Runbook catalogue** — "control plane unresponsive" → steps. "Sandbox stuck in Creating" → steps. Markdown in the repo.
+- **Upgrade tooling** — `helm upgrade` with pre/post hooks for migrations. One-command rollback.
+
+**Status:** PRESENT (SLO targets in `architecture/10-observability.md`; per-phase rollback windows in `roadmap.md`) / LIGHT (health probes named but no synthetic-transaction framework) / MISSING (diagnostic bundle, runbook catalogue, upgrade tooling beyond per-phase rollback).
+
+**Lands in phase:** cross-cut. Each phase should grow operator-UX artefacts in parallel rather than wait for a standalone phase.
+
+**External precedents:** Replicated Troubleshoot, Bitnami ops playbooks, GitLab "Database Lab" pattern, Sentry self-hosted ops.
+
+---
+
+## J. Versioning policy
+
+- **Backward compatibility** — does L1 v3 control plane work with an L4 v1 control plane? How many versions back are supported. Capabilities negotiation is already in the architecture, which is good.
+- **API deprecation policy** — announce N versions before removal, `Deprecated:` header on responses (Stripe-style).
+- **Database migrations** — forward-only without data loss. Rollback is a separate DR procedure. Atlas / Sqitch / golang-migrate.
+- **Live migration of sessions on upgrade** — if the control plane restarts, do live sandboxes keep running (because L1 is autonomous), or must the client reconnect? The contract must be written down.
+
+**Status:** LIGHT (capabilities negotiation in `architecture/05-layer1-guest-agent.md`; Phase 6 has a dual-run strategy section) / MISSING (formal API-deprecation policy, schema-migration tooling spec, session-survives-upgrade contract).
+
+**Lands in phase:** suggestion to add a new file `architecture/11-versioning.md` as the canonical versioning contract. Not created in this PR.
+
+**External precedents:** Stripe API versioning manifesto, Kubernetes Deprecation Policy, Tailscale upgrade-compatibility blog posts.
+
+---
+
+## K. Agentic-workload edge cases
+
+These are the core, and they tend to surface in production:
+
+- **Cancellation latency.** User clicks Stop. How many seconds before a `pip install` in flight is actually stopped? Graceful chain (`SIGTERM` → wait → `SIGKILL`) timeout has to be explicit.
+- **Long-running tools without HTTP timeout** — 30-minute web scrape, model training. WebSocket keepalive, progress events.
+- **Disconnection mid-tool** — tool still running, client dropped. What should L1 do? Wait + save result? Kill?
+- **Concurrent tool calls in one session** — legal or not? Two tools writing into the same directory?
+- **Tool output larger than the MCP message limit** — `dmesg` stdout or a giant JSON. Streaming, pagination, pre-signed URL — which one is chosen.
+- **Large files agent → user** — agent generated a 5 GB Parquet. S3 pre-signed URL or your transport? Cost implications.
+
+**Status:** LIGHT (`architecture/05-layer1-guest-agent.md` covers `SIGTERM`→`SIGKILL`, zombie reaping, dual-port API; the agent-in-microVM pattern handles zombies and long-running processes) / MISSING (explicit cancellation-latency SLO, long-running-tool heartbeat protocol, disconnection-mid-tool semantics, concurrent-tool-call contract, output-size flow control, large-artefact transport policy).
+
+**Lands in phase:** Phase 7 acceptance should be strengthened to cover the above. No new phase.
+
+**External precedents:** JupyterHub kernel restart semantics, gRPC streaming patterns, S3 multipart upload, Anthropic Computer Use public docs (cancellation behaviour is described there).
+
+---
+
+## L. MCP ecosystem (zone of uncertainty)
+
+- **MCP server discovery** — how the agent finds what is available. Static config vs runtime registry.
+- **Per-tenant MCP server set** — tenant A gets Jira/Confluence, tenant B gets Salesforce. Provisioning flow.
+- **Sandboxing MCP servers** — a third party wrote an MCP server. Do you trust it? Isolate it from agent state?
+- **Capability advertisement** — server X says "I can tool A with args B". Schema validation.
+
+**Status:** LIGHT (`architecture/02-layer4-control-plane.md` mentions tenant-scoped system prompt rendering and templates drive the tool set, but per-tenant MCP capability scoping is not contracted) / MISSING (MCP server discovery flow, sandboxing of MCP servers, capability schema validation).
+
+**Lands in phase:** parallel watching. The MCP spec itself is moving — do not lock the design under the current MCP API; expect movement.
+
+**External precedents:** Anthropic MCP spec (primary source). Few mature precedents — this is an open shape in the industry.
+
+---
+
+## M. Open-source community ops
+
+Before publishing:
+
+- **Security disclosure policy** — `SECURITY.md`, `security@your-domain`, GPG key, response SLA. Without it researchers file CVEs in public.
+- **Code of Conduct** — Contributor Covenant template.
+- **Maintainer access policy** — who can merge. Bus factor.
+- **Phone-home telemetry for OSS** — yes / no / opt-in. Default-on is a red flag for customers.
+- **Release cadence and LTS** — each minor supported for how long. Enterprise expectation is "N−2 versions receive security patches".
+- **Third-party builds** — do downstream distributions get to redistribute? Nuances with BUSL / FSL.
+
+**Status:** MISSING (no `SECURITY.md`, CoC, telemetry policy, release-cadence/LTS spec, redistribution policy in the architecture).
+
+**Lands in phase:** non-blocker. Pre-OSS-publish checklist; resolve before the first public marketing of the OSS edition.
+
+**External precedents:** CNCF security policy template, Kubernetes contributor ladder, Linux Foundation OSS Manager.
+
+---
+
+## Roadmap integration summary
+
+| Category | Tier | Suggested phase placement | New doc artefact (future) |
+|---|---|---|---|
+| A. Multi-tenancy beyond per-session | 1 | Deeper Phase 5 (tenant = namespace) + Phase 6 tenant CRUD | ADR on tenant model |
+| B. Identity beyond OIDC | 1 | Phase 6 (control plane auth) | ADR on auth surface; RBAC matrix in `architecture/02-*` |
+| C. Compliance & audit immutability | 1 | Phase 4 + Phase 8 (immutability), residency = post Phase 10 | `architecture/07-security.md` expansion; ADR per framework |
+| D. Determinism & session replay | 2 | Phase 7 + Phase 8 | Section in `architecture/05-*` and `architecture/10-*` |
+| E. Cost attribution & metering | 1 | Proposed **Phase 6.5** | `architecture/10-observability.md` billing-primitives section |
+| F. DR — RTO/RPO/backup/chaos | 1 | Rename Phase 10 → "HA + DR"; explicit RTO/RPO in acceptance | DR-runbook index |
+| G. Supply chain security | 1 | Cross-cut; add CI policy in a Phase-0.5 follow-on; base-image hardening in Phase 7 | SBOM/SLSA section in `architecture/07-security.md` |
+| H. Air-gap & corp networking | 2 | Dedicated future phase (customer-triggered) | Air-gap install guide |
+| I. Operator UX day-2 | 2 | Cross-cut; grows per phase | Runbook catalogue; diagnostic-bundle spec |
+| J. Versioning policy | 1 | New `architecture/11-versioning.md` | The file itself |
+| K. Agentic-workload edge cases | 1 | Strengthen Phase 7 acceptance | Acceptance-criteria update only |
+| L. MCP ecosystem | 2 | Parallel watching; revisit when MCP spec stabilises | None yet |
+| M. Open-source community ops | 3 | Pre-OSS-publish checklist | `SECURITY.md`, `CODE_OF_CONDUCT.md`, release-policy doc |
+
+**Tier 1** = critical for compliance / operations or for agentic-workload maturity at production scale.
+**Tier 2** = enterprise-adoption blockers that depend on a specific customer trigger.
+**Tier 3** = pre-public-launch hygiene.
+
+---
+
+## Out of scope (this document)
+
+- No phase reordering or scope edit in `roadmap.md`.
+- No new ADRs created — each Tier-1 gap is expected to graduate into its own ADR / phase-research doc when it is taken up.
+- No code, no config, no CI changes.
+
+## See also
+
+- [`roadmap.md`](./roadmap.md) — 12 phases, invariants, failure-modes menu, rollback runbook
+- [`antipatterns.md`](./antipatterns.md) — locked operational choices indexed by phase
+- [`architecture/`](./architecture/) — layer specs (L4 → L1)
+- [`adr/`](./adr/) — locked decisions
+- [`research/`](./research/) — reference-architecture digests

package/docs/future-architecture/phase-template.md

@@ -0,0 +1,123 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+# Phase-N template
+
+> Copy this file twice per phase: once as `phase-N-research.md` (Step 1: Research), once as `phase-N-plan.md` (Step 3: Plan). Leave this template untouched.
+
+## `phase-N-research.md` skeleton
+
+```markdown
+# Phase N research — <short title>
+
+**Status:** draft → in-review → signed-off
+**Owner:** <name>
+**Started:** YYYY-MM-DD
+**Signed-off:** YYYY-MM-DD
+
+## Context
+
+What this phase delivers per [roadmap.md](./roadmap.md#phase-N) in one paragraph. Why now.
+
+## Antipatterns scanned
+
+List every entry from [`antipatterns.md`](./antipatterns.md) phase-index row for Phase N. For each: "our choice still holds" OR "this phase needs to amend it because…". Don't skip any.
+
+## Options considered
+
+For each meaningful decision in this phase:
+
+### Decision X — <what>
+
+| Option | Pro | Con | Cost |
+|---|---|---|---|
+| A | … | … | … |
+| B | … | … | … |
+
+**Recommendation:** A. Because …
+
+(One block per meaningful decision. Targets: ≥ 1, typically 2–5.)
+
+## Reference repos read
+
+- `research/NN-foo.md` — what we took from it.
+- (additional external sources, if any)
+
+## Success metrics
+
+How will we know the phase shipped correctly? Concrete:
+- Latency: p99 < X ms on workload Y.
+- Test coverage: integration test Z passes against both PoC and target backend.
+- Observability: metric `foo_total` appears in dashboards.
+- No regression: existing tests `…/test_mcp_*.py` continue to pass.
+
+## Rollback plan
+
+If this phase causes a production incident:
+- Step 1: <flip flag / pin previous digest / re-point reverse-proxy>.
+- Step 2: <verify rollback effect via signal X>.
+- Estimated rollback time: < N minutes.
+
+## Open questions
+
+Anything that needs sign-off discussion before we proceed to `phase-N-plan.md`.
+
+## Sign-off
+
+- [ ] Owner reviewed.
+- [ ] Antipattern scan complete.
+- [ ] Rollback plan validated (dry-run if non-trivial).
+- [ ] Success metrics agreed.
+```
+
+## `phase-N-plan.md` skeleton
+
+```markdown
+# Phase N plan — <short title>
+
+**Based on:** `phase-N-research.md` (signed-off YYYY-MM-DD)
+**Branch:** `dev/future-architecture/phase-N-<topic>`
+
+## Day-1 checklist
+
+What touches code or config on the first commit. Concrete:
+- File X: refactor function Y into module Z (no behavior change).
+- File X: introduce flag `SANDBOX_PROVIDER` default `<old behavior>`.
+- Tests: add `tests/integration/test_phase-N_*.py`.
+
+## Atomic tasks
+
+(Output of `gsd-plan-phase`. Each task = one commit on the phase branch.)
+
+| # | Task | Files | Test | Reversibility |
+|---|---|---|---|---|
+| 1 | … | … | … | … |
+| 2 | … | … | … | … |
+
+## Acceptance gate
+
+Acceptance criteria from `roadmap.md` Phase N, repeated here verbatim. Tick each as it lands.
+
+- [ ] …
+- [ ] …
+- [ ] Compose PoC still works (run from clean clone, follow `docs/INSTALL.md`).
+- [ ] Antipatterns from Phase-N row of `antipatterns.md` still respected.
+
+## Phase retro
+
+Once merged, answer in 5 lines:
+- What was harder than expected?
+- What was easier?
+- Did this phase reveal a flaw in an earlier phase? (If yes → file follow-up per [roadmap.md § Failure modes](./roadmap.md#failure-modes--cross-phase-retros).)
+- Antipatterns to add to `antipatterns.md`?
+- One-line lesson for the next phase.
+```
+
+## Why a template
+
+- Forces the **antipattern scan** to happen before code (Step 1 of cadence is not skippable).
+- Forces explicit **rollback plan** before merge (Phase 6 dual-run lesson).
+- Forces **success metrics** before code (Phase 10 "measure first" invariant).
+- Forces a **retro** so cross-phase mistakes surface fast.
+
+The skeleton is intentionally short — fill it in 1–2 hours, not 1–2 days.

package/docs/future-architecture/references.md

@@ -0,0 +1,225 @@
+<!-- SPDX-License-Identifier: FSL-1.1-Apache-2.0 -->
+<!-- Copyright (c) 2025 Open Computer Use Contributors -->
+
+# External References
+
+> Catalog of open-source projects we either build on, learn from, or explicitly reject.
+>
+> Each entry carries: **License**, **Language**, **Role in our stack**, optional **To research** tag.
+> Entries tagged `to-research` are unresolved and must be evaluated during the relevant phase's research pass (see [`roadmap.md`](./roadmap.md) — per-phase research-then-sign-off cadence).
+
+---
+
+## Layer 1 — Guest agents (sandbox PID 1)
+
+### e2b-dev/infra — `envd`
+- **URL:** https://github.com/e2b-dev/infra/tree/main/packages/envd
+- **License:** Apache 2.0
+- **Language:** Go
+- **Role:** Comparison point for the L1 agent (Phase 7). API surface, gRPC streaming, image-build pipeline. Production at E2B Cloud.
+- **Notes:** Coupled to Firecracker networking and Nomad — port API ideas, not glue. With ADR-0002 now Rust, this is a comparison reference, not a stack reference.
+- **To research:** Phase 7.
+
+### kata-containers / src / agent
+- **URL:** https://github.com/kata-containers/kata-containers/tree/main/src/agent
+- **License:** Apache 2.0
+- **Language:** Rust
+- **Role:** Canonical kata-agent. PID 1 patterns, vsock transport, signal handling, `PR_SET_DUMPABLE=0` hardening.
+- **Notes:** OCI-shaped API — we want a product-aware API. Don't bolt Computer Use onto kata-agent itself.
+- **To research:** Phase 7 (compare Rust vs Go alternatives; feeds ADR-0002).
+
+### microsandbox / msb-agent
+- **URL:** https://github.com/microsandbox/microsandbox
+- **License:** Apache 2.0
+- **Language:** Rust
+- **Role:** Small, readable libkrun-based agent — good for learning the pattern.
+- **Notes:** Beta as of early 2026. Not production-ready.
+- **To research:** Phase 7 (skim for API ideas).
+
+---
+
+## Layer 2 — Sandbox runtimes
+
+### firecracker-microvm/firecracker
+- **URL:** https://github.com/firecracker-microvm/firecracker
+- **License:** Apache 2.0
+- **Language:** Rust
+- **Role:** Smallest attack surface, fastest cold start. AWS Lambda/Fargate foundation.
+- **Constraints:** Requires KVM + bare-metal (or nested virt). No virtio-fs, no GPU.
+- **To research:** Phase 9 (kata-fc alternative tier).
+
+### cloud-hypervisor/cloud-hypervisor
+- **URL:** https://github.com/cloud-hypervisor/cloud-hypervisor
+- **License:** Apache 2.0
+- **Language:** Rust
+- **Role:** Preferred microVM for Computer Use — supports virtio-fs, GPU passthrough, hot-plug. Used by AWS, Microsoft.
+- **Constraints:** Requires KVM + bare-metal. Larger codebase (~80K LOC) than Firecracker (~50K).
+- **To research:** Phase 9 (lead candidate for `kata-ch` tier).
+
+### kata-containers/kata-containers
+- **URL:** https://github.com/kata-containers/kata-containers
+- **License:** Apache 2.0
+- **Language:** Go + Rust
+- **Role:** k8s-native microVM runtime. RuntimeClass-driven, installed via `kata-deploy` DaemonSet. Backends: QEMU / Firecracker / Cloud Hypervisor.
+- **Status:** CNCF graduated.
+- **To research:** Phase 9.
+
+### google/gvisor
+- **URL:** https://github.com/google/gvisor
+- **License:** Apache 2.0
+- **Language:** Go
+- **Role:** Userspace kernel. Good for short-lived CPU-only scripts.
+- **Caveat:** **Not suitable for Chromium / Computer Use** — `docs/future-architecture/architecture/04-layer2-runtimes.md` explicitly rejects gVisor for our browser workloads (compat envelope too narrow). Use for non-browser tiers only.
+- **To research:** Phase 7 (validate as experimental tier for code-execution sandboxes).
+
+### nestybox/sysbox
+- **URL:** https://github.com/nestybox/sysbox
+- **License:** Apache 2.0 (CE) / commercial (EE)
+- **Language:** Go
+- **Role:** User-namespace + procfs/sysfs emulation. Allows root-in-container, Docker-in-Docker without `--privileged`. Default for the current Helm chart.
+- **Caveat:** Shares host kernel — vulnerable to kernel CVEs. Internal/trusted only.
+- **To research:** Phase 5 (already in use — formalize as the default L2 for the k8s provider).
+
+### opencontainers/runc
+- **URL:** https://github.com/opencontainers/runc
+- **License:** Apache 2.0
+- **Language:** Go
+- **Role:** Default dev/CI runtime. No isolation guarantees for untrusted code.
+
+---
+
+## Layer 3 — Orchestration
+
+### kubernetes-sigs/agent-sandbox
+- **URL:** https://github.com/kubernetes-sigs/agent-sandbox
+- **License:** Apache 2.0
+- **Language:** Go
+- **Role:** Basis for our future `KubernetesProvider` (Phase 5+). Provides `Sandbox`, `SandboxTemplate`, `SandboxClaim`, `SandboxWarmPool` CRDs.
+- **Status:** v0.1.1 (early but active, backed by Google + SIG Apps). Supports gVisor (default) and Kata.
+- **To research:** Phase 5 (mandatory deep-dive before writing K8sProvider; check CRD stability).
+
+### e2b-dev/infra
+- **URL:** https://github.com/e2b-dev/infra
+- **License:** Apache 2.0
+- **Language:** Go
+- **Role:** Reference for egress proxy (`packages/proxy`) and template builder (`packages/template-manager`).
+- **Caveat:** Nomad-coupled. Port ideas, don't fork wholesale.
+- **To research:** Phases 2, 9.
+
+### firecracker-microvm/firecracker-containerd
+- **URL:** https://github.com/firecracker-microvm/firecracker-containerd
+- **License:** Apache 2.0
+- **Language:** Go
+- **Role:** Firecracker via containerd CLI/API — intermediate option between raw FC and Kata.
+- **To research:** Phase 9 (snapshotter pattern feeds Phase 10).
+
+---
+
+## Layer 4 — Egress proxies
+
+### Michaelliv/agentbox
+- **URL:** https://github.com/Michaelliv/agentbox
+- **License:** MIT
+- **Language:** Python (asyncio aiohttp)
+- **Role:** Reference JWT-allowlist egress proxy (Phase 8). Working implementation — port to Go for production.
+- **Companion blog:** https://michaellivs.com/blog/sandboxed-execution-environment/
+- **To research:** Phase 8.
+
+### Tecnativa/docker-socket-proxy
+- **URL:** https://github.com/Tecnativa/docker-socket-proxy
+- **License:** Apache 2.0
+- **Role:** Pattern for filtering API access (HAProxy-based). Not directly useful unless legacy Docker-API consumer needs read-only access.
+
+---
+
+## Local sandboxing (research only)
+
+### anthropic-experimental/sandbox-runtime
+- **URL:** https://github.com/anthropic-experimental/sandbox-runtime
+- **License:** Apache 2.0 (research preview)
+- **Language:** Rust + bubblewrap (Linux) / seatbelt (macOS)
+- **Role:** Local-sandboxing reference. Useful patterns: FS allowlist, network restriction via seccomp BPF, macOS seatbelt profiles.
+
+---
+
+## Computer Use specific
+
+### e2b-dev/desktop
+- **URL:** https://github.com/e2b-dev/desktop
+- **License:** Apache 2.0
+- **Role:** GUI desktop env (Xfce) inside sandbox, VNC/RDP patterns. Comparable to our current CDP+ttyd setup.
+- **To research:** Phase 7 (compare Xfce/VNC vs our current CDP-only approach).
+
+### e2b-dev/surf
+- **URL:** https://github.com/e2b-dev/surf
+- **License:** Apache 2.0
+- **Role:** Computer Use agent reference — action loop, screenshot streaming.
+
+### Browser automation
+- **Playwright** (Microsoft, Apache 2.0) — already in our image
+- **Puppeteer** (Google, Apache 2.0)
+- **chromedp** (Go, MIT) — direct CDP; candidate if guest agent goes Go
+- **fantoccini** (Rust, MIT/Apache 2.0)
+
+For Computer Use we want direct CDP (not WebDriver) — fine-grained event injection + screencast. **To research (Phase 7):** Rust CDP options (`chromiumoxide`) vs raw CDP WebSocket passthrough in the Rust agent (per [ADR-0002](./adr/0002-guest-agent-language-go.md)).
+
+---
+
+## Explicitly rejected
+
+### Daytona (daytonaio/daytona)
+- **URL:** https://github.com/daytonaio/daytona
+- **License:** AGPL v3
+- **Reason:** AGPL contaminates downstream (incl. SaaS). Toxic for enterprise. See [ADR-0006](./adr/0006-no-agpl-no-bsl-dependencies.md).
+
+### HashiCorp Nomad
+- **License:** BSL — not OSI-open-source as of the HashiCorp re-license.
+- **Reason:** License-incompatible with our intended Apache-2.0 posture. Don't take a Nomad dependency. E2B's Nomad-specific code is reference-only.
+
+### Beam.cloud
+- **License:** Mixed (some Apache, control plane closed).
+- **Reason:** No isolation by default (containers, not microVM); control plane closed.
+
+### Modal
+- **License:** Closed, managed-only.
+
+---
+
+## Compatibility matrix (target combinations)
+
+| Agent | Hypervisor / Runtime | Orchestrator | Tier / Use case |
+|---|---|---|---|
+| current Python entrypoint + MCP server | runc / sysbox | Docker Compose | Today's PoC (Phase 0–5) |
+| current Python entrypoint + MCP server | sysbox | k8s (any) via our Helm chart | Phase 5 target |
+| **future Rust agent** | sysbox | k8s | Internal/trusted tier (Phase 7) |
+| future Rust agent | gVisor | k8s | Code-execution (non-browser) tier (Phase 7) |
+| future Rust agent | Kata + Cloud Hypervisor | k8s | Untrusted tier — Computer Use, public (Phase 9 — requires Phase 8 egress proxy) |
+| future Rust agent | Kata + Firecracker | k8s | Untrusted tier — fastest cold start (Phase 9 — requires Phase 8 egress proxy) |
+
+---
+
+## Lambda framing
+
+AWS Lambda recurs in this document and in the research digests (see [`research/05`](./research/05-firecracker.md)) as the design lineage behind Firecracker, behind the two-tier control split, and behind the snapshot-pool cold-start pattern we evaluate at Phase 10.
+
+**We are not deploying on Lambda or Fargate.** Open Computer Use targets 100–10K concurrent long-lived sandboxes on Kubernetes + Kata, not 10M serverless invocations. Sessions are multi-hour and stateful; Lambda's 15-minute cap and request-shaped billing fight every assumption.
+
+What we adopt from Lambda is **patterns**, bounded and named: (a) Firecracker as the smallest-attack-surface microVM tier, (b) two-tier control split (host router + in-guest supervisor) ported as L4↔L1 over vsock, (c) frozen-snapshot pool with block-device hot-swap as the Phase-10 cold-start optimization, (d) per-session VM isolation with no cross-tenant reuse. Everything else — the deployment substrate, the orchestrator, the billing model, the AWS product names — stays out.
+
+This question is closed by [ADR-0010](./adr/0010-lambda-as-inspiration-not-runtime.md). Future "should we go serverless?" debates should land on that ADR and not be re-opened here.
+
+---
+
+## License compatibility (our project)
+
+Project license: BUSL-1.1 (per `CLAUDE.md`) with MIT for select skills.
+
+Direct dependencies must be compatible — **safe:**
+- Apache 2.0, MIT, BSD-2/3, MPL 2.0, LGPL 2.1+ (link only)
+
+**Avoid:**
+- GPL v2 / v3 (copyleft)
+- AGPL v3 (Daytona)
+- BSL (Nomad post-HashiCorp)
+
+See [ADR-0006](./adr/0006-no-agpl-no-bsl-dependencies.md).