@lostgradient/weft 0.2.0

package/dist/core/engine/updates.d.ts

@@ -0,0 +1,56 @@
+import type { ContextOperationRequest } from '../context.ts';
+import type { CoordinatedUpdateResult } from '../types.ts';
+import { type UpdateRequest, type UpdateResponse } from '../updates.ts';
+import type { EngineInternals } from './internals.ts';
+export type UpdateCallbacks = {
+    dispatchEvent: (event: Event) => boolean;
+    broadcast: (message: {
+        type: 'update:completed';
+        workflowId: string;
+        updateId: string;
+    }) => void;
+    completeOperation: (workflowId: string, value: unknown) => void;
+    guardTerminalWorkflow: (workflowId: string) => Promise<void>;
+    guardTerminalWorkflowAfterCoordinatedRequest: (workflowId: string, updateId: string) => Promise<void>;
+    persistCoordinatedUpdateResponse: (workflowId: string, updateName: string, updateId: string, idempotencyKey: string | undefined, value: unknown) => Promise<void>;
+    deliverCoordinatedUpdateToWaiterIfAvailable: (workflowId: string, updateRequest: UpdateRequest, dispatchReceivedEvent?: boolean) => Promise<boolean>;
+    dispatchPendingUpdateReceived: (workflowId: string, updateName: string, updateRequest: UpdateRequest) => void;
+    createCoordinatedUpdateResponder: (workflowId: string, updateName: string, updateRequest: UpdateRequest) => (value: unknown) => void;
+    findPendingUpdateByName: (workflowId: string, name: string) => Promise<UpdateRequest | undefined>;
+    schedulePendingInlineUpdateDrain: (workflowId: string) => void;
+};
+export declare function update(internals: EngineInternals, workflowId: string, name: string, payload: unknown, options: {
+    timeout?: number;
+} | undefined, callbacks: UpdateCallbacks): Promise<unknown>;
+/** Retrieve the result of a coordinated update by its ID. */
+export declare function getUpdateResult(internals: EngineInternals, updateId: string): Promise<UpdateResponse | null>;
+/**
+ * Submit a coordinated update request. Handles idempotency checking,
+ * creates the request, and waits for a response within the timeout.
+ */
+export declare function submitCoordinatedUpdate(internals: EngineInternals, workflowId: string, name: string, payload: unknown, options: {
+    timeout?: number;
+    idempotencyKey?: string;
+} | undefined, callbacks: UpdateCallbacks): Promise<CoordinatedUpdateResult>;
+export declare function processWaitUpdateOperation(internals: EngineInternals, workflowId: string, operation: Extract<ContextOperationRequest, {
+    type: 'wait-update';
+}>, callbacks: UpdateCallbacks): Promise<void>;
+export declare function dispatchPendingUpdateReceived(_internals: EngineInternals, workflowId: string, updateName: string, updateRequest: UpdateRequest, callbacks: Pick<UpdateCallbacks, 'dispatchEvent'>): void;
+export declare function createCoordinatedUpdateResponder(_internals: EngineInternals, workflowId: string, updateName: string, updateRequest: UpdateRequest, callbacks: Pick<UpdateCallbacks, 'persistCoordinatedUpdateResponse'>): (value: unknown) => void;
+export declare function deliverCoordinatedUpdateToWaiterIfAvailable(internals: EngineInternals, workflowId: string, updateRequest: UpdateRequest, dispatchReceivedEvent: boolean | undefined, callbacks: UpdateCallbacks): Promise<boolean>;
+export declare function findPendingUpdateByName(internals: EngineInternals, workflowId: string, name: string): Promise<UpdateRequest | undefined>;
+/**
+ * Invoke an update handler, checking that it does not return a generator.
+ * Centralises the runtime generator guard for both the inline-handler path
+ * in `update()` and the pending-drain path on resume.
+ */
+export declare function invokeUpdateHandler(_internals: EngineInternals, name: string, handler: (payload: unknown) => unknown, payload: unknown): Promise<unknown>;
+/**
+ * Extract issues from a Standard Schema v1 failure result, or null if absent.
+ * No string-`message` entries yields `[]`; callers reject only on a non-empty
+ * array, so `null` and `[]` both mean acceptance. Preserves `path` (RFC 6901).
+ */
+export declare function extractStandardSchemaIssues(result: unknown): Array<{
+    message: string;
+    path?: string;
+}> | null;

