@bastani/atomic 0.9.11-alpha.4 → 0.9.11-alpha.6

package/dist/builtin/workflows/src/durable/stage-topology-validation.ts

@@ -0,0 +1,234 @@
+import {
+  DURABLE_STAGE_TOPOLOGY_VERSION,
+  type DurableStageCheckpoint,
+  type DurableStageRunTopology,
+  type DurableStageTopology,
+} from "./types.js";
+
+/** Immutable source identity must agree before lifecycle records are merged. */
+export function immutableStageGroupError(stages: readonly DurableStageCheckpoint[]): string | undefined {
+  const occurrenceError = promptOccurrenceIdentityError(stages);
+  if (occurrenceError !== undefined) return occurrenceError;
+  const byReplayKey = groupByDurableStageKey(stages);
+  for (const group of byReplayKey.values()) {
+    const firstName = group[0]?.name;
+    if (group.some((stage) => stage.name !== firstName)) return "stage name drift within one replay-key group";
+    const topologies = group.flatMap((stage) => stage.topology === undefined ? [] : [stage.topology]);
+    const first = topologies[0];
+    if (first === undefined) continue;
+    if (topologies.some((topology) => topology.version !== DURABLE_STAGE_TOPOLOGY_VERSION
+      || topology.stageId !== first.stageId
+      || !sameStrings(topology.parentIds, first.parentIds)
+      || topology.sourceOrder !== first.sourceOrder
+      || !sameOptionalRun(topology.run, first.run))) {
+      return "immutable stage identity drift within one replay-key group";
+    }
+  }
+  return undefined;
+}
+
+/** Validate the complete direct-child DAG before any scoped cache can be exposed. */
+export function directChildTopologyError(
+  stages: readonly DurableStageCheckpoint[],
+  replayScope: string,
+  expectedRun: DurableStageRunTopology,
+  requireCurrentIdentity = true,
+  allowedNodeIds: ReadonlySet<string> = new Set(),
+): string | undefined {
+  const prefix = `${replayScope}:`;
+  const claiming = stages.filter((stage) => stage.topology?.run?.runId === expectedRun.runId);
+  if (claiming.some((stage) => !stage.replayKey.startsWith(prefix))) {
+    return "child run topology exists outside its durable invocation scope";
+  }
+  if (claiming.some((stage) => !sameRun(stage.topology?.run, expectedRun))) {
+    return "child checkpoint ownership is not reciprocal";
+  }
+
+  const directKeys = new Set(claiming.map((stage) => durableStageGroupKey(stage, stages)));
+  const direct = stages.filter((stage) => directKeys.has(durableStageGroupKey(stage, stages)));
+  const immutableError = immutableStageGroupError(direct);
+  if (immutableError !== undefined) return immutableError;
+
+  const merged: DurableStageTopology[] = [];
+  for (const group of groupByDurableStageKey(direct).values()) {
+    const topology = group.find((stage) => stage.topology?.run?.runId === expectedRun.runId)?.topology;
+    if (topology === undefined) return "direct child stage group lacks owning-run topology";
+    if (topology.version !== DURABLE_STAGE_TOPOLOGY_VERSION
+      || (requireCurrentIdentity && topology.sourceOrder === undefined)) {
+      return "direct child stage topology lacks current source identity";
+    }
+    if (topology.stageId.length === 0) return "direct child stage id is empty";
+    merged.push(topology);
+  }
+
+  const ids = new Set<string>(allowedNodeIds);
+  const stageIds = new Set<string>();
+  const orders = new Set<number>();
+  for (const topology of merged) {
+    if (stageIds.has(topology.stageId) || ids.has(topology.stageId)) return "direct child stage ids are not unique";
+    stageIds.add(topology.stageId);
+    ids.add(topology.stageId);
+    if (topology.sourceOrder !== undefined) {
+      if (orders.has(topology.sourceOrder)) return "direct child source orders are not unique";
+      orders.add(topology.sourceOrder);
+    }
+  }
+  if (merged.some((topology) => topology.parentIds.some((parentId) => !ids.has(parentId)))) {
+    return "direct child stage references an unknown parent";
+  }
+  return hasCycle(merged) ? "direct child stage topology contains a cycle" : undefined;
+}
+
+export function owningBoundaryIdError(
+  stages: readonly DurableStageCheckpoint[],
+  owningRunId: string,
+): string | undefined {
+  const starts = stages.filter((stage) => stage.topology?.run?.runId === owningRunId
+    && stage.topology.boundary?.event === "start");
+  const seen = new Map<string, string>();
+  for (const start of starts) {
+    const stageId = start.topology!.stageId;
+    if (stageId.length === 0) return "owning-run boundary stage id is empty";
+    const prior = seen.get(stageId);
+    if (prior !== undefined && prior !== start.replayKey) return "owning-run boundary stage id is aliased";
+    seen.set(stageId, start.replayKey);
+  }
+  return undefined;
+}
+
+export function sameRun(
+  actual: DurableStageRunTopology | undefined,
+  expected: DurableStageRunTopology,
+): boolean {
+  return actual !== undefined
+    && actual.runId === expected.runId && actual.runName === expected.runName
+    && actual.parentRunId === expected.parentRunId
+    && actual.parentStageId === expected.parentStageId
+    && actual.rootRunId === expected.rootRunId;
+}
+
+export function sameStrings(left: readonly string[], right: readonly string[]): boolean {
+  return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+
+function sameOptionalRun(
+  actual: DurableStageRunTopology | undefined,
+  expected: DurableStageRunTopology | undefined,
+): boolean {
+  if (actual === undefined || expected === undefined) return actual === expected;
+  return sameRun(actual, expected);
+}
+
+/** Reject prompt occurrence metadata that aliases another logical replay identity. */
+export function promptOccurrenceIdentityError(
+  stages: readonly DurableStageCheckpoint[],
+): string | undefined {
+  const replayByOccurrence = new Map<string, string>();
+  const occurrenceByReplayStage = new Map<string, string>();
+  const stageByReplayOccurrence = new Map<string, string>();
+  for (const stage of stages) {
+    const topology = stage.topology;
+    const occurrence = topology?.occurrenceKey;
+    if (topology === undefined || occurrence === undefined) continue;
+    const priorReplay = replayByOccurrence.get(occurrence);
+    if (priorReplay !== undefined && priorReplay !== stage.replayKey) {
+      return "prompt occurrence is bound to multiple replay keys";
+    }
+    replayByOccurrence.set(occurrence, stage.replayKey);
+    const replayStage = compositeKey("prompt-stage", stage.replayKey, topology.stageId);
+    const priorOccurrence = occurrenceByReplayStage.get(replayStage);
+    if (priorOccurrence !== undefined && priorOccurrence !== occurrence) {
+      return "prompt stage identity is bound to multiple occurrences";
+    }
+    occurrenceByReplayStage.set(replayStage, occurrence);
+    const replayOccurrence = compositeKey("prompt-occurrence", stage.replayKey, occurrence);
+    const priorStage = stageByReplayOccurrence.get(replayOccurrence);
+    if (priorStage !== undefined && priorStage !== topology.stageId) {
+      return "prompt occurrence is bound to multiple stage identities";
+    }
+    stageByReplayOccurrence.set(replayOccurrence, topology.stageId);
+  }
+  for (const legacy of stages) {
+    if (legacy.topology === undefined || legacy.topology.occurrenceKey !== undefined) continue;
+    const matches = stages.filter((current) => current.topology?.occurrenceKey !== undefined
+      && current.replayKey === legacy.replayKey
+      && current.topology.stageId === legacy.topology?.stageId);
+    if (matches.some((current) => !samePromptOccurrenceIdentity(legacy, current))) {
+      return "legacy prompt occurrence immutable identity drifted from current metadata";
+    }
+  }
+  return undefined;
+}
+
+/** Group prompt occurrences by replay + occurrence while retaining strict non-prompt replay grouping. */
+export function durableStageGroupKey(
+  stage: DurableStageCheckpoint,
+  stages: readonly DurableStageCheckpoint[] = [stage],
+): string {
+  const occurrence = stage.topology?.occurrenceKey ?? matchingCurrentOccurrence(stage, stages);
+  return occurrence === undefined
+    ? compositeKey("stage-replay", stage.replayKey)
+    : compositeKey("prompt-occurrence", stage.replayKey, occurrence);
+}
+
+export function groupByDurableStageKey(
+  stages: readonly DurableStageCheckpoint[],
+): Map<string, DurableStageCheckpoint[]> {
+  const groups = new Map<string, DurableStageCheckpoint[]>();
+  for (const stage of stages) {
+    const key = durableStageGroupKey(stage, stages);
+    const group = groups.get(key) ?? [];
+    group.push(stage);
+    groups.set(key, group);
+  }
+  return groups;
+}
+
+function matchingCurrentOccurrence(
+  legacy: DurableStageCheckpoint,
+  stages: readonly DurableStageCheckpoint[],
+): string | undefined {
+  if (legacy.topology === undefined) return undefined;
+  const matches = stages.filter((current) => current.topology?.occurrenceKey !== undefined
+    && current.replayKey === legacy.replayKey
+    && current.topology.stageId === legacy.topology?.stageId
+    && samePromptOccurrenceIdentity(legacy, current));
+  const occurrences = new Set(matches.map((current) => current.topology!.occurrenceKey!));
+  return occurrences.size === 1 ? occurrences.values().next().value : undefined;
+}
+
+function samePromptOccurrenceIdentity(
+  legacy: DurableStageCheckpoint,
+  current: DurableStageCheckpoint,
+): boolean {
+  const left = legacy.topology;
+  const right = current.topology;
+  return left !== undefined && right !== undefined
+    && legacy.name === current.name
+    && left.version === right.version
+    && left.stageId === right.stageId
+    && sameStrings(left.parentIds, right.parentIds)
+    && left.sourceOrder === right.sourceOrder
+    && sameOptionalRun(left.run, right.run)
+    && left.boundary === undefined && right.boundary === undefined;
+}
+
+function compositeKey(domain: string, ...parts: readonly string[]): string {
+  return JSON.stringify([domain, ...parts]);
+}
+
+function hasCycle(topologies: readonly DurableStageTopology[]): boolean {
+  const parents = new Map(topologies.map((topology) => [topology.stageId, topology.parentIds]));
+  const visiting = new Set<string>();
+  const visited = new Set<string>();
+  const cyclic = (stageId: string): boolean => {
+    if (visiting.has(stageId)) return true;
+    if (visited.has(stageId)) return false;
+    visiting.add(stageId);
+    if ((parents.get(stageId) ?? []).some(cyclic)) return true;
+    visiting.delete(stageId);
+    visited.add(stageId);
+    return false;
+  };
+  return topologies.some((topology) => cyclic(topology.stageId));
+}

package/dist/builtin/workflows/src/durable/stage-topology.ts

@@ -0,0 +1,53 @@
+import type { StageSnapshot } from "../shared/store-types.js";
+import type { DurableWorkflowBackend } from "./backend.js";
+import {
+  DURABLE_STAGE_TOPOLOGY_VERSION,
+  type DurableStageCheckpoint,
+  type DurableStageRunTopology,
+  type DurableStageTopology,
+} from "./types.js";
+
+/** Find source identity for the latest active session at an exact replay key. */
+export function activeStageTopology(
+  backend: DurableWorkflowBackend,
+  workflowId: string,
+  replayKey: string,
+): DurableStageTopology | undefined {
+  const checkpoints = backend.listCheckpoints(workflowId);
+  for (let index = checkpoints.length - 1; index >= 0; index -= 1) {
+    const checkpoint = checkpoints[index];
+    if (checkpoint?.kind !== "stage" || checkpoint.replayKey !== replayKey) continue;
+    const topology = checkpoint.topology;
+    if (topology !== undefined && (topology.run === undefined || topology.run.runId === workflowId)) return topology;
+  }
+  return undefined;
+}
+
+export function durableStageCheckpointMetadata(
+  stage: StageSnapshot,
+  run?: DurableStageRunTopology,
+  sourceOrder?: number,
+): Partial<DurableStageCheckpoint> {
+  return {
+    topology: {
+      version: DURABLE_STAGE_TOPOLOGY_VERSION,
+      stageId: stage.id,
+      parentIds: [...stage.parentIds],
+      ...(stage.executionOrder !== undefined ? { order: stage.executionOrder } : {}),
+      ...(sourceOrder !== undefined && sourceOrder >= 0 ? { sourceOrder } : {}),
+      ...(stage.promptFootprint !== undefined ? { occurrenceKey: stage.id } : {}),
+      status: stage.status,
+      ...(run !== undefined ? { run: { ...run } } : {}),
+    },
+    ...(stage.startedAt !== undefined ? { startedAt: stage.startedAt } : {}),
+    ...(stage.endedAt !== undefined ? { endedAt: stage.endedAt } : {}),
+    ...(stage.result !== undefined ? { result: stage.result } : {}),
+    ...(stage.sessionId !== undefined ? { sessionId: stage.sessionId } : {}),
+    ...(stage.sessionFile !== undefined ? { sessionFile: stage.sessionFile } : {}),
+    ...(stage.durationMs !== undefined ? { durationMs: stage.durationMs } : {}),
+    ...(stage.model !== undefined ? { model: stage.model } : {}),
+    ...(stage.fastMode !== undefined ? { fastMode: stage.fastMode } : {}),
+    ...(stage.attemptedModels !== undefined ? { attemptedModels: [...stage.attemptedModels] } : {}),
+    ...(stage.modelAttempts !== undefined ? { modelAttempts: [...stage.modelAttempts] } : {}),
+  };
+}

package/dist/builtin/workflows/src/durable/tool-failure-checkpoint.ts

@@ -0,0 +1,49 @@
+import type { ToolNodeSnapshot } from "../shared/store-types.js";
+import type { DurableWorkflowBackend } from "./backend.js";
+import { workflowToolFailure } from "./tool-outcome.js";
+import { DURABLE_TOOL_TOPOLOGY_VERSION, type DurableStageRunTopology } from "./types.js";
+
+export interface ThrowingToolFailureCheckpointInput {
+  readonly workflowId: string;
+  readonly backend: DurableWorkflowBackend;
+  readonly nextCheckpointId: () => string;
+  readonly runTopology?: DurableStageRunTopology;
+}
+
+/** Persist a throwing failure for inspection without making it replayable. */
+export async function recordThrowingToolFailure(
+  input: ThrowingToolFailureCheckpointInput,
+  node: ToolNodeSnapshot,
+  identity: {
+    readonly name: string;
+    readonly argsHash: string;
+    readonly ordinal: number;
+    readonly startedAt: number;
+  },
+  error: unknown,
+  attempts: number,
+): Promise<{ readonly message: string; readonly failedAt: number }> {
+  const message = workflowToolFailure(error, attempts, false).error.message;
+  const failedAt = Date.now();
+  await input.backend.recordAdditiveCheckpointBestEffort({
+    kind: "tool",
+    workflowId: input.workflowId,
+    checkpointId: `tool-failure:${identity.argsHash}:${input.nextCheckpointId()}`,
+    name: identity.name,
+    argsHash: identity.argsHash,
+    output: null,
+    throwingFailureError: message,
+    completedAt: failedAt,
+    topology: {
+      version: DURABLE_TOOL_TOPOLOGY_VERSION,
+      nodeId: node.id,
+      ordinal: identity.ordinal,
+      order: node.executionOrder ?? 0,
+      parentIds: [...node.parentIds],
+      startedAt: identity.startedAt,
+      endedAt: failedAt,
+      ...(input.runTopology !== undefined ? { run: { ...input.runTopology } } : {}),
+    },
+  });
+  return { message, failedAt };
+}

package/dist/builtin/workflows/src/durable/tool-outcome.ts

@@ -0,0 +1,120 @@
+import type {
+  WorkflowSerializableValue,
+  WorkflowToolError,
+  WorkflowToolFailure,
+  WorkflowToolOutcome,
+  WorkflowToolSuccess,
+} from "../shared/types.js";
+import { errorMessage, errorName, field, redactSensitiveText, selectProcessFailureError } from "../shared/workflow-failures-signals.js";
+
+export const TOOL_FAILURE_TEXT_LIMIT_BYTES = 16_384;
+const TRUNCATION_PREFIX = "[workflow tool output truncated; showing final bytes]\n";
+
+function safeField(error: unknown, key: string): unknown {
+  try {
+    return field(error, key);
+  } catch {
+    return undefined;
+  }
+}
+
+function exposedText(error: unknown, key: "stdout" | "stderr"): string | undefined {
+  const value = safeField(error, key);
+  if (typeof value === "string") return value;
+  try {
+    if (value instanceof ArrayBuffer) return new TextDecoder().decode(value);
+    if (ArrayBuffer.isView(value)) {
+      return new TextDecoder().decode(new Uint8Array(value.buffer, value.byteOffset, value.byteLength));
+    }
+  } catch {
+    return undefined;
+  }
+  return undefined;
+}
+
+export function boundedSafeToolFailureText(value: string): string {
+  const redacted = redactSensitiveText(value);
+  const bytes = new TextEncoder().encode(redacted);
+  if (bytes.byteLength <= TOOL_FAILURE_TEXT_LIMIT_BYTES) return redacted;
+  const prefix = new TextEncoder().encode(TRUNCATION_PREFIX);
+  const tailLength = Math.max(0, TOOL_FAILURE_TEXT_LIMIT_BYTES - prefix.byteLength);
+  let start = bytes.byteLength - tailLength;
+  const decoder = new TextDecoder("utf-8", { fatal: true });
+  while (start < bytes.byteLength) {
+    try {
+      return TRUNCATION_PREFIX + decoder.decode(bytes.slice(start));
+    } catch {
+      start += 1;
+    }
+  }
+  return TRUNCATION_PREFIX.slice(0, TOOL_FAILURE_TEXT_LIMIT_BYTES);
+}
+
+function safeErrorText(error: unknown): string {
+  try {
+    return String(error);
+  } catch {
+    return "Tool callback failed";
+  }
+}
+
+export function normalizeWorkflowToolError(error: unknown): WorkflowToolError {
+  error = selectProcessFailureError(error);
+  const exitCode = safeField(error, "exitCode");
+  const stdout = exposedText(error, "stdout");
+  const stderr = exposedText(error, "stderr");
+  let message: string;
+  let name: string;
+  try {
+    message = errorMessage(error);
+  } catch {
+    message = safeErrorText(error);
+  }
+  try {
+    name = errorName(error) ?? "Error";
+  } catch {
+    name = "Error";
+  }
+  return {
+    name: boundedSafeToolFailureText(name),
+    message: boundedSafeToolFailureText(message),
+    ...(typeof exitCode === "number" && Number.isInteger(exitCode) ? { exitCode } : {}),
+    ...(stdout !== undefined ? { stdout: boundedSafeToolFailureText(stdout) } : {}),
+    ...(stderr !== undefined ? { stderr: boundedSafeToolFailureText(stderr) } : {}),
+  };
+}
+
+export function workflowToolSuccess<TValue extends WorkflowSerializableValue>(
+  value: TValue,
+  attempts: number,
+  cached: boolean,
+): WorkflowToolSuccess<TValue> {
+  return { ok: true, value, attempts, cached };
+}
+
+export function workflowToolFailure(error: unknown, attempts: number, cached: boolean): WorkflowToolFailure {
+  return { ok: false, error: normalizeWorkflowToolError(error), attempts, cached };
+}
+
+export function workflowToolOutcomeFromValue<TValue extends WorkflowSerializableValue>(
+  value: WorkflowSerializableValue,
+): WorkflowToolOutcome<TValue> | undefined {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return undefined;
+  const candidate = value as Record<string, WorkflowSerializableValue>;
+  if (!Number.isInteger(candidate["attempts"]) || typeof candidate["cached"] !== "boolean") return undefined;
+  if (candidate["ok"] === true && "value" in candidate) return candidate as WorkflowToolSuccess<TValue>;
+  const error = candidate["error"];
+  if (candidate["ok"] !== false || error === null || typeof error !== "object" || Array.isArray(error)) return undefined;
+  const details = error as Record<string, WorkflowSerializableValue>;
+  if (typeof details["name"] !== "string" || typeof details["message"] !== "string"
+    || (details["exitCode"] !== undefined && !Number.isInteger(details["exitCode"]))
+    || (details["stdout"] !== undefined && typeof details["stdout"] !== "string")
+    || (details["stderr"] !== undefined && typeof details["stderr"] !== "string")) return undefined;
+  return candidate as WorkflowToolFailure;
+}
+
+export function replayedWorkflowToolOutcome<TValue extends WorkflowSerializableValue>(
+  outcome: WorkflowToolOutcome<TValue>,
+): WorkflowToolOutcome<TValue> {
+  return { ...outcome, cached: true };
+}