Data objects and their engines

The third view of the same components, organized around first-class domain entities (the nouns) and the engines that operate on them (the verbs). Plus quick-start templates and surfaces that consume them.

Three views of the same set:

README.md — Question view (which user-facing question does each component answer?)
SYSTEMS.md — Systems view (which technical engine does each component belong to?)
This file (Domain view) — Data objects + their engines (what are the nouns, what operates on them, what are the quick-starts?)

Pick the cut that matches your scope. Subagents working on a noun ("I own everything that touches Policy") use this view.

At a glance — the nouns

Data object	What it is	Status today
Policy	Rego rules authored by operators; the source of truth	core shipped (intent-to-policy); compiler new
Sandbox	A logical agent installation: identity + runtime env	new
Keyring (sandbox config)	Materialized policy for one sandbox; multi-layer	new
Tool	What agents can call (vendor SaaS, internal MCP, custom Python)	catalog shipped; discovery + proxy new
Audit / Trace	Hash-chained record of every governed event + the mandates that authorized	shipped (hash-chain + ES256); drift detection new
Probe	An adversarial test case run against an agent	new
Identity	SSO operator, machine host, scoped sandbox token	partial (SSO shipped; sandbox tokens new)
Function / Category / Concern / Capability	Intent-to-policy authoring sub-objects (compose into Policy)	shipped on main

Eight first-class entities. Everything else (engines, surfaces, bundles) operates on or composes from these.

1. Policy

What it is: Rego rule sets authored by operators. The single source of truth. Composed from intent-to-policy authoring sub-objects (Function / Categories / Concerns / Capabilities — see §8) and merged through the cascade.

Policy (data)
│
├── Engines that operate on it
│   ├── Authoring resolver  (shipped on main today)
│   │     • Function + categories → effective pipeline (L4 from intent-to-policy)
│   │     • ~40 LOC, ~470 tests
│   │
│   ├── Cascade merger  (concept)
│   │     • Merges org floor → project floor → agent overrides
│   │     • Strictest-wins; rejects relaxations of higher floors
│   │     → cascade-merge-engine
│   │
│   └── Policy compiler  (concept) ★ central
│         • Compiles merged pipeline + sandbox-spec → layered keyring
│         • Deterministic, cached per-org, emits provenance trail
│         → policy-to-sandbox-config-builder
│
├── Quick-starts (compliance bundles) — ready-made policies for common regulations
│   ├── EU AI Act bundle           (concept, Q3)
│   ├── OWASP LLM Top 10 bundle    (concept, Q3)
│   ├── GDPR bundle                (planned)
│   ├── PCI-DSS bundle             (planned)
│   ├── HIPAA bundle               (planned)
│   └── NIS2 / DORA bundle         (planned)
│
└── Surfaces that touch it
    ├── tappass policy apply / list / show / diff / rollback / --pack <name>
    └── Onboarding wizard (Step 1: function picker; Step 3: pack picker)

Owner: platform (engines) + compliance (bundle content).

2. Sandbox

What it is: A logical agent installation — identity + the layered runtime environment one agent runs in. Provisioned from a sandbox-spec.

Sandbox (data)
│
├── Engines that operate on it
│   ├── Sandbox-spec creator       (within operator CLI)
│   │     • Names the template that binds a policy to a set of layers
│   │
│   ├── Bootstrap URL issuer       (within operator CLI)
│   │     • Mints single-use, 15-min-TTL enrollment URLs
│   │
│   ├── Bootstrap consumer         (within tappass-host)
│   │     • Exchanges bootstrap → mTLS cert + initial keyring
│   │
│   ├── Sandbox revoker            (within operator CLI)
│   │     • Kills tokens; next call returns 401 sandbox_revoked
│   │
│   ├── Sandbox rotator            (within operator CLI)
│   │     • Forces token rotation now (without policy change)
│   │
│   └── Heartbeat / liveness       (within tappass-host daemon)
│         • Status surfaces back to dashboard: pending → active → offline
│
├── Quick-starts (sandbox-specs) — named templates per agent shape
│   ├── customer-support-emailer   (planned)
│   ├── refund-processor           (planned)
│   ├── code-reviewer              (planned)
│   ├── data-engineer-agent        (planned)
│   ├── collibra-steward           (planned, demo)
│   └── (custom)                   (always available)
│
└── Surfaces
    ├── tappass sandbox-spec create / list / emit-bootstrap
    ├── tappass sandbox list / revoke / rotate / keyring
    ├── tappass-host init / start / stop / status / inspect / shell / logs
    └── Dashboard: sandbox list with status per sandbox

