@lostgradient/weft 0.3.0 → 0.4.0

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

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { defineOperation } from "../operation-registry.js";
+import { readRestTextBody } from "../rest-body.js";
 import { invalidParamsFault, shapeRestFault } from "./operation-helpers.js";
 const forkWorkflowInput = z.object({
   workflowId: z.string().min(1),
@@ -65,8 +66,8 @@ export const forkWorkflowOperation = defineOperation({
     workflowId: { kind: "path", pathParam: "id" },
     fromStep: { kind: "body-field", bodyField: "fromStep" }
   },
-  extractInput: async (request, pathParams) => {
-    const rawBody = await request.text();
+  extractInput: async (request, pathParams, context) => {
+    const rawBody = await readRestTextBody(request, context);
     if (rawBody.trim().length === 0)
       return { workflowId: pathParams.id ?? "" };
     let body;

package/dist/server/operations/get-checkpoint-at.d.ts

@@ -10,6 +10,6 @@ export type GetCheckpointAtOutput = CheckpointState;
 export declare const getCheckpointAtOperation: import("../operation-catalog.ts").OperationDefinition<{
     workflowId: string;
     step: number;
-}, CheckpointState>;
+}, CheckpointState, unknown>;
 export declare const getCheckpointAtRestBinding: UnknownRestBinding;
 export {};

package/dist/server/operations/get-registry.d.ts

@@ -21,6 +21,6 @@ import type { UnknownRestBinding } from '../rest-bindings.ts';
 declare const getRegistryInput: z.ZodObject<{}, z.core.$strip>;
 export type GetRegistryInput = z.infer<typeof getRegistryInput>;
 export type GetRegistryOutput = RegistrySnapshot;
-export declare const getRegistryOperation: import("../operation-catalog.ts").OperationDefinition<Record<string, never>, RegistrySnapshot>;
+export declare const getRegistryOperation: import("../operation-catalog.ts").OperationDefinition<Record<string, never>, RegistrySnapshot, unknown>;
 export declare const getRegistryRestBinding: UnknownRestBinding;
 export {};

package/dist/server/operations/get-retention-overview.d.ts

@@ -4,6 +4,6 @@ import type { UnknownRestBinding } from '../rest-bindings.ts';
 declare const getRetentionOverviewInput: z.ZodObject<{}, z.core.$strip>;
 export type GetRetentionOverviewInput = z.infer<typeof getRetentionOverviewInput>;
 export type GetRetentionOverviewOutput = RetentionOverview;
-export declare const getRetentionOverviewOperation: import("../operation-catalog.ts").OperationDefinition<Record<string, never>, RetentionOverview>;
+export declare const getRetentionOverviewOperation: import("../operation-catalog.ts").OperationDefinition<Record<string, never>, RetentionOverview, unknown>;
 export declare const getRetentionOverviewRestBinding: UnknownRestBinding;
 export {};

package/dist/server/operations/get-review.d.ts

@@ -10,6 +10,6 @@ export type GetReviewOutput = ReviewRequest;
 export declare const getReviewOperation: import("../operation-catalog.ts").OperationDefinition<{
     workflowId: string;
     reviewId: string;
-}, ReviewRequest>;
+}, ReviewRequest, unknown>;
 export declare const getReviewRestBinding: UnknownRestBinding;
 export {};

package/dist/server/operations/get-schedule.d.ts

@@ -15,6 +15,6 @@ export type GetScheduleInput = z.infer<typeof getScheduleInput>;
 export type GetScheduleOutput = ScheduleSummary;
 export declare const getScheduleOperation: import("../operation-catalog.ts").OperationDefinition<{
     scheduleId: string;
-}, ScheduleSummary>;
+}, ScheduleSummary, unknown>;
 export declare const getScheduleRestBinding: UnknownRestBinding;
 export {};

package/dist/server/operations/get-stream-chunks.d.ts

@@ -14,6 +14,6 @@ export declare const getStreamChunksOperation: import("../operation-catalog.ts")
     workflowId: string;
     key: string;
     after?: unknown;
-}, GetStreamChunksOutput>;
+}, GetStreamChunksOutput, unknown>;
 export declare const getStreamChunksRestBinding: UnknownRestBinding;
 export {};

package/dist/server/operations/get-system-metrics.d.ts

