@moretea-labs/forge 1.8.0 → 1.8.1

package/supervisor/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true
+  },
+  "include": ["./**/*.ts"],
+  "exclude": []
+}

package/supervisor/types.ts

@@ -0,0 +1,255 @@
+export type WorkflowSupervisorAction = 'CONTINUE' | 'DONE' | 'NEEDS_USER';
+export type WorkflowSupervisorState = 'running' | 'done' | 'needs_user';
+export type WorkflowSupervisorTerminalState = 'DONE' | 'NEEDS_USER' | 'STOPPED';
+/** Machine receipt attached to Forge MCP calls made by an autonomous ChatGPT turn. */
+export type WorkflowSupervisorAutomationStatus = 'working' | 'continue' | 'done' | 'needs_user';
+export type WorkflowEffectKind = 'enrollment' | 'continuation' | 'correction' | 'recovery';
+export type WorkflowEffectOutcome = 'applied' | 'not_applied' | 'unknown';
+
+/** Minimal machine-readable context carried into one autonomous provider turn. */
+export interface WorkflowSupervisorTurnEnvelope {
+  schema_version: 2;
+  identity: {
+    task_id: string;
+    effect_id: string;
+    kind: WorkflowEffectKind;
+  };
+  /** Semantic outcome to pursue. It is context, not an execution-plan DSL. */
+  goal: {
+    role: 'outcome';
+    objective: string;
+  };
+  /** Prior-turn continuity is evidence for orientation, never an execution constraint. */
+  continuity?: {
+    role: 'advisory';
+    summary: string;
+  };
+  repository?: {
+    repo_id: string;
+    checkout_id?: string;
+  };
+  cognition?: {
+    role: 'advisory';
+    projection: string;
+  };
+  automation: {
+    automation_task_id: string;
+    automation_type: 'autonomous_continuation';
+    intermediate_status: 'working';
+    final_statuses: ['continue', 'done', 'needs_user'];
+  };
+}
+
+export interface WorkflowSupervisorProposal {
+  action: WorkflowSupervisorAction;
+  sourceEffectId: string;
+  checkpoint: string;
+  reason: string;
+  evidence: string[];
+  /** Required by newly-rendered prompts; optional only for already-reserved legacy effects. */
+  conversationId?: string;
+  /** Stable Supervisor task identity, distinct from lower-layer Work authority. */
+  taskId?: string;
+  /** Redundant with action by design so a response carries an explicit machine state. */
+  supervisorState?: WorkflowSupervisorState;
+  /** Exact durable lower-layer relay scope such as requirement:<id> or goal:<id>. */
+  activeScope?: string;
+}
+
+export interface WorkflowSupervisorTaskInput {
+  taskId: string;
+  conversationId: string;
+  conversationUrl: string;
+  objective: string;
+  completionContract: Record<string, unknown>;
+  continuationPolicy: Record<string, unknown>;
+  userBlockerPolicy: Record<string, unknown>;
+}
+
+export interface WorkflowSupervisorTask extends WorkflowSupervisorTaskInput {
+  createdAt: string;
+}
+
+export interface WorkflowSupervisorEffect {
+  effectId: string;
+  taskId: string;
+  kind: WorkflowEffectKind;
+  sourceCompletionFingerprint?: string;
+  prompt: string;
+  createdAt: string;
+}
+
+export interface WorkflowSupervisorCompletion {
+  completionFingerprint: string;
+  taskId: string;
+  sourceEffectId: string;
+  action: WorkflowSupervisorAction;
+  responseSha256: string;
+  controlBlockSha256: string;
+  proposal: WorkflowSupervisorProposal;
+  committedAt: string;
+}
+
+/** Read-only proof derived from the existing effect/completion ledger. */
+export interface WorkflowSupervisorContinuationProof {
+  taskId: string;
+  conversationId: string;
+  activeReleaseId: string;
+  actions: ['CONTINUE', 'CONTINUE'];
+  completionFingerprints: [string, string];
+  sourceEffectIds: [string, string];
+  runtimeInstanceIds: string[];
+  firstCommittedAt: string;
+  lastCommittedAt: string;
+}
+
+/** Ephemeral operational projection for the single native Supervisor effect consumer. */
+export interface WorkflowSupervisorConsumerStatus {
+  enabled: boolean;
+  running: boolean;
+  observedAt: string;
+  lastTickStartedAt?: string;
+  lastTickCompletedAt?: string;
+  lastCommandAttemptAt?: string;
+  nextAttemptAt?: string;
+  transportFailureStreak: number;
+  providerBackpressureMs: number;
+  stalled: boolean;
+  dueCommand?: {
+    taskId: string;
+    conversationId: string;
+    effectId: string;
+    mode: 'send' | 'reconcile';
+    kind: WorkflowEffectKind;
+    createdAt?: string;
+    ageMs?: number;
+  };
+  lastFailure?: {
+    code: string;
+    observedAt: string;
+    taskId?: string;
+    effectId?: string;
+  };
+}
+
+export interface WorkflowContractValidation {
+  valid: boolean;
+  reason: string;
+  evidence?: string[];
+}
+
+/**
+ * Derived, read-only classification of a non-terminal task's causal position.
+ * A mechanically exhausted effect used to make its task silently leave the
+ * delivery queue with no durable projection; this makes that state visible and
+ * names the exact operator action that can move the task forward.
+ */
+export type WorkflowSupervisorTaskStall =
+  | { state: 'terminal' }
+  | { state: 'deliverable'; effectId: string; mode: 'send' | 'reconcile'; generation: number }
+  | { state: 'spaced'; effectId?: string; reason: 'retry_spacing' | 'unknown_observation_spacing' | 'awaiting_completion_receipt' | 'pre_send_infrastructure_blocked' }
+  | { state: 'retryable'; effectId: string; generations: number; maxGenerations: number }
+  | { state: 'provider_resume_exhausted'; effectId: string }
+  | { state: 'inert' };
+
+export interface WorkflowSupervisorValidators {
+  completionContract(task: WorkflowSupervisorTask, proposal: WorkflowSupervisorProposal): Promise<WorkflowContractValidation>;
+  userBlockerPolicy(task: WorkflowSupervisorTask, proposal: WorkflowSupervisorProposal): Promise<WorkflowContractValidation>;
+}
+export interface WorkflowSupervisorLifecycleHooks {
+  /** Resolve the current canonical Work objective at prompt generation time. */
+  canonicalObjectiveForTask?(task: WorkflowSupervisorTask): string | undefined;
+  /** Bounded cognition only; never carries lower-layer authority or lifecycle state. */
+  advisoryCognitionForTask?(task: WorkflowSupervisorTask): string | undefined;
+  /** Derived project identity used only for browser discovery; never a lifecycle authority. */
+  projectScopeForTask?(task: WorkflowSupervisorTask): WorkflowSupervisorProjectScope | undefined;
+  /** Build the one bounded enrollment task for a newly discovered project conversation. */
+  discoveredConversationTask?(conversation: WorkflowSupervisorDiscoveredConversation, scope: WorkflowSupervisorProjectScope): WorkflowSupervisorTaskInput | undefined;
+  /** Admission for a new send only. Never suppress observation of an already-started effect. */
+  browserTaskActive?(task: WorkflowSupervisorTask): boolean;
+  /** Mechanical provenance attached to outbound effect dispatch evidence. */
+  effectDispatchEvidence?(input: { task: WorkflowSupervisorTask; effectId: string }): Record<string, unknown>;
+  /**
+   * Mechanical projection of the canonical Work the turn is meant to advance.
+   * Comparison of the value captured at dispatch with the value observed at
+   * receipt is the only structural proof that a provider turn changed anything.
+   * Absent means the lower layer exposes no such signal, which is never treated
+   * as progress or as its absence.
+   */
+  workProgressFingerprint?(task: WorkflowSupervisorTask): string | undefined;
+  /** Existing lower-layer evidence that this exact reserved effect may already have been dispatched outside Supervisor. */
+  inheritedEffectDispatch?(
+    task: WorkflowSupervisorTask,
+    effect: WorkflowSupervisorEffect,
+  ): { generation: number; dispatchId: string; evidence: Record<string, unknown> } | undefined;
+  /** Idempotent: browser delivery observation may replay the same applied effect. */
+  effectApplied?(
+    task: WorkflowSupervisorTask,
+    effect: WorkflowSupervisorEffect,
+    observation: { observationId: string; evidence?: Record<string, unknown> },
+  ): void;
+  /** Atomically project a newly-created Computer conversation into Work binding authority. */
+  bootstrapConversationBound?(
+    task: WorkflowSupervisorTask,
+    context?: { migratedFromConversationId?: string; migrationRequestId?: string },
+  ): void;
+}
+
+export interface WorkflowAssistantObservation {
+  taskId: string;
+  conversationId: string;
+  responseText: string;
+}
+
+export interface WorkflowAssistantObservationResult {
+  action: WorkflowSupervisorAction;
+  completionFingerprint: string;
+  terminal: boolean;
+  successorEffect?: WorkflowSupervisorEffect;
+  validation?: WorkflowContractValidation;
+  deduplicated: boolean;
+}
+
+export interface WorkflowSupervisorBrowserTask {
+  taskId: string;
+  conversationId: string;
+  conversationUrl: string;
+}
+
+export interface WorkflowSupervisorDiscoveredConversation {
+  conversationId: string;
+  canonicalUrl: string;
+  title?: string;
+  projectTitle?: string;
+  projectUrl?: string;
+}
+
+export interface WorkflowSupervisorDiscoverySnapshot {
+  observedAt: string;
+  conversations: WorkflowSupervisorDiscoveredConversation[];
+}
+
+export interface WorkflowSupervisorProjectScope {
+  title: string;
+  /** Additional stable names used by the external Project surface. */
+  aliases?: string[];
+  repoId?: string;
+  controllerHome?: string;
+}
+
+export interface WorkflowSupervisorBrowserCommand {
+  mode: 'send' | 'reconcile';
+  effectId: string;
+  kind: WorkflowEffectKind;
+  prompt: string;
+  dispatchGeneration: number;
+  conversationId: string;
+  conversationUrl: string;
+}
+
+export interface WorkflowSupervisorBrowserPollResult {
+  authorized: true;
+  task: WorkflowSupervisorBrowserTask;
+  terminal?: WorkflowSupervisorTerminalState;
+  command?: WorkflowSupervisorBrowserCommand;
+}

