@nestjs/workflows 0.0.3 → 0.0.5

package/dist/services/workflow-client.service.d.ts

@@ -39,7 +39,12 @@ export declare class WorkflowClient implements BeforeApplicationShutdown {
      * with a different workflow or input. With `transaction`, the instance is
      * created in your transaction and commits or rolls back with it. Inside a
      * workflow step, a start without an `id` gets one derived from the step, so a
-     * retried step gets its instance back instead of starting another.
+     * retried step gets its instance back instead of starting another. An id, a
+     * key or an input string the store can't keep (`WorkflowStore.unstorableText()`:
+     * U+0000 on PostgreSQL, a lone UTF-16 surrogate in JSON on PostgreSQL and MySQL)
+     * is refused with a `TypeError`. Await it in your transaction's callback: a
+     * driver whose callback can't be async (better-sqlite3) commits before a failure
+     * is reported.
      */
     start<W>(workflow: Type<W> | string, input: WorkflowInput<W>, options?: StartWorkflowOptions): Promise<WorkflowStartResult>;
     /**
@@ -72,7 +77,8 @@ export declare class WorkflowClient implements BeforeApplicationShutdown {
     private outcomeOf;
     /**
      * `start()`, then `result()`: resolves with the output of the instance (the existing one, for
-     * an id that already has one), or rejects as `result()` does. `wait` is `result()`'s options;
+     * an id that already has one), or rejects as `result()` does. `wait` is `result()`'s options,
+     * counted once the instance is stored (`start()` isn't bounded by them);
      * `options.timeout` stays the instance's run timeout. Not with `{ transaction }`: the instance
      * wouldn't exist before your transaction commits.
      */
