@stigmer/server 3.14.0-dev.20260910084630

package/src/domain/workflowexecution/constants.ts

@@ -0,0 +1,102 @@
+/**
+ * WorkflowExecution byte-pinned wire copy and identifiers — every string a
+ * client or the Temporal wire can observe from this domain, copied
+ * character-for-character from the Go controller
+ * (pkg/domain/workflowexecution/controller). Coexistence rule: the Go
+ * server is the behavioral reference; do not "improve" copy here
+ * (guidelines §2).
+ */
+
+/**
+ * create's engine-gate refusal (create.go engineUnavailableMessage) —
+ * deliberately identical across AgentExecution and WorkflowExecution so
+ * both domains present one symmetric create-boundary contract. Pinned by
+ * the Class A conformance engine-gate test.
+ */
+export const ENGINE_UNAVAILABLE_MESSAGE =
+  "The execution engine is temporarily unavailable. Please try again shortly.";
+
+/**
+ * The lifecycle steps' engineless refusal (lifecycle_steps.go, five
+ * sites: pause/resume/cancel/terminate signal steps and recover's
+ * terminate-existing). FailedPrecondition, not Unavailable — the ratified
+ * Go asymmetry between the create gate and the lifecycle surface.
+ */
+export const TEMPORAL_UNAVAILABLE_MESSAGE = "Temporal is not available";
+
+/**
+ * Recover's fresh-start refusal (lifecycle_steps.go
+ * StartFreshWorkflowStep) — the creator-specific variant of the message
+ * above, also FailedPrecondition.
+ */
+export const TEMPORAL_UNAVAILABLE_CREATOR_MESSAGE =
+  "Temporal is not available (workflow creator not set)";
+
+/**
+ * sendSignal's engineless refusal (send_signal.go SendSignalToWorkflowStep)
+ * — FailedPrecondition with its own copy, distinct from both messages
+ * above.
+ */
+export const WORKFLOW_CREATOR_UNAVAILABLE_MESSAGE =
+  "workflow creator is not available";
+
+/**
+ * The Go orchestrator workflow name (temporal/workflows
+ * InvokeWorkflowExecutionWorkflowName) — a cross-edition Temporal wire
+ * constant; the orchestrator's workflow ID is `{name}/{executionId}`.
+ */
+export const INVOKE_WORKFLOW_EXECUTION_WORKFLOW_NAME =
+  "stigmer/workflow-execution/invoke";
+
+/** The orchestrator workflow ID for an execution (lifecycle_steps.go). */
+export function orchestratorWorkflowId(executionId: string): string {
+  return `${INVOKE_WORKFLOW_EXECUTION_WORKFLOW_NAME}/${executionId}`;
+}
+
+/**
+ * The TS runner child workflow ID (lifecycle_steps.go
+ * TerminateExistingWorkflowStep: "workflow-exec-" + executionID). The
+ * child has ParentClosePolicy=REQUEST_CANCEL, so recover terminates it
+ * explicitly for a hard ID-reuse guarantee.
+ */
+export function childWorkflowId(executionId: string): string {
+  return `workflow-exec-${executionId}`;
+}
+
+/**
+ * Signal channel names on the orchestrator (temporal/workflows). pause and
+ * resume are handled by Go's single selector goroutine; every other signal
+ * rides the generic relaySignal envelope (June DD-013).
+ */
+export const PAUSE_SIGNAL_NAME = "pause";
+export const RESUME_SIGNAL_NAME = "resume";
+export const RELAY_SIGNAL_CHANNEL_NAME = "relaySignal";
+
+/**
+ * submitWorkflowTaskApproval's signal-name prefix
+ * (submit_workflow_task_approval.go humanInputSignalPrefix): the runner
+ * listens on `human_input_{taskName}`.
+ */
+export const HUMAN_INPUT_SIGNAL_PREFIX = "human_input_";
+
+/**
+ * getEventLog pagination bounds (get_event_log.go): requests default to
+ * 100 events and are capped at 500 — the pinned CW-7 pagination contract.
+ */
+export const DEFAULT_EVENT_PAGE_SIZE = 100;
+export const MAX_EVENT_PAGE_SIZE = 500;
+
+/**
+ * listPendingApprovals pagination bounds (list_pending_approvals.go):
+ * default 20, cap 100.
+ */
+export const DEFAULT_PENDING_APPROVALS_PAGE_SIZE = 20;
+export const MAX_PENDING_APPROVALS_PAGE_SIZE = 100;
+
+/**
+ * subscribeEvents' live-tail poll interval (subscribe_events.go
+ * eventPollInterval = 500ms): the latency floor Go chose for event
+ * delivery after replay; faster polling buys little (the runner batches
+ * updates through updateStatus) and multiplies read load per subscriber.
+ */
+export const EVENT_POLL_INTERVAL_MS = 500;

