@lostgradient/weft 0.24.0 → 0.24.1

package/dist/core/engine/storage-io.d.ts

@@ -1,4 +1,4 @@
-import { type BatchOperation } from '../../storage/interface.ts';
+import { type BatchOperation, type ConditionalBatchCondition } from '../../storage/interface.ts';
 import type { ScheduleState, WorkflowState } from '../types.ts';
 import type { EngineInternals } from './internals.ts';
 import { type WorkflowClaimTransitionFragment } from './workflow-claim-transitions.ts';
@@ -84,11 +84,28 @@ export declare function commitExternalTerminalWorkflowStateOperations(internals:
 export declare function loadScheduleState(internals: EngineInternals, scheduleId: string): Promise<ScheduleState | null>;
 /** Load a schedule state. */
 export declare function requireScheduleState(internals: EngineInternals, scheduleId: string): Promise<ScheduleState>;
-/** Persist schedule state and optionally write the next schedule timer. */
+/**
+ * Persist schedule state and optionally write the next schedule timer.
+ *
+ * `extraConditions` (WFT-20) additionally fences the commit on caller-supplied
+ * preconditions — used by a `revisionPolicy: 'pinned'` create/update to fence
+ * the write on `buildCatalogEntryRevisionCondition(type, pinnedRevision)` so a
+ * concurrent `removeWorkflowRevision()` landing between pin capture and this
+ * commit cannot let a pin to an already-removed revision durably land. When
+ * the commit's `extraConditions` are the ones that lost the CAS,
+ * `onExtraConditionsLost` (required whenever `extraConditions` is non-empty)
+ * supplies the thrown error instead of this function's own generic
+ * lost-precondition error, so the caller sees an actionable, typed failure
+ * (e.g. `WorkflowRevisionUnavailableError`) rather than a bare "lost its
+ * precondition" message. Every existing caller passes neither option and gets
+ * byte-for-byte the pre-WFT-20 commit shape.
+ */
 export declare function writeScheduleState(internals: EngineInternals, state: ScheduleState, options?: {
     includeTimer?: boolean;
     replaceTimerFrom?: ScheduleState;
     additionalOperations?: BatchOperation[];
+    extraConditions?: ConditionalBatchCondition[];
+    onExtraConditionsLost?: () => Error;
 }): Promise<void>;
 /** Load persisted workflow start headers by workflow ID. */
 export declare function loadWorkflowStartHeaders(internals: EngineInternals, workflowId: string): Promise<Map<string, string> | undefined>;

package/dist/core/engine/storage-io.js

@@ -1,5 +1,6 @@
 import {
-  KEYS
+  KEYS,
+  storageValuesEqual
 } from "../../storage/interface.js";
 import { encode } from "../codec.js";
 import { buildTimerBatchOperations } from "../scheduler.js";
@@ -8,7 +9,10 @@ import {
   clearPendingAtomicWorkflowCommitSideEffects,
   takePendingAtomicWorkflowCommitSideEffects
 } from "./checkpoint-side-effects.js";
-import { commitFencedEngineWrite } from "./fenced-write.js";
+import {
+  commitFencedEngineWrite,
+  commitFencedEngineWriteAllowingPreconditionFailure
+} from "./fenced-write.js";
 import { getWorkflowExecutionStartedAt } from "./handles.js";
 import { resolveEffectiveScheduleFireAt } from "./schedule-jitter.js";
 import { createScheduleTimerId, decodeWorkflowStartHeaders } from "./state-utilities.js";
@@ -150,8 +154,23 @@ export async function writeScheduleState(internals, state, options) {
   ], includeTimer = options?.includeTimer ?? state.status === "active";
   operations.push(...buildScheduleTimerReplacementOperations(state, includeTimer, options?.replaceTimerFrom));
   operations.push(...options?.additionalOperations ?? []);
+  const extraConditions = options?.extraConditions ?? [];
+  if (extraConditions.length > 0) {
+    await commitScheduleStateWithExtraConditions(internals, state, operations, extraConditions, options?.onExtraConditionsLost);
+    return;
+  }
   await commitFencedEngineWrite(internals, null, operations, [], () => Error(`Schedule state commit for schedule "${state.id}" lost its precondition.`));
 }
