Systems view

Systems view

The same components, grouped by which engine they belong to rather than by which user-facing question they answer. Two views of the same set:

• Question view (README.md) — components nested by the architecture-doc question they answer (good for: subagents who own a user-facing concern, e.g. "compliance authoring").
• Systems view (this file) — components nested by engine/subsystem (good for: subagents who own a technical concern, e.g. "the policy engine").

Every component lives in one question folder on disk, but appears in one systems entry here. Use whichever cut helps you scope the work.

---

How to read this

Each engine below has:

• Purpose — one sentence
• Subcomponents — components this engine owns or composes
• Inherits from — existing TapPass infrastructure this builds on (already shipped)
• Status — overall delivery state of the engine
• Lead owner — single accountability per engine
• Internal architecture — how the subcomponents relate

---

1. Policy engine

Purpose: turns operator intent into the deterministic per-sandbox config that everything downstream consumes.

Subcomponents:

Component	Role in the engine	Status
Authoring resolver	Function/categories/concerns/capabilities → effective pipeline (intent-to-policy, already shipped on main)	shipped
cascade-merge-engine	Merges org → project → agent policies; rejects relaxations	concept
policy-to-sandbox-config-builder	Compiles merged policy into the layered keyring (the artifact)	concept
eu-ai-act-bundle	Pre-built policy targeting EU AI Act	concept
owasp-llm-bundle	Pre-built policy targeting OWASP LLM Top 10	concept

Inherits from: intent-to-policy substrate (live on main, ~470 tests); OPA pipeline; per-org KMS-envelope encryption.

Status: authoring resolver ✓ shipped; cascade + builder + packs are concept stage (highest priority for Q3).

Lead owner: platform.

Internal architecture:

Operator picks function + categories + compliance packs (UI / CLI)
        │
        ▼
Authoring resolver (~40 LOC, on main)
        │
        ▼
Pipeline config (L4 effective)
        │
        ▼
Cascade merge engine ◀── reads org / project / agent policies
        │                  rejects relaxations of upper floors
        ▼
Merged pipeline config
        │
        ▼
Policy → sandbox config builder
        │
        ▼
Layered keyring (the artifact)

The builder is the policy compiler — it takes the merged policy and emits the per-layer config that every other engine consumes.

---

2. Tool governance engine (MCP)

