2026-05-10-docs-trust-envelope-x2

Docs: Trust Envelope + Reputation + XDR Pipeline

Date: 2026-05-10 Status: shipped Slug: docs-trust-envelope-x2 Branch: feature/docs-trust-envelope-x2 Companion to: PRs #252-#270 (the full Trust Envelope + XDR strategic thread)

Summary

Adds three concept pages and one API-reference section to cover the trust envelope, agent reputation, and XDR pipeline work. Updates llms.txt (both the embedded server const and the static copy) and docs/openapi.yaml so external auditors and AI agents discovering the API see the new surface.

This closes the doc gap that opened across PRs #252-#270: the code shipped ahead of documentation, which is the right ordering for a strategic thread running under a no-deploy-gate principle, but the docs need to land before external review.

What's new

Concept pages (`docs/concepts/`)

trust-envelope.mdx — the canonical schema reference. Covers JOSE

alignment, all 6 claim sub-objects with field-by-field types, the three-mode pattern (off / warn / enforce), the audit-only synth mode, what each gate reads (routing / budget / guardrails), the synthesis cost (6-16ms cold, sub-1ms warm), failure-mode semantics (fail-open in A-1, fail-closed in enforce mode).

agent-reputation.mdx — the 5-tier system. Explains

restricted/bronze/silver/gold/platinum, cert lifetime per tier, signal precedence (tier first, then xdr_risk >= 0.7, then anomaly_score >= 0.8), outcome recording from completion paths, parent-chain inheritance rules (conservative — min(child.tier, all parents.tier)), promotion thresholds.

xdr-pipeline.mdx — the SIEM/XDR side. Covers OCSF 1.3.0 mapping, all

five first-party adapters (CrowdStrike, Sentinel, Splunk-OCSF, Cortex, Datadog-OCSF) with their auth schemes, the 52-event taxonomy across nine categories, the PII hard rule with the no-pii-leak test enforcement, filter rules with glob semantics (* = [^.]+), bidirectional risk-push, per-tenant config CRUD, the latency budget table.

API reference (`docs/api-reference/observability.mdx`)

Appended sections covering:

7 XDR destination CRUD endpoints (/v1/observability/xdr/destinations*)
Bidirectional risk-push (POST /v1/admin/xdr/risk-push, risk-clear)
Filter rules format with examples

OpenAPI (`docs/openapi.yaml`)

Added all 9 new endpoints with full request/response schemas:

XdrDestination schema (with redaction note for secrets)
DestinationFilterRules schema (with glob semantics)
7 XDR config CRUD operations
2 admin risk-push/clear operations

docs/openapi.yaml is the source of truth for OPENAPI_SPEC in src/api/static-assets.generated.ts (regenerated by pnpm build) — the runtime GET /openapi.json now includes all XDR routes. The static copy at site/public/openapi.yaml was synced for the docs site.

LLM artifacts

src/api/server.ts — embedded LLMS_TXT_CONTENT updated with three new

Core Concepts links (trust-envelope, agent-reputation, xdr-pipeline)

site/public/llms.txt — same update for the static docs-site copy
site/public/llms-full.txt — auto-regenerated by pnpm build, picks up

new openapi entries

Docs site nav (`docs/docs.json`)

Three new pages added to the "Core Concepts" group, positioned between agent-lifecycle and graduated-trust so the trust-envelope reads first.

Existing page updates

concepts/graduated-trust.mdx — added a `` clarifying the

relationship between the 4-level runtime trust system (this page) and the 5-tier reputation system (new page). Both feed the envelope; precedence is fixed.

Verification

Schema accuracy

Every claim citation was verified against actual code before writing:

Schema fields against src/security/trust-envelope/schema.ts

(Zod validator at line 135 + TypeScript type at line 45)

Routing-gate constants (XDR_RISK_THRESHOLD = 0.7,

ANOMALY_DOWNGRADE_THRESHOLD = 0.8) and the TIER_STRATEGY mapping against src/security/trust-envelope/routing-gates.ts:44-60

Tier values against ReputationTierSchema enum
7 XDR routes against src/api/routes/xdr.ts:144-446
Adapter file paths against src/observability/xdr/adapters/*.ts
52-event count against PLATFORM_EVENT_TYPES array in dispatcher.ts (X-2 + 1 prior original)
PII hard-rule enforcement against no-pii-leak.test.ts
Filter-rule glob semantics against passesFilterRules /

matchesGlob in src/observability/broadcast.ts

Build

pnpm build — clean, regenerated llms-full.txt + routes.json (447 routes)
python3 -c 'import yaml; yaml.safe_load(...)' on docs/openapi.yaml — valid
python3 -m json.tool docs/docs.json — valid

Lockstep

TS SDK / Python SDK / MCP tools — already shipped in #268 (X-8 lockstep)

and #262 (X-7 lockstep). No SDK surface change in this PR.

Ship log — this file.
pnpm exec oxfmt --check / oxlint — no source code changes that affect

these (only src/api/server.ts LLMS_TXT_CONTENT string change).

What this PR does NOT cover

A counterfactual replay endpoint (A-8) does not exist yet, so the related

doc reference in concepts/trust-envelope.mdx is forward-looking.

The autonomous reputation promotion engine ships in a follow-up; the docs

describe target policy and explicitly note current state.

TEE attestation (attestation_hash claim) is reserved space — schema

documented, no implementation yet.

Audit prep

This PR is the input to a Perplexity-driven correctness audit per the Computer Protocol. The audit will check claim citations against the live code in main and flag any drift. Three areas where future drift is most likely:

Tier strategy mapping — if TIER_STRATEGY in routing-gates.ts is

extended (e.g. silver → "balanced" instead of undefined), the table in agent-reputation.mdx must be updated.

XDR adapter list — if a new SIEM connector lands, the table in

xdr-pipeline.mdx and the enum in openapi.yaml must both be updated. The completeness gate test catches drift in EVENT_MAP, but adapter type enum drift is not gated yet.

Event count — the doc cites "51 event types" — when X-2 follow-ups

add more event types, this number will need updating. Consider a doc linter that asserts PLATFORM_EVENT_TYPES.length === N matches the docs.

These three drift surfaces should be added to a future "doc-gate" CI job.