@@ -107,6 +113,9 @@ export declare class WorkflowClient implements BeforeApplicationShutdown {
      * instances parked on a matching wait right now. With `transaction`, the
      * signal and the wake-ups commit or roll back with your transaction. With
      * `id`, or from inside a workflow step, a repeated signal is stored once.
+     * A name, key, id or payload string the store can't keep is refused with a
+     * `TypeError`, as in `start()`. Await it in your transaction's callback, as
+     * `start()`.
      */
     signal<T>(signal: WorkflowSignal<T> | string, payload: NoInfer<T>, options?: SignalWorkflowOptions): Promise<WorkflowSignalSendResult>;
     /**

package/dist/services/workflow-client.service.js

@@ -25,6 +25,7 @@ import { assertSameInstance, newInstance } from '../utils/new-instance.util.js';
 import { signalName } from '../signals/workflow.signal.js';
 import { ENGINE_STORE, WorkflowStorage } from '../storage/workflow.storage.js';
 import { stepSignalId, stepStartId } from '../utils/step-scope.util.js';
+import { assertStorableJson, assertStorableText } from '../utils/storable-text.util.js';
 import { WorkflowRegistry } from './workflow-registry.service.js';
 import { WorkflowSchedules } from './workflow-schedules.service.js';
 import { WorkflowWorker } from './workflow-worker.service.js';
@@ -75,7 +76,12 @@ let WorkflowClient = class WorkflowClient {
      * with a different workflow or input. With `transaction`, the instance is
      * created in your transaction and commits or rolls back with it. Inside a
      * workflow step, a start without an `id` gets one derived from the step, so a
-     * retried step gets its instance back instead of starting another.
+     * retried step gets its instance back instead of starting another. An id, a
+     * key or an input string the store can't keep (`WorkflowStore.unstorableText()`:
+     * U+0000 on PostgreSQL, a lone UTF-16 surrogate in JSON on PostgreSQL and MySQL)
+     * is refused with a `TypeError`. Await it in your transaction's callback: a
+     * driver whose callback can't be async (better-sqlite3) commits before a failure
+     * is reported.
      */
     async start(workflow, input, options = {}) {
         const resolved = this.registry.resolve(workflow, options.version);
@@ -84,13 +90,14 @@ let WorkflowClient = class WorkflowClient {
         const data = newInstance(resolved, id, input, {
             caller: 'start()',
             now: this.clock.now(),
+            text: this.store.textCheck,
             timeout: options.timeout,
             concurrencyKey: options.concurrencyKey,
             rateLimitKey: options.rateLimitKey,
             priority: options.priority,
         });
-        // Nothing is awaited before the store's call: on a driver whose transactions are
-        // synchronous, its statements must run before the application's transaction callback returns.
+        // Nothing is awaited before the store's call: calls issued back to back (the CQRS publisher's)
+        // reach the transaction's connection in the order they were made.
         const { instance, created } = await (options.transaction === undefined
             ? this.store.create(data)
             : this.storeMethod('createInTransaction', 'start')(options.transaction, data));
@@ -150,7 +157,8 @@ let WorkflowClient = class WorkflowClient {
     }
     /**
      * `start()`, then `result()`: resolves with the output of the instance (the existing one, for
-     * an id that already has one), or rejects as `result()` does. `wait` is `result()`'s options;
+     * an id that already has one), or rejects as `result()` does. `wait` is `result()`'s options,
+     * counted once the instance is stored (`start()` isn't bounded by them);
      * `options.timeout` stays the instance's run timeout. Not with `{ transaction }`: the instance
      * wouldn't exist before your transaction commits.
      */
@@ -208,6 +216,7 @@ let WorkflowClient = class WorkflowClient {
         return this.stop(id, reason, true);
     }
     async stop(id, reason, terminate) {
+        assertStorableText('Reason', reason, this.store.textCheck('cancelReason'));
         const accepted = await this.store.requestCancel(id, { reason: reason ?? null, now: this.clock.now(), terminate });
         // Accepted is accepted: an instance whose payloads no codec can read any more is returned as stored.
         const details = await this.store.get(id).catch(() => this.store.inner.get(id));
@@ -228,6 +237,9 @@ let WorkflowClient = class WorkflowClient {
      * instances parked on a matching wait right now. With `transaction`, the
      * signal and the wake-ups commit or roll back with your transaction. With
      * `id`, or from inside a workflow step, a repeated signal is stored once.
+     * A name, key, id or payload string the store can't keep is refused with a
+     * `TypeError`, as in `start()`. Await it in your transaction's callback, as
+     * `start()`.
      */
     async signal(signal, payload, options = {}) {
         const name = signalName(signal);
@@ -236,7 +248,13 @@ let WorkflowClient = class WorkflowClient {
             throw new TypeError(`Invalid signal id ${JSON.stringify(options.id)}. Use a non-empty string, such as the id of the event that causes it.`);
         }
         const dedupeId = options.id ?? stepSignalId(name, key) ?? null;
-        const data = { name, key, dedupeId, payload: normalize(payload), now: this.clock.now() };
+        const keyCheck = this.store.textCheck('key');
+        assertStorableText('A signal name', name, keyCheck);
+        assertStorableText('A signal key', key, keyCheck);
+        assertStorableText('A signal id', dedupeId, keyCheck);
+        const json = normalize(payload);
+        assertStorableJson('Signal payload', json, this.store.textCheck('payload'));
+        const data = { name, key, dedupeId, payload: json, now: this.clock.now() };
         // Nothing is awaited before the store's call, as in start().
         const result = await (options.transaction === undefined
             ? this.store.signal(data)

package/dist/services/workflow-execution.service.d.ts

@@ -2,6 +2,7 @@ import { type Type } from '@nestjs/common';
 import type { LeasedRun } from '../core/interfaces/leased-worker-options.interface.js';
 import type { WorkflowClock } from '../interfaces/workflow-clock.interface.js';
 import { type Duration } from '../core/time/duration.js';
+import { type TextChecks } from '../utils/storable-text.util.js';
 import type { SerializedWorkflowError } from '../interfaces/serialized-workflow-error.interface.js';
 import type { WorkflowContext } from '../interfaces/workflow-context.interface.js';
 import type { WorkflowInstance, WorkflowJournalEntry, WorkflowStatus, WorkflowWait } from '../interfaces/workflow-instance.interface.js';
@@ -21,6 +22,8 @@ export declare function uniqueEntries<T extends {
 }>(entries: T[]): T[];
 export interface ExecutionDeps {
     store: WorkflowInstanceStore;
+    /** What the store can't keep of a text at a place (`EncodedWorkflowStore.textCheck`), refused where the run makes it. */
+    textCheck: TextChecks;
     /** The workflow `ctx.startChild()` starts: its name, version and run timeout (`WorkflowRegistry.resolve()`). */
     resolve(workflow: Type<unknown> | string, version?: number): WorkflowMetadata;
     /**

package/dist/services/workflow-execution.service.js

@@ -11,7 +11,9 @@ import { StepFailedError } from '../errors/step-failed.error.js';
 import { NonRetryableStepError } from '../errors/non-retryable-step.error.js';
 import { isWorkflowInterrupt, WorkflowInterrupt, } from '../errors/workflow-interrupt.error.js';
 import { serializeError } from '../utils/serialize-error.util.js';
+import { assertStorableJson, assertStorableText, unstorableJson } from '../utils/storable-text.util.js';
 import { runInStepScope } from '../utils/step-scope.util.js';
+import { setTimer } from '../core/utils/timer.util.js';
 import { ChildWorkflowFailedError } from '../errors/child-workflow-failed.error.js';
 import { WorkflowIdConflictError } from '../errors/workflow-id-conflict.error.js';
 import { CHILD_ENDED_SIGNAL } from '../workflows.constants.js';
@@ -400,6 +402,10 @@ export class WorkflowExecution {
         // The journal first: a replay returns the child it started, whatever the keys of its workflow's limits
         // compute today (a deploy may change them); they are computed only to start it.
         const name = `$child:${id}`;
+        // Only for a child this run starts, as visit() checks names: a replay returns the one a store already kept.
+        if (this.mode === 'run' && !this.journal.has(name)) {
+            assertStorableText("A child's id", id, this.deps.textCheck('name'));
+        }
         this.visit(name, 'child', true);
         const request = { id, workflow: resolved.name, input: createHash('sha256').update(canonical(normalize(input) ?? null)).digest('base64url') };
         const entry = this.journal.get(name);
@@ -429,6 +435,7 @@ export class WorkflowExecution {
             priority: options.priority ?? this.instance.priority,
             parentId: this.instance.id,
             parentClose,
+            text: this.deps.textCheck,
         });
         this.checkKey('instanceId', child.id);
         this.checkKey('workflow', child.workflow);
@@ -485,7 +492,10 @@ export class WorkflowExecution {
             throw this.interrupt('halt');
         }
         this.assertAlive();
-        for (const branch of branches.values()) {
+        const branchNames = this.deps.textCheck('payload');
+        for (const [key, branch] of branches) {
+            // The entry's data holds the branches by name.
+            assertStorableText(`A waitForAny("${name}") branch's name`, key, branchNames);
             if (branch.wait) {
                 this.checkWait(branch.wait);
             }
@@ -587,7 +597,10 @@ export class WorkflowExecution {
             throw new TypeError(`ctx.setStatus() got ${bytes} bytes of JSON, over the ${MAX_CUSTOM_STATUS_BYTES}-byte limit. Keep the status a summary; ` +
                 'return large data from the workflow, or keep it in your own tables.');
         }
-        this.customStatus = json === undefined ? null : JSON.parse(json);
+        // Before it is kept: the write of a failing run carries the last status that was set.
+        const parsed = json === undefined ? null : JSON.parse(json);
+        assertStorableJson('ctx.setStatus() value', parsed, this.deps.textCheck('payload'));
+        this.customStatus = parsed;
     }
     /** `{ customStatus }` when `ctx.setStatus()` changed it since it was last written, else `{}`: spread into a write. */
     statusChange() {
@@ -686,6 +699,11 @@ export class WorkflowExecution {
             catch (error) {
                 throw new NonRetryableStepError(`Result of "${name}" is not JSON-serializable: ${error.message}`);
             }
+            // Like the above, the same result every time: the store would refuse it at every attempt.
+            const unstorable = unstorableJson(`Result of "${name}"`, value, this.deps.textCheck('payload'));
+            if (unstorable) {
+                throw new NonRetryableStepError(unstorable.message);
+            }
         }
         catch (error) {
             if (this.abort.signal.aborted) {
@@ -752,14 +770,14 @@ export class WorkflowExecution {
         });
         const overall = overallMs === undefined
             ? undefined
-            : setTimeout(() => expire(new StepTimeoutError(`Step "${name}" timed out after ${overallMs}ms.`)), overallMs).unref();
+            : setTimer(() => expire(new StepTimeoutError(`Step "${name}" timed out after ${overallMs}ms.`)), overallMs).unref();
         let idle;
         const armIdle = () => {
             if (idleMs === undefined) {
                 return;
             }
             clearTimeout(idle);
-            idle = setTimeout(() => expire(new StepTimeoutError(`Step "${name}" sent no heartbeat for ${idleMs}ms.`)), idleMs).unref();
+            idle = setTimer(() => expire(new StepTimeoutError(`Step "${name}" sent no heartbeat for ${idleMs}ms.`)), idleMs).unref();
         };
         armIdle();
         let current = entry;
@@ -784,7 +802,9 @@ export class WorkflowExecution {
                     }
                     return;
                 }
-                current = { ...current, progress: normalize(progress) };
+                const json = normalize(progress);
+                assertStorableJson('Step progress', json, this.deps.textCheck('payload'));
+                current = { ...current, progress: json };
                 update(current);
                 await this.write([current]);
             },
@@ -847,6 +867,7 @@ export class WorkflowExecution {
         if (!entry && this.mode === 'run') {
             this.assertJournalRoom(name);
             this.checkKey('journalName', name);
+            assertStorableText("A journal entry's name (a step's, a sleep's or a wait's)", name, this.deps.textCheck('name'));
         }
         if (entry && entry.kind !== kind) {
             throw this.setFatal(new WorkflowNonDeterminismError(`${this.describe()} does not match its journal: "${name}" was recorded as a ${entry.kind}, but the code now calls it as a ${kind}. ${ADVICE}`));
@@ -988,6 +1009,11 @@ export class WorkflowExecution {
     checkWait(wait) {
         this.checkKey('signal', wait.signal);
         this.checkKey('signalKey', wait.key);
+        // In the waits' own columns, and in the journal entry's data.
+        for (const check of [this.deps.textCheck('key'), this.deps.textCheck('payload')]) {
+            assertStorableText("A wait's signal name", wait.signal, check);
+            assertStorableText("A wait's signal key", wait.key, check);
+        }
     }
     /** Fenced write of staged entries plus `entries`. */
     async write(entries) {

package/dist/services/workflow-scheduler.service.d.ts

@@ -8,6 +8,7 @@ import type { WorkflowInstance } from '../interfaces/workflow-instance.interface
 import type { WorkflowSchedule } from '../interfaces/workflow-schedule.interface.js';
 import type { WorkflowsModuleOptions } from '../interfaces/workflows-module-options.interface.js';
 import { WorkflowStorage } from '../storage/workflow.storage.js';
+import { type TextCheck, type TextPlace } from '../utils/storable-text.util.js';
 import type { WorkflowScheduleSpec } from '../utils/schedule-spec.util.js';
 import { WorkflowRegistry } from './workflow-registry.service.js';
 /**
@@ -27,6 +28,8 @@ export declare class WorkflowScheduler implements OnApplicationBootstrap {
     constructor(storage: WorkflowStorage, options: WorkflowsModuleOptions, registry: WorkflowRegistry, events: WorkflowEvents);
     /** Read at each call, never in the constructor: sources register while providers are created. */
     private get store();
+    /** What the store can't keep of a text at `place` (`EncodedWorkflowStore.textCheck`), for `WorkflowSchedules`. */
+    textCheck(place: TextPlace): TextCheck | undefined;
     onApplicationBootstrap(): Promise<void>;
     /** @internal Called by the worker: starts the due occurrences of the schedules of the workflows it runs. */
     produce(owner: string, leaseMs: number): Promise<ScheduleProduction>;
@@ -47,6 +50,11 @@ export declare class WorkflowScheduler implements OnApplicationBootstrap {
     readableView(record: ScheduleRecord): Promise<WorkflowSchedule>;
     /** The schedules the workflows this process runs declare (each name's highest registered version's), for the `Scheduler`. */
     private declared;
+    /**
+     * Whether the store can keep a declared schedule's input (`WorkflowStore.unstorableText()`). One it can't is left out,
+     * logged, instead of failing every reconciliation of the others; an input the schedule computes is checked as it starts.
+     */
+    private storable;
     private fire;
     /** The unfinished instances the schedule started. */
     private running;

package/dist/services/workflow-scheduler.service.js

@@ -18,6 +18,7 @@ import { WorkflowStateError } from '../errors/workflow-state.error.js';
 import { WorkflowEvents } from '../events/workflow-events.service.js';
 import { ENGINE_STORE, PAYLOAD_CODECS, WorkflowStorage } from '../storage/workflow.storage.js';
 import { newInstance } from '../utils/new-instance.util.js';
+import { unstorableJson } from '../utils/storable-text.util.js';
 import { workflowScheduleStore } from '../utils/schedule-store.util.js';
 import { WORKFLOWS_MODULE_OPTIONS } from '../workflows.module-definition.js';
 import { WorkflowRegistry } from './workflow-registry.service.js';
@@ -57,6 +58,10 @@ let WorkflowScheduler = class WorkflowScheduler {
     get store() {
         return this.storage[ENGINE_STORE];
     }
+    /** What the store can't keep of a text at `place` (`EncodedWorkflowStore.textCheck`), for `WorkflowSchedules`. */
+    textCheck(place) {
+        return this.store.textCheck(place);
+    }
     async onApplicationBootstrap() {
         // A definition error (an id two workflows declare) fails the startup; the store's errors don't.
         this.registry.schedules();
@@ -93,6 +98,7 @@ let WorkflowScheduler = class WorkflowScheduler {
                 priority: spec.priority === 0 ? undefined : spec.priority,
                 scheduleId: record.id,
                 scheduledAt: at,
+                text: this.store.textCheck,
             });
         }
         catch (error) {
@@ -142,12 +148,25 @@ let WorkflowScheduler = class WorkflowScheduler {
     }
     /** The schedules the workflows this process runs declare (each name's highest registered version's), for the `Scheduler`. */
     declared() {
-        this.declarations ??= new Map([...this.registry.schedules()].map(([id, schedule]) => [
+        this.declarations ??= new Map([...this.registry.schedules()]
+            .filter(([id, schedule]) => this.storable(id, schedule.input))
+            .map(([id, schedule]) => [
             id,
             { id, target: schedule.workflow, version: this.registry.latest(schedule.workflow).version, spec: schedule.spec, payload: schedule.input },
         ]));
         return this.declarations;
     }
+    /**
+     * Whether the store can keep a declared schedule's input (`WorkflowStore.unstorableText()`). One it can't is left out,
+     * logged, instead of failing every reconciliation of the others; an input the schedule computes is checked as it starts.
+     */
+    storable(id, input) {
+        const refused = typeof input === 'function' ? undefined : unstorableJson(`Schedule "${id}": its input`, input, this.store.textCheck('payload'));
+        if (refused) {
+            this.logger.error(`${refused.message} The schedule isn't saved, and doesn't start its workflow.`);
+        }
+        return !refused;
+    }
     async fire({ schedule, spec, declared, at, now }) {
         const workflow = this.registry.resolve(schedule.target, spec.version ?? undefined);
         const started = await this.startOccurrence(schedule, spec, declared, workflow, at, now);

package/dist/services/workflow-schedules.service.js

@@ -16,6 +16,7 @@ import { systemClock } from '../core/time/clock.js';
 import { WorkflowNotFoundError } from '../errors/workflow-not-found.error.js';
 import { WorkflowStateError } from '../errors/workflow-state.error.js';
 import { normalize } from '../utils/normalize.util.js';
+import { assertStorableJson } from '../utils/storable-text.util.js';
 import { scheduleSpec } from '../utils/schedule-spec.util.js';
 import { WORKFLOWS_MODULE_OPTIONS } from '../workflows.module-definition.js';
 import { WorkflowRegistry } from './workflow-registry.service.js';
@@ -62,6 +63,7 @@ let WorkflowSchedules = class WorkflowSchedules {
         catch (error) {
             throw new TypeError(`${owner}: its input is not JSON-serializable: ${error.message}`);
         }
+        assertStorableJson(`${owner}: its input`, input, this.scheduler.textCheck('payload'));
         const saved = await this.engine.save(id, (current) => {
             if (current?.declared) {
                 throw declaredError(current);

package/dist/services/workflow-worker.service.js

@@ -16,6 +16,7 @@ import { LeasedWorker } from '../core/workers/leased-worker.js';
 import { WorkflowNonDeterminismError } from '../errors/workflow-non-determinism.error.js';
 import { isWorkflowInterrupt } from '../errors/workflow-interrupt.error.js';
 import { serializeError } from '../utils/serialize-error.util.js';
+import { assertStorableJson } from '../utils/storable-text.util.js';
 import { resolveRetry } from '../core/retries/retry.js';
 import { resolveJournalLimits } from '../utils/journal-limits.util.js';
 import { normalize } from '../utils/normalize.util.js';
@@ -64,6 +65,7 @@ let WorkflowWorker = class WorkflowWorker {
             get store() {
                 return storage[ENGINE_STORE];
             },
+            textCheck: (place) => storage[ENGINE_STORE].textCheck(place),
             resolve: (workflow, version) => registry.resolve(workflow, version),
             createChild: async (child) => {
                 const { instance, created } = await storage[ENGINE_STORE].create(child);
@@ -272,6 +274,7 @@ let WorkflowWorker = class WorkflowWorker {
             let output;
             try {
                 output = normalize(outcome.value);
+                assertStorableJson('Workflow output', output, this.store.textCheck('payload'));
             }
             catch (error) {
                 return this.compensate(exec, instance, serializeError(error), false);

package/dist/storage/encoded-workflow.store.d.ts

@@ -1,6 +1,7 @@
 import type { WorkflowPayloadContext } from '../interfaces/workflow-payload-codec.interface.js';
 import { type PayloadCodecs } from '../core/codecs/payload-codecs.js';
 import type { WorkflowScheduleMethods } from '../utils/schedule-store.util.js';
+import { type TextCheck, type TextPlace } from '../utils/storable-text.util.js';
 import type { WorkflowInstance, WorkflowStatus } from '../interfaces/workflow-instance.interface.js';
 import type { NewWorkflowInstance, NewWorkflowSignal, WorkflowCancelRequest, WorkflowClaim, WorkflowClaimRequest, WorkflowInstanceDetails, WorkflowListQuery, WorkflowPurgeQuery, WorkflowPurgeResult, WorkflowReopen, WorkflowSignalQuery, WorkflowSignalRecord, WorkflowSignalResult, WorkflowStore, WorkflowWrite } from '../interfaces/workflow-store.interface.js';
 /** @internal A `WorkflowStore` without its schedules, which the engine reaches through the core's `Scheduler`. */
@@ -24,6 +25,11 @@ export declare class EncodedWorkflowStore implements WorkflowInstanceStore {
     inner: WorkflowStore, codecs: PayloadCodecs<WorkflowPayloadContext>);
     /** Whether a codec encodes what is written. */
     get encodes(): boolean;
+    /**
+     * What the store can't keep of a text at `place` (`WorkflowStore.unstorableText()`), or `undefined` where it keeps
+     * any: a store without the method, and a payload or a cancel reason a codec encodes, which the store sees encoded.
+     */
+    readonly textCheck: (place: TextPlace) => TextCheck | undefined;
     create(instance: NewWorkflowInstance): Promise<{
         instance: WorkflowInstance;
         created: boolean;
@@ -53,6 +59,11 @@ export declare class EncodedWorkflowStore implements WorkflowInstanceStore {
         terminateRequested: boolean;
     } | null>;
     write(id: string, token: string, write: WorkflowWrite): Promise<boolean>;
+    /**
+     * `error` with what the store can't keep in its text replaced with U+FFFD (`storableText()`), as an error is recorded
+     * whatever it holds: its name, and its message and stack unless a codec encodes them.
+     */
+    private storableError;
     private encodeNew;
     private encodeSignal;
     private encodeEntries;

package/dist/storage/encoded-workflow.store.js

@@ -1,6 +1,7 @@
 import { Logger } from '@nestjs/common';
 import { isEncodedPayload as encoded } from '../core/codecs/payload-codecs.js';
 import { andThen, toPromise } from '../core/utils/maybe.util.js';
+import { storableText } from '../utils/storable-text.util.js';
 /**
  * @internal The store as the engine sees it with a codec: payloads encoded on the way in, decoded on the way out, so
  * the store sees only what the codec returns, and the engine only plain values. Ids, names, keys, statuses and
@@ -13,6 +14,18 @@ export class EncodedWorkflowStore {
         this.inner = inner;
         this.codecs = codecs;
         this.unreadable = new Set();
+        /**
+         * What the store can't keep of a text at `place` (`WorkflowStore.unstorableText()`), or `undefined` where it keeps
+         * any: a store without the method, and a payload or a cancel reason a codec encodes, which the store sees encoded.
+         */
+        this.textCheck = (place) => {
+            const inner = this.inner;
+            if (typeof inner.unstorableText !== 'function' || (this.encodes && (place === 'payload' || place === 'cancelReason'))) {
+                return undefined;
+            }
+            const column = place === 'payload' || place === 'name' ? 'json' : 'text';
+            return (text) => inner.unstorableText(text, column);
+        };
         // Only when the store has them: the client tells a store that can't join transactions by their absence.
         // Nothing is awaited before the store's call when the codec is synchronous (see WorkflowClient.start()).
         if (typeof inner.createInTransaction === 'function') {
@@ -52,7 +65,10 @@ export class EncodedWorkflowStore {
         return this.inner.requestCancel(id, { ...request, reason });
     }
     async reopen(id, reopen) {
-        const [error, entries] = await Promise.all([this.codecs.encodeError(reopen.error, { field: 'error', instanceId: id }), this.encodeEntries(reopen.entries, id)]);
+        const [error, entries] = await Promise.all([
+            this.codecs.encodeError(this.storableError(reopen.error), { field: 'error', instanceId: id }),
+            this.encodeEntries(reopen.entries, id),
+        ]);
         return this.inner.reopen(id, { ...reopen, error, entries });
     }
     delete(id, statuses) {
@@ -93,7 +109,7 @@ export class EncodedWorkflowStore {
         const [entries, output, error, customStatus, signal] = await Promise.all([
             this.encodeEntries(write.entries, id),
             this.codecs.encode(write.output, context('output')),
-            this.codecs.encodeError(write.error, context('error')),
+            this.codecs.encodeError(this.storableError(write.error), context('error')),
             this.codecs.encode(write.customStatus, context('customStatus')),
             write.signal ? this.encodeSignal(write.signal) : undefined,
         ]);
@@ -107,6 +123,25 @@ export class EncodedWorkflowStore {
         });
     }
     // ---------------------------------------------------------------- payloads
+    /**
+     * `error` with what the store can't keep in its text replaced with U+FFFD (`storableText()`), as an error is recorded
+     * whatever it holds: its name, and its message and stack unless a codec encodes them.
+     */
+    storableError(error) {
+        const check = this.textCheck('name');
+        if (!check || error === null || error === undefined) {
+            return error;
+        }
+        const text = (value) => (typeof value !== 'string' || this.encodes ? value : storableText(value, check));
+        const { compensation } = error;
+        return {
+            ...error,
+            name: typeof error.name === 'string' ? storableText(error.name, check) : error.name,
+            message: text(error.message),
+            ...(error.stack === undefined ? {} : { stack: text(error.stack) }),
+            ...(compensation === undefined ? {} : { compensation: this.storableError(compensation) }),
+        };
+    }
     encodeNew(instance) {
         return andThen(this.codecs.encode(instance.input, { field: 'input', instanceId: instance.id }), (input) => ({ ...instance, input }));
     }
@@ -120,7 +155,7 @@ export class EncodedWorkflowStore {
                 this.codecs.encode(entry.result, context('result')),
                 this.codecs.encode(entry.progress, context('progress')),
                 this.codecs.encode(entry.data, context('data')),
-                this.codecs.encodeError(entry.error, context('error')),
+                this.codecs.encodeError(this.storableError(entry.error), context('error')),
             ]);
             return { ...entry, result, progress, data, error };
         }));

package/dist/testing/index.js

@@ -426,11 +426,11 @@ export function workflowStoreContract(createStore, options = {}) {
     add('write() with a signal records it as signal() does, only when the write lands', async (t) => {
         await t.create('parent', 0);
         await t.create('child', 1);
-        await t.claim(1, { token: 'p', limit: 1 });
+        equal((await t.claim(1, { token: 'p', limit: 1 })).instances.map((i) => i.id), ['parent'], 'the parent, claimed');
         const parked = { wakeAt: FAR, waits: [{ signal: 'child.ended', key: 'child' }], signalCursor: 0 };
-        await t.store.write('parent', 'p', { now: 2, entries: [], status: 'suspended', release: parked });
-        await t.claim(3, { token: 'stale', leaseUntil: 4 });
-        await t.claim(5, { token: 'c' });
+        equal(await t.store.write('parent', 'p', { now: 2, entries: [], status: 'suspended', release: parked }), true, 'the parent, parked');
+        equal((await t.claim(3, { token: 'stale', leaseUntil: 4 })).instances.map((i) => i.id), ['child'], 'the child, claimed under a lease that ends at 4');
+        equal((await t.claim(5, { token: 'c' })).instances.map((i) => i.id), ['child'], 'the child, claimed again once that lease ended');
         const ended = { name: 'child.ended', key: 'child', dedupeId: 'child', payload: { status: 'completed', output: { label: 'LBL-1' } }, now: 6 };
         const finish = (token, now) => t.store.write('child', token, { now, entries: [], status: 'completed', output: 1, error: null, release: { wakeAt: null, waits: [], signalCursor: 0 }, signal: { ...ended, now } });
         equal(await finish('stale', 6), false, 'a stale write');

package/dist/utils/index.d.ts

@@ -5,3 +5,4 @@ export * from './step-scope.util.js';
 export * from './journal-limits.util.js';
 export * from './new-instance.util.js';
 export * from './normalize.util.js';
+export * from './storable-text.util.js';

package/dist/utils/index.js

@@ -5,3 +5,4 @@ export * from './step-scope.util.js';
 export * from './journal-limits.util.js';
 export * from './new-instance.util.js';
 export * from './normalize.util.js';
+export * from './storable-text.util.js';

package/dist/utils/new-instance.util.d.ts

@@ -2,6 +2,7 @@ import type { WorkflowMetadata } from '../interfaces/workflow-decorator-options.
 import type { WorkflowInstance, WorkflowParentClose } from '../interfaces/workflow-instance.interface.js';
 import type { NewWorkflowInstance } from '../interfaces/workflow-store.interface.js';
 import type { Duration } from '../core/time/duration.js';
+import { type TextChecks } from './storable-text.util.js';
 export interface NewInstanceOptions {
     caller: string;
     now: number;
@@ -13,6 +14,8 @@ export interface NewInstanceOptions {
     parentClose?: WorkflowParentClose;
     scheduleId?: string;
     scheduledAt?: number;
+    /** The store's checks of text (`EncodedWorkflowStore.textCheck`): what it can't keep is refused before it is asked to. */
+    text: TextChecks;
 }
 /** What `WorkflowClient.start()` and `ctx.startChild()` ask the store to create. */
 export declare function newInstance(workflow: WorkflowMetadata, id: unknown, input: unknown, options: NewInstanceOptions): NewWorkflowInstance;

package/dist/utils/new-instance.util.js

@@ -3,16 +3,23 @@ import { assertPriority } from '../core/limits/limits.js';
 import { canonical } from '../core/utils/canonical.util.js';
 import { runTimeoutMs } from './run-timeout.util.js';
 import { normalize } from './normalize.util.js';
+import { assertStorableJson, assertStorableText } from './storable-text.util.js';
 /** What `WorkflowClient.start()` and `ctx.startChild()` ask the store to create. */
 export function newInstance(workflow, id, input, options) {
     if (typeof id !== 'string' || id.length === 0) {
         throw new TypeError(`Invalid workflow instance id ${JSON.stringify(id)}. Use a non-empty string, such as \`order-\${orderId}\`.`);
     }
+    assertStorableText('An instance id', id, options.text('key'));
     if (options.priority !== undefined) {
         assertPriority(options.priority, options.caller);
     }
     const json = normalize(input);
+    assertStorableJson('Input', json, options.text('payload'));
     const timeoutMs = options.timeout === undefined ? workflow.timeout : runTimeoutMs(options.timeout, options.caller);
+    const concurrencyKey = keyOf(workflow, json, options.caller, 'concurrency', options.concurrencyKey);
+    assertStorableText('A concurrency key', concurrencyKey, options.text('key'));
+    const rateLimitKey = keyOf(workflow, json, options.caller, 'rateLimit', options.rateLimitKey);
+    assertStorableText('A rate-limit key', rateLimitKey, options.text('key'));
     return {
         id,
         workflow: workflow.name,
@@ -21,8 +28,8 @@ export function newInstance(workflow, id, input, options) {
         deadline: timeoutMs === undefined ? null : options.now + timeoutMs,
         parentId: options.parentId ?? null,
         parentClose: options.parentClose ?? null,
-        concurrencyKey: keyOf(workflow, json, options.caller, 'concurrency', options.concurrencyKey),
-        rateLimitKey: keyOf(workflow, json, options.caller, 'rateLimit', options.rateLimitKey),
+        concurrencyKey,
+        rateLimitKey,
         priority: options.priority ?? 0,
         scheduleId: options.scheduleId ?? null,
         scheduledAt: options.scheduledAt ?? null,

package/dist/utils/serialize-error.util.js

@@ -6,7 +6,13 @@ import { inspect } from 'node:util';
  */
 export function serializeError(error) {
     if (error instanceof Error) {
-        return { name: error.name || 'Error', message: String(error.message), stack: error.stack };
+        // Strings, as the record promises: a name or stack that isn't one is described, not thrown on.
+        const stack = stackOf(error);
+        return {
+            name: text(error.name || 'Error'),
+            message: text(error.message),
+            ...(stack === undefined ? {} : { stack }),
+        };
     }
     if (typeof error === 'string') {
         return { name: 'Error', message: error };
@@ -20,3 +26,21 @@ export function serializeError(error) {
     }
     return { name: 'Error', message: message ?? inspect(error, { depth: 3, breakLength: Infinity }) };
 }
+/** `String(value)`, or `util.inspect()` for a value `String()` throws on (no prototype, a throwing `toString()`). */
+function text(value) {
+    try {
+        return String(value);
+    }
+    catch {
+        return inspect(value, { depth: 3, breakLength: Infinity });
+    }
+}
+/** The error's stack, or `undefined`: V8 formats it on first read from the error's name, and throws if it can't. */
+function stackOf(error) {
+    try {
+        return error.stack === undefined ? undefined : text(error.stack);
+    }
+    catch {
+        return undefined;
+    }
+}