@ankhorage/flow 0.4.1 → 0.5.0

package/src/features/execution/application/createDurableRunAsync.ts

@@ -0,0 +1,14 @@
+import type { FlowDefinitionRef, FlowDurableRun } from '../../../types/durableExecution.js';
+import type { FlowClock } from '../../../types/execution.js';
+import { createDurableRun } from '../domain/createDurableRun.js';
+import type { FlowPersistencePort } from '../ports/FlowPersistencePort.js';
+
+/*** Persist a new durable run without executing an operation or provider effect. */
+export const createDurableRunAsync = async (
+  input: { readonly flow: FlowDefinitionRef; readonly id: string },
+  dependencies: { readonly clock: FlowClock; readonly persistence: FlowPersistencePort },
+): Promise<FlowDurableRun> => {
+  const run = createDurableRun(input, dependencies.clock.now());
+  await dependencies.persistence.createRunAsync(run);
+  return run;
+};

package/src/features/execution/application/runDurableWorkerAsync.ts

@@ -0,0 +1,337 @@
+import type {
+  FlowDurableRun,
+  FlowDurableWork,
+  FlowRetryPolicy,
+  FlowRunCheckpoint,
+} from '../../../types/durableExecution.js';
+import type { FlowClock } from '../../../types/execution.js';
+import type { FlowSecurityPort } from '../../../types/security.js';
+import { FlowSecurityError } from '../../security/FlowSecurityError.js';
+import { createRetryWork } from '../domain/createRetryWork.js';
+import type { FlowPersistencePort } from '../ports/FlowPersistencePort.js';
+
+/** Claim bounded durable work and execute it with fenced recovery, retry, and approval handling. */
+export const runDurableWorkerAsync = async (
+  input: {
+    readonly approvalPollIntervalMs: number;
+    readonly concurrency: number;
+    readonly leaseDurationMs: number;
+    readonly limit: number;
+    readonly retry: FlowRetryPolicy;
+    readonly workerId: string;
+  },
+  dependencies: {
+    readonly clock: FlowClock;
+    readonly effects: FlowDurableEffectPort;
+    readonly persistence: FlowPersistencePort;
+    readonly security?: FlowSecurityPort;
+  },
+): Promise<FlowWorkerResult> => {
+  assertWorkerInput(input);
+  const now = dependencies.clock.now();
+  const recoveredWorkIds = await dependencies.persistence.recoverExpiredClaimsAsync(now);
+  const claimed = await dependencies.persistence.claimDueWorkAsync({
+    leaseDurationMs: input.leaseDurationMs,
+    limit: Math.min(input.limit, input.concurrency),
+    now,
+    workerId: input.workerId,
+  });
+  const outcomes = await Promise.all(
+    claimed.map((work) => processWorkAsync(work, input, dependencies)),
+  );
+  return { claimedWorkIds: claimed.map((work) => work.id), outcomes, recoveredWorkIds };
+};
+
+/** Executes one effect through the durable step and security boundaries. */
+const processWorkAsync = async (
+  work: FlowDurableWork,
+  input: Parameters<typeof runDurableWorkerAsync>[0],
+  dependencies: Parameters<typeof runDurableWorkerAsync>[1],
+): Promise<FlowWorkerOutcome> => {
+  const { lease } = work;
+  if (lease === undefined) return { status: 'lost_lease', workId: work.id };
+  const run = await dependencies.persistence.readRunAsync(work.runId);
+  if (run === undefined || run.status === 'cancelled') {
+    await completeAsync(work, input.workerId, dependencies);
+    return { status: 'cancelled', workId: work.id };
+  }
+  if (isCompleted(run.checkpoint, work.stepId)) {
+    await completeAsync(work, input.workerId, dependencies);
+    return { status: 'already_completed', workId: work.id };
+  }
+  try {
+    const outbox = await prepareOutboxAsync(work, dependencies);
+    if (outbox.status === 'delivered') {
+      const transitioned = await transitionAsync(
+        run,
+        'succeeded',
+        completedCheckpoint(run.checkpoint, work.stepId),
+        dependencies,
+      );
+      const completed = await completeAsync(work, input.workerId, dependencies);
+      return {
+        status: transitioned && completed ? 'already_completed' : 'lost_lease',
+        workId: work.id,
+      };
+    }
+    const effectStatus = await executeEffectAsync(work, run, dependencies);
+    await dependencies.persistence.markOutboxDeliveredAsync(work.id);
+    const transitioned = await transitionAsync(
+      run,
+      'succeeded',
+      completedCheckpoint(run.checkpoint, work.stepId),
+      dependencies,
+    );
+    if (!transitioned || !(await completeAsync(work, input.workerId, dependencies)))
+      return { status: 'lost_lease', workId: work.id };
+    return { status: effectStatus, workId: work.id };
+  } catch (error) {
+    if (isApprovalPending(error)) return waitForApprovalAsync(work, run, input, dependencies);
+    return retryOrFailAsync(work, run, input, dependencies, error);
+  }
+};
+
+/** Create an idempotency-keyed outbox record before delivery, or resume its pending record after a crash. */
+const prepareOutboxAsync = async (
+  work: FlowDurableWork,
+  dependencies: Parameters<typeof runDurableWorkerAsync>[1],
+) => {
+  const existing = await dependencies.persistence.readOutboxAsync(work.id);
+  if (existing !== undefined) return existing;
+  const now = dependencies.clock.now().toISOString();
+  await dependencies.persistence.createOutboxAsync({
+    createdAt: now,
+    id: work.id,
+    idempotencyKey: work.idempotencyKey ?? work.id,
+    runId: work.runId,
+    status: 'pending',
+    workId: work.id,
+  });
+  const created = await dependencies.persistence.readOutboxAsync(work.id);
+  if (created === undefined) throw new Error('FLOW_OUTBOX_CREATE_FAILED');
+  return created;
+};
+
+/** Runs internal work directly, while protected provider work requires reconciliation and a canonical permit. */
+const executeEffectAsync = async (
+  work: FlowDurableWork,
+  run: FlowDurableRun,
+  dependencies: Parameters<typeof runDurableWorkerAsync>[1],
+): Promise<'succeeded'> => {
+  const execute = () =>
+    dependencies.effects.executeAsync({
+      idempotencyKey: work.idempotencyKey ?? work.id,
+      run,
+      work,
+    });
+  if (work.effectKind === 'internal') {
+    if (work.securityOperation !== undefined)
+      throw new Error('FLOW_INTERNAL_EFFECT_SECURITY_OPERATION');
+    await execute();
+    return 'succeeded';
+  }
+  if (work.securityOperation === undefined)
+    throw new Error('FLOW_PROTECTED_EFFECT_SECURITY_OPERATION');
+  if (dependencies.security === undefined) throw new Error('FLOW_SECURITY_PORT_REQUIRED');
+  if (dependencies.effects.reconcileAsync === undefined)
+    throw new Error('FLOW_PROTECTED_EFFECT_RECONCILIATION_REQUIRED');
+  if (
+    (await dependencies.effects.reconcileAsync({
+      idempotencyKey: work.idempotencyKey ?? work.id,
+      run,
+      work,
+    })) === 'delivered'
+  )
+    return 'succeeded';
+  const permit = await dependencies.security.authorizeAsync(work.securityOperation);
+  await permit.executeAsync(async () => execute());
+  return 'succeeded';
+};
+
+/** Persist a waiting approval and defer its at-least-once delivery without consuming the lease. */
+const waitForApprovalAsync = async (
+  work: FlowDurableWork,
+  run: FlowDurableRun,
+  input: Parameters<typeof runDurableWorkerAsync>[0],
+  dependencies: Parameters<typeof runDurableWorkerAsync>[1],
+): Promise<FlowWorkerOutcome> => {
+  const transitioned = await transitionAsync(run, 'waiting_approval', run.checkpoint, dependencies);
+  const released = await dependencies.persistence.releaseWorkAsync({
+    dueAt: new Date(
+      dependencies.clock.now().getTime() + input.approvalPollIntervalMs,
+    ).toISOString(),
+    id: work.id,
+    leaseFencingToken: claimFencingToken(work),
+    workerId: input.workerId,
+  });
+  return { status: transitioned && released ? 'waiting_approval' : 'lost_lease', workId: work.id };
+};
+
+/** Persist a bounded retry or terminal failure before releasing the claimed delivery. */
+const retryOrFailAsync = async (
+  work: FlowDurableWork,
+  run: FlowDurableRun,
+  input: Parameters<typeof runDurableWorkerAsync>[0],
+  dependencies: Parameters<typeof runDurableWorkerAsync>[1],
+  error: unknown,
+): Promise<FlowWorkerOutcome> => {
+  if (work.attempt >= input.retry.maxAttempts) {
+    await dependencies.effects.compensateAsync?.({ run, work });
+    const transitioned = await transitionAsync(
+      run,
+      'failed',
+      failedCheckpoint(run.checkpoint, work.stepId),
+      dependencies,
+    );
+    const completed = await completeAsync(work, input.workerId, dependencies);
+    return {
+      error: errorMessage(error),
+      status: transitioned && completed ? 'failed' : 'lost_lease',
+      workId: work.id,
+    };
+  }
+  await dependencies.persistence.enqueueWorkAsync(
+    createRetryWork(work, dependencies.clock.now(), input.retry),
+  );
+  const completed = await completeAsync(work, input.workerId, dependencies);
+  return {
+    error: errorMessage(error),
+    status: completed ? 'retry_scheduled' : 'lost_lease',
+    workId: work.id,
+  };
+};
+
+/** Compare-and-swap a run state while preserving its immutable flow revision. */
+const transitionAsync = (
+  run: FlowDurableRun,
+  status: FlowDurableRun['status'],
+  checkpoint: FlowRunCheckpoint | undefined,
+  dependencies: Parameters<typeof runDurableWorkerAsync>[1],
+): Promise<boolean> =>
+  dependencies.persistence.transitionRunAsync({
+    expectedRevision: run.revision,
+    run: {
+      ...run,
+      ...(checkpoint === undefined ? {} : { checkpoint }),
+      revision: run.revision + 1,
+      status,
+      updatedAt: dependencies.clock.now().toISOString(),
+    },
+  });
+
+/** Complete a work lease only when its owner and fencing token still match. */
+const completeAsync = (
+  work: FlowDurableWork,
+  workerId: string,
+  dependencies: Parameters<typeof runDurableWorkerAsync>[1],
+): Promise<boolean> =>
+  dependencies.persistence.completeWorkAsync({
+    id: work.id,
+    leaseFencingToken: claimFencingToken(work),
+    now: dependencies.clock.now(),
+    workerId,
+  });
+
+/** Read the lease token only from a claimed work item. */
+const claimFencingToken = (work: FlowDurableWork): number => {
+  if (work.lease === undefined) throw new Error('FLOW_WORK_LEASE_MISSING');
+  return work.lease.fencingToken;
+};
+
+/** Add a successful step exactly once to an immutable checkpoint. */
+const completedCheckpoint = (
+  checkpoint: FlowRunCheckpoint | undefined,
+  stepId: string | undefined,
+): FlowRunCheckpoint => ({
+  completedStepIds: unique([
+    ...(checkpoint?.completedStepIds ?? []),
+    ...(stepId === undefined ? [] : [stepId]),
+  ]),
+  ...(checkpoint?.data === undefined ? {} : { data: checkpoint.data }),
+  failedStepIds: checkpoint?.failedStepIds ?? [],
+});
+
+/** Add a terminally failed step to an immutable checkpoint. */
+const failedCheckpoint = (
+  checkpoint: FlowRunCheckpoint | undefined,
+  stepId: string | undefined,
+): FlowRunCheckpoint => ({
+  completedStepIds: checkpoint?.completedStepIds ?? [],
+  ...(checkpoint?.data === undefined ? {} : { data: checkpoint.data }),
+  failedStepIds: unique([
+    ...(checkpoint?.failedStepIds ?? []),
+    ...(stepId === undefined ? [] : [stepId]),
+  ]),
+});
+
+/** Check whether a completed checkpoint makes a duplicate delivery a no-op. */
+const isCompleted = (
+  checkpoint: FlowRunCheckpoint | undefined,
+  stepId: string | undefined,
+): boolean => stepId !== undefined && checkpoint?.completedStepIds.includes(stepId) === true;
+
+/** Validate finite worker bounds before touching persistence. */
+const assertWorkerInput = (input: Parameters<typeof runDurableWorkerAsync>[0]): void => {
+  for (const value of [
+    input.approvalPollIntervalMs,
+    input.concurrency,
+    input.leaseDurationMs,
+    input.limit,
+    input.retry.maxAttempts,
+  ])
+    if (!Number.isSafeInteger(value) || value < 1) throw new Error('FLOW_WORKER_INPUT_INVALID');
+};
+
+/** Identify the canonical pending-approval error without interpreting untrusted error shapes. */
+const isApprovalPending = (error: unknown): boolean =>
+  error instanceof FlowSecurityError && error.code === 'approval_pending';
+
+/** Preserve a concise, provider-neutral failure signal in the worker result. */
+const errorMessage = (error: unknown): string =>
+  error instanceof Error ? error.message : 'FLOW_EFFECT_FAILED';
+
+/** Keep persisted checkpoint arrays deterministic. */
+const unique = (values: readonly string[]): readonly string[] => [...new Set(values)];
+
+/** Application-owned effect boundary; adapters must apply the supplied idempotency key at their side-effect boundary. */
+export interface FlowDurableEffectPort {
+  readonly compensateAsync?: (input: {
+    readonly run: FlowDurableRun;
+    readonly work: FlowDurableWork;
+  }) => Promise<void>;
+  readonly executeAsync: (input: {
+    readonly idempotencyKey: string;
+    readonly run: FlowDurableRun;
+    readonly work: FlowDurableWork;
+  }) => Promise<void>;
+  /**
+   * Query the provider's idempotency boundary before a protected replay. A provider must return
+   * `delivered` only when the stable key proves that the original effect completed.
+   */
+  readonly reconcileAsync?: (input: {
+    readonly idempotencyKey: string;
+    readonly run: FlowDurableRun;
+    readonly work: FlowDurableWork;
+  }) => Promise<'delivered' | 'unknown'>;
+}
+
+/** Observable outcome for every delivery claimed by one bounded worker tick. */
+export interface FlowWorkerOutcome {
+  readonly error?: string;
+  readonly status:
+    | 'already_completed'
+    | 'cancelled'
+    | 'failed'
+    | 'lost_lease'
+    | 'retry_scheduled'
+    | 'succeeded'
+    | 'waiting_approval';
+  readonly workId: string;
+}
+
+/** Summary of one worker tick; delivery remains at-least-once until fenced completion. */
+export interface FlowWorkerResult {
+  readonly claimedWorkIds: readonly string[];
+  readonly outcomes: readonly FlowWorkerOutcome[];
+  readonly recoveredWorkIds: readonly string[];
+}

