[ { "id": "01-system-context", "title": "Cloud Development Environment Platform — System Context", "layout": "context", "system": { "label": "CDE Platform", "sub": "workspaces on demand" }, "groups": [ { "side": "left", "title": "People", "nodes": [ { "id": "dev", "label": "Developer", "kind": "actor", "rel": "opens · resumes", "dir": "in" }, { "id": "admin", "label": "Tenant admin", "kind": "actor", "rel": "policy · seats", "dir": "in" }, { "id": "sre", "label": "Platform SRE", "kind": "actor", "rel": "drains · patches", "dir": "in" } ] }, { "side": "top", "title": "Machine consumers", "nodes": [ { "id": "agent", "label": "Coding agent runtime", "kind": "external", "rel": "API sandboxes", "dir": "in" }, { "id": "autom", "label": "Tenant automation", "kind": "external", "rel": "scripted starts", "dir": "in" } ] }, { "side": "right", "title": "Systems it depends on", "nodes": [ { "id": "git", "label": "Git forge", "kind": "external", "rel": "clone · push" }, { "id": "idp", "label": "Identity provider", "kind": "external", "rel": "OIDC · SCIM", "dir": "in" }, { "id": "pkg", "label": "Package registries", "kind": "external", "rel": "proxy only" } ] }, { "side": "bottom", "title": "Deliberately out of scope", "nodes": [ { "id": "cicd", "label": "CI/CD pipelines", "kind": "external" }, { "id": "prod", "label": "Production runtime", "kind": "external" }, { "id": "editor", "label": "The editor product", "kind": "external" } ] } ], "note": "The three systems at the bottom have no relationship drawn on purpose: this platform runs developer code, it does not ship it.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-10" } }, { "id": "02-high-level-architecture", "title": "High-Level Architecture — Request to Running Workspace", "layout": "flow", "chain": true, "align": "middle", "stages": [ { "title": "Ask", "nodes": [ { "id": "cl-dev", "label": "Editor client", "kind": "actor", "sub": "browser · SSH" }, { "id": "cl-agent", "label": "Agent client", "kind": "external", "sub": "headless API" } ] }, { "title": "Edge", "nodes": [ { "id": "edge", "label": "Regional edge", "kind": "integration", "sub": "Envoy · TLS · authz" }, { "id": "router", "label": "Session router", "kind": "app", "sub": "stateless" } ] }, { "title": "Admit", "nodes": [ { "id": "admit", "label": "Admission control", "kind": "decision", "sub": "quota · class shed" }, { "id": "place", "label": "Placement", "kind": "app", "sub": "late binding" } ] }, { "title": "Incarnate", "nodes": [ { "id": "hostagent", "label": "Host agent", "kind": "platform", "sub": "Firecracker" }, { "id": "warm", "label": "Warm pool", "kind": "app", "sub": "claimed, not built" } ] }, { "title": "Run", "nodes": [ { "id": "ws", "label": "Workspace microVM", "kind": "app", "sub": "own kernel · root" }, { "id": "ports", "label": "Forwarded ports", "kind": "integration", "sub": "private by default" } ] }, { "title": "Persist", "nodes": [ { "id": "snap", "label": "Snapshot store", "kind": "store", "sub": "content-addressed" }, { "id": "pre", "label": "Prebuild artefacts", "kind": "store", "sub": "per definition rev" } ] }, { "title": "Mediate", "nodes": [ { "id": "pep", "label": "Egress policy point", "kind": "security", "sub": "per workspace" }, { "id": "broker", "label": "Secret broker", "kind": "security", "sub": "minutes-long tokens" } ] } ], "edges": [ { "from": "snap", "to": "hostagent", "label": "lazy block fetch", "kind": "sync" }, { "from": "admit", "to": "cl-agent", "label": "retryable refusal", "kind": "error" } ], "note": "Agent creations are shed at the admission gate before human resumes are, which is the only place in the set where the two classes are treated differently.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-10" } }, { "id": "03-actors-and-journeys", "title": "Actors and Their Core Journeys", "layout": "actors", "groups": [ { "title": "Developers", "kind": "boundary", "actors": [ { "id": "a-dev", "label": "Returning developer", "sub": "250k daily", "goal": "Pick up yesterday's branch and keep typing — I should not have to notice that it stopped.", "journeys": [ { "id": "j-resume", "label": "Resume a workspace", "sub": "p95 ≤ 2.5 s" }, { "label": "Share a preview URL" } ] }, { "id": "a-new", "label": "New joiner", "sub": "day one", "goal": "Run the application before I have installed anything at all on this laptop.", "journeys": [ { "label": "First start from a prebuild", "sub": "p95 ≤ 25 s" } ] }, { "id": "a-rev", "label": "Reviewer", "sub": "per pull request", "goal": "Open the branch running, not a screenshot of it running.", "journeys": [ { "label": "Open a review workspace" } ] } ] }, { "title": "Machines", "kind": "cloud", "actors": [ { "id": "a-agent", "label": "Coding agent", "kind": "external", "sub": "65% of starts", "goal": "Give me forty disposable machines now, let me run unreviewed code in them, and take back a diff.", "journeys": [ { "id": "j-burst", "label": "Burst 40 sandboxes", "sub": "10× for 60 s" }, { "label": "Fork a developer's state" } ] }, { "id": "a-autom", "label": "Tenant automation", "kind": "platform", "sub": "scheduled", "goal": "Create and destroy workspaces from a script with no human in the loop.", "journeys": [ { "label": "Nightly integration sandbox" } ] } ] }, { "title": "The people who keep it up", "kind": "trust", "actors": [ { "id": "a-sre", "label": "Platform SRE", "sub": "1,800 hosts", "goal": "Patch every host this week without a single developer noticing that I did.", "journeys": [ { "id": "j-patch", "label": "Drain and patch a host" }, { "label": "Absorb a host loss" } ] }, { "id": "a-sec", "label": "Security engineer", "sub": "per tenant", "goal": "Be able to say that a compromised dependency reaches nothing but its own kernel.", "journeys": [ { "label": "Set an egress posture" } ] } ] }, { "title": "Who pays for it", "kind": "plain", "actors": [ { "id": "a-admin", "label": "Tenant admin", "sub": "seats · policy", "goal": "Set the idle timeout and the egress posture, and see what each costs me.", "journeys": [ { "label": "Set a spend ceiling" } ] }, { "id": "a-fin", "label": "Engineering finance", "sub": "monthly", "goal": "See cost per active workspace-hour, not a bill for a fleet.", "journeys": [ { "label": "Read the showback" } ] } ] } ], "note": "A coding agent is drawn as an actor, not as a feature: it starts two of every three workspaces and its goals contradict the developer's.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-10" } }, { "id": "04-journey-resume-the-workspace", "title": "Journey — Resuming Yesterday's Workspace", "layout": "journey", "actor": { "label": "Returning developer", "sub": "after a long lunch", "goal": "Carry on in the same files, with the dev server still up", "trigger": "Clicks the workspace, or just reconnects the editor", "success": "Typing inside 2.5 seconds, nothing reinstalled, nothing lost" }, "phases": [ { "title": "Open", "sub": "one click" }, { "title": "Wait", "moment": true }, { "title": "Work" }, { "title": "Walk away", "moment": true } ], "lanes": [ { "title": "What they do", "kind": "step", "cells": [ [ { "label": "Clicks the workspace" } ], [ { "label": "Watches the line" } ], [ { "label": "Edits, tests, pushes" } ], [ { "label": "Closes the tab" } ] ] }, { "title": "What the platform does", "kind": "system", "cells": [ [ { "label": "Authorises at the edge" }, { "label": "Finds the snapshot" } ], [ { "label": "Claims a host" }, { "label": "Restores memory" }, { "label": "Fetches blocks lazily" } ], [ { "label": "Snapshots every 5 min" } ], [ { "label": "Detects idle" }, { "label": "Hibernates" } ] ] }, { "title": "How it feels", "kind": "emotion", "levels": [ "Delighted", "Fine", "Frustrated" ], "points": [ 2, 0, 2, 1 ] }, { "title": "Where it hurts", "kind": "pain", "cells": [ [], [ { "label": "A cold resume reads as broken" } ], [], [ { "label": "Did it keep my work?" } ] ] }, { "title": "What answers it", "kind": "gain", "cells": [ [], [ { "label": "Memory image + lazy fetch" }, { "label": "Progress, not a spinner" } ], [ { "label": "5-minute RPO stated" } ], [ { "label": "Lost interval reported" } ] ] } ], "chain": true, "note": "The trough is the wait, and it is why the whole architecture is organised around resume rather than around create.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-10" } }, { "id": "05-journey-agent-sandbox-burst", "title": "Journey — Forty Agent Sandboxes at Once", "layout": "journey", "actor": { "label": "Coding agent", "sub": "headless · 7-min median life", "goal": "Forty disposable machines now, and a diff back from each", "trigger": "One task fans out across forty repositories", "success": "Every sandbox ran, or was refused in a way the orchestrator can retry" }, "phases": [ { "title": "Ask", "sub": "40 at once" }, { "title": "Get or wait", "moment": true }, { "title": "Run" }, { "title": "Hand back", "moment": true }, { "title": "Vanish" } ], "lanes": [ { "title": "What it does", "kind": "step", "cells": [ [ { "label": "POSTs 40 creates" } ], [ { "label": "Reads the verdict" } ], [ { "label": "Runs unreviewed code" } ], [ { "label": "Pushes a branch" } ], [ { "label": "Deletes the sandbox" } ] ] }, { "title": "What the platform does", "kind": "system", "cells": [ [ { "label": "Checks spend ceiling" } ], [ { "label": "Claims warm pool" }, { "label": "Sheds the overflow" } ], [ { "label": "Deny-by-default egress" }, { "label": "Brokers a scoped token" } ], [ { "label": "Scans for secrets" } ], [ { "label": "Keeps the session record" } ] ] }, { "title": "How it feels", "kind": "emotion", "levels": [ "Delighted", "Fine", "Frustrated" ], "points": [ 2, 0, 1, 1, 2 ] }, { "title": "Where it hurts", "kind": "pain", "cells": [ [], [ { "label": "Silent queueing is worse than no" } ], [ { "label": "npm install blocked" } ], [ { "label": "Push refused late" } ], [] ] }, { "title": "What answers it", "kind": "gain", "cells": [ [], [ { "label": "Explicit retryable refusal" } ], [ { "label": "Registry proxy, not the internet" } ], [ { "label": "Scoped, short-lived token" } ], [ { "label": "Record outlives the VM" } ] ] } ], "chain": true, "note": "The agent's trough is a refusal it cannot tell from a hang — which is why shedding is explicit and classed, not implicit and slow.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-10" } }, { "id": "06-journey-patch-the-fleet", "title": "Journey — Patching 1,800 Hosts Without Anyone Noticing", "layout": "journey", "actor": { "label": "Platform SRE", "sub": "on call for the fleet", "goal": "Land a kernel fix on every host this week", "trigger": "A kernel CVE with a public exploit", "success": "Fleet patched, no developer ticket, no workspace lost" }, "phases": [ { "title": "Plan" }, { "title": "Drain", "moment": true }, { "title": "Patch" }, { "title": "Return" }, { "title": "Prove" } ], "lanes": [ { "title": "What they do", "kind": "step", "cells": [ [ { "label": "Picks a drain rate" } ], [ { "label": "Marks hosts draining" } ], [ { "label": "Rolls the kernel" } ], [ { "label": "Returns to pool" } ], [ { "label": "Reads the evidence" } ] ] }, { "title": "What the platform does", "kind": "system", "cells": [ [ { "label": "Shows live workspaces" } ], [ { "label": "Hibernates each one" }, { "label": "Resumes elsewhere" } ], [ { "label": "Refuses new placements" } ], [ { "label": "Rebalances warm pools" } ], [ { "label": "Reports resume success" } ] ] }, { "title": "How it feels", "kind": "emotion", "levels": [ "Confident", "Fine", "Exposed" ], "points": [ 1, 0, 1, 2, 2 ] }, { "title": "Where it hurts", "kind": "pain", "cells": [ [ { "label": "No idea who is mid-build" } ], [ { "label": "A pause looks like a crash" } ], [], [], [] ] }, { "title": "What answers it", "kind": "gain", "cells": [ [ { "label": "Liveness per workspace" } ], [ { "label": "Snapshot, not terminate" }, { "label": "Resume on any host" } ], [ { "label": "Patching is scheduling" } ], [], [ { "label": "99.9% resume success" } ] ] } ], "chain": true, "note": "This journey only exists because the workspace is a snapshot: on a host-owned design the same CVE becomes a maintenance window.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-10" } }, { "id": "07-layered-architecture", "title": "Layered Architecture", "layout": "bands", "bands": [ { "name": "Clients", "nodes": [ { "id": "l-web", "label": "Browser editor", "kind": "app" }, { "id": "l-desk", "label": "Desktop editor tunnel", "kind": "app" }, { "id": "l-ssh", "label": "SSH", "kind": "app" }, { "id": "l-api", "label": "Agent API client", "kind": "external" } ] }, { "name": "Edge & gateway", "nodes": [ { "id": "l-tls", "label": "TLS termination", "kind": "integration", "sub": "Envoy" }, { "id": "l-auth", "label": "Principal auth", "kind": "security" }, { "id": "l-res", "label": "Resume-on-connect", "kind": "app" }, { "id": "l-prev", "label": "Preview routing", "kind": "integration" } ] }, { "name": "Admission & placement", "nodes": [ { "id": "l-quota", "label": "Quota & spend", "kind": "decision" }, { "id": "l-shed", "label": "Class-aware shedding", "kind": "decision" }, { "id": "l-claim", "label": "Warm-pool claim", "kind": "app" }, { "id": "l-pick", "label": "Host selection", "kind": "app" } ] }, { "name": "Host agent", "nodes": [ { "id": "l-vm", "label": "microVM lifecycle", "kind": "platform", "sub": "Firecracker" }, { "id": "l-snap", "label": "Snapshot & restore", "kind": "platform" }, { "id": "l-caps", "label": "Resource caps", "kind": "platform", "sub": "cgroups · quotas" }, { "id": "l-drain", "label": "Drain & evacuate", "kind": "platform" } ] }, { "name": "Workspace sandbox", "nodes": [ { "id": "l-kern", "label": "Guest kernel", "kind": "app", "sub": "disposable" }, { "id": "l-root", "label": "Root for the user", "kind": "risk", "sub": "assumed hostile" }, { "id": "l-nest", "label": "Nested containers", "kind": "app" }, { "id": "l-dev", "label": "Dev server & ports", "kind": "integration" } ] }, { "name": "Persistence", "nodes": [ { "id": "l-cas", "label": "Content-addressed snapshots", "kind": "store" }, { "id": "l-mem", "label": "Memory images", "kind": "store" }, { "id": "l-pre", "label": "Prebuild artefacts", "kind": "store" }, { "id": "l-tier", "label": "Lifecycle & tiering", "kind": "app" } ] }, { "name": "Egress & brokerage", "nodes": [ { "id": "l-pep", "label": "Policy enforcement", "kind": "security" }, { "id": "l-proxy", "label": "Registry proxy", "kind": "integration" }, { "id": "l-brok", "label": "Secret broker", "kind": "security", "sub": "vsock" }, { "id": "l-scan", "label": "Secret scan on push", "kind": "security" } ] }, { "name": "Control plane (off the data path)", "nodes": [ { "id": "l-sm", "label": "Workspace state machine", "kind": "app" }, { "id": "l-pol", "label": "Tenants, seats, policy", "kind": "store" }, { "id": "l-idx", "label": "Prebuild index", "kind": "store" }, { "id": "l-kill", "label": "Kill switches", "kind": "security" } ] } ], "edges": [ { "from": "l-res", "to": "l-claim", "label": "resume request" }, { "from": "l-pick", "to": "l-vm", "label": "placement" }, { "from": "l-snap", "to": "l-cas", "label": "delta", "kind": "async" }, { "from": "l-root", "to": "l-pep", "label": "all egress" } ], "note": "Eight layers, of which exactly one survives a control-plane outage without caring: everything above the dashed read from cache.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-10" } }, { "id": "08-platform-components", "title": "Platform Components — Control Plane, Host Fleet, Shared Services", "layout": "nested", "canvas": { "width": 1760 }, "boxes": [ { "title": "Edge · regional, stateless with respect to workspace identity", "kind": "boundary", "dir": "row", "children": [ { "title": "Connection termination", "kind": "plain", "nodes": [ { "id": "c-envoy", "label": "Gateway", "kind": "integration", "sub": "Envoy · TLS · authz" }, { "id": "c-sess", "label": "Session proxy", "kind": "app", "sub": "editor · SSH · stream" } ] }, { "title": "Published ports", "kind": "plain", "nodes": [ { "id": "c-prev", "label": "Preview router", "kind": "integration", "sub": "private by default" } ] } ] }, { "title": "Control plane · Kubernetes, strongly consistent, off the data path", "kind": "boundary", "dir": "row", "children": [ { "title": "API and state", "kind": "plain", "nodes": [ { "id": "c-api", "label": "Workspace API", "kind": "integration", "sub": "REST · gRPC stream" }, { "id": "c-sm", "label": "State machine controller", "kind": "app", "sub": "CRD reconciler" }, { "id": "c-pol", "label": "Policy service", "kind": "app", "sub": "tenant posture" } ] }, { "title": "Decisioning", "kind": "plain", "nodes": [ { "id": "c-adm", "label": "Admission controller", "kind": "decision", "sub": "quota · class shed" }, { "id": "c-place", "label": "Placement controller", "kind": "app", "sub": "late binding" }, { "id": "c-pool", "label": "Warm-pool manager", "kind": "app", "sub": "demand-sized" } ] }, { "title": "Records", "kind": "plain", "nodes": [ { "id": "c-reg", "label": "Workspace registry", "kind": "store", "sub": "PostgreSQL · RPO 0" }, { "id": "c-idx", "label": "Prebuild index", "kind": "store", "sub": "validity predicate" }, { "id": "c-evt", "label": "Lifecycle event log", "kind": "queue", "sub": "Kafka · durable" } ] } ] }, { "title": "Data plane · bare-metal host fleet", "kind": "onprem", "dir": "row", "children": [ { "title": "Per host", "kind": "plain", "nodes": [ { "id": "c-ha", "label": "Host agent", "kind": "platform", "sub": "lifecycle · drain" }, { "id": "c-fc", "label": "Firecracker + jailer", "kind": "platform", "sub": "one VM per workspace" }, { "id": "c-blk", "label": "Block overlay", "kind": "app", "sub": "CoW · lazy fetch" }, { "id": "c-pep", "label": "Egress policy point", "kind": "security", "sub": "eBPF + forward proxy" } ] }, { "title": "Per workspace · untrusted", "kind": "trust", "nodes": [ { "id": "c-vm", "label": "Workspace microVM", "kind": "app", "sub": "guest kernel · root" }, { "id": "c-gag", "label": "Guest agent", "kind": "app", "sub": "liveness · ports" }, { "id": "c-risk", "label": "Unreviewed code", "kind": "risk", "sub": "human or agent" } ] } ] }, { "title": "Shared services", "kind": "boundary", "dir": "row", "children": [ { "title": "Persistence", "kind": "plain", "nodes": [ { "id": "c-snap", "label": "Snapshot store", "kind": "store", "sub": "S3-compatible · CAS" }, { "id": "c-art", "label": "Prebuild artefacts", "kind": "store", "sub": "per definition rev" }, { "id": "c-img", "label": "Image registry", "kind": "store", "sub": "digest-pinned" } ] }, { "title": "Security and evidence", "kind": "trust", "nodes": [ { "id": "c-brok", "label": "Secret broker", "kind": "security", "sub": "short-lived tokens" }, { "id": "c-wid", "label": "Workspace identity", "kind": "security", "sub": "one per workspace" }, { "id": "c-aud", "label": "Audit log", "kind": "store", "sub": "append-only · 5 y" } ] } ] } ], "outside": [ { "id": "c-git", "label": "Git forge", "kind": "external" }, { "id": "c-idp", "label": "Identity provider", "kind": "external" }, { "id": "c-pkg", "label": "Package registries", "kind": "external" } ], "edges": [ { "from": "c-sess", "to": "c-gag", "label": "attach", "kind": "sync" }, { "from": "c-place", "to": "c-ha", "label": "incarnate", "kind": "sync" }, { "from": "c-ha", "to": "c-snap", "label": "delta every 5 min", "kind": "async" }, { "from": "c-pep", "to": "c-pkg", "label": "proxied only", "kind": "sync" }, { "from": "c-brok", "to": "c-git", "label": "scoped token", "kind": "sync" } ], "note": "The control plane holds no workspace content. Nothing in the host fleet needs it to keep a running workspace alive.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-10" } }, { "id": "09-integration-surface", "title": "Interface Catalogue", "layout": "hub", "left": { "title": "Consumers", "nodes": [ { "id": "i-web", "label": "Browser editor", "kind": "app", "rel": "WebSocket" }, { "id": "i-ssh", "label": "SSH client", "kind": "app", "rel": "SSH" }, { "id": "i-agent", "label": "Agent runtime", "kind": "external", "rel": "API" }, { "id": "i-adm", "label": "Admin console", "kind": "app", "rel": "policy" } ] }, "centre": { "title": "CDE Platform", "nodes": [ { "id": "i-core", "label": "Workspace API & edge", "kind": "integration", "sub": "one authz model" } ] }, "right": { "title": "Dependencies", "nodes": [ { "id": "i-git", "label": "Git forge", "kind": "external", "rel": "clone", "dir": "out" }, { "id": "i-idp", "label": "Identity provider", "kind": "external", "rel": "OIDC", "dir": "out" }, { "id": "i-pkg", "label": "Package registries", "kind": "external", "rel": "proxied", "dir": "out" }, { "id": "i-obj", "label": "Object storage", "kind": "store", "rel": "snapshots", "dir": "out" } ] }, "note": "Four inbound interfaces under one authorisation model, four outbound. Usage events leave on the lifecycle stream, not through this surface; the only outbound path a workspace itself may take is the proxy.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-10" }, "canvas": { "width": 1500 } }, { "id": "10-workspace-data-flow", "title": "Data Flow — From Keystroke to Snapshot", "layout": "flow", "chain": true, "stages": [ { "title": "Sources", "nodes": [ { "id": "d-edit", "label": "Developer edits", "kind": "actor", "sub": "in the guest" }, { "id": "d-code", "label": "Agent writes", "kind": "external" }, { "id": "d-repo", "label": "Repository clone", "kind": "store" } ] }, { "title": "Inside the guest", "nodes": [ { "id": "d-fs", "label": "Workspace filesystem", "kind": "store", "sub": "32 GB disk" }, { "id": "d-mem", "label": "Process memory", "kind": "store", "sub": "8 GB nominal" }, { "id": "d-eph", "label": "Ephemeral paths", "kind": "risk", "sub": "excluded by default" } ] }, { "title": "Capture", "nodes": [ { "id": "d-cow", "label": "Copy-on-write delta", "kind": "app", "sub": "block level" }, { "id": "d-dedup", "label": "Dedup vs prebuild", "kind": "app", "sub": "median 2 GB" } ] }, { "title": "Durable", "nodes": [ { "id": "d-cas", "label": "Snapshot store", "kind": "store", "sub": "11 nines · tenant key" }, { "id": "d-memimg", "label": "Memory image", "kind": "store", "sub": "decays to disk-only" } ] }, { "title": "Evidence", "nodes": [ { "id": "d-ev", "label": "Lifecycle events", "kind": "queue", "sub": "RPO 1 min" }, { "id": "d-sess", "label": "Session records", "kind": "store", "sub": "400 d" }, { "id": "d-aud", "label": "Audit records", "kind": "store", "sub": "5 y immutable" } ] }, { "title": "Consumers", "nodes": [ { "id": "d-bill", "label": "Billing & showback", "kind": "external" }, { "id": "d-ops", "label": "Operations", "kind": "app", "sub": "latency by cause" }, { "id": "d-sec", "label": "Security review", "kind": "security" } ] } ], "edges": [ { "from": "d-eph", "to": "d-cow", "label": "dropped", "kind": "error" }, { "from": "d-cas", "to": "d-fs", "label": "lazy restore", "kind": "sync", "route": "gutter" } ], "note": "No workspace content ever reaches control-plane storage; the only thing that leaves the guest for the control plane is an event.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-10" } }, { "id": "11-storage-zones", "title": "Storage Zones by Ownership and Rebuildability", "layout": "nested", "canvas": { "width": 1700 }, "boxes": [ { "title": "Cannot be lost · the workspace itself", "kind": "trust", "dir": "row", "children": [ { "title": "Workspace content", "kind": "plain", "nodes": [ { "id": "s-snap", "label": "Filesystem snapshots", "kind": "store", "sub": "RPO 5 min · 180 TB/d" }, { "id": "s-mem", "label": "Memory images", "kind": "store", "sub": "best effort" } ] }, { "title": "Control-plane truth", "kind": "plain", "nodes": [ { "id": "s-reg", "label": "Workspace registry", "kind": "store", "sub": "RPO 0 · replicated" }, { "id": "s-pol", "label": "Tenants, seats, policy", "kind": "store", "sub": "RPO 0" } ] }, { "title": "Evidence", "kind": "plain", "nodes": [ { "id": "s-aud", "label": "Audit records", "kind": "store", "sub": "immutable · 5 y" } ] } ] }, { "title": "Rebuildable · losing it costs time, not truth", "kind": "boundary", "dir": "row", "children": [ { "title": "Start-time caches", "kind": "plain", "nodes": [ { "id": "s-pre", "label": "Prebuild artefacts", "kind": "store", "sub": "rebuild ≤ 4 h" }, { "id": "s-img", "label": "Base images", "kind": "store", "sub": "digest-pinned" } ] }, { "title": "Proxy caches", "kind": "plain", "nodes": [ { "id": "s-pkg", "label": "Registry pull-through", "kind": "store", "sub": "recomputed" } ] }, { "title": "Operational", "kind": "plain", "nodes": [ { "id": "s-tel", "label": "Telemetry", "kind": "store", "sub": "raw 14 d" }, { "id": "s-sess", "label": "Session records", "kind": "store", "sub": "400 d" } ] } ] }, { "title": "Lifecycle · archived, then gone", "kind": "plain", "dir": "row", "children": [ { "title": "Warm", "kind": "plain", "nodes": [ { "id": "s-warm", "label": "Not resumed ≤ 30 d", "kind": "store", "sub": "$0.004/h" } ] }, { "title": "Cold", "kind": "plain", "nodes": [ { "id": "s-cold", "label": "Archived to 90 d", "kind": "store", "sub": "rehydrate on ask" } ] }, { "title": "Deleted", "kind": "plain", "nodes": [ { "id": "s-del", "label": "Deleted at 90 d", "kind": "risk", "sub": "unless extended" } ] } ] } ], "edges": [ { "from": "s-warm", "to": "s-cold", "label": "tiering", "kind": "batch" }, { "from": "s-cold", "to": "s-del", "label": "retention", "kind": "batch" }, { "from": "s-pre", "to": "s-snap", "label": "dedup base", "kind": "sync" } ], "note": "Everything in the middle band may be deleted on a bad day; the top band is what the platform exists to keep.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-10" } }, { "id": "12-control-plane-data-model", "title": "Control-Plane Data Model", "layout": "er", "canvas": { "width": 1700, "cols": 4 }, "rowGap": 260, "entities": [ { "id": "tenant", "name": "tenant", "kind": "store", "row": 0, "col": 0, "attrs": [ "tenant_id PK", "region (residency pin)", "egress_posture", "idle_timeout_s", "spend_ceiling" ] }, { "id": "repo", "name": "repository_binding", "kind": "store", "row": 0, "col": 1, "attrs": [ "binding_id PK", "tenant_id FK", "forge_repo", "scopes_granted" ] }, { "id": "envdef", "name": "environment_definition", "kind": "store", "row": 0, "col": 2, "attrs": [ "definition_rev PK", "binding_id FK", "image_digest", "lockfile_hash", "machine_class" ] }, { "id": "prebuild", "name": "prebuild", "kind": "store", "row": 0, "col": 3, "attrs": [ "prebuild_id PK", "definition_rev FK", "commit", "artefact_digest", "valid bool" ] }, { "id": "principal", "name": "principal", "kind": "store", "row": 1, "col": 0, "attrs": [ "principal_id PK", "tenant_id FK", "class human | agent", "seat_state", "concurrency_limit" ] }, { "id": "ws", "name": "workspace", "kind": "store", "row": 1, "col": 1, "attrs": [ "workspace_id PK", "binding_id FK", "definition_rev FK", "state", "last_resume_at" ] }, { "id": "inc", "name": "incarnation", "kind": "store", "row": 1, "col": 2, "attrs": [ "incarnation_id PK", "workspace_id FK", "host_id FK", "started_at", "ended_reason" ] }, { "id": "snap", "name": "snapshot", "kind": "store", "row": 1, "col": 3, "attrs": [ "snapshot_id PK", "workspace_id FK", "content_digest", "has_memory bool", "bytes" ] }, { "id": "audit", "name": "audit_event", "kind": "store", "row": 2, "col": 0, "attrs": [ "event_id PK", "actor_principal FK", "workspace_id", "action", "reason (immutable)" ] }, { "id": "sess", "name": "session", "kind": "store", "row": 2, "col": 1, "attrs": [ "session_id PK", "incarnation_id FK", "principal_id FK", "attached_by", "diff_ref" ] }, { "id": "host", "name": "host", "kind": "store", "row": 2, "col": 2, "attrs": [ "host_id PK", "rack · region", "kernel_version", "state live | draining", "oversub_ratio" ] } ], "relations": [ { "from": "tenant", "to": "repo", "label": "1 : N", "from_side": "e", "to_side": "w" }, { "from": "repo", "to": "envdef", "label": "1 : N", "from_side": "e", "to_side": "w" }, { "from": "envdef", "to": "prebuild", "label": "1 : N", "from_side": "e", "to_side": "w" }, { "from": "tenant", "to": "principal", "label": "1 : N", "from_side": "s", "to_side": "n" }, { "from": "principal", "to": "ws", "label": "1 : N", "from_side": "e", "to_side": "w" }, { "from": "repo", "to": "ws", "label": "1 : N", "from_side": "s", "to_side": "n" }, { "from": "ws", "to": "inc", "label": "1 : N", "from_side": "e", "to_side": "w" }, { "from": "inc", "to": "snap", "label": "1 : N", "from_side": "e", "to_side": "w" }, { "from": "ws", "to": "sess", "label": "1 : N", "from_side": "s", "to_side": "n" }, { "from": "host", "to": "inc", "label": "1 : N", "from_side": "n", "to_side": "s" }, { "from": "principal", "to": "audit", "label": "1 : N", "from_side": "s", "to_side": "n" } ], "note": "A workspace has many incarnations and many snapshots, and no host: the host appears only on an incarnation.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-10" } }, { "id": "13-resume-sequence", "title": "Critical Flow — Resuming a Hibernated Workspace", "layout": "sequence", "lifelines": [ { "id": "q-dev", "label": "Developer", "kind": "actor" }, { "id": "q-edge", "label": "Edge gateway", "kind": "integration" }, { "id": "q-cp", "label": "Control plane", "kind": "app" }, { "id": "q-ha", "label": "Host agent", "kind": "platform" }, { "id": "q-snap", "label": "Snapshot store", "kind": "store" }, { "id": "q-vm", "label": "Workspace VM", "kind": "app" }, { "id": "q-brok", "label": "Secret broker", "kind": "security" } ], "messages": [ { "from": "q-dev", "to": "q-edge", "label": "connect workspace/42", "kind": "call" }, { "from": "q-edge", "to": "q-edge", "label": "authorise principal", "kind": "self" }, { "from": "q-edge", "to": "q-cp", "label": "resume request", "kind": "call" }, { "from": "q-cp", "to": "q-cp", "label": "quota · spend · region", "kind": "self" }, { "from": "q-cp", "to": "q-ha", "label": "incarnate (snapshot ref)", "kind": "call" }, { "from": "q-ha", "to": "q-snap", "label": "fetch memory image", "kind": "call" }, { "from": "q-snap", "to": "q-ha", "label": "image + block map", "kind": "return" }, { "from": "q-ha", "to": "q-vm", "label": "restore microVM", "kind": "call" }, { "from": "q-vm", "to": "q-ha", "label": "guest agent up", "kind": "return" }, { "from": "q-ha", "to": "q-vm", "label": "re-sync clock · topology", "kind": "call" }, { "from": "q-vm", "to": "q-brok", "label": "request git token", "kind": "call" }, { "from": "q-brok", "to": "q-vm", "label": "scoped, 15-min token", "kind": "return" }, { "from": "q-ha", "to": "q-edge", "label": "attach endpoint", "kind": "return" }, { "from": "q-edge", "to": "q-dev", "label": "terminal live (p95 2.5 s)", "kind": "return" }, { "from": "q-ha", "to": "q-snap", "label": "blocks in background", "kind": "async" }, { "from": "q-edge", "to": "q-dev", "label": "lost interval since snapshot", "kind": "error" } ], "note": "Message 16 is drawn as a failure path but is designed behaviour: where the 5-minute RPO cost work, the resume says so.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-10" } }, { "id": "14-prebuild-pipeline", "title": "Prebuild Pipeline — Making a Start a Restore", "layout": "flow", "chain": true, "stages": [ { "title": "Trigger", "nodes": [ { "id": "p-push", "label": "Push to a branch", "kind": "external" }, { "id": "p-def", "label": "Definition change", "kind": "external" }, { "id": "p-rate", "label": "Per-tenant rate limit", "kind": "decision", "sub": "fan-out cap" } ] }, { "title": "Resolve", "nodes": [ { "id": "p-pin", "label": "Pin image digest", "kind": "app" }, { "id": "p-hash", "label": "Hash lockfiles", "kind": "app", "sub": "validity predicate" } ] }, { "title": "Build", "nodes": [ { "id": "p-clone", "label": "Clone", "kind": "app" }, { "id": "p-deps", "label": "Install dependencies", "kind": "app", "sub": "through the proxy" }, { "id": "p-post", "label": "post-create", "kind": "app" } ] }, { "title": "Capture", "nodes": [ { "id": "p-snap", "label": "Snapshot after post-create", "kind": "store", "sub": "the artefact" }, { "id": "p-idx", "label": "Index as valid", "kind": "store", "sub": "(repo, rev, lock)" } ] }, { "title": "Serve", "nodes": [ { "id": "p-warm", "label": "Warm pool", "kind": "app", "sub": "popular pairs" }, { "id": "p-create", "label": "Create = restore", "kind": "app", "sub": "p95 ≤ 25 s" }, { "id": "p-rebase", "label": "Rebase onto newer commit", "kind": "app" } ] }, { "title": "Retire", "nodes": [ { "id": "p-gc", "label": "Garbage-collect superseded", "kind": "app" }, { "id": "p-fall", "label": "Inline build fallback", "kind": "risk", "sub": "p95 ≤ 4 min" } ] } ], "edges": [ { "from": "p-hash", "to": "p-fall", "label": "no valid prebuild", "kind": "error" }, { "from": "p-idx", "to": "p-warm", "label": "pre-start", "kind": "async" } ], "note": "Validity is a predicate over digest, definition revision and lockfile hash — never an age. A stale prebuild is worse than a slow start.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-10" } }, { "id": "15-hibernate-and-evacuate", "title": "Stopping a Workspace — Four Reasons, One Mechanism", "layout": "swimlane", "stages": [ "Detect", "Decide", "Quiesce", "Persist", "Release", "Resume" ], "laneHeaderWidth": 190, "lanes": [ { "title": "Idle human workspace", "cells": [ [ { "label": "No input, no activity", "kind": "app" } ], [ { "label": "Composite liveness", "kind": "decision" }, { "label": "Veto window honoured", "kind": "app" } ], [ { "label": "Freeze the guest", "kind": "app" } ], [ { "label": "Memory image + delta", "kind": "store" } ], [ { "label": "Host capacity freed", "kind": "app" } ], [ { "label": "On next connect", "kind": "app" } ] ] }, { "title": "Idle agent sandbox", "cells": [ [ { "label": "Short timeout", "kind": "app", "sub": "stricter default" } ], [ { "label": "No veto", "kind": "decision" } ], [ { "label": "Kill the guest", "kind": "app" } ], [ { "label": "Diff + session record", "kind": "store" } ], [ { "label": "Returned to warm pool", "kind": "app" } ], [] ] }, { "title": "Host drain (patching)", "cells": [ [ { "label": "Operator marks host", "kind": "actor" } ], [ { "label": "Refuse new placements", "kind": "decision" } ], [ { "label": "Freeze in waves", "kind": "app" } ], [ { "label": "Snapshot each", "kind": "store" } ], [ { "label": "Kernel rolled", "kind": "platform" } ], [ { "label": "Elsewhere, immediately", "kind": "app" } ] ] }, { "title": "Host loss (unplanned)", "cells": [ [ { "label": "Heartbeat gone", "kind": "risk" } ], [ { "label": "Fence the host", "kind": "decision" } ], [], [ { "label": "Last 5-min snapshot", "kind": "store" } ], [ { "label": "Host fenced", "kind": "risk" } ], [ { "label": "RTO 60 s, loss told", "kind": "app" } ] ] } ], "note": "The two blank cells are the design: an unplanned loss has nothing to quiesce, and a finished agent sandbox has nothing to resume.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-10" } }, { "id": "16-host-fleet-deployment", "title": "Deployment Topology — Owned Racks, Region-Pinned Content", "layout": "nested", "canvas": { "width": 1740 }, "boxes": [ { "title": "Region eu-west · owned racks · residency boundary", "kind": "onprem", "dir": "row", "children": [ { "title": "Workspace compute", "kind": "boundary", "nodes": [ { "id": "r1-h1", "label": "Host group A", "kind": "app", "sub": "600 × 128c / 1 TB" }, { "id": "r1-h2", "label": "Host group B", "kind": "app", "sub": "600 × 128c / 1 TB" }, { "id": "r1-gpu", "label": "GPU hosts", "kind": "app", "sub": "phase 3" } ] }, { "title": "Snapshot storage", "kind": "boundary", "nodes": [ { "id": "r1-obj", "label": "Object store", "kind": "store", "sub": "S3-compatible · EC" }, { "id": "r1-cold", "label": "Cold tier", "kind": "store", "sub": "30–90 d" } ] }, { "title": "Control plane", "kind": "boundary", "nodes": [ { "id": "r1-k8s", "label": "Kubernetes", "kind": "platform", "sub": "3 control nodes" }, { "id": "r1-pg", "label": "PostgreSQL", "kind": "store", "sub": "sync replicas" }, { "id": "r1-kaf", "label": "Event log", "kind": "queue", "sub": "Kafka · 3 brokers" } ] }, { "title": "Edge", "kind": "boundary", "nodes": [ { "id": "r1-env", "label": "Envoy fleet", "kind": "integration", "sub": "stateless" } ] } ] }, { "title": "Region us-east · owned racks · separate residency boundary", "kind": "onprem", "dir": "row", "children": [ { "title": "Workspace compute", "kind": "boundary", "nodes": [ { "id": "r2-h1", "label": "Host group A", "kind": "app", "sub": "400 × 128c / 1 TB" } ] }, { "title": "Snapshot storage", "kind": "boundary", "nodes": [ { "id": "r2-obj", "label": "Object store", "kind": "store", "sub": "no cross-region copy" } ] }, { "title": "Control plane + edge", "kind": "boundary", "nodes": [ { "id": "r2-k8s", "label": "Kubernetes", "kind": "platform", "sub": "3 control nodes" }, { "id": "r2-env", "label": "Envoy fleet", "kind": "integration" } ] } ] }, { "title": "Global · identity and catalogue only, never workspace content", "kind": "boundary", "dir": "row", "children": [ { "title": "Identity", "kind": "trust", "nodes": [ { "id": "g-idp", "label": "Tenant IdP federation", "kind": "security" }, { "id": "g-spiffe", "label": "Workspace identity CA", "kind": "security" } ] }, { "title": "Catalogue", "kind": "plain", "nodes": [ { "id": "g-img", "label": "Image registry", "kind": "store", "sub": "mirrored per region" }, { "id": "g-bill", "label": "Billing sink", "kind": "external" } ] } ] } ], "edges": [ { "from": "r1-obj", "to": "r2-obj", "label": "no automatic failover", "kind": "error" }, { "from": "g-img", "to": "r1-h1", "label": "digest pull", "kind": "batch" }, { "from": "r1-h1", "to": "r1-obj", "label": "snapshot · lazy fetch", "kind": "sync" } ], "note": "The red line is the one thing this topology refuses: content does not cross a region to keep a workspace up. Migration is a tenant decision.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-10" } }, { "id": "17-platform-delivery-pipeline", "title": "Delivering the Platform Itself — Kernel, Host Agent, Control Plane", "layout": "flow", "chain": true, "stages": [ { "title": "Source", "nodes": [ { "id": "b-ha", "label": "Host agent", "kind": "app", "sub": "Rust · Firecracker API" }, { "id": "b-kern", "label": "Host kernel config", "kind": "platform" }, { "id": "b-cp", "label": "Control-plane charts", "kind": "app" } ] }, { "title": "Build", "nodes": [ { "id": "b-sign", "label": "Signed artefacts", "kind": "security", "sub": "digest-pinned" }, { "id": "b-sbom", "label": "SBOM", "kind": "store" } ] }, { "title": "Gates", "nodes": [ { "id": "b-unit", "label": "Unit & integration", "kind": "decision" }, { "id": "b-boot", "label": "VM boot matrix", "kind": "decision", "sub": "every machine class" }, { "id": "b-fid", "label": "Snapshot fidelity", "kind": "decision", "sub": "restore = original" } ] }, { "title": "Canary", "nodes": [ { "id": "b-can", "label": "1% of hosts", "kind": "app", "sub": "synthetic workspaces" }, { "id": "b-slo", "label": "Resume SLO watch", "kind": "app", "sub": "p95 · success rate" } ] }, { "title": "Fleet", "nodes": [ { "id": "b-wave", "label": "Drain-and-patch waves", "kind": "app", "sub": "rate-limited" }, { "id": "b-evac", "label": "Live evacuation", "kind": "platform" } ] }, { "title": "Recover", "nodes": [ { "id": "b-roll", "label": "Roll back a wave", "kind": "app", "sub": "≤ 10 min" }, { "id": "b-stop", "label": "Halt on SLO breach", "kind": "risk" } ] } ], "edges": [ { "from": "b-slo", "to": "b-stop", "label": "regression", "kind": "error" }, { "from": "b-fid", "to": "b-sign", "label": "blocks release", "kind": "error" } ], "note": "The snapshot-fidelity gate is the one that cannot be waived: a release that restores a workspace wrongly destroys work rather than delaying it.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-10" } }, { "id": "18-observability-matrix", "title": "Observability Matrix — Signal by Layer", "layout": "grid", "stages": [ "Edge", "Admission", "Host agent", "Workspace", "Persistence", "Egress" ], "laneHeaderWidth": 170, "lanes": [ { "title": "Latency", "cells": [ [ { "label": "Connect to attach", "kind": "app" } ], [ { "label": "Decision p99", "kind": "app" } ], [ { "label": "Restore by cause", "kind": "app", "sub": "warm · mem · disk" } ], [ { "label": "Terminal round-trip", "kind": "app" } ], [ { "label": "Block fetch p95", "kind": "app" } ], [] ] }, { "title": "Saturation", "cells": [ [ { "label": "Gateway conns", "kind": "app" } ], [ { "label": "Shed rate by class", "kind": "app" } ], [ { "label": "Oversub headroom", "kind": "app" } ], [ { "label": "Caps hit", "kind": "app" } ], [ { "label": "Snapshot backlog", "kind": "app" } ], [ { "label": "Proxy queue", "kind": "app" } ] ] }, { "title": "Correctness", "cells": [ [], [ { "label": "Wrong-region place", "kind": "risk" } ], [ { "label": "Resume success", "kind": "app" } ], [ { "label": "False hibernations", "kind": "risk" } ], [ { "label": "Integrity failures", "kind": "risk" } ], [] ] }, { "title": "Cost", "cells": [ [], [ { "label": "Warm-pool spend", "kind": "app" } ], [ { "label": "$ / workspace-hour", "kind": "app" } ], [ { "label": "Active vs open hours", "kind": "app" } ], [ { "label": "Never-resumed bytes", "kind": "app" } ], [ { "label": "Egress bytes", "kind": "app" } ] ] }, { "title": "Security", "cells": [ [ { "label": "Preview publications", "kind": "security" } ], [], [ { "label": "Kernel drift", "kind": "security" } ], [ { "label": "Abuse profiles", "kind": "security" } ], [ { "label": "Key-revocation state", "kind": "security" } ], [ { "label": "Deny verdicts", "kind": "security" } ] ] } ], "note": "The blank cells are deliberate: there is no correctness question at the edge, and no latency question at the egress point that a developer would ever feel.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-10" } }, { "id": "19-capacity-and-reclaim-loop", "title": "The Loop That Pays For It", "layout": "cycle", "centre": { "label": "Fleet economics" }, "nodes": [ { "id": "y-obs", "label": "Observe demand", "kind": "app", "sub": "starts by pair" }, { "id": "y-warm", "label": "Size warm pools", "kind": "app", "sub": "≤ 7% of spend" }, { "id": "y-admit", "label": "Admit or shed", "kind": "decision", "sub": "class-aware" }, { "id": "y-place", "label": "Place on oversubscribed hosts", "kind": "app", "sub": "4:1 memory" }, { "id": "y-idle", "label": "Detect idleness", "kind": "app", "sub": "composite signal" }, { "id": "y-hib", "label": "Hibernate and tier", "kind": "store", "sub": "$0.004/h" }, { "id": "y-rec", "label": "Reclaim and archive", "kind": "app", "sub": "30 → 90 d" } ], "ringLabels": [ "forecast", "capacity", "placement", "pressure", "relief", "storage", "headroom" ], "note": "Oversubscription is only safe because hibernation is the relief valve; break the idleness signal and the ring stops closing.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-10" } }, { "id": "20-network-segmentation", "title": "Trust Zones — A Machine Whose User Has Root", "layout": "zones", "zones": [ { "title": "Internet", "kind": "trust", "nodes": [ { "id": "n-dev", "label": "Developer client", "kind": "actor" }, { "id": "n-agent", "label": "Agent runtime", "kind": "external" }, { "id": "n-visit", "label": "Preview visitor", "kind": "external" }, { "id": "n-pkg", "label": "Package registries", "kind": "external" } ] }, { "title": "Perimeter", "kind": "trust", "nodes": [ { "id": "n-env", "label": "Envoy edge", "kind": "integration", "sub": "TLS · authz" }, { "id": "n-prev", "label": "Preview router", "kind": "integration", "sub": "private default" }, { "id": "n-proxy", "label": "Registry proxy", "kind": "integration", "sub": "pull-through" } ] }, { "title": "Workspace sandbox · untrusted, root inside", "kind": "trust", "nodes": [ { "id": "n-vm", "label": "Guest kernel", "kind": "risk", "sub": "assumed compromised" }, { "id": "n-code", "label": "Unreviewed code", "kind": "risk" }, { "id": "n-gag", "label": "Guest agent", "kind": "app", "sub": "advisory only" } ] }, { "title": "Host · the boundary that holds", "kind": "trust", "nodes": [ { "id": "n-ha", "label": "Host agent", "kind": "platform" }, { "id": "n-pep", "label": "Egress policy point", "kind": "security" }, { "id": "n-vsock", "label": "vsock side channel", "kind": "security", "sub": "no network path" } ] }, { "title": "Platform · control plane and brokers", "kind": "trust", "nodes": [ { "id": "n-cp", "label": "Control plane", "kind": "app" }, { "id": "n-brok", "label": "Secret broker", "kind": "security" }, { "id": "n-aud", "label": "Audit log", "kind": "store" } ] }, { "title": "Durable content", "kind": "trust", "nodes": [ { "id": "n-snap", "label": "Snapshot store", "kind": "store", "sub": "tenant-scoped keys" } ] } ], "edges": [ { "from": "n-dev", "to": "n-env", "label": "mTLS · OIDC" }, { "from": "n-visit", "to": "n-prev", "label": "published port only" }, { "from": "n-env", "to": "n-ha", "label": "attach, scoped" }, { "from": "n-code", "to": "n-pep", "label": "every packet" }, { "from": "n-pep", "to": "n-proxy", "label": "allowlist · deny-default" }, { "from": "n-gag", "to": "n-vsock", "label": "broker request" }, { "from": "n-vsock", "to": "n-brok", "label": "workspace identity" }, { "from": "n-ha", "to": "n-snap", "label": "write delta" } ], "note": "The sandbox sits above the host on purpose: it is less trusted than the internet zone, and it has no network path at all to the control plane or the broker.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-10" } }, { "id": "21-credential-brokerage", "title": "Identity Flow — Getting a Token Into a Root-Owned Machine", "layout": "sequence", "lifelines": [ { "id": "x-code", "label": "Code in guest", "kind": "risk" }, { "id": "x-gag", "label": "Guest agent", "kind": "app" }, { "id": "x-ha", "label": "Host agent", "kind": "platform" }, { "id": "x-brok", "label": "Secret broker", "kind": "security" }, { "id": "x-cp", "label": "Control plane", "kind": "app" }, { "id": "x-git", "label": "Git forge", "kind": "external" }, { "id": "x-aud", "label": "Audit log", "kind": "store" } ], "messages": [ { "from": "x-code", "to": "x-gag", "label": "git push", "kind": "call" }, { "from": "x-gag", "to": "x-ha", "label": "need repo token (vsock)", "kind": "call" }, { "from": "x-ha", "to": "x-ha", "label": "attach workspace identity", "kind": "self" }, { "from": "x-ha", "to": "x-brok", "label": "request, workspace-scoped", "kind": "call" }, { "from": "x-brok", "to": "x-cp", "label": "check repository binding", "kind": "call" }, { "from": "x-cp", "to": "x-brok", "label": "one repo, push scope", "kind": "return" }, { "from": "x-brok", "to": "x-git", "label": "mint installation token", "kind": "call" }, { "from": "x-git", "to": "x-brok", "label": "token, 15 min", "kind": "return" }, { "from": "x-brok", "to": "x-aud", "label": "issuance recorded", "kind": "async" }, { "from": "x-brok", "to": "x-gag", "label": "token, in memory only", "kind": "return" }, { "from": "x-gag", "to": "x-git", "label": "push, through the proxy", "kind": "call" }, { "from": "x-git", "to": "x-gag", "label": "accepted", "kind": "return" }, { "from": "x-code", "to": "x-brok", "label": "direct request", "kind": "error" }, { "from": "x-code", "to": "x-git", "label": "replay from another workspace", "kind": "error" } ], "note": "The last two messages are the point of the view: the guest has no network path to the broker, and a leaked token is scoped to the workspace that asked for it.", "meta": { "v": "1.0", "owner": "Platform Architecture", "date": "2026-10" } } ]