package/adapters/chatgpt/controller-host.ts

@@ -1,119 +0,0 @@
-import { createHash } from 'crypto';
-import {
-  getControllerRoundRelay,
-  type ControllerBinding,
-  type ControllerHost,
-  type ControllerRoundContext,
-} from '../../packages/kernel/controller/api/index';
-import { runWorkChatgptContinuation } from '../../src/runtime/control-plane/launcher/chatgpt-work-continuation';
-import { renderChatgptControllerRoundPrompt } from '../../src/runtime/root/controller-round-composition';
-import { getChatgptControllerBindingPayload } from './controller-binding-store';
-import { getChatgptWorkConversationBinding } from './work-conversation-binding-store';
-import { chatgptProviderDispatchReceiptId, classifyChatgptProviderFailure } from './provider-delivery';
-import { createHandoffItem, getHandoffItem } from '../../src/runtime/control-plane/facade/handoff-inbox-store';
-
-
-function providerUserActionHandoffId(repoId: string, workId: string, relayScopeId: string, authorityId: string): string {
-  const digest = createHash('sha256').update(`${repoId}\n${workId}\n${relayScopeId}\n${authorityId}`).digest('hex').slice(0, 20);
-  return `hnd-chatgpt-provider-auth-${digest}`;
-}
-
-function ensureChatgptProviderUserActionHandoff(
-  options: { controllerHome: string; repoId: string },
-  roundContext: ControllerRoundContext,
-  code: string,
-  message: string,
-): string {
-  const id = providerUserActionHandoffId(options.repoId, roundContext.workId, roundContext.relayScopeId, roundContext.authorityId);
-  const existing = getHandoffItem(options, id);
-  if (existing && existing.status === 'pending') return existing.id;
-  if (existing) return existing.id;
-  return createHandoffItem(options, {
-    id,
-    repoId: options.repoId,
-    workId: roundContext.workId,
-    title: 'ChatGPT provider authorization required',
-    severity: 'needs_review',
-    reason: message,
-    creationReason: 'missing_authorization',
-    summary: `Provider delivery is blocked until the user completes ChatGPT authentication or permission: ${code}`,
-    currentState: {
-      repoId: options.repoId,
-      workId: roundContext.workId,
-      statusSummary: 'ControllerRound is waiting for an explicit provider authentication/permission action.',
-      blockedBy: [code],
-      nextSafeAction: 'Complete the provider login/permission action, then resolve this Handoff to trigger a fresh continuation occurrence.',
-    },
-    evidenceRefs: [],
-    blockingDecision: 'Complete the required ChatGPT login or permission action.',
-    recommendedDecision: 'Complete provider authentication/permission and resume the same durable Work.',
-    recommendedPrompt: `Resume exact Work ${roundContext.workId} after provider authentication is complete.`,
-    suggestedNextActions: [],
-  }).id;
-}
-
-export function createChatgptControllerHost(options: {
-  controllerHome: string;
-  repoId: string;
-  repoRoot: string;
-}): ControllerHost {
-  return {
-    async resume(binding: ControllerBinding, roundContext: ControllerRoundContext) {
-      if (binding.hostKind !== 'chatgpt') return { accepted: false, reason: `CONTROLLER_HOST_KIND_MISMATCH:${binding.hostKind}` };
-      const payload = getChatgptControllerBindingPayload(options, binding.adapterRef);
-      if (!payload || payload.bindingId !== binding.bindingId || payload.workId !== roundContext.workId) {
-        return { accepted: false, reason: `CHATGPT_CONTROLLER_BINDING_NOT_FOUND:${binding.bindingId}` };
-      }
-      const relayStore = { controllerHome: options.controllerHome, repoId: options.repoId };
-      const relay = getControllerRoundRelay(relayStore, roundContext.workId);
-      if (!relay || relay.relayScopeId !== roundContext.relayScopeId || relay.authorityId !== roundContext.authorityId) {
-        return { accepted: false, reason: `CONTROLLER_ROUND_CONTEXT_STALE:${roundContext.workId}` };
-      }
-      const durableConversation = getChatgptWorkConversationBinding(relayStore, roundContext.workId);
-      const prompt = [
-        renderChatgptControllerRoundPrompt(relayStore, relay, { exactOriginWork: roundContext.exactOriginWork === true }),
-        roundContext.continuationHint?.trim() ? `Continuation hint: ${roundContext.continuationHint.trim()}` : '',
-      ].filter(Boolean).join('\n\n');
-      const result = await runWorkChatgptContinuation({
-        controllerHome: options.controllerHome,
-        repoId: options.repoId,
-        repoRoot: options.repoRoot,
-        workId: roundContext.workId,
-        prompt,
-        controllerAuthorityId: roundContext.authorityId,
-        relayScopeId: roundContext.relayScopeId,
-        title: payload.title,
-        browserSessionId: durableConversation?.latestBrowserSessionId ?? payload.browserSessionId,
-        conversationUrl: durableConversation?.conversationUrl ?? payload.conversationUrl,
-        model: payload.model ?? 'gpt-5.6',
-        reasoning: payload.reasoning ?? 'high',
-        tabPolicy: payload.tabPolicy ?? 'auto',
-        timeoutMs: payload.timeoutMs,
-        originSurface: 'schedule',
-      });
-      if (result.status === 'failed') {
-        const code = result.error?.code ?? 'CHATGPT_WORK_CONTINUATION_FAILED';
-        const message = result.error?.message ?? code;
-        const disposition = classifyChatgptProviderFailure(code, message);
-        if (disposition === 'outcome_unknown') {
-          throw new Error(`CONTROLLER_HOST_PROVIDER_DISPATCH_OUTCOME_UNKNOWN:${code}:${message}`);
-        }
-        if (disposition === 'wait_for_user') {
-          const handoffId = ensureChatgptProviderUserActionHandoff(options, roundContext, code, message);
-          return { accepted: false, waitForUser: true, handoffId, reason: message };
-        }
-        return { accepted: false, reason: message };
-      }
-      return {
-        accepted: true,
-        dispatchId: chatgptProviderDispatchReceiptId({
-          repoId: options.repoId,
-          workId: roundContext.workId,
-          relayScopeId: roundContext.relayScopeId,
-          controllerAuthorityId: roundContext.authorityId,
-          provider: result.provider,
-        }),
-      };
-    },
-  };
-}

