@lostgradient/weft 0.24.0 → 0.24.1

package/README.md

@@ -1,6 +1,6 @@
 # Weft
 
-A Bun-native durable execution engine. Current release: `0.24.0`.
+A Bun-native durable execution engine. Current release: `0.24.1`.
 
 Install the library from npm as `@lostgradient/weft`:
 
@@ -435,7 +435,7 @@ await using server = serve({ engine, port: 7233 });
 // server.url is e.g. "http://0.0.0.0:7233"
 ```
 
-Endpoints under `/api/v1/` cover the full lifecycle: start workflows, list, signal, update, query, cancel, fork, and stream events. JSON-RPC over WebSocket also exposes workflow and fleet event subscriptions for operator UIs that need live state without polling. Content negotiation supports JSON and MessagePack. `engine.workflows` and the matching `/v1/registry/` operations expose the durable workflow catalog for admin tooling — install a revision's manifest and activate it as the advertised active revision — bookkeeping only, never workflow execution routing; see [`workflow-versioning.md`](documentation/guides/workflow-versioning.md#engineworkflows-public-catalog-control). `workflowSource()` pairs a typed, serializable source descriptor with a never-serialized loader capability, so one workflow can register lazily while another stays eagerly registered; `engine.registerSource()` records the candidate without importing it, and `engine.resolveWorkflowSource()` loads, validates, and installs it into the same catalog with single-flight deduplication per `(name, revision)`; see [Dynamic Workflow Sources](documentation/guides/workflow-versioning.md#dynamic-workflow-sources). The server can also mount an externally supplied dashboard shell at known page routes; see the [server guide](documentation/guides/server.md#external-dashboard-mounting) for the hosting contract.
+Endpoints under `/api/v1/` cover the full lifecycle: start workflows, list, signal, update, query, cancel, fork, and stream events. JSON-RPC over WebSocket also exposes workflow and fleet event subscriptions for operator UIs that need live state without polling. Content negotiation supports JSON and MessagePack. `engine.workflows` and the matching `/v1/registry/` operations expose the durable workflow catalog for admin tooling — install a revision's manifest and activate it as the advertised active revision — bookkeeping only, never workflow execution routing; see [`workflow-versioning.md`](documentation/guides/workflow-versioning.md#engineworkflows-public-catalog-control). `workflowSource()` pairs a typed, serializable source descriptor with a never-serialized loader capability, so one workflow can register lazily while another stays eagerly registered; `engine.registerSource()` records the candidate without importing it, and `engine.resolveWorkflowSource()` (or its `engine.workflows.preload()` alias) loads, validates, and installs it into the same catalog with single-flight deduplication per `(name, revision)`. Every execution entry point — `start()`, `startOrSignal()`, `schedule()`, `fork()`, `resume()`, and recovery — awaits resolution for a lazy type before running any handler code, with bounded diagnostics and process-local events for the load pipeline; see [Engine Integration](documentation/guides/workflow-versioning.md#engine-integration-wft-1516). The server can also mount an externally supplied dashboard shell at known page routes; see the [server guide](documentation/guides/server.md#external-dashboard-mounting) for the hosting contract.
 
 ### Remote Workers
 

package/dist/cli/conformance.js

@@ -119,14 +119,15 @@ async function readResolvedStatus(storage, operationId) {
 async function waitForResolvedStatus(storage, operationId, status, timeoutMs) {
   await waitForCondition(async () => await readResolvedStatus(storage, operationId) === status, timeoutMs, `${operationId} to resolve as ${status}`);
 }
-async function dispatchAndWait(server, storage, operationId, activityName, input, expectedStatus, timeoutMs) {
+async function dispatchAndWait(server, storage, operationId, activityName, input, expectedStatus, timeoutMs, workflowRevision) {
   if (!await server.dispatchTask({
     operationId,
     activityName,
     workflowType: "conformance",
     input,
     queue: CONFORMANCE_QUEUE,
-    visibilityTimeout: Math.max(500, timeoutMs)
+    visibilityTimeout: Math.max(500, timeoutMs),
+    ...workflowRevision !== void 0 && { workflowRevision }
   }))
     throw Error(`Could not dispatch ${operationId}`);
   await waitForResolvedStatus(storage, operationId, expectedStatus, timeoutMs);
@@ -184,6 +185,8 @@ async function runConformanceChecks(command, timeoutMs) {
     await waitForWorkerIdle(server, replacementWorkerId, timeoutMs);
     await waitForResolvedStatus(storage, reconnectOperationId, "completed", timeoutMs);
     checks.push(createCheck("reconnect", !0, "in-flight task completed after reconnect"));
+    await dispatchAndWait(server, storage, "conformance-revision-echo", "conformance.echo", { ok: !0 }, "completed", timeoutMs, "conformance-revision-1");
+    checks.push(createCheck("revision echo", !0, "workflowRevision echoed and accepted"));
     const shutdownWorkerId = server.registry.getWorker(replacementWorkerId)?.id;
     if (shutdownWorkerId === void 0)
       throw Error("No worker available for graceful shutdown check");

package/dist/cli/generated/operation-catalog.snapshot.json

@@ -173,7 +173,7 @@
       "name": "weft.catalog.diagnostics",
       "kind": "unary",
       "summary": "Get bounded reference-count and removability diagnostics for one workflow revision",
-      "description": "Report whether a `(name, revision)` workflow catalog entry is installed, whether it is currently the active revision, its full reference-count breakdown, and whether it's currently removable. Never returns manifest or contract content.",
+      "description": "Report whether a `(name, revision)` workflow catalog entry is installed, whether it is currently the active revision, its full reference-count breakdown, and whether it's currently removable. When `name` was ever registered as a dynamic workflow source (`engine.registerSource()`), also reports its bounded load-state diagnostics: source kind, load state, load duration, last failure category, and outstanding waiter count. Never returns manifest or contract content.",
       "tags": ["Observability"],
       "destructive": false,
       "access": {
@@ -272,6 +272,37 @@
           },
           "revision": {
             "type": "string"
+          },
+          "source": {
+            "additionalProperties": false,
+            "properties": {
+              "kind": {
+                "const": "module",
+                "type": "string"
+              },
+              "lastFailureCategory": {
+                "enum": ["application", "timeout", "cancellation", "resource", "system"],
+                "type": "string"
+              },
+              "loadDurationMs": {
+                "minimum": 0,
+                "type": "number"
+              },
+              "requestedRevision": {
+                "type": "string"
+              },
+              "state": {
+                "enum": ["idle", "loading", "ready", "failed", "cancelled"],
+                "type": "string"
+              },
+              "waiterCount": {
+                "maximum": 9007199254740991,
+                "minimum": 0,
+                "type": "integer"
+              }
+            },
+            "required": ["kind", "requestedRevision", "state", "waiterCount"],
+            "type": "object"
           }
         },
         "required": ["name", "revision", "installed", "active", "references", "removable"],
@@ -926,6 +957,9 @@
           "input": {},
           "jitter": {},
           "overlap": {},
+          "revisionPolicy": {
+            "description": "Revision policy (WFT-20). Runtime validation requires \"active-at-fire\" or \"pinned\"; defaults to \"active-at-fire\"."
+          },
           "type": {
             "description": "Workflow type name. Runtime validation requires a non-empty string."
           }
@@ -1095,6 +1129,9 @@
           },
           "jitter": {},
           "overlap": {},
+          "revisionPolicy": {
+            "description": "Revision policy (WFT-20). Runtime validation requires \"active-at-fire\" or \"pinned\". Omitted preserves the current policy (and pin); \"pinned\" always re-resolves and re-captures the pin against the revision active right now."
+          },
           "scheduleId": {
             "minLength": 1,
             "type": "string"
@@ -2351,6 +2388,9 @@
               "workflowId": {
                 "type": "string"
               },
+              "workflowRevision": {
+                "type": "string"
+              },
               "workflowType": {
                 "type": "string"
               }
@@ -2512,6 +2552,9 @@
               "workflowId": {
                 "type": "string"
               },
+              "workflowRevision": {
+                "type": "string"
+              },
               "workflowType": {
                 "type": "string"
               }
@@ -2682,6 +2725,9 @@
               "workflowId": {
                 "type": "string"
               },
+              "workflowRevision": {
+                "type": "string"
+              },
               "workflowType": {
                 "type": "string"
               }
@@ -2853,6 +2899,9 @@
               "workflowId": {
                 "type": "string"
               },
+              "workflowRevision": {
+                "type": "string"
+              },
               "workflowType": {
                 "type": "string"
               }
@@ -3020,6 +3069,9 @@
                   "workflowId": {
                     "type": "string"
                   },
+                  "workflowRevision": {
+                    "type": "string"
+                  },
                   "workflowType": {
                     "type": "string"
                   }
@@ -3174,6 +3226,9 @@
                   "workflowId": {
                     "type": "string"
                   },
+                  "workflowRevision": {
+                    "type": "string"
+                  },
                   "workflowType": {
                     "type": "string"
                   }
@@ -3327,6 +3382,9 @@
                   "workflowId": {
                     "type": "string"
                   },
+                  "workflowRevision": {
+                    "type": "string"
+                  },
                   "workflowType": {
                     "type": "string"
                   }
@@ -3490,6 +3548,9 @@
               "workflowId": {
                 "type": "string"
               },
+              "workflowRevision": {
+                "type": "string"
+              },
               "workflowType": {
                 "type": "string"
               }
@@ -7750,6 +7811,39 @@
       },
       "outputSchema": {}
     },
+    {
+      "name": "weft.workflows.revisions.preload",
+      "kind": "unary",
+      "summary": "Load, validate, and install a registered dynamic workflow source revision",
+      "description": "Load, validate, and install `(name, revision)` — previously recorded via engine.registerSource() — durably into the workflow catalog. Faults NotFound when no source was ever registered for this exact key, and Conflict when the load fails or the loaded module fails validation.",
+      "tags": ["Workflow Catalog"],
+      "destructive": false,
+      "access": {
+        "kind": "scoped",
+        "scopes": ["workflows:admin"]
+      },
+      "transports": {
+        "http": true,
+        "jsonRpcHttp": true,
+        "jsonRpcWebSocket": true,
+        "jsonRpcStdio": true
+      },
+      "producibleFaults": ["Conflict", "InvalidParams", "NotFound"],
+      "inputSchema": {
+        "additionalProperties": false,
+        "properties": {
+          "name": {
+            "description": "Workflow name. Runtime validation requires a wire-safe identifier."
+          },
+          "revision": {
+            "description": "The registerSource()-registered revision to load, validate, and install. Runtime validation requires a non-empty string."
+          }
+        },
+        "required": ["name", "revision"],
+        "type": "object"
+      },
+      "outputSchema": {}
+    },
     {
       "name": "weft.workflows.scheduleprovenance.get",
       "kind": "unary",

package/dist/cli/generated/operation-client.generated.d.ts

@@ -1,7 +1,7 @@
 import { type CatalogWeftClient, type WeftClientConnection } from '../operation-client-runtime.ts';
-export declare const CATALOG_OPERATION_NAMES: readonly ["weft.activities.complete", "weft.activities.fail", "weft.alerts.list", "weft.catalog.diagnostics", "weft.recover.all", "weft.retention.get", "weft.reviews.decision.submit", "weft.reviews.get", "weft.reviews.list", "weft.schedules.cancel", "weft.schedules.create", "weft.schedules.get", "weft.schedules.list", "weft.schedules.pause", "weft.schedules.resume", "weft.schedules.update", "weft.storage.capabilities", "weft.system.lease", "weft.system.metrics", "weft.system.principal", "weft.system.registry", "weft.task.queues.list", "weft.tasks.diagnostics", "weft.tasks.get", "weft.updates.result.get", "weft.worker.deployments.drain", "weft.worker.deployments.resume", "weft.workers.diagnostics", "weft.workers.drain", "weft.workers.list", "weft.workers.rejections", "weft.workers.resume", "weft.workflows.active.get", "weft.workflows.activities.pending.list", "weft.workflows.aggregate", "weft.workflows.attributes.get", "weft.workflows.attributes.set", "weft.workflows.bulk.cancel", "weft.workflows.bulk.delete", "weft.workflows.bulk.retryfailed", "weft.workflows.bulk.signal", "weft.workflows.bulk.tags", "weft.workflows.cancel", "weft.workflows.checkpoints.get", "weft.workflows.checkpoints.list", "weft.workflows.events.list", "weft.workflows.finalizer.get", "weft.workflows.fork", "weft.workflows.get", "weft.workflows.list", "weft.workflows.purge", "weft.workflows.query", "weft.workflows.replay", "weft.workflows.result.get", "weft.workflows.resume", "weft.workflows.revisions.activate", "weft.workflows.revisions.get", "weft.workflows.revisions.install", "weft.workflows.revisions.list", "weft.workflows.scheduleprovenance.get", "weft.workflows.signal", "weft.workflows.start", "weft.workflows.startorsignal", "weft.workflows.streams.chunks", "weft.workflows.suspend", "weft.workflows.tags.add", "weft.workflows.tags.remove", "weft.workflows.timeline.get", "weft.workflows.timeout", "weft.workflows.update"];
+export declare const CATALOG_OPERATION_NAMES: readonly ["weft.activities.complete", "weft.activities.fail", "weft.alerts.list", "weft.catalog.diagnostics", "weft.recover.all", "weft.retention.get", "weft.reviews.decision.submit", "weft.reviews.get", "weft.reviews.list", "weft.schedules.cancel", "weft.schedules.create", "weft.schedules.get", "weft.schedules.list", "weft.schedules.pause", "weft.schedules.resume", "weft.schedules.update", "weft.storage.capabilities", "weft.system.lease", "weft.system.metrics", "weft.system.principal", "weft.system.registry", "weft.task.queues.list", "weft.tasks.diagnostics", "weft.tasks.get", "weft.updates.result.get", "weft.worker.deployments.drain", "weft.worker.deployments.resume", "weft.workers.diagnostics", "weft.workers.drain", "weft.workers.list", "weft.workers.rejections", "weft.workers.resume", "weft.workflows.active.get", "weft.workflows.activities.pending.list", "weft.workflows.aggregate", "weft.workflows.attributes.get", "weft.workflows.attributes.set", "weft.workflows.bulk.cancel", "weft.workflows.bulk.delete", "weft.workflows.bulk.retryfailed", "weft.workflows.bulk.signal", "weft.workflows.bulk.tags", "weft.workflows.cancel", "weft.workflows.checkpoints.get", "weft.workflows.checkpoints.list", "weft.workflows.events.list", "weft.workflows.finalizer.get", "weft.workflows.fork", "weft.workflows.get", "weft.workflows.list", "weft.workflows.purge", "weft.workflows.query", "weft.workflows.replay", "weft.workflows.result.get", "weft.workflows.resume", "weft.workflows.revisions.activate", "weft.workflows.revisions.get", "weft.workflows.revisions.install", "weft.workflows.revisions.list", "weft.workflows.revisions.preload", "weft.workflows.scheduleprovenance.get", "weft.workflows.signal", "weft.workflows.start", "weft.workflows.startorsignal", "weft.workflows.streams.chunks", "weft.workflows.suspend", "weft.workflows.tags.add", "weft.workflows.tags.remove", "weft.workflows.timeline.get", "weft.workflows.timeout", "weft.workflows.update"];
 export type CatalogOperationName = (typeof CATALOG_OPERATION_NAMES)[number];
-export declare const CLIENT_OPERATION_NAMES: readonly ["weft.activities.complete", "weft.activities.fail", "weft.alerts.list", "weft.catalog.diagnostics", "weft.recover.all", "weft.retention.get", "weft.reviews.decision.submit", "weft.reviews.get", "weft.reviews.list", "weft.schedules.cancel", "weft.schedules.create", "weft.schedules.get", "weft.schedules.list", "weft.schedules.pause", "weft.schedules.resume", "weft.schedules.update", "weft.storage.capabilities", "weft.system.lease", "weft.system.metrics", "weft.system.principal", "weft.system.registry", "weft.task.queues.list", "weft.tasks.diagnostics", "weft.tasks.diagnostics.deadletters.clear", "weft.tasks.get", "weft.updates.result.get", "weft.worker.deployments.drain", "weft.worker.deployments.resume", "weft.workers.diagnostics", "weft.workers.drain", "weft.workers.list", "weft.workers.rejections", "weft.workers.resume", "weft.workflows.active.get", "weft.workflows.activities.pending.list", "weft.workflows.aggregate", "weft.workflows.attributes.get", "weft.workflows.attributes.set", "weft.workflows.bulk.cancel", "weft.workflows.bulk.delete", "weft.workflows.bulk.retryfailed", "weft.workflows.bulk.signal", "weft.workflows.bulk.tags", "weft.workflows.cancel", "weft.workflows.checkpoints.get", "weft.workflows.checkpoints.list", "weft.workflows.events.list", "weft.workflows.finalizer.get", "weft.workflows.fork", "weft.workflows.get", "weft.workflows.list", "weft.workflows.purge", "weft.workflows.query", "weft.workflows.replay", "weft.workflows.result.get", "weft.workflows.resume", "weft.workflows.revisions.activate", "weft.workflows.revisions.get", "weft.workflows.revisions.install", "weft.workflows.revisions.list", "weft.workflows.scheduleprovenance.get", "weft.workflows.signal", "weft.workflows.start", "weft.workflows.startorsignal", "weft.workflows.streams.chunks", "weft.workflows.suspend", "weft.workflows.tags.add", "weft.workflows.tags.remove", "weft.workflows.timeline.get", "weft.workflows.timeout", "weft.workflows.update"];
+export declare const CLIENT_OPERATION_NAMES: readonly ["weft.activities.complete", "weft.activities.fail", "weft.alerts.list", "weft.catalog.diagnostics", "weft.recover.all", "weft.retention.get", "weft.reviews.decision.submit", "weft.reviews.get", "weft.reviews.list", "weft.schedules.cancel", "weft.schedules.create", "weft.schedules.get", "weft.schedules.list", "weft.schedules.pause", "weft.schedules.resume", "weft.schedules.update", "weft.storage.capabilities", "weft.system.lease", "weft.system.metrics", "weft.system.principal", "weft.system.registry", "weft.task.queues.list", "weft.tasks.diagnostics", "weft.tasks.diagnostics.deadletters.clear", "weft.tasks.get", "weft.updates.result.get", "weft.worker.deployments.drain", "weft.worker.deployments.resume", "weft.workers.diagnostics", "weft.workers.drain", "weft.workers.list", "weft.workers.rejections", "weft.workers.resume", "weft.workflows.active.get", "weft.workflows.activities.pending.list", "weft.workflows.aggregate", "weft.workflows.attributes.get", "weft.workflows.attributes.set", "weft.workflows.bulk.cancel", "weft.workflows.bulk.delete", "weft.workflows.bulk.retryfailed", "weft.workflows.bulk.signal", "weft.workflows.bulk.tags", "weft.workflows.cancel", "weft.workflows.checkpoints.get", "weft.workflows.checkpoints.list", "weft.workflows.events.list", "weft.workflows.finalizer.get", "weft.workflows.fork", "weft.workflows.get", "weft.workflows.list", "weft.workflows.purge", "weft.workflows.query", "weft.workflows.replay", "weft.workflows.result.get", "weft.workflows.resume", "weft.workflows.revisions.activate", "weft.workflows.revisions.get", "weft.workflows.revisions.install", "weft.workflows.revisions.list", "weft.workflows.revisions.preload", "weft.workflows.scheduleprovenance.get", "weft.workflows.signal", "weft.workflows.start", "weft.workflows.startorsignal", "weft.workflows.streams.chunks", "weft.workflows.suspend", "weft.workflows.tags.add", "weft.workflows.tags.remove", "weft.workflows.timeline.get", "weft.workflows.timeout", "weft.workflows.update"];
 export type ClientOperationName = (typeof CLIENT_OPERATION_NAMES)[number];
 export declare const CLIENT_REST_OPERATION_BINDINGS: {
     readonly 'weft.tasks.diagnostics.deadletters.clear': {
@@ -155,6 +155,14 @@ export type ClientOperationTypes = {
             };
             readonly removable: boolean;
             readonly revision: string;
+            readonly source?: {
+                readonly kind: 'module';
+                readonly lastFailureCategory?: 'application' | 'timeout' | 'cancellation' | 'resource' | 'system';
+                readonly loadDurationMs?: number;
+                readonly requestedRevision: string;
+                readonly state: 'idle' | 'loading' | 'ready' | 'failed' | 'cancelled';
+                readonly waiterCount: number;
+            };
         };
         readonly faults: never;
     };
@@ -247,6 +255,7 @@ export type ClientOperationTypes = {
             readonly input?: unknown;
             readonly jitter?: unknown;
             readonly overlap?: unknown;
+            readonly revisionPolicy?: unknown;
             readonly type: unknown;
         };
         readonly output: {
@@ -293,6 +302,7 @@ export type ClientOperationTypes = {
             readonly every?: unknown;
             readonly jitter?: unknown;
             readonly overlap?: unknown;
+            readonly revisionPolicy?: unknown;
             readonly scheduleId: string;
         };
         readonly output: null;
@@ -470,6 +480,7 @@ export type ClientOperationTypes = {
             readonly visibilityTimeoutMilliseconds: number;
             readonly workflowExecutionToken?: string;
             readonly workflowId?: string;
+            readonly workflowRevision?: string;
             readonly workflowType: string;
         } | {
             readonly activityName: string;
@@ -496,6 +507,7 @@ export type ClientOperationTypes = {
             readonly visibilityTimeoutMilliseconds: number;
             readonly workflowExecutionToken?: string;
             readonly workflowId?: string;
+            readonly workflowRevision?: string;
             readonly workflowType: string;
         } | {
             readonly activityName: string;
@@ -524,6 +536,7 @@ export type ClientOperationTypes = {
             readonly visibilityTimeoutMilliseconds: number;
             readonly workflowExecutionToken?: string;
             readonly workflowId?: string;
+            readonly workflowRevision?: string;
             readonly workflowType: string;
         } | {
             readonly activityName: string;
@@ -552,6 +565,7 @@ export type ClientOperationTypes = {
             readonly visibilityTimeoutMilliseconds: number;
             readonly workflowExecutionToken?: string;
             readonly workflowId?: string;
+            readonly workflowRevision?: string;
             readonly workflowType: string;
         } | {
             readonly activityName: string;
@@ -577,6 +591,7 @@ export type ClientOperationTypes = {
             readonly visibilityTimeoutMilliseconds: number;
             readonly workflowExecutionToken?: string;
             readonly workflowId?: string;
+            readonly workflowRevision?: string;
             readonly workflowType: string;
         } | {
             readonly activityName: string;
@@ -600,6 +615,7 @@ export type ClientOperationTypes = {
             readonly visibilityTimeoutMilliseconds: number;
             readonly workflowExecutionToken?: string;
             readonly workflowId?: string;
+            readonly workflowRevision?: string;
             readonly workflowType: string;
         } | {
             readonly activityName: string;
@@ -623,6 +639,7 @@ export type ClientOperationTypes = {
             readonly visibilityTimeoutMilliseconds: number;
             readonly workflowExecutionToken?: string;
             readonly workflowId?: string;
+            readonly workflowRevision?: string;
             readonly workflowType: string;
         } | {
             readonly activityName: string;
@@ -649,6 +666,7 @@ export type ClientOperationTypes = {
             readonly visibilityTimeoutMilliseconds: number;
             readonly workflowExecutionToken?: string;
             readonly workflowId?: string;
+            readonly workflowRevision?: string;
             readonly workflowType: string;
         };
         readonly faults: 'NotFound';
@@ -1060,6 +1078,14 @@ export type ClientOperationTypes = {
         readonly output: unknown;
         readonly faults: 'InvalidParams';
     };
+    'weft.workflows.revisions.preload': {
+        readonly input: {
+            readonly name: unknown;
+            readonly revision: unknown;
+        };
+        readonly output: unknown;
+        readonly faults: 'Conflict' | 'InvalidParams' | 'NotFound';
+    };
     'weft.workflows.scheduleprovenance.get': {
         readonly input: {
             readonly workflowId: string;

package/dist/cli/generated/operation-client.generated.js

@@ -62,6 +62,7 @@ export const CATALOG_OPERATION_NAMES = [
   "weft.workflows.revisions.get",
   "weft.workflows.revisions.install",
   "weft.workflows.revisions.list",
+  "weft.workflows.revisions.preload",
   "weft.workflows.scheduleprovenance.get",
   "weft.workflows.signal",
   "weft.workflows.start",
@@ -134,6 +135,7 @@ export const CATALOG_OPERATION_NAMES = [
   "weft.workflows.revisions.get",
   "weft.workflows.revisions.install",
   "weft.workflows.revisions.list",
+  "weft.workflows.revisions.preload",
   "weft.workflows.scheduleprovenance.get",
   "weft.workflows.signal",
   "weft.workflows.start",

package/dist/cli/parse-schedule-arguments.js

@@ -1,6 +1,6 @@
 import { parseArgs } from "node:util";
 import { parsePersistentStorageBackend } from "./storage-backend-arguments.js";
-const SCHEDULE_ACTIONS = new Set(["list", "create", "pause", "resume", "cancel"]), VALID_SCHEDULE_OVERLAP_POLICIES = new Set(["skip", "queue", "cancel-running", "allow"]);
+const SCHEDULE_ACTIONS = new Set(["list", "create", "pause", "resume", "cancel"]), VALID_SCHEDULE_OVERLAP_POLICIES = new Set(["skip", "queue", "cancel-running", "allow"]), VALID_SCHEDULE_REVISION_POLICIES = new Set(["active-at-fire", "pinned"]);
 function parseScheduleCliValues(args) {
   return parseArgs({
     args,
@@ -14,6 +14,7 @@ function parseScheduleCliValues(args) {
       overlap: { type: "string" },
       backfill: { type: "boolean", default: !1 },
       jitter: { type: "string" },
+      "revision-policy": { type: "string" },
       help: { type: "boolean", short: "h", default: !1 },
       json: { type: "boolean", short: "j", default: !1 }
     },
@@ -76,12 +77,23 @@ function requireScheduleAction(positionals) {
     throw Error(`Unknown schedule action "${action}". Expected one of: ${formatScheduleActionList()}`);
   return action;
 }
+function isScheduleRevisionPolicy(value) {
+  return VALID_SCHEDULE_REVISION_POLICIES.has(value);
+}
+function parseScheduleRevisionPolicy(value) {
+  if (value === void 0)
+    return;
+  if (!isScheduleRevisionPolicy(value))
+    throw Error(`Invalid revision policy '${value}'. Must be one of: active-at-fire, pinned`);
+  return value;
+}
 function buildScheduleCreateOptionalFields(values) {
-  const overlap = parseScheduleOverlapPolicy(values.overlap);
+  const overlap = parseScheduleOverlapPolicy(values.overlap), revisionPolicy = parseScheduleRevisionPolicy(values["revision-policy"]);
   return {
     ...values.id !== void 0 ? { id: values.id } : {},
     ...overlap !== void 0 ? { overlap } : {},
-    ...values.jitter !== void 0 ? { jitter: values.jitter } : {}
+    ...values.jitter !== void 0 ? { jitter: values.jitter } : {},
+    ...revisionPolicy !== void 0 ? { revisionPolicy } : {}
   };
 }
 function buildScheduleCreateCommand(values, positionals) {

package/dist/cli/schedule.js

@@ -64,7 +64,8 @@ async function executeScheduleCreate(options, engine, loadRegistrationsFromModul
     ...options.id !== void 0 ? { id: options.id } : {},
     ...options.overlap !== void 0 ? { overlap: options.overlap } : {},
     ...options.backfill ? { backfill: !0 } : {},
-    ...options.jitter !== void 0 ? { jitter: options.jitter } : {}
+    ...options.jitter !== void 0 ? { jitter: options.jitter } : {},
+    ...options.revisionPolicy !== void 0 ? { revisionPolicy: options.revisionPolicy } : {}
   }), schedule = await handle.describe();
   return {
     stdout: formatScheduleCommandOutput(schedule, options.json, `Created schedule ${handle.id}`),

package/dist/cli/types.d.ts

@@ -1,4 +1,4 @@
-import type { ScheduleOverlapPolicy } from '../core/types.ts';
+import type { ScheduleOverlapPolicy, ScheduleRevisionPolicy } from '../core/types.ts';
 /** Supported storage backend identifiers for the `--storage` flag. */
 export type StorageBackend = 'sqlite' | 'lmdb' | 'memory';
 /** Storage backends suitable for commands that must survive process exit. */
@@ -86,6 +86,7 @@ export type CliCommand = {
     overlap?: ScheduleOverlapPolicy;
     backfill: boolean;
     jitter?: string;
+    revisionPolicy?: ScheduleRevisionPolicy;
     help: boolean;
     json: boolean;
 } | {

package/dist/client/http-client-requests.js

@@ -1,7 +1,7 @@
 import { assertScopedBulkWorkflowFilter } from "../core/bulk-workflow-filter.js";
 import { HttpClientError, request } from "./http-request.js";
 import { buildReviewListSearchParams } from "./search-params.js";
-import { scheduleSpecToWireFields } from "./start-body.js";
+import { scheduleSpecToWireFields, setIfDefined } from "./start-body.js";
 export async function listReviewRequests(context, filter) {
   const search = buildReviewListSearchParams(filter).toString(), path = search.length > 0 ? `/reviews?${search}` : "/reviews";
   return (await request(context.baseUrl, path, context.headers)).items;
@@ -187,14 +187,11 @@ export function cancelScheduleRequest(context, id) {
 }
 export function updateScheduleRequest(context, id, newSpec, options) {
   const body = scheduleSpecToWireFields(newSpec);
-  if (options?.description !== void 0)
-    body.description = options.description;
-  if (options?.overlap !== void 0)
-    body.overlap = options.overlap;
-  if (options?.backfill !== void 0)
-    body.backfill = options.backfill;
-  if (options?.jitter !== void 0)
-    body.jitter = options.jitter;
+  setIfDefined(body, "description", options?.description);
+  setIfDefined(body, "overlap", options?.overlap);
+  setIfDefined(body, "backfill", options?.backfill);
+  setIfDefined(body, "jitter", options?.jitter);
+  setIfDefined(body, "revisionPolicy", options?.revisionPolicy);
   return request(context.baseUrl, `/schedules/${encodeURIComponent(id)}`, context.headers, {
     method: "PATCH",
     body: JSON.stringify(body)

package/dist/client/start-body.js

@@ -16,6 +16,7 @@ export function buildScheduleBody(type, input, spec, options) {
   setIfDefined(body, "overlap", options?.overlap);
   setIfDefined(body, "backfill", options?.backfill);
   setIfDefined(body, "jitter", options?.jitter);
+  setIfDefined(body, "revisionPolicy", options?.revisionPolicy);
   return body;
 }
 function applyStartOptionsToBody(body, options) {

package/dist/core/catalog/index.d.ts

@@ -19,7 +19,7 @@
  */
 export { WorkflowCatalogActivationConflictError, WorkflowCatalogActiveEntryMissingError, WorkflowCatalogConflictError, WorkflowRevisionNotInstalledError, } from './errors.ts';
 export { decrementNestedRevisionCount, incrementNestedRevisionCount, readNestedRevisionCount, totalWorkflowRevisionReferences, type WorkflowRevisionReferenceCounts, } from './reference-counts.ts';
-export { removeCatalogEntry, type WorkflowCatalogRemovalOutcome } from './removal.ts';
-export { restoreWorkflowCatalog, type RestoredWorkflowCatalogState } from './storage-io.ts';
+export { finalizeCatalogTombstone, removeCatalogEntry, restoreCatalogEntryFromTombstone, type WorkflowCatalogRemovalOutcome, } from './removal.ts';
+export { decodeCatalogEntryRecord, restoreWorkflowCatalog, type RestoredWorkflowCatalogState, } from './storage-io.ts';
 export type { WorkflowCatalogActivationResult, WorkflowCatalogActivePointer, WorkflowCatalogEntry, WorkflowRevisionRecord, } from './types.ts';
 export { WorkflowCatalog, type ActivateCandidateOptions } from './workflow-catalog.ts';

package/dist/core/catalog/index.js

@@ -10,6 +10,13 @@ export {
   readNestedRevisionCount,
   totalWorkflowRevisionReferences
 } from "./reference-counts.js";
-export { removeCatalogEntry } from "./removal.js";
-export { restoreWorkflowCatalog } from "./storage-io.js";
+export {
+  finalizeCatalogTombstone,
+  removeCatalogEntry,
+  restoreCatalogEntryFromTombstone
+} from "./removal.js";
+export {
+  decodeCatalogEntryRecord,
+  restoreWorkflowCatalog
+} from "./storage-io.js";
 export { WorkflowCatalog } from "./workflow-catalog.js";

package/dist/core/catalog/reference-counts.d.ts

@@ -3,10 +3,17 @@
  * `(name, revision)` removal decision is gated on (WFT-12).
  *
  * Seven fields, all always present so a consumer never has to special-case
- * an "unknown" reference kind. Two are wired to real in-process signals this
- * batch; the remaining five stay structurally present but always `0` until
- * run-level revision pinning lands (WFT-17) gives them something real to
- * count — see each field's own doc for its specific WFT-17 dependency. This
+ * an "unknown" reference kind. Four are wired to real in-process/durable
+ * signals: `registeredDefinitions` and `inFlightStarts` from WFT-12,
+ * `nonTerminalRuns` from WFT-17 (a bounded storage scan of persisted
+ * `WorkflowState.revision` pins — see {@link countNonTerminalRunsForRevision}),
+ * and `pinnedSchedules` from WFT-20 (a bounded storage scan of persisted
+ * `revisionPolicy: 'pinned'` schedules — see
+ * {@link import('../engine/pinned-schedule-revision-count.ts').countPinnedSchedulesForRevision}).
+ * The remaining three stay structurally present but always `0` — each
+ * awaits revision identity in a different, later-owned subsystem (dispatch
+ * ledger, execution realms, and retained recovery records: not yet
+ * scheduled) — see each field's own doc for its specific dependency. This
  * mirrors `workflow-catalog.ts`'s own precedent of describing a forward
  * dependency in prose rather than leaving a `TODO`/`FIXME` marker.
  *
@@ -56,32 +63,40 @@ export type WorkflowRevisionReferenceCounts = Readonly<{
      */
     inFlightStarts: number;
     /**
-     * Non-terminal runs whose `WorkflowState` pins exactly this revision.
-     * Always `0` until run-level revision pinning (WFT-17) gives a run's
-     * persisted state a `revision` field to count against.
+     * Non-terminal (`running`/`pending`/`suspended`) runs whose `WorkflowState`
+     * pins exactly this revision. Wired now (WFT-17), via a bounded
+     * `storage.scan('wf:')` — see
+     * {@link import('../engine/nonterminal-revision-count.ts').countNonTerminalRunsForRevision}.
+     * A legacy run with no persisted `revision` never counts against any
+     * specific revision here.
      */
     nonTerminalRuns: number;
     /**
-     * Schedules pinned to exactly this revision. Always `0` until WFT-17
-     * introduces schedule-level revision pinning.
+     * Non-cancelled schedules with `revisionPolicy: 'pinned'` and
+     * `pinnedRevision` equal to exactly this revision. Wired now (WFT-20), via
+     * a bounded `storage.scan('schedule:')` — see
+     * {@link import('../engine/pinned-schedule-revision-count.ts').countPinnedSchedulesForRevision}.
+     * An `'active-at-fire'` schedule never counts here, regardless of its
+     * `workflowType` — it resolves whatever revision is active at each future
+     * fire, so it holds no standing reference to any one revision.
      */
     pinnedSchedules: number;
     /**
      * Queued dispatches (delayed starts, retries) targeting exactly this
-     * revision. Always `0` until WFT-17 threads revision identity through the
-     * dispatch ledger.
+     * revision. Always `0` until a later batch threads revision identity
+     * through the dispatch ledger.
      */
     pendingDispatches: number;
     /**
      * Active execution realms (remote worker sessions) currently running
-     * exactly this revision. Always `0` until WFT-17 gives a realm's
+     * exactly this revision. Always `0` until a later batch gives a realm's
      * advertised contract a revision this accounting can compare against.
      */
     activeExecutionRealms: number;
     /**
      * Retained recovery records (crash-recovery checkpoints, dead letters)
-     * referencing exactly this revision. Always `0` until WFT-17 threads
-     * revision identity through those retained records.
+     * referencing exactly this revision. Always `0` until a later batch
+     * threads revision identity through those retained records.
      */
     retainedRecoveryRecords: number;
 }>;