@cosmicdrift/kumiko-framework 0.386.0 → 0.388.0

package/dist/jobs/job-runner-context.js

@@ -0,0 +1,305 @@
+/// <reference types="temporal-polyfill/global" preserve="true" />
+import { crossTenantReadsGrantFor, escapeHatchFor } from "@cosmicdrift/kumiko-types/handlers";
+import { createCrossTenantReads } from "../db/cross-tenant-reads.js";
+import { createTenantDb, createUncheckedSystemDb } from "../db/tenant-db.js";
+import { createDerivativesContext } from "../derivatives/derivatives-context.js";
+import { createSystemUser } from "../engine/system-user.js";
+import { InternalError } from "../errors/index.js";
+import { createTenantFileContext } from "../files/file-handle.js";
+import { createEscapeHatchReporter, createMetricsForFactory } from "../observability/index.js";
+import { configAccessorFactoryOf } from "../pipeline/config-accessor-factory.js";
+import { createGatedIdentitySwitch } from "../pipeline/system-identity-switch.js";
+import { buildPersonalDataGate, parseWriteOrigin } from "../pipeline/write-origin.js";
+import { attemptNumberOf, createJobLogger, handlerPayloadOf, isFinalAttempt, isJobTriggerEvent, jobSubjectKey, missingDbProxy, tenantIdOfJobData, } from "./job-runner-helpers.js";
+// Tenant-visible failure record (JobDefinition.tenantVisibleFailure). The
+// subject is read from the handler payload, so it is resolved where the
+// payload is built, not in the callbacks.
+// A bad subject config must surface as a failed run, so it is only recorded
+// here and thrown from inside the span, not before any run record exists.
+function resolveTenantVisibleSubjects(jobName, jobDef, payload) {
+    let failureSubject = null;
+    let runSubject = null;
+    let configError;
+    const runDecl = jobDef.tenantVisibleRun;
+    const failureDecl = jobDef.tenantVisibleFailure;
+    if (runDecl) {
+        try {
+            runSubject = jobSubjectKey(jobName, payload, runDecl.subjectFields, "tenantVisibleRun");
+        }
+        catch (err) {
+            configError = err instanceof Error ? err : new Error(String(err));
+        }
+    }
+    if (failureDecl && !configError) {
+        try {
+            failureSubject = jobSubjectKey(jobName, payload, failureDecl.subjectFields, "tenantVisibleFailure");
+        }
+        catch (err) {
+            configError = err instanceof Error ? err : new Error(String(err));
+        }
+    }
+    return { failureSubject, runSubject, configError };
+}
+// Absent = legacy or ungated root; present but invalid fails the run closed.
+function parseJobWriteOrigin(rawData, jobName) {
+    const rawWriteOrigin = rawData["_writeOrigin"]; // @cast-boundary dynamic-key
+    if (rawWriteOrigin === undefined)
+        return { writeOrigin: undefined, writeOriginInvalid: false };
+    const parsed = parseWriteOrigin(rawWriteOrigin);
+    if (!parsed)
+        return { writeOrigin: undefined, writeOriginInvalid: true };
+    return { writeOrigin: { ...parsed, viaJob: jobName }, writeOriginInvalid: false };
+}
+function createJobEscapeHatchReporter(scope, input, systemUser) {
+    const { jobName, jobDef, tenantId, triggeredById } = input;
+    // One reporter for ctx.systemDb and ctx.db.unsafeRaw() so both dedupe in the same window.
+    const isSystemCronRun = triggeredById === null && jobDef.escapeHatch !== undefined && "cron" in jobDef.trigger;
+    return createEscapeHatchReporter({
+        handler: jobName,
+        tenantId,
+        actor: systemUser.id,
+        sink: scope.context._escapeHatchAuditSink,
+        log: scope.errorLogger,
+        window: scope.escapeHatchReportWindow,
+        ...(triggeredById !== null && { caller: triggeredById }),
+        ...(isSystemCronRun && { processDedup: scope.systemCronEscapeHatchDedup }),
+        ...(scope.context.meter && { meter: scope.context.meter }),
+    });
+}
+function buildJobDbFacets(scope, facetInput) {
+    const { context, registry } = scope;
+    const { input, isSystemJob, reportEscapeHatch } = facetInput;
+    const { jobDef, tenantId, writeOrigin } = input;
+    const personalDataGate = writeOrigin ? buildPersonalDataGate(registry, writeOrigin) : undefined;
+    const configDb = context.db; // @cast-boundary db-operator
+    // Shared by the config accessor and ctx.derivatives below — both need the
+    // same tenant-scoped db, and building it twice would let the two calls
+    // drift apart. Always "system" mode regardless of the job's own
+    // systemScope() status (pre-existing, not something this change alters)
+    // — isSystemJob below is what actually keeps ctx.systemDb off a
+    // non-system job; it is the only thing standing between this db and an
+    // unchecked cross-tenant escape hatch for such a job. Gated like jobDb so
+    // ctx.systemDb, built from it, is gated too.
+    const tenantScopedDb = configDb
+        ? createTenantDb({
+            db: configDb,
+            tenantId,
+            mode: "system",
+            grants: {
+                projectionRegistry: registry,
+                ...(personalDataGate && { personalDataGate }),
+            },
+        })
+        : undefined;
+    const systemDb = isSystemJob && tenantScopedDb
+        ? createUncheckedSystemDb(tenantScopedDb, undefined, reportEscapeHatch)
+        : undefined;
+    const jobDb = configDb
+        ? createTenantDb({
+            db: configDb,
+            tenantId,
+            mode: "tenant",
+            tracer: context.tracer,
+            meter: context.meter,
+            grants: {
+                unsafeRaw: escapeHatchFor(jobDef.escapeHatch, "unsafeRaw"),
+                globalWrites: escapeHatchFor(jobDef.escapeHatch, "globalWrites"),
+                report: reportEscapeHatch,
+                projectionRegistry: registry,
+                ...(personalDataGate && { personalDataGate }),
+            },
+        })
+        : undefined;
+    const crossTenantReadsReason = crossTenantReadsGrantFor(jobDef.escapeHatch)?.reason;
+    const crossTenantReads = tenantScopedDb && crossTenantReadsReason !== undefined
+        ? createCrossTenantReads(tenantScopedDb, crossTenantReadsReason, reportEscapeHatch)
+        : undefined;
+    return { tenantScopedDb, jobDb, systemDb, crossTenantReads };
+}
+function buildJobServiceFacets(scope, facetInput, tenantScopedDb) {
+    const { context, registry } = scope;
+    const { input, systemUser } = facetInput;
+    const { tenantId } = input;
+    // Mirror dispatch-shared.ts buildHandlerContext: ctx.files must resolve
+    // through the same _fileProviderResolver for jobs as for write-handlers,
+    // otherwise event-triggered jobs silently get an unresolved ctx.files.
+    const fileResolver = context._fileProviderResolver;
+    const files = fileResolver ? createTenantFileContext(fileResolver, tenantId) : context.files;
+    // Same buildHandlerContext parity as ctx.files above: ctx.notify/ctx.config
+    // must resolve for jobs the same way they do for write-handlers, or an
+    // app-author job calling ctx.notify(...)/ctx.config(...) hits a TypeError
+    // at runtime the write-handler path never would.
+    const notify = context._notifyFactory?.(systemUser, tenantId, scope.getSelfRunner(), undefined, context._fileProviderResolver);
+    const configFactory = configAccessorFactoryOf(context);
+    const config = configFactory && tenantScopedDb
+        ? configFactory({
+            user: { id: systemUser.id, tenantId },
+            db: tenantScopedDb,
+            secrets: context.secrets,
+        })
+        : undefined;
+    // Mirror dispatch-shared.ts: ctx.derivatives needs files+db, same
+    // tenant-scoped db the config accessor above uses.
+    const derivatives = files && tenantScopedDb
+        ? createDerivativesContext({ files, registry, db: tenantScopedDb, tenantId })
+        : context.derivatives;
+    return { files, notify, config, derivatives };
+}
+function requireDispatchRef(scope, method) {
+    const ref = scope.getDispatchWriteRef();
+    if (!ref) {
+        throw new Error(`JobContext.${method} called before dispatcher attached — call attachDispatcher() first`);
+    }
+    return ref;
+}
+function buildJobDispatchFacets(scope, facetInput) {
+    const { input, systemUser, isSystemJob, reportEscapeHatch } = facetInput;
+    const { jobName, jobDef, tenantId, writeOrigin } = input;
+    // Per-job-run reader, created lazily on queryAsMember's first call and
+    // cached for the rest of this run.
+    let memberReader;
+    const identitySwitchHatch = escapeHatchFor(jobDef.escapeHatch, "systemIdentity");
+    const identitySwitchGrantReason = identitySwitchHatch?.reason ??
+        (isSystemJob ? `r.systemScope() feature of job "${jobName}"` : undefined);
+    const gatedIdentitySwitch = createGatedIdentitySwitch(`job "${jobName}"`, systemUser, isSystemJob || identitySwitchHatch !== undefined, {
+        queryAs: (user, qn, payload) => requireDispatchRef(scope, "queryAs").queryAs(user, qn, payload, writeOrigin),
+        writeAs: async (user, qn, payload) => requireDispatchRef(scope, "writeAs").write(user, qn, payload, writeOrigin),
+    }, { reason: identitySwitchGrantReason, report: reportEscapeHatch });
+    return {
+        write: (qn, payload) => requireDispatchRef(scope, "write").write(systemUser, qn, payload, writeOrigin),
+        writeAs: gatedIdentitySwitch.writeAs,
+        queryAs: gatedIdentitySwitch.queryAs,
+        queryAsMember: (userId, qn, payload) => {
+            const ref = requireDispatchRef(scope, "queryAsMember");
+            // Lazy per-run reader, mirroring the handler-context reader.
+            memberReader ??= ref.createMemberReader(tenantId);
+            return memberReader(userId, qn, payload);
+        },
+    };
+}
+function createJobDefer(jobName, bullJob, token) {
+    return (delayMs) => {
+        if (!Number.isInteger(delayMs) || delayMs <= 0) {
+            throw new RangeError(`Job "${jobName}": ctx.defer needs a positive integer delay in ms (got ${delayMs})`);
+        }
+        if (token === undefined || !bullJob.moveToDelayed) {
+            throw new InternalError({
+                message: `Job "${jobName}": ctx.defer needs a queued run; it is not available inline (boot gate).`,
+            });
+        }
+        return { kind: "job-deferral", delayMs };
+    };
+}
+function buildJobContext(scope, input) {
+    const { jobName, bullJob, token, rawData, tenantId, triggeredById, attempt, finalAttempt } = input;
+    const systemUser = createSystemUser(tenantId);
+    const facetInput = {
+        input,
+        systemUser,
+        isSystemJob: scope.registry.isJobSystemScoped(jobName),
+        reportEscapeHatch: createJobEscapeHatchReporter(scope, input, systemUser),
+    };
+    const { tenantScopedDb, jobDb, systemDb, crossTenantReads } = buildJobDbFacets(scope, facetInput);
+    const { files, notify, config, derivatives } = buildJobServiceFacets(scope, facetInput, tenantScopedDb);
+    const dispatchFacets = buildJobDispatchFacets(scope, facetInput);
+    const selfRunner = scope.getSelfRunner();
+    // Carry `_triggerName` from rawData when set — handleEvent injects it on
+    // multi-trigger dispatch; exposed as jobContext.triggerName so handlers
+    // don't dig through the raw payload themselves.
+    const triggerName = rawData["_triggerName"]; // @cast-boundary dynamic-key
+    // Same carry-through for `_triggerEvent` — handleEvent injects it when
+    // the job-trigger event consumer supplied the stored event that fired
+    // this run (see createJobTriggerEventConsumer).
+    const rawTriggerEvent = rawData["_triggerEvent"];
+    const triggerEvent = isJobTriggerEvent(rawTriggerEvent) ? rawTriggerEvent : undefined;
+    const jobContext = {
+        defer: createJobDefer(jobName, bullJob, token),
+        ...scope.context,
+        db: jobDb ?? missingDbProxy(jobName),
+        files,
+        derivatives,
+        ...(notify !== undefined && { notify }),
+        ...(config !== undefined && { config }),
+        ...(systemDb && { systemDb }),
+        ...(crossTenantReads && { crossTenantReads }),
+        // The runner owns the registry it resolved this job from — expose it so
+        // workers can reach projections/jobs without the app author duplicating
+        // it into `context` (the JobContext contract guarantees `registry`).
+        registry: scope.registry,
+        // Expose the runner so handlers can chain a follow-up job. Symmetric with
+        // how the command-dispatcher hands write-handlers their jobRunner.
+        ...(selfRunner !== undefined && { jobRunner: selfRunner }),
+        systemUser,
+        triggeredBy: triggeredById !== null ? { id: triggeredById, tenantId } : null,
+        attempt,
+        finalAttempt,
+        log: createJobLogger(input.logs),
+        metricsFor: createMetricsForFactory(scope.context.meter),
+        ...(triggerName !== undefined && { triggerName }),
+        ...(triggerEvent !== undefined && { triggerEvent }),
+        ...dispatchFacets,
+    };
+    return { jobContext, config };
+}
+export function prepareJobRun(scope, jobDef, bullJob, token) {
+    const jobName = bullJob.name;
+    const jobId = bullJob.id ?? "unknown";
+    const startTime = Date.now();
+    const logs = [];
+    // Extract meta from job data. `attempt` is BullMQ's own counter
+    // (1-based on the first run, incremented on each retry) — threading
+    // it through lets the logger tag the run-started event with the
+    // retry number, so audit queries distinguish fresh from retry runs
+    // without peeking at BullMQ internals.
+    const rawData = bullJob.data;
+    const attempt = attemptNumberOf(bullJob);
+    // Build handler payload (without internal meta fields)
+    const payload = handlerPayloadOf(rawData);
+    // Determine tenantId and triggeredBy from meta
+    const tenantId = tenantIdOfJobData(rawData);
+    const triggeredById = rawData["_triggeredById"] ?? null; // @cast-boundary dynamic-key
+    const subjects = resolveTenantVisibleSubjects(jobName, jobDef, payload);
+    const finalAttempt = isFinalAttempt(bullJob, jobDef);
+    const { writeOrigin, writeOriginInvalid } = parseJobWriteOrigin(rawData, jobName);
+    const meta = {
+        triggeredById: rawData["_triggeredById"], // @cast-boundary dynamic-key
+        payload: rawData["_payload"], // @cast-boundary dynamic-key
+        attempt,
+        ...(jobDef.tenantVisibleRun &&
+            !subjects.configError && {
+            tenantVisibleRun: { tenantId, subject: subjects.runSubject },
+        }),
+    };
+    const { jobContext, config } = buildJobContext(scope, {
+        jobName,
+        jobDef,
+        bullJob,
+        token,
+        rawData,
+        tenantId,
+        triggeredById,
+        writeOrigin,
+        attempt,
+        finalAttempt,
+        logs,
+    });
+    return {
+        jobName,
+        jobDef,
+        jobId,
+        startTime,
+        logs,
+        rawData,
+        attempt,
+        finalAttempt,
+        meta,
+        payload,
+        tenantId,
+        triggeredById,
+        subjects,
+        writeOrigin,
+        writeOriginInvalid,
+        config,
+        jobContext,
+    };
+}