+async function commitScheduleStateWithExtraConditions(internals, state, operations, extraConditions, onExtraConditionsLost) {
+  if (await commitFencedEngineWriteAllowingPreconditionFailure(internals, null, operations, extraConditions))
+    return;
+  for (const condition of extraConditions) {
+    const currentValue = await internals.storage.get(condition.key);
+    if (!storageValuesEqual(currentValue, condition.expectedValue))
+      throw onExtraConditionsLost?.() ?? Error(`Schedule state commit for schedule "${state.id}" lost its precondition.`);
+  }
+  throw Error(`Schedule state commit for schedule "${state.id}" lost its precondition.`);
+}
 export async function loadWorkflowStartHeaders(internals, workflowId) {
   const bytes = await internals.storage.get(KEYS.workflowHeaders(workflowId));
   if (!bytes)

package/dist/core/engine/termination/finalizer-registration.d.ts

@@ -0,0 +1,18 @@
+import type { EngineInternals } from '../internals.ts';
+import type { RunnableFinalizer } from './finalizer-activity.ts';
+/**
+ * Resolve `type`'s `finalizer` against the workflow instance's own EXACT
+ * pinned `revision` (WFT-17/WFT-19), awaiting a full dynamic-source resolve
+ * when it is `registerSource()`-registered but unresolved on this process —
+ * {@link getResolvedDynamicRegistration}'s sync-only lookup cannot close
+ * that gap. Without this, a type never started/resumed/recovered here after
+ * a fresh restart (only torn down) rearms its `wf-teardown:` timer forever,
+ * since nothing else triggers the resolve `lastResolvedRevisionByName`
+ * needs. Returns `undefined` (rearm) when `type` has no registration at
+ * all, when the pinned revision cannot be resolved on this process
+ * ({@link WorkflowRevisionUnavailableError}), or when the resolve itself
+ * fails ({@link DynamicWorkflowSourceUnavailableError}) — a load failure
+ * here doesn't fail the (already terminal) workflow, it just defers to the
+ * next self-heal attempt.
+ */
+export declare function resolveFinalizerRegistration(internals: EngineInternals, type: string, revision: string | undefined): Promise<RunnableFinalizer | undefined>;

package/dist/core/engine/termination/finalizer-registration.js

@@ -0,0 +1,21 @@
+import { DynamicWorkflowSourceUnavailableError } from "../dynamic-source-errors.js";
+import {
+  getResolvedDynamicRegistration,
+  resolveExecutableRegistrationForRevision
+} from "../dynamic-source-execution.js";
+import { WorkflowRevisionUnavailableError } from "../revision-errors.js";
+export async function resolveFinalizerRegistration(internals, type, revision) {
+  const eagerOrAlreadyResolved = getResolvedDynamicRegistration(internals, type, revision)?.finalizer;
+  if (eagerOrAlreadyResolved !== void 0)
+    return eagerOrAlreadyResolved;
+  if (!internals.sources.byName.has(type))
+    return;
+  try {
+    const { entry } = await resolveExecutableRegistrationForRevision(internals.engine, internals, type, revision);
+    return entry.finalizer;
+  } catch (error) {
+    if (error instanceof DynamicWorkflowSourceUnavailableError || error instanceof WorkflowRevisionUnavailableError)
+      return;
+    throw error;
+  }
+}

package/dist/core/engine/termination/finalizer.d.ts

@@ -3,29 +3,26 @@
  * Dispatched by the scheduler when a `wf-teardown:` timer fires, it drives a
  * workflow's definition-level `finalizer` to durable completion after a
  * `cancelled`/`timed-out` terminal — claiming the durable teardown marker, running
- * the finalizer activity (via {@link runFinalizerActivity}), and then clearing,
- * backing off, or dead-lettering based on the outcome. The byte-level claim mechanics
- * (CAS, settle, re-arm, dead-letter, the stale horizon and backoff) live in
- * `./finalizer-claim.ts`; this module is the orchestration that decides which to call.
+ * the finalizer activity (via {@link runFinalizerActivity}), and then clearing, backing
+ * off, or dead-lettering based on the outcome. The byte-level claim mechanics (CAS,
+ * settle, re-arm, dead-letter, stale horizon, backoff) live in `./finalizer-claim.ts`;
+ * this module is the orchestration that decides which to call.
  *
- * Concurrency model — a single durable, TIME-based claim:
- * the durable `teardownOwed` marker carries a `{ status, attempts, token, claimedAt }`
- * claim ({@link TeardownClaim}). A holder fenced-CAS's `owed → running` (stamping
- * `claimedAt`) before running, and settle-CAS's the exact `running` bytes it wrote when
- * clearing or rescheduling — so a concurrent reclaimer can never clobber a fresher
- * claim. Liveness is decided purely by the clock: a `running` claim is reclaimable once
- * `claimedAt` is older than {@link teardownStaleThresholdMs} (the finalizer's per-attempt
- * timeout plus a margin). There is NO in-memory liveness set and NO epoch in the record;
- * crash recovery is an ordinary stale-claim retry driven by the timer that survived the
- * terminal batch. The tradeoff is that a finalizer running past the stale threshold may
- * be re-driven concurrently, which is why workflow finalizers must be idempotent (a
- * contract of the #446 design).
+ * Concurrency model — a single durable, TIME-based claim: the durable `teardownOwed`
+ * marker carries a `{ status, attempts, token, claimedAt }` claim ({@link TeardownClaim}).
+ * A holder fenced-CAS's `owed → running` (stamping `claimedAt`) before running, and
+ * settle-CAS's the exact `running` bytes it wrote when clearing or rescheduling — so a
+ * concurrent reclaimer can never clobber a fresher claim. Liveness is decided purely by
+ * the clock: a `running` claim is reclaimable once `claimedAt` is older than
+ * {@link teardownStaleThresholdMs}. There is NO in-memory liveness set and NO epoch in
+ * the record; crash recovery is an ordinary stale-claim retry driven by the timer that
+ * survived the terminal batch — the tradeoff is a finalizer running past the stale
+ * threshold may be re-driven concurrently, which is why finalizers must be idempotent.
  *
  * Self-heal invariant: every exit that does NOT settle the claim (a lost claim CAS, a
  * presumed-live `running` claim, a shutdown-aborted attempt, or a missing registration)
- * re-arms a future `wf-teardown:` timer before returning, because the scheduler deletes
- * the fired timer once this returns without throwing. A non-settling exit that forgot to
- * re-arm would strand the marker with no timer to re-drive it.
+ * re-arms a future `wf-teardown:` timer before returning — the scheduler deletes the fired
+ * timer on return, so a non-settling exit that forgot to re-arm strands the marker.
  *
  * @module core/engine/termination/finalizer
  */

package/dist/core/engine/termination/finalizer.js

@@ -18,6 +18,7 @@ import {
   teardownStaleThresholdMs,
   teardownTimerOperations
 } from "./finalizer-claim.js";
+import { resolveFinalizerRegistration } from "./finalizer-registration.js";
 export { teardownStaleThresholdMs } from "./finalizer-claim.js";
 const TERMINAL_STATUSES_OWED_TEARDOWN = new Set([
   "cancelled",
@@ -53,10 +54,9 @@ async function resolveTeardownDrive(internals, workflowId, token, callbacks) {
   const state = await callbacks.loadWorkflowState(workflowId);
   if (state === null || !TERMINAL_STATUSES_OWED_TEARDOWN.has(state.status))
     return clearOrRearm(internals, workflowId, token, markerBytes);
-  const registeredFinalizer = internals.registrations.get(state.type)?.finalizer;
-  if (registeredFinalizer === void 0)
+  const finalizer = await resolveFinalizerRegistration(internals, state.type, state.revision);
+  if (finalizer === void 0)
     return { kind: "rearm", token };
-  const finalizer = registeredFinalizer;
   if (!runningClaimIsStale(internals, claim, finalizer))
     return { kind: "rearm", token };
   const finalizerStateBytes = await internals.storage.get(KEYS.finalizerState(workflowId));

package/dist/core/engine/time-operation-callbacks.d.ts

@@ -0,0 +1,32 @@
+/**
+ * {@link TimeOperationCallbacks} — the callback bundle `operations-time.ts`'s
+ * timer-fire handlers (delayed start, sleep, deadline, schedule) take. Split
+ * out of that file, which has no headroom under the repository's 500-line
+ * implementation-file ceiling for this type inline.
+ *
+ * @module core/engine/time-operation-callbacks
+ */
+import type { Checkpoint, Duration, TimerEntry, WorkflowState } from '../types.ts';
+import type { WorkflowVersionTuple } from '../workflow-version-tuple.ts';
+import type { ExecutableRegistration } from './dynamic-source-execution.ts';
+type RegistrationEntry = ExecutableRegistration['entry'];
+export type TimeOperationCallbacks = {
+    completeOperation: (workflowId: string, value: unknown) => void;
+    dispatchEvent: (event: Event) => void;
+    loadWorkflowState: (workflowId: string) => Promise<WorkflowState | null>;
+    failWorkflow: (workflowId: string, error: Error) => Promise<void>;
+    runSerializedWorkflowStateWrite: <Result>(workflowId: string, writeOperation: () => Promise<Result>) => Promise<Result>;
+    beginWorkflowExecution: (workflowId: string, workflowExecutionToken: string | undefined, workflowType: string, revision: string | undefined, input: unknown, checkpoint: Checkpoint, executionDeadline: number | undefined, executionStateOwnerId: string, registration: RegistrationEntry) => void;
+    workflowVersionTupleFromState: (state: WorkflowState) => WorkflowVersionTuple;
+    setWorkflowStartHeaders: (workflowId: string, headers: Map<string, string> | undefined) => void;
+    loadWorkflowStartHeaders: (workflowId: string) => Promise<Map<string, string> | undefined>;
+    parseStartOptionDuration: (value: Duration, fieldName: 'options.executionTimeout' | 'options.startAfter') => number;
+    runDeferredTerminalCleanup: (workflowId: string, timerId: string) => Promise<void>;
+    runWorkflowFinalizer: (workflowId: string, timerId: string) => Promise<void>;
+    handleScheduleTimer: (entry: TimerEntry) => Promise<void>;
+    timeout: (workflowId: string) => Promise<void>;
+    handleCleanupError: (source: string, error: unknown, workflowId: string) => void;
+    /** Resolve `type` against an EXACT pinned `WorkflowState.revision` (WFT-17, `undefined` for a legacy record) — never the catalog's active pointer. Used by a delayed-start fire, matching `resumeWorkflowFromStorage()`. */
+    resolveExecutableRegistrationForRevision: (type: string, revision: string | undefined) => Promise<ExecutableRegistration>;
+};
+export {};

package/dist/core/engine/validation/schedule-cadence.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Decode a persisted schedule record's cadence fields (`cronExpression` XOR
+ * `intervalMs`). Split out of `schedule.ts` purely to stay under this
+ * repository's 500-line-per-file ceiling (the same precedent
+ * `lifecycle/start.ts`/`decode-revision.ts` set for WFT-17/18) — there is no
+ * behavioral reason to import this module directly instead of `schedule.ts`,
+ * which re-exports nothing from here because `decodeScheduleCadence` is
+ * consumed only by `decodeScheduleIdentityFields` in that file.
+ *
+ * @module core/engine/validation/schedule-cadence
+ */
+/** Decode the cadence fields (`cronExpression` XOR `intervalMs`) of a persisted schedule record, or `null` (and warn) on a malformed record. */
+export declare function decodeScheduleCadence(decoded: Record<string, unknown>, scheduleId: string): {
+    cronExpression?: string;
+    intervalMs?: number;
+} | null;

package/dist/core/engine/validation/schedule-cadence.js

@@ -0,0 +1,20 @@
+import { parseCronExpression } from "../../schedule.js";
+import { rejectInvalidScheduleRecord } from "./schedule-warnings.js";
+export function decodeScheduleCadence(decoded, scheduleId) {
+  const { cronExpression, intervalMs } = decoded, hasCron = cronExpression !== void 0, hasInterval = intervalMs !== void 0;
+  if (hasCron === hasInterval)
+    return rejectInvalidScheduleRecord(scheduleId, "with conflicting or missing cadence (expected exactly one of cronExpression or intervalMs)");
+  if (hasInterval) {
+    if (typeof intervalMs !== "number" || !Number.isSafeInteger(intervalMs) || intervalMs <= 0)
+      return rejectInvalidScheduleRecord(scheduleId, "with invalid intervalMs");
+    return { intervalMs };
+  }
+  if (typeof cronExpression !== "string")
+    return rejectInvalidScheduleRecord(scheduleId, "with invalid cronExpression");
+  try {
+    parseCronExpression(cronExpression);
+  } catch {
+    return rejectInvalidScheduleRecord(scheduleId, "with invalid cronExpression");
+  }
+  return { cronExpression };
+}

package/dist/core/engine/validation/schedule-options.d.ts

@@ -1,15 +1,18 @@
-import type { ScheduleOptions, ScheduleOverlapPolicy, ScheduleUpdateOptions } from '../../types.ts';
+import type { ScheduleOptions, ScheduleOverlapPolicy, ScheduleRevisionPolicy, ScheduleUpdateOptions } from '../../types.ts';
 export declare const SCHEDULE_OVERLAP_POLICIES: Set<ScheduleOverlapPolicy>;
+export declare const SCHEDULE_REVISION_POLICIES: Set<ScheduleRevisionPolicy>;
 type NormalizedScheduleOptions = Required<Pick<ScheduleOptions, 'overlap' | 'backfill'>> & {
     id?: string;
     description?: string;
     jitterMs?: number;
+    revisionPolicy?: ScheduleRevisionPolicy;
 };
 type NormalizedScheduleUpdateOptions = {
     description?: string;
     overlap?: ScheduleOverlapPolicy;
     backfill?: boolean;
     jitterMs?: number;
+    revisionPolicy?: ScheduleRevisionPolicy;
 };
 export declare function normalizeScheduleOptions(options: ScheduleOptions | undefined): NormalizedScheduleOptions;
 export declare function normalizeScheduleUpdateOptions(options: ScheduleUpdateOptions | undefined): NormalizedScheduleUpdateOptions;

package/dist/core/engine/validation/schedule-options.js

@@ -5,6 +5,9 @@ export const SCHEDULE_OVERLAP_POLICIES = new Set([
   "queue",
   "cancel-running",
   "allow"
+]), SCHEDULE_REVISION_POLICIES = new Set([
+  "active-at-fire",
+  "pinned"
 ]);
 export function normalizeScheduleOptions(options) {
   if (options === void 0)
@@ -20,6 +23,9 @@ export function normalizeScheduleOptions(options) {
     },
     ...options.jitter !== void 0 && {
       jitterMs: normalizeScheduleJitter(options.jitter, "options.jitter")
+    },
+    ...options.revisionPolicy !== void 0 && {
+      revisionPolicy: normalizeScheduleRevisionPolicy(options.revisionPolicy, "options.revisionPolicy")
     }
   };
 }
@@ -38,9 +44,17 @@ export function normalizeScheduleUpdateOptions(options) {
     },
     ...options.jitter !== void 0 && {
       jitterMs: normalizeScheduleJitter(options.jitter, "options.jitter")
+    },
+    ...options.revisionPolicy !== void 0 && {
+      revisionPolicy: normalizeScheduleRevisionPolicy(options.revisionPolicy, "options.revisionPolicy")
     }
   };
 }
