@bastani/atomic 0.9.16-alpha.1 → 0.9.16-alpha.3

package/dist/builtin/workflows/src/durable/scoped-backend.ts

@@ -1,308 +0,0 @@
-/**
- * Scoped durable backend for child workflow runs.
- *
- * A child workflow launched via `ctx.workflow(child)` runs with its own run id,
- * but its internal `ctx.tool` / `ctx.ui` / `ctx.stage` side effects must be
- * checkpointed under the PARENT (root) durable workflow so that an interrupted
- * child does not re-execute completed side effects when the parent is resumed.
- *
- * Without scoping, child checkpoints are written under a fresh per-run UUID
- * that is never recovered on resume, so a re-dispatched child loses all of its
- * prior checkpoints and re-runs side effects (split-brain). {@link ScopedDurableBackend}
- * remaps every checkpoint identity to the root workflow id, prefixed by a stable
- * child boundary key, so the same side effects are recovered on resume.
- *
- * Only checkpoint read/write methods are scoped. Root lifecycle, catalog,
- * metadata, and deletion methods are no-ops because child runs are not
- * independently addressable.
- *
- * cross-ref: issue #1498 — child side effects under the root durable workflow.
- */
-
-import type { WorkflowSerializableValue } from "../shared/types.js";
-import type {
-	DurableInactiveDeleteResult,
-	DurableWorkflowBackend,
-	DurableWorkflowCatalogEntries,
-	DurableWorkflowHydrationResult,
-	WorkflowRegistrationInput,
-} from "./backend.js";
-import {
-	claimDurablePromptToken,
-	durablePromptScope,
-	type PromptReservationToken,
-	releaseDurablePrompt,
-	reserveDurablePrompt,
-} from "./prompt-reservations.js";
-import type {
-	DurableCheckpoint,
-	DurableStageCheckpoint,
-	DurableWorkflowStatus,
-	ResumableWorkflowEntry,
-} from "./types.js";
-
-/**
- * Durable scope for a child workflow run.
- *
- * - `rootWorkflowId`: the top-level workflow id under which checkpoints persist.
- * - `scopePrefix`: a stable boundary key (e.g. `workflow:<name>:<ordinal>`)
- *   unique within the root so multiple children (and the root itself) do not
- *   collide.
- */
-export interface DurableScope {
-	readonly rootWorkflowId: string;
-	readonly scopePrefix: string;
-}
-
-/**
- * Wrap a durable backend so all checkpoint identities for a child run are
- * namespaced under the root workflow. The wrapped backend is the source of
- * truth; this wrapper only translates keys.
- */
-export class ScopedDurableBackend implements DurableWorkflowBackend {
-	public readonly persistent: boolean;
-	private readonly inner: DurableWorkflowBackend;
-	private readonly scope: DurableScope;
-
-	constructor(inner: DurableWorkflowBackend, scope: DurableScope) {
-		this.inner = inner;
-		this.scope = scope;
-		this.persistent = inner.persistent;
-	}
-
-	registerWorkflow(_handle: WorkflowRegistrationInput): void {
-		// Child runs are not independently resumable; only the root is registered.
-	}
-
-	recordCheckpoint(checkpoint: DurableCheckpoint): void {
-		this.inner.recordCheckpoint(this.remap(checkpoint));
-	}
-
-	async recordCheckpointAsync(checkpoint: DurableCheckpoint): Promise<void> {
-		await this.inner.recordCheckpointAsync(this.remap(checkpoint));
-	}
-
-	async recordAdditiveCheckpointBestEffort(checkpoint: DurableCheckpoint): Promise<boolean> {
-		return await this.inner.recordAdditiveCheckpointBestEffort(this.remap(checkpoint));
-	}
-
-	flush(): Promise<void> {
-		return this.inner.flush();
-	}
-
-	getToolOutput(_workflowId: string, argsHash: string): WorkflowSerializableValue | undefined {
-		return this.inner.getToolOutput(this.scope.rootWorkflowId, this.scopeKey(argsHash));
-	}
-
-	getToolCheckpoint(_workflowId: string, argsHash: string) {
-		return this.inner.getToolCheckpoint(this.scope.rootWorkflowId, this.scopeKey(argsHash));
-	}
-
-	getUiResponse(_workflowId: string, promptHash: string): WorkflowSerializableValue | undefined {
-		return this.inner.getUiResponse(this.scope.rootWorkflowId, this.scopeKey(promptHash));
-	}
-
-	getStageOutput(_workflowId: string, replayKey: string): WorkflowSerializableValue | undefined {
-		return this.inner.getStageOutput(this.scope.rootWorkflowId, this.scopeKey(replayKey));
-	}
-
-	getStageSession(
-		_workflowId: string,
-		replayKey: string,
-	):
-		| {
-				sessionId?: string;
-				sessionFile?: string;
-				startedAt?: number;
-				durationMs?: number;
-		  }
-		| undefined {
-		return this.inner.getStageSession(this.scope.rootWorkflowId, this.scopeKey(replayKey));
-	}
-
-	listCheckpoints(workflowId: string): readonly DurableCheckpoint[] {
-		const prefix = `${this.scope.scopePrefix}:`;
-		return this.inner
-			.listCheckpoints(this.scope.rootWorkflowId)
-			.filter((checkpoint) => checkpointHasPrefix(checkpoint, prefix))
-			.map((checkpoint) => localCheckpoint(checkpoint, workflowId, prefix));
-	}
-
-	getWorkflow(_workflowId: string): undefined {
-		// Child runs have no independent resumable handle.
-		return undefined;
-	}
-
-	getLoadableWorkflow(_workflowId: string): undefined {
-		return undefined;
-	}
-
-	setWorkflowStatus(
-		_workflowId: string,
-		_status: DurableWorkflowStatus,
-		_pendingPrompts?: number,
-		_resumable?: boolean,
-	): void {
-		// No-op: child status is reflected via the root workflow boundary.
-	}
-
-	async transitionWorkflowStatus(
-		_workflowId: string,
-		_expectedStatuses: readonly DurableWorkflowStatus[],
-		_status: DurableWorkflowStatus,
-		_pendingPrompts?: number,
-		_resumable?: boolean,
-	): Promise<boolean> {
-		return false;
-	}
-
-	adjustPendingPrompts(_workflowId: string, delta: number): void {
-		this.inner.adjustPendingPrompts(this.scope.rootWorkflowId, delta);
-	}
-
-	promptReservationScope(_workflowId: string): { readonly rootWorkflowId: string; readonly scope: string } {
-		return this.effectivePromptScope();
-	}
-
-	pendingPromptToken(_workflowId: string, reservationId: string): PromptReservationToken | undefined {
-		return claimDurablePromptToken(this.inner, this.scope.rootWorkflowId, reservationId);
-	}
-
-	reservePendingPrompt(_workflowId: string, reservationId: string): PromptReservationToken {
-		return reserveDurablePrompt(this.inner, this.scope.rootWorkflowId, reservationId);
-	}
-
-	releasePendingPrompt(_workflowId: string, reservationId: string, token: PromptReservationToken): void {
-		releaseDurablePrompt(this.inner, this.scope.rootWorkflowId, reservationId, token);
-	}
-
-	listResumableWorkflows(): readonly ResumableWorkflowEntry[] {
-		return [];
-	}
-
-	listCompletedWorkflows(): readonly ResumableWorkflowEntry[] {
-		return [];
-	}
-
-	async prepareWorkflowCatalog(): Promise<DurableWorkflowCatalogEntries> {
-		return { resumable: [], completed: [] };
-	}
-
-	toMetadata(_workflowId: string): undefined {
-		return undefined;
-	}
-
-	async deleteWorkflow(_workflowId: string): Promise<void> {
-		// No-op: scoped children never own or delete root durable state.
-	}
-
-	async deleteWorkflowIfInactive(_workflowId: string): Promise<DurableInactiveDeleteResult> {
-		return { ok: false, reason: "not_found" };
-	}
-
-	isWorkflowLoadable(_workflowId: string): boolean {
-		return false;
-	}
-
-	reset(): void {
-		// No-op: scoped backends never own root state.
-	}
-
-	hydrateWorkflow(_workflowId: string): Promise<void> {
-		return Promise.resolve();
-	}
-	hydrateWorkflowForInspection(_workflowId: string): Promise<DurableWorkflowHydrationResult> {
-		return Promise.resolve({ kind: "absent" });
-	}
-
-	hydrateResumableWorkflows(): Promise<void> {
-		return Promise.resolve();
-	}
-
-	private effectivePromptScope(): { readonly rootWorkflowId: string; readonly scope: string } {
-		const parent = durablePromptScope(this.inner, this.scope.rootWorkflowId);
-		const scope = parent.scope === "root" ? this.scope.scopePrefix : `${parent.scope}:${this.scope.scopePrefix}`;
-		return {
-			rootWorkflowId: parent.rootWorkflowId,
-			scope,
-		};
-	}
-
-	private scopeKey(key: string): string {
-		return `${this.scope.scopePrefix}:${key}`;
-	}
-
-	private remap(checkpoint: DurableCheckpoint): DurableCheckpoint {
-		const workflowId = this.scope.rootWorkflowId;
-		if (checkpoint.kind === "tool") {
-			return {
-				...checkpoint,
-				workflowId,
-				checkpointId: this.scopeKey(checkpoint.checkpointId),
-				argsHash: this.scopeKey(checkpoint.argsHash),
-			};
-		}
-		if (checkpoint.kind === "ui") {
-			return {
-				...checkpoint,
-				workflowId,
-				checkpointId: this.scopeKey(checkpoint.checkpointId),
-				promptHash: this.scopeKey(checkpoint.promptHash),
-			};
-		}
-		return {
-			...checkpoint,
-			workflowId,
-			checkpointId: this.scopeKey(checkpoint.checkpointId),
-			replayKey: this.scopeKey(checkpoint.replayKey),
-			...remappedBoundaryScope(checkpoint, this.scopeKey(checkpoint.topology?.boundary?.replayScope ?? "")),
-		};
-	}
-}
-
-/** Return true only when every stored identity belongs to this immediate scope. */
-function checkpointHasPrefix(checkpoint: DurableCheckpoint, prefix: string): boolean {
-	if (!checkpoint.checkpointId.startsWith(prefix)) return false;
-	if (checkpoint.kind === "tool") return checkpoint.argsHash.startsWith(prefix);
-	if (checkpoint.kind === "ui") return checkpoint.promptHash.startsWith(prefix);
-	return checkpoint.replayKey.startsWith(prefix);
-}
-
-/** Strip exactly one wrapper prefix to expose a composable child-local view. */
-function localCheckpoint(checkpoint: DurableCheckpoint, workflowId: string, prefix: string): DurableCheckpoint {
-	const checkpointId = checkpoint.checkpointId.slice(prefix.length);
-	if (checkpoint.kind === "tool") {
-		return { ...checkpoint, workflowId, checkpointId, argsHash: checkpoint.argsHash.slice(prefix.length) };
-	}
-	if (checkpoint.kind === "ui") {
-		return { ...checkpoint, workflowId, checkpointId, promptHash: checkpoint.promptHash.slice(prefix.length) };
-	}
-	const replayKey = checkpoint.replayKey.slice(prefix.length);
-	const replayScope = stripOnePrefix(checkpoint.topology?.boundary?.replayScope, prefix);
-	return {
-		...checkpoint,
-		workflowId,
-		checkpointId,
-		replayKey,
-		...remappedBoundaryScope(checkpoint, replayScope),
-	};
-}
-
-function remappedBoundaryScope(
-	checkpoint: DurableStageCheckpoint,
-	replayScope: string | undefined,
-): Pick<DurableStageCheckpoint, "topology"> | Record<string, never> {
-	const topology = checkpoint.topology;
-	if (topology?.boundary === undefined || replayScope === undefined) return {};
-	return {
-		topology: {
-			...topology,
-			boundary: { ...topology.boundary, replayScope },
-		},
-	};
-}
-
-function stripOnePrefix(value: string | undefined, prefix: string): string | undefined {
-	if (value === undefined || !value.startsWith(prefix)) return value;
-	return value.slice(prefix.length);
-}