package/dist/jobs/job-runner-execution.d.ts

@@ -0,0 +1,7 @@
+/// <reference types="temporal-polyfill/global" preserve="true" />
+import type { JobDeferral } from "../engine/types/index.ts";
+import type { JobRun } from "./job-runner-context.ts";
+import { type JobRunnerScope } from "./job-runner-scope.ts";
+import type { JobInvocation } from "./job-runner-types.ts";
+export declare function executeJobInSpan(scope: JobRunnerScope, run: JobRun): Promise<JobDeferral | undefined>;
+export declare function applyHandlerDeferral(scope: JobRunnerScope, run: JobRun, bullJob: JobInvocation, deferral: JobDeferral | undefined, token: string | undefined): Promise<"deferred" | "not-deferred">;

package/dist/jobs/job-runner-execution.js

@@ -0,0 +1,160 @@
+/// <reference types="temporal-polyfill/global" preserve="true" />
+import { UnrecoverableError } from "bullmq";
+import { requestContext } from "../api/request-context.js";
+import { qnScope } from "../engine/qualified-name.js";
+import { InternalError } from "../errors/index.js";
+import { scrubLogText } from "../logging/index.js";
+import { emitJobLastSuccess, withEscapeHatchAuditScope } from "../observability/index.js";
+import { DEFAULT_MAX_DEFERS, HANDLER_DEFER_COUNT_KEY, isJobDeferral, priorDeferCountOf, readTraceContext, resolveJobTz, tenantFailureMessageKey, } from "./job-runner-helpers.js";
+import { laneForJob, logFailedAttempt } from "./job-runner-scope.js";
+function buildOutcomeMeta(run, messageKey, unrecoverable = false) {
+    const { jobDef, subjects } = run;
+    return {
+        tenantId: run.tenantId,
+        // BullMQ never retries an UnrecoverableError, whatever attempts are left.
+        finalAttempt: run.finalAttempt || unrecoverable,
+        ...(jobDef.tenantVisibleFailure &&
+            !subjects.configError && {
+            tenantVisible: { subject: subjects.failureSubject, messageKey },
+        }),
+        ...(jobDef.tenantVisibleRun &&
+            !subjects.configError && { tenantVisibleRun: { subject: subjects.runSubject } }),
+    };
+}
+async function runJobHandler(scope, run, correlation) {
+    if (run.subjects.configError) {
+        // Retrying cannot fix a declaration error.
+        throw new UnrecoverableError(run.subjects.configError.message);
+    }
+    if (run.writeOriginInvalid) {
+        throw new InternalError({
+            message: `Job "${run.jobName}" received an unparseable _writeOrigin — refusing to run without ` +
+                "a trustworthy anonymous-root gate.",
+        });
+    }
+    return requestContext.run({
+        requestId: correlation.requestId,
+        correlationId: correlation.correlationId,
+        // Events a job writes carry the job as their origin.
+        handler: run.jobName,
+        feature: scope.registry.getJobFeature(run.jobName) ?? qnScope(run.jobName),
+        writeOrigin: run.writeOrigin,
+        tenantId: run.tenantId,
+        ...(run.triggeredById !== null && { userId: run.triggeredById }),
+    }, async () => run.jobDef.handler(run.payload, {
+        ...run.jobContext,
+        tz: await resolveJobTz(run.config, scope.context, scope.errorLogger),
+    }));
+}
+function assertDeferBudget(run) {
+    const maxDefers = run.jobDef.maxDefers ?? DEFAULT_MAX_DEFERS;
+    if (priorDeferCountOf(run.rawData, HANDLER_DEFER_COUNT_KEY) >= maxDefers) {
+        // The counter never resets, so a retry would hit the cap again.
+        throw new UnrecoverableError(`Job "${run.jobName}" was deferred ${maxDefers} times (maxDefers); giving up.`);
+    }
+}
+async function recordJobSuccess(scope, run) {
+    // Stamped before the observer hook: a throwing onJobComplete must not
+    // make a run that actually succeeded look dead to the liveness alert.
+    if (scope.context.meter) {
+        try {
+            emitJobLastSuccess(scope.context.meter, run.jobName);
+        }
+        catch (err) {
+            scope.errorLogger.warn("job last-success metric failed", {
+                job: run.jobName,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    const duration = Date.now() - run.startTime;
+    await scope.options.onJobComplete?.(run.jobName, run.jobId, duration, run.logs, buildOutcomeMeta(run, null));
+}
+async function recordJobFailure(scope, run, err) {
+    const errorMsg = err instanceof Error ? err.message : String(err);
+    run.logs.push({ level: "error", message: errorMsg, timestamp: Temporal.Now.instant() });
+    logFailedAttempt(scope, {
+        job: run.jobName,
+        jobId: run.jobId,
+        attempt: run.attempt,
+        finalAttempt: run.finalAttempt,
+        err,
+    });
+    await scope.options.onJobFailed?.(run.jobName, run.jobId, errorMsg, run.logs, buildOutcomeMeta(run, tenantFailureMessageKey(err, run.jobDef.tenantVisibleFailure), err instanceof UnrecoverableError));
+}
+async function runAndRecordJob(scope, run, correlation) {
+    try {
+        const handlerResult = await runJobHandler(scope, run, correlation);
+        if (isJobDeferral(handlerResult)) {
+            assertDeferBudget(run);
+            // skip: the deferral is applied after the span closes
+            return handlerResult;
+        }
+        await recordJobSuccess(scope, run);
+        return undefined;
+    }
+    catch (err) {
+        await recordJobFailure(scope, run, err);
+        throw err;
+    }
+}
+export async function executeJobInSpan(scope, run) {
+    // Cross-process trace continuation: if the enqueuing code captured a
+    // parent span, start the job.execute span as its child. Works for event
+    // and manual triggers; cron jobs start a fresh root span.
+    const parentContext = readTraceContext(run.rawData);
+    // Correlation propagation: the scheduling request's correlationId was
+    // packed into _correlationId at dispatch time. Re-enter requestContext.run
+    // so event writes during this job stamp the same correlation as the
+    // request that scheduled it. Cron/boot jobs (no scheduler) start fresh
+    // — correlationId = new requestId, no parent causation.
+    const inheritedCorrelationId = run.rawData["_correlationId"] ?? undefined; // @cast-boundary dynamic-key
+    const requestId = requestContext.generateId();
+    const correlationId = inheritedCorrelationId ?? requestId;
+    // Unified span creation: withSpan handles start/end + status/exception
+    // recording identically for both parent-context and no-parent paths.
+    // When parentContext is set, the new parent-aware StartSpanOptions
+    // plumbs it through to startSpan — no manual try/finally needed.
+    return withEscapeHatchAuditScope(() => scope.tracer.withSpan("job.execute", {
+        attributes: {
+            "job.name": run.jobName,
+            "job.id": run.jobId,
+            "job.attempt": run.attempt,
+            "kumiko.tenant_id": run.tenantId,
+            // Lane-routing attributes. `run_in` is the job's
+            // declared lane (explicit or default-"worker"); `consumer_lane`
+            // is which runner actually executed it. They diverge in
+            // all-in-one (both lanes live in one process) but must match
+            // in split deploys — a mismatch in prod logs signals a
+            // misrouted job that slipped past the boot-validator.
+            "kumiko.job.run_in": laneForJob(run.jobDef),
+            // Omit attribute entirely when no consumer (enqueuer-only runner) —
+            // SpanAttributeValue doesn't accept undefined.
+            ...(scope.consumerLane !== undefined
+                ? { "kumiko.job.consumer_lane": scope.consumerLane }
+                : {}),
+        },
+        ...(parentContext ? { parent: parentContext } : {}),
+    }, () => runAndRecordJob(scope, run, { requestId, correlationId })));
+}
+export async function applyHandlerDeferral(scope, run, bullJob, deferral, token) {
+    if (!deferral || token === undefined || !bullJob.moveToDelayed)
+        return "not-deferred";
+    // Run-log bookkeeping must not turn a defer into a failure.
+    try {
+        await scope.options.onJobDeferred?.(run.jobName, run.jobId, run.meta);
+    }
+    catch (err) {
+        scope.errorLogger.warn("job deferred hook failed", {
+            job: run.jobName,
+            jobId: run.jobId,
+            error: scrubLogText(err instanceof Error ? err.message : String(err)),
+        });
+    }
+    await bullJob.updateData?.({
+        ...bullJob.data,
+        [HANDLER_DEFER_COUNT_KEY]: priorDeferCountOf(bullJob.data, HANDLER_DEFER_COUNT_KEY) + 1,
+    });
+    await bullJob.moveToDelayed(Date.now() + deferral.delayMs, token);
+    return "deferred";
+}

package/dist/jobs/job-runner-gates.d.ts

@@ -0,0 +1,19 @@
+/// <reference types="temporal-polyfill/global" preserve="true" />
+import type { JobDefinition } from "../engine/types/index.ts";
+import { type JobRun } from "./job-runner-context.ts";
+import { type JobRunnerScope } from "./job-runner-scope.ts";
+import type { JobInvocation } from "./job-runner-types.ts";
+export declare const PER_TENANT_PREFIX = "_perTenant:";
+export declare function perTenantTargetOf(jobName: string): string | undefined;
+export declare function fanOutPerTenantJob(scope: JobRunnerScope, bullJob: JobInvocation, actualName: string): Promise<void>;
+export declare function startJobRun(scope: JobRunnerScope, jobDef: JobDefinition, bullJob: JobInvocation, token: string | undefined): Promise<JobRun>;
+export declare function resolveJobDefinitionOrFail(scope: JobRunnerScope, bullJob: JobInvocation): Promise<JobDefinition>;
+export declare function deferOverTenantLimit(scope: JobRunnerScope, jobDef: JobDefinition, bullJob: JobInvocation, token: string | undefined): Promise<"deferred" | "run">;
+export type SequentialSlot = {
+    readonly kind: "run";
+    readonly lockToken: string | null;
+} | {
+    readonly kind: "requeued";
+};
+export declare function claimSequentialSlot(scope: JobRunnerScope, jobDef: JobDefinition, bullJob: JobInvocation): Promise<SequentialSlot>;
+export declare function releaseSequentialSlot(scope: JobRunnerScope, jobName: string, lockToken: string | null): Promise<void>;