+function normalizeScheduleRevisionPolicy(value, fieldName) {
+  if (!SCHEDULE_REVISION_POLICIES.has(value))
+    throw Error(`${fieldName} must be one of ${[...SCHEDULE_REVISION_POLICIES].join(", ")}`);
+  return value;
+}
 function normalizeScheduleDescription(description) {
   if (typeof description !== "string")
     throw Error("options.description must be a string when provided");

package/dist/core/engine/validation/schedule-revision.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Decode a persisted schedule record's revision-policy fields
+ * (`revisionPolicy` / `pinnedRevision`, WFT-20). Split out of `schedule.ts`
+ * purely to stay under this repository's 500-line-per-file ceiling — see
+ * that file's own precedent (`lifecycle/start.ts`/`decode-revision.ts` for
+ * WFT-17/18) — there is no behavioral reason to import this module directly
+ * instead of `schedule.ts`, which composes it into `decodeScheduleState`.
+ *
+ * @module core/engine/validation/schedule-revision
+ */
+import type { ScheduleState } from '../../types.ts';
+type ScheduleRevisionFields = Pick<ScheduleState, 'revisionPolicy' | 'pinnedRevision'>;
+/**
+ * Decode `revisionPolicy`/`pinnedRevision` from a persisted schedule record.
+ * A record with NO `revisionPolicy` field predates WFT-20 and decodes as
+ * `'active-at-fire'` — the same "absent means legacy, not corrupt" treatment
+ * `WorkflowState.revision` got (WFT-17/18) — never rejected as malformed. An
+ * explicit but unrecognized `revisionPolicy` string, or a `pinnedRevision`
+ * present while `revisionPolicy !== 'pinned'` (or absent while it IS
+ * `'pinned'`), both reject the whole record via
+ * {@link rejectInvalidScheduleRecord} rather than silently coercing.
+ */
+export declare function decodeScheduleRevisionPolicyFields(decoded: Record<string, unknown>, scheduleId: string): ScheduleRevisionFields | null;
+export {};