package/adapters/mcp/controller-round-compatibility.ts

@@ -1,184 +0,0 @@
-import {
-  CONTROLLER_ROUND_DISPOSITIONS,
-  type ControllerRoundDisposition,
-} from '../../packages/kernel/controller/api/index';
-
-const CONTROLLER_DISPOSITION_COMPATIBILITY_PREFIX = 'controller.disposition:';
-const CONTROLLER_ROUND_COMPATIBILITY_PREFIX = 'controller.round:';
-export const CONTROLLER_ROUND_COMPATIBILITY_OPERATIONS = [
-  'controller_claim',
-  'plan_accept_step',
-  'continue',
-  'verify',
-  'review',
-  'finalize',
-  'stop',
-  'controller_release',
-] as const;
-export type ControllerRoundCompatibilityOperation = (typeof CONTROLLER_ROUND_COMPATIBILITY_OPERATIONS)[number];
-export const CONTROLLER_ROUND_REVIEW_DECISIONS = ['approved', 'changes_required', 'blocked'] as const;
-export type ControllerRoundReviewDecision = (typeof CONTROLLER_ROUND_REVIEW_DECISIONS)[number];
-
-export function parseControllerDispositionCompatibilityCapability(
-  operation: string,
-  capabilityId: unknown,
-): { disposition: ControllerRoundDisposition; relayScopeId: string; authorityId?: string } | undefined {
-  if (operation !== 'repair' || typeof capabilityId !== 'string') return undefined;
-  const normalized = capabilityId.trim();
-  if (!normalized.startsWith(CONTROLLER_DISPOSITION_COMPATIBILITY_PREFIX)) return undefined;
-  const payload = normalized.slice(CONTROLLER_DISPOSITION_COMPATIBILITY_PREFIX.length);
-  const separator = payload.indexOf(':');
-  if (separator <= 0) throw new Error('CONTROLLER_RELAY_DISPOSITION_COMPATIBILITY_INVALID');
-  const disposition = payload.slice(0, separator) as ControllerRoundDisposition;
-  const remainder = payload.slice(separator + 1).trim();
-  let authorityId: string | undefined;
-  let relayScopeId = remainder;
-  if (remainder.startsWith('cra_')) {
-    const authoritySeparator = remainder.indexOf(':');
-    if (authoritySeparator <= 0) throw new Error('CONTROLLER_RELAY_DISPOSITION_COMPATIBILITY_INVALID');
-    authorityId = remainder.slice(0, authoritySeparator).trim();
-    relayScopeId = remainder.slice(authoritySeparator + 1).trim();
-    if (!/^cra_[0-9a-f]{32}$/i.test(authorityId)) throw new Error('CONTROLLER_RELAY_DISPOSITION_COMPATIBILITY_INVALID');
-  }
-  if (!CONTROLLER_ROUND_DISPOSITIONS.includes(disposition) || !relayScopeId) {
-    throw new Error('CONTROLLER_RELAY_DISPOSITION_COMPATIBILITY_INVALID');
-  }
-  return { disposition, relayScopeId, ...(authorityId ? { authorityId } : {}) };
-}
-
-export function parseControllerRoundCompatibilityCapability(
-  operation: string,
-  capabilityId: unknown,
-): { operation: ControllerRoundCompatibilityOperation; authorityId: string; relayScopeId: string; reviewDecision?: ControllerRoundReviewDecision } | undefined {
-  if (operation !== 'repair' || typeof capabilityId !== 'string') return undefined;
-  const normalized = capabilityId.trim();
-  if (!normalized.startsWith(CONTROLLER_ROUND_COMPATIBILITY_PREFIX)) return undefined;
-  const payload = normalized.slice(CONTROLLER_ROUND_COMPATIBILITY_PREFIX.length);
-  const operationSeparator = payload.indexOf(':');
-  if (operationSeparator <= 0) throw new Error('CONTROLLER_ROUND_COMPATIBILITY_INVALID');
-  const canonicalOperation = payload.slice(0, operationSeparator) as ControllerRoundCompatibilityOperation;
-  if (!CONTROLLER_ROUND_COMPATIBILITY_OPERATIONS.includes(canonicalOperation)) {
-    throw new Error('CONTROLLER_ROUND_COMPATIBILITY_INVALID');
-  }
-
-  let cursor = operationSeparator + 1;
-  let reviewDecision: ControllerRoundReviewDecision | undefined;
-  if (canonicalOperation === 'review') {
-    const decisionSeparator = payload.indexOf(':', cursor);
-    if (decisionSeparator <= cursor) throw new Error('CONTROLLER_ROUND_COMPATIBILITY_INVALID');
-    const decision = payload.slice(cursor, decisionSeparator).trim() as ControllerRoundReviewDecision;
-    if (!CONTROLLER_ROUND_REVIEW_DECISIONS.includes(decision)) throw new Error('CONTROLLER_ROUND_COMPATIBILITY_INVALID');
-    reviewDecision = decision;
-    cursor = decisionSeparator + 1;
-  }
-
-  const authoritySeparator = payload.indexOf(':', cursor);
-  if (authoritySeparator <= cursor) throw new Error('CONTROLLER_ROUND_COMPATIBILITY_INVALID');
-  const authorityId = payload.slice(cursor, authoritySeparator).trim();
-  const relayScopeId = payload.slice(authoritySeparator + 1).trim();
-  if (!/^cra_[0-9a-f]{32}$/i.test(authorityId) || !relayScopeId) {
-    throw new Error('CONTROLLER_ROUND_COMPATIBILITY_INVALID');
-  }
-  return { operation: canonicalOperation, authorityId, relayScopeId, ...(reviewDecision ? { reviewDecision } : {}) };
-}
-
-
-const PLAN_OBLIGATION_COMPATIBILITY_PREFIX = 'plan.obligations.v1:';
-const PLAN_OBLIGATION_COMPATIBILITY_MAX_ENCODED_CHARS = 96_000;
-const PLAN_OBLIGATION_COMPATIBILITY_MAX_DECODED_BYTES = 64 * 1024;
-const PLAN_OBLIGATION_COMPATIBILITY_MAX_DISPOSITIONS = 512;
-const PLAN_OBLIGATION_COMPATIBILITY_MAX_SUCCESSOR_REFS = 32;
-
-export type PlanObligationCompatibilityDispositionKind = 'keep' | 'change' | 'defer' | 'drop';
-
-export interface PlanObligationCompatibilityDisposition {
-  predecessor_plan_id: string;
-  obligation_id: string;
-  disposition: PlanObligationCompatibilityDispositionKind;
-  successor_refs: string[];
-  rationale?: string;
-}
-
-function boundedCompatibilityText(value: unknown, maximum: number): string {
-  const normalized = typeof value === 'string' ? value.trim() : '';
-  if (!normalized || normalized.length > maximum) throw new Error('PLAN_OBLIGATION_COMPATIBILITY_INVALID');
-  return normalized;
-}
-
-/**
- * Encode only the field missing from older frozen rh_work schemas. This is a
- * transport compatibility envelope, never Plan state or semantic authority.
- */
-export function buildPlanObligationCompatibilityCapability(
-  dispositions: readonly PlanObligationCompatibilityDisposition[],
-): string {
-  if (dispositions.length > PLAN_OBLIGATION_COMPATIBILITY_MAX_DISPOSITIONS) {
-    throw new Error('PLAN_OBLIGATION_COMPATIBILITY_TOO_LARGE');
-  }
-  const payload = {
-    v: 1,
-    d: dispositions.map((entry) => ({
-      p: boundedCompatibilityText(entry.predecessor_plan_id, 256),
-      o: boundedCompatibilityText(entry.obligation_id, 512),
-      d: entry.disposition,
-      s: entry.successor_refs.map((ref) => boundedCompatibilityText(ref, 512)),
-      ...(entry.rationale?.trim() ? { r: boundedCompatibilityText(entry.rationale, 4_000) } : {}),
-    })),
-  };
-  for (const entry of payload.d) {
-    if (!['keep', 'change', 'defer', 'drop'].includes(entry.d) || entry.s.length > PLAN_OBLIGATION_COMPATIBILITY_MAX_SUCCESSOR_REFS) {
-      throw new Error('PLAN_OBLIGATION_COMPATIBILITY_INVALID');
-    }
-  }
-  const encoded = Buffer.from(JSON.stringify(payload), 'utf8').toString('base64url');
-  if (encoded.length > PLAN_OBLIGATION_COMPATIBILITY_MAX_ENCODED_CHARS) {
-    throw new Error('PLAN_OBLIGATION_COMPATIBILITY_TOO_LARGE');
-  }
-  return `${PLAN_OBLIGATION_COMPATIBILITY_PREFIX}${encoded}`;
-}
-
-export function parsePlanObligationCompatibilityCapability(
-  operation: string,
-  capabilityId: unknown,
-): PlanObligationCompatibilityDisposition[] | undefined {
-  if (operation !== 'plan_create' || typeof capabilityId !== 'string') return undefined;
-  const normalized = capabilityId.trim();
-  if (!normalized.startsWith(PLAN_OBLIGATION_COMPATIBILITY_PREFIX)) return undefined;
-  const encoded = normalized.slice(PLAN_OBLIGATION_COMPATIBILITY_PREFIX.length);
-  if (!encoded || encoded.length > PLAN_OBLIGATION_COMPATIBILITY_MAX_ENCODED_CHARS || !/^[A-Za-z0-9_-]+$/.test(encoded)) {
-    throw new Error('PLAN_OBLIGATION_COMPATIBILITY_INVALID');
-  }
-  let decoded: Buffer;
-  let parsed: unknown;
-  try {
-    decoded = Buffer.from(encoded, 'base64url');
-    if (decoded.byteLength > PLAN_OBLIGATION_COMPATIBILITY_MAX_DECODED_BYTES) throw new Error('too_large');
-    parsed = JSON.parse(decoded.toString('utf8'));
-  } catch (error) {
-    if (error instanceof Error && error.message === 'too_large') throw new Error('PLAN_OBLIGATION_COMPATIBILITY_TOO_LARGE');
-    throw new Error('PLAN_OBLIGATION_COMPATIBILITY_INVALID');
-  }
-  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('PLAN_OBLIGATION_COMPATIBILITY_INVALID');
-  const envelope = parsed as Record<string, unknown>;
-  if (envelope.v !== 1 || !Array.isArray(envelope.d) || envelope.d.length > PLAN_OBLIGATION_COMPATIBILITY_MAX_DISPOSITIONS) {
-    throw new Error('PLAN_OBLIGATION_COMPATIBILITY_INVALID');
-  }
-  return envelope.d.map((value) => {
-    if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('PLAN_OBLIGATION_COMPATIBILITY_INVALID');
-    const entry = value as Record<string, unknown>;
-    const disposition = boundedCompatibilityText(entry.d, 16) as PlanObligationCompatibilityDispositionKind;
-    const successorRefs = Array.isArray(entry.s) ? entry.s : [];
-    if (!['keep', 'change', 'defer', 'drop'].includes(disposition) || successorRefs.length > PLAN_OBLIGATION_COMPATIBILITY_MAX_SUCCESSOR_REFS) {
-      throw new Error('PLAN_OBLIGATION_COMPATIBILITY_INVALID');
-    }
-    return {
-      predecessor_plan_id: boundedCompatibilityText(entry.p, 256),
-      obligation_id: boundedCompatibilityText(entry.o, 512),
-      disposition,
-      successor_refs: successorRefs.map((ref) => boundedCompatibilityText(ref, 512)),
-      ...(typeof entry.r === 'string' && entry.r.trim()
-        ? { rationale: boundedCompatibilityText(entry.r, 4_000) }
-        : {}),
-    };
-  });
-}