package/src/domain/workflowexecution/controller.ts

@@ -0,0 +1,564 @@
+/**
+ * WorkflowExecution controller — ports pkg/domain/workflowexecution/
+ * controller (command + query sides): the workflow-run record surface.
+ * One Go controller implements both services; this module mirrors that
+ * with one deps object and one registration function.
+ *
+ * Pipeline per RPC mirrors the Go step chains character-for-character;
+ * the list/summary/pending-approval reads are direct handlers, exactly as
+ * Go writes them (no pipeline in list.go / list_by_workflow.go /
+ * get_execution_summary.go / list_pending_approvals.go).
+ *
+ * Proven by workflowexecution.conformance.test.ts
+ * (CONFORMANCE_TARGET=local) and __tests__/.
+ *
+ * Versus Stigmer Cloud, OSS excludes the Authorize, Publish,
+ * PublishToRedis, and TransformResponse steps (no multi-tenant auth,
+ * event publishing, or Redis here — subscribe streams ride in-memory
+ * channels per ADR 011).
+ */
+import type { ConnectRouter, HandlerContext } from "@connectrpc/connect";
+
+import { WorkflowExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
+import type { WorkflowExecution } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
+import { WorkflowExecutionCommandController } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/command_pb";
+import { ExecutionSortField } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/io_pb";
+import { WorkflowExecutionListSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/io_pb";
+import type {
+  ListWorkflowExecutionsByWorkflowRequest,
+  ListWorkflowExecutionsRequest,
+  WorkflowExecutionId,
+  WorkflowExecutionList,
+} from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/io_pb";
+import { WorkflowExecutionQueryController } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/query_pb";
+import type { ApiResourceId } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { create } from "@bufbuild/protobuf";
+
+import type { Logger } from "../../boot/logger.js";
+import type { Authorizer } from "../../extensions/authorizer.js";
+import type { ResolvedGateSteps } from "../../extensions/gate-slots.js";
+import { stepsForSlot } from "../../extensions/gate-slots.js";
+import type { ListReadScope } from "../../extensions/list-read-scope.js";
+import { restrictListByReadScope } from "../../extensions/list-read-scope.js";
+import type { CallerIdentity } from "../../extensions/identity.js";
+import type { ResourceAuthorizationLifecycle } from "../../extensions/resource-authorization.js";
+import { internalError, invalidArgumentError } from "../../pipeline/errors.js";
+import { apiResourceKindKey } from "../../pipeline/interceptors/apiresource.js";
+import { newPipeline } from "../../pipeline/pipeline.js";
+import { callerIdentityOf } from "../../pipeline/interceptors/auth.js";
+import { RequestContext } from "../../pipeline/request-context.js";
+import { newAuthorizeStep } from "../../pipeline/steps/authorize.js";
+import { newGuardReservedLabelsStep } from "../../pipeline/steps/guard-reserved-labels.js";
+import { newBuildUpdateStateStep } from "../../pipeline/steps/build-update-state.js";
+import { newBuildNewStateStep } from "../../pipeline/steps/defaults.js";
+import { newCheckDuplicateStep } from "../../pipeline/steps/duplicate.js";
+import { newValidateVisibilityStep } from "../../pipeline/steps/validate-visibility.js";
+import {
+  newDeleteResourceStep,
+  newExtractResourceIdStep,
+  newLoadExistingForDeleteStep,
+} from "../../pipeline/steps/delete.js";
+import {
+  newDeleteSearchIndexStep,
+  newIndexSearchStep,
+} from "../../pipeline/steps/index-search.js";
+import {
+  EXISTING_RESOURCE_KEY,
+  newLoadExistingStep,
+} from "../../pipeline/steps/load-existing.js";
+import {
+  TARGET_RESOURCE_KEY,
+  newLoadTargetStep,
+} from "../../pipeline/steps/load-target.js";
+import { newNormalizeReferencesStep } from "../../pipeline/steps/references.js";
+import {
+  newCleanupIamPoliciesStep,
+  newCreateAuthorizationTuplesStep,
+} from "../../pipeline/steps/authorization-tuples.js";
+import { newPersistStep } from "../../pipeline/steps/persist.js";
+import { newResolveSlugStep } from "../../pipeline/steps/slug.js";
+import { newValidateProtoStep } from "../../pipeline/steps/validation.js";
+import type { Store } from "../../store/interface.js";
+
+import type { AgentExecutionApprovalForwarderProvider } from "./submit-approval.js";
+import { submitApproval } from "./submit-approval.js";
+import type { AgentExecutionFileDecisionForwarderProvider } from "./submit-file-decision.js";
+import { submitFileDecision } from "./submit-file-decision.js";
+import { submitWorkflowTaskApproval } from "./submit-workflow-task-approval.js";
+import type { ExecutionWorkflowInstanceCreatorProvider } from "./create-steps.js";
+import {
+  newCreateDefaultInstanceIfNeededStep,
+  newSetInitialPhaseStep,
+  newStartWorkflowStep,
+  newValidateWorkflowOrInstanceStep,
+} from "./create-steps.js";
+import type { WorkflowExecutionContextBuilderDeps } from "./create-execution-context-step.js";
+import { newCreateExecutionContextStep } from "./create-execution-context-step.js";
+import type { WorkflowExecutionEngineStateProvider } from "./engine.js";
+import { newEnsureEngineAvailableStep } from "./engine.js";
+import {
+  applyFilterCriteria,
+  applyLegacyPhaseFilter,
+  applySortField,
+} from "./execution-filter.js";
+import {
+  cancelExecution,
+  pauseExecution,
+  recoverExecution,
+  resumeExecution,
+  terminateExecution,
+} from "./lifecycle.js";
+import { newNormalizeWorkflowRefStep } from "./normalize-workflow-ref-step.js";
+import { newPinWorkflowVersionStep } from "./pin-workflow-version-step.js";
+import { sendSignal } from "./send-signal.js";
+import { getEventLog } from "./get-event-log.js";
+import { getExecutionSummary } from "./get-execution-summary.js";
+import { listPendingApprovals } from "./list-pending-approvals.js";
+import { loadAllWorkflowExecutions } from "./queries.js";
+import { workflowExecutionSearchExtractor } from "./search-extractor.js";
+import type { SandboxLane } from "../../sandbox/lane.js";
+import type { WorkflowSandboxTerminalObserver } from "../../sandbox/steps.js";
+import { newEnsureWorkflowSandboxStep } from "../../sandbox/steps.js";
+import type { WorkflowExecutionTemporalConfig } from "./temporal/config.js";
+import type { StreamBroker } from "./stream-broker.js";
+import { subscribeExecution } from "./subscribe.js";
+import { subscribeEvents } from "./subscribe-events.js";
+import { updateStatus } from "./update-status.js";
+
+export interface WorkflowExecutionControllerDeps {
+  readonly store: Store;
+  readonly logger: Logger;
+  /** The composed authorization seam — the Authorize step at position 1 of every chain calls it (O2, DD-007 §3). */
+  readonly authorizer: Authorizer;
+  /** The composed tuple-lifecycle driver — undefined = the shared steps no-op (C2). */
+  readonly authorizationLifecycle: ResourceAuthorizationLifecycle | undefined;
+  /** The composed summary read scope — undefined = the OSS full scan (C2 Stage 4). */
+  readonly listReadScope: ListReadScope | undefined;
+  /**
+   * The merged slot registrations (O1/O4; DD-006 §2). This domain
+   * carries `sandbox-acquisition:gate` on the create and recover chains
+   * at the Java-verified capacity-gate position (C4, 20260827.09) —
+   * empty in OSS.
+   */
+  readonly gateSteps: ResolvedGateSteps;
+  /**
+   * The workflow-execution engine seam (engine.ts): permanently
+   * disconnected until #21's TemporalManager flips it. Consumed by the
+   * create gate, the lifecycle RPCs, sendSignal, and
+   * submitWorkflowTaskApproval.
+   */
+  readonly engineState: WorkflowExecutionEngineStateProvider;
+  /**
+   * The shared broadcast fabric for subscribe streams. ONE instance spans
+   * both routers (serving + in-process) — see stream-broker.ts; the
+   * composition root owns it (Go: NewStreamBroker in the controller
+   * constructor + GetStreamBroker for #21's Temporal activities).
+   */
+  readonly broker: StreamBroker;
+  /**
+   * The in-process edges (lazy providers — the routes↔clients cycle
+   * resolves at request time): the default-instance creator, the two
+   * HITL forwarding edges into the agentexecution controller, and the
+   * EC-builder loaders.
+   */
+  readonly workflowInstanceCreator: ExecutionWorkflowInstanceCreatorProvider;
+  readonly approvalForwarder: AgentExecutionApprovalForwarderProvider;
+  readonly fileDecisionForwarder: AgentExecutionFileDecisionForwarderProvider;
+  /** The shared EC-builder deps (create's step 12 + recover's recreate). */
+  readonly executionContextBuilder: WorkflowExecutionContextBuilderDeps;
+  /**
+   * The sandbox lane (§6d, O6): disabled on the OSS default. Create and
+   * recover ensure the per-execution sandbox CRITICALLY (pre-persist /
+   * pre-start — a refusal orphans nothing); the terminal observer below
+   * tears it down.
+   */
+  readonly sandboxLane: SandboxLane;
+  /** Dispatch config — the sandbox ensure resolves target/queue through it. */
+  readonly temporalConfig: WorkflowExecutionTemporalConfig;
+  /**
+   * Fired after every persisted status write that transitions the phase
+   * (gate ruling Q3b) — updateStatus and the lifecycle persists call it;
+   * the worker's activity carries its own copy of the same observer.
+   */
+  readonly sandboxTerminalObserver: WorkflowSandboxTerminalObserver;
+}
+
+/** Registers both workflowexecution services on the router (routes stage). */
+export function registerWorkflowExecutionServices(
+  router: ConnectRouter,
+  deps: WorkflowExecutionControllerDeps,
+): void {
+  const lifecycleDeps = {
+    store: deps.store,
+    logger: deps.logger,
+    authorizer: deps.authorizer,
+    broker: deps.broker,
+    engineState: deps.engineState,
+    executionContextBuilder: deps.executionContextBuilder,
+    sandboxLane: deps.sandboxLane,
+    temporalConfig: deps.temporalConfig,
+    sandboxTerminalObserver: deps.sandboxTerminalObserver,
+    gateSteps: deps.gateSteps,
+  };
+  router.service(WorkflowExecutionCommandController, {
+    create: (execution, ctx) => createExecution(deps, execution, ctx),
+    update: (execution, ctx) => update(deps, execution, ctx),
+    updateStatus: (input, ctx) =>
+      updateStatus(deps, input, callerIdentityOf(ctx)),
+    submitApproval: (input, ctx) =>
+      submitApproval(deps, input, callerIdentityOf(ctx)),
+    submitFileDecision: (input, ctx) =>
+      submitFileDecision(deps, input, callerIdentityOf(ctx)),
+    submitWorkflowTaskApproval: (input, ctx) =>
+      submitWorkflowTaskApproval(deps, input, callerIdentityOf(ctx)),
+    delete: (id, ctx) => deleteExecution(deps, id, ctx),
+    sendSignal: (input, ctx) => sendSignal(deps, input, callerIdentityOf(ctx)),
+    cancel: (input, ctx) =>
+      cancelExecution(lifecycleDeps, input, callerIdentityOf(ctx)),
+    terminate: (input, ctx) =>
+      terminateExecution(lifecycleDeps, input, callerIdentityOf(ctx)),
+    recover: (input, ctx) =>
+      recoverExecution(lifecycleDeps, input, callerIdentityOf(ctx)),
+    pause: (input, ctx) =>
+      pauseExecution(lifecycleDeps, input, callerIdentityOf(ctx)),
+    resume: (input, ctx) =>
+      resumeExecution(lifecycleDeps, input, callerIdentityOf(ctx)),
+  });
+  router.service(WorkflowExecutionQueryController, {
+    get: (id, ctx) => get(deps, id, ctx),
+    list: (req, ctx) => list(deps, req, callerIdentityOf(ctx)),
+    listByWorkflow: (req, ctx) => listByWorkflow(deps, req, callerIdentityOf(ctx)),
+    subscribe: (req, ctx) => subscribeExecution(deps, req, ctx),
+    getEventLog: (req, ctx) => getEventLog(deps, req, callerIdentityOf(ctx)),
+    subscribeEvents: (req, ctx) => subscribeEvents(deps, req, ctx),
+    getExecutionSummary: (req, ctx) =>
+      getExecutionSummary(deps, req, callerIdentityOf(ctx)),
+    listPendingApprovals: (req, ctx) =>
+      listPendingApprovals(deps, req, callerIdentityOf(ctx)),
+  });
+}
+
+/**
+ * Create — create.go buildCreatePipeline, step-for-step (the numbered
+ * 15-step chain): validation (proto → visibility → slug →
+ * workflow-or-instance presence, the #196 InvalidArgument contrast) →
+ * the ENGINE GATE at its pinned position (before every side effect — a
+ * down engine orphans nothing; Go's unit test pins that it precedes even
+ * the workflow lookup) → default-instance resolution → the standard
+ * build → PENDING phase → workflow-ref denormalization → version pin →
+ * the ExecutionContext with merged env (runtime_env consumed and
+ * cleared) → Persist → IndexSearch → StartWorkflow (after persist; a
+ * start failure marks the execution FAILED, recoverable via Recover).
+ */
+async function createExecution(
+  deps: WorkflowExecutionControllerDeps,
+  execution: WorkflowExecution,
+  ctx: HandlerContext,
+): Promise<WorkflowExecution> {
+  const reqCtx = new RequestContext(
+    WorkflowExecutionSchema,
+    execution,
+    callerIdentityOf(ctx),
+    kindOf(ctx),
+  );
+  const builder = newPipeline<typeof WorkflowExecutionSchema>(
+    "workflowexecution-create",
+    deps.logger,
+  )
+    .addStep(
+      newAuthorizeStep(
+        WorkflowExecutionCommandController.method.create,
+        deps.authorizer,
+      ),
+    )
+    .addStep(newValidateProtoStep())
+    .addStep(newValidateVisibilityStep())
+    .addStep(newResolveSlugStep())
+    .addStep(newValidateWorkflowOrInstanceStep())
+    .addStep(newEnsureEngineAvailableStep(deps.engineState))
+    .addStep(
+      newCreateDefaultInstanceIfNeededStep({
+        store: deps.store,
+        logger: deps.logger,
+        workflowInstanceCreator: deps.workflowInstanceCreator,
+        authorizationLifecycle: deps.authorizationLifecycle,
+      }),
+    )
+    .addStep(newCheckDuplicateStep(deps.store))
+    .addStep(newBuildNewStateStep())
+    .addStep(newGuardReservedLabelsStep(deps.authorizer))
+    .addStep(newNormalizeReferencesStep());
+  // The ratified sandbox-acquisition gate slot (blueprint 03 §3a; C4):
+  // the Java-verified capacity-gate position — after Authorize and every
+  // resolution step (the default instance, like Java's, side-effects
+  // pre-gate: orphan-on-refusal is inherited semantics), before the
+  // phase stamp and every later side effect, pre-provision. Empty in OSS.
+  for (const step of stepsForSlot<typeof WorkflowExecutionSchema>(
+    deps.gateSteps,
+    "sandbox-acquisition:gate",
+  )) {
+    builder.addStep(step);
+  }
+  await builder
+    .addStep(newSetInitialPhaseStep())
+    .addStep(newNormalizeWorkflowRefStep(deps.store, deps.logger))
+    .addStep(newPinWorkflowVersionStep(deps.store, deps.logger))
+    .addStep(newCreateExecutionContextStep(deps.executionContextBuilder))
+    // The workflow-lane sandbox ensure (§6d, O6): CRITICAL and
+    // pre-persist — a provisioning refusal answers Unavailable with zero
+    // orphaned state (no row, no Temporal workflow), the verified Java
+    // ordering. Skips instantly when no provisioner is composed.
+    .addStep(
+      newEnsureWorkflowSandboxStep({
+        logger: deps.logger,
+        lane: deps.sandboxLane,
+        temporalConfig: deps.temporalConfig,
+      }),
+    )
+    .addStep(newPersistStep(deps.store))
+    .addStep(
+      newCreateAuthorizationTuplesStep(
+        deps.authorizationLifecycle,
+        deps.logger,
+      ),
+    )
+    .addStep(
+      newIndexSearchStep(
+        deps.store,
+        workflowExecutionSearchExtractor,
+        deps.logger,
+      ),
+    )
+    .addStep(
+      newStartWorkflowStep({
+        store: deps.store,
+        logger: deps.logger,
+        engineState: deps.engineState,
+      }),
+    )
+    .build()
+    .execute(reqCtx);
+  return reqCtx.newState;
+}
+
+function kindOf(ctx: HandlerContext): ApiResourceKind {
+  return ctx.values.get(apiResourceKindKey);
+}
+
+/**
+ * Update — update.go buildUpdatePipeline: USER-initiated spec updates
+ * (status updates from the runner use UpdateStatus instead). Standard
+ * chain; BuildUpdateState clears status per the shared pattern.
+ */
+async function update(
+  deps: WorkflowExecutionControllerDeps,
+  execution: WorkflowExecution,
+  ctx: HandlerContext,
+): Promise<WorkflowExecution> {
+  const reqCtx = new RequestContext(
+    WorkflowExecutionSchema,
+    execution,
+    callerIdentityOf(ctx),
+    kindOf(ctx),
+  );
+  await newPipeline<typeof WorkflowExecutionSchema>(
+    "workflowexecution-update",
+    deps.logger,
+  )
+    .addStep(
+      newAuthorizeStep(
+        WorkflowExecutionCommandController.method.update,
+        deps.authorizer,
+      ),
+    )
+    .addStep(newValidateProtoStep())
+    .addStep(newResolveSlugStep())
+    .addStep(newLoadExistingStep(deps.store))
+    .addStep(newBuildUpdateStateStep())
+    .addStep(newGuardReservedLabelsStep(deps.authorizer))
+    .addStep(newNormalizeReferencesStep())
+    .addStep(newPersistStep(deps.store))
+    .addStep(
+      newIndexSearchStep(
+        deps.store,
+        workflowExecutionSearchExtractor,
+        deps.logger,
+      ),
+    )
+    .build()
+    .execute(reqCtx);
+  return reqCtx.newState;
+}
+
+/**
+ * Delete — delete.go buildDeletePipeline; returns the deleted execution
+ * for the audit trail (gRPC convention). Executions and audit rows of the
+ * parent workflow are untouched — only this record and its search-index
+ * row go.
+ */
+async function deleteExecution(
+  deps: WorkflowExecutionControllerDeps,
+  id: ApiResourceId,
+  ctx: HandlerContext,
+): Promise<WorkflowExecution> {
+  const reqCtx = new RequestContext(
+    WorkflowExecutionCommandController.method.delete.input,
+    id,
+    callerIdentityOf(ctx),
+    kindOf(ctx),
+  );
+  await newPipeline<
+    typeof WorkflowExecutionCommandController.method.delete.input
+  >("workflowexecution-delete", deps.logger)
+    .addStep(
+      newAuthorizeStep(
+        WorkflowExecutionCommandController.method.delete,
+        deps.authorizer,
+      ),
+    )
+    .addStep(newValidateProtoStep())
+    .addStep(newExtractResourceIdStep())
+    .addStep(newLoadExistingForDeleteStep(deps.store, WorkflowExecutionSchema))
+    .addStep(newDeleteResourceStep(deps.store))
+    .addStep(
+      newCleanupIamPoliciesStep(deps.authorizationLifecycle, deps.logger),
+    )
+    .addStep(newDeleteSearchIndexStep(deps.store, deps.logger))
+    .build()
+    .execute(reqCtx);
+
+  const deleted = reqCtx.get(EXISTING_RESOURCE_KEY);
+  if (deleted === undefined) {
+    throw internalError(
+      new Error("deleted workflow execution not found in context"),
+      "deleted workflow execution not found in context",
+    );
+  }
+  return deleted as WorkflowExecution;
+}
+
+/** Get — get.go buildGetPipeline: ValidateProto → LoadTarget. */
+async function get(
+  deps: WorkflowExecutionControllerDeps,
+  id: WorkflowExecutionId,
+  ctx: HandlerContext,
+): Promise<WorkflowExecution> {
+  const reqCtx = new RequestContext(
+    WorkflowExecutionQueryController.method.get.input,
+    id,
+    callerIdentityOf(ctx),
+    kindOf(ctx),
+  );
+  await newPipeline<typeof WorkflowExecutionQueryController.method.get.input>(
+    "workflowexecution-get",
+    deps.logger,
+  )
+    .addStep(
+      newAuthorizeStep(
+        WorkflowExecutionQueryController.method.get,
+        deps.authorizer,
+      ),
+    )
+    .addStep(newValidateProtoStep())
+    .addStep(newLoadTargetStep(deps.store, WorkflowExecutionSchema))
+    .build()
+    .execute(reqCtx);
+  return reqCtx.get(TARGET_RESOURCE_KEY) as WorkflowExecution;
+}
+
+/**
+ * List — list.go: full scan, the legacy top-level phase filter (only when
+ * filter.phases is absent), structured filter criteria (T13), and the
+ * sort default started_at descending. No pagination (total_pages
+ * placeholder 1). With a composed ListReadScope (20260830.01, census
+ * lane 6) the scan narrows to the caller's authorized executions and the
+ * request `org` narrows when non-blank (the Java
+ * WorkflowExecutionListHandler baseline: blank = permission-bounded
+ * across orgs); no scope = the full scan with `org` a deliberate no-op
+ * on this single-tenant edition — byte-identical.
+ */
+async function list(
+  deps: WorkflowExecutionControllerDeps,
+  req: ListWorkflowExecutionsRequest,
+  identity: CallerIdentity,
+): Promise<WorkflowExecutionList> {
+  let executions = await restrictListByReadScope(
+    deps.listReadScope,
+    identity,
+    ApiResourceKind.workflow_execution,
+    await loadAllWorkflowExecutions(
+      deps.store,
+      deps.logger,
+      "failed to list workflow executions",
+    ),
+    req.org,
+  );
+
+  if (req.filter === undefined || req.filter.phases.length === 0) {
+    executions = applyLegacyPhaseFilter(executions, req.phase);
+  }
+  executions = applyFilterCriteria(executions, req.filter);
+
+  let sortField = req.sortField;
+  let ascending = req.sortAscending;
+  if (sortField === ExecutionSortField.UNSPECIFIED) {
+    sortField = ExecutionSortField.STARTED_AT;
+    ascending = false;
+  }
+  applySortField(executions, sortField, ascending);
+
+  return create(WorkflowExecutionListSchema, {
+    entries: executions,
+    totalPages: 1,
+  });
+}
+
+/**
+ * ListByWorkflow — list_by_workflow.go: the request field accepts either
+ * a Workflow ID or a WorkflowInstance ID, so both spec fields are
+ * matched. Same filter/sort tail as list; no pagination.
+ */
+async function listByWorkflow(
+  deps: WorkflowExecutionControllerDeps,
+  req: ListWorkflowExecutionsByWorkflowRequest,
+  identity: CallerIdentity,
+): Promise<WorkflowExecutionList> {
+  if (req.workflowId === "") {
+    throw invalidArgumentError("workflow_id is required");
+  }
+
+  // Census lane 7: authorized ids ∩ workflow filter; the Java handler
+  // never consults org on this lane (bounded by the workflow id).
+  const all = await restrictListByReadScope(
+    deps.listReadScope,
+    identity,
+    ApiResourceKind.workflow_execution,
+    await loadAllWorkflowExecutions(
+      deps.store,
+      deps.logger,
+      "failed to list workflow executions",
+    ),
+    "",
+  );
+  let executions = all.filter(
+    (execution) =>
+      execution.spec?.workflowInstanceId === req.workflowId ||
+      execution.spec?.workflowId === req.workflowId,
+  );
+
+  executions = applyFilterCriteria(executions, req.filter);
+
+  let sortField = req.sortField;
+  let ascending = req.sortAscending;
+  if (sortField === ExecutionSortField.UNSPECIFIED) {
+    sortField = ExecutionSortField.STARTED_AT;
+    ascending = false;
+  }
+  applySortField(executions, sortField, ascending);
+
+  return create(WorkflowExecutionListSchema, {
+    entries: executions,
+    totalPages: 1,
+  });
+}