package/dist/core/engine/validation/schedule-revision.js

@@ -0,0 +1,21 @@
+import { SCHEDULE_REVISION_POLICIES } from "./schedule-options.js";
+import { rejectInvalidScheduleRecord } from "./schedule-warnings.js";
+export function decodeScheduleRevisionPolicyFields(decoded, scheduleId) {
+  const rawRevisionPolicy = decoded.revisionPolicy;
+  if (rawRevisionPolicy === void 0) {
+    if (decoded.pinnedRevision !== void 0)
+      return rejectInvalidScheduleRecord(scheduleId, "with a pinnedRevision but no revisionPolicy");
+    return { revisionPolicy: "active-at-fire" };
+  }
+  if (!SCHEDULE_REVISION_POLICIES.has(rawRevisionPolicy))
+    return rejectInvalidScheduleRecord(scheduleId, "with invalid revisionPolicy");
+  const revisionPolicy = rawRevisionPolicy, pinnedRevision = decoded.pinnedRevision, hasPinnedRevision = pinnedRevision !== void 0;
+  if (revisionPolicy === "pinned") {
+    if (!hasPinnedRevision || typeof pinnedRevision !== "string" || pinnedRevision.length === 0)
+      return rejectInvalidScheduleRecord(scheduleId, 'with revisionPolicy "pinned" but a missing or invalid pinnedRevision');
+    return { revisionPolicy, pinnedRevision };
+  }
+  if (hasPinnedRevision)
+    return rejectInvalidScheduleRecord(scheduleId, 'with a pinnedRevision but revisionPolicy is not "pinned"');
+  return { revisionPolicy };
+}

