switchboard-cli 0.1.0-alpha.1 → 0.1.0-alpha.3

package/node_modules/@switchboard/core/src/types.ts

@@ -0,0 +1,3054 @@
+import { z } from "zod";
+
+const nonEmptyString = z.string().trim().min(1);
+const nonEmptyStringArray = z.array(nonEmptyString);
+
+export const SURFACE_LABELS = {
+  chatgpt: "ChatGPT",
+  "claude-code": "Claude Code",
+  cursor: "Cursor",
+  codex: "Codex",
+} as const;
+
+export const surfaceSchema = z.enum(["chatgpt", "claude-code", "cursor", "codex"]);
+export const repoStatusSchema = z.enum(["repo-present", "repo-not-present"]);
+export const returnStatusSchema = z.enum(["not-started", "done", "partial", "blocked"]);
+export const objectiveMetSchema = z.enum(["yes", "no", "partial"]);
+export const executionShapeSchema = z.enum(["single", "bounded_parallel_research", "bounded_parallel_implementation"]);
+export const launchReadinessStatusSchema = z.enum(["ready", "missing required boundary info", "needs clarification"]);
+
+export const projectContractSchema = z.object({
+  project_id: nonEmptyString,
+  title: nonEmptyString,
+  one_liner: nonEmptyString,
+  problem: nonEmptyString,
+  target_user: nonEmptyString,
+  desired_v1_outcome: nonEmptyString,
+  non_goals: nonEmptyStringArray.min(1),
+  repo_status: repoStatusSchema,
+  // Task-specific clauses — narrower than brand-level non_goals
+  task_clauses: z.object({
+    scope_in: z.array(z.string()).default([]),
+    scope_out: z.array(z.string()).default([]),
+    systems_expected: z.array(z.string()).default([]),
+    files_allowed: z.array(z.string()).default([]),
+    must_not_widen: z.array(z.string()).default([]),
+    build_constraints: z.array(z.string()).default([]),
+  }).default({
+    scope_in: [], scope_out: [], systems_expected: [],
+    files_allowed: [], must_not_widen: [], build_constraints: [],
+  }),
+});
+
+export const projectCharterSchema = z.object({
+  title: nonEmptyString,
+  intent: nonEmptyString,
+  target_user: nonEmptyString,
+  first_bounded_slice: z.string().default(""),
+  scope_in: z.array(z.string()),
+  scope_out: z.array(z.string()),
+  protected_boundaries: z.array(z.string()),
+  systems_touched: z.array(z.string()),
+  repo_binding: z.string().default(""),
+  unresolved_assumptions: z.array(z.string()),
+  missingness: z.array(z.string()),
+  confidence: z.enum(["high", "medium", "low"]),
+  task_type: z.string(),
+  created_at: z.string(),
+});
+
+export const workingStateSchema = z.object({
+  stage: nonEmptyString,
+  current_objective: nonEmptyString,
+  dominant_uncertainty: nonEmptyString,
+  open_questions: nonEmptyStringArray,
+  primary_artifact_ref: nonEmptyString,
+  active_handoff_id: z.string(),
+  last_return_status: returnStatusSchema,
+  latest_decisions: nonEmptyStringArray.default([]),
+  latest_blockers: nonEmptyStringArray.default([]),
+  next_recommended_surface: surfaceSchema,
+  next_objective: nonEmptyString,
+});
+
+/**
+ * UI-only derivation type: what happens to downstream artifacts when the
+ * operator edits a charter-level field.  Never persisted — computed at render.
+ */
+export type CharterFieldConsequence =
+  | "still_valid"
+  | "stale_recompile"
+  | "stale_redispatch";
+
+export const activationInputSchema = z.object({
+  raw_idea: nonEmptyString,
+  repo_exists: z.boolean(),
+  what_do_you_want_next: nonEmptyString,
+  constraints: z.string().trim().default(""),
+});
+
+// ---------------------------------------------------------------------------
+// Product Objects: Ask → Compile → Run
+// ---------------------------------------------------------------------------
+
+/**
+ * Ask — a bounded inquiry. The operator's raw intent, captured and scoped
+ * into something the system can compile.
+ *
+ * NOT a prompt. NOT a wish. An Ask has identity and becomes the seed of
+ * canonical state after compilation.
+ */
+export const askSchema = z.object({
+  ask_id: z.string(),
+  raw_idea: nonEmptyString,
+  repo_exists: z.boolean(),
+  what_do_you_want_next: nonEmptyString,
+  constraints: z.string().trim().default(""),
+  created_at: z.string(),
+  source: z.enum(["operator", "next-slice", "re-dispatch"]).default("operator"),
+});
+
+/**
+ * Compile — a governed control object produced from an Ask. Contains the
+ * locked contract, charter, routing decision, and candidate brief.
+ *
+ * NOT synthesis (which enriches). NOT execution (which acts). A Compile
+ * is the governed artifact that dispatch reads from.
+ */
+export const compileSchema = z.object({
+  compile_id: z.string(),
+  ask_id: z.string(),
+  contract_id: z.string(),
+  task_type: z.string(),
+  complexity_mode: z.string(),
+  route_surface: z.string(),
+  compiled_at: z.string(),
+  lock_readiness: z.string(), // lock_allowed / lock_allowed_with_cautions / lock_blocked
+});
+
+/**
+ * Run — a compiled execution packet dispatched under a governed contract.
+ * Bundles dispatch identity, receipt, and return linkage.
+ *
+ * NOT an execution (which is what the surface does). NOT a task (which has
+ * no governance lifecycle). A Run has dispatch provenance and expects a
+ * structured return.
+ */
+export const runSchema = z.object({
+  run_id: z.string(),
+  ask_id: z.string(),
+  compile_id: z.string(),
+  handoff_id: z.string(),
+  dispatch_id: z.string(),
+  receipt_id: z.string().default(""),
+  surface: z.string(),
+  objective: z.string(),
+  dispatched_at: z.string(),
+  // Return linkage (populated after return)
+  return_id: z.string().default(""),
+  delta_id: z.string().default(""),
+  gate_outcome: z.string().default(""),
+  completed_at: z.string().default(""),
+});
+
+export type Ask = z.infer<typeof askSchema>;
+export type Compile = z.infer<typeof compileSchema>;
+export type Run = z.infer<typeof runSchema>;
+
+export const routingInputSchema = z.object({
+  repo_present: z.boolean(),
+  task: nonEmptyString,
+  last_return_status: z.enum(["done", "partial", "blocked"]).optional(),
+  last_return_reason: z.string().trim().optional(),
+  seed_confidence: z.enum(["high", "medium", "low"]).optional(),
+  research_needed: z.boolean().optional(),
+  process_mode: z.enum(["minimal", "structured", "governance"]).optional(),
+});
+
+export const routingResultSchema = z.object({
+  primary_recommendation: surfaceSchema,
+  fallback_surface: surfaceSchema,
+  rationale: nonEmptyString,
+  next_objective: nonEmptyString,
+  return_condition: nonEmptyString,
+});
+
+export const loopContractSchema = z.object({
+  objective: nonEmptyString,
+  scope_in: nonEmptyStringArray.min(1),
+  scope_out: nonEmptyStringArray.min(1),
+  done_when: nonEmptyStringArray.min(1),
+  success_criteria: nonEmptyStringArray.min(1),
+  verify_with: nonEmptyStringArray.min(1),
+  return_when: nonEmptyString,
+  blocker_escalation: nonEmptyStringArray.min(1),
+  expected_artifacts: nonEmptyStringArray.min(1),
+  fallback_surface: surfaceSchema,
+  execution_shape: executionShapeSchema,
+});
+
+export const launchReadinessSchema = z.object({
+  status: launchReadinessStatusSchema,
+  issues: nonEmptyStringArray.default([]),
+});
+
+export const surfacePlaybookSchema = z.object({
+  surface: surfaceSchema,
+  notes: nonEmptyStringArray.min(1),
+});
+
+export const handoffRecordSchema = z.object({
+  handoff_id: nonEmptyString,
+  surface: surfaceSchema,
+  objective: nonEmptyString,
+  included_scope: nonEmptyStringArray.min(1),
+  excluded_scope: nonEmptyStringArray.min(1),
+  done_when: nonEmptyStringArray.min(1),
+  return_condition: nonEmptyString,
+  loop: loopContractSchema,
+  readiness: launchReadinessSchema,
+  bundle_version: z.literal("SBX-v1"),
+  launched_at: z.string().optional(),
+});
+
+export const returnReportSchema = z
+  .object({
+    handoff_id: nonEmptyString,
+    surface_used: surfaceSchema,
+    objective_attempted: nonEmptyString,
+    status: z.enum(["done", "partial", "blocked"]),
+    objective_met: objectiveMetSchema,
+    done_when_met: objectiveMetSchema,
+    summary: nonEmptyString,
+    changed_files: z.array(z.string().trim()).default([]),
+    decisions_made: z.array(z.string().trim()).default([]),
+    blockers: z.array(z.string().trim()).default([]),
+    escalations: z.array(z.string().trim()).default([]),
+    evidence: z.array(z.string().trim()).default([]),
+    success_criteria_met: z.array(z.string().trim()).default([]),
+    verification_run: z.array(z.string().trim()).default([]),
+    artifacts_created: z.array(z.string().trim()).default([]),
+    recommended_next_step: nonEmptyString,
+    // Cursor packet binding — required when surface_used is "cursor".
+    // Binds the return to the governed packet that was transported.
+    packet_id: z.string().trim().default(""),
+    // SHA-256 prefix hash of the governed packet content at generation time.
+    // Verified on Cursor return ingest to detect silent content edits.
+    packet_hash: z.string().trim().default(""),
+  })
+  .superRefine((value, ctx) => {
+    if (value.objective_met === "yes" && value.evidence.length === 0 && value.verification_run.length === 0) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "objective_met=yes requires evidence or verification_run.",
+        path: ["objective_met"],
+      });
+    }
+
+    if (value.done_when_met === "yes" && value.success_criteria_met.length === 0) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "done_when_met=yes requires at least one met success criterion.",
+        path: ["done_when_met"],
+      });
+    }
+
+    if (value.status === "done" && value.done_when_met === "no") {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "A done return cannot report done_when_met=no.",
+        path: ["status"],
+      });
+    }
+  });
+
+export const sbxFileSchema = z.object({
+  path: nonEmptyString,
+  content: nonEmptyString,
+});
+
+export const sbxBundleSchema = z.object({
+  bundle_name: nonEmptyString,
+  launch_prompt: nonEmptyString,
+  files: z.array(sbxFileSchema).min(5),
+});
+
+export const runtimePackSchema = z.object({
+  pack_name: nonEmptyString,
+  files: z.array(sbxFileSchema).min(1),
+});
+
+export type Surface = z.infer<typeof surfaceSchema>;
+export type ProjectContract = z.infer<typeof projectContractSchema>;
+export type ProjectCharter = z.infer<typeof projectCharterSchema>;
+export type WorkingState = z.infer<typeof workingStateSchema>;
+export type ActivationInput = z.infer<typeof activationInputSchema>;
+export type RoutingInput = z.infer<typeof routingInputSchema>;
+export type RoutingResult = z.infer<typeof routingResultSchema>;
+export type LoopContract = z.infer<typeof loopContractSchema>;
+export type LaunchReadiness = z.infer<typeof launchReadinessSchema>;
+export type SurfacePlaybook = z.infer<typeof surfacePlaybookSchema>;
+export type HandoffRecord = z.infer<typeof handoffRecordSchema>;
+export type ReturnReport = z.infer<typeof returnReportSchema>;
+export type SbxBundle = z.infer<typeof sbxBundleSchema>;
+export type RuntimePack = z.infer<typeof runtimePackSchema>;
+
+export type ProjectSnapshot = {
+  contract: ProjectContract;
+  current: WorkingState;
+  spec_markdown: string;
+  latest_handoff: HandoffRecord | null;
+  latest_return: ReturnReport | null;
+  active_handoff: HandoffRecord | null;
+  route: RoutingResult;
+};
+
+// ---------------------------------------------------------------------------
+// Synthesis spine types
+// ---------------------------------------------------------------------------
+
+export const taskTypeSchema = z.enum(["product-idea", "implementation-request", "unknown"]);
+
+export const synthesizedSeedSchema = z.object({
+  title: nonEmptyString,
+  one_liner: nonEmptyString,
+  problem: nonEmptyString,
+  proposed_solution: nonEmptyString,
+  target_user: nonEmptyString,
+  v1_outcome: nonEmptyString,
+  non_goals: nonEmptyStringArray.min(1),
+  missing_inputs: z.array(z.string().trim()).default([]),
+  open_questions: z.array(z.string().trim()).default([]),
+  first_build_slice: z.string().trim().default(""),
+  confidence: z.enum(["high", "medium", "low"]),
+  task_type: taskTypeSchema.default("unknown"),
+});
+
+// ---------------------------------------------------------------------------
+// Provider / dispatch types
+// ---------------------------------------------------------------------------
+
+export const providerCapabilitySchema = z.enum(["compile", "execute"]);
+
+export const providerIdSchema = z.enum([
+  "claude-code-sdk",
+  "openai-api",
+  "codex",
+  "chatgpt-auto",
+  "chatgpt-manual",  // deprecated — kept for schema backward compat
+  "cursor-manual",
+  "internal-fallback",
+]);
+
+export const providerStatusSchema = z.enum(["available", "needs-setup", "stub"]);
+
+export const providerEntrySchema = z.object({
+  id: providerIdSchema,
+  name: nonEmptyString,
+  capability: providerCapabilitySchema,
+  automated: z.boolean(),
+  status: providerStatusSchema,
+  requires_env: z.array(z.string()).default([]),
+});
+
+// ---------------------------------------------------------------------------
+// Execution Surface Abstraction
+// ---------------------------------------------------------------------------
+
+/**
+ * Surface classes — what kind of interface the execution surface exposes.
+ *
+ * Switchboard sits ABOVE all surfaces. It does not assume uniform API access.
+ * Each surface class defines what the control plane can expect in terms of
+ * dispatch, acknowledgment, and return.
+ */
+export const surfaceClassSchema = z.enum([
+  "api",            // Programmatic SDK/API (Claude Agent SDK, OpenAI API)
+  "cli",            // Command-line tool (Codex CLI, local scripts)
+  "ide",            // Interactive IDE (Cursor, VS Code extensions)
+  "manual",         // Human-mediated handoff (paste into ChatGPT, manual copy)
+  "file_based",     // File drop / watch (export SBX bundle, import return YAML)
+  "audit_only",     // Read-only audit surface (Codex audit, review tools)
+]);
+
+export const surfaceCapabilitiesSchema = z.object({
+  can_dispatch_programmatically: z.boolean(),
+  can_acknowledge: z.boolean(),
+  can_return_structured: z.boolean(),
+  can_stream: z.boolean(),
+  requires_human_in_loop: z.boolean(),
+  supports_working_directory: z.boolean(),
+});
+
+export const surfaceProfileSchema = z.object({
+  surface_id: z.string(),
+  surface_class: surfaceClassSchema,
+  display_name: z.string(),
+  capabilities: surfaceCapabilitiesSchema,
+  receipt_model: z.enum([
+    "synchronous",    // API: dispatch → ack → return in one call
+    "async_callback", // CLI: dispatch, poll or wait for return
+    "human_return",   // Manual: operator pastes/uploads return
+    "file_watch",     // File: watch directory for return YAML
+    "none",           // Audit-only: no return expected
+  ]),
+  packet_format: z.enum([
+    "sdk_prompt",     // Full prompt string for SDK dispatch
+    "sbx_bundle",     // SBX export bundle (markdown + YAML)
+    "clipboard",      // Copy-paste-ready text
+    "file_drop",      // File written to working directory
+  ]),
+});
+
+export type SurfaceClass = z.infer<typeof surfaceClassSchema>;
+export type SurfaceCapabilities = z.infer<typeof surfaceCapabilitiesSchema>;
+export type SurfaceProfile = z.infer<typeof surfaceProfileSchema>;
+
+export const inferredChipSchema = z.object({
+  id: z.string(),
+  label: z.string(),
+  category: z.enum(["boundary", "system", "source", "user-type"]),
+  selected: z.boolean(),
+  inferred_from: z.string().default(""),
+});
+
+export const followUpQuestionSchema = z.object({
+  question: z.string(),
+  why: z.string(),
+  options: z.array(z.string()).optional(),
+});
+
+/** Draft charter fields shown before activation (same source as compile seed). */
+export const activationPreviewSchema = z.object({
+  title: z.string(),
+  one_liner: z.string(),
+  problem: z.string(),
+  proposed_solution: z.string(),
+  target_user: z.string(),
+  v1_outcome: z.string(),
+  non_goals: z.array(z.string()),
+  first_build_slice: z.string(),
+  open_questions: z.array(z.string()),
+  missing_inputs: z.array(z.string()),
+  confidence: z.enum(["high", "medium", "low"]),
+  task_type: taskTypeSchema,
+});
+
+export const activationLockStateSchema = z.enum(["ready_to_lock", "blocked_by_missing_evidence"]);
+
+export const intakeAnalysisSchema = z.object({
+  task_type: taskTypeSchema,
+  chips: z.array(inferredChipSchema),
+  follow_ups: z.array(followUpQuestionSchema),
+  confidence_note: z.string().default(""),
+  activation_preview: activationPreviewSchema,
+  /** Whether the target user was explicitly stated in the raw idea (not a placeholder). */
+  target_user_on_record: z.boolean(),
+  activation_state: activationLockStateSchema,
+  lock_blocking_requirements: z.array(z.string()),
+  lock_cautions: z.array(z.string()),
+  lock_tracked_open: z.array(z.string()),
+});
+
+export type ActivationPreview = z.infer<typeof activationPreviewSchema>;
+export type InferredChip = z.infer<typeof inferredChipSchema>;
+export type FollowUpQuestion = z.infer<typeof followUpQuestionSchema>;
+export type IntakeAnalysis = z.infer<typeof intakeAnalysisSchema>;
+export type ActivationLockState = z.infer<typeof activationLockStateSchema>;
+export type TaskType = z.infer<typeof taskTypeSchema>;
+export type ProviderId = z.infer<typeof providerIdSchema>;
+export type ProviderCapability = z.infer<typeof providerCapabilitySchema>;
+export type ProviderStatus = z.infer<typeof providerStatusSchema>;
+export type ProviderEntry = z.infer<typeof providerEntrySchema>;
+
+export const researchAngleSchema = z.object({
+  category: z.enum([
+    "user-validation",
+    "technical-feasibility",
+    "competitive-landscape",
+    "domain-knowledge",
+    "implementation-pattern",
+  ]),
+  question: nonEmptyString,
+  why_it_matters: nonEmptyString,
+  priority: z.enum(["blocking", "strengthening", "nice-to-have"]),
+});
+
+export const researchClassificationSchema = z.object({
+  angles: z.array(researchAngleSchema),
+  research_needed: z.boolean(),
+  summary: nonEmptyString,
+});
+
+export const reconcileFindingSchema = z.object({
+  category: z.enum([
+    "scope-inflation",
+    "non-goal-violation",
+    "goal-drift",
+    "target-user-shift",
+    "untracked-decision",
+    "evidence-contradiction",
+  ]),
+  description: nonEmptyString,
+  severity: z.enum(["warning", "review-required"]),
+  source_field: nonEmptyString,
+  parent_evidence: z.string().trim().default(""),
+});
+
+export const reconcileReportSchema = z.object({
+  findings: z.array(reconcileFindingSchema),
+  drift_detected: z.boolean(),
+  recommendation: z.enum(["accept", "accept-with-warnings", "review-required"]),
+  cleared_count: z.number().default(0),
+  checked_count: z.number().default(0),
+});
+
+export type SynthesizedSeed = z.infer<typeof synthesizedSeedSchema>;
+export type ResearchAngle = z.infer<typeof researchAngleSchema>;
+export type ResearchClassification = z.infer<typeof researchClassificationSchema>;
+export type ReconcileFinding = z.infer<typeof reconcileFindingSchema>;
+export type ReconcileReport = z.infer<typeof reconcileReportSchema>;
+
+// ---------------------------------------------------------------------------
+// Control plane types — complexity, process mode, compiler adapter
+// ---------------------------------------------------------------------------
+
+export const complexityVerdictSchema = z.enum(["simple", "standard", "dangerous"]);
+
+export const processModeSchema = z.enum(["minimal", "structured", "governance"]);
+
+export const complexitySignalSchema = z.object({
+  implied_systems: z.number(),
+  missing_target_user: z.boolean(),
+  missing_workflow: z.boolean(),
+  missing_trust_boundary: z.boolean(),
+  scope_breadth: z.enum(["narrow", "moderate", "broad"]),
+  contradiction_count: z.number(),
+  resource_mismatch: z.boolean(),
+});
+
+export const complexityClassificationSchema = z.object({
+  verdict: complexityVerdictSchema,
+  mode: processModeSchema,
+  signals: complexitySignalSchema,
+  rationale: nonEmptyString,
+});
+
+export const compilerTypeSchema = z.enum([
+  "fidelity-first",
+  "execution-first",
+  "internal-fallback",
+]);
+
+export const compilerSelectionSchema = z.object({
+  compiler_type: compilerTypeSchema,
+  recommended_surface: surfaceSchema,
+  rationale: nonEmptyString,
+});
+
+export type ComplexityVerdict = z.infer<typeof complexityVerdictSchema>;
+export type ProcessMode = z.infer<typeof processModeSchema>;
+export type ComplexitySignals = z.infer<typeof complexitySignalSchema>;
+export type ComplexityClassification = z.infer<typeof complexityClassificationSchema>;
+export const artifactStatusSchema = z.enum(["candidate", "canonical"]);
+
+export const candidateArtifactSchema = z.object({
+  spec_markdown: nonEmptyString,
+  source: compilerTypeSchema,
+  status: artifactStatusSchema,
+  reconcile: reconcileReportSchema.optional(),
+});
+
+export type CompilerType = z.infer<typeof compilerTypeSchema>;
+export type CompilerSelection = z.infer<typeof compilerSelectionSchema>;
+export const operatorReviewSchema = z.object({
+  date: nonEmptyString,
+  judgment: z.enum(["correct", "too-strict", "too-lenient"]),
+  note: z.string().trim().default(""),
+});
+
+export const dossierStepSchema = z.object({
+  phase: nonEmptyString,
+  timestamp: nonEmptyString,
+  outcome: nonEmptyString,
+  detail: z.string().trim().default(""),
+});
+
+export const runDossierSchema = z.object({
+  run_id: nonEmptyString,
+  project_title: nonEmptyString,
+  fixture: z.string().trim().default(""),
+  created_at: nonEmptyString,
+  updated_at: nonEmptyString,
+  complexity_verdict: complexityVerdictSchema,
+  process_mode: processModeSchema,
+  compiler_type: compilerTypeSchema,
+  seed_confidence: z.enum(["high", "medium", "low"]),
+  steps: z.array(dossierStepSchema),
+  reconcile_recommendation: z.enum(["accept", "accept-with-warnings", "review-required"]).optional(),
+  reconcile_findings_count: z.number().default(0),
+  reconcile_cleared_count: z.number().default(0),
+  promotion_result: z.enum(["canonical", "candidate", "pending"]).default("pending"),
+  operator_reviews: z.array(operatorReviewSchema).default([]),
+  refs: z.object({
+    seed: z.string().default(""),
+    brief: z.string().default(""),
+    handoff: z.string().default(""),
+    execution_return: z.string().default(""),
+    reconcile_report: z.string().default(""),
+  }).default({}),
+});
+
+export type OperatorReview = z.infer<typeof operatorReviewSchema>;
+export type DossierStep = z.infer<typeof dossierStepSchema>;
+export type RunDossier = z.infer<typeof runDossierSchema>;
+export type ArtifactStatus = z.infer<typeof artifactStatusSchema>;
+export type CandidateArtifact = z.infer<typeof candidateArtifactSchema>;
+
+// ---------------------------------------------------------------------------
+// Canonical object model — spec / status / conditions
+// ---------------------------------------------------------------------------
+
+// Conditions: queryable lifecycle summaries
+export const conditionTypeSchema = z.enum([
+  "ProjectActivated",
+  "NeedsClarification",
+  "BriefCompiling",
+  "BriefAccepted",
+  "BriefHeld",
+  "Executing",
+  "ReturnReceived",
+  "ProjectUpdated",
+  "HeldForReview",
+  "FeedbackPending",
+  "Closed",
+]);
+
+export const conditionStatusSchema = z.enum(["True", "False", "Unknown"]);
+
+export const conditionSchema = z.object({
+  type: conditionTypeSchema,
+  status: conditionStatusSchema,
+  reason: z.string().default(""),
+  last_transition: z.string().default(""),
+});
+
+// Spec: desired intent — only changed by product logic or user action
+export const projectSpecSchema = z.object({
+  problem: z.string().default(""),
+  target_user: z.string().default(""),
+  v1_outcome: z.string().default(""),
+  non_goals: z.array(z.string()).default([]),
+  constraints: z.string().default(""),
+  assumptions: z.array(z.string()).default([]),
+  acceptance_criteria: z.array(z.string()).default([]),
+  process_mode: processModeSchema.optional(),
+  compiler_intent: compilerTypeSchema.optional(),
+  task_type: taskTypeSchema.default("unknown"),
+  first_build_slice: z.string().default(""),
+  approved_scope_changes: z.array(z.string()).default([]),
+});
+
+// Status: observed state — written by controlled pathways only
+export const projectStatusSchema = z.object({
+  phase: z.string().default("no-project"),
+  observed_generation: z.number().default(0),
+  activation: z.object({
+    seed_confidence: z.enum(["high", "medium", "low"]).optional(),
+    complexity: complexityVerdictSchema.optional(),
+    research_needed: z.boolean().optional(),
+  }).default({}),
+  brief: z.object({
+    source: compilerTypeSchema.optional(),
+    accepted: z.boolean().default(false),
+    reconcile_summary: z.string().default(""),
+  }).default({}),
+  execution: z.object({
+    surface: surfaceSchema.optional(),
+    started_at: z.string().optional(),
+    return_status: z.string().optional(),
+    reconcile_summary: z.string().default(""),
+  }).default({}),
+  latest_artifact_ref: z.string().default(""),
+  latest_return_ref: z.string().default(""),
+});
+
+// Metadata
+export const projectMetadataSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  created_at: z.string(),
+  generation: z.number().default(1),
+});
+
+// The full canonical resource
+export const projectResourceSchema = z.object({
+  metadata: projectMetadataSchema,
+  spec: projectSpecSchema,
+  status: projectStatusSchema,
+  conditions: z.array(conditionSchema).default([]),
+});
+
+// ---------------------------------------------------------------------------
+// Project Truth Ledger types
+// ---------------------------------------------------------------------------
+
+export const evidenceTypeSchema = z.enum([
+  "user-backed",
+  "research-backed",
+  "execution-required",
+  "weak-inference",
+]);
+
+export const ledgerEntryKindSchema = z.enum([
+  "goal",
+  "constraint",
+  "assumption",
+  "decision",
+  "acceptance-criterion",
+  "scope-change",
+]);
+
+export const riskLevelSchema = z.enum(["low", "medium", "high"]);
+
+export const ledgerEntrySchema = z.object({
+  id: z.string(),
+  kind: ledgerEntryKindSchema,
+  text: z.string(),
+  evidence_type: evidenceTypeSchema.default("weak-inference"),
+  evidence_refs: z.array(z.string()).default([]),
+  parent_ids: z.array(z.string()).default([]),
+  risk_level: riskLevelSchema.optional(),
+  downstream_artifacts: z.array(z.string()).default([]),
+  created_at: z.string().default(""),
+  superseded_by: z.string().optional(),
+});
+
+export const scopeChangeSchema = z.object({
+  id: z.string(),
+  description: z.string(),
+  entries_added: z.array(z.string()).default([]),
+  entries_removed: z.array(z.string()).default([]),
+  entries_modified: z.array(z.string()).default([]),
+  approved_at: z.string(),
+  reason: z.string().default(""),
+});
+
+export const projectLedgerSchema = z.object({
+  entries: z.array(ledgerEntrySchema),
+  scope_changes: z.array(scopeChangeSchema).default([]),
+  version: z.number().default(1),
+});
+
+// Drift diff types
+export const diffActionSchema = z.enum(["added", "removed", "modified"]);
+
+export const diffEntrySchema = z.object({
+  action: diffActionSchema,
+  kind: ledgerEntryKindSchema,
+  entry_id: z.string(),
+  old_text: z.string().optional(),
+  new_text: z.string().optional(),
+  summary: z.string(),
+});
+
+export const driftDiffSchema = z.object({
+  entries: z.array(diffEntrySchema),
+  has_drift: z.boolean(),
+  summary: z.string(),
+});
+
+export type EvidenceType = z.infer<typeof evidenceTypeSchema>;
+export type LedgerEntryKind = z.infer<typeof ledgerEntryKindSchema>;
+export type RiskLevel = z.infer<typeof riskLevelSchema>;
+export type LedgerEntry = z.infer<typeof ledgerEntrySchema>;
+export type ScopeChange = z.infer<typeof scopeChangeSchema>;
+export type ProjectLedger = z.infer<typeof projectLedgerSchema>;
+export type DiffAction = z.infer<typeof diffActionSchema>;
+export type DiffEntry = z.infer<typeof diffEntrySchema>;
+export type DriftDiff = z.infer<typeof driftDiffSchema>;
+
+// ---------------------------------------------------------------------------
+// Activation V2 types
+// ---------------------------------------------------------------------------
+
+export const assumptionStatusSchema = z.enum(["unconfirmed", "confirmed", "rejected", "superseded"]);
+
+export const assumptionSchema = z.object({
+  id: z.string(),
+  text: z.string(),
+  status: assumptionStatusSchema.default("unconfirmed"),
+  evidence_type: evidenceTypeSchema.default("weak-inference"),
+  risk_level: riskLevelSchema.default("medium"),
+  source: z.string().default(""),
+});
+
+export const workflowCanvasSchema = z.object({
+  primary_user: z.string().default(""),
+  current_workflow: z.string().default(""),
+  target_workflow: z.string().default(""),
+  job_to_be_done: z.string().default(""),
+  edge_cases: z.array(z.string()).default([]),
+});
+
+export const nonFunctionalGateSchema = z.object({
+  category: z.enum(["security", "privacy", "observability", "performance", "compliance"]),
+  flagged: z.boolean(),
+  reason: z.string().default(""),
+  severity: riskLevelSchema.default("low"),
+});
+
+export const dangerousGateSchema = z.object({
+  gate: z.string(),
+  triggered: z.boolean(),
+  reason: z.string().default(""),
+});
+
+export const modeScoringSchema = z.object({
+  surface_area: z.number().min(0).max(3),
+  integration_count: z.number().min(0).max(3),
+  user_clarity: z.number().min(0).max(3),
+  outcome_concreteness: z.number().min(0).max(3),
+  coordination_complexity: z.number().min(0).max(3),
+  contradiction_level: z.number().min(0).max(3),
+  appetite_mismatch: z.number().min(0).max(3),
+  total: z.number(),
+});
+
+export const activationResultSchema = z.object({
+  assumptions: z.array(assumptionSchema),
+  workflow_canvas: workflowCanvasSchema,
+  non_functional_gates: z.array(nonFunctionalGateSchema),
+  dangerous_gates: z.array(dangerousGateSchema),
+  mode_scoring: modeScoringSchema,
+  selected_mode: processModeSchema,
+  mode_is_escalatable: z.boolean().default(true),
+  escalation_triggers: z.array(z.string()).default([]),
+});
+
+export type AssumptionStatus = z.infer<typeof assumptionStatusSchema>;
+export type Assumption = z.infer<typeof assumptionSchema>;
+export type WorkflowCanvas = z.infer<typeof workflowCanvasSchema>;
+export type NonFunctionalGate = z.infer<typeof nonFunctionalGateSchema>;
+export type DangerousGate = z.infer<typeof dangerousGateSchema>;
+export type ModeScoring = z.infer<typeof modeScoringSchema>;
+export type ActivationResult = z.infer<typeof activationResultSchema>;
+
+// ---------------------------------------------------------------------------
+// Handoff Contract V2 + Run History types
+// ---------------------------------------------------------------------------
+
+export const dispatchStateSchema = z.enum([
+  "queued", "preflight", "started", "completed", "failed", "timed-out", "late-return", "cancelled",
+]);
+
+export const runTokenSchema = z.object({
+  token: z.string(),
+  spec_generation: z.number(),
+  created_at: z.string(),
+  contract_version: z.literal("v2"),
+});
+
+export const handoffContractV2Schema = z.object({
+  contract_version: z.literal("v2"),
+  run_token: runTokenSchema,
+  spec_generation: z.number(),
+  canonical_snapshot_ref: z.string().default(""),
+  intent: z.object({
+    objective: z.string(),
+    scope_in: z.array(z.string()),
+    scope_out: z.array(z.string()),
+    non_goals: z.array(z.string()),
+  }),
+  constraints: z.object({
+    done_when: z.array(z.string()),
+    success_criteria: z.array(z.string()),
+    verify_with: z.array(z.string()),
+    blocker_escalation: z.array(z.string()),
+    return_when: z.string(),
+  }),
+  context: z.object({
+    surface: surfaceSchema,
+    fallback_surface: surfaceSchema,
+    execution_shape: z.string(),
+    process_mode: processModeSchema,
+  }),
+  return_expectations: z.object({
+    required_fields: z.array(z.string()),
+    must_reference_token: z.boolean().default(true),
+    must_match_generation: z.boolean().default(true),
+  }),
+  dispatch_state: dispatchStateSchema.default("queued"),
+  created_at: z.string(),
+});
+
+export const runEventKindSchema = z.enum([
+  "activation", "contract-locked", "brief-dispatched", "brief-received", "brief-accepted", "brief-held",
+  "execution-dispatched", "execution-started", "execution-returned", "execution-absorbed",
+  "canonical-updated",
+  "gate-held", "gate-blocked", "gate-accepted", "gate-accepted-with-cautions",
+  "next-slice-created",
+  "review-hold", "review-released",
+  "closure-recorded", "feedback-submitted",
+  "loop-transition",
+  "closed", "error", "late-return",
+]);
+
+export const eventContextSchema = z.object({
+  contract_ref: z.string().default(""),
+  handoff_id: z.string().default(""),
+  dispatch_id: z.string().default(""),
+  return_id: z.string().default(""),
+  delta_id: z.string().default(""),
+  next_slice_id: z.string().default(""),
+  closure_id: z.string().default(""),
+  surface: z.string().default(""),
+  gate_label: z.string().default(""),
+  delta_summary: z.string().default(""),
+  evidence_summary: z.string().default(""),
+  next_action: z.string().default(""),
+}).default({});
+
+export const runEventSchema = z.object({
+  id: z.string(),
+  kind: runEventKindSchema,
+  timestamp: z.string(),
+  run_token: z.string().optional(),
+  spec_generation: z.number().optional(),
+  detail: z.string().default(""),
+  context: eventContextSchema,
+  metadata: z.record(z.string(), z.unknown()).default({}),
+});
+
+export const runHistorySchema = z.object({
+  events: z.array(runEventSchema),
+  project_id: z.string(),
+});
+
+export const handoffPreflightResultSchema = z.object({
+  ready: z.boolean(),
+  blockers: z.array(z.string()),
+  warnings: z.array(z.string()),
+});
+
+export type DispatchState = z.infer<typeof dispatchStateSchema>;
+export type RunToken = z.infer<typeof runTokenSchema>;
+export type HandoffContractV2 = z.infer<typeof handoffContractV2Schema>;
+export type RunEventKind = z.infer<typeof runEventKindSchema>;
+export type EventContext = z.infer<typeof eventContextSchema>;
+export type RunEvent = z.infer<typeof runEventSchema>;
+export type RunHistory = z.infer<typeof runHistorySchema>;
+export type HandoffPreflightResult = z.infer<typeof handoffPreflightResultSchema>;
+
+// ---------------------------------------------------------------------------
+// Routing V2 types
+// ---------------------------------------------------------------------------
+
+export const verificationPathSchema = z.enum([
+  "none",
+  "documentation-required",
+  "dependency-verification",
+  "reduced-tool-surface",
+]);
+
+export const routingCandidateSchema = z.object({
+  provider_id: providerIdSchema,
+  score: z.number(),
+  disqualified: z.boolean().default(false),
+  disqualification_reason: z.string().default(""),
+  verification_path: verificationPathSchema.default("none"),
+});
+
+export const routingDecisionSchema = z.object({
+  selected: routingCandidateSchema,
+  fallback: routingCandidateSchema.optional(),
+  candidates: z.array(routingCandidateSchema),
+  rationale: z.string(),
+  constraints_applied: z.array(z.string()),
+  verification_path: verificationPathSchema,
+});
+
+export const routingConstraintsSchema = z.object({
+  task_type: taskTypeSchema,
+  process_mode: processModeSchema,
+  seed_confidence: z.enum(["high", "medium", "low"]),
+  repo_exists: z.boolean(),
+  capability_needed: providerCapabilitySchema,
+  non_functional_flags: z.array(z.string()).default([]),
+  blast_radius: riskLevelSchema.default("low"),
+  provider_readiness: z.record(providerIdSchema, z.boolean()).default({}),
+});
+
+export type VerificationPath = z.infer<typeof verificationPathSchema>;
+export type RoutingCandidate = z.infer<typeof routingCandidateSchema>;
+export type RoutingDecision = z.infer<typeof routingDecisionSchema>;
+export type RoutingConstraints = z.infer<typeof routingConstraintsSchema>;
+
+// ---------------------------------------------------------------------------
+// Reconcile V2 types
+// ---------------------------------------------------------------------------
+
+export const provenanceRecordSchema = z.object({
+  spec_generation: z.number(),
+  run_token: z.string().default(""),
+  agent_id: z.string().default(""),
+  outputs: z.array(z.string()).default([]),
+  activity: z.array(z.string()).default([]),
+});
+
+export const reconcileCheckResultSchema = z.object({
+  check: z.string(),
+  passed: z.boolean(),
+  severity: z.enum(["info", "warning", "blocker"]),
+  detail: z.string().default(""),
+});
+
+export const traceabilityCoverageSchema = z.object({
+  entry_id: z.string(),
+  entry_text: z.string(),
+  linked_artifacts: z.array(z.string()),
+  covered: z.boolean(),
+});
+
+export const reconcileV2ResultSchema = z.object({
+  checks: z.array(reconcileCheckResultSchema),
+  traceability: z.array(traceabilityCoverageSchema).default([]),
+  passed: z.boolean(),
+  blockers: z.number().default(0),
+  warnings: z.number().default(0),
+  recommendation: z.enum(["accept", "accept-with-warnings", "review-required"]),
+  summary: z.string(),
+});
+
+export type ProvenanceRecord = z.infer<typeof provenanceRecordSchema>;
+export type ReconcileCheckResult = z.infer<typeof reconcileCheckResultSchema>;
+export type TraceabilityCoverage = z.infer<typeof traceabilityCoverageSchema>;
+export type ReconcileV2Result = z.infer<typeof reconcileV2ResultSchema>;
+
+// ---------------------------------------------------------------------------
+// Approval gates + review packet types
+// ---------------------------------------------------------------------------
+
+export const gateReasonSchema = z.enum([
+  "major-scope-change",
+  "destructive-rewrite",
+  "policy-exception",
+  "unparented-high-impact-decision",
+  "weak-evidence-high-risk",
+  "requirement-removal",
+  "trust-boundary-change",
+]);
+
+export const approvalGateSchema = z.object({
+  id: z.string(),
+  reason: gateReasonSchema,
+  detail: z.string(),
+  triggered_by: z.string().default(""),
+  evidence_missing: z.array(z.string()).default([]),
+  resolution_path: z.string().default(""),
+  created_at: z.string(),
+});
+
+export const holdStateSchema = z.object({
+  held: z.boolean(),
+  gates: z.array(approvalGateSchema),
+  held_since: z.string().optional(),
+  summary: z.string().default(""),
+  resolution_actions: z.array(z.string()).default([]),
+});
+
+export const reviewPacketSchema = z.object({
+  project_id: z.string(),
+  spec_generation: z.number(),
+  requirement_diff_summary: z.string(),
+  changed_constraints: z.array(z.string()),
+  decisions_with_evidence: z.array(z.object({
+    text: z.string(),
+    evidence_type: evidenceTypeSchema,
+    has_refs: z.boolean(),
+    risk_level: riskLevelSchema.optional(),
+  })),
+  execution_proof: z.object({
+    verification_count: z.number(),
+    evidence_count: z.number(),
+    criteria_met_count: z.number(),
+    summary: z.string(),
+  }),
+  warnings: z.array(z.string()),
+  missing_evidence: z.array(z.string()),
+  gates: z.array(approvalGateSchema),
+  recommendation: z.enum(["accept", "accept-with-warnings", "review-required"]),
+  human_summary: z.string(),
+});
+
+export type GateReason = z.infer<typeof gateReasonSchema>;
+export type ApprovalGate = z.infer<typeof approvalGateSchema>;
+export type HoldState = z.infer<typeof holdStateSchema>;
+export type ReviewPacket = z.infer<typeof reviewPacketSchema>;
+
+// ---------------------------------------------------------------------------
+// Gate state — evidence-backed trust labels
+// ---------------------------------------------------------------------------
+
+export const gateStateLabelSchema = z.enum([
+  "accepted",
+  "accepted-with-cautions",
+  "held-for-review",
+  "blocked-missing-evidence",
+  "pending",
+  "not-checked",
+]);
+
+export const gateStateSchema = z.object({
+  label: gateStateLabelSchema,
+  reason: z.string(),
+  evidence_summary: z.object({
+    verification_count: z.number(),
+    evidence_count: z.number(),
+    criteria_met_count: z.number(),
+    caution_count: z.number(),
+    blocker_count: z.number(),
+  }),
+  honest: z.boolean(), // true = label is consistent with evidence
+});
+
+export type GateStateLabel = z.infer<typeof gateStateLabelSchema>;
+export type GateState = z.infer<typeof gateStateSchema>;
+
+// ---------------------------------------------------------------------------
+// Post-execution canonical delta + next slice
+// ---------------------------------------------------------------------------
+
+export const fileChangeSchema = z.object({
+  path: z.string(),
+  system: z.string().default(""),
+});
+
+export const testCheckSchema = z.object({
+  name: z.string(),
+  passed: z.boolean(),
+});
+
+export const consequenceTypeSchema = z.enum([
+  "code-change",
+  "contract-clarification",
+  "absorbed-return",
+  "open-items-recorded",
+  "next-slice-created",
+  "closure-recorded",
+  "no-change",
+]);
+
+export const evidenceAccountingSchema = z.object({
+  scope_check_count: z.number(),
+  scope_check_pass_count: z.number(),
+  scope_check_caution_count: z.number(),
+  scope_check_blocker_count: z.number(),
+  verification_run_count: z.number(),
+  verification_runs: z.array(z.string()),
+  evidence_item_count: z.number(),
+  evidence_items: z.array(z.string()),
+  file_change_count: z.number(),
+  artifact_change_count: z.number(),
+  criteria_met_count: z.number(),
+  criteria_met: z.array(z.string()),
+  caution_count: z.number(),
+  unresolved_count: z.number(),
+  boundary_preserved_count: z.number(),
+  boundary_violated_count: z.number(),
+  consequence_type: consequenceTypeSchema,
+  consequence_label: z.string(),
+});
+
+export type ConsequenceType = z.infer<typeof consequenceTypeSchema>;
+export type EvidenceAccounting = z.infer<typeof evidenceAccountingSchema>;
+
+export const canonicalDeltaSchema = z.object({
+  // Identity & lineage
+  delta_id: z.string().default(""),
+  project_id: z.string().default(""),
+  parent_contract_id: z.string().default(""),
+  return_id: z.string().default(""),
+  gate_state: z.string().default(""),
+  objective_state: z.enum(["met", "partial", "unmet", "not_started"]).default("not_started"),
+  created_at: z.string().default(""),
+
+  // What changed
+  implemented: z.array(z.string()),
+  systems_touched: z.array(z.string()),
+  file_changes: z.array(fileChangeSchema).default([]),
+  artifact_changes: z.array(z.string()).default([]),
+
+  // Evidence
+  tests_or_checks: z.array(testCheckSchema).default([]),
+  verification_runs: z.array(z.string()).default([]),
+  evidence_items: z.array(z.string()).default([]),
+
+  // Boundaries
+  boundaries_preserved: z.array(z.string()),
+  boundaries_violated: z.array(z.string()),
+
+  // Open items
+  cautions: z.array(z.string()),
+  unresolved: z.array(z.string()),
+  decisions: z.array(z.object({
+    text: z.string(),
+    traced: z.boolean(),
+  })),
+
+  // What advanced
+  state_fields_advanced: z.array(z.string()).default([]),
+
+  // Display
+  summary: z.string(),
+
+  // Canonical evidence accounting — single source of truth for all counts
+  evidence_accounting: evidenceAccountingSchema.optional(),
+
+  // Legacy compat — kept so existing code doesn't break
+  verified: z.array(z.string()),
+
+  // Next slice seed
+  next_slice_seed: z.object({
+    title: z.string(),
+    rationale: z.string(),
+    systems_likely: z.array(z.string()),
+    ready: z.boolean(),
+  }).optional(),
+
+  // Residual resolution rows — maps prior-loop residuals to this loop's evidence
+  residual_resolutions: z.array(z.object({
+    prior_residual_text: z.string(),
+    source: z.enum(["caution", "unresolved", "blocker", "escalation"]),
+    loop2_evidence_used: z.string(),
+    disposition: z.enum(["resolved", "partially_resolved", "carried_forward", "superseded"]),
+    resolution_note: z.string().default(""),
+  })).default([]),
+});
+
+export type FileChange = z.infer<typeof fileChangeSchema>;
+export type TestCheck = z.infer<typeof testCheckSchema>;
+export type ResidualResolution = CanonicalDelta["residual_resolutions"][number];
+
+export const nextSliceStatusSchema = z.enum([
+  "draft", "ready", "held", "blocked", "dispatched", "superseded", "closed",
+]);
+
+export const nextSliceSchema = z.object({
+  // Identity & lineage
+  slice_id: z.string().default(""),
+  project_id: z.string().default(""),
+  parent_contract_id: z.string().default(""),
+  parent_delta_id: z.string().default(""),
+  created_from: z.string().default(""),
+  created_at: z.string().default(""),
+
+  // Core
+  title: z.string(),
+  objective: z.string().default(""),
+  why_next: z.string().default(""),
+  status: nextSliceStatusSchema.default("draft"),
+  dispatch_ready: z.boolean().default(false),
+
+  // Context
+  scope: z.array(z.string()),
+  systems_in_play: z.array(z.string()),
+  required_inputs: z.array(z.string()).default([]),
+  expected_evidence: z.array(z.string()).default([]),
+  open_dependencies: z.array(z.string()).default([]),
+  blocking_reason: z.string().default(""),
+
+  // Legacy compat fields (still consumed by UI)
+  rationale: z.string(),
+  systems_likely: z.array(z.string()),
+  ready_for_dispatch: z.boolean(),
+  review_reason: z.string().default(""),
+  unresolved_blocker: z.string().default(""),
+  assumption: z.string().default(""),
+});
+
+export type NextSliceStatus = z.infer<typeof nextSliceStatusSchema>;
+
+export type CanonicalDelta = z.infer<typeof canonicalDeltaSchema>;
+export type NextSlice = z.infer<typeof nextSliceSchema>;
+
+// ---------------------------------------------------------------------------
+// Handoff / route visibility — frontstage-safe dispatch + return linkage
+// ---------------------------------------------------------------------------
+
+export const dispatchSummarySchema = z.object({
+  goal: z.string(),
+  protected_boundaries: z.array(z.string()),
+  expected_outputs: z.array(z.string()),
+  acceptance_basis: z.array(z.string()),
+});
+
+export const handoffVisibilitySchema = z.object({
+  // Where and why
+  surface: surfaceSchema,
+  surface_label: z.string(),
+  routing_reason: z.string(),
+  // Identity
+  handoff_id: z.string(),
+  contract_title: z.string(),
+  // Context
+  repo_binding: z.string(),
+  systems_in_scope: z.array(z.string()),
+  dispatched_at: z.string(),
+  // What was sent
+  dispatch: dispatchSummarySchema,
+  // Return linkage (populated after return)
+  return_summary: z.string().default(""),
+  return_status: z.string().default(""),
+  return_linked: z.boolean().default(false),
+});
+
+export type DispatchSummary = z.infer<typeof dispatchSummarySchema>;
+export type HandoffVisibility = z.infer<typeof handoffVisibilitySchema>;
+
+export const lineageStatusSchema = z.enum([
+  "dispatched", "return-received", "absorbed", "held", "rejected",
+]);
+
+// ---------------------------------------------------------------------------
+// Lane / realization metadata — tracks HOW a governed action was realized
+// ---------------------------------------------------------------------------
+
+export const realizationTypeSchema = z.enum([
+  "external_dispatch",   // real API/CLI call to an external provider
+  "local_compute",       // deterministic heuristic / pure function
+  "manual_packet",       // immutable packet generated for operator transport
+  "manual_transport",    // operator transported a packet to a surface
+  "internal_heuristic",  // pattern-matching / rule-based assessment
+]);
+
+export const agentRoleSchema = z.enum([
+  "compiler",   // brief/spec compilation
+  "executor",   // primary bounded execution
+  "auditor",    // post-execution audit / code review
+  "evaluator",  // independent evaluation / challenger
+  "synthesizer", // internal seed/activation synthesis
+]);
+
+export const laneRecordSchema = z.object({
+  lane_id: z.string(),
+  agent_role: agentRoleSchema,
+  agent_surface: surfaceSchema,
+  realization_type: realizationTypeSchema,
+  model: z.string().default(""),
+  started_at: z.string().default(""),
+  completed_at: z.string().default(""),
+  duration_ms: z.number().default(0),
+  artifact_id: z.string().default(""),
+  status: z.enum(["pending", "running", "completed", "failed", "skipped"]).default("pending"),
+  error: z.string().optional(),
+  detail: z.string().default(""),
+});
+
+export type RealizationType = z.infer<typeof realizationTypeSchema>;
+export type AgentRole = z.infer<typeof agentRoleSchema>;
+export type LaneRecord = z.infer<typeof laneRecordSchema>;
+
+export const dispatchRecordSchema = z.object({
+  // Identity
+  dispatch_id: z.string(),
+  project_id: z.string(),
+  contract_id: z.string(),
+
+  // Route decision (stable, machine-readable)
+  provider_target: z.string(),
+  provider_label: z.string(),
+  dispatch_reason: z.string(),
+  route_surface: surfaceSchema.optional(),
+  route_fallback: surfaceSchema.optional(),
+  route_rationale: z.string().default(""),
+  slice_id: z.string().default(""),
+
+  // Packet (frontstage-safe)
+  packet_summary: z.string(),
+  bounded_by: z.array(z.string()),
+  systems_in_play: z.array(z.string()),
+  dispatched_at: z.string(),
+
+  // Return linkage
+  return_id: z.string().default(""),
+  return_received_at: z.string().default(""),
+  return_status: z.string().default(""),
+  return_summary: z.string().default(""),
+  lineage_status: lineageStatusSchema.default("dispatched"),
+
+  // Delta linkage
+  delta_id: z.string().default(""),
+  next_slice_id: z.string().default(""),
+  closure_id: z.string().default(""),
+
+  // Lane metadata — tracks primary + secondary lane realizations
+  realization_type: realizationTypeSchema.default("external_dispatch"),
+  lanes: z.array(laneRecordSchema).default([]),
+});
+
+export type LineageStatus = z.infer<typeof lineageStatusSchema>;
+export type DispatchRecord = z.infer<typeof dispatchRecordSchema>;
+
+// ---------------------------------------------------------------------------
+// Reconcile check matrix + review packet — frontstage-safe trust proof
+// ---------------------------------------------------------------------------
+
+export const checkResultSchema = z.enum(["pass", "caution", "missing", "blocked"]);
+
+export const checkMatrixRowSchema = z.object({
+  check: z.string(),
+  result: checkResultSchema,
+  evidence: z.string(),
+  why_it_matters: z.string(),
+  contributes_to_gate: z.boolean(),
+});
+
+export const checkMatrixSchema = z.object({
+  rows: z.array(checkMatrixRowSchema),
+  pass_count: z.number(),
+  caution_count: z.number(),
+  missing_count: z.number(),
+  blocked_count: z.number(),
+});
+
+export const reconcileReviewPacketSchema = z.object({
+  contract_summary: z.string(),
+  delta_summary: z.string(),
+  check_matrix: checkMatrixSchema,
+  cautions: z.array(z.string()),
+  missing_evidence: z.array(z.string()),
+  gate_label: z.string(),
+  gate_reason: z.string(),
+  next_resolution: z.string(),
+});
+
+export type CheckResult = z.infer<typeof checkResultSchema>;
+export type CheckMatrixRow = z.infer<typeof checkMatrixRowSchema>;
+export type CheckMatrix = z.infer<typeof checkMatrixSchema>;
+export type ReconcileReviewPacket = z.infer<typeof reconcileReviewPacketSchema>;
+
+export type ConditionType = z.infer<typeof conditionTypeSchema>;
+export type ConditionStatus = z.infer<typeof conditionStatusSchema>;
+export type Condition = z.infer<typeof conditionSchema>;
+export type ProjectSpec = z.infer<typeof projectSpecSchema>;
+export type ProjectStatus = z.infer<typeof projectStatusSchema>;
+export type ProjectMetadata = z.infer<typeof projectMetadataSchema>;
+export type ProjectResource = z.infer<typeof projectResourceSchema>;
+
+// ---------------------------------------------------------------------------
+// Governance Envelope — single hard finite state model
+// ---------------------------------------------------------------------------
+
+export const activationStateSchema = z.enum([
+  "blocked_by_missing_evidence",
+  "held_for_review",
+  "ready_to_lock",
+  "locked",
+]);
+
+export const gateOutcomeSchema = z.enum([
+  "not_evaluated",
+  "pending_reconcile",
+  "blocked_by_missing_evidence",
+  "held_for_review",
+  "accepted_with_cautions",
+  "accepted",
+]);
+
+export const closureRecordSchema = z.object({
+  // Identity & lineage
+  closure_id: z.string().default(""),
+  project_id: z.string().default(""),
+  return_id: z.string().default(""),
+  delta_id: z.string().default(""),
+  dispatch_id: z.string().default(""),
+
+  // --- SEALED FACTS (immutable after seal) ---
+  sealed_at: z.string(),
+  gate_outcome: gateOutcomeSchema,
+  cautions_at_close: z.array(z.string()),
+  unresolved_at_close: z.array(z.string()),
+  objective_state: z.enum(["met", "partial", "unmet"]),
+  next_slice_at_close: nextSliceSchema.nullable().default(null),
+  seal_integrity: z.enum(["verified", "snapshot_empty", "no_return"]).default("verified"),
+
+  // --- APPENDED METADATA (added after seal, does NOT revise sealed facts) ---
+  feedback_appended_at: z.string().default(""),
+  feedback_snapshot: z.record(z.string(), z.unknown()).default({}),
+
+  // Legacy compat
+  closed_at: z.string(),
+});
+
+export const governanceEnvelopeSchema = z.object({
+  // Activation
+  activation_state: activationStateSchema,
+  activation_blockers: z.array(z.string()),
+
+  // Gate (post-return)
+  gate_state: gateOutcomeSchema.nullable(),
+  gate_reason: z.string().default(""),
+
+  // Structured counts — never inferred from prose
+  blockers: z.array(z.string()),
+  cautions: z.array(z.string()),
+  unresolved_items: z.array(z.string()),
+  scope_check_count: z.number(),
+  scope_check_caution_count: z.number(),
+  return_caution_count: z.number(),
+  verification_run_count: z.number(),
+  evidence_item_count: z.number(),
+  objective_state: z.enum(["met", "partial", "unmet", "not_started"]),
+
+  // Control flags
+  state_advance_allowed: z.boolean(),
+  closure_allowed: z.boolean(),
+
+  // Closure
+  closure_state: closureRecordSchema.nullable(),
+});
+
+export type ActivationState = z.infer<typeof activationStateSchema>;
+export type GateOutcome = z.infer<typeof gateOutcomeSchema>;
+export type ClosureRecord = z.infer<typeof closureRecordSchema>;
+export type GovernanceEnvelope = z.infer<typeof governanceEnvelopeSchema>;
+
+// ---------------------------------------------------------------------------
+// Dispatch Packet Integrity
+// ---------------------------------------------------------------------------
+
+export const packetFindingTypeSchema = z.enum([
+  "missing_referenced_artifact",
+  "missing_required_contract_input",
+  "missing_repo_binding",
+  "missing_parent_context",
+  "unresolved_placeholder",
+  "empty_required_field",
+  "packet_contract_mismatch",
+]);
+
+export const packetFindingSeveritySchema = z.enum(["blocking", "caution"]);
+
+export const packetFindingSchema = z.object({
+  type: packetFindingTypeSchema,
+  severity: packetFindingSeveritySchema,
+  field: z.string(),
+  detail: z.string(),
+});
+
+export const packetIntegrityOutcomeSchema = z.enum(["ready", "ready_with_cautions", "blocked"]);
+
+export const packetIntegrityResultSchema = z.object({
+  outcome: packetIntegrityOutcomeSchema,
+  findings: z.array(packetFindingSchema),
+  blocking_findings_count: z.number(),
+  caution_findings_count: z.number(),
+  checked_at: z.string(),
+  checked_against_contract_version: z.string(),
+  validator_version: z.string(),
+});
+
+export type PacketFindingType = z.infer<typeof packetFindingTypeSchema>;
+export type PacketFindingSeverity = z.infer<typeof packetFindingSeveritySchema>;
+export type PacketFinding = z.infer<typeof packetFindingSchema>;
+export type PacketIntegrityOutcome = z.infer<typeof packetIntegrityOutcomeSchema>;
+export type PacketIntegrityResult = z.infer<typeof packetIntegrityResultSchema>;
+
+// ---------------------------------------------------------------------------
+// Pressure Signals + Evidence-Required Acceptance
+// ---------------------------------------------------------------------------
+
+export const pressureSignalTypeSchema = z.enum([
+  "repeated_failed_attempts",
+  "repeated_retry_loop",
+  "missing_context_encountered",
+  "objective_partial",
+  "claimed_implementation_without_artifact_change",
+  "missing_required_evidence",
+  "test_failure_or_absent_tests_when_expected",
+  "execution_error_or_tool_failure",
+  "suspicious_return_shape_for_task_type",
+]);
+
+export const pressureSignalSchema = z.object({
+  type: pressureSignalTypeSchema,
+  detail: z.string(),
+});
+
+export const evidenceSufficiencyOutcomeSchema = z.enum([
+  "sufficient",
+  "partial",
+  "insufficient",
+]);
+
+export const pressureAssessmentSchema = z.object({
+  signals: z.array(pressureSignalSchema),
+  pressure_detected: z.boolean(),
+  evidence_requirements: z.array(z.string()),
+  evidence_items_present: z.array(z.string()),
+  evidence_items_missing: z.array(z.string()),
+  evidence_sufficiency: evidenceSufficiencyOutcomeSchema,
+  acceptance_decision_reason: z.string(),
+  task_type_basis: z.string(),
+  checked_at: z.string(),
+});
+
+export type PressureSignalType = z.infer<typeof pressureSignalTypeSchema>;
+export type PressureSignal = z.infer<typeof pressureSignalSchema>;
+export type EvidenceSufficiencyOutcome = z.infer<typeof evidenceSufficiencyOutcomeSchema>;
+export type PressureAssessment = z.infer<typeof pressureAssessmentSchema>;
+
+// ---------------------------------------------------------------------------
+// Evidence Proof — semantically distinct layers of evidence
+// ---------------------------------------------------------------------------
+
+/**
+ * Separates structured proof rows, extracted return fields, policy
+ * satisfaction, and canonical advancement so no two surfaces can
+ * disagree about what evidence exists.
+ */
+export const evidenceProofSchema = z.object({
+  // Layer 1: Structured proof rows (from return arrays, countable)
+  structured_paths: z.number(),       // return.changed_files.length
+  structured_artifacts: z.number(),   // return.artifacts_created.filter(Boolean).length
+  structured_verification_lines: z.number(), // return.verification_run.length
+  structured_evidence_lines: z.number(),     // return.evidence.length
+  structured_criteria_met: z.number(),       // return.success_criteria_met.length
+
+  // Layer 2: Policy evaluation (from checkEvidenceSufficiency)
+  policy_task_type: z.string(),       // effective task type used for policy
+  policy_requirements: z.array(z.string()),   // what was required
+  policy_satisfied: z.array(z.string()),      // what was met
+  policy_missing: z.array(z.string()),        // what was not met
+  policy_outcome: z.string(),         // sufficient / partial / insufficient
+
+  // Layer 3: Canonical advancement (what actually changed in governed state)
+  state_fields_advanced: z.array(z.string()),
+  consequence_type: z.string(),       // code-change / contract-clarification / etc
+  consequence_label: z.string(),
+
+  // Layer 4: Provenance — captured vs reconstructed evidence
+  provenance_captured_count: z.number().default(0),       // proof artifacts with provenance=captured
+  provenance_reconstructed_count: z.number().default(0),  // proof artifacts with provenance=reconstructed
+  provenance_derived_count: z.number().default(0),        // proof artifacts with provenance=derived
+  has_execution_transcript: z.boolean().default(false),   // whether raw transcript was captured
+  proof_folder: z.string().optional(),                    // path to run proof folder
+});
+
+export type EvidenceProof = z.infer<typeof evidenceProofSchema>;
+
+// ---------------------------------------------------------------------------
+// Canonical Run Snapshot — single source of truth for all surfaces
+// ---------------------------------------------------------------------------
+
+export const runPhaseSchema = z.enum([
+  "no_project",
+  "activation_blocked",
+  "activation_held",
+  "ready_to_lock",
+  "locked",
+  "dispatched",
+  "return_received",
+  "absorbed",
+  "accepted",
+  "accepted_with_cautions",
+  "held_for_review",
+  "blocked",
+  "closed",
+]);
+
+export const homeBucketSchema = z.enum([
+  "needs_attention",
+  "recently_changed",
+  "held_or_blocked",
+  "ready_to_execute",
+  "feedback_pending",
+  "recently_closed",
+  "idle",
+]);
+
+export const runSnapshotSchema = z.object({
+  // Phase — exactly one
+  phase: runPhaseSchema,
+
+  // Gate — from tightened derivation (null before return)
+  gate_label: z.string().default(""),
+  gate_reason: z.string().default(""),
+  hold_source: z.enum(["none", "reconcile", "pressure", "audit"]).default("none"),
+
+  // Cautions + unresolved — single canonical source for ALL surfaces
+  cautions_on_record: z.array(z.string()),
+  unresolved_on_record: z.array(z.string()),
+
+  // Next slice readiness
+  next_slice_ready: z.boolean(),
+  next_slice_status: z.string().default(""),
+  next_slice_blocking_reason: z.string().default(""),
+
+  // Task type — from seed, immutable for the run
+  task_type_basis: z.string(),
+
+  // Home bucket — deterministic from phase + gate + unresolved
+  home_bucket: homeBucketSchema,
+
+  // Closure
+  is_closed: z.boolean(),
+  closure_allowed: z.boolean(),
+  state_advance_allowed: z.boolean(),
+
+  // Counts — from evidence accounting (legacy, kept for compat)
+  verification_run_count: z.number(),
+  evidence_item_count: z.number(),
+  caution_count: z.number(),
+  unresolved_count: z.number(),
+
+  // Evidence proof — semantically layered evidence model
+  evidence_proof: evidenceProofSchema.optional(),
+
+  // --- Strict status schema — 5 distinct fields, projected consistently ---
+  // merge_outcome: what the gate decided about canonical advancement
+  merge_outcome: z.enum(["not_evaluated", "accepted", "accepted_with_cautions", "held", "blocked"]).default("not_evaluated"),
+  // run_outcome: what the execution actually produced
+  run_outcome: z.enum(["not_started", "done", "partial", "blocked"]).default("not_started"),
+  // closure_posture: whether the run can/has been sealed
+  closure_posture: z.enum(["open", "closable", "closable_with_cautions", "sealed", "not_closable"]).default("open"),
+  // seal_integrity: did the seal capture what was on record
+  seal_integrity: z.enum(["not_sealed", "verified", "snapshot_empty", "no_return"]).default("not_sealed"),
+  // next_slice_posture: what the next bounded slice's readiness is
+  next_slice_posture: z.enum(["none", "draft", "ready", "blocked", "held"]).default("none"),
+  // systems_touched: from file paths, not text inference
+  systems_touched: z.array(z.string()).default([]),
+
+  // --- Independent evaluation state (populated after receipt evaluation) ---
+  evaluation_verdict: z.enum(["not_evaluated", "pass", "pass_with_flags", "fail", "inconclusive"]).default("not_evaluated"),
+  evaluation_finding_count: z.number().default(0),
+  evaluation_reentry_signal: z.enum(["none", "hold_recommended", "block_recommended", "caution_added"]).default("none"),
+
+  derived_at: z.string(),
+});
+
+export type RunPhase = z.infer<typeof runPhaseSchema>;
+export type HomeBucket = z.infer<typeof homeBucketSchema>;
+export type RunSnapshot = z.infer<typeof runSnapshotSchema>;
+
+// ---------------------------------------------------------------------------
+// Governed Build Map — operator-readable scaffold of what was built
+// ---------------------------------------------------------------------------
+
+export const buildAreaStatusSchema = z.enum([
+  "official",
+  "provisional",
+  "changed_this_run",
+  "carries_unresolved",
+  "carries_caution",
+  "linkage_unknown",
+]);
+
+export const canonicalLinkageSchema = z.object({
+  source: z.string(),
+  field: z.string(),
+  strength: z.enum(["strong", "weak", "none"]),
+});
+
+export const buildAreaSchema = z.object({
+  area_id: z.string(),
+  label: z.string(),
+  what_it_is: z.string(),
+  why_it_exists: z.string(),
+  repo_paths: z.array(z.string()),
+  artifacts: z.array(z.string()),
+  linked_canonical_sources: z.array(canonicalLinkageSchema),
+  introduced_by_run: z.string().default(""),
+  changed_by_run: z.string().default(""),
+  current_status: buildAreaStatusSchema,
+  cautions: z.array(z.string()).default([]),
+  unresolved: z.array(z.string()).default([]),
+});
+
+export const buildMapSchema = z.object({
+  project_id: z.string(),
+  areas: z.array(buildAreaSchema),
+  total_paths: z.number(),
+  total_areas: z.number(),
+  derived_at: z.string(),
+  run_id: z.string().default(""),
+});
+
+export type BuildAreaStatus = z.infer<typeof buildAreaStatusSchema>;
+export type CanonicalLinkage = z.infer<typeof canonicalLinkageSchema>;
+export type BuildArea = z.infer<typeof buildAreaSchema>;
+export type BuildMap = z.infer<typeof buildMapSchema>;
+
+// ---------------------------------------------------------------------------
+// Lock Readiness — task-aware activation requirements
+// ---------------------------------------------------------------------------
+
+export const lockFindingSeveritySchema = z.enum(["blocking", "caution"]);
+
+export const lockFindingCategorySchema = z.enum([
+  "missing_required_input",
+  "missing_task_boundary",
+  "missing_scope",
+  "missing_systems",
+  "missing_repo_binding",
+  "vague_intent",
+  "product_guardrail_only",
+  "unresolved_assumption",
+]);
+
+export const lockFindingSchema = z.object({
+  category: lockFindingCategorySchema,
+  severity: lockFindingSeveritySchema,
+  field: z.string(),
+  detail: z.string(),
+});
+
+export const lockReadinessOutcomeSchema = z.enum([
+  "lock_allowed",
+  "lock_allowed_with_cautions",
+  "lock_blocked",
+]);
+
+export const lockReadinessSchema = z.object({
+  outcome: lockReadinessOutcomeSchema,
+  findings: z.array(lockFindingSchema),
+  blocking_count: z.number(),
+  caution_count: z.number(),
+  task_type_basis: z.string(),
+  checked_at: z.string(),
+});
+
+export type LockFindingSeverity = z.infer<typeof lockFindingSeveritySchema>;
+export type LockFindingCategory = z.infer<typeof lockFindingCategorySchema>;
+export type LockFinding = z.infer<typeof lockFindingSchema>;
+export type LockReadinessOutcome = z.infer<typeof lockReadinessOutcomeSchema>;
+export type LockReadiness = z.infer<typeof lockReadinessSchema>;
+
+// ---------------------------------------------------------------------------
+// Dispatch Receipt — auditable dispatch lifecycle
+// ---------------------------------------------------------------------------
+
+export const dispatchPhaseSchema = z.enum([
+  "packet_prepared",
+  "packet_committed",
+  "provider_acknowledged",
+  "return_received",
+  "failed",
+]);
+
+export const dispatchReceiptSchema = z.object({
+  // Identity
+  receipt_id: z.string(),
+  dispatch_id: z.string(),
+  packet_version: z.number(),
+
+  // What was sent
+  destination_surface: z.string(),
+  destination_label: z.string(),
+  governing_contract_id: z.string(),
+  packet_hash: z.string(),
+  prompt_hash: z.string(),
+  included_artifact_ids: z.array(z.string()),
+
+  // Lifecycle
+  phase: dispatchPhaseSchema,
+  prepared_at: z.string(),
+  committed_at: z.string().default(""),
+  acknowledged_at: z.string().default(""),
+  return_received_at: z.string().default(""),
+  failed_at: z.string().default(""),
+
+  // Provider acknowledgment
+  provider_run_ref: z.string().default(""),
+  provider_ack_available: z.boolean().default(false),
+
+  // Model config snapshot
+  model_used: z.string().default(""),
+  execution_duration_ms: z.number().default(0),
+
+  // Return linkage
+  return_id: z.string().default(""),
+  delta_id: z.string().default(""),
+});
+
+export type DispatchPhase = z.infer<typeof dispatchPhaseSchema>;
+export type DispatchReceipt = z.infer<typeof dispatchReceiptSchema>;
+
+// ---------------------------------------------------------------------------
+// Codex Audit — post-execution lane for code-touching work
+// ---------------------------------------------------------------------------
+
+export const auditTriggerSchema = z.enum([
+  "auth_logic",
+  "payment_logic",
+  "database_migration",
+  "dangerous_mode",
+  "operator_requested",
+]);
+
+export const auditFindingSeveritySchema = z.enum(["pass", "caution", "blocker"]);
+
+export const auditFindingSchema = z.object({
+  check: z.string(),
+  severity: auditFindingSeveritySchema,
+  detail: z.string(),
+  files_affected: z.array(z.string()).default([]),
+});
+
+export const auditResultSchema = z.object({
+  audit_id: z.string(),
+  return_id: z.string(),
+  triggered_by: z.array(auditTriggerSchema),
+  audit_required: z.boolean(),
+  outcome: z.enum(["pass", "pass_with_cautions", "blocker", "skipped", "not_required"]),
+  findings: z.array(auditFindingSchema),
+  blocker_count: z.number(),
+  caution_count: z.number(),
+  systems_audited: z.array(z.string()),
+  checked_at: z.string(),
+});
+
+export type AuditTrigger = z.infer<typeof auditTriggerSchema>;
+export type AuditFindingSeverity = z.infer<typeof auditFindingSeveritySchema>;
+export type AuditFinding = z.infer<typeof auditFindingSchema>;
+export type AuditResult = z.infer<typeof auditResultSchema>;
+
+// ---------------------------------------------------------------------------
+// Proof Capture — execution-time evidence with explicit provenance
+// ---------------------------------------------------------------------------
+
+export const provenanceLabelSchema = z.enum([
+  "captured",       // observed/recorded during execution (raw transcripts, CLI output)
+  "reconstructed",  // inferred or summarized after execution
+  "derived",        // computed from other proof artifacts (hashes, diffs)
+]);
+
+export const proofArtifactKindSchema = z.enum([
+  "execution-transcript",   // raw SDK/agent output
+  "cli-output",             // captured command output
+  "http-transcript",        // raw HTTP request/response
+  "file-snapshot",          // file content at capture time
+  "dispatch-metadata",      // what was sent to the executor
+  "return-structured",      // the parsed structured return
+  "verification-output",    // test/check output
+  "execution-trace",        // structured step-by-step trace of execution
+  "failure-context",        // structured failure breakdown
+  "custom",                 // operator-defined proof
+  "overflow-context",       // externalized overflow content (progressive disclosure)
+]);
+
+export const proofArtifactSchema = z.object({
+  artifact_id: z.string(),
+  kind: proofArtifactKindSchema,
+  provenance: provenanceLabelSchema,
+  filename: z.string(),
+  captured_at: z.string(),
+  size_bytes: z.number().default(0),
+  content_hash: z.string().default(""),
+  description: z.string().default(""),
+});
+
+export const proofManifestSchema = z.object({
+  manifest_id: z.string(),
+  dispatch_id: z.string(),
+  run_folder: z.string(),
+  created_at: z.string(),
+  artifacts: z.array(proofArtifactSchema),
+  provenance_summary: z.object({
+    captured_count: z.number(),
+    reconstructed_count: z.number(),
+    derived_count: z.number(),
+    total_size_bytes: z.number(),
+  }),
+});
+
+export type ProvenanceLabel = z.infer<typeof provenanceLabelSchema>;
+export type ProofArtifactKind = z.infer<typeof proofArtifactKindSchema>;
+export type ProofArtifact = z.infer<typeof proofArtifactSchema>;
+export type ProofManifest = z.infer<typeof proofManifestSchema>;
+
+// ---------------------------------------------------------------------------
+// Live Event — canonical observable event for all live consumers
+// ---------------------------------------------------------------------------
+
+export const liveEventKindSchema = z.enum([
+  "status-changed",
+  "dispatched",
+  "return-received",
+  "gate-resolved",
+  "evaluation-completed",
+  "operator-action-required",
+  "closure-sealed",
+  "loop-advanced",
+  "error",
+]);
+
+export const budgetPostureSchema = z.enum([
+  "nominal",
+  "caution",
+  "over-budget",
+  "unknown",
+]);
+
+export const liveProvenanceLevelSchema = z.enum([
+  "captured",
+  "reconstructed",
+  "derived",
+  "synthetic",
+  "unknown",
+]);
+
+export const liveEventSchema = z.object({
+  // Identity
+  event_id: z.string(),
+  kind: liveEventKindSchema,
+  timestamp: z.string(),
+
+  // Project / run identity
+  project_id: z.string(),
+  dispatch_id: z.string().default(""),
+  slice_id: z.string().default(""),
+  loop_ordinal: z.number().default(-1),
+
+  // Surface identity
+  surface: surfaceSchema.optional(),
+  surface_label: z.string().default(""),
+  surface_fallback: surfaceSchema.optional(),
+  route_rationale: z.string().default(""),
+  role: z.enum(["agent", "operator"]).default("agent"),
+
+  // Status projection (from RunSnapshot)
+  phase: runPhaseSchema,
+  home_bucket: homeBucketSchema,
+  gate_label: z.string().default(""),
+  hold_source: z.enum(["none", "reconcile", "pressure", "audit"]).default("none"),
+
+  // Operator signal
+  operator_action_required: z.boolean().default(false),
+  operator_action: z.string().default(""),
+
+  // Budget posture
+  budget_posture: budgetPostureSchema.default("unknown"),
+
+  // Provenance level
+  provenance_level: liveProvenanceLevelSchema.default("unknown"),
+
+  // Outcome projection (from strict status schema)
+  merge_outcome: z.enum(["not_evaluated", "accepted", "accepted_with_cautions", "held", "blocked"]).default("not_evaluated"),
+  run_outcome: z.enum(["not_started", "done", "partial", "blocked"]).default("not_started"),
+  closure_posture: z.enum(["open", "closable", "closable_with_cautions", "sealed", "not_closable"]).default("open"),
+
+  // Lightweight counts
+  caution_count: z.number().default(0),
+  unresolved_count: z.number().default(0),
+
+  // Lane identity (which governed lane produced this event)
+  agent_role: agentRoleSchema.optional(),
+  realization_type: realizationTypeSchema.optional(),
+
+  // Human-readable detail
+  detail: z.string().default(""),
+});
+
+export type LiveEventKind = z.infer<typeof liveEventKindSchema>;
+export type BudgetPosture = z.infer<typeof budgetPostureSchema>;
+export type LiveProvenanceLevel = z.infer<typeof liveProvenanceLevelSchema>;
+export type LiveEvent = z.infer<typeof liveEventSchema>;
+
+// ---------------------------------------------------------------------------
+// Normalized Return Envelope — governed common shape for multi-tool returns
+// ---------------------------------------------------------------------------
+//
+// Every surface (ChatGPT, Claude Code, Cursor) produces returns in slightly
+// different shapes. The NormalizedReturnEnvelope maps any surface's raw
+// return into a single governed form that downstream receipt, audit, and
+// delta logic can trust without surface-specific branching.
+//
+// Content modes track HOW a value was obtained at the source:
+//   direct        — the surface produced this value explicitly
+//   wrapped       — the value was present but reformatted to fit the schema
+//   inferred      — the value was derived from other fields or context
+//   reconstructed — the value was rebuilt after the fact from logs/artifacts
+// ---------------------------------------------------------------------------
+
+export const contentModeSchema = z.enum(["direct", "wrapped", "inferred", "reconstructed"]);
+
+export const outcomeClassSchema = z.enum([
+  "completed",   // objective fully met, done_when satisfied
+  "partial",     // some progress, objective not fully met
+  "blocked",     // execution could not proceed
+  "errored",     // execution failed unexpectedly
+  "absorbed",    // return ingested but no meaningful change recorded
+]);
+
+export const sourceRoleSchema = z.enum(["agent", "operator", "system"]);
+
+export const normalizedEvidenceItemSchema = z.object({
+  text: z.string(),
+  content_mode: contentModeSchema,
+});
+
+export const normalizedCautionSchema = z.object({
+  text: z.string(),
+  source: z.enum(["return", "reconcile", "audit", "pressure"]),
+});
+
+export const normalizedResidualSchema = z.object({
+  text: z.string(),
+  kind: z.enum(["blocker", "escalation", "unresolved"]),
+});
+
+export const normalizedReturnEnvelopeSchema = z.object({
+  // Identity
+  envelope_id: z.string(),
+  envelope_version: z.literal(1),
+  created_at: z.string(),
+
+  // Source
+  source_surface: surfaceSchema,
+  source_role: sourceRoleSchema,
+
+  // Objective
+  objective_used: z.string(),
+  outcome_class: outcomeClassSchema,
+
+  // Changed files — pre-classified with system detection
+  changed_files: z.array(z.object({
+    path: z.string(),
+    system: z.string().default(""),
+  })).default([]),
+  touched_artifacts: z.array(z.string()).default([]),
+
+  // Actions / commands actually executed
+  commands_run: z.array(z.string()).default([]),
+
+  // Evidence — each item tagged with how it was obtained
+  evidence_items: z.array(normalizedEvidenceItemSchema).default([]),
+  verification_runs: z.array(normalizedEvidenceItemSchema).default([]),
+  criteria_met: z.array(normalizedEvidenceItemSchema).default([]),
+
+  // Decisions
+  decisions: z.array(z.object({
+    text: z.string(),
+    content_mode: contentModeSchema,
+  })).default([]),
+
+  // Cautions — typed by where they originate
+  cautions: z.array(normalizedCautionSchema).default([]),
+
+  // Residuals — open items that carry forward
+  residuals: z.array(normalizedResidualSchema).default([]),
+
+  // Next step
+  recommended_next_step: z.string().default(""),
+
+  // Provenance posture — overall confidence in the return's content
+  provenance_posture: z.enum(["captured", "reconstructed", "derived", "mixed", "unknown"]).default("unknown"),
+  confidence_posture: z.enum(["high", "medium", "low", "unknown"]).default("unknown"),
+
+  // Summary
+  summary: z.string(),
+
+  // Lineage — ties this envelope back to the dispatch/handoff that produced it
+  handoff_id: z.string().default(""),
+  dispatch_id: z.string().default(""),
+  return_id: z.string().default(""),
+});
+
+export type ContentMode = z.infer<typeof contentModeSchema>;
+export type OutcomeClass = z.infer<typeof outcomeClassSchema>;
+export type SourceRole = z.infer<typeof sourceRoleSchema>;
+export type NormalizedEvidenceItem = z.infer<typeof normalizedEvidenceItemSchema>;
+export type NormalizedCaution = z.infer<typeof normalizedCautionSchema>;
+export type NormalizedResidual = z.infer<typeof normalizedResidualSchema>;
+export type NormalizedReturnEnvelope = z.infer<typeof normalizedReturnEnvelopeSchema>;
+
+// ---------------------------------------------------------------------------
+// Audited Receipt — the official product-level receipt object
+// ---------------------------------------------------------------------------
+//
+// The audited receipt is the thing the system trusts.
+// NOT the raw executor output. NOT the normalized envelope alone.
+//
+// It synthesizes: normalized return + canonical delta + gate verdict +
+// evidence accounting + closure posture + next-slice basis into a single
+// governed object that downstream UI, closure, and dispatch logic can
+// consume as the official record of what happened.
+// ---------------------------------------------------------------------------
+
+export const claimDispositionSchema = z.enum([
+  "proven",           // verification + evidence directly backs this
+  "supported",        // evidence exists but no independent verification
+  "partial",          // some evidence exists but coverage is incomplete
+  "inferred",         // derived from context, not directly proven
+  "unsubstantiated",  // claimed but no backing evidence found
+]);
+
+export const trustPostureSchema = z.enum([
+  "verified",    // gate accepted, evidence sufficient, no unresolved
+  "cautioned",   // gate accepted with cautions
+  "held",        // gate held for review
+  "blocked",     // gate blocked — missing evidence or blocker
+  "unknown",     // insufficient data to determine
+]);
+
+export const claimAssessmentSchema = z.object({
+  claim: z.string(),
+  disposition: claimDispositionSchema,
+  basis: z.string(),
+});
+
+export const auditedReceiptSchema = z.object({
+  // Identity & lineage
+  receipt_id: z.string(),
+  receipt_version: z.literal(1),
+  created_at: z.string(),
+  project_id: z.string().default(""),
+  dispatch_id: z.string().default(""),
+  return_id: z.string().default(""),
+  envelope_id: z.string().default(""),
+  delta_id: z.string().default(""),
+
+  // --- WHAT WAS CLAIMED ---
+  objective_claimed: z.string(),
+  outcome_claimed: outcomeClassSchema,
+  summary_claimed: z.string(),
+
+  // --- WHAT WAS PROVEN (structured counts from evidence accounting) ---
+  verification_count: z.number(),
+  evidence_count: z.number(),
+  criteria_met_count: z.number(),
+  files_changed_count: z.number(),
+
+  // Claim-vs-proof rows — each significant claim assessed
+  claim_assessments: z.array(claimAssessmentSchema).default([]),
+
+  // --- GATE VERDICT ---
+  gate_label: gateStateLabelSchema,
+  gate_reason: z.string(),
+  gate_honest: z.boolean(),
+
+  // --- PROVENANCE ---
+  provenance_posture: z.enum(["captured", "reconstructed", "derived", "mixed", "unknown"]).default("unknown"),
+  confidence_posture: z.enum(["high", "medium", "low", "unknown"]).default("unknown"),
+
+  // --- CLOSURE ---
+  closure_allowed: z.boolean(),
+  closure_basis: z.string(),
+
+  // --- AUDIT FINDINGS (explicit, not just reflected in gate) ---
+  audit_required: z.boolean().default(false),
+  audit_finding_count: z.number().default(0),
+  audit_cautions: z.array(z.string()).default([]),
+  audit_blockers: z.array(z.string()).default([]),
+
+  // --- RESIDUALS (carry forward) ---
+  cautions_on_record: z.array(z.string()).default([]),
+  unresolved_on_record: z.array(z.string()).default([]),
+  residual_count: z.number(),
+
+  // --- CANONICAL ADVANCEMENT ---
+  state_advanced: z.boolean(),
+  advancement_basis: z.string(),
+  consequence_type: consequenceTypeSchema,
+  consequence_label: z.string(),
+
+  // --- NEXT SLICE (with basis — why this is the next bounded move) ---
+  next_slice_exists: z.boolean(),
+  next_slice_id: z.string().default(""),
+  next_slice_title: z.string().default(""),
+  next_slice_ready: z.boolean().default(false),
+  next_slice_why: z.string().default(""),
+  next_slice_blocking_reason: z.string().default(""),
+
+  // --- EXECUTION TRACE SUMMARY (lightweight optimization inputs) ---
+  trace_step_count: z.number().default(0),
+  trace_tool_use_count: z.number().default(0),
+  trace_failure_phase: z.string().default(""),       // empty = no failure; otherwise the phase where failure occurred
+  trace_error_category: z.string().default(""),      // empty = no error; otherwise a short classification
+  trace_duration_ms: z.number().default(0),
+  trace_available: z.boolean().default(false),       // true if a structured execution-trace artifact exists
+
+  // --- BUDGET BREAKDOWN (task / verification / correction) ---
+  budget_task_steps: z.number().default(0),
+  budget_task_tool_uses: z.number().default(0),
+  budget_verification_steps: z.number().default(0),
+  budget_verification_tool_uses: z.number().default(0),
+  budget_correction_steps: z.number().default(0),
+  budget_correction_tool_uses: z.number().default(0),
+  budget_overhead_ratio: z.number().default(0),      // (verification + correction) / total
+  budget_had_corrections: z.boolean().default(false), // true if any correction effort was recorded
+  budget_posture: budgetPostureSchema.default("unknown"),
+  budget_posture_basis: z.string().default(""),
+
+  // --- OVERFLOW / PROGRESSIVE DISCLOSURE ---
+  overflow_entry_count: z.number().default(0),
+  overflow_total_bytes: z.number().default(0),
+  overflow_sources: z.array(z.string()).default([]),
+  overflow_available: z.boolean().default(false),
+
+  // --- OVERALL TRUST POSTURE ---
+  trust_posture: trustPostureSchema,
+  trust_basis: z.string(),
+});
+
+export type ClaimDisposition = z.infer<typeof claimDispositionSchema>;
+export type TrustPosture = z.infer<typeof trustPostureSchema>;
+export type ClaimAssessment = z.infer<typeof claimAssessmentSchema>;
+export type AuditedReceipt = z.infer<typeof auditedReceiptSchema>;
+
+// ---------------------------------------------------------------------------
+// Independent Evaluation Lane — model-independent governance assessment
+// ---------------------------------------------------------------------------
+//
+// The evaluation lane is structurally distinct from the builder/executor lane.
+// It receives a receipt + proof context and produces an independent assessment
+// that re-enters the governed loop as a first-class governance signal.
+//
+// Key invariant: the evaluator never re-executes. It assesses what happened
+// against what was contracted, using the audited receipt and proof artifacts
+// as its sole inputs.
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Validation Scope — layered eval scope model
+// ---------------------------------------------------------------------------
+//
+// micro-check:  fast, local, low-cost — claim coverage + basic evidence check
+// slice-check:  contract compliance + proof chain for a single slice/dispatch
+// full-run:     end-to-end evaluation including cross-slice lineage and promotion
+//
+// The scope is declared on evaluation input, persisted on the result, and
+// used by the promotion gate to enforce that broader checks are required
+// before higher-trust promotion.
+// ---------------------------------------------------------------------------
+
+export const validationScopeSchema = z.enum([
+  "micro-check",   // fast local check — claim coverage only
+  "slice-check",   // single-slice — claim + contract + proof chain
+  "full-run",      // full end-to-end — all checks, required for promotion
+]);
+
+export const promotionGateSchema = z.object({
+  /** The scope of the evaluation that feeds this gate. */
+  scope_performed: validationScopeSchema,
+  /** Whether this scope is sufficient for the requested promotion. */
+  promotion_allowed: z.boolean(),
+  /** The minimum scope required for this promotion level. */
+  minimum_scope_required: validationScopeSchema,
+  /** Why promotion was allowed or denied. */
+  gate_basis: z.string(),
+});
+
+export type ValidationScope = z.infer<typeof validationScopeSchema>;
+export type PromotionGate = z.infer<typeof promotionGateSchema>;
+
+export const evaluationTriggerSchema = z.enum([
+  "auto_post_receipt",     // automatically triggered after receipt is built
+  "operator_requested",    // operator manually triggered evaluation
+  "threshold_breach",      // evidence/trust threshold triggered evaluation
+  "re_evaluation",         // re-evaluation of a previously evaluated receipt
+]);
+
+export const evaluationVerdictSchema = z.enum([
+  "pass",           // evidence supports claims, contract satisfied
+  "pass_with_flags", // pass but findings noted for operator review
+  "fail",           // evidence does not support claims or contract violated
+  "inconclusive",   // insufficient evidence to make a determination
+]);
+
+export const evaluationFindingSeveritySchema = z.enum([
+  "info",      // informational — no action needed
+  "flag",      // notable — operator should be aware
+  "concern",   // concerning — may warrant action
+  "violation", // contract or evidence violation
+]);
+
+export const evaluationFindingSchema = z.object({
+  finding_id: z.string(),
+  severity: evaluationFindingSeveritySchema,
+  category: z.enum([
+    "claim_vs_evidence",   // claim not backed by evidence
+    "scope_adherence",     // work outside contracted scope
+    "contract_compliance", // contract terms not met
+    "evidence_quality",    // evidence is weak or insufficient
+    "residual_risk",       // unresolved items carry forward risk
+    "provenance_gap",      // proof chain has gaps
+    "budget_concern",      // excessive correction/rework effort detected
+  ]),
+  detail: z.string(),
+  claim_ref: z.string().default(""),   // which claim this finding relates to, if any
+  evidence_ref: z.string().default(""), // which evidence item this relates to, if any
+});
+
+export const evaluationReentrySignalSchema = z.enum([
+  "none",                 // no governance action needed
+  "hold_recommended",     // evaluator recommends hold for operator review
+  "block_recommended",    // evaluator recommends block — evidence insufficient
+  "caution_added",        // evaluator added cautions to the record
+]);
+
+export const evaluationResultSchema = z.object({
+  // Identity & lineage
+  evaluation_id: z.string(),
+  evaluation_version: z.literal(1),
+  created_at: z.string(),
+  project_id: z.string().default(""),
+  dispatch_id: z.string().default(""),
+  receipt_id: z.string(),              // the receipt being evaluated
+
+  // Trigger
+  triggered_by: evaluationTriggerSchema,
+
+  // Verdict
+  verdict: evaluationVerdictSchema,
+  verdict_basis: z.string(),           // why this verdict was reached
+
+  // Findings
+  findings: z.array(evaluationFindingSchema).default([]),
+  finding_count: z.number(),
+  violation_count: z.number().default(0),
+  concern_count: z.number().default(0),
+  flag_count: z.number().default(0),
+
+  // Claim coverage assessment (independent of receipt's own claim assessments)
+  claims_evaluated: z.number(),
+  claims_supported: z.number(),        // evaluator agrees claim is backed
+  claims_disputed: z.number(),         // evaluator disagrees with claim disposition
+  claims_unverifiable: z.number(),     // evaluator cannot verify independently
+
+  // Evidence quality assessment
+  evidence_sufficient: z.boolean(),
+  provenance_intact: z.boolean(),      // proof chain is unbroken
+  proof_artifacts_checked: z.number().default(0),
+
+  // Re-entry signal — how this evaluation should affect the governed loop
+  reentry_signal: evaluationReentrySignalSchema,
+  reentry_basis: z.string().default(""),
+  cautions_added: z.array(z.string()).default([]),
+
+  // Evaluator metadata
+  evaluator_role: z.literal("independent"),  // always independent, never builder
+  evaluation_scope: z.string(),              // what was in scope for this evaluation
+
+  // Layered validation scope — first-class scope classification
+  validation_scope: validationScopeSchema.default("micro-check"),
+  promotion_gate: promotionGateSchema.optional(),
+});
+
+export type EvaluationTrigger = z.infer<typeof evaluationTriggerSchema>;
+export type EvaluationVerdict = z.infer<typeof evaluationVerdictSchema>;
+export type EvaluationFindingSeverity = z.infer<typeof evaluationFindingSeveritySchema>;
+export type EvaluationFinding = z.infer<typeof evaluationFindingSchema>;
+export type EvaluationReentrySignal = z.infer<typeof evaluationReentrySignalSchema>;
+export type EvaluationResult = z.infer<typeof evaluationResultSchema>;
+
+// ---------------------------------------------------------------------------
+// Claim/Receipt Spread — deterministic per-run drift measurement
+// ---------------------------------------------------------------------------
+//
+// Measures how far executor claims tend to drift from audited receipts.
+// Each axis is a normalized [0..1] signal (0 = no drift, 1 = maximum drift).
+// The scalar is a weighted composite clamped to [0..1].
+//
+// Design invariant: the spread is a *derived observation* — it never overrides
+// the receipt, gate, or closure decisions. It is computed deterministically
+// from the receipt's governed fields.
+// ---------------------------------------------------------------------------
+
+export const claimSpreadVectorSchema = z.object({
+  /** Claims not proven or supported / total claims. 0 = all proven. */
+  claim_mismatch_ratio: z.number().min(0).max(1),
+  /** Audit-added cautions + blockers normalized (0 = none, 1 = 5+). */
+  audit_burden: z.number().min(0).max(1),
+  /** Residuals relative to total claims (0 = none, 1 = residuals >= claims). */
+  residual_weight: z.number().min(0).max(1),
+  /** Provenance weakness: captured=0, mixed=0.25, derived=0.5, reconstructed=0.75, unknown=1. */
+  provenance_weakness: z.number().min(0).max(1),
+  /** Gate distance from accepted: accepted=0, accepted-with-cautions=0.25, held=0.5, blocked=0.75, pending/not-checked=1. */
+  gate_distance: z.number().min(0).max(1),
+  /** 1 if execution failed, 0 otherwise. */
+  trace_failure_signal: z.number().min(0).max(1),
+  /** Correction steps as proportion of total steps (0..1). */
+  budget_correction_weight: z.number().min(0).max(1),
+});
+
+export const claimSpreadSchema = z.object({
+  /** Identifies the receipt this spread was computed from. */
+  receipt_id: z.string(),
+  /** Identifies the dispatch. */
+  dispatch_id: z.string().default(""),
+  /** ISO timestamp of computation. */
+  computed_at: z.string(),
+  /** The individual axis values. */
+  vector: claimSpreadVectorSchema,
+  /** Weighted composite score (0..1). 0 = perfect alignment, 1 = maximum drift. */
+  spread_score: z.number().min(0).max(1),
+  /** Human-readable basis for the score. */
+  spread_basis: z.string(),
+});
+
+export type ClaimSpreadVector = z.infer<typeof claimSpreadVectorSchema>;
+export type ClaimSpread = z.infer<typeof claimSpreadSchema>;
+
+// ---------------------------------------------------------------------------
+// Budget Categories — explicit task / verification / correction separation
+// ---------------------------------------------------------------------------
+//
+// Every unit of work an agent performs falls into one of three categories:
+//
+//   task        — primary implementation work toward the objective
+//   verification — checking, testing, or validating what was produced
+//   correction  — fixing issues found during verification
+//
+// These are first-class so that routing, evaluation, and receipts can
+// distinguish *what kind* of effort was spent, not just how much.
+// ---------------------------------------------------------------------------
+
+export const budgetCategorySchema = z.enum([
+  "task",          // primary implementation effort
+  "verification",  // checking / testing / validating
+  "correction",    // fixing issues found during verification
+]);
+
+export const budgetLedgerEntrySchema = z.object({
+  category: budgetCategorySchema,
+  step_count: z.number().default(0),
+  tool_use_count: z.number().default(0),
+  duration_ms: z.number().default(0),
+});
+
+export const budgetLedgerSchema = z.object({
+  /** Per-category breakdown of effort. */
+  entries: z.array(budgetLedgerEntrySchema).default([]),
+  /** Total steps across all categories. */
+  total_steps: z.number().default(0),
+  /** Total tool uses across all categories. */
+  total_tool_uses: z.number().default(0),
+  /** Total duration across all categories. */
+  total_duration_ms: z.number().default(0),
+  /** Ratio of verification + correction to total (0..1). 0 = no overhead. */
+  overhead_ratio: z.number().default(0),
+  /** Whether the correction category was non-zero (indicates rework). */
+  had_corrections: z.boolean().default(false),
+  /** Derived posture from the ledger. */
+  posture: budgetPostureSchema.default("unknown"),
+  /** Why this posture was assigned. */
+  posture_basis: z.string().default(""),
+});
+
+export type BudgetCategory = z.infer<typeof budgetCategorySchema>;
+export type BudgetLedgerEntry = z.infer<typeof budgetLedgerEntrySchema>;
+export type BudgetLedger = z.infer<typeof budgetLedgerSchema>;
+
+// ---------------------------------------------------------------------------
+// Overflow Manifest — progressive disclosure of externalized context
+// ---------------------------------------------------------------------------
+//
+// When execution context (transcripts, traces, structured returns) exceeds
+// a size threshold, the overflow mechanism externalizes it into governed
+// artifacts and retains a lightweight reference on the live control surface.
+//
+// The manifest tracks what was externalized, where it lives, why it was
+// externalized, and what summary was retained inline. This preserves
+// lineage so later evaluation lanes know the full context existed.
+// ---------------------------------------------------------------------------
+
+export const overflowEntrySchema = z.object({
+  overflow_id: z.string(),
+  /** What was externalized (e.g. "transcript", "trace_steps", "structured_return"). */
+  source_label: z.string(),
+  /** Why it was externalized (e.g. "exceeded 50000 char threshold"). */
+  reason: z.string(),
+  /** Filename within the proof folder where the overflow was written. */
+  artifact_filename: z.string(),
+  /** Reference to the proof artifact ID (links into proof manifest). */
+  artifact_id: z.string(),
+  /** Original size in bytes before externalization. */
+  original_size_bytes: z.number(),
+  /** What was kept inline as a summary/preview. */
+  retained_summary: z.string(),
+  /** How many bytes were retained inline. */
+  retained_bytes: z.number().default(0),
+  /** When the overflow was created. */
+  externalized_at: z.string(),
+});
+
+export const overflowManifestSchema = z.object({
+  manifest_id: z.string(),
+  dispatch_id: z.string(),
+  entries: z.array(overflowEntrySchema).default([]),
+  total_externalized_bytes: z.number().default(0),
+  total_entries: z.number().default(0),
+  created_at: z.string(),
+});
+
+export const overflowSummarySchema = z.object({
+  overflow_entry_count: z.number().default(0),
+  overflow_total_bytes: z.number().default(0),
+  overflow_sources: z.array(z.string()).default([]),
+  overflow_available: z.boolean().default(false),
+});
+
+export type OverflowEntry = z.infer<typeof overflowEntrySchema>;
+export type OverflowManifest = z.infer<typeof overflowManifestSchema>;
+export type OverflowSummary = z.infer<typeof overflowSummarySchema>;
+
+// ---------------------------------------------------------------------------
+// Execution Harness — route-native compilation output
+// ---------------------------------------------------------------------------
+
+/**
+ * Dispatch mode derived from surface capabilities.
+ * - auto:   programmatic dispatch, synchronous return
+ * - manual: human-mediated dispatch (clipboard, paste)
+ * - async:  programmatic dispatch, async/callback return
+ */
+export const dispatchModeSchema = z.enum(["auto", "manual", "async"]);
+
+/**
+ * Return expectation shape — what the control plane expects back
+ * from the receiving surface after execution.
+ */
+export const returnExpectationSchema = z.object({
+  structured: z.boolean(),
+  required_fields: z.array(z.string()),
+  human_mediated: z.boolean(),
+  async_callback: z.boolean(),
+});
+
+/**
+ * Budget constraints compiled from surface + task context.
+ * Defines the verification and correction thresholds the harness carries.
+ */
+export const budgetConstraintSchema = z.object({
+  correction_caution_threshold: z.number().default(0.2),
+  correction_over_budget_threshold: z.number().default(0.5),
+  verification_expected: z.boolean(),
+  verification_notes: z.array(z.string()).default([]),
+});
+
+/**
+ * Context bindings that are route-native — only relevant to
+ * the specific surface/dispatch mechanism being used.
+ */
+export const contextBindingsSchema = z.object({
+  working_directory: z.string().nullable().default(null),
+  model_hint: z.string().default(""),
+  async_return: z.boolean().default(false),
+});
+
+/**
+ * Harness governance binding — the contract boundaries that survive
+ * across every dispatch. Extracted once from the canonical
+ * contract, carried immutably in the harness.
+ *
+ * Distinct from GovernanceEnvelope (activation/gate/closure state).
+ */
+export const harnessGovernanceSchema = z.object({
+  contract_id: z.string(),
+  contract_title: z.string(),
+  non_goals: z.array(z.string()),
+  must_not_widen: z.array(z.string()),
+  protected_scope_out: z.array(z.string()),
+});
+
+/**
+ * ExecutionHarness — the route-native compilation output.
+ *
+ * This is the single compiled object that contains everything
+ * the receiving surface needs. It is produced from model-neutral
+ * canonical state (contract + working + loop) and route-specific
+ * decisions (surface profile + playbook + dispatch mode).
+ *
+ * The harness is the compilation boundary between canonical
+ * governance and route-native execution.
+ */
+export const executionHarnessSchema = z.object({
+  harness_id: z.string(),
+  dispatch_id: z.string(),
+  compiled_at: z.string(),
+
+  // Route identity
+  surface: surfaceSchema,
+  surface_class: surfaceClassSchema,
+  dispatch_mode: dispatchModeSchema,
+  receipt_model: surfaceProfileSchema.shape.receipt_model,
+  packet_format: surfaceProfileSchema.shape.packet_format,
+  execution_shape: executionShapeSchema,
+
+  // Compiled execution scope (from loop contract)
+  objective: z.string(),
+  scope_in: z.array(z.string()),
+  scope_out: z.array(z.string()),
+  done_when: z.array(z.string()),
+  success_criteria: z.array(z.string()),
+  verify_with: z.array(z.string()),
+  return_when: z.string(),
+  blocker_escalation: z.array(z.string()),
+  fallback_surface: surfaceSchema,
+
+  // Route-native sections
+  playbook_notes: z.array(z.string()),
+  return_expectation: returnExpectationSchema,
+  budget_constraint: budgetConstraintSchema,
+  context_bindings: contextBindingsSchema,
+  governance_envelope: harnessGovernanceSchema,
+});
+
+export type DispatchMode = z.infer<typeof dispatchModeSchema>;
+export type ReturnExpectation = z.infer<typeof returnExpectationSchema>;
+export type BudgetConstraint = z.infer<typeof budgetConstraintSchema>;
+export type ContextBindings = z.infer<typeof contextBindingsSchema>;
+export type HarnessGovernance = z.infer<typeof harnessGovernanceSchema>;
+export type ExecutionHarness = z.infer<typeof executionHarnessSchema>;
+
+// ---------------------------------------------------------------------------
+// Meta Harness — internal compile subsystem for context packet improvement
+// ---------------------------------------------------------------------------
+
+export const harnessCompilationExperimentSchema = z.enum([
+  "repo_context_bootstrap",     // repo-grounded context packet compilation
+]);
+
+export const harnessCandidateStatusSchema = z.enum([
+  "derived",         // candidate was generated
+  "selected",        // candidate was selected for use
+  "rejected",        // candidate was rejected (rationale recorded)
+  "no_op",           // no candidate was appropriate
+]);
+
+export const harnessInputSnapshotSchema = z.object({
+  contract_id: z.string(),
+  dispatch_id: z.string(),
+  spec_hash: z.string().default(""),
+  repo_grounded: z.boolean(),
+  prior_delta_id: z.string().default(""),
+  prior_gate_label: z.string().default(""),
+  loop_objective: z.string().default(""),
+  systems_in_play: z.array(z.string()).default([]),
+  snapshot_hash: z.string().default(""),
+});
+
+export const harnessOutputArtifactRefSchema = z.object({
+  artifact_type: z.enum(["context_section", "repo_summary", "prior_evidence_digest", "scope_refinement"]),
+  content_hash: z.string().default(""),
+  size_bytes: z.number().default(0),
+  description: z.string().default(""),
+});
+
+export const harnessCandidateSchema = z.object({
+  candidate_id: z.string(),
+  experiment: harnessCompilationExperimentSchema,
+  status: harnessCandidateStatusSchema,
+  rationale: z.string(),
+  input_snapshot: harnessInputSnapshotSchema,
+  output_artifacts: z.array(harnessOutputArtifactRefSchema).default([]),
+  context_additions: z.array(z.string()).default([]),
+  created_at: z.string(),
+});
+
+export const harnessSelectionSchema = z.object({
+  selected_candidate_id: z.string().default(""),
+  selection_rationale: z.string(),
+  was_no_op: z.boolean(),
+  no_op_reason: z.string().default(""),
+});
+
+export const harnessCompilationSummarySchema = z.object({
+  compilation_id: z.string(),
+  project_id: z.string(),
+  dispatch_id: z.string(),
+  experiment: harnessCompilationExperimentSchema,
+  candidates: z.array(harnessCandidateSchema),
+  selection: harnessSelectionSchema,
+  compiled_at: z.string(),
+  /** Bounded context sections emitted for downstream dispatch. */
+  emitted_context_sections: z.array(z.string()).default([]),
+  /** Total chars added to the dispatch prompt by the meta harness. */
+  context_chars_added: z.number().default(0),
+});
+
+export type HarnessCompilationExperiment = z.infer<typeof harnessCompilationExperimentSchema>;
+export type HarnessCandidateStatus = z.infer<typeof harnessCandidateStatusSchema>;
+export type HarnessInputSnapshot = z.infer<typeof harnessInputSnapshotSchema>;
+export type HarnessOutputArtifactRef = z.infer<typeof harnessOutputArtifactRefSchema>;
+export type HarnessCandidate = z.infer<typeof harnessCandidateSchema>;
+export type HarnessSelection = z.infer<typeof harnessSelectionSchema>;
+export type HarnessCompilationSummary = z.infer<typeof harnessCompilationSummarySchema>;
+
+// ---------------------------------------------------------------------------
+// Receipt V2 — immutable issuance payload + append-only lifecycle status
+// ---------------------------------------------------------------------------
+
+// --- Lifecycle posture (resolved from status events) ---
+
+export const receiptLifecyclePostureSchema = z.enum([
+  "CURRENT",
+  "CURRENT_WITH_LIMITS",
+  "SUSPENDED",
+  "SUPERSEDED",
+  "REVOKED",
+  "EXPIRED",
+]);
+
+// --- Status event types ---
+
+export const receiptStatusEventTypeSchema = z.enum([
+  "LIMIT_APPLIED",
+  "LIMIT_LIFTED",
+  "SUSPENDED",
+  "REINSTATED",
+  "SUPERSEDED_BY",
+  "REVOKED",
+  "EXPIRY_SET",
+  "EXPIRED",
+]);
+
+// --- Human-facing receipt verdict (immutable, set at issuance) ---
+
+export const receiptVerdictSchema = z.enum([
+  "verified",
+  "partially_verified",
+  "inconclusive",
+  "not_verified",
+  "disputed",
+]);
+
+// --- Claim source + provenance (two-axis model) ---
+
+export const claimSourceSchema = z.enum([
+  "executor",
+  "operator",
+  "switchboard",
+  "third_party",
+]);
+
+export const claimProvenanceTypeSchema = z.enum([
+  "claimed",
+  "observed",
+  "derived",
+]);
+
+// Updated claim disposition (same as V1 for compatibility)
+// "proven" | "supported" | "partial" | "inferred" | "unsubstantiated"
+
+export const claimAssessmentV2Schema = z.object({
+  claim: z.string(),
+  source: claimSourceSchema,
+  provenance_type: claimProvenanceTypeSchema,
+  disposition: claimDispositionSchema,
+  basis: z.string(),
+});
+
+// --- Verification / evidence schema ---
+
+export const verificationResultSchema = z.object({
+  verification_id: z.string(),
+  scope: z.string(),
+  method: z.string(),
+  outcome: z.enum(["pass", "fail", "partial", "skipped", "error"]),
+  coverage: z.string().default(""),
+  determinism: z.enum(["deterministic", "probabilistic", "manual", "unknown"]).default("unknown"),
+  evidence_type: z.enum(["captured", "reconstructed", "derived", "none"]).default("none"),
+  detail: z.string().default(""),
+});
+
+export const evidenceItemV2Schema = z.object({
+  evidence_id: z.string(),
+  kind: z.enum(["test_output", "file_diff", "cli_output", "transcript", "metric", "attestation", "other"]),
+  provenance: provenanceLabelSchema,
+  description: z.string(),
+  reference: z.string().default(""),
+});
+
+export const findingV2Schema = z.object({
+  finding_id: z.string(),
+  severity: z.enum(["info", "caution", "concern", "blocker"]),
+  category: z.string(),
+  detail: z.string(),
+  resolution: z.string().default(""),
+});
+
+export const unresolvedGapSchema = z.object({
+  gap_id: z.string(),
+  description: z.string(),
+  impact: z.enum(["blocks_verification", "degrades_confidence", "informational"]),
+  category: z.string().default(""),
+});
+
+// --- Execution metadata ---
+
+export const executionMetadataSchema = z.object({
+  surface: z.string(),
+  model: z.string().default(""),
+  duration_ms: z.number().default(0),
+  realization_type: z.string().default(""),
+  environment: z.string().default(""),
+  human_intervention: z.enum(["none", "present", "unknown"]).default("unknown"),
+});
+
+// --- Proof summary ---
+
+export const proofSummarySchema = z.object({
+  captured_count: z.number().default(0),
+  reconstructed_count: z.number().default(0),
+  derived_count: z.number().default(0),
+  total_artifacts: z.number().default(0),
+  manifest_present: z.boolean().default(false),
+  manifest_id: z.string().default(""),
+});
+
+// --- Issuance assessment ---
+
+export const issuanceAssessmentSchema = z.object({
+  verdict: receiptVerdictSchema,
+  verdict_basis: z.string(),
+  scope_qualified: z.boolean().default(false),
+  scope_description: z.string().default(""),
+  degradation_reasons: z.array(z.string()).default([]),
+  /** Structured honesty violation list — set by builder when summary contains banned terms. */
+  honesty_violations: z.array(z.string()).default([]),
+});
+
+// --- Audit + evaluation links ---
+
+export const auditAndEvaluationLinksSchema = z.object({
+  latest_evaluation_id: z.string().default(""),
+  evaluation_verdict: z.string().default(""),
+  evaluation_scope: z.string().default(""),
+  evaluation_timestamp: z.string().default(""),
+  evaluation_basis: z.string().default(""),
+});
+
+// --- Redaction profile ---
+
+export const redactionProfileSchema = z.object({
+  mode: z.enum(["full", "share", "redacted"]).default("full"),
+  redacted_fields: z.array(z.string()).default([]),
+  share_safe: z.boolean().default(false),
+});
+
+// --- Receipt Status Event ---
+
+export const receiptStatusEventSchema = z.object({
+  event_id: z.string(),
+  receipt_id: z.string(),
+  event_type: receiptStatusEventTypeSchema,
+  reason: z.string(),
+  issued_by: z.string().default("system"),
+  issued_at: z.string(),
+  superseded_by_receipt_id: z.string().default(""),
+  expiry_at: z.string().default(""),
+  limit_description: z.string().default(""),
+  metadata: z.record(z.string(), z.unknown()).default({}),
+});
+
+// --- ReceiptIssuedV2 — the immutable issuance payload ---
+
+export const receiptIssuedV2Schema = z.object({
+  // Identity
+  receipt_id: z.string(),
+  receipt_version: z.literal(2),
+  issued_at: z.string(),
+  project_id: z.string().default(""),
+  dispatch_id: z.string().default(""),
+  return_id: z.string().default(""),
+  envelope_id: z.string().default(""),
+  delta_id: z.string().default(""),
+
+  // --- asked ---
+  objective_asked: z.string(),
+  scope_summary: z.string().default(""),
+
+  // --- execution ---
+  execution: executionMetadataSchema,
+
+  // --- claimed ---
+  outcome_claimed: outcomeClassSchema,
+  summary_claimed: z.string(),
+
+  // --- claim_assessments (two-axis) ---
+  claim_assessments: z.array(claimAssessmentV2Schema).default([]),
+
+  // --- verification ---
+  verification_results: z.array(verificationResultSchema).default([]),
+  evidence_items: z.array(evidenceItemV2Schema).default([]),
+  findings: z.array(findingV2Schema).default([]),
+  unresolved_gaps: z.array(unresolvedGapSchema).default([]),
+
+  // --- gate ---
+  gate_label: gateStateLabelSchema,
+  gate_reason: z.string(),
+  gate_honest: z.boolean(),
+
+  // --- issuance_assessment (human-facing verdict) ---
+  issuance_assessment: issuanceAssessmentSchema,
+
+  // --- advancement ---
+  state_advanced: z.boolean(),
+  advancement_basis: z.string(),
+  consequence_type: consequenceTypeSchema,
+  consequence_label: z.string(),
+
+  // --- residuals ---
+  cautions_on_record: z.array(z.string()).default([]),
+  unresolved_on_record: z.array(z.string()).default([]),
+  residual_count: z.number(),
+
+  // --- next_slice ---
+  next_slice_exists: z.boolean(),
+  next_slice_id: z.string().default(""),
+  next_slice_title: z.string().default(""),
+
+  // --- provenance_summary ---
+  proof_summary: proofSummarySchema,
+  provenance_posture: z.enum(["captured", "reconstructed", "derived", "mixed", "unknown"]).default("unknown"),
+
+  // --- audit_and_evaluation_links ---
+  audit_and_evaluation_links: auditAndEvaluationLinksSchema.default({}),
+
+  // --- redaction_profile ---
+  redaction_profile: redactionProfileSchema.default({}),
+
+  // --- closure ---
+  closure_allowed: z.boolean(),
+  closure_basis: z.string(),
+
+  // --- legacy compat (carries V1 fields for backward compat) ---
+  trust_posture: trustPostureSchema,
+  trust_basis: z.string(),
+
+  // --- V1 receipt ID for lineage if upgraded ---
+  v1_receipt_id: z.string().default(""),
+
+  // --- Meta harness compile provenance ---
+  harness_provenance: z.object({
+    harness_ran: z.boolean().default(false),
+    compilation_id: z.string().default(""),
+    selected_candidate_id: z.string().default(""),
+    experiment: z.string().default(""),
+    selection_rationale: z.string().default(""),
+    context_chars_added: z.number().default(0),
+    was_no_op: z.boolean().default(true),
+  }).default({}),
+});
+
+export type ReceiptLifecyclePosture = z.infer<typeof receiptLifecyclePostureSchema>;
+export type ReceiptStatusEventType = z.infer<typeof receiptStatusEventTypeSchema>;
+export type ReceiptVerdict = z.infer<typeof receiptVerdictSchema>;
+export type ClaimSource = z.infer<typeof claimSourceSchema>;
+export type ClaimProvenanceType = z.infer<typeof claimProvenanceTypeSchema>;
+export type ClaimAssessmentV2 = z.infer<typeof claimAssessmentV2Schema>;
+export type VerificationResult = z.infer<typeof verificationResultSchema>;
+export type EvidenceItemV2 = z.infer<typeof evidenceItemV2Schema>;
+export type FindingV2 = z.infer<typeof findingV2Schema>;
+export type UnresolvedGap = z.infer<typeof unresolvedGapSchema>;
+export type ExecutionMetadata = z.infer<typeof executionMetadataSchema>;
+export type ProofSummary = z.infer<typeof proofSummarySchema>;
+export type IssuanceAssessment = z.infer<typeof issuanceAssessmentSchema>;
+export type AuditAndEvaluationLinks = z.infer<typeof auditAndEvaluationLinksSchema>;
+export type RedactionProfile = z.infer<typeof redactionProfileSchema>;
+export type ReceiptStatusEvent = z.infer<typeof receiptStatusEventSchema>;
+export type ReceiptIssuedV2 = z.infer<typeof receiptIssuedV2Schema>;