Owner: platform (lifecycle) + cli (surfaces).

3. Keyring / Sandbox Config

What it is: Materialized policy for one specific sandbox — a multi-layer bundle (gateway / mcp / codemode / harness / kernel) containing tokens, URLs, capability scopes. Derived deterministically by the policy compiler. Read-only by the agent.

Keyring (data)
│
├── Engines that operate on it
│   ├── Policy compiler            (writes it)
│   │     → policy-to-sandbox-config-builder
│   │
│   ├── Live policy push channel   (delivers it)  ★ Q12
│   │     • Signed Ed25519, monotonic policy_version, anti-replay
│   │     → live-policy-push-channel
│   │
│   ├── Layer appliers             (consume each slice; apply at runtime)
│   │     ├── Kernel applier       — egress allowlist + Landlock + cred hiding
│   │     │     → ring-kernel
│   │     ├── Codemode applier     — executor profile (allowed/denied imports)
│   │     │     → ring-interpreter
│   │     ├── Harness applier      — writes settings.json equivalent
│   │     │     → ring-harness
│   │     ├── MCP applier          — pointer to tool governance engine
│   │     │     → cross-cutting-mcp-broker
│   │     └── Gateway applier      — pointer to existing gateway primitive
│   │           → cross-cutting-llm-gateway
│   │
│   └── Keyring inspector          (operator read-only view)
│         • tappass sandbox keyring <id>
│         • tappass-host inspect <name>
│
└── Surfaces
    ├── Filesystem (host writes; agent reads): /var/run/tappass/<sbx>/keyring.json
    ├── tappass-agent SDK: Keyring.load(); Client(kr); on_keyring_change()
    └── Dashboard: per-sandbox keyring view (sanitized, scopes-only for non-admin)

Owner: platform.

4. Tool

What it is: A named capability with arg schema and slot bindings. Vendor SaaS (gmail.send), internal MCP server tools (acme-internal.dispatch), or custom Python functions (LangChain @tool decorators).