package/src/features/execution/domain/calculateRetryDueAt.ts

@@ -0,0 +1,21 @@
+import type { FlowRetryPolicy } from '../../../types/durableExecution.js';
+
+/*** Calculate an exponential retry time from persisted attempt state without ambient time. */
+export const calculateRetryDueAt = (
+  now: Date,
+  completedAttempt: number,
+  policy: FlowRetryPolicy,
+): string => {
+  if (!Number.isSafeInteger(completedAttempt) || completedAttempt < 1)
+    throw new Error('FLOW_RETRY_ATTEMPT_INVALID');
+  if (!Number.isSafeInteger(policy.baseDelayMs) || policy.baseDelayMs < 0)
+    throw new Error('FLOW_RETRY_BASE_DELAY_INVALID');
+  if (
+    !Number.isSafeInteger(policy.maxDelayMs) ||
+    policy.maxDelayMs < policy.baseDelayMs ||
+    policy.maxDelayMs < 0
+  )
+    throw new Error('FLOW_RETRY_MAX_DELAY_INVALID');
+  const delay = Math.min(policy.maxDelayMs, policy.baseDelayMs * 2 ** (completedAttempt - 1));
+  return new Date(now.getTime() + delay).toISOString();
+};

package/src/features/execution/domain/createDurableRun.ts

