codex-workflow-v2 2.0.0-beta.13.9 → 2.0.0-beta.14

package/src/contracts.ts

@@ -0,0 +1,1494 @@
+export const STATE_SCHEMA_VERSION = 2 as const;
+export const PROTOCOL_VERSION = 2 as const;
+
+export type DiscoveryStatus =
+  | 'needs_discovery'
+  | 'needs_clarification'
+  | 'ready_to_materialize'
+  | 'materialized'
+  | 'abandoned';
+
+export type TaskStatus =
+  | 'planning'
+  | 'awaiting_execution_authorization'
+  | 'ready'
+  | 'in_progress'
+  | 'validating'
+  | 'needs_fix'
+  | 'awaiting_final_acceptance'
+  | 'merging'
+  | 'ready_to_merge'
+  | 'merged'
+  | 'blocked'
+  | 'cancelled';
+
+export type MilestoneStatus =
+  | 'planning'
+  | 'awaiting_execution_authorization'
+  | 'active'
+  | 'validating'
+  | 'awaiting_final_acceptance'
+  | 'accepted'
+  | 'blocked'
+  | 'cancelled';
+
+export type StepStatus = 'planned' | 'in_progress' | 'completed' | 'failed' | 'blocked' | 'skipped';
+export type WorkspaceOwner = 'local' | 'external';
+export type ReviewStatus = 'pending' | 'passed' | 'failed' | 'unverified';
+export type AuthorizationKind = 'execution' | 'final_acceptance' | 'exception';
+export type AuthorizationMode = 'human' | 'delegated' | 'corrective-derived';
+export type DelegationStatus = 'active' | 'revoked';
+export type DelegationTransition =
+  | 'project_memory.approve'
+  | 'task.execution_authorize'
+  | 'task.final_accept'
+  | 'milestone.execution_authorize'
+  | 'milestone.final_accept';
+export type KnowledgeImpact = 'none' | 'update' | 'create' | 'retire';
+export type GraphUse = 'code-aware' | 'not-applicable';
+export type GraphKind = 'product' | 'workflow';
+export type GraphMode = 'moderate' | 'full';
+export type GraphBindingStatus = 'ready' | 'stale' | 'unavailable' | 'fallback';
+export type KnowledgeCategory =
+  | 'agent-guidance'
+  | 'onboarding'
+  | 'architecture'
+  | 'decisions'
+  | 'commands'
+  | 'ownership'
+  | 'testing'
+  | 'operations'
+  | 'domain';
+export type KnowledgeAuthority = 'canonical' | 'supporting';
+export type KnowledgeMapStatus = 'draft' | 'awaiting_approval' | 'active' | 'stale' | 'conflicted';
+export type WorkflowRole =
+  | 'scope-lead'
+  | 'technical-planner'
+  | 'delivery-coordinator'
+  | 'worker'
+  | 'independent-reviewer';
+
+export interface RevisionedRecord {
+  schemaVersion: typeof STATE_SCHEMA_VERSION;
+  revision: number;
+  id: string;
+  projectId: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface DiscoveryState extends RevisionedRecord {
+  kind: 'discovery';
+  status: DiscoveryStatus;
+  goal: string;
+  outcome: string | null;
+  facts: string[];
+  decisions: string[];
+  assumptions: string[];
+  unknowns: string[];
+  blockingUnknowns: string[];
+  scope: string[];
+  outOfScope: string[];
+  constraints: string[];
+  acceptance: string[];
+  materializedEntityId: string | null;
+}
+
+export interface PlanStepInput {
+  id: string;
+  title: string;
+  objective: string;
+  requirements: string[];
+  dependencies: string[];
+  expectedOutputs: string[];
+  allowedWrites: string[];
+  forbiddenScope: string[];
+  checks: string[];
+}
+
+/** A declared production hand-off; never inferred from component prose. */
+export interface ProductionEdgeInput {
+  ownerStepId: string;
+  consumerStepId: string;
+  checkRef: string;
+}
+
+export interface TaskPlanInput {
+  objective: string;
+  requirements: string[];
+  acceptance: string[];
+  risks: string[];
+  knowledgeImpact: KnowledgeImpact;
+  knowledgeImpactReason: string;
+  knowledgeTargets: KnowledgeTarget[];
+  knowledgeMapRevision: number;
+  knowledgeMapHash: string;
+  graphUse: GraphUse;
+  steps: PlanStepInput[];
+  /** Structural integration declaration, independently required by runtime-composition PRA authority. */
+  productionEdges?: ProductionEdgeInput[];
+  /** Explicit acknowledgement of the derived structural boundary; never the trigger by itself. */
+  requiresProductionEdges?: boolean;
+}
+
+export interface KnowledgeTarget {
+  category: KnowledgeCategory;
+  path: string;
+  reason: string;
+  requirementIds: string[];
+}
+
+export interface KnowledgeSource {
+  id: string;
+  category: KnowledgeCategory;
+  path: string;
+  scope: string;
+  authority: KnowledgeAuthority;
+  contentHash: string;
+  discoveredBy: string;
+  lastVerifiedAt: string;
+}
+
+export interface KnowledgeGap {
+  category: KnowledgeCategory;
+  scope: string;
+  reason: string;
+}
+
+export interface KnowledgeConflict {
+  category: KnowledgeCategory;
+  scope: string;
+  sourceIds: string[];
+  reason: string;
+}
+
+export interface KnowledgeMapApproval {
+  mapHash: string;
+  actor: string;
+  approvedAt: string;
+  authorizationMode?: AuthorizationMode;
+  delegation?: DelegatedAuthorizationEvidence;
+}
+
+export interface ProjectKnowledgeMap extends RevisionedRecord {
+  kind: 'knowledge-map';
+  status: KnowledgeMapStatus;
+  entries: KnowledgeSource[];
+  gaps: KnowledgeGap[];
+  conflicts: KnowledgeConflict[];
+  approval: KnowledgeMapApproval | null;
+}
+
+export interface GraphBindingSnapshot {
+  projectKey: string | null;
+  rootFingerprint: string;
+  indexedHead: string | null;
+  packageVersion: string | null;
+  manifestHash: string | null;
+  mode: GraphMode;
+  status: GraphBindingStatus;
+  nodeCount: number | null;
+  edgeCount: number | null;
+  observedAt: string;
+  evidenceHash: string;
+  fallbackReason: string | null;
+}
+
+export interface GraphBinding extends RevisionedRecord, GraphBindingSnapshot {
+  kind: 'graph-binding';
+  graphKind: GraphKind;
+  provider: 'codebase-memory-mcp';
+  previous: GraphBindingSnapshot | null;
+}
+
+export interface GraphRefreshRequest {
+  protocolVersion: typeof PROTOCOL_VERSION;
+  requestId: string;
+  projectId: string;
+  graphKind: GraphKind;
+  sourceRoot: string;
+  rootFingerprint: string;
+  indexedHead: string | null;
+  packageVersion: string | null;
+  manifestHash: string | null;
+  mode: GraphMode;
+  persistence: false;
+  issuedAt: string;
+}
+
+export interface GraphRefreshEvidence {
+  requestId: string;
+  provider: 'codebase-memory-mcp';
+  projectKey: string;
+  rootFingerprint: string;
+  indexedHead: string | null;
+  packageVersion: string | null;
+  manifestHash: string | null;
+  mode: GraphMode;
+  status: 'ready' | 'stale' | 'unavailable';
+  nodeCount: number | null;
+  edgeCount: number | null;
+  observedAt: string;
+}
+
+export interface KnowledgeSelection {
+  sourceId: string;
+  authority: KnowledgeAuthority;
+}
+
+export interface StepEvidence {
+  recordedAt: string;
+  commitSha: string;
+  changedFiles: string[];
+  checks: Array<{
+    command: string;
+    passed: boolean;
+    exitCode: number;
+    output: string;
+  }>;
+  notes: string[];
+}
+
+export interface StepFailurePause {
+  recordedAt: string;
+  dirtyFiles: string[];
+  dirtyWorktreeHash: string;
+  checksHash: string;
+  checksEvidence?: { kind: 'captured-checks/v1'; artifactHash: string };
+  failedChecks?: Array<{
+    command: string;
+    exitCode: number;
+    diagnosticCodes: string[];
+    diagnosticShape: string[];
+    diagnosticPaths: string[];
+    causeFingerprint: string;
+  }>;
+}
+
+export interface TaskStep extends PlanStepInput {
+  status: StepStatus;
+  evidence: StepEvidence | null;
+  failurePause?: StepFailurePause | null;
+}
+
+export type MechanicalFeasibilityResult = 'pass' | 'blocked' | 'unverified';
+
+export interface MechanicalFeasibilityAnalyzer {
+  analyzerId:
+    | 'wf2.root-npm-script'
+    | 'wf2.root-npm-script-arguments'
+    | 'wf2.check-support-anchor'
+    | 'wf2.exact-output-path'
+    | 'wf2.exact-predecessor-path';
+  analyzerVersion: 1;
+}
+
+export interface MechanicalFeasibilityFinding extends MechanicalFeasibilityAnalyzer {
+  result: MechanicalFeasibilityResult;
+  stepId: string;
+  subject: string;
+  evidence: string;
+  reasonCode: string;
+}
+
+export interface MechanicalFeasibilityEvidence {
+  schemaVersion: 1;
+  taskId: string;
+  evaluatedTaskRevision: number;
+  briefHash: string;
+  planHash: string;
+  sourceKind: 'pre-start-base' | 'corrective-task-workspace';
+  sourceBranch: string;
+  evaluatedHead: string;
+  baseCommit: string | null;
+  analyzerSetHash: string;
+  analyzerInputHash: string;
+  analyzers: MechanicalFeasibilityAnalyzer[];
+  findings: MechanicalFeasibilityFinding[];
+  decision: 'clear' | 'blocked';
+}
+
+export interface AuthorizationEvent {
+  kind: AuthorizationKind;
+  decision: 'approved' | 'rejected' | 'waived' | 'superseded';
+  actor: string;
+  recordedAt: string;
+  briefHash: string | null;
+  planHash: string | null;
+  resultHash: string | null;
+  evidenceHash: string | null;
+  headCommit: string | null;
+  reason: string;
+  authorizationMode?: AuthorizationMode;
+  delegation?: DelegatedAuthorizationEvidence;
+  /** Missing only on execution authorizations written before P01-A. */
+  mechanicalFeasibility?: MechanicalFeasibilityEvidence;
+}
+
+export interface DelegatedAuthorizationEvidence {
+  grantId: string;
+  policyHash: string;
+  principal: string;
+  delegate: string;
+  transition: DelegationTransition;
+}
+
+export type DelegationScope =
+  | { kind: 'project' }
+  | { kind: 'milestone'; id: string }
+  | { kind: 'task'; id: string };
+
+export interface DelegationPolicyInput {
+  principal: string;
+  delegate: string;
+  scope: DelegationScope;
+  transitions: DelegationTransition[];
+  expiresAt: string;
+}
+
+export interface DelegationGrant extends RevisionedRecord {
+  kind: 'delegation-grant';
+  status: DelegationStatus;
+  principal: string;
+  delegate: string;
+  scope: DelegationScope;
+  transitions: DelegationTransition[];
+  expiresAt: string;
+  policyHash: string;
+  revokedAt: string | null;
+  revokedBy: string | null;
+  revokeReason: string | null;
+}
+
+export interface DelegationGrantGate {
+  kind: 'delegation_grant_issuance';
+  projectId: string;
+  policy: DelegationPolicyInput;
+  policyHash: string;
+  confirmationCode: string;
+}
+
+export interface DelegatedApprovalOption {
+  grantId: string;
+  principal: string;
+  delegate: string;
+  transition: DelegationTransition;
+  scope: DelegationScope;
+  expiresAt: string;
+  policyHash: string;
+}
+
+export interface TaskKnowledgeRebindRecord {
+  recordedAt: string;
+  fromKnowledgeMapRevision: number;
+  fromKnowledgeMapHash: string;
+  toKnowledgeMapRevision: number;
+  toKnowledgeMapHash: string;
+  previousPlanHash: string;
+  reboundPlanHash: string;
+}
+
+export interface ReviewRecord {
+  status: ReviewStatus;
+  reviewer: string;
+  recordedAt: string | null;
+  headCommit: string | null;
+  briefHash: string | null;
+  planHash: string | null;
+  evidenceHash: string | null;
+  summary: string;
+  findings: Array<{
+    id: string;
+    severity: 'critical' | 'major' | 'minor';
+    requirement: string | null;
+    summary: string;
+    evidence: string;
+    requiredAction: string;
+    /** Stable identity for the underlying cause, not for this review attempt. */
+    causeId?: string;
+    route?: 'fix' | 'replan';
+    planConflict?: {
+      planClause: string;
+      whyFixCannotFit: string;
+      minimalPlanChange: string;
+    } | null;
+  }>;
+}
+
+export type ReviewInput = Pick<ReviewRecord, 'status' | 'reviewer' | 'summary' | 'findings'>;
+
+export interface CorrectivePlanAuditInput {
+  auditor: string;
+  summary: string;
+  decision: 'continue-fix' | 'replan-required' | 'split-required' | 'stop-escalate';
+  reviewedFindingIds: string[];
+}
+
+export type GuardedRiskCategory =
+  | 'migration'
+  | 'concurrency'
+  | 'restart-replay'
+  | 'crash-window'
+  | 'external-provider'
+  | 'runtime-composition'
+  | 'security-boundary'
+  | 'auth-secrets'
+  | 'irreversible-execution';
+
+export type PlanRiskAuditDecision =
+  | 'approved'
+  | 'approved-with-rationale'
+  | 'split-required'
+  | 'stop-escalate';
+export type StepReviewEventType = 'pending' | 'review-recorded' | 'attestation-verified';
+export type RemediationMode = 'ordinary' | 'corrective';
+export type RemediationFailureKind = 'checks-failed' | 'review-failed' | 'review-unverified';
+export type TaskHandoffEventType = 'handoff' | 'claim' | 'credential-replace' | 'yield' | 'handback';
+export type TaskCoordinationLevel = 'C1';
+export type AdoptionPostureEventType = 'project-registration' | 'adoption-apply';
+export type MilestoneTransactionPhase = 'prepared' | 'applying' | 'applied' | 'rolled_back';
+
+export interface SidecarEventRecord {
+  eventId: string;
+  previousEventHash: string | null;
+  recordedAt: string;
+  eventHash: string;
+}
+
+export interface DownstreamProofInvalidationEvent extends SidecarEventRecord {
+  taskId: string;
+  previousTaskRevision: number;
+  resultTaskRevision: number;
+  planHash: string;
+  activeStepId: string;
+  invalidatedSteps: Array<{
+    stepId: string;
+    evidenceCommit: string;
+    triggerFiles: string[];
+  }>;
+  dirtyFiles: string[];
+  dirtyWorktreeHash?: string;
+  preservedHeadCommit: string;
+  actor: string;
+  reason: string;
+  packageVersion: string;
+}
+
+export interface DownstreamProofReplanRecoveryEvent extends SidecarEventRecord {
+  taskId: string;
+  previousTaskRevision: number;
+  resultTaskRevision: number;
+  invalidationEventId: string;
+  invalidationPlanHash: string;
+  reboundPlanHash: string;
+  knowledgeRebindRecordedAt: string;
+  dirtyFiles: string[];
+  dirtyWorktreeHash: string;
+  preservedHeadCommit: string;
+  dependencyRecoveryCommit: string | null;
+  actor: string;
+  reason: string;
+  packageVersion: string;
+}
+
+export interface DownstreamProofReplanCompatibility {
+  invalidationEventId: string;
+  activeStepId: string;
+  sourcePlanHash: string;
+  reboundPlanHash: string;
+  knowledgeRebindRecordedAt: string;
+  dirtyFiles: string[];
+  dirtyWorktreeHash: string;
+  invalidatedStepIds: string[];
+}
+
+export interface PlanRiskAuditStepClassification {
+  stepId: string;
+  categories: GuardedRiskCategory[];
+  reviewRequired: boolean;
+  failureModes: string[];
+  requiredEvidence: string[];
+  proofObligations?: PlanRiskProofObligation[];
+}
+
+export interface PlanRiskProofObligation {
+  failureMode: string;
+  counterexample: string;
+  expectedResult: string;
+  evidence: string;
+}
+
+export interface PlanRiskAuditEvent extends SidecarEventRecord {
+  taskId: string;
+  taskRevision: number;
+  briefHash: string;
+  planHash: string;
+  knowledgeMapRevision: number;
+  knowledgeMapHash: string;
+  planner: string;
+  auditor: string;
+  summary: string;
+  decision: PlanRiskAuditDecision;
+  splitRationale: string | null;
+  stepClassifications: PlanRiskAuditStepClassification[];
+  /** Hash-chained marker: audits written by the structural-edge contract retain that authority on readback. */
+  structuralProductionEdgeAuthority?: 'required-v1';
+}
+
+export interface StepReviewEvent extends SidecarEventRecord {
+  taskId: string;
+  taskRevision: number;
+  stepId: string;
+  stepDefinitionHash: string;
+  completionCommit: string;
+  checksHash: string;
+  planHash: string;
+  evidenceHash: string | null;
+  eventType: StepReviewEventType;
+  decision: ReviewStatus;
+  reviewerAttestationHash: string | null;
+  remediationRoute?: 'fix' | 'replan' | null;
+  planConflicts?: Array<{
+    findingId: string;
+    planClause: string;
+    whyFixCannotFit: string;
+    minimalPlanChange: string;
+  }>;
+  remediationCauses?: Array<{
+    findingId: string;
+    causeId: string;
+    causeFingerprint: string;
+    route: 'fix' | 'replan';
+    planConflict: boolean;
+  }>;
+}
+
+export interface ReviewerAttestationEvent extends SidecarEventRecord {
+  taskId: string;
+  stepId: string;
+  reviewer: string;
+  isolationResult: 'verified' | 'unverified';
+  outputHash: string;
+  reviewedCommit: string;
+  reviewEventHash: string;
+  planHash: string;
+  evidenceHash: string | null;
+}
+
+export interface UnclaimedExecutionBoundary {
+  kind: 'native-unclaimed-check-failure';
+  actor: string;
+  priorHandoffEventHash: string | null;
+}
+
+export interface RemediationFailureEvidence {
+  completionCommit: string;
+  checksHash: string;
+  reviewEventHash: string | null;
+  reviewerAttestationHash: string | null;
+  /**
+   * Present on native checks-failed events. The revision is assigned by task run and therefore
+   * identifies one declared execution independently of volatile check output or unchanged Git HEAD.
+   */
+  executionTaskRevision?: number;
+  /** Exact dirty product bytes protected by the failed-Step continuation transaction. */
+  dirtyWorktreeHash?: string;
+  /** Native verified lease owner and exact historical no-C1 boundary, covered by the event hash. */
+  unclaimedExecutionBoundary?: UnclaimedExecutionBoundary;
+}
+
+export interface RemediationCauseBinding {
+  authority: 'mechanical' | 'external-reviewer';
+  causeId: string;
+  causeFingerprint: string;
+  planConflict: boolean;
+}
+
+export interface RemediationEvent extends SidecarEventRecord {
+  taskId: string;
+  stepId: string;
+  guardedCategory: GuardedRiskCategory;
+  failureKind: RemediationFailureKind;
+  failureEvidence: RemediationFailureEvidence;
+  attemptOrdinal: number;
+  mode: RemediationMode;
+  /** Missing only on historical beta.11/beta.12 events retained as a compatibility bridge. */
+  causeBindings?: RemediationCauseBinding[];
+}
+
+export interface PlanIntegrityConflictEvidenceV1 {
+  kind: 'missing-npm-script-outside-allowed-writes';
+  taskRevision: number;
+  remediationEventId: string;
+  remediationEventHash: string;
+  manifestPath: 'package.json';
+  manifestHash: string | null;
+  gitHead: string;
+  stepDefinitionHash: string;
+  missingScripts: string[];
+  checkCommands: string[];
+  changedFiles: string[];
+  conflictHash: string;
+}
+
+export interface PlanIntegrityConflictEvidenceV2 {
+  kind: 'non-executable-npm-check-outside-allowed-writes';
+  taskRevision: number;
+  remediationEvents: Array<{
+    eventId: string;
+    eventHash: string;
+    attemptOrdinal: number;
+  }>;
+  manifestPath: 'package.json';
+  manifestHash: string | null;
+  gitHead: string;
+  stepDefinitionHash: string;
+  conflicts: Array<{
+    reasonCode: 'MISSING_NPM_SCRIPT' | 'REQUIRED_SELECTOR_MISSING';
+    script: string;
+    command: string;
+    scriptCommand: string | null;
+    runnerPath: string | null;
+    runnerHash: string | null;
+  }>;
+  changedFiles: string[];
+  conflictHash: string;
+}
+
+export interface PlanIntegrityConflictEvidenceV3 {
+  kind: 'check-support-anchor-outside-allowed-writes';
+  taskRevision: number;
+  remediationEvents: Array<{
+    eventId: string;
+    eventHash: string;
+    attemptOrdinal: number;
+  }>;
+  manifestPath: 'package.json';
+  manifestHash: string | null;
+  gitHead: string;
+  stepDefinitionHash: string;
+  conflicts: Array<{
+    reasonCode: 'CHECK_SUPPORT_ANCHOR_OUTSIDE_ALLOWED_WRITES';
+    script: string;
+    command: string;
+    scriptCommand: string;
+    runnerPath: string;
+    runnerHash: string;
+    supportPath: string;
+    supportHash: string;
+    importSpecifier: string;
+    expectedOutputPaths: string[];
+    anchoredMigrationNames: string[];
+  }>;
+  scopeExtensions: string[];
+  changedFiles: string[];
+  conflictHash: string;
+}
+
+export interface PlanIntegrityConflictEvidenceV4 {
+  kind: 'failed-check-component-owner-outside-allowed-writes';
+  taskRevision: number;
+  remediationEvents: Array<{
+    eventId: string;
+    eventHash: string;
+    attemptOrdinal: number;
+  }>;
+  gitHead: string;
+  stepDefinitionHash: string;
+  semanticBoundaryHash: string;
+  failedCheckCauseFingerprint: string;
+  conflicts: Array<{
+    reasonCode: 'FAILED_CHECK_COMPONENT_OWNER_OUTSIDE_ALLOWED_WRITES';
+    command: string;
+    runnerPath: string;
+    ownerPath: string;
+    ownerHash: string;
+    importChain: string[];
+    testInvocation?: {
+      kind: 'literal-vitest-catalog';
+      runnerHash: string;
+      argv: string[];
+      migrationOutputs: string[];
+      catalogNames: string[];
+    };
+    diagnosticPath: string;
+    componentRoot: string;
+  }>;
+  scopeExtensions: string[];
+  changedFiles: string[];
+  conflictHash: string;
+}
+
+export type PlanIntegrityConflictEvidence =
+  | PlanIntegrityConflictEvidenceV1
+  | PlanIntegrityConflictEvidenceV2
+  | PlanIntegrityConflictEvidenceV3
+  | PlanIntegrityConflictEvidenceV4;
+
+export interface CorrectiveDecisionEvent extends SidecarEventRecord {
+  taskId: string;
+  stepId: string;
+  triggeringAttemptCount: number;
+  decision: CorrectivePlanAuditInput['decision'];
+  auditor: string;
+  coveredFindingIds: string[];
+  coveredEventIds: string[];
+  planHash: string;
+  recoveryBasis?: 'plan-integrity';
+  planIntegrityEvidence?: PlanIntegrityConflictEvidence;
+}
+
+export interface CorrectiveDecisionRecoveryEvent extends SidecarEventRecord {
+  taskId: string;
+  stepId: string;
+  triggeringAttemptCount: number;
+  correctiveDecisionEventId: string;
+  correctiveDecisionEventHash: string;
+  decisionPlanHash: string;
+  reboundPlanHash: string;
+  semanticPlanHash: string;
+  fromKnowledgeMapRevision: number;
+  fromKnowledgeMapHash: string;
+  toKnowledgeMapRevision: number;
+  toKnowledgeMapHash: string;
+  rebindRecordedAt: string;
+  sourcePlanRiskAuditEventId: string;
+  sourcePlanRiskAuditEventHash: string;
+  reboundPlanRiskAuditEventId: string;
+  reboundPlanRiskAuditEventHash: string;
+  knowledgeMapApprovalFingerprint: string;
+  taskAuthorizationFingerprint: string;
+  delegationGrantFingerprint: string;
+  c1EvidenceFingerprint: string;
+  evidenceFingerprint: string;
+  actor: string;
+}
+
+export interface RemediationModeRecoveryEvent extends SidecarEventRecord {
+  taskId: string;
+  stepId: string;
+  taskRevision: number;
+  remediationEventId: string;
+  remediationEventHash: string;
+  correctiveDecisionEventId: string;
+  correctiveDecisionEventHash: string;
+  correctiveDecisionRecoveryEventId: string;
+  correctiveDecisionRecoveryEventHash: string;
+  attemptOrdinal: 3;
+  planHash: string;
+  actor: string;
+  c1ClaimEventHash: string | null;
+  writerLeaseTokenHash: string | null;
+  fromMode: 'ordinary';
+  toMode: 'corrective';
+  reason: 'alpha7.2-recovered-continue-fix-mode-omission';
+}
+
+export interface StopEscalateOverrideEvent extends SidecarEventRecord {
+  taskId: string;
+  taskRevision: number;
+  stepId: string;
+  stopDecisionEventId: string;
+  stopDecisionEventHash: string;
+  priorContinueDecisionEventId: string;
+  priorContinueDecisionEventHash: string;
+  triggeringAttemptCount: 4;
+  coveredEventIds: string[];
+  planHash: string;
+  headCommit: string;
+  actor: string;
+  reason: string;
+  packageVersion: string;
+  confirmationCodeBindingHash: string;
+  policy: 'beta11-attempt4-stop-compatibility-v1';
+}
+
+export interface TaskHandoffMachineEvidence {
+  hostname: string;
+  pid: number;
+  platform: string;
+  arch: string;
+  nodeVersion: string;
+}
+
+export interface TaskHandbackRecord {
+  status: TaskStatus;
+  mergedCommit: string | null;
+  planHash: string | null;
+  resultHash: string | null;
+  evidenceHash: string | null;
+  reviewAttestationHash: string | null;
+  knowledgeMapRevision: number | null;
+  knowledgeMapHash: string | null;
+  limitations: string[];
+  recommendedNext: string;
+}
+
+export interface MilestoneDependencyBinding {
+  milestoneRevision: number;
+  membershipRevision: number;
+  milestonePlanHash: string;
+}
+
+export interface TaskHandoffBundle {
+  handoffId: string;
+  milestoneId: string | null;
+  milestoneDisplayNumber: number | null;
+  taskId: string;
+  taskDisplayNumber: number | null;
+  taskRevision: number;
+  briefHash: string;
+  planHash: string | null;
+  knowledgeMapRevision: number | null;
+  knowledgeMapHash: string | null;
+  dependencyBinding: MilestoneDependencyBinding | null;
+  expectedNext: string;
+  delegate: string;
+  grantId: string | null;
+  claimToken: string;
+  createdAt: string;
+  expiresAt: string;
+  prompt: string;
+}
+
+export interface TaskHandoffEvent extends SidecarEventRecord {
+  handoffId: string;
+  taskId: string;
+  taskRevision: number;
+  milestoneId: string | null;
+  milestoneDisplayNumber: number | null;
+  taskDisplayNumber: number | null;
+  briefHash: string;
+  planHash: string | null;
+  knowledgeMapRevision: number | null;
+  knowledgeMapHash: string | null;
+  /** Missing only on legacy sidecar events written before canonical Milestone dependencies. */
+  dependencyBinding?: MilestoneDependencyBinding | null;
+  expectedNext: string;
+  delegate: string;
+  grantId: string | null;
+  claimTokenHash: string;
+  expiresAt: string;
+  eventType: TaskHandoffEventType;
+  coordinationLevel: TaskCoordinationLevel;
+  actor: string;
+  targetActor: string | null;
+  machineEvidence: TaskHandoffMachineEvidence;
+  writerLeaseTokenHash: string | null;
+  reason: string;
+  handback: TaskHandbackRecord | null;
+}
+
+export interface MilestoneScopeSnapshot {
+  outcome: string;
+  successSignal: string;
+  acceptance: string[];
+  checks: string[];
+  taskIds: string[];
+  memberships: MilestoneMembership[];
+}
+
+export interface AuditedRemediationEvidence {
+  blockedTaskId: string;
+  blockedTaskRevision: number;
+  blockedBriefHash: string;
+  blockedPlanHash: string;
+  planRiskAuditEventId: string;
+  planRiskAuditEventHash: string;
+  remediationTaskId: string;
+  predecessorTaskIds: string[];
+}
+
+export interface MilestoneScopeChangeEvent extends SidecarEventRecord {
+  milestoneId: string;
+  previousMilestoneRevision: number;
+  previousPlanHash: string | null;
+  previousMembershipRevision: number;
+  candidatePlanHash: string;
+  candidateMembershipRevision: number;
+  before: MilestoneScopeSnapshot;
+  after: MilestoneScopeSnapshot;
+  actor: string;
+  confirmationCodeBindingHash: string;
+  authorizationMode?: 'human' | 'milestone-autonomy' | 'audited-remediation';
+  autonomyContractEventHash?: string | null;
+  remediationEvidence?: AuditedRemediationEvidence | null;
+}
+
+export interface AdoptionTaskStepSnapshot {
+  stepId: string;
+  status: 'completed' | 'skipped';
+  evidenceHash: string | null;
+}
+
+export interface AdoptionTaskBaseline {
+  taskId: string;
+  taskRevision: number;
+  status: Exclude<TaskStatus, 'merged' | 'cancelled'>;
+  completedSteps: AdoptionTaskStepSnapshot[];
+  remainingStepIds: string[];
+}
+
+export interface AdoptionRepositoryIdentity {
+  repositoryRoot: string;
+  gitCommonDir: string;
+}
+
+export interface AdoptionPostureEvent extends SidecarEventRecord {
+  projectId: string;
+  eventType: AdoptionPostureEventType;
+  actor: string | null;
+  packageVersion: string;
+  /** Persisted protocol evidence. Version 1 remains readable for the exact state-schema-v2 compatibility boundary. */
+  protocolVersion: 1 | typeof PROTOCOL_VERSION;
+  stateSchemaVersion: typeof STATE_SCHEMA_VERSION;
+  adoptionBoundaryAt: string;
+  baselineDigestHash: string;
+  sidecarBaselineHash: string;
+  confirmationCodeBindingHash: string | null;
+  repositoryIdentity: AdoptionRepositoryIdentity;
+  terminalMilestones: Array<{
+    milestoneId: string;
+    revision: number;
+    status: Extract<MilestoneStatus, 'accepted' | 'cancelled'>;
+  }>;
+  terminalTasks: Array<{
+    taskId: string;
+    revision: number;
+    status: Extract<TaskStatus, 'merged' | 'cancelled'>;
+  }>;
+  activeTasks: AdoptionTaskBaseline[];
+}
+
+export interface MilestoneTransactionJournalFileSnapshot {
+  exists: boolean;
+  contentHash: string | null;
+  contentBase64: string | null;
+  contentPath: string | null;
+}
+
+export interface MilestoneTransactionJournalTarget {
+  path: string;
+  preimage: MilestoneTransactionJournalFileSnapshot;
+  staged: MilestoneTransactionJournalFileSnapshot;
+}
+
+export interface MilestoneTransactionJournal {
+  transactionId: string;
+  milestoneId: string;
+  expectedMilestoneRevision: number;
+  actor: string;
+  confirmationCodeBindingHash: string;
+  phase: MilestoneTransactionPhase;
+  targetFiles: MilestoneTransactionJournalTarget[];
+  preparedAt: string;
+  updatedAt: string;
+}
+
+export interface TaskContextRefreshResult {
+  authority?: 'planning-only' | 'execution';
+  mode: 'delegated-content-only' | 'delegated-plan-bounded-supporting-source';
+  transitions: string[];
+  addedSources: Array<Pick<KnowledgeSource, 'id' | 'path' | 'category' | 'scope' | 'authority'>>;
+  knowledgeMap: ProjectKnowledgeMap;
+  task: TaskState;
+}
+
+export type ObservationReasonCode =
+  | 'PROJECT_REGISTRATION_MISSING'
+  | 'PROJECT_REPOSITORY_ROOT_UNBOUND'
+  | 'PROJECT_RECOVERY_REQUIRED'
+  | 'MILESTONE_RECOVERY_REQUIRED'
+  | 'TASK_RECOVERY_REQUIRED'
+  | 'TASK_TRANSACTION_INTEGRITY_FAILED'
+  | 'TASK_OPERATION_IN_PROGRESS'
+  | 'STALE_TASK_OPERATION'
+  | 'ACTIVE_WRITER_LEASE'
+  | 'STALE_WRITER_LEASE'
+  | 'ADOPTION_MISSING';
+
+export interface ObservedProjectTransaction {
+  transactionId: string;
+  kind: string;
+  phase: 'prepared' | 'applying' | 'applied' | 'rolled_back';
+  preparedAt: string;
+  ownerActive: boolean;
+}
+
+export interface ObservedMilestoneTransaction {
+  milestoneId: string;
+  transactionId: string;
+  phase: MilestoneTransactionPhase;
+  preparedAt: string;
+  updatedAt: string;
+}
+
+export interface ObservedTaskTransaction {
+  transitionId: 'task.plan.corrective-replan' | 'task.coordination.corrective-yield';
+  taskId: string;
+  transactionId: string;
+  phase: 'intent' | 'applying' | 'published-pending-readback' | 'completed';
+  phaseRevision: number;
+  updatedAt: string;
+}
+
+export interface CorruptObservedTaskTransaction {
+  taskId: string;
+  transactionId: string;
+  reason: 'journal-invalid';
+}
+
+export interface PublicWriterLease {
+  schemaVersion: typeof STATE_SCHEMA_VERSION;
+  entityId: string;
+  owner: string;
+  pid: number;
+  hostname: string;
+  acquiredAt: string;
+  heartbeatAt: string;
+  expiresAt: string;
+  stale: boolean;
+}
+
+export interface PublicCoreTaskOperation {
+  schemaVersion: typeof STATE_SCHEMA_VERSION;
+  entityId: string;
+  operationId: string;
+  transitionId: string;
+  owner: 'workflow-core';
+  acquiredAt: string;
+  expiresAt: string;
+  stale: boolean;
+}
+
+export interface PublicWriterLeaseDiagnostic extends PublicWriterLease {
+  tokenFingerprint: string;
+}
+
+export interface PublicWriterLeaseRepairResult extends PublicWriterLeaseDiagnostic {
+  repaired: true;
+}
+
+export interface WriterCredentialStatus {
+  disposition: 'issued' | 'renewed';
+}
+
+export type WriterCredentialResult =
+  | { disposition: 'issued'; token: string }
+  | { disposition: 'renewed' };
+
+export interface MilestoneObservationRepairCommand {
+  command: 'milestone recover';
+  cataloged: false;
+  projectId: string;
+  milestoneIds: string[];
+  transactionIds: string[];
+}
+
+export interface LeaseObservationRepairCommand {
+  command: 'locks repair';
+  cataloged: false;
+  projectId: string;
+  entityIds: string[];
+}
+
+export interface TaskTransactionObservationRepairCommand {
+  command: 'task corrective-replan-recover' | 'task corrective-yield-recover';
+  cataloged: false;
+  available: true;
+  projectId: string;
+  taskIds: string[];
+  transactionIds: string[];
+}
+
+export type ObservationRepairCommand =
+  | MilestoneObservationRepairCommand
+  | LeaseObservationRepairCommand
+  | TaskTransactionObservationRepairCommand;
+
+export interface WorkflowObservation {
+  kind: 'assessment' | 'repair' | 'blocked';
+  reasonCodes: ObservationReasonCode[];
+  stateRootPresent: boolean;
+  projectRootPresent: boolean;
+  lockRootPresent: boolean;
+  missingRegistration: boolean;
+  repositoryRootBound: boolean;
+  adoptionAssessed: boolean;
+  missingAdoption: boolean;
+  pendingProjectTransactions: ObservedProjectTransaction[];
+  pendingMilestoneTransactions: ObservedMilestoneTransaction[];
+  pendingTaskTransactions: ObservedTaskTransaction[];
+  corruptTaskTransactions: CorruptObservedTaskTransaction[];
+  coreTaskOperations: PublicCoreTaskOperation[];
+  leases: PublicWriterLease[];
+  availableRepairTransitionId: null;
+  repair: ObservationRepairCommand | null;
+}
+
+export interface UpdatePreflightResult {
+  safe: boolean;
+  packageVersion: string;
+  protocolVersion: typeof PROTOCOL_VERSION;
+  stateSchemaVersion: typeof STATE_SCHEMA_VERSION;
+  projectId: string;
+  repositoryRoot: string;
+  clean: boolean;
+  changedFiles: string[];
+  runningSteps: Array<{ taskId: string; stepId: string }>;
+  activeLeases: PublicWriterLease[];
+  staleLeases: PublicWriterLease[];
+  blockers: string[];
+  workflowVersions: {
+    runtime: string;
+    declared: string | null;
+    locked: string | null;
+    installed: string | null;
+    currentBranch: string | null;
+    milestoneBases: Array<{ branch: string; version: string | null; milestoneIds: string[] }>;
+  };
+  dependencyTransport: {
+    safe: boolean;
+    requiredAction: string | null;
+  };
+  observation: WorkflowObservation;
+}
+
+export interface DependencyProvenanceRecoveryRecord {
+  commitSha: string;
+  parentCommitSha: string;
+  packageName: string;
+  packageVersion: string;
+  files: ['package-lock.json', 'package.json'];
+  actor: string;
+  reason: string;
+  recordedAt: string;
+  retainedHistoricalCommits?: string[];
+  activeDownstreamProof?: {
+    activeStepId: string;
+    planHash: string;
+    dirtyFiles: string[];
+    dirtyWorktreeHash: string;
+    invalidatedStepIds: string[];
+  };
+  downstreamProofReplan?: DownstreamProofReplanCompatibility;
+  historicalStepProvenance?: HistoricalStepDependencyCompatibility;
+  planIntegrity?: PlanIntegrityUpdateCompatibility;
+  rootCauseReplan?: RootCauseReplanDirtyCarryoverCompatibility;
+}
+
+export interface RootCauseReplanDirtyCarryoverCompatibility {
+  kind: 'root-cause-corrective-replan-dirty-carryover';
+  taskId: string;
+  sourceTaskRevision: number;
+  stepId: string;
+  sourcePlanHash: string;
+  sourcePlanSemanticHash: string;
+  replacementPlanHash: string;
+  replacementPlanSemanticHash: string;
+  sourceHeadCommit: string;
+  remediationEvents: Array<{ eventId: string; eventHash: string; attemptOrdinal: number }>;
+  terminalRemediationEventId: string;
+  terminalRemediationEventHash: string;
+  terminalExecutionTaskRevision: number;
+  repeatedCauseFingerprint: string;
+  correctiveYieldEventId: string | null;
+  correctiveYieldEventHash: string | null;
+  unclaimedExecutionBoundary?: UnclaimedExecutionBoundary;
+  dirtyFiles: string[];
+  dirtyWorktreeHash: string;
+  replacementPlanRiskAuditEventId: string;
+  replacementPlanRiskAuditEventHash: string;
+  executionAuthorizationHash: string;
+  executionAuthorizationHead: string;
+  completedStepsHash: string;
+  c1ClaimEventId: string;
+  c1ClaimEventHash: string;
+  claimant: string;
+  compatibilityHash: string;
+}
+
+export interface HistoricalStepDependencyCompatibility {
+  activeStepId: string;
+  planHash: string;
+  dirtyFiles: string[];
+  dirtyWorktreeHash: string;
+  retainedCommitSha: string;
+}
+
+export interface PlanIntegrityUpdateCompatibility {
+  stepId: string;
+  planHash: string;
+  conflictHash: string;
+  dirtyFiles: string[];
+  dirtyWorktreeHash: string;
+  remediationEventIds: string[];
+  mode?:
+    | 'failed-step-conflict'
+    | 'post-rebind-scope-adoption'
+    | 'post-rebind-dirty-carryover'
+    | 'navigation-fix-dirty-carryover';
+  scopeExtensions?: string[];
+}
+
+export interface DependencyProvenanceRecoveryPreflight {
+  eligible: boolean;
+  action:
+    | 'update dependency-provenance-recover'
+    | 'update downstream-proof-dependency-recover'
+    | 'update historical-step-dependency-recover'
+    | null;
+  projectId: string;
+  taskId: string;
+  taskRevision: number;
+  commitSha: string | null;
+  parentCommitSha: string | null;
+  packageVersion: string;
+  changedFiles: string[];
+  /** Oldest-to-newest exact dependency-only commits recovered atomically. */
+  dependencyCommits: Array<{
+    commitSha: string;
+    parentCommitSha: string;
+    packageVersion: string;
+  }>;
+  retainedHistoricalCommits: string[];
+  activeDownstreamProof: {
+    activeStepId: string;
+    planHash: string;
+    dirtyFiles: string[];
+    dirtyWorktreeHash: string;
+    invalidatedStepIds: string[];
+  } | null;
+  historicalStepProvenance: HistoricalStepDependencyCompatibility | null;
+  /** Derived from an existing, native-evidence-bound navigation checkpoint; never caller authority. */
+  retainedNavigationCarryover?: PlanIntegrityUpdateCompatibility | null;
+  blockers: string[];
+}
+
+export interface HistoricalStepProvenanceRecoveryRecord {
+  commitSha: string;
+  actor: string;
+  reason: string;
+  recordedAt: string;
+  sourceFinalAcceptanceRecordedAt: string;
+  sourcePlanHash: string;
+  sourceResultHash: string;
+  sourceEvidenceHash: string;
+}
+
+export interface HistoricalStepProvenanceRecoveryPreflight {
+  eligible: boolean;
+  action: 'task historical-step-provenance-recover' | null;
+  projectId: string;
+  taskId: string;
+  taskRevision: number;
+  briefHash: string;
+  planHash: string | null;
+  headCommit: string;
+  activeStepId: string | null;
+  dirtyFiles: string[];
+  commitSha: string | null;
+  sourceFinalAcceptanceRecordedAt: string | null;
+  blockers: string[];
+}
+
+export interface MilestoneProgressStepProjection {
+  ordinal: string;
+  stepId: string;
+  title: string;
+  status: StepStatus;
+}
+
+export interface MilestoneProgressTaskProjection {
+  ordinal: string;
+  taskId: string;
+  title: string;
+  status: TaskStatus;
+  revision: number;
+  disposition: MilestoneMembership['disposition'];
+  membershipReason: string;
+  dependencyState: 'canonical' | 'legacy-unknown';
+  dependsOnTaskIds: string[];
+  unsatisfiedPredecessors: Array<{
+    taskId: string;
+    disposition: MilestoneMembership['disposition'] | 'missing';
+    status: TaskStatus | 'missing';
+  }>;
+  runnable: boolean;
+  dependencyBlockReason: string | null;
+  replacementForTaskId: string | null;
+  replacedByTaskId: string | null;
+  stepsCompleted: number;
+  stepsTotal: number;
+  steps: MilestoneProgressStepProjection[];
+}
+
+export interface MilestoneProgressProjection {
+  readOnly: true;
+  projectId: string;
+  milestoneId: string;
+  milestoneTitle: string;
+  milestoneStatus: MilestoneStatus;
+  milestoneRevision: number;
+  membershipRevision: number;
+  tasksCompleted: number;
+  tasksRequired: number;
+  tasks: MilestoneProgressTaskProjection[];
+}
+
+export interface TaskState extends RevisionedRecord {
+  kind: 'task';
+  status: TaskStatus;
+  title: string;
+  slug: string;
+  discoveryId: string;
+  milestoneId: string | null;
+  repositoryRoot: string;
+  baseBranch: string;
+  baseCommit: string | null;
+  taskBranch: string | null;
+  workspaceOwner: WorkspaceOwner | null;
+  briefHash: string;
+  planHash: string | null;
+  planObjective: string | null;
+  resultHash: string | null;
+  evidenceHash: string | null;
+  requirements: string[];
+  acceptance: string[];
+  risks: string[];
+  knowledgeImpact: KnowledgeImpact | null;
+  knowledgeImpactReason: string | null;
+  knowledgeTargets: KnowledgeTarget[];
+  knowledgeMapRevision: number | null;
+  knowledgeMapHash: string | null;
+  graphUse: GraphUse | null;
+  /** Optional structural production-path contract persisted with the approved Plan. */
+  productionEdges?: ProductionEdgeInput[];
+  /** Explicit structural boundary acknowledgement; runtime-composition PRA remains authoritative. */
+  requiresProductionEdges?: boolean;
+  steps: TaskStep[];
+  authorizations: AuthorizationEvent[];
+  knowledgeRebinds: TaskKnowledgeRebindRecord[];
+  review: ReviewRecord;
+  blockReason: string | null;
+  mergedCommit: string | null;
+  systemCommits: string[];
+  /** Durable unvalidated merge checkpoint; never approval or successful check evidence. */
+  pendingBaseSyncValidation?: { baseCommit: string; syncCommit: string; checksHash: string; headCommit: string };
+  /** Product commits retained after bounded invalidation of stale completed-Step authority. */
+  invalidatedStepCommits?: string[];
+  /** Audit trail for bounded recovery of previously reviewed Step commits omitted by a corrective Plan. */
+  historicalStepProvenanceRecoveries?: HistoricalStepProvenanceRecoveryRecord[];
+  /** Audit trail for bounded adoption of exact Workflow dependency-only commits. */
+  dependencyProvenanceRecoveries?: DependencyProvenanceRecoveryRecord[];
+  /** Set only by the beta replacement transaction; absent on legacy states. */
+  replacementForTaskId?: string | null;
+  /** Set only on the terminal historical Task consumed by a replacement transaction. */
+  replacedByTaskId?: string | null;
+}
+
+export interface MilestoneState extends RevisionedRecord {
+  kind: 'milestone';
+  status: MilestoneStatus;
+  title: string;
+  discoveryId: string;
+  outcome: string;
+  successSignal: string;
+  acceptance: string[];
+  baseBranch: string;
+  taskIds: string[];
+  memberships: MilestoneMembership[];
+  checks: string[];
+  membershipRevision: number;
+  authorizations: AuthorizationEvent[];
+  planHash: string | null;
+  resultHash: string | null;
+  evidenceHash: string | null;
+  acceptedHead: string | null;
+  cancellationReason: string | null;
+}
+
+export interface MilestoneMembership {
+  taskId: string;
+  disposition: 'required' | 'waived' | 'cancelled';
+  reason: string;
+  /** Missing only on legacy persisted Milestones whose dependency graph is unknown. */
+  dependsOnTaskIds?: string[];
+}
+
+export interface MilestonePlanMembershipInput extends MilestoneMembership {
+  dependsOnTaskIds: string[];
+}
+
+export interface MilestonePlanInput {
+  outcome: string;
+  successSignal: string;
+  acceptance: string[];
+  memberships: MilestonePlanMembershipInput[];
+  checks: string[];
+}
+
+export interface MilestoneFinalAcceptanceGate {
+  kind: 'milestone_final_acceptance';
+  milestoneId: string;
+  revision: number;
+  planHash: string | null;
+  resultHash: string;
+  evidenceHash: string;
+  headCommit: string;
+  confirmationCode: string;
+}
+
+export interface ProjectRecord {
+  schemaVersion: typeof STATE_SCHEMA_VERSION;
+  projectId: string;
+  gitCommonDir: string;
+  repositoryRoots: string[];
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface WriterLease {
+  schemaVersion: typeof STATE_SCHEMA_VERSION;
+  entityId: string;
+  token: string;
+  owner: string;
+  pid: number;
+  hostname: string;
+  acquiredAt: string;
+  heartbeatAt: string;
+  expiresAt: string;
+}
+
+export interface ContextEnvelope {
+  protocolVersion: typeof PROTOCOL_VERSION;
+  packageVersion: string;
+  role: WorkflowRole;
+  objective: string;
+  inputs: string[];
+  allowedReads: string[];
+  allowedWrites: string[];
+  commands: string[];
+  forbiddenScope: string[];
+  resultSchema: Record<string, unknown>;
+  stopConditions: string[];
+  contextBudget: 'small' | 'medium' | 'large';
+  taskId: string;
+  stepId: string;
+  expectedRevision: number;
+  writerToken: string | null;
+  knowledgeMap: {
+    revision: number;
+    hash: string;
+    status: KnowledgeMapStatus;
+  };
+  knowledgeSources: string[];
+}
+
+export type EntityState =
+  | DiscoveryState
+  | TaskState
+  | MilestoneState
+  | ProjectKnowledgeMap
+  | GraphBinding
+  | DelegationGrant;