Purpose: governs every tool call — outbound (agent → upstream) and inbound (external → agent's MCP).

Subcomponents:

Component	Role in the engine	Status
upstream-tool-proxy	Forwards agent's MCP traffic to upstreams after policy checks	concept
approved-tool-server-list	Per-org allowlist of which upstream MCP servers are approved	concept
resource-access-checker	Pipeline step: per-call resource ACL (schema_acl)	concept
runaway-agent-stopper	Pipeline step: loop / pattern detection (loop_guard)	concept
Runtime tool discovery	Default-deny + review queue for unknown tools (concept written; capture exists; promotion path not shipped)	partial

Inherits from: existing TapPass MCP server (gateway/mcp_server.py, shipped); existing 32-step pipeline; existing capability tokens (ES256).

Status: existing MCP server is shipped; forward proxy + new pipeline steps + per-org registry + tool discovery are concept stage.

Lead owner: platform.

Internal architecture:

Agent's MCP client
        │
        ▼  (terminates at TapPass)
Upstream tool proxy ◀── reads keyring layer-4 capabilities
        │
        ├── pipeline: schema_acl   ◀── reads resource access rules from keyring
        ├── pipeline: loop_guard   ◀── per-session sliding window
        ├── pipeline: PII / secrets / scan_output (existing 32-step)
        │
        ▼  (forwards to)
Approved tool-server list ◀── upstream credentials from vault
        │
        ▼
Real upstream MCP server (Collibra, internal, vendor)

---

3. Sandbox runtime (host enforcement)

Purpose: what runs on the agent's machine to apply the layered keyring and contain the agent process.

Subcomponents:

Component	Role in the engine	Status
host-runtime-cli	Daemon + CLI on the host. Owns mTLS, applies layers, launches agent	concept
ring-kernel	Kernel — egress allowlist + Landlock + credential hiding	concept
ring-harness	Harness — settings.json-style config writer	concept
ring-interpreter	Codemode — executor allow/deny	concept
cross-cutting-mcp-broker	Pointer — delegates to tool governance engine	pointer
cross-cutting-llm-gateway	Pointer — already shipped as tappass/gateway/	shipped pointer

Inherits from: OpenShell sandbox (tappass/sandbox/, shipped — Landlock, L7 network, credential hiding).

Status: OpenShell primitives shipped; host CLI + per-layer appliers are concept stage.

Lead owner: platform.

Internal architecture:

tappass-host daemon (privileged UID, mTLS to TapPass)
        │
        ▼ at sandbox start, applies in order:
        ├── 1. Kernel applier — net namespace, Landlock, egress allowlist
        ├── 2. Codemode applier — executor profile
        ├── 3. Harness applier — writes settings.json
        ├── 4. (MCP layer is server-side; nothing applied locally)
        ├── 5. (Gateway is server-side; nothing applied locally)
        ├── Mounts keyring file RO into agent namespace
        └── Drops privileges; execs agent entrypoint

The five layers compose by sequence — kernel first (most isolated), gateway last (most abstract). On sync push, the daemon re-applies in the same order.

---

4. Sync system

Purpose: keeps every running sandbox current as policy changes; detects drift in production.

Subcomponents:

Component	Role in the engine	Status
live-policy-push-channel	Signed unidirectional WS push from TapPass to host	concept
behavior-drift-monitor	Compares production audit metrics against pre-deployment baseline	concept

Inherits from: existing TapPass WS infrastructure; existing audit hash-chain.

Status: concept.

Lead owner: platform.

Internal architecture:

Policy change at any cascade level
        │
        ▼
Builder re-derives stale keyrings
        │
        ▼
Push channel signs payload (Ed25519) and pushes per-sandbox
        │
        ▼
Host validates signature + monotonic policy_version
        │
        ▼ (host applies; agent observes)
        │
        ▼ (audit captures every call thereafter)
        │
        ▼
Drift monitor compares observed metrics to baseline
        │
        ▼
Dashboard alert + recommended action

---

5. Operator surfaces (CLIs and dashboard)

Purpose: how humans interact with the system — three CLIs, one dashboard, hard privilege separation.

Subcomponents:

Component	Role in the engine	Status
operator-cli (tappass)	Authors policy, provisions sandboxes; SSO+MFA	concept
host-runtime-cli (tappass-host)	Runs on host; receives sync; launches agents (also part of Sandbox Runtime engine)	concept
agent-client-sdk (tappass-agent)	Library agents import; read-only keyring access	concept
onboarding-wizard	Dashboard equivalent of tappass CLI for non-engineers	concept
Dashboard (existing pages)	Agents / Pipelines / Sessions / Audit Trail / Copilot / Playground / Settings	shipped

Inherits from: existing TapPass dashboard; existing SSO + RBAC.

Status: dashboard pages shipped; new CLIs + wizard are concept stage.

Lead owner: cli (CLIs), frontend (wizard).

Internal architecture:

Operator                    Host owner                Agent process
   │                           │                          │
   ▼                           ▼                          ▼
tappass CLI              tappass-host CLI          tappass-agent SDK
(SSO + MFA)              (machine identity)        (scoped sandbox token)
   │                           │                          │
   │ admin API                 │ sync WS                  │ keyring file (RO)
   ▼                           ▼                          ▼
TapPass control plane    TapPass control plane     Local mounted file

Each CLI has a different authentication mechanism, a different audience, and zero command overlap. This is the materialization of the privsep contract.

---

6. Evaluation engine

Purpose: verifies the agent obeys policy before it ships; establishes the baseline drift detection compares against.

Subcomponents:

Component	Role in the engine	Status
pre-deployment-evaluator	Runs probe suite against the agent under candidate policy	concept
owasp-llm-probe-library	First probe library; covers OWASP LLM Top 10	concept
EU AI Act probe library (planned)	Probes for EU AI Act-specific obligations	not yet a component
Custom probe SDK (planned)	Customers add their own probes	v2; not in this set

Inherits from: the policy engine (calls the builder in evaluation mode); the agent-client-sdk (drives agents identically to production).

Status: concept; first delivery Q4.

Lead owner: platform (harness), compliance (probe content).

Internal architecture:

tappass eval run
        │
        ▼
Policy engine derives a temp keyring (mode=evaluation, no persist)
        │
        ▼
Evaluator spawns ephemeral sandbox (uses the same Sandbox Runtime engine)
        │
        ▼  for each probe in the suite:
        ├── Drives agent through the probe scenario via its CLI
        └── Collects audit events from the ephemeral sandbox
        │
        ▼
JUnit report + TapPass trace bundle + recommended-policy-refinement
        │
        ▼
Establishes baseline → consumed by Drift monitor

---

7. Reference implementations

Purpose: worked examples that exercise the entire stack end-to-end. Proof the architecture composes.

Subcomponents:

Component	Role	Status
collibra-reference-agent	First example. Mock Collibra MCP + LangChain agent + demo script	concept
Subsequent agents (support emailer, code reviewer, refund processor, data engineer)	Demand-driven; each in its own repo	not yet components

Inherits from: every other engine in this list.

Status: concept; first delivery Q4 once architectural spine ships.

Lead owner: platform (initial scaffold), then handed to demo / sales / partner team.

---

8. Trust & compliance (operational)

Purpose: make TapPass procurement-defensible to enterprise / regulated / EU buyers. Not engineering work; calendar-bound.

Subcomponents:

Component	Role	Status
public-trust-page	Customer-facing claims (0-training, residency, encryption, sub-processors)	concept
soc2-type1-audit	External-auditor attested Type 1 report	concept; ~6 month calendar
ISO 27001 (planned)	Roadmap 2027	future
SOC 2 Type 2 (planned)	Roadmap 2027 H1	future

Inherits from: existing audit hash-chain, existing OSS compliance gates (liccheck + SBOM in 4 repos), existing trust center site.

Status: trust page expansion + Type 1 audit kicks off Q3; report by end Q4.

Lead owner: ops / compliance.

---

Cross-engine dependency graph (high level)

                  Operator surfaces (CLIs, dashboard, wizard)
                              │
                              ▼ authoring
                      ┌───────────────┐
                      │ Policy engine │
                      └───────┬───────┘
                              │ produces
                              ▼ layered keyring
              ┌───────────────────────────────────┐
              ▼                                   ▼
   ┌─────────────────────┐             ┌──────────────────┐
   │ Sync system         │             │ Evaluation engine│
   │ (push + drift)      │◀────baseline──── (eval runs)   │
   └──────────┬──────────┘             └──────────────────┘
              │ delivers + audits
              ▼
   ┌──────────────────────────────────────┐
   │ Sandbox runtime (host enforcement)   │◀── invokes ───┐
   │  + Tool governance engine            │               │
   └──────────────────────────────────────┘               │
              │ runs in / consumes                        │
              ▼                                           │
   ┌──────────────────────────────────────┐               │
   │ Reference implementations            │───────────────┘
   │ (Collibra agent, etc.)               │
   └──────────────────────────────────────┘

      Trust & compliance — runs alongside, not in the dependency graph

The Policy engine is the source of truth. The Sync system delivers. The Sandbox runtime + Tool governance enforce. The Evaluation engine pre-flights. Reference implementations exercise the whole stack. Trust & compliance is the operational frame.

---

When to use which view

You're a subagent who…	Use the	Best entry
owns a user-facing concern (e.g. compliance authoring, business onboarding)	Question view	README.md
owns a technical engine (e.g. the policy compiler, the sync system)	Systems view	(this file)
is implementing one specific component	Either view	go directly to the component file
is planning the work	Both	this file shows engine ownership; the roadmap sequences delivery
is onboarding to TapPass	Concept doc first	governed-agents-architecture.md, then this file

Both views point at the same component files. Pick the cut that matches your scope.