#572 Playbook Agent: types and abstract interfaces (1/8)

Summary

Foundation for the playbook agent framework — the type system and abstract contracts.

Part 1 of 8 in the playbook agent stack (#659). Review this first — all subsequent PRs depend on it.

What is the Playbook Agent?

An AI investigation framework that automates evidence gathering, deterministic rule evaluation, and LLM-powered verdicts for content moderation. Ported from Block's internal Risk Goose Agent as open-source components for Coop.

playbookTypes.ts — Declarative investigation config types

• SemanticVersion with parsing/formatting (pinned versions only, no "latest")
• CatalogReference for versioned query references
• Playbook config: evidence ontology, labels, decision logic, confidence weights, output contracts
• PlaybookVerdict and ConfidenceBreakdown result types
• QueryResult/QueryResults for evidence store responses

interfaces.ts — Abstract contracts (implement these to integrate)

• ILLMAdapter — pluggable LLM provider (OpenAI, Anthropic, local models, etc.)
• IEvidenceStore — execute pre-approved queries by catalog_id@version
• IArtifactStore — insert-only storage for immutable audit trail
• IPlaybookRunner — core runner interface

Key design decision

Playbooks reference queries by catalog_id@version and never contain SQL, table names, or field mappings. This is enforced at the type level.

PR Stack

Part	PR	Description	Status
1	#572 Types and interfaces	Foundation types and abstract contracts	This PR
2	#573 Playbook loader	YAML parsing and cross-reference validation	Depends on #572
3	#574 Query catalog	Pre-approved SQL template resolution	Depends on #573
4	#575 Hard rule engine	Deterministic pre-LLM decisions	Depends on #574
5	#576 Confidence engine	Grounded scoring formula	Depends on #575
6	#577 JSON extractor	Robust LLM output parsing	Depends on #576
7	#578 Runner and service	Orchestrator and Coop integration	Depends on #577
8	#579 Examples and walkthrough	Concrete examples exercising every component	Depends on #578

Test plan

• Types compile without errors
• No runtime code — pure type definitions and utility functions

Summary by CodeRabbit

• New Features

  • Introduced a playable investigation framework: configurable playbooks with versioned catalog references, evidence ontology, query policies, deep-dive modules, decision logic, and confidence breakdowns.
  • Outputs include structured verdicts, execution timing, session IDs, and stored investigation artifacts.

• Chores

  • Added adapters and stores to enable language-model integration, evidence lookups, artifact persistence, and orchestrated playbook runs.