@moretea-labs/forge 1.7.1 → 1.8.0

package/src/runtime/control-plane/facade/types.ts

@@ -1,10 +1,35 @@
-import type { ProcessCheckReceiptEvidence } from '../../evidence/process-check-receipt';
-import type { CompletionReceipt as RepositoryCompletionReceipt } from '../../../cli/controller/types';
-import type { AccessMode } from '../governance/access-policy';
-import { decideRoute, type ExplicitTaskMode, type RouteDecision, type RoutePolicyInput } from '../routing/route-policy';
+import type {
+  WorkContract,
+  VerificationOutcome,
+  ExecutionMode,
+  FacadeDetailLevel,
+  EvidenceRef,
+  SuggestedNextAction,
+  PolicyDecision,
+} from '../../../../packages/kernel/work/domain/types';
+export type {
+  ExecutionMode,
+  FacadeDetailLevel,
+  EvidenceRef,
+  SuggestedNextAction,
+  PolicyDecision,
+} from '../../../../packages/kernel/work/domain/types';
+import { applyRouteContextHints, decideRoute, type ExplicitTaskMode, type RouteContextHints, type RouteDecision, type RoutePolicyInput } from '../routing/route-policy';
+import {
+  TERMINAL_PLAN_CONTRACT_STATUSES,
+  type PlanContractStatus,
+  type PlanStepStatus,
+} from '../../../../packages/kernel/goal/api/index';
+export {
+  PLAN_CONTRACT_STATUSES,
+  TERMINAL_PLAN_CONTRACT_STATUSES,
+  PLAN_STEP_STATUSES,
+  type PlanContractStatus,
+  type PlanStepStatus,
+} from '../../../../packages/kernel/goal/api/index';
 
 export const EXECUTION_MODES = ['direct_control', 'goal_workloop', 'handoff_only'] as const;
-export type ExecutionMode = (typeof EXECUTION_MODES)[number];
+const _executionModesTypeCheck: readonly ExecutionMode[] = EXECUTION_MODES;
 
 export const FACADE_TOOLS = ['rh_access', 'rh_status', 'rh_inbox', 'rh_context', 'rh_work'] as const;
 export type FacadeTool = (typeof FACADE_TOOLS)[number];
@@ -13,7 +38,6 @@ export type CapabilityExecutionSurface = FacadeTool | 'plugin_action_execute';
 export const FACADE_STATUSES = ['ok', 'blocked', 'failed', 'approval_required', 'not_found'] as const;
 export type FacadeStatus = (typeof FACADE_STATUSES)[number];
 
-export type FacadeDetailLevel = 'summary' | 'detail' | 'raw';
 
 export const CAPABILITY_DOMAINS = ['repository', 'plugin', 'controller', 'evidence', 'maintenance'] as const;
 export type CapabilityDomain = (typeof CAPABILITY_DOMAINS)[number];
@@ -55,236 +79,62 @@ export type PolicyDecisionKind = (typeof POLICY_DECISIONS)[number];
 export const HANDOFF_SEVERITIES = ['info', 'needs_review', 'blocked', 'failed', 'ready_to_continue'] as const;
 export type HandoffSeverity = (typeof HANDOFF_SEVERITIES)[number];
 