@@ -0,0 +1,14 @@
+import type { FlowDefinitionRef, FlowDurableRun } from '../../../types/durableExecution.js';
+
+/*** Create a revision-zero run pinned permanently to one published flow definition. */
+export const createDurableRun = (
+  input: { readonly flow: FlowDefinitionRef; readonly id: string },
+  now: Date,
+): FlowDurableRun => ({
+  createdAt: now.toISOString(),
+  flow: { ...input.flow },
+  id: input.id,
+  revision: 0,
+  status: 'queued',
+  updatedAt: now.toISOString(),
+});

package/src/features/execution/domain/createRetryWork.ts

@@ -0,0 +1,22 @@
+import type { FlowDurableWork, FlowRetryPolicy } from '../../../types/durableExecution.js';
+import { calculateRetryDueAt } from './calculateRetryDueAt.js';
+
+/*** Create the next immutable work attempt from a completed attempt and controlled clock. */
+export const createRetryWork = (
+  completed: FlowDurableWork,
+  now: Date,
+  policy: FlowRetryPolicy,
+): FlowDurableWork => ({
+  ...(completed.idempotencyKey === undefined ? {} : { idempotencyKey: completed.idempotencyKey }),
+  attempt: completed.attempt + 1,
+  dueAt: calculateRetryDueAt(now, completed.attempt, policy),
+  effectKind: completed.effectKind,
+  flow: { ...completed.flow },
+  id: `${completed.runId}:attempt:${completed.attempt + 1}`,
+  runId: completed.runId,
+  ...(completed.securityOperation === undefined
+    ? {}
+    : { securityOperation: completed.securityOperation }),
+  ...(completed.stepId === undefined ? {} : { stepId: completed.stepId }),
+  status: 'ready',
+});