Tool (data)
│
├── Engines that operate on it
│   ├── Tool catalog               (storage + lookup)
│   │     • Curated library (~30 entries shipped in v1)
│   │     • Per-tenant overrides (Pattern A, B, C from intent-to-policy §8)
│   │
│   ├── Approved tool-server list  (per-org MCP server allowlist)
│   │     • Vault-backed credentials; agent never sees them
│   │     → approved-tool-server-list
│   │
│   ├── Upstream tool proxy        (forwards agent's MCP traffic to approved servers)
│   │     • Pipeline runs on every forwarded call
│   │     → upstream-tool-proxy
│   │
│   ├── Runtime tool discovery     (default-deny + review queue)
│   │     • Captures unknown tools the agent emits; blocks until reviewed
│   │     • Audit-driven classification wizard (intent-to-policy §8b)
│   │     → concepts/runtime-tool-discovery.md
│   │
│   ├── Capability binder          (catalog ↔ concerns ↔ tools)
│   │     • Maps abstract capabilities (external_messaging, pci_dss_scope) to concrete tools
│   │     • Lives within authoring resolver
│   │
│   └── Pipeline steps             (per-call enforcement)
│         ├── Resource access checker  (schema_acl)
│         │     → resource-access-checker
│         └── Runaway agent stopper    (loop_guard)
│               → runaway-agent-stopper
│
├── Quick-starts (catalog tools shipped in v1)
│   ├── gmail.send         (capabilities: external_messaging)
│   ├── slack.send_message (capabilities: external_messaging)
│   ├── stripe.refund      (capabilities: pci_dss_scope, financial_write)
│   ├── github.create_issue, github.create_pr_comment
│   ├── jira.create_issue
│   ├── Bash, Read, Write, WebFetch, WebSearch
│   └── ~20 more (full list in `intent-to-policy.md` L3 catalog)
│
└── Surfaces
    ├── tappass mcp register / list / show / update / revoke
    ├── Dashboard: tool catalog, per-org overrides, runtime-tool review queue
    └── tappass policy show <ver> --tools (which tools are in scope for a policy)

Owner: platform (engines) + integrations (catalog content).

5. Audit / Trace

What it is: Hash-chained records of every governed call + the ES256 mandates that authorized them. The compliance evidence and the operational visibility, in one stream.

Audit / Trace (data)
│
├── Engines that operate on it
│   ├── Hash-chain audit writer    (shipped)
│   │     • SHA-256 chained, integrity verifiable
│   │
│   ├── ES256 mandate signer       (shipped)
│   │     • Signs every allow decision; verifiable offline via JWKS
│   │
│   ├── Trace aggregator           (shipped)
│   │     • Single trace_id threaded through every hop (LLM → tool → response)
│   │
│   ├── Verify-integrity routine   (shipped)
│   │     • Recomputes hash chain; flags tampering
│   │
│   ├── Drift baseline learner     (concept)
│   │     • Builds per-sandbox behavior baseline from pre-deployment eval
│   │     → behavior-drift-monitor
│   │
│   └── Drift signal evaluator     (concept)
│         • Compares production audit metrics to baseline; fires alerts
│         → behavior-drift-monitor (same component)
│
└── Surfaces
    ├── tappass audit tail [--sandbox <id>] [--layer <name>]
    └── Dashboard: trace timelines, audit views, drift alerts

Owner: platform.

6. Probe

What it is: A self-contained adversarial test case run against an agent under a candidate policy. Pass/fail criteria explicit and machine-evaluable.

Probe (data)
│
├── Engines that operate on it
│   ├── Pre-deployment evaluator   (concept) ★ Q4 priority
│   │     • Drives the agent through probe suite
│   │     • Spawns ephemeral sandbox with candidate keyring
│   │     • Returns JUnit XML + TapPass trace bundle + recommendations
│   │     → pre-deployment-evaluator
│   │
│   └── Custom probe SDK           (planned, v2)
│         • Customers add their own probes
│
├── Quick-starts (probe libraries)
│   ├── OWASP LLM probe library v1   (concept, ≥50 probes)
│   │     → owasp-llm-probe-library
│   ├── EU AI Act probe library      (planned)
│   ├── GDPR probes                  (planned)
│   └── PCI-DSS probes               (planned)
│
└── Surfaces
    ├── tappass eval run --agent <pkg> --policy <id> --packs <list>
    ├── CI integration: GitHub Action / GitLab CI templates
    └── Dashboard: per-agent eval history, regression deltas

Owner: platform (harness) + compliance (probe content).

7. Identity

What it is: Three principal types: Operator (SSO+MFA), Host (machine identity via mTLS), Agent (scoped sandbox token). Each authenticates differently, has different privileges, can do strictly different things.

Identity (data — three principal types)
│
├── Operator identity
│   ├── SSO + MFA authentication        (shipped)
│   ├── Short-lived JWT (1h)            (within operator-cli)
│   └── RBAC by team / project / org    (projects-teams substrate)
│
├── Host identity
│   ├── mTLS cert (TPM-bound optional)  (concept, Q3)
│   │     • Issued at tappass-host init from bootstrap exchange
│   │     • TTL: 1 hour; auto-renewed
│   ├── Bootstrap URL                   (single-use, 15-min, signed)
│   └── No SSO involved at any point
│
├── Agent identity
│   ├── Scoped sandbox token (gateway_token, mcp_session_token)  (concept)
│   │     • TTL: 5 minutes; renewed via sync push
│   │     • Zero admin scope; can only call gateway/MCP endpoints
│   └── Cannot be obtained except via host's keyring write
│
└── Surfaces
    ├── tappass auth login (operator)
    ├── tappass-host init (host)
    └── (no identity surface for the agent — it inherits from the host's keyring write)

Owner: platform.

8. Intent-to-policy authoring objects

What they are: The four sub-objects that compose into a Policy. Defined in intent-to-policy.md. Each owned by a different role; each editable as data, not code.

Authoring sub-objects (compose → Policy → §1)
│
├── Function       (~20 starter entries shipped)
│     • What is this agent for? (refund_processor, customer_support_emailer, ...)
│     • Owned by: Product / Compliance
│
├── Category       (UI labels)
│     • What kind of data? (customer_pii, payment_data, eu_residents, ...)
│     • Owned by: UX
│
├── Concern        (regulatory / risk vocabulary)
│     • What risks apply? (data_leak, pci_dss, gdpr_required, fraud_risk, ...)
│     • Owned by: Compliance
│
├── Capability     (tool abstraction)
│     • What can each tool do? (external_messaging, code_execution, pci_dss_scope)
│     • Owned by: Integrations
│
└── + Manual overlay      (operator-specific tweaks; stack on top with strictest-wins)

Engines (all shipped on main today):

Authoring resolver (~40 LOC; produces L4 effective pipeline)
Catalog management (8 tables; per-tenant override pattern)
Audit-driven discovery (concept; surfaces unknown tools for one-click classification)

Quick-starts: the curated catalogs ship with v1:

11 starter functions
7 starter categories
13 starter concerns
22 starter capabilities
30 starter tools

(Full catalog in intent-to-policy.md §5.)

Cross-reference: which engine owns which data object

Engine	Reads	Writes	Status
Authoring resolver	Function, Category, Concern, Capability	→ produces L4 effective pipeline	shipped
Cascade merger	3× Policy (org/project/agent)	→ merged Policy	concept
Policy compiler ★	Policy, Sandbox-spec, Tool catalog	→ Keyring	concept
Live policy push channel	Keyring	→ delivers to host	concept
Layer appliers	Keyring (their slice)	→ OS state	concept
Upstream tool proxy	Tool catalog, Approved tool-server list, Keyring	→ Audit	concept
Runtime tool discovery	Tool calls (observed)	→ Tool catalog (status=pending)	concept
Hash-chain audit	every governed call	→ Audit	shipped
Mandate signer	every allow decision	→ Audit (ES256-signed)	shipped
Drift monitor	Audit (production), Drift baseline	→ Alerts	concept
Pre-deployment evaluator	Probe library, Policy, Agent	→ Eval report, Drift baseline	concept
Bootstrap URL issuer	Sandbox	→ Bootstrap URL (single-use)	concept
Sandbox-spec creator	(operator input)	→ Sandbox-spec	concept

The Policy compiler is the central engine — it's where the most data objects converge (Policy + Sandbox-spec + Tool catalog → Keyring), and where downstream delivery and enforcement begin.

Quick-starts as a category

Every data object that customers configure has a quick-start lane. Customers can ignore them and configure manually, but quick-starts are the fastest path to a procurement-defensible deployment:

Data object	Quick-starts	What they save the customer
Policy	Compliance bundles (EU AI Act, OWASP LLM, GDPR, …)	Don't author Rego from scratch; tick a box
Sandbox	Sandbox-specs (refund-processor, code-reviewer, …)	Don't compose layers from scratch; pick a template
Tool	Curated catalog (~30 well-known SaaS)	Don't classify gmail/slack/stripe yourself
Probe	Probe libraries (OWASP LLM, EU AI Act)	Don't author adversarial probes from scratch
Authoring sub-objects	Catalog of 11 functions, 7 categories, 13 concerns, 22 capabilities	Don't build the vocabulary from scratch

This is the substrate of the substrate. When a customer adopts TapPass, they shouldn't be building any of these from scratch — they should be picking from quick-starts and adjusting at the margins.

When to use which view

If you're thinking about…	Use the
A user-facing concern (compliance authoring, business onboarding)	Question view
A technical engine (the policy compiler, the sync system)	Systems view
A noun (Policy, Tool, Audit, Probe)	This file (Domain view)
Implementing one specific component	the component file directly
Sequencing the work	the roadmap
The big-picture vision	governed-agents-architecture.md

All four views point at the same component files. Navigate from whichever cut matches your scope.