@@ -28,8 +28,8 @@ export type GetSystemMetricsOutput = MetricsSnapshot;
  */
 export declare function createGetSystemMetricsOperation(options?: {
     metricsCollector?: MetricsCollector | undefined;
-}): import("../operation-catalog.ts").OperationDefinition<Record<string, never>, MetricsSnapshot>;
-export declare const getSystemMetricsOperation: import("../operation-catalog.ts").OperationDefinition<Record<string, never>, MetricsSnapshot>;
+}): import("../operation-catalog.ts").OperationDefinition<Record<string, never>, MetricsSnapshot, unknown>;
+export declare const getSystemMetricsOperation: import("../operation-catalog.ts").OperationDefinition<Record<string, never>, MetricsSnapshot, unknown>;
 /**
  * Factory for the `weft.system.metrics` REST binding.
  *

package/dist/server/operations/get-task-diagnostics.d.ts

@@ -13,6 +13,7 @@ import type { WorkerRegistry } from '../../worker/registry.ts';
 import type { UnknownRestBinding } from '../rest-bindings.ts';
 import type { TaskQueue } from '../task-queue.ts';
 declare const taskDiagnosticKindSchema: z.ZodEnum<{
+    "dead-lettered": "dead-lettered";
     "stuck-queued": "stuck-queued";
     "stale-inflight": "stale-inflight";
     "retry-storm": "retry-storm";
@@ -20,12 +21,14 @@ declare const taskDiagnosticKindSchema: z.ZodEnum<{
 }>;
 declare const taskDiagnosticItemSchema: z.ZodObject<{
     kind: z.ZodEnum<{
+        "dead-lettered": "dead-lettered";
         "stuck-queued": "stuck-queued";
         "stale-inflight": "stale-inflight";
         "retry-storm": "retry-storm";
         "all-workers-at-capacity": "all-workers-at-capacity";
     }>;
     state: z.ZodEnum<{
+        "dead-lettered": "dead-lettered";
         queued: "queued";
         inflight: "inflight";
         resolved: "resolved";
@@ -46,6 +49,10 @@ declare const taskDiagnosticItemSchema: z.ZodObject<{
         "worker-disconnect": "worker-disconnect";
     }>>;
     resolutionReason: z.ZodOptional<z.ZodString>;
+    deadLetteredAt: z.ZodOptional<z.ZodNumber>;
+    deadLetterReason: z.ZodOptional<z.ZodLiteral<"result-resolution-storage-exhausted">>;
+    storageError: z.ZodOptional<z.ZodString>;
+    retryAttempts: z.ZodOptional<z.ZodNumber>;
     evidence: z.ZodArray<z.ZodString>;
 }, z.core.$strict>;
 declare const taskDiagnosticsSummarySchema: z.ZodObject<{
@@ -53,16 +60,19 @@ declare const taskDiagnosticsSummarySchema: z.ZodObject<{
     staleInflight: z.ZodNumber;
     retryStorms: z.ZodNumber;
     allWorkersAtCapacity: z.ZodNumber;
+    deadLettered: z.ZodNumber;
 }, z.core.$strict>;
 declare const getTaskDiagnosticsOutput: z.ZodObject<{
     items: z.ZodArray<z.ZodObject<{
         kind: z.ZodEnum<{
+            "dead-lettered": "dead-lettered";
             "stuck-queued": "stuck-queued";
             "stale-inflight": "stale-inflight";
             "retry-storm": "retry-storm";
             "all-workers-at-capacity": "all-workers-at-capacity";
         }>;
         state: z.ZodEnum<{
+            "dead-lettered": "dead-lettered";
             queued: "queued";
             inflight: "inflight";
             resolved: "resolved";
@@ -83,6 +93,10 @@ declare const getTaskDiagnosticsOutput: z.ZodObject<{
             "worker-disconnect": "worker-disconnect";
         }>>;
         resolutionReason: z.ZodOptional<z.ZodString>;
+        deadLetteredAt: z.ZodOptional<z.ZodNumber>;
+        deadLetterReason: z.ZodOptional<z.ZodLiteral<"result-resolution-storage-exhausted">>;
+        storageError: z.ZodOptional<z.ZodString>;
+        retryAttempts: z.ZodOptional<z.ZodNumber>;
         evidence: z.ZodArray<z.ZodString>;
     }, z.core.$strict>>;
     summary: z.ZodObject<{
@@ -90,6 +104,7 @@ declare const getTaskDiagnosticsOutput: z.ZodObject<{
         staleInflight: z.ZodNumber;
         retryStorms: z.ZodNumber;
         allWorkersAtCapacity: z.ZodNumber;
+        deadLettered: z.ZodNumber;
     }, z.core.$strict>;
     limit: z.ZodNumber;
 }, z.core.$strict>;
@@ -102,11 +117,19 @@ declare const getTaskDiagnosticsInput: z.ZodObject<{
     retryStormMinimumAttempts: z.ZodDefault<z.ZodNumber>;
     limit: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>;
+declare const clearTaskDeadLetterInput: z.ZodObject<{
+    operationId: z.ZodString;
+}, z.core.$strip>;
+declare const okOutput: z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+}, z.core.$strict>;
 export type GetTaskDiagnosticsInput = z.infer<typeof getTaskDiagnosticsInput>;
 export type TaskDiagnosticKind = z.infer<typeof taskDiagnosticKindSchema>;
 export type TaskDiagnosticItem = z.infer<typeof taskDiagnosticItemSchema>;
 export type TaskDiagnosticsSummary = z.infer<typeof taskDiagnosticsSummarySchema>;
 export type GetTaskDiagnosticsOutput = z.infer<typeof getTaskDiagnosticsOutput>;
+export type ClearTaskDeadLetterInput = z.infer<typeof clearTaskDeadLetterInput>;
+export type ClearTaskDeadLetterOutput = z.infer<typeof okOutput>;
 interface GetTaskDiagnosticsOptions {
     registry?: WorkerRegistry | undefined;
     taskQueue?: TaskQueue | undefined;
@@ -122,8 +145,8 @@ export declare function createGetTaskDiagnosticsOperation(options?: GetTaskDiagn
     queue?: string | undefined;
 }, {
     items: {
-        kind: "stuck-queued" | "stale-inflight" | "retry-storm" | "all-workers-at-capacity";
-        state: "queued" | "inflight" | "resolved" | "capacity";
+        kind: "dead-lettered" | "stuck-queued" | "stale-inflight" | "retry-storm" | "all-workers-at-capacity";
+        state: "dead-lettered" | "queued" | "inflight" | "resolved" | "capacity";
         retryCount: number;
         requeueCount: number;
         evidence: string[];
@@ -137,15 +160,20 @@ export declare function createGetTaskDiagnosticsOperation(options?: GetTaskDiagn
         heartbeatAgeMs?: number | undefined;
         lastRequeueReason?: "visibility-timeout" | "worker-disconnect" | undefined;
         resolutionReason?: string | undefined;
+        deadLetteredAt?: number | undefined;
+        deadLetterReason?: "result-resolution-storage-exhausted" | undefined;
+        storageError?: string | undefined;
+        retryAttempts?: number | undefined;
     }[];
     summary: {
         stuckQueued: number;
         staleInflight: number;
         retryStorms: number;
         allWorkersAtCapacity: number;
+        deadLettered: number;
     };
     limit: number;
-}>;
+}, unknown>;
 export declare const getTaskDiagnosticsOperation: import("../operation-catalog.ts").OperationDefinition<{
     staleQueuedAfterMs: number;
     staleHeartbeatAfterMs: number;
@@ -156,8 +184,8 @@ export declare const getTaskDiagnosticsOperation: import("../operation-catalog.t
     queue?: string | undefined;
 }, {
     items: {
-        kind: "stuck-queued" | "stale-inflight" | "retry-storm" | "all-workers-at-capacity";
-        state: "queued" | "inflight" | "resolved" | "capacity";
+        kind: "dead-lettered" | "stuck-queued" | "stale-inflight" | "retry-storm" | "all-workers-at-capacity";
+        state: "dead-lettered" | "queued" | "inflight" | "resolved" | "capacity";
         retryCount: number;
         requeueCount: number;
         evidence: string[];
@@ -171,14 +199,25 @@ export declare const getTaskDiagnosticsOperation: import("../operation-catalog.t
         heartbeatAgeMs?: number | undefined;
         lastRequeueReason?: "visibility-timeout" | "worker-disconnect" | undefined;
         resolutionReason?: string | undefined;
+        deadLetteredAt?: number | undefined;
+        deadLetterReason?: "result-resolution-storage-exhausted" | undefined;
+        storageError?: string | undefined;
+        retryAttempts?: number | undefined;
     }[];
     summary: {
         stuckQueued: number;
         staleInflight: number;
         retryStorms: number;
         allWorkersAtCapacity: number;
+        deadLettered: number;
     };
     limit: number;
-}>;
+}, unknown>;
+export declare const clearTaskDeadLetterOperation: import("../operation-catalog.ts").OperationDefinition<{
+    operationId: string;
+}, {
+    ok: true;
+}, unknown>;
 export declare const getTaskDiagnosticsRestBinding: UnknownRestBinding;
+export declare const clearTaskDeadLetterRestBinding: UnknownRestBinding;
 export {};

package/dist/server/operations/get-task-diagnostics.js

@@ -6,6 +6,8 @@ import {
   calculateExecutionLatencyMs,
   calculateHeartbeatAgeMs,
   calculateQueueLatencyMs,
+  clearDeadLetteredTaskRecord,
+  isDeadLetteredTaskRecord,
   isInflightRecord,
   isQueuedRecord,
   isResolvedRecord
@@ -15,10 +17,11 @@ const DEFAULT_STALE_QUEUED_AFTER_MS = 60000, DEFAULT_STALE_HEARTBEAT_AFTER_MS =
   "stuck-queued",
   "stale-inflight",
   "retry-storm",
-  "all-workers-at-capacity"
+  "all-workers-at-capacity",
+  "dead-lettered"
 ]), taskDiagnosticItemSchema = z.object({
   kind: taskDiagnosticKindSchema,
-  state: z.enum(["queued", "inflight", "resolved", "capacity"]),
+  state: z.enum(["queued", "inflight", "resolved", "capacity", "dead-lettered"]),
   operationId: z.string().optional(),
   workflowId: z.string().optional(),
   activityName: z.string().optional(),
@@ -31,12 +34,17 @@ const DEFAULT_STALE_QUEUED_AFTER_MS = 60000, DEFAULT_STALE_HEARTBEAT_AFTER_MS =
   heartbeatAgeMs: z.number().nonnegative().optional(),
   lastRequeueReason: z.enum(["visibility-timeout", "worker-disconnect"]).optional(),
   resolutionReason: z.string().optional(),
+  deadLetteredAt: z.number().nonnegative().optional(),
+  deadLetterReason: z.literal("result-resolution-storage-exhausted").optional(),
+  storageError: z.string().optional(),
+  retryAttempts: z.number().int().nonnegative().optional(),
   evidence: z.array(z.string())
 }).strict(), taskDiagnosticsSummarySchema = z.object({
   stuckQueued: z.number().int().nonnegative(),
   staleInflight: z.number().int().nonnegative(),
   retryStorms: z.number().int().nonnegative(),
-  allWorkersAtCapacity: z.number().int().nonnegative()
+  allWorkersAtCapacity: z.number().int().nonnegative(),
+  deadLettered: z.number().int().nonnegative()
 }).strict(), getTaskDiagnosticsOutput = z.object({
   items: z.array(taskDiagnosticItemSchema),
   summary: taskDiagnosticsSummarySchema,
@@ -49,7 +57,14 @@ const DEFAULT_STALE_QUEUED_AFTER_MS = 60000, DEFAULT_STALE_HEARTBEAT_AFTER_MS =
   staleHeartbeatAfterMs: z.number().int().nonnegative().default(DEFAULT_STALE_HEARTBEAT_AFTER_MS),
   retryStormMinimumAttempts: z.number().int().min(1).default(DEFAULT_RETRY_STORM_MINIMUM_ATTEMPTS),
   limit: z.number().int().min(1).max(MAX_LIMIT).default(DEFAULT_LIMIT)
-});
+}), clearTaskDeadLetterInput = z.object({
+  operationId: z.string().min(1)
+}), okOutput = z.object({ ok: z.literal(!0) }).strict(), restOnlyTaskDiagnosticsTransports = {
+  http: !0,
+  jsonRpcHttp: !1,
+  jsonRpcWebSocket: !1,
+  jsonRpcStdio: !1
+};
 export function createGetTaskDiagnosticsOperation(options = {}) {
   return defineOperation({
     name: "weft.tasks.diagnostics",
@@ -79,7 +94,27 @@ export function createGetTaskDiagnosticsOperation(options = {}) {
     }
   });
 }
-export const getTaskDiagnosticsOperation = createGetTaskDiagnosticsOperation();
+export const getTaskDiagnosticsOperation = createGetTaskDiagnosticsOperation(), clearTaskDeadLetterOperation = defineOperation({
+  name: "weft.tasks.diagnostics.deadletters.clear",
+  mcpExposable: !1,
+  summary: "Clear a task-result dead-letter diagnostic entry",
+  destructive: !0,
+  tags: ["Observability"],
+  inputSchema: clearTaskDeadLetterInput,
+  outputSchema: okOutput,
+  access: {
+    kind: "scoped",
+    scopes: { kind: "anyOf", scopes: ["system:admin"] }
+  },
+  producibleFaults: [],
+  discoverable: !0,
+  transports: restOnlyTaskDiagnosticsTransports,
+  unknownKeyPolicy: { http: "reject", jsonRpc: "reject" },
+  invoke: async ({ input, engine }) => {
+    await clearDeadLetteredTaskRecord(engine.storage, input.operationId);
+    return { ok: !0 };
+  }
+});
 async function collectTaskDiagnostics({
   engine,
   input,
@@ -91,12 +126,21 @@ async function collectTaskDiagnostics({
     stuckQueued: 0,
     staleInflight: 0,
     retryStorms: 0,
-    allWorkersAtCapacity: 0
-  }, relevantQueues = new Set, addItem = (item) => {
+    allWorkersAtCapacity: 0,
+    deadLettered: 0
+  }, relevantQueues = new Set, deadLetteredOperationIds = new Set, addItem = (item) => {
     incrementSummary(summary, item.kind);
     if (items.length < input.limit)
       items.push(item);
   };
+  for await (const record of scanDeadLetterRecords(engine)) {
+    if (!matchesTaskRecordFilter(record, input))
+      continue;
+    deadLetteredOperationIds.add(record.operationId);
+    if (record.queue !== void 0)
+      relevantQueues.add(record.queue);
+    addDeadLetterDiagnostics(record, addItem);
+  }
   for await (const record of scanQueuedRecords(engine)) {
     if (!matchesTaskRecordFilter(record, input))
       continue;
@@ -106,6 +150,8 @@ async function collectTaskDiagnostics({
   for await (const record of scanInflightRecords(engine)) {
     if (!matchesTaskRecordFilter(record, input))
       continue;
+    if (deadLetteredOperationIds.has(record.operationId))
+      continue;
     relevantQueues.add(record.queue);
     addInflightDiagnostics(record, input, currentTime, addItem);
   }
@@ -125,6 +171,13 @@ async function collectTaskDiagnostics({
   });
   return { items, summary, limit: input.limit };
 }
+async function* scanDeadLetterRecords(engine) {
+  for await (const [, value] of engine.storage.scan(KEYS.operationDeadLetterPrefix())) {
+    const decoded = decode(value);
+    if (isDeadLetteredTaskRecord(decoded))
+      yield decoded;
+  }
+}
 async function* scanQueuedRecords(engine) {
   for await (const [, value] of engine.storage.scan("op:queued:")) {
     const decoded = decode(value);
@@ -201,6 +254,27 @@ function addInflightDiagnostics(record, input, currentTime, addItem) {
     });
   addRetryStormDiagnostic(record, "inflight", input, addItem);
 }
+function addDeadLetterDiagnostics(record, addItem) {
+  addItem({
+    kind: "dead-lettered",
+    state: "dead-lettered",
+    operationId: record.operationId,
+    workflowId: record.workflowId,
+    activityName: record.activityName,
+    queue: record.queue,
+    workerId: record.workerId,
+    retryCount: record.retryCount ?? Math.max(0, (record.attempt ?? 1) - 1),
+    requeueCount: record.requeueCount ?? 0,
+    lastRequeueReason: record.lastRequeueReason,
+    deadLetteredAt: record.deadLetteredAt,
+    deadLetterReason: record.reason,
+    storageError: record.errorMessage,
+    retryAttempts: record.retryAttempts,
+    evidence: [
+      `Task result transition exhausted ${record.retryAttempts} storage attempts; reconciliation will not re-dispatch operation "${record.operationId}" until the dead-letter entry is cleared`
+    ]
+  });
+}
 function addRetryStormDiagnostic(record, state, input, addItem) {
   const retryCount = record.retryCount ?? Math.max(0, (record.attempt ?? 1) - 1), requeueCount = record.requeueCount ?? 0;
   if (retryCount < input.retryStormMinimumAttempts && requeueCount < input.retryStormMinimumAttempts)
@@ -300,6 +374,9 @@ function incrementSummary(summary, kind) {
     case "all-workers-at-capacity":
       summary.allWorkersAtCapacity += 1;
       return;
+    case "dead-lettered":
+      summary.deadLettered += 1;
+      return;
   }
 }
 function parseOptionalNumber(value) {
@@ -337,4 +414,21 @@ export const getTaskDiagnosticsRestBinding = {
     headers: { "Content-Type": "application/json" }
   }),
   shapeFault: shapeRestFault
+}, clearTaskDeadLetterRestBinding = {
+  method: "DELETE",
+  path: "/v1/tasks/diagnostics/dead-letter/:operationId",
+  pathParamNames: ["operationId"],
+  operationName: "weft.tasks.diagnostics.deadletters.clear",
+  inputSources: {
+    operationId: { kind: "path", pathParam: "operationId" }
+  },
+  extractInput: async (_request, pathParams) => ({
+    operationId: pathParams.operationId ?? ""
+  }),
+  success: { kind: "json", status: 200 },
+  shapeSuccess: (output) => new Response(JSON.stringify(output), {
+    status: 200,
+    headers: { "Content-Type": "application/json" }
+  }),
+  shapeFault: shapeRestFault
 };

package/dist/server/operations/get-update-result.d.ts

@@ -13,6 +13,6 @@ export type GetUpdateResultOutput = {
 };
 export declare const getUpdateResultOperation: import("../operation-catalog.ts").OperationDefinition<{
     updateId: string;
-}, GetUpdateResultOutput>;
+}, GetUpdateResultOutput, unknown>;
 export declare const getUpdateResultRestBinding: UnknownRestBinding;
 export {};

package/dist/server/operations/get-workflow-attributes.d.ts

@@ -8,6 +8,6 @@ export type GetWorkflowAttributesInput = z.infer<typeof getWorkflowAttributesInp
 export type GetWorkflowAttributesOutput = Record<string, SearchAttributeValue>;
 export declare const getWorkflowAttributesOperation: import("../operation-catalog.ts").OperationDefinition<{
     workflowId: string;
-}, GetWorkflowAttributesOutput>;
+}, GetWorkflowAttributesOutput, unknown>;
 export declare const getWorkflowAttributesRestBinding: UnknownRestBinding;
 export {};

package/dist/server/operations/get-workflow-events.d.ts

@@ -10,6 +10,6 @@ export type GetWorkflowEventsOutput = {
 };
 export declare const getWorkflowEventsOperation: import("../operation-catalog.ts").OperationDefinition<{
     workflowId: string;
-}, GetWorkflowEventsOutput>;
+}, GetWorkflowEventsOutput, unknown>;
 export declare const getWorkflowEventsRestBinding: UnknownRestBinding;
 export {};

package/dist/server/operations/get-workflow-result.d.ts

@@ -9,6 +9,6 @@ export type GetWorkflowResultOutput = {
 };
 export declare const getWorkflowResultOperation: import("../operation-catalog.ts").OperationDefinition<{
     workflowId: string;
-}, GetWorkflowResultOutput>;
+}, GetWorkflowResultOutput, unknown>;
 export declare const getWorkflowResultRestBinding: UnknownRestBinding;
 export {};

package/dist/server/operations/get-workflow-timeline.d.ts

@@ -8,6 +8,6 @@ export type GetWorkflowTimelineInput = z.infer<typeof getWorkflowTimelineInput>;
 export type GetWorkflowTimelineOutput = WorkflowTimelineEntry[];
 export declare const getWorkflowTimelineOperation: import("../operation-catalog.ts").OperationDefinition<{
     workflowId: string;
-}, GetWorkflowTimelineOutput>;
+}, GetWorkflowTimelineOutput, unknown>;
 export declare const getWorkflowTimelineRestBinding: UnknownRestBinding;
 export {};

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

@@ -18,7 +18,7 @@ export type GetWorkflowInput = z.infer<typeof getWorkflowInput>;
 export type GetWorkflowOutput = WorkflowState;
 export declare const getWorkflowOperation: import("../operation-catalog.ts").OperationDefinition<{
     workflowId: string;
-}, WorkflowState>;
+}, WorkflowState, unknown>;
 /**
  * RestBinding for `GET /v1/workflows/:id`. Pulls the workflow id from
  * the path param, invokes the operation, maps success/fault to the

package/dist/server/operations/list-checkpoints.d.ts

@@ -8,6 +8,6 @@ export type ListCheckpointsInput = z.infer<typeof listCheckpointsInput>;
 export type ListCheckpointsOutput = CheckpointSummary[];
 export declare const listCheckpointsOperation: import("../operation-catalog.ts").OperationDefinition<{
     workflowId: string;
-}, ListCheckpointsOutput>;
+}, ListCheckpointsOutput, unknown>;
 export declare const listCheckpointsRestBinding: UnknownRestBinding;
 export {};

package/dist/server/operations/list-reviews.d.ts

@@ -14,6 +14,6 @@ export declare const listReviewsOperation: import("../operation-catalog.ts").Ope
     status?: ReviewStatus | undefined;
     workflowId?: string | undefined;
     reviewType?: string | undefined;
-}, ListReviewsOutput>;
+}, ListReviewsOutput, unknown>;
 export declare const listReviewsRestBinding: UnknownRestBinding;
 export {};

package/dist/server/operations/list-schedules.d.ts

@@ -23,6 +23,6 @@ export declare const listSchedulesOperation: import("../operation-catalog.ts").O
     workflowType?: unknown;
     limit?: unknown;
     offset?: unknown;
-}, ListSchedulesOutput>;
+}, ListSchedulesOutput, unknown>;
 export declare const listSchedulesRestBinding: UnknownRestBinding;
 export {};

package/dist/server/operations/list-task-queues.d.ts

@@ -52,7 +52,7 @@ type ListTaskQueuesOptions = {
  * with metadata only — discovery output still describes the endpoint —
  * but `invoke` throws if called.
  */
