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

package/src/alpha7/autonomy.ts

@@ -0,0 +1,449 @@
+import type {
+  DelegationGrant,
+  DelegationPolicyInput,
+  MilestonePlanInput,
+  MilestoneState,
+  SidecarEventRecord,
+} from '../contracts.js';
+import { STATE_SCHEMA_VERSION } from '../contracts.js';
+import { assertDelegationCanAuthorize, hashDelegationPolicy } from '../delegation.js';
+import { WorkflowError } from '../errors.js';
+import type { FileStateStore } from '../state/store.js';
+import { createEntityId, createUlid } from '../ulid.js';
+import { canonicalJsonStringify, sha256Hex } from '../alpha6/store-sidecars.js';
+
+const AUTONOMY_SIDECAR = 'autonomy-contract-events.jsonl';
+const MAX_AUTONOMY_MS = 72 * 60 * 60 * 1000;
+const AUTONOMY_TRANSITIONS = [
+  'milestone.execution_authorize',
+  'milestone.final_accept',
+  'project_memory.approve',
+  'task.execution_authorize',
+  'task.final_accept',
+] as const;
+
+export interface MilestoneAutonomyEvent extends SidecarEventRecord {
+  eventType: 'issued';
+  confirmationCodeBindingHash?: string;
+  issuedMilestoneStatus?: MilestoneState['status'];
+  projectId: string;
+  milestoneId: string;
+  milestoneRevision: number;
+  principal: string;
+  delegate: string;
+  issuedAt: string;
+  expiresAt: string;
+  semanticScopeHash: string;
+  delegationGrantId: string;
+  delegationPolicyHash: string;
+}
+
+export interface MilestoneAutonomyPreparation {
+  kind: 'milestone_autonomy_contract';
+  projectId: string;
+  milestoneId: string;
+  milestoneRevision: number;
+  principal: string;
+  delegate: string;
+  expiresAt: string;
+  semanticScopeHash: string;
+  delegationPolicy: DelegationPolicyInput;
+  delegationPolicyHash: string;
+  confirmationCodeBindingHash: string;
+  confirmationCode: string;
+}
+
+export interface ActiveMilestoneAutonomy {
+  contract: MilestoneAutonomyEvent;
+  grant: DelegationGrant;
+}
+
+export function milestoneSemanticScopeHash(milestone: Pick<
+  MilestoneState,
+  'id' | 'discoveryId' | 'baseBranch' | 'outcome' | 'successSignal' | 'acceptance' | 'checks'
+>): string {
+  return sha256Hex(canonicalJsonStringify({
+    version: 'milestone-autonomy-semantic-scope-v1',
+    milestoneId: milestone.id,
+    discoveryId: milestone.discoveryId,
+    baseBranch: milestone.baseBranch,
+    outcome: milestone.outcome,
+    successSignal: milestone.successSignal,
+    acceptance: milestone.acceptance,
+    checks: milestone.checks,
+  }));
+}
+
+function autonomyAuthoritySnapshot(store: FileStateStore, projectId: string, milestoneId: string): unknown {
+  const event = readMilestoneAutonomyEvents(store, projectId, milestoneId).at(-1);
+  if (!event) return null;
+  try {
+    const grant = store.readDelegation(projectId, event.delegationGrantId);
+    return { eventHash: event.eventHash, grant };
+  } catch (error) {
+    if (!(error instanceof WorkflowError) || error.code !== 'NOT_FOUND') throw error;
+    return { eventHash: event.eventHash, grant: null };
+  }
+}
+
+export function prepareMilestoneAutonomyContract(options: {
+  store: FileStateStore;
+  projectId: string;
+  milestone: MilestoneState;
+  principal: string;
+  delegate: string;
+  expiresAt: string;
+  now: Date;
+}): MilestoneAutonomyPreparation {
+  const { projectId, milestone, now } = options;
+  if (!['awaiting_execution_authorization', 'active'].includes(milestone.status) || !milestone.planHash) {
+    throw new WorkflowError(
+      'TRANSITION_BLOCKED',
+      'Milestone autonomy requires a complete Plan and an awaiting-authorization or active Milestone.',
+      { milestoneId: milestone.id, status: milestone.status },
+    );
+  }
+  const principal = options.principal.trim();
+  const delegate = options.delegate.trim();
+  if (!principal || principal.startsWith('agent:')) {
+    throw new WorkflowError('INVALID_ARGUMENT', 'Milestone autonomy principal must be an explicit human actor.');
+  }
+  if (!delegate.startsWith('agent:') || !delegate.slice(6).trim() || delegate === principal) {
+    throw new WorkflowError('INVALID_ARGUMENT', 'Milestone autonomy delegate must be a distinct agent actor.');
+  }
+  const expiry = new Date(options.expiresAt);
+  if (!Number.isFinite(expiry.getTime()) || expiry.getTime() <= now.getTime()) {
+    throw new WorkflowError('INVALID_ARGUMENT', 'Milestone autonomy expiresAt must be a future ISO-8601 timestamp.');
+  }
+  if (expiry.getTime() - now.getTime() > MAX_AUTONOMY_MS) {
+    throw new WorkflowError('INVALID_ARGUMENT', 'Milestone autonomy cannot exceed 72 hours.');
+  }
+  const expiresAt = expiry.toISOString();
+  const delegationPolicy: DelegationPolicyInput = {
+    principal,
+    delegate,
+    scope: { kind: 'milestone', id: milestone.id },
+    transitions: [...AUTONOMY_TRANSITIONS],
+    expiresAt,
+  };
+  const delegationPolicyHash = hashDelegationPolicy(projectId, delegationPolicy);
+  const semanticScopeHash = milestoneSemanticScopeHash(milestone);
+  const confirmationCodeBindingHash = sha256Hex(canonicalJsonStringify({
+    version: 'milestone-autonomy-contract-v2',
+    milestoneStatus: milestone.status,
+    priorAuthority: autonomyAuthoritySnapshot(options.store, projectId, milestone.id),
+    projectId,
+    milestoneId: milestone.id,
+    milestoneRevision: milestone.revision,
+    planHash: milestone.planHash,
+    semanticScopeHash,
+    delegationPolicyHash,
+  }));
+  return {
+    kind: 'milestone_autonomy_contract',
+    projectId,
+    milestoneId: milestone.id,
+    milestoneRevision: milestone.revision,
+    principal,
+    delegate,
+    expiresAt,
+    semanticScopeHash,
+    delegationPolicy,
+    delegationPolicyHash,
+    confirmationCodeBindingHash,
+    confirmationCode: `MAC-${confirmationCodeBindingHash.slice(0, 24).toUpperCase()}`,
+  };
+}
+
+export function applyMilestoneAutonomyContract(options: {
+  store: FileStateStore;
+  projectId: string;
+  milestone: MilestoneState;
+  principal: string;
+  delegate: string;
+  expiresAt: string;
+  confirmationCode: string;
+  now: Date;
+}): ActiveMilestoneAutonomy {
+  const prepared = prepareMilestoneAutonomyContract(options);
+  const root = options.store.milestoneRoot(options.projectId, options.milestone.id);
+  const existing = readMilestoneAutonomyEvents(options.store, options.projectId, options.milestone.id);
+  let event = existing.at(-1) ?? null;
+  // The original confirmation remains usable only for an exact successful retry or
+  // completion of its event-first interrupted write, never to undo a revocation.
+  // Legacy event-first writes retain their original v1 retry code. They can only
+  // finish at the original pre-execution revision, never reopen revoked authority.
+  const retryBindingHash = event?.confirmationCodeBindingHash ?? (event ? sha256Hex(canonicalJsonStringify({
+    version: 'milestone-autonomy-contract-v1',
+    projectId: options.projectId,
+    milestoneId: options.milestone.id,
+    milestoneRevision: options.milestone.revision,
+    planHash: options.milestone.planHash,
+    semanticScopeHash: event.semanticScopeHash,
+    delegationPolicyHash: event.delegationPolicyHash,
+  })) : null);
+  const retry = event !== null && retryBindingHash !== null
+    && options.confirmationCode.trim() === `MAC-${retryBindingHash.slice(0, 24).toUpperCase()}`
+    && event.delegationPolicyHash === prepared.delegationPolicyHash
+    && event.milestoneRevision === options.milestone.revision
+    && (event.issuedMilestoneStatus ?? 'awaiting_execution_authorization') === options.milestone.status
+    && event.principal === options.principal.trim()
+    && event.delegate === options.delegate.trim()
+    && event.expiresAt === prepared.expiresAt
+    && event.semanticScopeHash === milestoneSemanticScopeHash(options.milestone);
+  if (retry && event) {
+    if (Date.parse(event.expiresAt) <= options.now.getTime()) {
+      throw new WorkflowError('TRANSITION_BLOCKED', 'Expired autonomy confirmation cannot be replayed.');
+    }
+    try {
+      options.store.readDelegation(options.projectId, event.delegationGrantId);
+      return requireActiveMilestoneAutonomy({ ...options, actor: options.delegate });
+    } catch (error) {
+      if (!(error instanceof WorkflowError) || error.code !== 'NOT_FOUND') throw error;
+      // Only this exact confirmed event may finish its missing grant write below.
+    }
+  }
+  if (!retry && options.confirmationCode.trim() !== prepared.confirmationCode) {
+    throw new WorkflowError('TRANSITION_BLOCKED', 'Milestone autonomy confirmation does not match the exact bounded contract.', {
+      milestoneId: options.milestone.id,
+      confirmationCodeBindingHash: prepared.confirmationCodeBindingHash,
+    });
+  }
+  if (event && !retry) {
+    let previousGrant = null;
+    try {
+      previousGrant = options.store.readDelegation(options.projectId, event.delegationGrantId);
+    } catch (error) {
+      if (!(error instanceof WorkflowError) || error.code !== 'NOT_FOUND') throw error;
+      // A fresh confirmation binds the missing grant and may supersede an inert
+      // interrupted issuance. Preserve its event; never recreate its authority.
+    }
+    if (previousGrant?.status === 'active'
+      && Date.parse(previousGrant.expiresAt) > options.now.getTime()
+      && event.semanticScopeHash === milestoneSemanticScopeHash(options.milestone)) {
+      throw new WorkflowError('TRANSITION_BLOCKED', 'Milestone already has an active autonomy contract.', {
+        eventId: event.eventId,
+        delegationGrantId: event.delegationGrantId,
+        expiresAt: previousGrant.expiresAt,
+      });
+    }
+    event = null;
+  }
+  if (!event) {
+    const grantId = createEntityId('DGR', options.now.getTime());
+    event = options.store.appendSidecarEvent<MilestoneAutonomyEvent>(
+      root,
+      AUTONOMY_SIDECAR,
+      {
+        eventId: `MAC-${createUlid(options.now.getTime())}`,
+        recordedAt: options.now.toISOString(),
+        eventType: 'issued',
+        confirmationCodeBindingHash: prepared.confirmationCodeBindingHash,
+        issuedMilestoneStatus: options.milestone.status,
+        projectId: options.projectId,
+        milestoneId: options.milestone.id,
+        milestoneRevision: options.milestone.revision,
+        principal: prepared.principal,
+        delegate: prepared.delegate,
+        issuedAt: options.now.toISOString(),
+        expiresAt: prepared.expiresAt,
+        semanticScopeHash: prepared.semanticScopeHash,
+        delegationGrantId: grantId,
+        delegationPolicyHash: prepared.delegationPolicyHash,
+      },
+      {
+        validateEvent: (candidate) => validateMilestoneAutonomyEvent(
+          candidate,
+          options.projectId,
+          options.milestone.id,
+        ),
+      },
+    );
+  }
+  const grantId = event.delegationGrantId;
+  const timestamp = event.issuedAt;
+  const grant = options.store.writeDelegation({
+    schemaVersion: STATE_SCHEMA_VERSION,
+    revision: 0,
+    id: grantId,
+    projectId: options.projectId,
+    createdAt: timestamp,
+    updatedAt: timestamp,
+    kind: 'delegation-grant',
+    status: 'active',
+    principal: prepared.principal,
+    delegate: prepared.delegate,
+    scope: prepared.delegationPolicy.scope,
+    transitions: prepared.delegationPolicy.transitions,
+    expiresAt: prepared.expiresAt,
+    policyHash: prepared.delegationPolicyHash,
+    revokedAt: null,
+    revokedBy: null,
+    revokeReason: null,
+  }, null);
+  return { contract: event, grant };
+}
+
+/** Derive a contract without issuing, extending or reactivating a grant. */
+export function bindMilestoneAutonomyToGrant(options: {
+  store: FileStateStore; projectId: string; milestone: MilestoneState;
+  actor: string; grantId: string; now: Date;
+}): ActiveMilestoneAutonomy {
+  const { store, projectId, milestone, actor, now } = options;
+  if (!['awaiting_execution_authorization', 'active'].includes(milestone.status) || !milestone.planHash)
+    throw new WorkflowError('TRANSITION_BLOCKED', 'Autonomy binding requires a complete active Milestone Plan.');
+  const grant = store.readDelegation(projectId, options.grantId);
+  if (grant.scope.kind !== 'milestone' || grant.scope.id !== milestone.id)
+    throw new WorkflowError('TRANSITION_BLOCKED', 'Autonomy binding requires an exact Milestone grant.');
+  for (const transition of AUTONOMY_TRANSITIONS) {
+    if (transition !== 'project_memory.approve' && !grant.transitions.includes(transition))
+      throw new WorkflowError('TRANSITION_BLOCKED', `Autonomy binding requires ${transition}; request grant expansion.`);
+  }
+  assertDelegationCanAuthorize(grant, 'milestone.execution_authorize', actor, milestone, now);
+  const previous = readMilestoneAutonomyEvents(store, projectId, milestone.id).at(-1);
+  if (previous) {
+    if (previous.delegationGrantId === grant.id) return requireActiveMilestoneAutonomy(options);
+    if (previous.semanticScopeHash !== milestoneSemanticScopeHash(milestone))
+      throw new WorkflowError('TRANSITION_BLOCKED', 'Autonomy rebinding cannot change the approved semantic scope.');
+    let previousGrant: DelegationGrant | null = null;
+    try { previousGrant = store.readDelegation(projectId, previous.delegationGrantId); }
+    catch (error) { if (!(error instanceof WorkflowError) || error.code !== 'NOT_FOUND') throw error; }
+    if (previousGrant?.status === 'active' && Date.parse(previousGrant.expiresAt) > now.getTime())
+      throw new WorkflowError('TRANSITION_BLOCKED', 'Revoke the existing active grant before replacing its autonomy binding.');
+  }
+  const contract = store.appendSidecarEvent<MilestoneAutonomyEvent>(
+    store.milestoneRoot(projectId, milestone.id), AUTONOMY_SIDECAR, {
+      eventId: `MAC-${createUlid(now.getTime())}`, recordedAt: now.toISOString(), eventType: 'issued',
+      projectId, milestoneId: milestone.id, milestoneRevision: milestone.revision,
+      principal: grant.principal, delegate: grant.delegate, issuedAt: now.toISOString(), expiresAt: grant.expiresAt,
+      semanticScopeHash: milestoneSemanticScopeHash(milestone), delegationGrantId: grant.id,
+      delegationPolicyHash: grant.policyHash,
+    }, { validateEvent: candidate => validateMilestoneAutonomyEvent(candidate, projectId, milestone.id) });
+  return { contract, grant };
+}
+
+export function requireActiveMilestoneAutonomy(options: {
+  store: FileStateStore;
+  projectId: string;
+  milestone: MilestoneState;
+  actor: string;
+  now: Date;
+}): ActiveMilestoneAutonomy {
+  const events = readMilestoneAutonomyEvents(options.store, options.projectId, options.milestone.id);
+  const contract = events.at(-1);
+  if (!contract) {
+    throw new WorkflowError('TRANSITION_BLOCKED', `Milestone ${options.milestone.id} has no autonomy contract.`);
+  }
+  if (contract.delegate !== options.actor.trim()) {
+    throw new WorkflowError('TRANSITION_BLOCKED', 'Milestone autonomy contract does not authorize this actor.', {
+      expectedDelegate: contract.delegate,
+    });
+  }
+  if (Date.parse(contract.expiresAt) <= options.now.getTime()) {
+    throw new WorkflowError('TRANSITION_BLOCKED', 'Milestone autonomy contract has expired.', {
+      expiresAt: contract.expiresAt,
+    });
+  }
+  if (contract.semanticScopeHash !== milestoneSemanticScopeHash(options.milestone)) {
+    throw new WorkflowError('TRANSITION_BLOCKED', 'Milestone semantic scope changed after autonomy was granted.');
+  }
+  const grant = options.store.readDelegation(options.projectId, contract.delegationGrantId);
+  const expectedPolicyHash = hashDelegationPolicy(options.projectId, {
+    principal: grant.principal,
+    delegate: grant.delegate,
+    scope: grant.scope,
+    transitions: grant.transitions,
+    expiresAt: grant.expiresAt,
+  });
+  if (
+    grant.status !== 'active'
+    || grant.principal !== contract.principal
+    || grant.delegate !== contract.delegate
+    || grant.expiresAt !== contract.expiresAt
+    || grant.scope.kind !== 'milestone'
+    || grant.scope.id !== options.milestone.id
+    || grant.policyHash !== expectedPolicyHash
+    || grant.policyHash !== contract.delegationPolicyHash
+  ) {
+    throw new WorkflowError('TRANSITION_BLOCKED', 'Milestone autonomy delegation is revoked or invalid.');
+  }
+  return { contract, grant };
+}
+
+export function assertAutonomousPlanEvolution(
+  milestone: MilestoneState,
+  plan: MilestonePlanInput,
+  contract: MilestoneAutonomyEvent,
+): void {
+  const candidateScopeHash = sha256Hex(canonicalJsonStringify({
+    version: 'milestone-autonomy-semantic-scope-v1',
+    milestoneId: milestone.id,
+    discoveryId: milestone.discoveryId,
+    baseBranch: milestone.baseBranch,
+    outcome: plan.outcome.trim(),
+    successSignal: plan.successSignal.trim(),
+    acceptance: plan.acceptance,
+    checks: plan.checks,
+  }));
+  if (candidateScopeHash !== contract.semanticScopeHash) {
+    throw new WorkflowError(
+      'TRANSITION_BLOCKED',
+      'Autonomous Milestone evolution may change only Task membership; semantic scope requires a new human contract.',
+      { expectedSemanticScopeHash: contract.semanticScopeHash, candidateSemanticScopeHash: candidateScopeHash },
+    );
+  }
+}
+
+export function readMilestoneAutonomyEvents(
+  store: FileStateStore,
+  projectId: string,
+  milestoneId: string,
+): MilestoneAutonomyEvent[] {
+  return store.readSidecarEvents<MilestoneAutonomyEvent>(
+    store.milestoneRoot(projectId, milestoneId),
+    AUTONOMY_SIDECAR,
+    { validateEvent: (event) => validateMilestoneAutonomyEvent(event, projectId, milestoneId) },
+  );
+}
+
+function validateMilestoneAutonomyEvent(
+  event: MilestoneAutonomyEvent,
+  expectedProjectId: string,
+  expectedMilestoneId: string,
+): void {
+  if (
+    event.eventType !== 'issued'
+    || event.projectId !== expectedProjectId
+    || event.milestoneId !== expectedMilestoneId
+  ) {
+    throw new WorkflowError('STATE_CORRUPT', 'Milestone autonomy event identity is invalid.');
+  }
+  if (!event.principal || event.principal.startsWith('agent:') || !event.delegate.startsWith('agent:')) {
+    throw new WorkflowError('STATE_CORRUPT', 'Milestone autonomy event actors are invalid.');
+  }
+  for (const [label, value] of [
+    ['semanticScopeHash', event.semanticScopeHash],
+    ['delegationPolicyHash', event.delegationPolicyHash],
+  ] as const) {
+    if (!/^[a-f0-9]{64}$/.test(value)) {
+      throw new WorkflowError('STATE_CORRUPT', `Milestone autonomy ${label} is invalid.`);
+    }
+  }
+  if (!/^DGR-[0-9A-HJKMNP-TV-Z]{26}$/.test(event.delegationGrantId)) {
+    throw new WorkflowError('STATE_CORRUPT', 'Milestone autonomy delegationGrantId is invalid.');
+  }
+  if (!Number.isFinite(Date.parse(event.issuedAt)) || !Number.isFinite(Date.parse(event.expiresAt))) {
+    throw new WorkflowError('STATE_CORRUPT', 'Milestone autonomy timestamps are invalid.');
+  }
+  if (Date.parse(event.expiresAt) <= Date.parse(event.issuedAt)) {
+    throw new WorkflowError('STATE_CORRUPT', 'Milestone autonomy expiry must follow issuance.');
+  }
+  if (event.confirmationCodeBindingHash !== undefined
+    && (!/^[a-f0-9]{64}$/.test(event.confirmationCodeBindingHash)
+      || !['awaiting_execution_authorization', 'active'].includes(event.issuedMilestoneStatus ?? ''))) {
+    throw new WorkflowError('STATE_CORRUPT', 'Milestone autonomy confirmation binding is invalid.');
+  }
+  if (!Number.isInteger(event.milestoneRevision) || event.milestoneRevision < 1) {
+    throw new WorkflowError('STATE_CORRUPT', 'Milestone autonomy revision is invalid.');
+  }
+}