package/dist/core/engine/validation/schedule-warnings.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The shared "ignore this malformed persisted schedule record" warning
+ * helper, split into its own leaf module so both `schedule.ts` and its
+ * decode helpers (`schedule-cadence.ts`, `schedule-revision.ts`) can import
+ * it without an import cycle — `schedule.ts` re-exports it so every existing
+ * caller keeps importing it from there.
+ *
+ * @module core/engine/validation/schedule-warnings
+ */
+/** Warn and return `null` for a persisted schedule record that failed decode validation. */
+export declare function rejectInvalidScheduleRecord(scheduleId: string | undefined, message: string): null;

package/dist/core/engine/validation/schedule-warnings.js

@@ -0,0 +1,5 @@
+export function rejectInvalidScheduleRecord(scheduleId, message) {
+  const prefix = scheduleId === void 0 ? "[weft] Ignoring malformed schedule record" : `[weft] Ignoring malformed schedule "${scheduleId}"`;
+  console.warn(`${prefix} ${message}.`);
+  return null;
+}

package/dist/core/engine/validation/schedule.d.ts

@@ -1,9 +1,11 @@
-import type { ScheduleFilter, ScheduleOverlapPolicy, ScheduleSpec, ScheduleState, ScheduleStatus } from '../../types.ts';
-export { normalizeScheduleOptions, normalizeScheduleUpdateOptions, SCHEDULE_OVERLAP_POLICIES, } from './schedule-options.ts';
+import type { ScheduleFilter, ScheduleOverlapPolicy, ScheduleRevisionPolicy, ScheduleSpec, ScheduleState, ScheduleStatus } from '../../types.ts';
+export { normalizeScheduleOptions, normalizeScheduleUpdateOptions, SCHEDULE_OVERLAP_POLICIES, SCHEDULE_REVISION_POLICIES, } from './schedule-options.ts';
+export { rejectInvalidScheduleRecord } from './schedule-warnings.ts';
 export declare const SCHEDULE_STATUSES: Set<ScheduleStatus>;
 export declare function isValidScheduleTimestamp(value: unknown): value is number;
 export declare function isValidScheduleStatus(value: unknown): value is ScheduleStatus;
 export declare function isValidScheduleOverlapPolicy(value: unknown): value is ScheduleOverlapPolicy;