package/dist/core/engine/updates.js

@@ -0,0 +1,230 @@
+import { UpdateCompletedEvent, UpdateReceivedEvent } from "../events.js";
+import { isGeneratorResult } from "../step-context.js";
+import {
+  UpdateTimeoutError,
+  UpdateValidationError
+} from "../updates.js";
+import { trackWaiterKey, untrackWaiterKey } from "./signals.js";
+export async function update(internals, workflowId, name, payload, options, callbacks) {
+  const timeout = options?.timeout ?? 30000;
+  await runUpdateValidator(internals, workflowId, name, payload);
+  await callbacks.guardTerminalWorkflow(workflowId);
+  const inlineResult = await tryInlineUpdateHandler(internals, workflowId, name, payload, callbacks);
+  if (inlineResult.handled)
+    return inlineResult.value;
+  const waitingResult = await tryWaitingUpdateHandler(internals, workflowId, name, payload, timeout, callbacks);
+  if (waitingResult.handled)
+    return waitingResult.value;
+  return await runCoordinatedUpdate(internals, workflowId, name, payload, timeout, callbacks);
+}
+async function tryInlineUpdateHandler(internals, workflowId, name, payload, callbacks) {
+  const handler = internals.inlineStrategy?.getContext(workflowId)?.updateHandlers.get(name);
+  if (!handler)
+    return { handled: !1 };
+  const updateId = crypto.randomUUID();
+  callbacks.dispatchEvent(new UpdateReceivedEvent(updateId, workflowId, name, payload));
+  try {
+    const result = await invokeUpdateHandler(internals, name, handler, payload);
+    callbacks.dispatchEvent(new UpdateCompletedEvent(updateId, workflowId, name, result));
+    callbacks.broadcast({ type: "update:completed", workflowId, updateId });
+    return { handled: !0, value: result };
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    callbacks.dispatchEvent(new UpdateCompletedEvent(updateId, workflowId, name, void 0, errorMessage));
+    callbacks.broadcast({ type: "update:completed", workflowId, updateId });
+    throw error;
+  }
+}
+async function tryWaitingUpdateHandler(internals, workflowId, name, payload, timeout, callbacks) {
+  const waiterKey = `${workflowId}:${name}`, updateWaiter = internals.updateWaiters.get(waiterKey);
+  if (!updateWaiter)
+    return { handled: !1 };
+  const existingPendingUpdate = await callbacks.findPendingUpdateByName(workflowId, name);
+  if (internals.updateWaiters.get(waiterKey) !== updateWaiter || existingPendingUpdate)
+    return { handled: !1 };
+  internals.updateWaiters.delete(waiterKey);
+  untrackWaiterKey(internals.updateWaitersByWorkflow, workflowId, waiterKey);
+  const updateId = crypto.randomUUID();
+  callbacks.dispatchEvent(new UpdateReceivedEvent(updateId, workflowId, name, payload));
+  const result = await waitForUpdateResponse(updateId, payload, timeout, updateWaiter);
+  callbacks.dispatchEvent(new UpdateCompletedEvent(updateId, workflowId, name, result));
+  callbacks.broadcast({ type: "update:completed", workflowId, updateId });
+  return { handled: !0, value: result };
+}
+async function waitForUpdateResponse(updateId, payload, timeout, updateWaiter) {
+  const { promise: respondPromise, resolve: resolveRespond } = Promise.withResolvers();
+  let responded = !1;
+  updateWaiter({ payload, respond: (value) => {
+    if (responded)
+      return;
+    responded = !0;
+    resolveRespond(value);
+  } });
+  let timeoutId;
+  try {
+    return await Promise.race([
+      respondPromise,
+      new Promise((_resolve, reject) => {
+        timeoutId = setTimeout(() => reject(new UpdateTimeoutError(updateId, timeout)), timeout);
+      })
+    ]);
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+async function runCoordinatedUpdate(internals, workflowId, name, payload, timeout, callbacks) {
+  const updateId = await internals.updateCoordinator.createRequest(workflowId, name, payload);
+  callbacks.schedulePendingInlineUpdateDrain(workflowId);
+  await callbacks.guardTerminalWorkflowAfterCoordinatedRequest(workflowId, updateId);
+  callbacks.dispatchEvent(new UpdateReceivedEvent(updateId, workflowId, name, payload));
+  await callbacks.deliverCoordinatedUpdateToWaiterIfAvailable(workflowId, {
+    updateId,
+    workflowId,
+    name,
+    payload,
+    createdAt: Date.now()
+  });
+  const response = await internals.updateCoordinator.waitForResponse(updateId, timeout);
+  if (response.error)
+    throw Error(response.error);
+  return response.result;
+}
+export async function getUpdateResult(internals, updateId) {
+  return internals.updateCoordinator.getResponse(updateId);
+}
+export async function submitCoordinatedUpdate(internals, workflowId, name, payload, options, callbacks) {
+  const timeout = options?.timeout ?? 30000, idempotencyKey = options?.idempotencyKey;
+  if (idempotencyKey !== void 0) {
+    const existing = await internals.updateCoordinator.checkIdempotency(workflowId, idempotencyKey);
+    if (existing !== null)
+      return { updateId: existing.updateId, result: existing.result };
+  }
+  await runUpdateValidator(internals, workflowId, name, payload);
+  await callbacks.guardTerminalWorkflow(workflowId);
+  const requestOptions = { timeout };
+  if (idempotencyKey !== void 0)
+    requestOptions.idempotencyKey = idempotencyKey;
+  const updateId = await internals.updateCoordinator.createRequest(workflowId, name, payload, requestOptions);
+  callbacks.schedulePendingInlineUpdateDrain(workflowId);
+  await callbacks.guardTerminalWorkflowAfterCoordinatedRequest(workflowId, updateId);
+  await callbacks.deliverCoordinatedUpdateToWaiterIfAvailable(workflowId, {
+    updateId,
+    workflowId,
+    name,
+    payload,
+    createdAt: Date.now(),
+    idempotencyKey
+  }, !0);
+  const response = await internals.updateCoordinator.waitForResponse(updateId, timeout), result = {
+    updateId: response.updateId,
+    result: response.result
+  };
+  if (response.error !== void 0)
+    result.error = response.error;
+  return result;
+}
+export async function processWaitUpdateOperation(internals, workflowId, operation, callbacks) {
+  const waiterKey = `${workflowId}:${operation.updateName}`, matchingUpdate = await callbacks.findPendingUpdateByName(workflowId, operation.updateName);
+  if (matchingUpdate) {
+    await internals.updateCoordinator.deleteRequest(workflowId, matchingUpdate.updateId);
+    callbacks.dispatchPendingUpdateReceived(workflowId, operation.updateName, matchingUpdate);
+    callbacks.completeOperation(workflowId, {
+      payload: matchingUpdate.payload,
+      respond: callbacks.createCoordinatedUpdateResponder(workflowId, operation.updateName, matchingUpdate)
+    });
+    return;
+  }
+  const { promise, resolve } = Promise.withResolvers();
+  internals.updateWaiters.set(waiterKey, resolve);
+  trackWaiterKey(internals.updateWaitersByWorkflow, workflowId, waiterKey);
+  const pendingUpdateAfterRegistration = await callbacks.findPendingUpdateByName(workflowId, operation.updateName);
+  if (pendingUpdateAfterRegistration) {
+    if (internals.updateWaiters.get(waiterKey) === resolve) {
+      internals.updateWaiters.delete(waiterKey);
+      untrackWaiterKey(internals.updateWaitersByWorkflow, workflowId, waiterKey);
+    }
+    await internals.updateCoordinator.deleteRequest(workflowId, pendingUpdateAfterRegistration.updateId);
+    callbacks.dispatchPendingUpdateReceived(workflowId, operation.updateName, pendingUpdateAfterRegistration);
+    callbacks.completeOperation(workflowId, {
+      payload: pendingUpdateAfterRegistration.payload,
+      respond: callbacks.createCoordinatedUpdateResponder(workflowId, operation.updateName, pendingUpdateAfterRegistration)
+    });
+    return;
+  }
+  callbacks.completeOperation(workflowId, await promise);
+}
+export function dispatchPendingUpdateReceived(_internals, workflowId, updateName, updateRequest, callbacks) {
+  callbacks.dispatchEvent(new UpdateReceivedEvent(updateRequest.updateId, workflowId, updateName, updateRequest.payload));
+}
+export function createCoordinatedUpdateResponder(_internals, workflowId, updateName, updateRequest, callbacks) {
+  let coordinatedResponded = !1;
+  return (value) => {
+    if (coordinatedResponded)
+      return;
+    coordinatedResponded = !0;
+    callbacks.persistCoordinatedUpdateResponse(workflowId, updateName, updateRequest.updateId, updateRequest.idempotencyKey, value);
+  };
+}
+export async function deliverCoordinatedUpdateToWaiterIfAvailable(internals, workflowId, updateRequest, dispatchReceivedEvent = !1, callbacks) {
+  const waiterKey = `${workflowId}:${updateRequest.name}`, waiter = internals.updateWaiters.get(waiterKey);
+  if (!waiter)
+    return !1;
+  const oldestPendingUpdate = await callbacks.findPendingUpdateByName(workflowId, updateRequest.name);
+  if (!oldestPendingUpdate || oldestPendingUpdate.updateId !== updateRequest.updateId)
+    return !1;
+  await internals.updateCoordinator.deleteRequest(workflowId, updateRequest.updateId);
+  internals.updateWaiters.delete(waiterKey);
+  untrackWaiterKey(internals.updateWaitersByWorkflow, workflowId, waiterKey);
+  if (dispatchReceivedEvent)
+    callbacks.dispatchPendingUpdateReceived(workflowId, updateRequest.name, updateRequest);
+  waiter({
+    payload: updateRequest.payload,
+    respond: callbacks.createCoordinatedUpdateResponder(workflowId, updateRequest.name, updateRequest)
+  });
+  return !0;
+}
+export async function findPendingUpdateByName(internals, workflowId, name) {
+  return (await internals.updateCoordinator.getPendingUpdates(workflowId)).find((updateRequest) => updateRequest.name === name);
+}
+export async function invokeUpdateHandler(_internals, name, handler, payload) {
+  const result = handler(payload);
+  if (isGeneratorResult(result))
+    throw TypeError(`Update handler "${name}" returned a generator. Update handlers must return a plain value or a Promise, not a generator.`);
+  return await result;
+}
+async function runUpdateValidator(internals, workflowId, name, payload) {
+  const validator = internals.inlineStrategy?.getContext(workflowId)?.updateValidators.get(name);
+  if (validator === void 0)
+    return;
+  let result;
+  try {
+    result = await validator(payload);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new UpdateValidationError(name, [{ message }]);
+  }
+  const issues = extractStandardSchemaIssues(result);
+  if (issues !== null && issues.length > 0)
+    throw new UpdateValidationError(name, issues);
+}
+export function extractStandardSchemaIssues(result) {
+  if (result === null || typeof result !== "object" || !("issues" in result))
+    return null;
+  const { issues } = result;
+  if (!Array.isArray(issues))
+    return null;
+  return issues.flatMap((issue) => {
+    if (issue === null || typeof issue !== "object")
+      return [];
+    const obj = issue;
+    if (typeof obj.message !== "string")
+      return [];
+    const entry = { message: obj.message };
+    if (Array.isArray(obj.path) && obj.path.length > 0)
+      entry.path = obj.path.reduce((p, seg) => {
+        const k = seg !== null && typeof seg === "object" && "key" in seg ? String(seg.key) : String(seg);
+        return p + "/" + k.replace(/~/g, "~0").replace(/\//g, "~1");
+      }, "");
+    return [entry];
+  });
+}

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

@@ -0,0 +1,38 @@
+import type { ScheduleFilter, ScheduleOptions, ScheduleOverlapPolicy, ScheduleSpec, ScheduleState, ScheduleStatus } from '../../types.ts';
+export declare const SCHEDULE_STATUSES: Set<ScheduleStatus>;
+export declare const SCHEDULE_OVERLAP_POLICIES: Set<ScheduleOverlapPolicy>;
+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 isValidScheduleIdentifier(value: unknown): value is string;
+export declare function coerceScheduleId(scheduleId: string, fieldName: string): string;
+export declare function normalizeScheduleOptions(options: ScheduleOptions | undefined): Required<Pick<ScheduleOptions, 'overlap' | 'backfill'>> & {
+    id?: string;
+};
+/**
+ * A recurrence specification normalized into the discriminated cadence the
+ * engine persists. Interval periods are resolved to whole milliseconds.
+ */
+export type NormalizedScheduleSpec = {
+    kind: 'cron';
+    cronExpression: string;
+} | {
+    kind: 'interval';
+    intervalMs: number;
+};
+/**
+ * Normalize a schedule recurrence specification into the persisted cadence. A
+ * bare string is treated as a cron expression (preserving the original
+ * cron-only API). An object must supply exactly one of `cron` or `every`.
+ */
+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;
+}) | null;
+type ScheduleRuntimeFields = Pick<ScheduleState, 'backfill' | 'createdAt' | 'updatedAt' | 'lastFireAt' | 'nextFireAt' | 'currentWorkflowId' | 'queuedRuns'>;
+export declare function decodeScheduleRuntimeFields(decoded: Record<string, unknown>, scheduleId: string): ScheduleRuntimeFields | null;
+export declare function decodeScheduleState(bytes: Uint8Array): ScheduleState | null;
+export {};

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

@@ -0,0 +1,258 @@
+import { decode } from "../../codec.js";
+import { isRecord } from "../../debug-output.js";
+import { parseCronExpression } from "../../schedule.js";
+import { parseDuration } from "../../scheduler.js";
+import { coerceStartWorkflowId } from "../../start-workflow-validation.js";
+export const SCHEDULE_STATUSES = new Set(["active", "paused", "cancelled"]), SCHEDULE_OVERLAP_POLICIES = new Set([
+  "skip",
+  "queue",
+  "cancel-running",
+  "allow"
+]);
+export function isValidScheduleTimestamp(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+export function isValidScheduleStatus(value) {
+  return typeof value === "string" && SCHEDULE_STATUSES.has(value);
+}
+export function isValidScheduleOverlapPolicy(value) {
+  return typeof value === "string" && SCHEDULE_OVERLAP_POLICIES.has(value);
+}
+export function isValidScheduleIdentifier(value) {
+  if (typeof value !== "string")
+    return !1;
+  try {
+    coerceStartWorkflowId(value, "schedule id");
+    return !0;
+  } catch {
+    return !1;
+  }
+}
+export function coerceScheduleId(scheduleId, fieldName) {
+  return coerceStartWorkflowId(scheduleId, fieldName);
+}
+export function normalizeScheduleOptions(options) {
+  if (options === void 0)
+    return { overlap: "skip", backfill: !1 };
+  if (typeof options !== "object" || options === null)
+    throw Error("options must be an object when provided");
+  const { id, overlap, backfill } = options, normalizedOptions = {
+    overlap: "skip",
+    backfill: !1
+  };
+  if (id !== void 0)
+    normalizedOptions.id = coerceScheduleId(id, "options.id");
+  if (overlap !== void 0) {
+    if (!SCHEDULE_OVERLAP_POLICIES.has(overlap))
+      throw Error(`options.overlap must be one of ${[...SCHEDULE_OVERLAP_POLICIES].join(", ")}`);
+    normalizedOptions.overlap = overlap;
+  }
+  if (backfill !== void 0) {
+    if (typeof backfill !== "boolean")
+      throw Error("options.backfill must be a boolean when provided");
+    normalizedOptions.backfill = backfill;
+  }
+  return normalizedOptions;
+}
+function normalizeIntervalEvery(every) {
+  if (typeof every !== "string" && typeof every !== "number")
+    throw Error('Schedule interval "every" must be a duration string or a number of milliseconds');
+  let milliseconds;
+  try {
+    milliseconds = parseDuration(every);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw Error(`Invalid schedule interval "every": ${message}`, { cause: error });
+  }
+  const intervalMs = Math.ceil(milliseconds);
+  if (!Number.isSafeInteger(intervalMs) || intervalMs <= 0)
+    throw Error('Schedule interval "every" must resolve to a positive number of milliseconds');
+  return { kind: "interval", intervalMs };
+}
+function normalizeCronSpec(cronExpression) {
+  if (typeof cronExpression !== "string")
+    throw Error('Schedule "cron" must be a string');
+  parseCronExpression(cronExpression);
+  return { kind: "cron", cronExpression };
+}
+export function normalizeScheduleSpec(spec) {
+  if (typeof spec === "string")
+    return normalizeCronSpec(spec);
+  if (typeof spec !== "object" || spec === null)
+    throw Error('Schedule spec must be a cron string or an object with "cron" or "every"');
+  const hasCron = "cron" in spec && spec.cron !== void 0, hasEvery = "every" in spec && spec.every !== void 0;
+  if (hasCron === hasEvery)
+    throw Error('Schedule spec must specify exactly one of "cron" or "every"');
+  return hasEvery ? normalizeIntervalEvery(spec.every) : normalizeCronSpec(spec.cron);
+}
+function validateScheduleFilterStatus(status) {
+  if (status === void 0)
+    return;
+  const statuses = Array.isArray(status) ? status : [status];
+  for (const candidateStatus of statuses)
+    if (!SCHEDULE_STATUSES.has(candidateStatus))
+      throw Error(`filter.status must be one of ${[...SCHEDULE_STATUSES].join(", ")}`);
+}
+function validateScheduleFilterWorkflowType(workflowType) {
+  if (workflowType === void 0)
+    return;
+  if (typeof workflowType !== "string" || workflowType.length === 0)
+    throw Error("filter.workflowType must be a non-empty string when provided");
+}
+function validateScheduleFilterBound(value, fieldName) {
+  if (value === void 0)
+    return;
+  if (!Number.isSafeInteger(value) || value < 0)
+    throw Error(`filter.${fieldName} must be a non-negative safe integer when provided`);
+}
+export function normalizeScheduleFilter(filter) {
+  if (filter === void 0)
+    return;
+  if (typeof filter !== "object" || filter === null)
+    throw Error("filter must be an object when provided");
+  validateScheduleFilterStatus(filter.status);
+  validateScheduleFilterWorkflowType(filter.workflowType);
+  validateScheduleFilterBound(filter.limit, "limit");
+  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))
+    return rejectInvalidScheduleRecord(void 0, "with invalid id");
+  const workflowType = decoded.workflowType;
+  if (typeof workflowType !== "string" || workflowType.length === 0)
+    return rejectInvalidScheduleRecord(id, "with invalid workflowType");
+  const cadence = decodeScheduleCadence(decoded, id);
+  if (!cadence)
+    return null;
+  const status = decoded.status;
+  if (!isValidScheduleStatus(status))
+    return rejectInvalidScheduleRecord(id, "with invalid status");
+  const overlap = decoded.overlap;
+  if (!isValidScheduleOverlapPolicy(overlap))
+    return rejectInvalidScheduleRecord(id, "with invalid overlap policy");
+  return {
+    id,
+    workflowType,
+    status,
+    overlap,
+    ...cadence
+  };
+}
+function decodeScheduleBackfill(decoded, scheduleId) {
+  const backfill = decoded.backfill;
+  if (typeof backfill !== "boolean") {
+    rejectInvalidScheduleRecord(scheduleId, "with invalid backfill flag");
+    return null;
+  }
+  return backfill;
+}
+function decodeScheduleTimestamps(decoded, scheduleId) {
+  const { createdAt, updatedAt } = decoded;
+  if (!isValidScheduleTimestamp(createdAt) || !isValidScheduleTimestamp(updatedAt))
+    return rejectInvalidScheduleRecord(scheduleId, "with invalid timestamps");
+  const lastFireAt = decoded.lastFireAt;
+  if (lastFireAt !== void 0 && !isValidScheduleTimestamp(lastFireAt))
+    return rejectInvalidScheduleRecord(scheduleId, "with invalid lastFireAt");
+  return {
+    createdAt,
+    updatedAt,
+    ...lastFireAt !== void 0 && { lastFireAt }
+  };
+}
+function decodeScheduleNextFireAt(decoded, scheduleId) {
+  const nextFireAt = decoded.nextFireAt;
+  if (nextFireAt === void 0) {
+    rejectInvalidScheduleRecord(scheduleId, "with invalid nextFireAt");
+    return { ok: !1 };
+  }
+  if (nextFireAt !== null && !isValidScheduleTimestamp(nextFireAt)) {
+    rejectInvalidScheduleRecord(scheduleId, "with invalid nextFireAt");
+    return { ok: !1 };
+  }
+  return { ok: !0, value: nextFireAt };
+}
+function decodeScheduleCurrentWorkflowId(decoded, scheduleId) {
+  const currentWorkflowId = decoded.currentWorkflowId;
+  if (currentWorkflowId === void 0)
+    return { ok: !0 };
+  if (!isValidScheduleIdentifier(currentWorkflowId)) {
+    rejectInvalidScheduleRecord(scheduleId, "with invalid currentWorkflowId");
+    return { ok: !1 };
+  }
+  return { ok: !0, value: currentWorkflowId };
+}
+function decodeScheduleQueuedRuns(decoded, scheduleId) {
+  const queuedRuns = decoded.queuedRuns;
+  if (typeof queuedRuns !== "number" || !Number.isSafeInteger(queuedRuns) || queuedRuns < 0) {
+    rejectInvalidScheduleRecord(scheduleId, "with invalid queuedRuns");
+    return null;
+  }
+  return queuedRuns;
+}
+export function decodeScheduleRuntimeFields(decoded, scheduleId) {
+  const backfill = decodeScheduleBackfill(decoded, scheduleId);
+  if (backfill === null)
+    return null;
+  const timestamps = decodeScheduleTimestamps(decoded, scheduleId);
+  if (timestamps === null)
+    return null;
+  const nextFireAt = decodeScheduleNextFireAt(decoded, scheduleId);
+  if (!nextFireAt.ok)
+    return null;
+  const currentWorkflow = decodeScheduleCurrentWorkflowId(decoded, scheduleId);
+  if (!currentWorkflow.ok)
+    return null;
+  const queuedRuns = decodeScheduleQueuedRuns(decoded, scheduleId);
+  if (queuedRuns === null)
+    return null;
+  return {
+    backfill,
+    ...timestamps,
+    nextFireAt: nextFireAt.value,
+    ...currentWorkflow.value !== void 0 && { currentWorkflowId: currentWorkflow.value },
+    queuedRuns
+  };
+}
+export function decodeScheduleState(bytes) {
+  const decoded = decode(bytes);
+  if (!isRecord(decoded)) {
+    console.warn("[weft] Ignoring malformed schedule record with non-object payload.");
+    return null;
+  }
+  const identity = decodeScheduleIdentityFields(decoded);
+  if (!identity)
+    return null;
+  const runtime = decodeScheduleRuntimeFields(decoded, identity.id);
+  if (!runtime)
+    return null;
+  return {
+    ...identity,
+    input: decoded.input,
+    ...runtime
+  };
+}

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