-export declare function createListTaskQueuesOperation(options?: ListTaskQueuesOptions): import("../operation-catalog.ts").OperationDefinition<Record<string, never>, ListTaskQueuesOutput>;
+export declare function createListTaskQueuesOperation(options?: ListTaskQueuesOptions): import("../operation-catalog.ts").OperationDefinition<Record<string, never>, ListTaskQueuesOutput, unknown>;
 type MergeArgs = {
     now: number;
     workerSummaries: WorkerSummary[];
@@ -65,7 +65,7 @@ type MergeArgs = {
  */
 export declare function mergeQueueHealth(args: MergeArgs): TaskQueueHealth[];
 /** Default discovery-only operation; live servers use `createListTaskQueuesOperation(...)`. */
-export declare const listTaskQueuesOperation: import("../operation-catalog.ts").OperationDefinition<Record<string, never>, ListTaskQueuesOutput>;
+export declare const listTaskQueuesOperation: import("../operation-catalog.ts").OperationDefinition<Record<string, never>, ListTaskQueuesOutput, unknown>;
 /** Build the REST binding for `weft.task.queues.list`. */
 export declare function createListTaskQueuesRestBinding(): UnknownRestBinding;
 export {};

package/dist/server/operations/list-workers.d.ts

@@ -44,9 +44,9 @@ type ListWorkersOptions = {
  * stays honest, but `invoke` throws if called — this path is reserved
  * for discovery-only registries (OpenAPI/AsyncAPI generators).
  */
-export declare function createListWorkersOperation(options?: ListWorkersOptions): import("../operation-catalog.ts").OperationDefinition<Record<string, never>, ListWorkersOutput>;
+export declare function createListWorkersOperation(options?: ListWorkersOptions): import("../operation-catalog.ts").OperationDefinition<Record<string, never>, ListWorkersOutput, unknown>;
 /** Default discovery-only operation; live servers use `createListWorkersOperation(...)`. */
-export declare const listWorkersOperation: import("../operation-catalog.ts").OperationDefinition<Record<string, never>, ListWorkersOutput>;
+export declare const listWorkersOperation: import("../operation-catalog.ts").OperationDefinition<Record<string, never>, ListWorkersOutput, unknown>;
 /**
  * Build the REST binding for `weft.workers.list`. The binding is metadata
  * only; the live `WorkerRegistry` is wired into the operation, not the

package/dist/server/operations/list-workflows.d.ts

@@ -74,6 +74,6 @@ export declare const listWorkflowsOperation: import("../operation-catalog.ts").O
     } | undefined;
     failureCategory?: FailureCategory | FailureCategory[] | undefined;
     include?: string | string[] | undefined;
-}, ListWorkflowsOutput>;
+}, ListWorkflowsOutput, unknown>;
 export declare const listWorkflowsRestBinding: UnknownRestBinding;
 export {};

package/dist/server/operations/operation-helpers.d.ts

@@ -1,3 +1,4 @@
+import { type WeftErrorCode } from '../../core/weft-error.ts';
 import { type OperationFault } from '../operation-fault.ts';
 /** Type guard distinguishing an `OperationFault` from a value type. */
 export declare function isOperationFault(value: unknown): value is OperationFault;
@@ -11,11 +12,25 @@ export declare function jsonErrorResponse(message: string, status: number): Resp
  * Construct an `InvalidParams` fault with the `{ issues: [] }` data
  * shape. This is the canonical 400-class fault for caller-input validation
  * errors raised inside `invoke()` or `extractInput()`.
+ *
+ * Pass `weftCode` only when a typed `WeftError` is in hand (e.g. a caught
+ * `WorkflowNotRegisteredError`) so REST clients can branch on it through
+ * `isWeftFault`. It is omitted entirely when absent — never written as
+ * `weftCode: undefined` — so the dozens of generic validation callers keep
+ * their exact `{ issues: [] }` data shape.
  */
-export declare function invalidParamsFault(message: string): OperationFault;
+export declare function invalidParamsFault(message: string, weftCode?: WeftErrorCode): OperationFault;
 /**
  * Default REST fault shaper: masks `EngineFailure` to a generic
  * `"Internal server error"` 500; other faults map by `FAULT_CODE_TO_HTTP_STATUS`.
  * REST-only — JSON-RPC transports receive unmasked faults.
+ *
+ * When the fault carries a fine-grained `data.weftCode` (set only at sites that
+ * hold a typed `WeftError`, e.g. `WorkflowNotFoundError` /
+ * `WorkflowNotRegisteredError`), it is emitted as a top-level `weftCode` sibling
+ * of the flat `{ error }` body so REST clients can branch transport-uniformly
+ * via `isWeftFault`. The body's `error` stays a plain string, so the new field
+ * is a sibling rather than nested. Faults without a `weftCode` keep their exact
+ * `{ error }` shape, and `EngineFailure` stays masked (it carries no weftCode).
  */
 export declare function shapeRestFault(fault: OperationFault): Response;

package/dist/server/operations/operation-helpers.js

@@ -1,3 +1,4 @@
+import { isWeftErrorCode } from "../../core/weft-error.js";
 import { FAULT_CODE_TO_HTTP_STATUS } from "../operation-fault.js";
 export function isOperationFault(value) {
   return typeof value === "object" && value !== null && "code" in value && "message" in value && "data" in value;
@@ -8,15 +9,26 @@ export function jsonErrorResponse(message, status) {
     headers: { "Content-Type": "application/json" }
   });
 }
-export function invalidParamsFault(message) {
+export function invalidParamsFault(message, weftCode) {
   return {
     code: "InvalidParams",
     message,
-    data: { issues: [] }
+    data: weftCode === void 0 ? { issues: [] } : { issues: [], weftCode }
   };
 }
 export function shapeRestFault(fault) {
   if (fault.code === "EngineFailure")
     return jsonErrorResponse("Internal server error", 500);
-  return jsonErrorResponse(fault.message, FAULT_CODE_TO_HTTP_STATUS[fault.code]);
+  const status = FAULT_CODE_TO_HTTP_STATUS[fault.code], weftCode = weftCodeFromFaultData(fault.data);
+  if (weftCode === void 0)
+    return jsonErrorResponse(fault.message, status);
+  return new Response(JSON.stringify({ error: fault.message, weftCode }), {
+    status,
+    headers: { "Content-Type": "application/json" }
+  });
+}
+function weftCodeFromFaultData(data) {
+  if (typeof data !== "object" || data === null || !("weftCode" in data))
+    return;
+  return isWeftErrorCode(data.weftCode) ? data.weftCode : void 0;
 }

package/dist/server/operations/pause-schedule.d.ts

@@ -8,6 +8,6 @@ export type PauseScheduleInput = z.infer<typeof pauseScheduleInput>;
 export type PauseScheduleOutput = z.infer<typeof pauseScheduleOutput>;
 export declare const pauseScheduleOperation: import("../operation-catalog.ts").OperationDefinition<{
     scheduleId: string;
-}, undefined>;
+}, undefined, unknown>;
 export declare const pauseScheduleRestBinding: UnknownRestBinding;
 export {};