package/src/features/execution/domain/isCronDueAt.ts

@@ -0,0 +1,131 @@
+/** Determine whether one UTC instant matches a five-field POSIX cron expression in an IANA zone. */
+export const isCronDueAt = (input: {
+  readonly cron: string;
+  readonly now: Date;
+  readonly timezone?: string;
+}): boolean => {
+  const fields = input.cron.trim().split(/\s+/);
+  if (fields.length !== 5) throw new Error('FLOW_CRON_INVALID');
+  const local = localParts(input.now, input.timezone ?? 'Etc/UTC');
+  const [minute, hour, dayOfMonth, month, dayOfWeek] = fields;
+  if (
+    minute === undefined ||
+    hour === undefined ||
+    dayOfMonth === undefined ||
+    month === undefined ||
+    dayOfWeek === undefined
+  )
+    throw new Error('FLOW_CRON_INVALID');
+  const minuteMatches = matchesField(minute, local.minute, 0, 59);
+  const hourMatches = matchesField(hour, local.hour, 0, 23);
+  const monthMatches = matchesField(month, local.month, 1, 12);
+  const dayOfMonthMatches = matchesField(dayOfMonth, local.day, 1, 31);
+  const dayOfWeekMatches = matchesField(dayOfWeek, local.dayOfWeek, 0, 7);
+  const dayMatches =
+    dayOfMonth === '*' || dayOfWeek === '*'
+      ? dayOfMonthMatches && dayOfWeekMatches
+      : dayOfMonthMatches || dayOfWeekMatches;
+  return minuteMatches && hourMatches && monthMatches && dayMatches;
+};
+
+/** Format a UTC instant into its real local wall-clock fields; duplicate fall-back instants remain distinct instants. */
+const localParts = (
+  now: Date,
+  timezone: string,
+): {
+  readonly day: number;
+  readonly dayOfWeek: number;
+  readonly hour: number;
+  readonly minute: number;
+  readonly month: number;
+} => {
+  try {
+    const parts = new Intl.DateTimeFormat('en-US', {
+      day: 'numeric',
+      hour: 'numeric',
+      hourCycle: 'h23',
+      minute: 'numeric',
+      month: 'numeric',
+      timeZone: timezone,
+      weekday: 'short',
+    }).formatToParts(now);
+    const read = (type: Intl.DateTimeFormatPartTypes): string =>
+      parts.find((part) => part.type === type)?.value ?? invalidTimezone();
+    return {
+      day: Number(read('day')),
+      dayOfWeek: weekday(read('weekday')),
+      hour: Number(read('hour')),
+      minute: Number(read('minute')),
+      month: Number(read('month')),
+    };
+  } catch {
+    throw new Error('FLOW_CRON_TIMEZONE_INVALID');
+  }
+};
+
+/** Match one POSIX cron field including lists, ranges, and positive step values. */
+const matchesField = (field: string, value: number, minimum: number, maximum: number): boolean =>
+  field.split(',').some((part) => matchesPart(part, value, minimum, maximum));
+
+/** Match one validated cron list member. */
+const matchesPart = (part: string, value: number, minimum: number, maximum: number): boolean => {
+  const [rangePart, stepPart] = part.split('/');
+  if (part.split('/').length > 2 || rangePart === undefined) throw new Error('FLOW_CRON_INVALID');
+  const step = stepPart === undefined ? 1 : parseValue(stepPart, 1, maximum - minimum + 1);
+  const [start, end] = parseRange(rangePart, minimum, maximum);
+  return value >= start && value <= end && (value - start) % step === 0;
+};
+
+/** Parse a wildcard, number, or inclusive numeric range. */
+const parseRange = (range: string, minimum: number, maximum: number): readonly [number, number] => {
+  if (range === '*') return [minimum, maximum];
+  const values = range.split('-');
+  if (values.length === 1) {
+    const [single] = values;
+    if (single === undefined) throw new Error('FLOW_CRON_INVALID');
+    const value = parseValue(single, minimum, maximum);
+    return [value, value];
+  }
+  if (values.length !== 2 || values[0] === undefined || values[1] === undefined)
+    throw new Error('FLOW_CRON_INVALID');
+  const start = parseValue(values[0], minimum, maximum);
+  const end = parseValue(values[1], minimum, maximum);
+  if (end < start) throw new Error('FLOW_CRON_INVALID');
+  return [start, end];
+};
+
+/** Parse one strict POSIX cron integer. */
+const parseValue = (value: string, minimum: number, maximum: number): number => {
+  if (!/^\d+$/.test(value)) throw new Error('FLOW_CRON_INVALID');
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed < minimum || parsed > maximum)
+    throw new Error('FLOW_CRON_INVALID');
+  return parsed;
+};
+
+/** Map English short weekday names produced by the fixed formatter to POSIX weekday values. */
+const weekday = (value: string): number => {
+  switch (value) {
+    case 'Sun':
+      return 0;
+    case 'Mon':
+      return 1;
+    case 'Tue':
+      return 2;
+    case 'Wed':
+      return 3;
+    case 'Thu':
+      return 4;
+    case 'Fri':
+      return 5;
+    case 'Sat':
+      return 6;
+    default:
+      return invalidTimezone();
+  }
+};
+
+/** Keep an impossible formatter shape distinct from a cron syntax error. */
+const invalidTimezone = (): never => {
+  throw new Error('FLOW_CRON_TIMEZONE_INVALID');
+};

