@adonis-agora/durable 1.0.0-rc.12 → 1.0.0-rc.14

package/dist/src/engine.js

@@ -36,6 +36,7 @@ import { SINGLETON_RESERVED_TAGS, withoutAdmission, withSingletonTracked, } from
 import { SingletonGate } from './singleton-gate.js';
 import { validateStandard, validateStandardSync, } from './standard-schema.js';
 import { StickyCache, StickyContinuation } from './sticky-continuation.js';
+import { intersectTenantIds, runTenantOf, runVisible, tenantScopeIds, } from './tenancy.js';
 import { sanitizeQueueToken, tenantGroup } from './tenant-group.js';
 import { TransportPool } from './transport-pool.js';
 import { workflowAls } from './workflow-als.js';
@@ -338,6 +339,7 @@ export class WorkflowEngine {
     context;
     /** Establish the originating context ambiently around a local step body (see {@link WorkflowEngineDeps.rehydrate}). Default passthrough. */
     rehydrate;
+    tenancy;
     compensationRetries;
     compensationTimeoutMs;
     retention;
@@ -615,6 +617,7 @@ export class WorkflowEngine {
         this.context = deps.context;
         // Default passthrough: with no bridge supplied, a local step body runs exactly as before.
         this.rehydrate = deps.rehydrate ?? ((_carrier, fn) => fn());
+        this.tenancy = deps.tenancy;
         this.compensationRetries = Math.max(1, deps.compensationRetries ?? 1);
         this.compensationTimeoutMs = Math.max(1_000, deps.compensationTimeoutMs ?? 300_000);
         this.retention = deps.retention;
@@ -626,6 +629,8 @@ export class WorkflowEngine {
             start: (workflow, input, runId, opts) => this.start(workflow, input, runId, opts),
             getRun: (runId) => this.store.getRun(runId),
             isDraining: () => this.draining,
+            tenant: () => this.startTenant(undefined),
+            visible: (record) => this.runVisibleNow({ tenantId: record.tenantId }),
         }, { namespace: this.namespace, clock: this.clock });
         this.stalledAfterMs = Math.max(60_000, deps.stalledAfterMs ?? 900_000);
         this.trackStepStart = deps.trackStepStart ?? true;
@@ -1465,6 +1470,8 @@ export class WorkflowEngine {
         };
         this.trackEffect(this.start(target, input, `dlq:${run.id}`, {
             ...(run.namespace !== undefined ? { namespace: run.namespace } : {}),
+            tenantId: run.tenantId ?? null,
+            ...(run.tenantKind ? { tenantKind: run.tenantKind } : {}),
         }).catch((err) => {
             console.warn(`[adonis-durable] could not start dead-letter workflow ${target} for run ${run.id}: ${err instanceof Error ? err.message : String(err)}`);
         }));
@@ -2548,6 +2555,11 @@ export class WorkflowEngine {
      */
     async republishLifecycle(target) {
         const result = { runs: 0, started: 0, failed: [] };
+        if ('runId' in target &&
+            typeof target.runId === 'string' &&
+            (await this.runHidden(target.runId))) {
+            return result;
+        }
         // A backfill usually follows a deploy: read the fleet's subscriptions now, not from the cache.
         await this.refreshAnnouncedSubscriptions();
         const publish = async (run) => {
@@ -2792,6 +2804,9 @@ export class WorkflowEngine {
         // Idempotent by run id: a redelivered trigger (at-least-once queues) or a scheduler re-tick for
         // the same id is a no-op, returning the existing run's state instead of starting a duplicate.
         const existing = async (prior) => {
+            // Another tenant's run id: answer like a clash, never with that run's state.
+            if (!this.runVisibleNow(prior))
+                throw new Error(`run ${runId} already exists`);
             // A PENDING prior still needs an executor: re-nudge the dispatcher so a redelivered trigger —
             // or a continuation persisted pre-settle (see the ContinueAsNew handoff) picked up by a custom
             // dispatcher — doesn't sit `pending` until the next poll. Idempotent: execution is leased, so
@@ -2840,6 +2855,8 @@ export class WorkflowEngine {
         // Compared against the ENGINE clock (injectable), not wall time — the same clock the timer
         // poller will use to decide the run is due.
         const delayed = startAtMs !== undefined && startAtMs > this.clock();
+        const tenant = this.startTenant(opts);
+        const tenantNamespace = tenant && opts?.namespace === undefined ? this.tenancy?.namespace?.(tenant) : undefined;
         const run = {
             id: runId,
             workflow: name,
@@ -2847,7 +2864,10 @@ export class WorkflowEngine {
             status: delayed ? 'suspended' : 'pending',
             ...(delayed ? { wakeAt: startAtMs } : {}),
             origin: opts?.origin ?? registered.origin,
-            namespace: opts?.namespace ?? this.namespace,
+            namespace: opts?.namespace ?? tenantNamespace ?? this.namespace,
+            ...(tenant
+                ? { tenantId: tenant.id, ...(tenant.kind ? { tenantKind: tenant.kind } : {}) }
+                : {}),
             input,
             tags,
             searchAttributes: opts?.searchAttributes,
@@ -2910,6 +2930,16 @@ export class WorkflowEngine {
      * `limiter` bounds how many of these run at once (a fan's children wait in it as ids).
      */
     handoffRun(workflow, input, runId, opts, onStartError, onAlreadySettled, limiter) {
+        // The tenant is read NOW, inside the parent's turn: a bounded handoff may run later, elsewhere.
+        if (opts?.tenantId === undefined) {
+            const tenant = this.startTenant(opts);
+            if (tenant)
+                opts = {
+                    ...opts,
+                    tenantId: tenant.id,
+                    ...(tenant.kind ? { tenantKind: tenant.kind } : {}),
+                };
+        }
         const handoff = async () => {
             // Defer one microtask: never reentrantly resume the parent that is still suspending/settling.
             await Promise.resolve();
@@ -2949,8 +2979,54 @@ export class WorkflowEngine {
         this.trackEffect(limiter ? limiter.submit(runId, handoff) : handoff());
     }
     /** Read a run's current persisted state (or null if unknown). A thin pass-through to the store. */
-    getRun(runId) {
-        return this.store.getRun(runId);
+    async getRun(runId) {
+        const run = await this.store.getRun(runId);
+        return run && this.runVisibleNow(run) ? run : null;
+    }
+    /** The tenant a new run gets: the explicit option, else the active tenant (tenancy on), else none. */
+    startTenant(opts) {
+        if (opts?.tenantId === null)
+            return undefined;
+        if (typeof opts?.tenantId === 'string' && opts.tenantId !== '') {
+            return opts.tenantKind ? { id: opts.tenantId, kind: opts.tenantKind } : { id: opts.tenantId };
+        }
+        const filter = this.tenantFilterNow();
+        return filter.mode === 'tenant' ? filter.tenant : undefined;
+    }
+    /** How the current app-facing call is scoped (`system` inside the engine's own work). */
+    tenantFilterNow() {
+        if (!this.tenancy || engineInternal.getStore() === true)
+            return { mode: 'system' };
+        return this.tenancy.filter();
+    }
+    /** Whether the current call may see `run` (always, with tenancy off). */
+    runVisibleNow(run) {
+        if (!this.tenancy)
+            return true;
+        return runVisible(this.tenantFilterNow(), run, this.tenancy.nullRows);
+    }
+    /** Whether `runId` exists but the current call may not see it (an app-facing guard: answer not-found). */
+    async runHidden(runId) {
+        if (!this.tenancy)
+            return false;
+        const filter = this.tenantFilterNow();
+        if (filter.mode === 'system' || filter.mode === 'all')
+            return false;
+        const run = await this.store.getRun(runId);
+        return run !== null && !runVisible(filter, run, this.tenancy.nullRows);
+    }
+    /** `query` confined to the runs the current call may see. */
+    tenantScoped(query) {
+        if (!this.tenancy)
+            return query;
+        const ids = tenantScopeIds(this.tenantFilterNow(), this.tenancy.nullRows);
+        if (ids === undefined)
+            return query;
+        return { ...query, tenantIds: intersectTenantIds(query.tenantIds, ids) };
+    }
+    /** Run `fn` as the engine's own work: app-facing tenant guards do not apply inside it. */
+    asEngine(fn) {
+        return this.tenancy ? engineInternal.run(true, fn) : fn();
     }
     /**
      * List persisted runs matching `query` (newest activity first, per the store's own ordering). The
@@ -2958,7 +3034,7 @@ export class WorkflowEngine {
      * through the engine rather than reaching for its private store.
      */
     async listRuns(query) {
-        const scoped = withoutBookkeepingRuns(query);
+        const scoped = withoutBookkeepingRuns(this.tenantScoped(query));
         const runs = await this.store.listRuns(scoped);
         const hidden = scoped.excludeWorkflows;
         return hidden?.length ? runs.filter((run) => !hidden.includes(run.workflow)) : runs;
@@ -2970,14 +3046,16 @@ export class WorkflowEngine {
      * {@link listRuns}.
      */
     runValueFacets(axis, query, opts) {
-        const scoped = withoutBookkeepingRuns(query);
+        const scoped = withoutBookkeepingRuns(this.tenantScoped(query));
         if (this.store.runValueFacets) {
             return this.store.runValueFacets(axis, scoped, opts);
         }
         return scanRunValueFacets(this.store, axis, scoped, opts);
     }
     /** List a run's step checkpoints (its timeline). Part of the engine's read API; see {@link listRuns}. */
-    listCheckpoints(runId) {
+    async listCheckpoints(runId) {
+        if (await this.runHidden(runId))
+            return [];
         return this.store.listCheckpoints(runId);
     }
     /**
@@ -2985,7 +3063,7 @@ export class WorkflowEngine {
      * has {@link StateStore.runFacets} (else counted over a listing). Part of the engine's read API.
      */
     runFacets(query) {
-        return runFacetsOf(this.store, withoutBookkeepingRuns(query));
+        return runFacetsOf(this.store, withoutBookkeepingRuns(this.tenantScoped(query)));
     }
     /**
      * A run's detail (see `loadRunDetail`), built from the store's checkpoint aggregates when it has
@@ -2993,6 +3071,8 @@ export class WorkflowEngine {
      * instead of the whole history, and carries an `etag` that `options.ifNoneMatch` can match.
      */
     async getRunDetail(runId, options) {
+        if (await this.runHidden(runId))
+            return null;
         const source = this.detailSource();
         const withExtras = async (detail) => {
             const extras = await this.lifecycleDetail(detail.run);
@@ -3130,7 +3210,9 @@ export class WorkflowEngine {
         return out;
     }
     /** One page of a summarized fan's members (see `loadFanMembers`), versioned like {@link getRunDetail}. */
-    getFanMembers(runId, group, query) {
+    async getFanMembers(runId, group, query) {
+        if (await this.runHidden(runId))
+            return null;
         return loadFanMembers(this.detailSource(), runId, group, query);
     }
     detailSource() {
@@ -3468,7 +3550,7 @@ export class WorkflowEngine {
     }
     async deleteRun(runId) {
         const run = await this.store.getRun(runId);
-        if (!run)
+        if (!run || !this.runVisibleNow(run))
             return 0;
         // Collect children BEFORE deleting this run's checkpoints (getRunChildren reads them).
         let deleted = 0;
@@ -3553,7 +3635,7 @@ export class WorkflowEngine {
                 if (!TERMINAL_RUN_STATUSES.includes(status)) {
                     if (!cancelLive)
                         continue;
-                    await this.cancel(id).catch(() => undefined);
+                    await this.asEngine(() => this.cancel(id)).catch(() => undefined);
                 }
                 doomed.push(id);
             }
@@ -3737,7 +3819,7 @@ export class WorkflowEngine {
         }
         if (!registered)
             throw new WorkflowNotRegistered(run.workflow, run.workflowVersion);
-        return this.track(runId, this.execute(run, registered.fn));
+        return this.track(runId, this.inRunTenant(run, () => this.execute(run, registered.fn)));
     }
     /**
      * Deferred re-drive after a suspended settle whose waited checkpoint(s) already settled — the
@@ -4580,6 +4662,8 @@ export class WorkflowEngine {
         const seen = _seen ?? new Set();
         if (seen.has(runId))
             return null;
+        if (_seen === undefined && (await this.runHidden(runId)))
+            return null;
         seen.add(runId);
         const run = await this.store.getRun(runId);
         if (!run)
@@ -4728,7 +4812,7 @@ export class WorkflowEngine {
      */
     async redispatchPending(runId) {
         const run = await this.store.getRun(runId);
-        if (!run)
+        if (!run || !this.runVisibleNow(run))
             return null;
         const pending = (await this.store.listCheckpoints(runId)).filter((cp) => cp.kind === 'remote' && cp.status === 'pending');
         let redispatched = 0;
@@ -4764,12 +4848,18 @@ export class WorkflowEngine {
      */
     async retryWithInput(runId, input, newRunId) {
         const run = await this.store.getRun(runId);
-        if (!run)
+        if (!run || !this.runVisibleNow(run))
             return null;
         const id = newRunId ?? `${runId}~retry~${globalThis.crypto.randomUUID().slice(0, 8)}`;
         // Inherit the original run's namespace so a retry lands in the SAME worker-pool partition (an
-        // operator-routed run keeps its tenant on retry, rather than falling back to the engine's own).
-        await this.start(run.workflow, input, id, { tags: run.tags, namespace: run.namespace });
+        // operator-routed run keeps its pool on retry, rather than falling back to the engine's own),
+        // and its tenant (or none).
+        await this.start(run.workflow, input, id, {
+            tags: run.tags,
+            namespace: run.namespace,
+            tenantId: run.tenantId ?? null,
+            ...(run.tenantKind ? { tenantKind: run.tenantKind } : {}),
+        });
         return { runId: id };
     }
     /**
@@ -5036,7 +5126,10 @@ export class WorkflowEngine {
         const waiters = await this.store.listSignalWaiters(eventPrefix(name));
         for (const w of waiters) {
             if (eventMatches(payload, eventMatchOf(w.token))) {
-                await this.signal(w.token, payload);
+                // With tenancy on, a tenant's event reaches its own runs only.
+                if (await this.runHidden(w.runId))
+                    continue;
+                await this.asEngine(() => this.signal(w.token, payload));
                 touched += 1;
             }
         }
@@ -5054,6 +5147,13 @@ export class WorkflowEngine {
         // unless the caller opted out. `touched > 0` covers BOTH the waiter fan-out and the subscriber loop.
         if (touched > 0 || opts?.buffer === false)
             return touched;
+        // A buffered copy carries no tenant and would reach whichever run waits next, so a publisher
+        // scoped to one tenant (or to none) does not buffer: its event reaches live waiters only.
+        if (this.tenancy) {
+            const mode = this.tenantFilterNow().mode;
+            if (mode === 'tenant' || mode === 'tenantless')
+                return touched;
+        }
         const bufferedId = globalThis.crypto.randomUUID();
         await this.store.bufferEvent({ name, payload, id: bufferedId, publishedAt: this.clock() });
         // Re-check: a waiter may have registered in the window between the miss above and this buffer
@@ -5164,6 +5264,8 @@ export class WorkflowEngine {
      * side's write, and the destructive `take*` ops arbitrate so a signal is never delivered twice.
      */
     async signal(token, payload) {
+        if (await this.signalHidden(token))
+            return null;
         const waiter = await this.store.takeSignalWaiter(token);
         if (waiter)
             return this.deliverSignal(waiter, payload);
@@ -5185,6 +5287,23 @@ export class WorkflowEngine {
         }
         return this.deliverSignal(lateWaiter, reclaimed.payload);
     }
+    /** Whether a run another tenant owns is the one waiting on `token` (an app-facing signal is dropped). */
+    async signalHidden(token) {
+        if (!this.tenancy)
+            return false;
+        const filter = this.tenantFilterNow();
+        if (filter.mode === 'system' || filter.mode === 'all')
+            return false;
+        const waiters = await this.store.listSignalWaiters(token);
+        for (const waiter of waiters) {
+            if (waiter.token !== token)
+                continue;
+            const run = await this.store.getRun(waiter.runId);
+            if (run && !runVisible(filter, run, this.tenancy.nullRows))
+                return true;
+        }
+        return false;
+    }
     /**
      * Wake the run parked on `token` with `payload`, if there is one; otherwise do nothing — unlike
      * {@link signal}, it never buffers. For a wake-up whose real payload is ALREADY buffered on the
@@ -5216,14 +5335,18 @@ export class WorkflowEngine {
      * null if no run is waiting on the task (e.g. a duplicate/late delivery) — a safe no-op.
      */
     async completeTask(runId, name, result) {
-        return this.signal(`task:${runId}:${name}`, {
+        if (await this.runHidden(runId))
+            return null;
+        return this.asEngine(() => this.signal(`task:${runId}:${name}`, {
             ok: true,
             value: result,
-        });
+        }));
     }
     /** Report that a `ctx.task` failed — the run resumes and throws a FatalError at the task. */
     async failTask(runId, name, error) {
-        return this.signal(`task:${runId}:${name}`, { ok: false, error });
+        if (await this.runHidden(runId))
+            return null;
+        return this.asEngine(() => this.signal(`task:${runId}:${name}`, { ok: false, error }));
     }
     /**
      * Notify a parent that's waiting on `runId` as a child of its terminal outcome (the `ctx.child`
@@ -5276,7 +5399,7 @@ export class WorkflowEngine {
                 if (!(await childCompletionNeedsBuffer(this.store, token.slice(CHILD_TOKEN_PREFIX.length), completion))) {
                     return;
                 }
-                const resumed = await this.signal(token, completion);
+                const resumed = await this.asEngine(() => this.signal(token, completion));
                 // The parent may settle the child from its run row between the look above and the buffer
                 // write (a join that registers its waiter only now): it then stamped the child first, and the
                 // copy just buffered would never be read.
@@ -5341,7 +5464,7 @@ export class WorkflowEngine {
             : settled.status === 'completed'
                 ? { ok: true, value: settled.output }
                 : failedCompletion(settled.error ?? { message: settled.status });
-        await this.signal(token, completion);
+        await this.asEngine(() => this.signal(token, completion));
     }
     /**
      * Cancel a run (e.g. from the dashboard). Returns null if the run does not exist. Pass
@@ -5350,7 +5473,9 @@ export class WorkflowEngine {
      * cancelled. Without it, cancellation is immediate (no undo).
      */
     async cancel(runId, opts) {
-        return this.cancelOnce(runId, opts, true);
+        if (await this.runHidden(runId))
+            return null;
+        return this.asEngine(() => this.cancelOnce(runId, opts, true));
     }
     async cancelOnce(runId, opts, mayRetry) {
         const run = await this.store.getRun(runId);
@@ -5471,7 +5596,7 @@ export class WorkflowEngine {
      */
     async cancelChildren(parentRunId, opts) {
         for (const id of await this.getRunChildren(parentRunId)) {
-            await this.cancel(id, opts).catch(() => undefined);
+            await this.asEngine(() => this.cancel(id, opts)).catch(() => undefined);
         }
     }
     /**
@@ -5527,7 +5652,7 @@ export class WorkflowEngine {
      * the full listing for a store without one.
      */
     countRuns(query) {
-        return countRuns(this.store, withoutBookkeepingRuns(query));
+        return countRuns(this.store, withoutBookkeepingRuns(this.tenantScoped(query)));
     }
     /**
      * Every workflow the live fleet can execute in this engine's partition: what workers DECLARE in
@@ -5909,6 +6034,18 @@ export class WorkflowEngine {
                 throw err;
         });
     }
+    /**
+     * Run a turn with the run's own tenant active, so a resume driven by a timer, a signal or recovery
+     * (no request around it) sees the tenant the run was started under, and what the turn starts or
+     * dispatches carries it. A run with no tenant runs as before.
+     */
+    inRunTenant(run, fn) {
+        const tenant = runTenantOf(run);
+        if (!this.tenancy || !tenant)
+            return fn();
+        const tenancy = this.tenancy;
+        return engineInternal.run(false, () => tenancy.run(tenant, fn));
+    }
     async execute(run, fn) {
         const registered = this.workflows.get(versionKey(run.workflow, run.workflowVersion));
         // Hold the lease for the WHOLE execution — whatever path got us here (leased sweep, a signal, a
@@ -7586,7 +7723,11 @@ export class WorkflowEngine {
                 // converges on the already-persisted continuation (idempotent by the continuation id).
                 // `dispatch: false`: the tracked handoff below owns the pickup. The continuation inherits
                 // the parent RUN's namespace so a tenant's chain stays in its worker-pool partition.
-                await this.startCore(run.workflow, err.input, nextId, { namespace: run.namespace }, false);
+                await this.startCore(run.workflow, err.input, nextId, {
+                    namespace: run.namespace,
+                    tenantId: run.tenantId ?? null,
+                    ...(run.tenantKind ? { tenantKind: run.tenantKind } : {}),
+                }, false);
                 // Conditional, like every settle: a cancel persisted after the re-read above (`cancelling`, or a
                 // plain `cancelled`) must win over this completion. The continuation already exists then, and
                 // nothing has handed it off: cancel it, and unwind this run if the cancel compensates.
@@ -7597,7 +7738,7 @@ export class WorkflowEngine {
                     updatedAt: new Date(),
                 });
                 if (!completed) {
-                    await this.cancel(nextId);
+                    await this.asEngine(() => this.cancel(nextId));
                     const current = await this.store.getRun(run.id);
                     if (current?.status === 'cancelling' && !this.leaseLostRuns.has(run.id)) {
                         return await this.compensateAndCancel(run, compensations);
@@ -7615,7 +7756,11 @@ export class WorkflowEngine {
                 // continuation has entered `inflight` and settled, so `drain()` can't return before the next
                 // run's store writes land. Still deferred; its startCore call converges on the run persisted
                 // above (prior-run branch) and drives the pickup.
-                this.handoffRun(run.workflow, err.input, nextId, { namespace: run.namespace });
+                this.handoffRun(run.workflow, err.input, nextId, {
+                    namespace: run.namespace,
+                    tenantId: run.tenantId ?? null,
+                    ...(run.tenantKind ? { tenantKind: run.tenantKind } : {}),
+                });
                 return { runId: run.id, status: 'completed' };
             }
             if (err instanceof WorkflowBlocked) {
@@ -7988,7 +8133,7 @@ export class WorkflowEngine {
             // escape `drain()` onto a torn-down connection ("Transaction query already complete"). The
             // one-microtask defer is preserved; the promise is registered synchronously.
             cancelChild: (childId) => {
-                this.trackEffect(Promise.resolve().then(() => this.cancel(childId)));
+                this.trackEffect(Promise.resolve().then(() => this.asEngine(() => this.cancel(childId))));
             },
             // Shallow-merge into the run's searchAttributes (the ctx primitive makes this exactly-once).
             upsertSearchAttributes: async (runId, attrs) => {
@@ -8036,11 +8181,13 @@ export class WorkflowEngine {
      * paused at a breakpoint.
      */
     async continue(runId) {
+        if (await this.runHidden(runId))
+            return null;
         const checkpoints = await this.store.listCheckpoints(runId);
         const bp = checkpoints.find(isBreakpoint);
         if (!bp)
             return null;
-        return this.signal(breakpointToken(runId, bp.seq), undefined);
+        return this.asEngine(() => this.signal(breakpointToken(runId, bp.seq), undefined));
     }
     /**
      * Read the latest value a run published for `key` via {@link WorkflowCtx.setEvent} — a
@@ -8048,6 +8195,8 @@ export class WorkflowEngine {
      * never published that key. The suspend-model counterpart of a Temporal query.
      */
     async getEvent(runId, key) {
+        if (await this.runHidden(runId))
+            return undefined;
         const name = `event:${key}`;
         // Targeted read: the highest-seq checkpoint for this name is the most recent value (a re-published
         // key overwrites at a higher seq), matching the old "last in seq order wins" scan. Falls back to a
@@ -8079,7 +8228,7 @@ export class WorkflowEngine {
      */
     async update(runId, name, arg) {
         const run = await this.store.getRun(runId);
-        if (!run)
+        if (!run || !this.runVisibleNow(run))
             return { accepted: false, reason: `run ${runId} not found` };
         const validate = this.updateValidators.get(`${run.workflow}:${name}`);
         if (validate) {
@@ -8092,7 +8241,7 @@ export class WorkflowEngine {
                 return { accepted: false, reason: err instanceof Error ? err.message : String(err) };
             }
         }
-        const result = await this.signal(`update:${runId}:${name}`, arg);
+        const result = await this.asEngine(() => this.signal(`update:${runId}:${name}`, arg));
         return { accepted: true, run: result };
     }
     // ---------------------------------------------------------------------------
@@ -9816,6 +9965,8 @@ function turnBeatKey(runId) {
 /** The run whose remote turn is being enqueued in the current async context — lets the decision
  *  handler spot a transport delivering the decision from inside its own `dispatchWorkflowTask`. */
 const turnDispatchAls = new AsyncLocalStorage();
+/** `true` while the engine does its own work: app-facing tenant guards do not apply inside it. */
+const engineInternal = new AsyncLocalStorage();
 /** Tolerance (ms) between the worker's clock, which stamps a persisted heartbeat, and this engine's,
  *  when deciding whether a beat belongs to the current attempt (see `awaitWithHeartbeat`). */
 const HEARTBEAT_CLOCK_SKEW_MS = 1_000;