-export const HANDOFF_STATUSES = [
-  'pending',
-  'acknowledged',
-  'in_progress',
-  'resolved',
-  'dismissed',
-  'superseded',
-  'expired',
-] as const;
-export type HandoffStatus = (typeof HANDOFF_STATUSES)[number];
-
-export const TERMINAL_HANDOFF_STATUSES: readonly HandoffStatus[] = [
-  'resolved',
-  'dismissed',
-  'superseded',
-  'expired',
-] as const;
-
-export const WORK_CONTRACT_STATUSES = [
-  'open',
-  'running',
-  'blocked',
-  'ready',
-  'completed',
-  'failed',
-  'cancelled',
-] as const;
-export type WorkContractStatus = (typeof WORK_CONTRACT_STATUSES)[number];
-
-/**
- * Work execution phases are intentionally small and technical. User-facing
- * Requirement lifecycle belongs to Requirement, not this projection.
- */
-export const WORK_PHASES = ['implementation', 'verification', 'delivery', 'cleanup'] as const;
-export type WorkPhase = (typeof WORK_PHASES)[number];
-
-export const WORK_PHASE_EVIDENCE_STATES = ['pending', 'active', 'satisfied', 'blocked', 'failed', 'skipped'] as const;
-export type WorkPhaseEvidenceState = (typeof WORK_PHASE_EVIDENCE_STATES)[number];
-
-/** Durable evidence checkpoint for one technical Work phase. */
-export interface WorkPhaseEvidence {
-  state: WorkPhaseEvidenceState;
-  source?: 'recorded' | 'legacy_inferred';
-  summary: string;
-  evidenceRefs: EvidenceRef[];
-  recordedAt: string;
-  receiptId?: string;
-}
-
-export type WorkPhaseEvidenceMap = Record<WorkPhase, WorkPhaseEvidence>;
-
-/** Risk is part of the Work contract, never of a mutable Task projection. */
-export const WORK_RISKS = ['readonly', 'low', 'medium', 'high', 'destructive'] as const;
-export type WorkRisk = (typeof WORK_RISKS)[number];
-
-export const TERMINAL_WORK_CONTRACT_STATUSES: readonly WorkContractStatus[] = [
-  'completed',
-  'failed',
-  'cancelled',
-] as const;
-
-/** Independent semantic axes; `status` remains a compatibility projection. */
-export const WORK_KINDS = [
-  'repository_change',
-  'completed_no_change',
-  'read_only_review',
-  'investigation',
-  'local_effect',
-  'remote_effect',
-  'reconciliation',
-  'superseded',
-] as const;
-export type WorkKind = (typeof WORK_KINDS)[number];
-
-export const DISPATCH_STATES = ['not_dispatched', 'claimed', 'launching', 'running', 'blocked', 'terminal'] as const;
-export type DispatchState = (typeof DISPATCH_STATES)[number];
-
-export const EVIDENCE_STATES = ['none', 'partial', 'valid', 'stale', 'contradictory', 'failed'] as const;
-export type EvidenceState = (typeof EVIDENCE_STATES)[number];
-
-export const COMPLETION_OUTCOMES = ['completed_changed', 'completed_no_change', 'completed_local', 'completed_remote', 'superseded'] as const;
-export type CompletionOutcome = (typeof COMPLETION_OUTCOMES)[number];
-
-/** Source-bound semantic evidence accumulated by a recoverable read-only review. */
-export interface ReadOnlyReviewEvidence {
-  sourceRevision: string;
-  workspaceFingerprint?: string;
-  inspectedPaths: string[];
-  findings: string[];
-  recordedAt: string;
-}
-
-/** Controller-reviewed binding from one exact Work acceptance criterion to durable evidence. */
-export interface WorkSemanticAcceptanceEvidence {
-  criterion: string;
-  evidenceIds: string[];
-  rationale: string;
-  recordedAt: string;
-}
-
-/**
- * Terminal authority for a clean read-only review. This deliberately does not
- * impersonate repository delivery: it proves the reviewed source stayed at the
- * frozen base revision with no workspace delta and records the bounded review
- * scope that justified completed_no_change.
- */
-export interface ReadOnlyReviewCompletionReceipt {
-  schemaVersion: 1;
-  receiptId: string;
-  source: 'read_only_review';
-  workId: string;
-  baseRevision: string;
-  sourceRevision: string;
-  workspaceFingerprint?: string;
-  /** Explicit unchanged-workspace proof captured by the trusted finalizer. Must be empty. */
-  workspaceChangedPaths: string[];
-  inspectedPaths: string[];
-  findingCount: 0;
-  recordedAt: string;
-}
-
-/**
- * Terminal receipt for a bounded Controller-local side effect that is not a
- * repository delivery. Repository Task/Issue completion keeps using the
- * historical Git-oriented CompletionReceipt unchanged.
- */
-export interface LocalEffectCompletionReceipt {
-  schemaVersion: 1;
-  receiptId: string;
-  source: 'local_effect';
-  workId: string;
-  operation: string;
-  target: {
-    kind: 'workspace_target' | 'controller_local';
-    id: string;
-    identityFingerprint?: string;
-  };
-  changed: boolean;
-  recordedAt: string;
-}
-
-/** Durable completion authority for one typed remote effect. */
-export interface RemoteEffectCompletionReceipt {
-  schemaVersion: 1;
-  /** Plugin receipts retain their PLG-* id; repository Process effects use their canonical Process id. */
-  receiptId: string;
-  source: 'remote_effect';
-  workId: string;
-  /** Historical receipts omit this field and are interpreted as plugin_action. */
-  authority?: 'plugin_action' | 'repository_process';
-  pluginId?: string;
-  actionId: string;
-  requestId: string;
-  semanticKey: string;
-  resultDigest: string;
-  processId?: string;
-  recordedAt: string;
-}
-
-/**
- * Completion authority for a standalone Direct Edit that is not bound to the
- * retired Issue/Task completion model. Normal completion proves one finalized
- * edit session at an exact reachable Git revision. Historical completion may
- * instead reference one explicit reviewed reconciliation after exact revision,
- * path-scope, verification, reachability, and cleanup proof checks.
- */
-export interface DirectEditWorkCompletionReceipt {
-  schemaVersion: 1;
-  receiptId: string;
-  source: 'direct_edit_work';
-  workId: string;
-  editSessionId?: string;
-  reconciliationId?: string;
-  targetBranch: string;
-  targetRevision: string;
-  sourceRevision?: string;
-  baseRevision?: string;
-  changedPaths: string[];
-  delivery: RepositoryCompletionReceipt['delivery'];
-  cleanup: RepositoryCompletionReceipt['cleanup'];
-  verifiedAt: string;
-  recordedAt: string;
-}
-
-export type WorkCompletionReceipt = RepositoryCompletionReceipt | DirectEditWorkCompletionReceipt | ReadOnlyReviewCompletionReceipt | LocalEffectCompletionReceipt | RemoteEffectCompletionReceipt;
-
-export function isRepositoryCompletionReceipt(
-  receipt: WorkCompletionReceipt,
-): receipt is RepositoryCompletionReceipt {
-  return receipt.source !== 'local_effect'
-    && receipt.source !== 'remote_effect'
-    && receipt.source !== 'direct_edit_work'
-    && receipt.source !== 'read_only_review';
-}
-
-export function isReadOnlyReviewCompletionReceipt(
-  receipt: WorkCompletionReceipt,
-): receipt is ReadOnlyReviewCompletionReceipt {
-  return receipt.source === 'read_only_review';
-}
-
-export function isRemoteEffectCompletionReceipt(
-  receipt: WorkCompletionReceipt,
-): receipt is RemoteEffectCompletionReceipt {
-  return receipt.source === 'remote_effect';
-}
-
-export function isDirectEditWorkCompletionReceipt(
-  receipt: WorkCompletionReceipt,
-): receipt is DirectEditWorkCompletionReceipt {
-  return receipt.source === 'direct_edit_work';
-}
-
-/** A reviewed exception for historical/manual integration; never inferred automatically. */
-export const WORK_RECONCILIATION_METHODS = ['exact_commit', 'owned_path_tree', 'reviewed_patch_identity'] as const;
-export type WorkReconciliationMethod = (typeof WORK_RECONCILIATION_METHODS)[number];
-
-export const WORK_RECONCILIATION_OUTCOMES = ['accepted_equivalence', 'rejected_equivalence', 'superseded'] as const;
-export type WorkReconciliationOutcome = (typeof WORK_RECONCILIATION_OUTCOMES)[number];
-
-export const VERIFICATION_OUTCOMES = [
-  'valid_pass',
-  'valid_fail',
-  'invalid_check_id',
-  'infrastructure_failure',
-  'skipped',
-  'superseded',
-] as const;
-export type VerificationOutcome = (typeof VERIFICATION_OUTCOMES)[number];
-
+export { HANDOFF_STATUSES, TERMINAL_HANDOFF_STATUSES, isTerminalHandoffStatus, type HandoffStatus } from '../../../../packages/protocols/handoff/index';
+import type { HandoffStatus } from '../../../../packages/protocols/handoff/index';
+
+// Kernel V2: Work domain contracts are owned by packages/kernel/work/domain.
+export {
+  WORK_CONTRACT_STATUSES,
+  WORK_PHASES,
+  WORK_PHASE_EVIDENCE_STATES,
+  WORK_RISKS,
+  TERMINAL_WORK_CONTRACT_STATUSES,
+  WORK_KINDS,
+  DISPATCH_STATES,
+  EVIDENCE_STATES,
+  COMPLETION_OUTCOMES,
+  WORK_RECONCILIATION_METHODS,
+  WORK_RECONCILIATION_OUTCOMES,
+  VERIFICATION_OUTCOMES,
+  isRepositoryCompletionReceipt,
+  isReadOnlyReviewCompletionReceipt,
+  isRemoteEffectCompletionReceipt,
+  isDirectEditWorkCompletionReceipt,
+  isTerminalWorkContractStatus,
+} from '../../../../packages/kernel/work/domain/types';
+export type {
+  WorkContractStatus,
+  WorkPhase,
+  WorkPhaseEvidenceState,
+  WorkPhaseEvidence,
+  WorkPhaseEvidenceMap,
+  WorkRisk,
+  WorkKind,
+  DispatchState,
+  EvidenceState,
+  CompletionOutcome,
+  ReadOnlyReviewEvidence,
+  WorkSemanticAcceptanceEvidence,
+  ReadOnlyReviewCompletionReceipt,
+  LocalEffectCompletionReceipt,
+  RemoteEffectCompletionReceipt,
+  DirectEditWorkCompletionReceipt,
+  WorkCompletionReceipt,
+  WorkReconciliationMethod,
+  WorkReconciliationOutcome,
+  VerificationOutcome,
+  WorkContractConstraints,
+  WorkContractDriverPolicy,
+  WorktreePolicy,
+  EvidencePolicy,
+  ApprovalPolicy,
+  RecoveryPolicy,
+  VerificationRecord,
+  WorkReconciliationRecord,
+  WorkContract,
+  SubmittedWorkOperation,
+  WorkContractStore,
+} from '../../../../packages/kernel/work/domain/types';
 export const HANDOFF_CREATION_REASONS = [
   'policy_approval_required',
   'ambiguous_outcome',
@@ -296,25 +146,6 @@ export const HANDOFF_CREATION_REASONS = [
 ] as const;
 export type HandoffCreationReason = (typeof HANDOFF_CREATION_REASONS)[number];
 
-export interface EvidenceRef {
-  evidenceId?: string;
-  artifactId?: string;
-  title: string;
-  summary?: string;
-  detailLevel?: FacadeDetailLevel;
-}
-
-export interface SuggestedNextAction {
-  label: string;
-  tool: FacadeTool;
-  operation: string;
-  payload?: Record<string, unknown>;
-  risk: CapabilityRisk;
-  confidence?: 'low' | 'medium' | 'high';
-  reason?: string;
-  fallback?: string;
-}
-
 export interface FacadeResult<TData = Record<string, unknown>> {
   schemaVersion: 1;
   status: FacadeStatus;
@@ -386,263 +217,15 @@ export interface HandoffInboxStore {
   items: HandoffItem[];
 }
 
-export interface WorkContractConstraints {
-  maxChangedFiles?: number;
-  maxChangedLines?: number;
-  allowCommit?: boolean;
-  allowMerge?: boolean;
-  allowCleanup?: boolean;
-  allowDestructive?: boolean;
-  requireHandoffOnAmbiguity?: boolean;
-  /** Immutable execution-policy snapshot captured when work starts. */
-  accessMode?: AccessMode;
-  /** current is the stability-first default; isolated is opt-in or used for explicit parallelism. */
-  workspaceMode?: 'current' | 'isolated' | 'auto';
-  requireWorktree?: boolean;
-  /** Admission fence: repository mutation must not use the Direct Control/current-main lane. */
-  directMainProhibited?: boolean;
-  /** True when a change alters the agreed architecture direction rather than only implementation details. */
-  architectureStrategyChange?: boolean;
-  /** True when the proposed change weakens the thin-harness / high-performance execution policy. */
-  conflictsWithThinHarnessPolicy?: boolean;
-  /** True when the change alters the default routing or execution mode visible to users. */
-  changesDefaultExecutionStrategy?: boolean;
-  /** Repository-change delivery must publish the exact integrated revision before Work terminalization. */
-  remoteDeliveryRequired?: boolean;
-}
-
-export interface WorkContractDriverPolicy {
-  preferred: 'direct_edit' | 'isolated_worktree' | 'external_controller' | 'handoff_only';
-  allowWorker: boolean;
-  allowDirectEdit: boolean;
-}
-
-export interface WorktreePolicy {
-  required: boolean;
-  reason?: string;
-  ref?: string;
-}
-
-export interface EvidencePolicy {
-  defaultDetailLevel: FacadeDetailLevel;
-  allowRawOptIn: boolean;
-  maxEvidenceRefs: number;
-}
-
-export interface ApprovalPolicy {
-  required: boolean;
-  reasons: string[];
-  confirmed: boolean;
-}
-
-export interface RecoveryPolicy {
-  allowSelfHealing: boolean;
-  maxInfrastructureRetries: number;
-  handoffOnAmbiguity: boolean;
-}
-
-export interface VerificationRecord {
-  checkId: string;
-  outcome: VerificationOutcome;
-  summary: string;
-  recordedAt: string;
-  /** Exact checked revision. Absence denotes legacy/non-authoritative evidence. */
-  sourceRevision?: string;
-  /** Exact dirty-workspace content identity observed by the check. */
-  workspaceFingerprint?: string;
-  /** Hash of the check inputs that must match before this result can be reused. */
-  verificationInputFingerprint?: string;
-  /** Bounded identity of the command/configuration that produced the result. */
-  commandFingerprint?: string;
-  resultArtifactId?: string;
-  startedAt?: string;
-  completedAt?: string;
-  supersedes?: string;
-  staleReason?: string;
-  evidenceRef?: EvidenceRef;
-  receipt?: ProcessCheckReceiptEvidence;
-}
-
-/**
- * Durable human-reviewed reconciliation for a Work whose original finalization
- * facts cannot be recovered. It records an exception; it is not completion
- * evidence by itself.
- */
-export interface WorkReconciliationRecord {
-  schemaVersion: 1;
-  reconciliationId: string;
-  originalExpectedRevision: string;
-  observedTargetRevision: string;
-  baseRevision: string;
-  targetBranch: string;
-  reachable: boolean;
-  method: WorkReconciliationMethod;
-  comparedPaths: string[];
-  reviewer: string;
-  reviewedAt: string;
-  unrecoverableStages: string[];
-  cleanupOwnershipProof: string;
-  rationale: string;
-  outcome: WorkReconciliationOutcome;
-}
-
-export interface WorkContract {
-  schemaVersion: 1 | 2;
-  workId: string;
-  repoId: string;
-  /** Execution identity snapshot. Optional only for legacy records. */
-  checkoutId?: string;
-  principalId?: string;
-  controllerInstanceId?: string;
-  baseRevision?: string;
-  workspaceFingerprint?: string;
-  routeDecisionFingerprint?: string;
-  routeDecision?: RouteDecision;
-  mode: ExecutionMode;
-  objective: string;
-  acceptanceCriteria: string[];
-  constraints: WorkContractConstraints;
-  /** Risk is immutable contract input and is projected to legacy Task reads. */
-  risk: WorkRisk;
-  /** Technical phase; Requirement owns the user lifecycle. */
-  phase: WorkPhase;
-  /** Work-owned phase checkpoints. Task/Run/Process records may contribute evidence but cannot write this map directly. */
-  phaseEvidence: WorkPhaseEvidenceMap;
-  /** Explicit v2 execution semantics. `status` is retained for compatibility. */
-  workKind: WorkKind;
-  /** Primary is an objective-level business execution lane; execution_child is a resumable low-level operation handle owned by a primary Work or standalone caller. */
-  lifecycleRole?: 'primary' | 'execution_child';
-  /** Optional objective-level parent when this Work is only an execution child. */
-  parentWorkId?: string;
-  dispatchState: DispatchState;
-  evidenceState: EvidenceState;
-  completionOutcome?: CompletionOutcome;
-  status: WorkContractStatus;
-  createdAt: string;
-  updatedAt: string;
-  /** @deprecated Prefer Requirement/Plan/Work links; kept for compatibility reads only. */
-  issueId?: string;
-  taskId?: string;
-  /** Stable Requirement authority that this Work may complete. */
-  requirementId?: string;
-  /** Work-owned completion receipt. Legacy Task receipts are projections only. */
-  completionReceipt?: WorkCompletionReceipt;
-  /** Provenance for complex work dispatched from a durable PlanContract step. */
-  planId?: string;
-  planStepId?: string;
-  planSourceRevision?: string;
-  scopeSummary?: string;
-  /**
-   * Discovery evidence, never an authorization boundary. Initial guesses,
-   * inspected paths, and observed changes remain distinct so early retrieval
-   * cannot masquerade as complete implementation scope.
-   */
-  scopeEvidence?: {
-    initialLikelyPaths: string[];
-    inspectedPaths: string[];
-    actualChangedPaths: string[];
-    recordedAt: string;
-  };
-  /** Source-bound semantic findings/scope for first-class recoverable read-only review Work. */
-  readOnlyReviewEvidence?: ReadOnlyReviewEvidence;
-  /** Explicit Controller-reviewed acceptance bindings. Mechanical evidence attribution alone never writes this field. */
-  semanticAcceptanceEvidence?: WorkSemanticAcceptanceEvidence[];
-  /** Explicit policy fence. This is not semantic completeness evidence. */
-  allowedPaths: string[];
-  forbiddenPaths: string[];
-  checks: string[];
-  driver: WorkContractDriverPolicy;
-  worktreePolicy: WorktreePolicy;
-  evidencePolicy: EvidencePolicy;
-  approvalPolicy: ApprovalPolicy;
-  recoveryPolicy: RecoveryPolicy;
-  requestedBy: 'chatgpt' | 'user' | 'system' | 'scheduler';
-  evidenceRefs: EvidenceRef[];
-  handoffRefs: string[];
-  suggestedNextActions: SuggestedNextAction[];
-  policyDecisions: PolicyDecision[];
-  checkRefs: VerificationRecord[];
-  /** Reviewed historical/manual integration exceptions, retained for audit. */
-  reconciliations: WorkReconciliationRecord[];
-  continuationPrompt?: string;
-  worktreeRef?: string;
-  workerRef?: string;
-  requestId?: string;
-  /** Typed execution metadata; it does not imply ExecutionJob creation. */
-  submittedOperation?: SubmittedWorkOperation;
-}
-
-/** Typed execution metadata retained on execution-child WorkContracts. */
-export interface SubmittedWorkOperation {
-  name: string;
-  semanticKey: string;
-  argumentHash: string;
-  mode: 'readonly' | 'mutating' | 'remote_write' | 'destructive';
-  idempotent: boolean;
-  replayable: boolean;
-  resourceClaims: Array<{
-    resourceKey: string;
-    mode: string;
-    quantity?: number;
-  }>;
-}
-
-export interface WorkContractStore {
-  schemaVersion: 1 | 2;
-  updatedAt: string;
-  contracts: WorkContract[];
-}
-
-export type ControllerType = 'chatgpt' | 'codex' | 'grok' | 'claude' | 'human';
-
-export interface ControllerSession {
-  schemaVersion: 1;
-  workId: string;
-  controllerId: string;
-  controllerType: ControllerType;
-  sessionId: string;
-  /** Authenticated authority that owned the claim; legacy records may omit it. */
-  principalId?: string;
-  /** Controller process/epoch that admitted the transport session. */
-  controllerInstanceId?: string;
-  /** Monotonic ownership fence. It changes only when ownership moves. */
-  claimGeneration?: number;
-  claimedAt: string;
-  leaseExpiresAt: string;
-}
-
-export interface ControllerSessionStore {
-  schemaVersion: 1;
-  updatedAt: string;
-  sessions: ControllerSession[];
-}
-
-export const PLAN_CONTRACT_STATUSES = [
-  'draft',
-  'inspecting',
-  'reviewing',
-  'approved',
-  'executing',
-  'replanning',
-  'verifying',
-  'ready_to_finalize',
-  'finalized',
-  'superseded',
-  'cancelled',
-  'invalidated_by_drift',
-] as const;
-export type PlanContractStatus = (typeof PLAN_CONTRACT_STATUSES)[number];
-
-export const TERMINAL_PLAN_CONTRACT_STATUSES: readonly PlanContractStatus[] = [
-  'finalized',
-  'superseded',
-  'cancelled',
-  'invalidated_by_drift',
-];
-
-export const PLAN_STEP_STATUSES = ['pending', 'ready', 'executing', 'validating', 'completed'] as const;
-export type PlanStepStatus = (typeof PLAN_STEP_STATUSES)[number];
-
+// Kernel V2: Controller session contracts are owned by packages/kernel/controller/domain.
+export type {
+  ControllerType,
+  ControllerSession,
+  ControllerSessionStore,
+  ControllerBinding,
+  ControllerLease,
+  ControllerRoundContext,
+} from '../../../../packages/kernel/controller/domain/types';
 export interface PlanStep {
   id: string;
   objective: string;
@@ -662,9 +245,86 @@ export interface PlanStep {
  * A durable pre-execution decision record. WorkContract remains the unit that
  * owns dispatch, workspace, worker, and verification lifecycle.
  */
+export const PLAN_OBLIGATION_DISPOSITIONS = ['keep', 'change', 'defer', 'drop'] as const;
+export type PlanObligationDispositionKind = (typeof PLAN_OBLIGATION_DISPOSITIONS)[number];
+
+export interface PlanObligationDisposition {
+  predecessorPlanId: string;
+  obligationId: string;
+  disposition: PlanObligationDispositionKind;
+  /** Successor locations such as step:<id>, acceptance:<id>:<index>, resolved_decision:<index>. */
+  successorRefs: string[];
+  /** Required for CHANGE/DEFER/DROP. KEEP may omit it. */
+  rationale?: string;
+}
+
+/**
+ * Immutable provenance for one predecessor delivery that may be reused by a
+ * successor Plan after approval. The Work itself remains historical and bound
+ * to the predecessor Plan; this record never transfers execution authority.
+ */
+export interface PlanStepDeliveryCarry {
+  predecessorPlanId: string;
+  predecessorStepId: string;
+  successorStepId: string;
+  workId: string;
+  completionReceiptId: string;
+  deliveredSourceRevision: string;
+  recordedAt: string;
+}
+
+/** Mutable only until approval. A stable Plan may stage at most one next revision;
+ * the currently committed Plan fields remain authoritative until this draft is approved. */
+export interface PlanRevisionDraft {
+  revision: number;
+  requestedRevisionLabel?: string;
+  sourceRevision: string;
+  goal: string;
+  nonGoals: string[];
+  assumptions: string[];
+  resolvedDecisions: string[];
+  stopConditions: string[];
+  replanConditions: string[];
+  integrationStrategy?: string;
+  steps: PlanStep[];
+  obligationDispositions?: PlanObligationDisposition[];
+  deliveryCarries?: PlanStepDeliveryCarry[];
+  createdAt: string;
+  updatedAt: string;
+}
+
+/** Immutable audit snapshot of one committed Plan revision. Historical revisions
+ * never own active scope, Work, scheduling, or admission authority. */
+export interface PlanRevisionRecord {
+  schemaVersion: 1;
+  repoId: string;
+  planId: string;
+  revision: number;
+  requirementId?: string;
+  scopeKey: string;
+  sourceRevision: string;
+  goal: string;
+  nonGoals: string[];
+  assumptions: string[];
+  resolvedDecisions: string[];
+  stopConditions: string[];
+  replanConditions: string[];
+  integrationStrategy?: string;
+  status: PlanContractStatus;
+  steps: PlanStep[];
+  evidenceRefs: EvidenceRef[];
+  obligationDispositions?: PlanObligationDisposition[];
+  recordedAt: string;
+  reason?: string;
+  /** Compatibility label supplied by older successor-Plan clients. It is not a Plan identity. */
+  requestedRevisionLabel?: string;
+}
+
 export interface PlanContract {
   schemaVersion: 1;
   planId: string;
+  /** Current committed semantic revision. Legacy rows without this field normalize to revision 1. */
+  revision?: number;
   repoId: string;
   /** Stable Requirement owner. Legacy plans may omit this until portfolio migration. */
   requirementId?: string;
@@ -680,7 +340,17 @@ export interface PlanContract {
   status: PlanContractStatus;
   steps: PlanStep[];
   evidenceRefs: EvidenceRef[];
+  /** Historical predecessor Plans explicitly replaced by this Plan. */
+  supersedes?: string[];
   supersededBy?: string;
+  /** Bounded durable reason for the supersession edge. */
+  supersessionReason?: string;
+  /** Explicit reconciliation of unresolved predecessor obligations. */
+  obligationDispositions?: PlanObligationDisposition[];
+  /** Trusted, bounded delivery provenance derived only during canonical successor admission. */
+  deliveryCarries?: PlanStepDeliveryCarry[];
+  /** At most one staged next revision. It is not another active Plan authority. */
+  pendingRevision?: PlanRevisionDraft;
   createdAt: string;
   updatedAt: string;
 }
@@ -704,6 +374,8 @@ export interface CapabilityDescriptor {
   exposedVia: CapabilityExecutionSurface;
   schemaExposure: CapabilitySchemaExposure;
   summary: string;
+  /** Provider-declared semantic capabilities implemented by this executable action. */
+  semanticCapabilities?: string[];
 }
 
 export interface CapabilityGroupSummary {
@@ -717,16 +389,6 @@ export interface CapabilityGroupSummary {
   schemaExposures: CapabilitySchemaExposure[];
 }
 
-export interface PolicyDecision {
-  decision: PolicyDecisionKind;
-  reason: string;
-  capabilityId?: string;
-  approvalRequestId?: string;
-  requiredConfirmationText?: string;
-  warnings: string[];
-  suggestedNextActions: SuggestedNextAction[];
-}
-
 export interface ExecutionModeSelectionInput {
   objective?: string;
   expectedFiles?: number;
@@ -757,6 +419,8 @@ export interface ExecutionModeSelectionInput {
   secretAccess?: boolean;
   mutation?: boolean;
   risk?: CapabilityRisk;
+  /** Advisory Context Plane routing hints. Explicit request fields still win. */
+  contextRouteHints?: RouteContextHints;
   /** Migration/testing escape hatch: adapters must return this exact policy decision. */
   routePolicyInput?: RoutePolicyInput;
 }
@@ -771,20 +435,12 @@ export interface ExecutionModeSelection {
   routeDecision: RouteDecision;
 }
 
-export function isTerminalHandoffStatus(status: HandoffStatus): boolean {
-  return TERMINAL_HANDOFF_STATUSES.includes(status);
-}
-
-export function isTerminalWorkContractStatus(status: WorkContractStatus): boolean {
-  return TERMINAL_WORK_CONTRACT_STATUSES.includes(status);
-}
-
 /** @deprecated Compatibility adapter. Route Policy is the sole routing authority. */
 export function selectExecutionMode(input: ExecutionModeSelectionInput): ExecutionModeSelection {
   const missingContractFields: string[] = [];
   if (!input.scopeClear) missingContractFields.push('scopeSummary', 'acceptanceCriteria', 'allowedPaths');
   if (input.objective !== undefined && input.objective.trim().length === 0) missingContractFields.push('objective');
-  const routeDecision = decideRoute(input.routePolicyInput ?? {
+  const baseRoutePolicyInput: RoutePolicyInput = input.routePolicyInput ?? {
     intent: {
       objective: input.objective ?? (input.scopeClear ? 'bounded repository work' : ''),
       scopeClear: input.scopeClear,
@@ -822,7 +478,8 @@ export function selectExecutionMode(input: ExecutionModeSelectionInput): Executi
     recovery: {
       required: input.requiresRecovery,
     },
-  });
+  };
+  const routeDecision = decideRoute(applyRouteContextHints(baseRoutePolicyInput, input.contextRouteHints));
   return {
     mode: routeDecision.executionMode,
     reason: routeDecision.reasons.map((reason) => reason.message).join(' '),