package/src/features/execution/ports/FlowPersistencePort.ts

@@ -0,0 +1,38 @@
+import type {
+  FlowDurableRun,
+  FlowDurableWork,
+  FlowOutboxRecord,
+} from '../../../types/durableExecution.js';
+
+export interface FlowPersistencePort {
+  readonly cancelRunWorkAsync: (runId: string) => Promise<readonly string[]>;
+  readonly claimDueWorkAsync: (input: {
+    readonly leaseDurationMs: number;
+    readonly limit: number;
+    readonly now: Date;
+    readonly workerId: string;
+  }) => Promise<readonly FlowDurableWork[]>;
+  readonly completeWorkAsync: (input: {
+    readonly id: string;
+    readonly leaseFencingToken: number;
+    readonly now: Date;
+    readonly workerId: string;
+  }) => Promise<boolean>;
+  readonly createOutboxAsync: (record: FlowOutboxRecord) => Promise<void>;
+  readonly createRunAsync: (run: FlowDurableRun) => Promise<void>;
+  readonly enqueueWorkAsync: (work: FlowDurableWork) => Promise<void>;
+  readonly markOutboxDeliveredAsync: (id: string) => Promise<boolean>;
+  readonly readOutboxAsync: (id: string) => Promise<FlowOutboxRecord | undefined>;
+  readonly readRunAsync: (id: string) => Promise<FlowDurableRun | undefined>;
+  readonly recoverExpiredClaimsAsync: (now: Date) => Promise<readonly string[]>;
+  readonly releaseWorkAsync: (input: {
+    readonly dueAt: string;
+    readonly id: string;
+    readonly leaseFencingToken: number;
+    readonly workerId: string;
+  }) => Promise<boolean>;
+  readonly transitionRunAsync: (input: {
+    readonly expectedRevision: number;
+    readonly run: FlowDurableRun;
+  }) => Promise<boolean>;
+}