+export declare function isValidScheduleRevisionPolicy(value: unknown): value is ScheduleRevisionPolicy;
 export declare function isValidScheduleIdentifier(value: unknown): value is string;
 export declare function coerceScheduleId(scheduleId: string, fieldName: string): string;
 /**
@@ -24,7 +26,6 @@ export type NormalizedScheduleSpec = {
  */
 export declare function normalizeScheduleSpec(spec: string | ScheduleSpec): NormalizedScheduleSpec;
 export declare function normalizeScheduleFilter(filter: ScheduleFilter | undefined): ScheduleFilter | undefined;
-export declare function rejectInvalidScheduleRecord(scheduleId: string | undefined, message: string): null;
 export declare function decodeScheduleIdentityFields(decoded: Record<string, unknown>): (Pick<ScheduleState, 'id' | 'workflowType' | 'status' | 'overlap'> & {
     cronExpression?: string;
     intervalMs?: number;

package/dist/core/engine/validation/schedule.js

@@ -3,12 +3,17 @@ import { isRecord } from "../../debug-output.js";
 import { parseCronExpression } from "../../schedule.js";
 import { parseDuration } from "../../scheduler.js";
 import { coerceStartWorkflowId } from "../../start-workflow-validation.js";
-import { SCHEDULE_OVERLAP_POLICIES } from "./schedule-options.js";
+import { decodeScheduleCadence } from "./schedule-cadence.js";
+import { SCHEDULE_OVERLAP_POLICIES, SCHEDULE_REVISION_POLICIES } from "./schedule-options.js";
+import { decodeScheduleRevisionPolicyFields } from "./schedule-revision.js";
+import { rejectInvalidScheduleRecord } from "./schedule-warnings.js";
 export {
   normalizeScheduleOptions,
   normalizeScheduleUpdateOptions,
-  SCHEDULE_OVERLAP_POLICIES
+  SCHEDULE_OVERLAP_POLICIES,
+  SCHEDULE_REVISION_POLICIES
 } from "./schedule-options.js";
+export { rejectInvalidScheduleRecord } from "./schedule-warnings.js";
 export const SCHEDULE_STATUSES = new Set(["active", "paused", "cancelled"]);
 export function isValidScheduleTimestamp(value) {
   return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
@@ -19,6 +24,9 @@ export function isValidScheduleStatus(value) {
 export function isValidScheduleOverlapPolicy(value) {
   return typeof value === "string" && SCHEDULE_OVERLAP_POLICIES.has(value);
 }
+export function isValidScheduleRevisionPolicy(value) {
+  return typeof value === "string" && SCHEDULE_REVISION_POLICIES.has(value);
+}
 export function isValidScheduleIdentifier(value) {
   if (typeof value !== "string")
     return !1;
@@ -94,29 +102,6 @@ export function normalizeScheduleFilter(filter) {
   validateScheduleFilterBound(filter.offset, "offset");
   return filter;
 }
-export function rejectInvalidScheduleRecord(scheduleId, message) {
-  const prefix = scheduleId === void 0 ? "[weft] Ignoring malformed schedule record" : `[weft] Ignoring malformed schedule "${scheduleId}"`;
-  console.warn(`${prefix} ${message}.`);
-  return null;
-}
-function decodeScheduleCadence(decoded, scheduleId) {
-  const { cronExpression, intervalMs } = decoded, hasCron = cronExpression !== void 0, hasInterval = intervalMs !== void 0;
-  if (hasCron === hasInterval)
-    return rejectInvalidScheduleRecord(scheduleId, "with conflicting or missing cadence (expected exactly one of cronExpression or intervalMs)");
-  if (hasInterval) {
-    if (typeof intervalMs !== "number" || !Number.isSafeInteger(intervalMs) || intervalMs <= 0)
-      return rejectInvalidScheduleRecord(scheduleId, "with invalid intervalMs");
-    return { intervalMs };
-  }
-  if (typeof cronExpression !== "string")
-    return rejectInvalidScheduleRecord(scheduleId, "with invalid cronExpression");
-  try {
-    parseCronExpression(cronExpression);
-  } catch {
-    return rejectInvalidScheduleRecord(scheduleId, "with invalid cronExpression");
-  }
-  return { cronExpression };
-}
 export function decodeScheduleIdentityFields(decoded) {
   const id = decoded.id;
   if (!isValidScheduleIdentifier(id))
@@ -307,9 +292,13 @@ export function decodeScheduleState(bytes) {
   const runtime = decodeScheduleRuntimeFields(decoded, identity.id);
   if (!runtime)
     return null;
+  const revisionFields = decodeScheduleRevisionPolicyFields(decoded, identity.id);
+  if (!revisionFields)
+    return null;
   return {
     ...identity,
     input: decoded.input,
-    ...runtime
+    ...runtime,
+    ...revisionFields
   };
 }

package/dist/core/engine/validation.js

@@ -4,6 +4,7 @@ import { normalizeFailureCategory } from "../failure-categories.js";
 import { coerceStartWorkflowId, parseStartWorkflowDuration } from "../start-workflow-validation.js";
 import { DEFAULT_WORKFLOW_VERSION } from "../versioning.js";
 import { isWorkflowTagArray } from "../workflow-tags.js";
+import { sanitizeDecodedRevision } from "./decode-revision.js";
 import {
   MAX_TIMELINE_COORDINATOR_DETAILS,
   MAX_TIMELINE_DETAIL_STRING_LENGTH
@@ -30,6 +31,7 @@ const WORKFLOW_STATE_FIELD_NAMES = new Set(defineCompleteWorkflowStateFieldNames
   "failureCategory",
   "terminationReason",
   "versionTuple",
+  "revision",
   "workflowExecutionToken",
   "executionStateOwnerId",
   "parentWorkflowId",
@@ -140,6 +142,7 @@ export function decodeWorkflowState(bytes) {
     }
   sanitizeDecodedParentLineage(state);
   sanitizeDecodedRestartLineage(state);
+  sanitizeDecodedRevision(state);
   return decodedRecord === void 0 ? state : stripUnknownWorkflowStateFields(state, decodedRecord);
 }
 function sanitizeDecodedParentLineage(state) {

package/dist/core/engine/workflow-claim-reclaim-target.d.ts

@@ -104,4 +104,4 @@ export declare function createWorkflowClaimReclaimTarget(registry: WorkflowClaim
  * every existing caller/test that does not care about mixed workflow-type
  * fleets keeps working unchanged.
  */
-isTypeRegistered?: (workflowType: string) => boolean): WorkflowClaimReclaimTargetHandle;
+isTypeRegistered?: (workflowType: string, revision: string | undefined) => boolean): WorkflowClaimReclaimTargetHandle;

package/dist/core/engine/workflow-claim-reclaim-target.js

@@ -17,7 +17,21 @@ async function isWorkflowTypeRegistered(storage, workflowId, isTypeRegistered) {
   if (bytes === null)
     return !1;
   try {
-    return isTypeRegistered(decodeWorkflowState(bytes).type);
+    const state = decodeWorkflowState(bytes);
+    return isTypeRegistered(state.type, state.revision);
+  } catch {
+    return !1;
+  }
+}
+async function isWorkflowStillRunningAndEligible(storage, workflowId, isTypeRegistered) {
+  const bytes = await storage.get(KEYS.workflow(workflowId));
+  if (bytes === null)
+    return !1;
+  try {
+    const state = decodeWorkflowState(bytes);
+    if (state.status !== "running")
+      return !1;
+    return isTypeRegistered === void 0 || isTypeRegistered(state.type, state.revision);
   } catch {
     return !1;
   }
@@ -43,7 +57,7 @@ export function createWorkflowClaimReclaimTarget(registry, storage, metrics, onR
     await registry.release(workflowId);
   }
   async function confirmStillRunningOrReleaseFreshClaim(workflowId, acquiredEpoch) {
-    if (await isWorkflowStillRunning(storage, workflowId))
+    if (await isWorkflowStillRunningAndEligible(storage, workflowId, isTypeRegistered))
       return !0;
     if (registry.currentEpoch(workflowId) === acquiredEpoch)
       await registry.release(workflowId);

package/dist/core/engine/workflow-retention-deadline.d.ts

@@ -0,0 +1,16 @@
+import type { WorkflowState } from '../types.ts';
+import type { EngineInternals } from './internals.ts';
+/**
+ * The timestamp at which `state` becomes eligible for retention-driven
+ * purge, or `null` when it is non-terminal, has no applicable retention
+ * window, or (WFT-19 review round 2) its own pinned revision's retention
+ * policy cannot be resolved on this process right now — an unresolvable pin
+ * is NOT purge-eligible under the engine default; it is re-examined on a
+ * later sweep once the pin becomes resolvable, rather than risking an
+ * irreversible early purge against a shorter policy than the run's own.
+ * Falls back to the resolved dynamic definition's own retention policy for a
+ * `registerSource()`-registered type (see `resolveRetentionPolicyForState()`),
+ * then the engine-wide default for any other type — mirroring `retention.ts`'s
+ * `resolveWorkflowTypeRetention`.
+ */
+export declare function getWorkflowRetentionDeadline(internals: EngineInternals, state: WorkflowState): Promise<number | null>;

package/dist/core/engine/workflow-retention-deadline.js

@@ -0,0 +1,33 @@
+import { DynamicWorkflowSourceUnavailableError } from "./dynamic-source-errors.js";
+import {
+  getResolvedDynamicRegistration,
+  resolveExecutableRegistrationForRevision
+} from "./dynamic-source-execution.js";
+import { WorkflowRevisionUnavailableError } from "./revision-errors.js";
+import { isTerminalWorkflowStatus, resolveRetentionForStatus } from "./validation.js";
+async function resolveRetentionPolicyForState(internals, state) {
+  const eagerOrAlreadyResolved = getResolvedDynamicRegistration(internals, state.type, state.revision)?.retention;
+  if (eagerOrAlreadyResolved !== void 0)
+    return { kind: "resolved", policy: eagerOrAlreadyResolved };
+  if (!internals.sources.byName.has(state.type))
+    return { kind: "resolved", policy: void 0 };
+  try {
+    const { entry } = await resolveExecutableRegistrationForRevision(internals.engine, internals, state.type, state.revision);
+    return { kind: "resolved", policy: entry.retention };
+  } catch (error) {
+    if (error instanceof DynamicWorkflowSourceUnavailableError || error instanceof WorkflowRevisionUnavailableError)
+      return { kind: "unresolvable" };
+    throw error;
+  }
+}
+export async function getWorkflowRetentionDeadline(internals, state) {
+  if (!isTerminalWorkflowStatus(state.status))
+    return null;
+  const resolution = await resolveRetentionPolicyForState(internals, state);
+  if (resolution.kind === "unresolvable")
+    return null;
+  const policy = resolution.policy ?? internals.options.retention, retentionMs = resolveRetentionForStatus(policy, state.status);
+  if (retentionMs === void 0)
+    return null;
+  return state.updatedAt + retentionMs;
+}

package/dist/core/events/event-map.d.ts

@@ -7,6 +7,7 @@ import type { SignalDeliveredEvent, SignalReceivedEvent } from './signal-events.
 import type { AlertFiredEvent, AlertResolvedEvent, CheckpointSizeWarningEvent, CleanupWarningEvent, ConstraintViolatedEvent, DevelopmentWarningEvent, StorageSizeReportedEvent, WorkerConnectedEvent, WorkerDisconnectedEvent } from './system-events.ts';
 import type { UpdateCompletedEvent, UpdateReceivedEvent } from './update-events.ts';
 import type { WorkflowCancelledEvent, WorkflowCompletedEvent, WorkflowDefinitionRegisteredEvent, WorkflowFailedEvent, WorkflowRecoverySkippedEvent, WorkflowResumedEvent, WorkflowStartedEvent, WorkflowSuspendedEvent, WorkflowTeardownEvent, WorkflowTimedOutEvent } from './workflow-events.ts';
+import type { WorkflowSourceLoadCancelledEvent, WorkflowSourceLoadFailedEvent, WorkflowSourceLoadReadyEvent, WorkflowSourceLoadStartedEvent } from './workflow-source-events.ts';
 /**
  * Record mapping each event-name string the {@link Engine} dispatches to its
  * corresponding typed `Event` subclass.
@@ -63,6 +64,10 @@ export type WeftEventMap = {
     'catalog:activation-rejected': WorkflowRevisionActivationRejectedEvent;
     'catalog:revision-draining': WorkflowRevisionDrainingEvent;
     'catalog:revision-removed': WorkflowRevisionRemovedEvent;
+    'workflow-source:load-started': WorkflowSourceLoadStartedEvent;
+    'workflow-source:load-ready': WorkflowSourceLoadReadyEvent;
+    'workflow-source:load-failed': WorkflowSourceLoadFailedEvent;
+    'workflow-source:load-cancelled': WorkflowSourceLoadCancelledEvent;
 };
 /**
  * Typed version of the `EventTarget` interface that constrains

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

@@ -7,3 +7,4 @@ export * from './signal-events.ts';
 export * from './system-events.ts';
 export * from './update-events.ts';
 export * from './workflow-events.ts';
+export * from './workflow-source-events.ts';