stack/docs/scratchpads/tess-m1-002-provider-registry.md

TESS-M1-002 — Provider Registry

• Issue: #707
• Branch: feat/tess-provider-registry
• Objective: Build the runtime provider registry/service boundary that derives immutable actor/tenant/channel/correlation scope server-side, fail-closes unsupported and destructive runtime operations, binds termination approval to the exact structured action, and emits correlation-safe audit events.

Plan

1. Add a provider-agnostic registry in @mosaicstack/agent over the merged AgentRuntimeProvider contract.
2. Write abuse-case tests before implementation for duplicate/unknown providers, immutable server-derived scope, capability denial, approval mismatch/absence, and audit failure.
3. Implement the Gateway service that converts only authenticated ActorTenantScope plus trusted ingress metadata into a frozen RuntimeScope, gates capabilities and terminate approval, and records metadata-only audits.
4. Register the service in AgentModule, then run focused, baseline, cold-cache, and independent-review gates.

Security Invariants

• Caller-supplied actor/tenant identity never reaches runtime providers.
• Provider capability absence and approval/audit failure deny before side effects.
• Termination approval is verified against provider, session, actor, tenant, channel, and correlation context.
• Audit events retain correlation and authority metadata but never message content or approval material.

Progress

• 2026-07-12: Created fresh worktree from origin/main at 119f64e6; source and Tess planning/security documentation reviewed.
• 2026-07-12: Security TDD added registry and gateway abuse tests before implementation.
• 2026-07-12: Implemented AgentRuntimeProviderRegistry and gateway RuntimeProviderService; registered both in AgentModule and documented the internal boundary.
• 2026-07-12: Independent review found two audit correctness issues. Remediated completion-audit failure handling and provider execution failures: pre-invocation denials are audited as denied; post-invocation errors as failed; completion audit failure does not misreport a completed effect as retryable.
• 2026-07-12: Final independent security review: no findings. Final code review had one false positive: @mosaicstack/types is already declared in packages/agent/package.json.

Tests

• TDD red: pnpm --filter @mosaicstack/gateway test -- runtime-provider-registry.service.test.ts failed before both audit remediations, as expected.
• Focused: package registry 2 tests and gateway security boundary 7 tests pass.
• Cold-cache: removed this worktree's node_modules, then pnpm install --offline --frozen-lockfile --store-dir /home/jarvis/.local/share/pnpm/store passed.
• Cold-cache baseline: TURBO_FORCE=true pnpm typecheck — 42/42 tasks passed; TURBO_FORCE=true pnpm lint — 23/23 tasks passed; TURBO_FORCE=true pnpm format:check passed; TURBO_FORCE=true pnpm test — 42/42 tasks passed (gateway 548 tests passed, 11 intentionally skipped).

Risks / Blockers

• The canonical durable approval implementation is currently command-specific. This card introduces a fail-closed runtime approval verifier boundary so a runtime provider cannot terminate until its exact-action verifier is wired; later provider implementations cannot bypass it.