@lostgradient/weft 0.2.1 → 0.3.0

package/dist/server/interactive-operations.js

@@ -8,6 +8,7 @@ export const INTERACTIVE_OPERATION_NAMES = [
   "weft.workflows.cancel",
   "weft.workflows.timeout",
   "weft.workflows.resume",
+  "weft.workflows.suspend",
   "weft.workflows.replay",
   "weft.schedules.create",
   "weft.schedules.get",

package/dist/server/operations/resume-workflow.js

@@ -11,8 +11,8 @@ const resumeWorkflowInput = z.object({
 });
 export const resumeWorkflowOperation = createSingleWorkflowControlOperation({
   name: "weft.workflows.resume",
-  summary: "Resume a suspended workflow",
-  description: "Resume a workflow that is suspended (for example, paused awaiting a human review or an operator hold) by `workflowId`, returning the workflow `id`. Faults with NotFound when the workflow is not visible.",
+  summary: "Resume a suspended or recovered workflow",
+  description: "Re-drive a workflow from its persisted checkpoint by `workflowId`, returning the workflow `id`. Accepts a workflow that was explicitly suspended (`weft.workflows.suspend`) or one left running by a prior process; a suspended workflow is durably flipped back to running as part of resuming. Faults with NotFound when the workflow is not visible, or Conflict when it is in a status that cannot be resumed (terminal or pending).",
   destructive: !1,
   tags: ["Workflows"],
   inputSchema: resumeWorkflowInput,

package/dist/server/operations/start-or-signal-workflow.d.ts

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+import type { UnknownRestBinding } from '../rest-bindings.ts';
+declare const startOrSignalWorkflowInput: z.ZodObject<{
+    type: z.ZodUnknown;
+    input: z.ZodOptional<z.ZodUnknown>;
+    signalName: z.ZodString;
+    signalPayload: z.ZodOptional<z.ZodUnknown>;
+    signalId: z.ZodOptional<z.ZodString>;
+    id: z.ZodOptional<z.ZodUnknown>;
+    executionTimeout: z.ZodOptional<z.ZodUnknown>;
+    startAt: z.ZodOptional<z.ZodUnknown>;
+    startAfter: z.ZodOptional<z.ZodUnknown>;
+    tags: z.ZodOptional<z.ZodUnknown>;
+    idempotencyKey: z.ZodOptional<z.ZodUnknown>;
+    searchAttributes: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+declare const startOrSignalWorkflowOutput: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+export type StartOrSignalWorkflowInput = z.infer<typeof startOrSignalWorkflowInput>;
+export type StartOrSignalWorkflowOutput = z.infer<typeof startOrSignalWorkflowOutput>;
+export declare const startOrSignalWorkflowOperation: import("../operation-catalog.ts").OperationDefinition<{
+    type: unknown;
+    signalName: string;
+    input?: unknown;
+    signalPayload?: unknown;
+    signalId?: string | undefined;
+    id?: unknown;
+    executionTimeout?: unknown;
+    startAt?: unknown;
+    startAfter?: unknown;
+    tags?: unknown;
+    idempotencyKey?: unknown;
+    searchAttributes?: unknown;
+}, {
+    id: string;
+}>;
+export declare const startOrSignalWorkflowRestBinding: UnknownRestBinding;
+export {};

package/dist/server/operations/start-or-signal-workflow.js

@@ -0,0 +1,140 @@
+import { z } from "zod";
+import {
+  IdempotencyKeyPurgedError,
+  StartOrSignalConflictError,
+  WorkflowNotRegisteredError
+} from "../../core/engine/errors.js";
+import { runtimeWorkflowEngine } from "../../core/runtime-workflow-engine.js";
+import { isSignalIdWithinByteLimit } from "../../core/signal-id.js";
+import { StartWorkflowValidationError } from "../../core/start-workflow-validation.js";
+import { defineOperation } from "../operation-registry.js";
+import { invalidParamsFault, shapeRestFault } from "./operation-helpers.js";
+import { buildSharedStartWorkflowOptions } from "./start-workflow-options.js";
+const startOrSignalWorkflowInput = z.object({
+  type: z.unknown().describe("Workflow type name. Runtime validation requires a non-empty string."),
+  input: z.unknown().optional(),
+  signalName: z.string().min(1).describe("Signal name. Must be a non-empty string."),
+  signalPayload: z.unknown().optional(),
+  signalId: z.string().min(1).refine(isSignalIdWithinByteLimit, "signalId must be at most 128 bytes").optional(),
+  id: z.unknown().optional(),
+  executionTimeout: z.unknown().optional(),
+  startAt: z.unknown().optional(),
+  startAfter: z.unknown().optional(),
+  tags: z.unknown().optional(),
+  idempotencyKey: z.unknown().optional(),
+  searchAttributes: z.unknown().optional()
+}), startOrSignalWorkflowOutput = z.object({
+  id: z.string()
+});
+function validateStartOrSignalWorkflowInput(input, lookupSearchAttributeSchema) {
+  if (typeof input.type !== "string" || input.type.length === 0)
+    throw invalidParamsFault("Missing required field: type");
+  let options;
+  try {
+    options = buildSharedStartWorkflowOptions(input, lookupSearchAttributeSchema(input.type));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw invalidParamsFault(message);
+  }
+  assertConvergenceTokenProvided(input.signalId, options.idempotencyKey);
+  const signal = {
+    name: input.signalName,
+    payload: input.signalPayload,
+    ...input.signalId === void 0 ? {} : { signalId: input.signalId }
+  };
+  return { type: input.type, signal, options };
+}
+function assertConvergenceTokenProvided(signalId, idempotencyKey) {
+  if (signalId === void 0 && idempotencyKey === void 0)
+    throw invalidParamsFault("startOrSignal requires either signalId or idempotencyKey to identify the signal to deliver. (Concurrent callers converge on one workflow and one signal only with a shared idempotencyKey, or a shared id plus signalId; a bare signalId starts a fresh run per caller.)");
+  if (signalId !== void 0 && idempotencyKey !== void 0)
+    throw invalidParamsFault("startOrSignal does not accept both signalId and idempotencyKey: the signal id derives from the idempotency key for convergence. Provide exactly one.");
+}
+function resolveStartOrSignalWorkflowFault(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  if (error instanceof WorkflowNotRegisteredError)
+    throw invalidParamsFault(message);
+  if (error instanceof StartOrSignalConflictError || error instanceof IdempotencyKeyPurgedError)
+    throw {
+      code: "Conflict",
+      message,
+      data: { reason: message }
+    };
+  if (error instanceof StartWorkflowValidationError)
+    throw invalidParamsFault(message);
+  throw {
+    code: "EngineFailure",
+    message,
+    data: {}
+  };
+}
+export const startOrSignalWorkflowOperation = defineOperation({
+  name: "weft.workflows.startorsignal",
+  mcpExposable: !1,
+  summary: "Atomically start a workflow or signal it if it already exists",
+  description: 'Start a workflow or deliver a signal to it if it already exists (signal-with-start). An absent target is created and delivered the signal in one batch; a non-terminal target (running, pending, or suspended) is signalled; a terminal target faults with Conflict, as does a spent `idempotencyKey` whose run was purged or swept by retention. Requires `type`, `signalName`, and exactly one of `signalId` or `idempotencyKey` (not both). Accepts `input`, `signalPayload`, and the non-idempotency start options from weft.workflows.start (`id`, `executionTimeout`, `startAt`/`startAfter`, `tags`, `searchAttributes`); `idempotencyKey` is governed solely by the "exactly one of" rule above. Returns the workflow `id`. Concurrent callers converge on one workflow and one signal only with a shared `idempotencyKey`, or a shared `id` plus `signalId`; a bare `signalId` (no `id`/`idempotencyKey`) starts a fresh run per caller and does not converge.',
+  destructive: !1,
+  tags: ["Workflows", "Signals"],
+  inputSchema: startOrSignalWorkflowInput,
+  outputSchema: startOrSignalWorkflowOutput,
+  access: { kind: "public" },
+  producibleFaults: ["Conflict"],
+  transports: { http: !0, jsonRpcHttp: !0, jsonRpcWebSocket: !0, jsonRpcStdio: !0 },
+  unknownKeyPolicy: { http: "strip", jsonRpc: "reject" },
+  invoke: async ({ input, engine }) => {
+    const typedEngine = runtimeWorkflowEngine(engine), { type, signal, options } = validateStartOrSignalWorkflowInput(input, (validType) => {
+      return typedEngine.getWorkflowDefinition(validType)?.searchAttributes;
+    });
+    try {
+      return { id: (await typedEngine.startOrSignal(type, input.input, signal, options)).id };
+    } catch (error) {
+      resolveStartOrSignalWorkflowFault(error);
+    }
+  }
+}), startOrSignalWorkflowRestBinding = {
+  method: "POST",
+  path: "/v1/workflows/start-or-signal",
+  pathParamNames: [],
+  operationName: "weft.workflows.startorsignal",
+  inputSources: {
+    type: { kind: "body-field", bodyField: "type" },
+    input: { kind: "body-field", bodyField: "input" },
+    signalName: { kind: "body-field", bodyField: "signalName" },
+    signalPayload: { kind: "body-field", bodyField: "signalPayload" },
+    signalId: { kind: "body-field", bodyField: "signalId" },
+    id: { kind: "body-field", bodyField: "id" },
+    executionTimeout: { kind: "body-field", bodyField: "executionTimeout" },
+    startAt: { kind: "body-field", bodyField: "startAt" },
+    startAfter: { kind: "body-field", bodyField: "startAfter" },
+    tags: { kind: "body-field", bodyField: "tags" },
+    idempotencyKey: { kind: "body-field", bodyField: "idempotencyKey" },
+    searchAttributes: { kind: "body-field", bodyField: "searchAttributes" }
+  },
+  extractInput: async (request) => {
+    let body;
+    try {
+      body = await request.json();
+    } catch {
+      throw invalidParamsFault("Invalid JSON body");
+    }
+    if (typeof body !== "object" || body === null)
+      throw invalidParamsFault("Request body must be a JSON object");
+    const record = body;
+    return {
+      type: record.type,
+      input: record.input,
+      signalName: record.signalName,
+      signalPayload: record.signalPayload,
+      signalId: record.signalId,
+      id: record.id,
+      executionTimeout: record.executionTimeout,
+      startAt: record.startAt,
+      startAfter: record.startAfter,
+      tags: record.tags,
+      idempotencyKey: record.idempotencyKey,
+      searchAttributes: record.searchAttributes
+    };
+  },
+  success: { kind: "json", status: 201 },
+  shapeFault: shapeRestFault
+};

package/dist/server/operations/start-workflow-options.d.ts

@@ -0,0 +1,32 @@
+import type { SearchAttributeSchema, SearchAttributeValue, StartOptions } from '../../core/types.ts';
+/**
+ * The raw, transport-supplied start-option fields shared by `weft.workflows.start`
+ * and `weft.workflows.startorsignal`. Each is `unknown` because validation happens
+ * in {@link buildSharedStartWorkflowOptions}, not at the schema boundary, so both
+ * surfaces hit one cross-transport error path.
+ */
+export type SharedStartWorkflowOptionInput = {
+    id?: unknown;
+    executionTimeout?: unknown;
+    startAt?: unknown;
+    startAfter?: unknown;
+    tags?: unknown;
+    idempotencyKey?: unknown;
+    searchAttributes?: unknown;
+};
+/**
+ * Coerce the shared start-option fields into a validated {@link StartOptions}.
+ * Both start operations call this so they cannot drift in how they validate `id`,
+ * `executionTimeout`, `startAt`/`startAfter`, `tags`, `idempotencyKey`, and
+ * `searchAttributes` (a new field added here covers both surfaces at once). Throws
+ * {@link StartWorkflowValidationError} on any malformed field.
+ */
+export declare function buildSharedStartWorkflowOptions(input: SharedStartWorkflowOptionInput, searchAttributeSchema: SearchAttributeSchema | undefined): StartOptions;
+/**
+ * Coerce a transport-supplied `searchAttributes` object into validated
+ * {@link SearchAttributeValue}s. Shared by `weft.workflows.start` and
+ * `weft.workflows.startorsignal` so both apply the same null-prototype guard,
+ * date-time normalization, schema-presence check, and type validation —
+ * preventing the two start surfaces from drifting in how they accept attributes.
+ */
+export declare function coerceStartWorkflowSearchAttributes(value: unknown, fieldName: string, schema: SearchAttributeSchema | undefined): Record<string, SearchAttributeValue>;

package/dist/server/operations/start-workflow-options.js

@@ -0,0 +1,63 @@
+import { validateAttributeType } from "../../core/search-attributes.js";
+import {
+  assertExclusiveStartWorkflowOptions,
+  coerceStartWorkflowDuration,
+  coerceStartWorkflowId,
+  coerceStartWorkflowIdempotencyKey,
+  coerceStartWorkflowTags,
+  coerceStartWorkflowTimestamp,
+  StartWorkflowValidationError
+} from "../../core/start-workflow-validation.js";
+export function buildSharedStartWorkflowOptions(input, searchAttributeSchema) {
+  const options = {};
+  if (input.id !== void 0)
+    options.id = coerceStartWorkflowId(input.id, 'Field "id"');
+  if (input.executionTimeout !== void 0)
+    options.executionTimeout = coerceStartWorkflowDuration(input.executionTimeout, 'Field "executionTimeout"');
+  if (input.startAt !== void 0)
+    options.startAt = coerceStartWorkflowTimestamp(input.startAt, 'Field "startAt"');
+  if (input.startAfter !== void 0)
+    options.startAfter = coerceStartWorkflowDuration(input.startAfter, 'Field "startAfter"');
+  if (input.tags !== void 0)
+    options.tags = coerceStartWorkflowTags(input.tags, 'Field "tags"');
+  if (input.idempotencyKey !== void 0)
+    options.idempotencyKey = coerceStartWorkflowIdempotencyKey(input.idempotencyKey, 'Field "idempotencyKey"');
+  if (input.searchAttributes !== void 0)
+    options.searchAttributes = coerceStartWorkflowSearchAttributes(input.searchAttributes, 'Field "searchAttributes"', searchAttributeSchema);
+  assertExclusiveStartWorkflowOptions(options.startAt, options.startAfter);
+  return options;
+}
+export function coerceStartWorkflowSearchAttributes(value, fieldName, schema) {
+  if (typeof value !== "object" || value === null || Array.isArray(value))
+    throw new StartWorkflowValidationError(`${fieldName} must be an object`);
+  const attributes = Object.create(null);
+  for (const [key, attributeValue] of Object.entries(value))
+    attributes[key] = coerceStartWorkflowSearchAttributeValue(key, attributeValue, fieldName, schema);
+  return attributes;
+}
+function coerceStartWorkflowSearchAttributeValue(key, value, fieldName, schema) {
+  if (!isSearchAttributeValue(value))
+    throw new StartWorkflowValidationError(`${fieldName}.${key} must be a string, number, boolean, Date, or string array`);
+  if (schema === void 0)
+    return value;
+  const definition = schema[key];
+  if (definition === void 0)
+    throw new StartWorkflowValidationError(`Unknown search attribute "${key}". Registered attributes: ${Object.keys(schema).join(", ")}`);
+  const normalizedValue = definition.type === "string" && definition.format === "date-time" && typeof value === "string" ? coerceDateTimeSearchAttribute(key, value, fieldName) : value;
+  try {
+    validateAttributeType(key, normalizedValue, definition);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new StartWorkflowValidationError(message);
+  }
+  return normalizedValue;
+}
+function coerceDateTimeSearchAttribute(key, value, fieldName) {
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime()))
+    throw new StartWorkflowValidationError(`${fieldName}.${key} must be a valid date-time string`);
+  return date;
+}
+function isSearchAttributeValue(value) {
+  return typeof value === "string" || typeof value === "number" || typeof value === "boolean" || value instanceof Date || Array.isArray(value) && value.every((item) => typeof item === "string");
+}

package/dist/server/operations/start-workflow.js

@@ -1,20 +1,14 @@
 import { z } from "zod";
 import {
+  IdempotencyKeyPurgedError,
   WorkflowAlreadyExistsError,
   WorkflowNotRegisteredError
 } from "../../core/engine/errors.js";
 import { runtimeWorkflowEngine } from "../../core/runtime-workflow-engine.js";
-import { validateAttributeType } from "../../core/search-attributes.js";
-import {
-  assertExclusiveStartWorkflowOptions,
-  coerceStartWorkflowDuration,
-  coerceStartWorkflowId,
-  coerceStartWorkflowTags,
-  coerceStartWorkflowTimestamp,
-  StartWorkflowValidationError
-} from "../../core/start-workflow-validation.js";
+import { StartWorkflowValidationError } from "../../core/start-workflow-validation.js";
 import { defineOperation } from "../operation-registry.js";
 import { invalidParamsFault, shapeRestFault } from "./operation-helpers.js";
+import { buildSharedStartWorkflowOptions } from "./start-workflow-options.js";
 const startWorkflowInput = z.object({
   type: z.unknown().describe("Workflow type name. Runtime validation requires a non-empty string."),
   input: z.unknown().optional(),
@@ -34,7 +28,7 @@ function validateStartWorkflowInput(input, lookupSearchAttributeSchema) {
   const type = input.type;
   let options;
   try {
-    options = buildStartWorkflowOptions(input, lookupSearchAttributeSchema(type));
+    options = buildSharedStartWorkflowOptions(input, lookupSearchAttributeSchema(type));
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     throw invalidParamsFault(message);
@@ -45,7 +39,7 @@ function resolveStartWorkflowAccess(error) {
   const message = error instanceof Error ? error.message : String(error);
   if (error instanceof WorkflowNotRegisteredError)
     throw invalidParamsFault(message);
-  if (error instanceof WorkflowAlreadyExistsError)
+  if (error instanceof WorkflowAlreadyExistsError || error instanceof IdempotencyKeyPurgedError)
     throw {
       code: "Conflict",
       message,
@@ -63,7 +57,7 @@ export const startWorkflowOperation = defineOperation({
   name: "weft.workflows.start",
   mcpExposable: !1,
   summary: "Start a new workflow",
-  description: "Start a new workflow execution of a registered type. Requires `type` (the registered workflow type name) and accepts an optional `input` payload plus start options: `id` (client-supplied workflow id), `executionTimeout`, `startAt`/`startAfter` (mutually exclusive scheduling), `tags`, and `searchAttributes`. Returns the workflow `id`. Faults with InvalidParams for an unregistered type or malformed options, and Conflict when a workflow with the same id already exists.",
+  description: "Start a new workflow execution of a registered type. Requires `type` (the registered workflow type name) and accepts an optional `input` payload plus start options: `id` (client-supplied workflow id), `executionTimeout`, `startAt`/`startAfter` (mutually exclusive scheduling), `tags`, `idempotencyKey` (at-most-once dedup: a repeated key returns the existing run instead of starting a second), and `searchAttributes`. Returns the workflow `id`. Faults with InvalidParams for an unregistered type or malformed options, and Conflict when a workflow with the same id already exists or the supplied `idempotencyKey` has been spent (its run was purged or swept by retention).",
   destructive: !1,
   tags: ["Workflows"],
   inputSchema: startWorkflowInput,
@@ -82,63 +76,7 @@ export const startWorkflowOperation = defineOperation({
       resolveStartWorkflowAccess(error);
     }
   }
-});
-function buildStartWorkflowOptions(input, searchAttributeSchema) {
-  const options = {};
-  if (input.id !== void 0)
-    options.id = coerceStartWorkflowId(input.id, 'Field "id"');
-  if (input.executionTimeout !== void 0)
-    options.executionTimeout = coerceStartWorkflowDuration(input.executionTimeout, 'Field "executionTimeout"');
-  if (input.startAt !== void 0)
-    options.startAt = coerceStartWorkflowTimestamp(input.startAt, 'Field "startAt"');
-  if (input.startAfter !== void 0)
-    options.startAfter = coerceStartWorkflowDuration(input.startAfter, 'Field "startAfter"');
-  if (input.tags !== void 0)
-    options.tags = coerceStartWorkflowTags(input.tags, 'Field "tags"');
-  if (input.idempotencyKey !== void 0)
-    throw new StartWorkflowValidationError("idempotencyKey is not supported over HttpClient because the start workflow HTTP protocol does not implement start idempotency");
-  if (input.searchAttributes !== void 0)
-    options.searchAttributes = coerceStartWorkflowSearchAttributes(input.searchAttributes, 'Field "searchAttributes"', searchAttributeSchema);
-  assertExclusiveStartWorkflowOptions(options.startAt, options.startAfter);
-  return options;
-}
-function coerceStartWorkflowSearchAttributes(value, fieldName, schema) {
-  if (typeof value !== "object" || value === null || Array.isArray(value))
-    throw new StartWorkflowValidationError(`${fieldName} must be an object`);
-  const attributes = Object.create(null);
-  for (const [key, attributeValue] of Object.entries(value)) {
-    const coercedValue = coerceStartWorkflowSearchAttributeValue(key, attributeValue, fieldName, schema);
-    attributes[key] = coercedValue;
-  }
-  return attributes;
-}
-function coerceStartWorkflowSearchAttributeValue(key, value, fieldName, schema) {
-  if (!isSearchAttributeValue(value))
-    throw new StartWorkflowValidationError(`${fieldName}.${key} must be a string, number, boolean, Date, or string array`);
-  if (schema === void 0)
-    return value;
-  const definition = schema[key];
-  if (definition === void 0)
-    throw new StartWorkflowValidationError(`Unknown search attribute "${key}". Registered attributes: ${Object.keys(schema).join(", ")}`);
-  const normalizedValue = definition.type === "string" && definition.format === "date-time" && typeof value === "string" ? coerceDateTimeSearchAttribute(key, value, fieldName) : value;
-  try {
-    validateAttributeType(key, normalizedValue, definition);
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    throw new StartWorkflowValidationError(message);
-  }
-  return normalizedValue;
-}
-function coerceDateTimeSearchAttribute(key, value, fieldName) {
-  const date = new Date(value);
-  if (Number.isNaN(date.getTime()))
-    throw new StartWorkflowValidationError(`${fieldName}.${key} must be a valid date-time string`);
-  return date;
-}
-function isSearchAttributeValue(value) {
-  return typeof value === "string" || typeof value === "number" || typeof value === "boolean" || value instanceof Date || Array.isArray(value) && value.every((item) => typeof item === "string");
-}
-export const startWorkflowRestBinding = {
+}), startWorkflowRestBinding = {
   method: "POST",
   path: "/v1/workflows",
   pathParamNames: [],

package/dist/server/operations/suspend-workflow.d.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+import type { UnknownRestBinding } from '../rest-bindings.ts';
+declare const suspendWorkflowInput: z.ZodObject<{
+    workflowId: z.ZodString;
+}, z.core.$strip>;
+declare const suspendWorkflowOutput: z.ZodUndefined;
+export type SuspendWorkflowInput = z.infer<typeof suspendWorkflowInput>;
+export type SuspendWorkflowOutput = z.infer<typeof suspendWorkflowOutput>;
+export declare const suspendWorkflowOperation: import("../operation-catalog.ts").OperationDefinition<{
+    workflowId: string;
+}, undefined>;
+export declare const suspendWorkflowRestBinding: UnknownRestBinding;
+export {};

package/dist/server/operations/suspend-workflow.js

@@ -0,0 +1,36 @@
+import { z } from "zod";
+import { WorkflowSuspendNotSupportedError } from "../../core/engine/errors.js";
+import { shapeRestFault } from "./operation-helpers.js";
+import {
+  createSingleWorkflowControlOperation,
+  extractWorkflowIdFromPath
+} from "./single-workflow-control-operation.js";
+const suspendWorkflowInput = z.object({
+  workflowId: z.string().min(1)
+}), suspendWorkflowOutput = z.undefined();
+export const suspendWorkflowOperation = createSingleWorkflowControlOperation({
+  name: "weft.workflows.suspend",
+  summary: "Suspend a running workflow",
+  description: "Request suspension of a running workflow by `id` without terminating it. The workflow transitions to the non-terminal `suspended` status, keeps its durable checkpoint, and is later resumable via `resume`. Unlike cancellation, suspension does not run cancel handlers and does not settle the result. Suspending a workflow that is not running is a no-op. Faults with Unprocessable when the engine runs in worker execution mode (which cannot pause a run without cancelling it).",
+  destructive: !1,
+  tags: ["Workflows"],
+  inputSchema: suspendWorkflowInput,
+  outputSchema: suspendWorkflowOutput,
+  producibleFaults: ["Unprocessable"],
+  invoke: async ({ input, engine }) => {
+    await engine.suspend(input.workflowId);
+    return;
+  },
+  mapErrorToFault: ({ error, message }) => error instanceof WorkflowSuspendNotSupportedError ? { code: "Unprocessable", message, data: { reason: message } } : void 0
+}), suspendWorkflowRestBinding = {
+  method: "POST",
+  path: "/v1/workflows/:id/suspend",
+  pathParamNames: ["id"],
+  operationName: "weft.workflows.suspend",
+  inputSources: {
+    workflowId: { kind: "path", pathParam: "id" }
+  },
+  extractInput: async (_request, pathParams) => extractWorkflowIdFromPath(pathParams),
+  success: { kind: "empty", status: 204 },
+  shapeFault: shapeRestFault
+};

package/dist/server/rest-binding.d.ts

@@ -111,14 +111,25 @@ export type RestBinding<Input, Output> = {
     readonly shapeSuccess?: (output: Output, request: Request) => Response;
     /**
      * Optional override for fault → HTTP response mapping. When absent,
-     * the transport adapter falls back to `faultToHttpResponse` (the
-     * canonical `{ error: { code, message, data? } }` shape).
+     * the transport adapter falls back to `faultToHttpResponse`, which emits
+     * the REST fault body `{ error: { code, message, data? } }`. This is
+     * distinct from the JSON-RPC fault object (`faultToJsonRpcError`): JSON-RPC
+     * uses a flat `{ code, message, data }` with a numeric `code` and the
+     * symbolic name relocated to `data.weftCode`. REST and JSON-RPC deliberately
+     * differ in fault shape, so each transport owns its own projection.
      *
-     * During Milestone 1, bindings for REST operations that already exist
-     * with a different legacy error shape MUST provide this so their
-     * parity diff test passes byte-for-byte against the legacy handler.
-     * Milestone 2 drops the per-binding override and all REST endpoints
-     * move to the canonical fault shape.
+     * REST operations provide this to shape faults the way a REST client
+     * expects: most use `shapeRestFault`, which masks an `EngineFailure` to a
+     * flat `{ error: "Internal server error" }` with status `500` (never
+     * leaking internal detail over REST) and maps the remaining fault codes to
+     * their HTTP statuses. A few operations supply a bespoke shaper to special-case
+     * a particular fault — typically to override its message or to handle one code
+     * explicitly — while delegating the rest. The status often matches what the
+     * shared map would already produce; the shaper exists for the operation-specific
+     * detail (for example, `get-workflow-result` returns the custom message
+     * `"Timeout waiting for workflow result"` on a `Timeout`, and `get-stream-chunks`
+     * handles `InvalidParams` inline). This per-operation hook is the current
+     * contract, not a transitional shim.
      */
     readonly shapeFault?: (fault: OperationFault) => Response;
 };

package/dist/server/rest-bindings.js

@@ -139,6 +139,10 @@ import {
   signalWorkflowOperation,
   signalWorkflowRestBinding
 } from "./operations/signal-workflow.js";
+import {
+  startOrSignalWorkflowOperation,
+  startOrSignalWorkflowRestBinding
+} from "./operations/start-or-signal-workflow.js";
 import { startWorkflowOperation, startWorkflowRestBinding } from "./operations/start-workflow.js";
 import {
   storageBatchOperation,
@@ -162,6 +166,10 @@ import {
   submitReviewDecisionOperation,
   submitReviewDecisionRestBinding
 } from "./operations/submit-review-decision.js";
+import {
+  suspendWorkflowOperation,
+  suspendWorkflowRestBinding
+} from "./operations/suspend-workflow.js";
 import {
   timeoutWorkflowOperation,
   timeoutWorkflowRestBinding
@@ -191,6 +199,7 @@ import {
 import { workflowEventsSubscriptionOperation } from "./operations/workflow-events-subscription.js";
 export const REST_BINDINGS = [
   startWorkflowRestBinding,
+  startOrSignalWorkflowRestBinding,
   recoverAllRestBinding,
   listWorkflowsRestBinding,
   aggregateWorkflowsRestBinding,
@@ -211,6 +220,7 @@ export const REST_BINDINGS = [
   queryWorkflowRestBinding,
   queryWorkflowWithInputRestBinding,
   resumeWorkflowRestBinding,
+  suspendWorkflowRestBinding,
   forkWorkflowRestBinding,
   timeoutWorkflowRestBinding,
   updateWorkflowRestBinding,
@@ -314,6 +324,7 @@ export function createLiveOperationRegistry(options) {
   const resolved = options ?? {};
   return createOperationRegistry([
     startWorkflowOperation,
+    startOrSignalWorkflowOperation,
     recoverAllOperation,
     listWorkflowsOperation,
     aggregateWorkflowsOperation,
@@ -333,6 +344,7 @@ export function createLiveOperationRegistry(options) {
     failAsyncActivityOperation,
     queryWorkflowOperation,
     resumeWorkflowOperation,
+    suspendWorkflowOperation,
     forkWorkflowOperation,
     timeoutWorkflowOperation,
     updateWorkflowOperation,

package/dist/server/runtime/task-dispatch.js

@@ -59,8 +59,8 @@ async function selectAndReserveWorker(context, options, task, queue, visibilityT
   const ws = context.workerSockets.get(worker.id);
   if (!ws)
     return !1;
-  const now = Date.now(), existingQueuedRecord = await readQueuedRecord(options.engine.storage, task.operationId);
-  context.registry.assignTask(worker.id, task.operationId, visibilityTimeout, task.fairShareKey);
+  const now = Date.now(), existingQueuedRecord = await readQueuedRecord(options.engine.storage, task.operationId), attemptToken = crypto.randomUUID();
+  context.registry.assignTask(worker.id, task.operationId, visibilityTimeout, task.fairShareKey, attemptToken);
   const deadline = now + visibilityTimeout;
   context.deadlineTracker.add({ operationId: task.operationId, deadline });
   const inflightRecord = {
@@ -73,7 +73,8 @@ async function selectAndReserveWorker(context, options, task, queue, visibilityT
     attempt: task.attempt ?? 1,
     visibilityTimeout,
     retryPolicy: task.retryPolicy,
-    workflowId: task.workflowId
+    workflowId: task.workflowId,
+    attemptToken
   }, normalizedInflightRecord = await transitionQueuedToInflight(options.engine.storage, task.operationId, inflightRecord, {
     queuedRecord: existingQueuedRecord,
     now
@@ -84,6 +85,7 @@ async function selectAndReserveWorker(context, options, task, queue, visibilityT
     activityName: task.activityName,
     input: task.input === void 0 ? null : task.input,
     attempt: task.attempt ?? 1,
+    attemptToken,
     ...task.headers ? { headers: task.headers } : {}
   }));
   recordTaskQueueLatencyMetric(context.metricsCollector, normalizedInflightRecord);

package/dist/server/runtime/task-polling.d.ts

@@ -3,7 +3,21 @@ import { type Principal } from '../principal.ts';
 import type { PendingTask } from '../task-queue-types.ts';
 import type { InflightRecord } from '../task-state.ts';
 import type { ServerContext } from './context.ts';
-export declare function createLongPollInflightRecord(queue: string, task: PendingTask): InflightRecord;
-export declare function markTaskClaimedByLongPollWorker(context: ServerContext, options: ServeOptions, queue: string, task: PendingTask): Promise<string>;
+/**
+ * A freshly created long-poll inflight record always carries an `attemptToken`.
+ * The intersection makes that invariant a compile-time fact so the claim can read
+ * the token directly without an unreachable empty-string fallback.
+ */
+type TokenedInflightRecord = InflightRecord & {
+    attemptToken: string;
+};
+export declare function createLongPollInflightRecord(queue: string, task: PendingTask): TokenedInflightRecord;
+/** The worker-facing identity of a long-poll claim: the synthetic worker id and its per-claim token. */
+export interface LongPollClaim {
+    workerId: string;
+    attemptToken: string;
+}
+export declare function markTaskClaimedByLongPollWorker(context: ServerContext, options: ServeOptions, queue: string, task: PendingTask): Promise<LongPollClaim>;
 export declare function handleTaskPollRequest(context: ServerContext, options: ServeOptions, request: Request, url: URL, principal?: Principal): Promise<Response | null>;
 export declare function handleTaskResultRequest(context: ServerContext, options: ServeOptions, request: Request, url: URL, principal?: Principal): Promise<Response | null>;
+export {};