@@ -0,0 +1,40 @@
+import type { HistoryPolicy, NormalizedHistoryPolicy, NormalizedPayloadSizePolicy, NormalizedRetentionPolicy, PayloadSizePolicy, RetentionPolicy, WorkflowState, WorkflowStatus, WorkflowTimelineEntry } from '../types.ts';
+import type { WorkflowVersionTuple } from '../workflow-version-tuple.ts';
+export declare function isSanitizedSearchAttributeValue(value: unknown): value is import('../types.ts').SearchAttributeValue;
+export declare function isWorkflowVersionTuple(value: unknown): value is WorkflowVersionTuple;
+export declare function isFiniteNumber(value: unknown): value is number;
+export declare function isTimelineStep(value: unknown): value is number;
+export declare function isWorkflowTimelineEntry(value: unknown): value is WorkflowTimelineEntry;
+export declare function normalizeBulkFilterNumber(value: unknown, fieldName: 'limit' | 'offset'): number | undefined;
+export declare function isValidDecodedTags(value: unknown): value is string[] | undefined;
+export declare function decodeWorkflowState(bytes: Uint8Array): WorkflowState;
+export declare function normalizeRetentionDuration(value: import('../types.ts').Duration | undefined, fieldName: string): number | undefined;
+/**
+ * Validate and normalise a {@link HistoryPolicy} into a
+ * {@link NormalizedHistoryPolicy}. Mirrors {@link normalizeRetentionPolicy}'s
+ * throw-on-bad-input contract.
+ *
+ * Both `maxEvents` and `retentionWindow` share the same validation mechanics
+ * (they differ in semantics — see {@link HistoryPolicy}):
+ * - omitted policy, or omitted/`undefined` field → `null` (disabled).
+ * - `0` → `null` (disabled; mirrors `checkpointHistory: 0` meaning "off").
+ * - any other value that is not a positive safe integer (negatives, non-integers,
+ *   non-finite values, unsafe integers, wrong types) → throws.
+ */
+export declare function normalizeHistoryPolicy(policy: HistoryPolicy | undefined, context: string): NormalizedHistoryPolicy;
+/**
+ * Validate and normalise a {@link PayloadSizePolicy} into a
+ * {@link NormalizedPayloadSizePolicy}. Mirrors {@link normalizeHistoryPolicy}'s
+ * throw-on-bad-input contract.
+ *
+ * Contract for `maxBytes`:
+ * - omitted policy, or omitted/`undefined`/`null` field → `{ maxBytes: null }` (disabled).
+ * - `0` → `{ maxBytes: null }` (disabled).
+ * - any other value that is not a positive safe integer (negatives, non-integers,
+ *   non-finite values, unsafe integers, wrong types) → throws.
+ */
+export declare function normalizePayloadSizePolicy(policy: PayloadSizePolicy | undefined, context: string): NormalizedPayloadSizePolicy;
+export declare function normalizeRetentionPolicy(policy: RetentionPolicy | undefined, context: string): NormalizedRetentionPolicy | null;
+export declare function resolveRetentionForStatus(policy: NormalizedRetentionPolicy | null | undefined, status: WorkflowStatus): number | undefined;
+export declare function isTerminalWorkflowStatus(status: WorkflowStatus): boolean;
+export declare function isPlainObjectRecord(value: unknown): value is Record<string, unknown>;