package/src/features/security/application/createFlowSecurityPort.ts

@@ -54,9 +54,9 @@ const authorizeAsync = async (
   if (!isGranted(input.grants, identity.actor, identity.capability))
     return denyAsync(input.audit, identity, targetHost, 'permission_denied');
   const approval = await input.approvalStore.getAsync(identity);
-  if (!approval || approval.status === 'pending')
+  if (approval?.status === 'pending')
     return denyAsync(input.audit, identity, targetHost, 'approval_pending');
-  if (approval.status !== 'approved' || !sameIdentity(approval.operation, identity))
+  if (approval?.status !== 'approved' || !sameIdentity(approval.operation, identity))
     return denyAsync(input.audit, identity, targetHost, 'approval_rejected');
   if (!(await input.operationStore.claimAsync(identity)))
     return denyAsync(input.audit, identity, targetHost, 'idempotency_conflict');

package/src/index.ts

@@ -1,9 +1,23 @@
 /*** Headless graph compilation and deterministic single-process execution. */
+export { createDurableRunAsync } from './features/execution/application/createDurableRunAsync.js';
 export { executeFlowAsync } from './features/execution/application/executeFlowAsync.js';
+export { calculateRetryDueAt } from './features/execution/domain/calculateRetryDueAt.js';
 export { compileFlowGraph } from './features/execution/domain/compileFlowGraph.js';
 export { createDefaultNodeRegistry } from './features/execution/domain/createDefaultNodeRegistry.js';
+export { createDurableRun } from './features/execution/domain/createDurableRun.js';
+export { createRetryWork } from './features/execution/domain/createRetryWork.js';
+export { isCronDueAt } from './features/execution/domain/isCronDueAt.js';
+export type { FlowPersistencePort } from './features/execution/ports/FlowPersistencePort.js';
 export { createFlowSecurityPort } from './features/security/application/createFlowSecurityPort.js';
 export { FlowSecurityError } from './features/security/FlowSecurityError.js';
+export type {
+  FlowDefinitionRef,
+  FlowDurableRun,
+  FlowDurableWork,
+  FlowOutboxRecord,
+  FlowRetryPolicy,
+  FlowRunCheckpoint,
+} from './types/durableExecution.js';
 export type {
   FlowClock,
   FlowCompiledGraph,

package/src/types/durableExecution.ts

@@ -0,0 +1,61 @@
+import type { DataContractValue } from '@ankhorage/contracts/data';
+
+import type { FlowSecurityOperation } from './security.js';
+
+export interface FlowDefinitionRef {
+  readonly id: string;
+  readonly version: number;
+}
+
+export interface FlowDurableRun {
+  readonly checkpoint?: FlowRunCheckpoint;
+  readonly createdAt: string;
+  readonly flow: FlowDefinitionRef;
+  readonly id: string;
+  readonly revision: number;
+  readonly status: 'cancelled' | 'failed' | 'queued' | 'running' | 'succeeded' | 'waiting_approval';
+  readonly updatedAt: string;
+}
+
+export interface FlowDurableWork {
+  readonly attempt: number;
+  readonly dueAt: string;
+  /** Explicitly separates side-effect-free internal work from a security-protected provider effect. */
+  readonly effectKind: 'internal' | 'protected';
+  readonly flow: FlowDefinitionRef;
+  readonly id: string;
+  readonly idempotencyKey?: string;
+  readonly lease?: {
+    readonly expiresAt: string;
+    readonly fencingToken: number;
+    readonly workerId: string;
+  };
+  readonly runId: string;
+  readonly securityOperation?: FlowSecurityOperation;
+  readonly stepId?: string;
+  readonly status: 'cancelled' | 'claimed' | 'completed' | 'ready';
+}
+
+export interface FlowRetryPolicy {
+  readonly baseDelayMs: number;
+  readonly maxAttempts: number;
+  readonly maxDelayMs: number;
+}
+
+/** Persisted state for each completed or in-flight Flow step. */
+export interface FlowRunCheckpoint {
+  readonly completedStepIds: readonly string[];
+  readonly data?: DataContractValue;
+  readonly failedStepIds: readonly string[];
+}
+
+/** A durable outbox record separates at-least-once delivery from an idempotent application effect. */
+export interface FlowOutboxRecord {
+  readonly createdAt: string;
+  readonly id: string;
+  readonly idempotencyKey: string;
+  readonly payload?: DataContractValue;
+  readonly runId: string;
+  readonly status: 'delivered' | 'pending';
+  readonly workId: string;
+}