@cosmicdrift/kumiko-framework 0.365.0 → 0.366.0

package/dist/jobs/job-runner.js

@@ -1,6 +1,7 @@
+/// <reference types="temporal-polyfill/global" preserve="true" />
 import { escapeHatchFor } from "@cosmicdrift/kumiko-types/handlers";
 import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
-import { Queue, UnrecoverableError, Worker } from "bullmq";
+import { DelayedError, Queue, UnrecoverableError, Worker } from "bullmq";
 import { Redis } from "ioredis";
 import { requestContext } from "../api/request-context.js";
 import { createTenantDb, createUncheckedSystemDb } from "../db/tenant-db.js";
@@ -16,9 +17,12 @@ import { createEscapeHatchProcessDedup, createEscapeHatchReporter, createEscapeH
 import { createDistributedLock } from "../pipeline/distributed-lock.js";
 import { RedisKeys } from "../pipeline/redis-keys.js";
 import { createGatedIdentitySwitch } from "../pipeline/system-identity-switch.js";
+import { TENANT_TIMEZONE_CONFIG_KEY } from "../pipeline/tenant-timezone-config-key.js";
 import { buildPersonalDataGate, isPersonalDataGated, parseWriteOrigin, } from "../pipeline/write-origin.js";
 import { bridgeStub } from "../testing/handler-context.js";
+import { createTzContext, isValidIanaTimeZone } from "../time/index.js";
 import { cronRepeatOptions } from "./cron-repeat-options.js";
+import { resolveMaxPerTenant } from "./max-per-tenant.js";
 // Shape-checked after the BullMQ/Redis JSON round-trip. Unlike `_writeOrigin`
 // (a security-relevant escape hatch that must fail the run closed), a
 // malformed `_triggerEvent` only costs an idempotency-key convenience — the
@@ -200,6 +204,14 @@ function jobSubjectKey(jobName, payload, fields, declaration) {
     }
     return serializeJobSubject(subject);
 }
+async function resolveJobTz(config, context) {
+    const tenantTz = config ? await config(TENANT_TIMEZONE_CONFIG_KEY) : undefined;
+    return createTzContext({
+        ...(context.geoTzProvider !== undefined && { geoTz: context.geoTzProvider }),
+        ...(context.clock !== undefined && { clock: context.clock }),
+        tenant: typeof tenantTz === "string" && isValidIanaTimeZone(tenantTz) ? tenantTz : "UTC",
+    });
+}
 // Jobs that never touch ctx.db run fine on a runner built without one; a job
 // that does gets a named error instead of a bare TypeError on undefined.
 function missingDbProxy(jobName) {
@@ -248,6 +260,9 @@ function tenantFailureMessageKey(err, declaration) {
 // Leading underscore matches the existing internal-meta convention
 // (_triggeredById, _tenantId, _payload).
 const TRACE_CONTEXT_KEY = "_traceContext";
+const DEFER_COUNT_KEY = "_deferCount";
+const DEFER_DELAY_CAP_MS = 30_000;
+const DEFER_BACKOFF_MAX_DOUBLINGS = 5;
 function readTraceContext(data) {
     const raw = data[TRACE_CONTEXT_KEY];
     if (!raw || typeof raw !== "object")
@@ -555,18 +570,23 @@ export function createJobRunner(options) {
     // lane (jobDef.runIn is static), but walking both is cheap and avoids
     // a subtle bug if someone ever reassigns a job to a different lane
     // between deploys while old queue contents are still draining.
-    async function isOverPerTenantLimit(jobName, tenantId, max) {
+    // `activeOnly` + `self` serve the defer check, which runs inside the job being
+    // counted: it must not see waiting jobs or itself, and only counts jobs that
+    // became active before it. Without that order, workers that fetch a burst of
+    // jobs together all see each other as active and all defer, again and again.
+    async function isOverPerTenantLimit(jobName, tenantId, max, scope = {}) {
         const results = await Promise.all([
             queues.api.getActive(),
-            queues.api.getWaiting(),
             queues.worker.getActive(),
-            queues.worker.getWaiting(),
+            ...(scope.activeOnly ? [] : [queues.api.getWaiting(), queues.worker.getWaiting()]),
         ]);
         let count = 0;
         for (const list of results) {
             for (const j of list) {
                 if (j.name !== jobName)
                     continue;
+                if (scope.self && !isActiveBefore(j, scope.self))
+                    continue;
                 const t = j.data?._tenantId; // @cast-boundary dynamic-key
                 if (t === tenantId) {
                     count += 1;
@@ -577,6 +597,22 @@ export function createJobRunner(options) {
         }
         return false;
     }
+    function isActiveBefore(other, self) {
+        if (other.id === self.id)
+            return false;
+        if (self.processedOn === undefined)
+            return true;
+        const otherProcessedOn = other.processedOn ?? 0;
+        if (otherProcessedOn !== self.processedOn)
+            return otherProcessedOn < self.processedOn;
+        return (other.id ?? "") < (self.id ?? "");
+    }
+    // Growing delay bounds Redis and worker load while one tenant has a large
+    // backlog: every deferred job would otherwise be re-checked every deferMs.
+    function deferDelayMs(deferMs, deferCount) {
+        const grown = Math.min(deferMs * 2 ** Math.min(deferCount, DEFER_BACKOFF_MAX_DOUBLINGS), DEFER_DELAY_CAP_MS);
+        return grown + Math.floor(Math.random() * deferMs);
+    }
     // Only err.message, never payload or the logs array: job payloads can carry PII.
     function logFailedAttempt(entry) {
         errorLogger.error("job failed", {
@@ -647,7 +683,7 @@ export function createJobRunner(options) {
             });
         }
     }
-    async function handleJob(bullJob) {
+    async function handleJob(bullJob, token) {
         const rawName = bullJob.name;
         // Handle perTenant dispatch jobs — fan out to one job per tenant. The
         // fan-out re-enqueues into the lane the actual job is assigned to;
@@ -729,6 +765,25 @@ export function createJobRunner(options) {
             await reportPreRunFailure(jobName, bullJob, err);
             throw err;
         }
+        // maxPerTenant defer: checked before anything is recorded for this run, so a
+        // deferred pickup leaves no span, run-log entry or failure trace and does not
+        // consume an attempt (moveToDelayed + DelayedError, not a retry).
+        const maxPerTenant = resolveMaxPerTenant(jobDef);
+        const deferTenantId = bullJob.data["_tenantId"];
+        if (maxPerTenant?.onLimit === "defer" &&
+            typeof deferTenantId === "string" &&
+            token !== undefined &&
+            bullJob.moveToDelayed &&
+            (await isOverPerTenantLimit(jobName, deferTenantId, maxPerTenant.limit, {
+                activeOnly: true,
+                self: { id: bullJob.id, processedOn: bullJob.processedOn },
+            }))) {
+            const priorDeferCount = bullJob.data[DEFER_COUNT_KEY];
+            const deferCount = typeof priorDeferCount === "number" ? priorDeferCount : 0;
+            await bullJob.updateData?.({ ...bullJob.data, [DEFER_COUNT_KEY]: deferCount + 1 });
+            await bullJob.moveToDelayed(Date.now() + deferDelayMs(maxPerTenant.deferMs, deferCount), token);
+            throw new DelayedError();
+        }
         // Sequential gate: try to claim the per-name lock. If another worker
         // (or this worker on a different bullJob) holds it, re-enqueue with a
         // small delay and exit *successfully* — using throw would burn the
@@ -940,7 +995,7 @@ export function createJobRunner(options) {
                 return dispatchWriteRef.write(user, qn, payload, jobOrigin);
             },
         }, { reason: identitySwitchGrantReason, report: reportEscapeHatch });
-        const jobContext = {
+        const jobContextWithoutTz = {
             ...context,
             db: jobDb ?? missingDbProxy(jobName),
             files,
@@ -1016,7 +1071,10 @@ export function createJobRunner(options) {
                     handler: jobName,
                     feature: registry.getJobFeature(jobName) ?? qnScope(jobName),
                     writeOrigin: jobOrigin,
-                }, () => jobDef.handler(payload, jobContext));
+                }, async () => jobDef.handler(payload, {
+                    ...jobContextWithoutTz,
+                    tz: await resolveJobTz(config, context),
+                }));
                 // Stamped before the observer hook: a throwing onJobComplete must not
                 // make a run that actually succeeded look dead to the liveness alert.
                 if (context.meter) {
@@ -1202,7 +1260,7 @@ export function createJobRunner(options) {
                 return;
             }
             const consumerQueue = queues[consumerLane];
-            worker = new Worker(queueNameFor(queueNamePrefix, consumerLane), handleJob, {
+            worker = new Worker(queueNameFor(queueNamePrefix, consumerLane), (job, token) => handleJob(job, token), {
                 connection: redisOpts,
                 concurrency: 5,
                 // Not consuming until the boot gates passed: a job already queued from a
@@ -1361,10 +1419,11 @@ export function createJobRunner(options) {
             // against; without it the guard is inactive (system jobs, ambient
             // dispatch). Fan-out children of perTenant jobs land here on their
             // recursive queue.add and DO carry _tenantId.
-            if (jobDef.maxPerTenant !== undefined) {
+            const maxPerTenant = resolveMaxPerTenant(jobDef);
+            if (maxPerTenant?.onLimit === "skip") {
                 const tenantId = payload?._tenantId; // @cast-boundary dynamic-key
                 if (tenantId !== undefined &&
-                    (await isOverPerTenantLimit(jobName, tenantId, jobDef.maxPerTenant))) {
+                    (await isOverPerTenantLimit(jobName, tenantId, maxPerTenant.limit))) {
                     return "skipped:max-per-tenant";
                 }
             }
@@ -1406,6 +1465,8 @@ export function createJobRunner(options) {
                 bullOpts["timeout"] = jobDef.timeout;
             if (meta?.priority !== undefined)
                 bullOpts["priority"] = meta.priority;
+            if (meta?.jobId !== undefined)
+                bullOpts["jobId"] = meta.jobId;
             // Pack meta into job data with _ prefix
             const data = { ...payload };
             if (meta?.triggeredById !== undefined)
@@ -1467,8 +1528,9 @@ export function createJobRunner(options) {
                     data["_correlationId"] = reqCtx.correlationId;
                 // Same maxPerTenant guard as dispatch — events that fan into many
                 // jobs must respect the per-tenant cap or the limit is one-sided.
-                if (jobDef.maxPerTenant !== undefined && user?.tenantId !== undefined) {
-                    if (await isOverPerTenantLimit(name, String(user.tenantId), jobDef.maxPerTenant)) {
+                const maxPerTenant = resolveMaxPerTenant(jobDef);
+                if (maxPerTenant?.onLimit === "skip" && user?.tenantId !== undefined) {
+                    if (await isOverPerTenantLimit(name, String(user.tenantId), maxPerTenant.limit)) {
                         continue;
                     }
                 }
@@ -1485,17 +1547,21 @@ export function createJobRunner(options) {
         async countPendingJobs() {
             let total = 0;
             for (const queue of Object.values(queues)) {
-                const counts = await queue.getJobCounts("waiting", "active", "prioritized", "waiting-children");
+                // One getJobCounts call is a single atomic snapshot. Reading delayed in a
+                // second call misses a deferred job that cycles delayed -> active between
+                // the reads, so delayed is counted here and only repeat schedulers (which
+                // stay delayed between cron fires) are subtracted afterwards.
+                const counts = await queue.getJobCounts("waiting", "active", "prioritized", "waiting-children", "delayed");
                 total +=
                     (counts["waiting"] ?? 0) +
                         (counts["active"] ?? 0) +
                         (counts["prioritized"] ?? 0) +
-                        (counts["waiting-children"] ?? 0);
-                // getJobCounts has no id-prefix filter for "delayed" — getJobs(["delayed"])
-                // loads the full Job objects (payload included) just to read .id; fine for
+                        (counts["waiting-children"] ?? 0) +
+                        (counts["delayed"] ?? 0);
+                // getJobs(["delayed"]) loads full Job objects just to read .id; fine for
                 // test-draining's low volume, not a pattern for a prod-path hot loop.
                 const delayed = await queue.getJobs(["delayed"]);
-                total += delayed.filter((job) => !(job.id ?? "").startsWith("repeat:")).length;
+                total -= delayed.filter((job) => (job.id ?? "").startsWith("repeat:")).length;
             }
             return total;
         },

package/dist/jobs/max-per-tenant.d.ts

@@ -0,0 +1,8 @@
+import type { JobDefinition } from "../engine/types/index.js";
+export declare const DEFAULT_MAX_PER_TENANT_DEFER_MS = 1000;
+export type ResolvedMaxPerTenant = {
+    readonly limit: number;
+    readonly onLimit: "skip" | "defer";
+    readonly deferMs: number;
+};
+export declare function resolveMaxPerTenant(jobDef: Pick<JobDefinition, "maxPerTenant">): ResolvedMaxPerTenant | undefined;

package/dist/jobs/max-per-tenant.js

@@ -0,0 +1,14 @@
+export const DEFAULT_MAX_PER_TENANT_DEFER_MS = 1_000;
+export function resolveMaxPerTenant(jobDef) {
+    const raw = jobDef.maxPerTenant;
+    if (raw === undefined)
+        return undefined;
+    if (typeof raw === "number") {
+        return { limit: raw, onLimit: "skip", deferMs: DEFAULT_MAX_PER_TENANT_DEFER_MS };
+    }
+    return {
+        limit: raw.limit,
+        onLimit: raw.onLimit,
+        deferMs: raw.deferMs ?? DEFAULT_MAX_PER_TENANT_DEFER_MS,
+    };
+}

package/dist/pipeline/dispatch-query.js

@@ -66,7 +66,7 @@ async function runQueryHandler(ctx, type, handler, payload, includeDeleted, user
     // below only knows the entity's stammfields).
     //
     // Two firing-pfade kombiniert in dieser Reihenfolge:
-    //   1. Handler-keyed hooks via r.hook("postQuery", "ns:query:list", fn)
+    //   1. Handler-keyed hooks via r.hook({ type: "postQuery", target: "ns:query:list", handler })
     //      — feuern nur für genau diesen handler
     //   2. Entity-keyed hooks via r.entityHook("postQuery", "property", fn)
     //      — feuern für ALLE query-handlers des entity

package/dist/pipeline/dispatch-shared.d.ts

@@ -12,9 +12,10 @@ import { type AfterCommitHook } from "./dispatcher-utils.js";
 import type { IdempotencyGuard } from "./idempotency.js";
 import type { LifecycleHooks } from "./lifecycle-pipeline.js";
 import type { TenantTimezoneCache } from "./tenant-timezone-cache.js";
+import { TENANT_TIMEZONE_CONFIG_KEY } from "./tenant-timezone-config-key.js";
 import { type WriteOrigin } from "./write-origin.js";
 export type { WriteOrigin } from "./write-origin.js";
-export declare const TENANT_TIMEZONE_CONFIG_KEY = "tenant:config:timezone";
+export { TENANT_TIMEZONE_CONFIG_KEY };
 export declare const CONFIG_WRITE_SET_TYPE = "config:write:set";
 export declare const CONFIG_WRITE_RESET_TYPE = "config:write:reset";
 export type BatchCommand = {

package/dist/pipeline/dispatch-shared.js

@@ -29,13 +29,9 @@ import { dispatcherSpanAttributes, isFailedWriteResult, NestedWriteRollback, } f
 import { createMemberReaderFn } from "./member-reader.js";
 import { createDeferringNotify } from "./notify-scope.js";
 import { createGatedIdentitySwitch, createGatedMemberReader, createGatedProjectionReader, isSystemIdentity, systemIdentitySwitchDenied, } from "./system-identity-switch.js";
+import { TENANT_TIMEZONE_CONFIG_KEY } from "./tenant-timezone-config-key.js";
 import { buildPersonalDataGate, rootWriteOrigin } from "./write-origin.js";
-// Framework/pipeline stays bundled-features-free, so this can't import the
-// `tenant` feature — the literal below IS the coupling to its `timezone`
-// config key. Renaming that key (or the "tenant" feature name) must update
-// this constant too; tenant-timezone-boot.integration.test.ts boots the real
-// createTenantFeature() and would catch a drift.
-export const TENANT_TIMEZONE_CONFIG_KEY = "tenant:config:timezone";
+export { TENANT_TIMEZONE_CONFIG_KEY };
 // Same bundled-features-free constraint as above — these name the config
 // feature's write handlers so dispatch-write.ts can invalidate
 // TENANT_TIMEZONE_CONFIG_KEY's cache entry on a successful write without
@@ -826,6 +822,7 @@ readOnlyForTenant = false) {
     const safeUserTz = user.timezone !== undefined && isValidIanaTimeZone(user.timezone) ? user.timezone : undefined;
     const tz = createTzContext({
         ...(context.geoTzProvider !== undefined ? { geoTz: context.geoTzProvider } : {}),
+        ...(context.clock !== undefined ? { clock: context.clock } : {}),
         tenant: safeTenantTz,
         ...(safeUserTz !== undefined && { user: safeUserTz }),
     });

package/dist/pipeline/index.d.ts

@@ -31,6 +31,8 @@ export type { LifecycleHooks, SystemHookDef, SystemHooks } from "./lifecycle-pip
 export { createLifecycleHooks } from "./lifecycle-pipeline.js";
 export type { MspRebuildDeps } from "./msp-rebuild.js";
 export { rebuildMultiStreamProjection } from "./msp-rebuild.js";
+export type { MultiStreamApplyContext, MultiStreamApplyContextDeps, } from "./multi-stream-apply-context.js";
+export { createMultiStreamApplyContext } from "./multi-stream-apply-context.js";
 export { assertNotifyTargetsOwnTenant, createDeferringNotify } from "./notify-scope.js";
 export type { ProjectionProgress, RebuildResult } from "./projection-rebuild.js";
 export { getAllProjectionProgress, getProjectionState, listProjectionsWithState, rebuildProjection, } from "./projection-rebuild.js";

package/dist/pipeline/index.js

@@ -16,6 +16,7 @@ export { createIdempotencyGuard } from "./idempotency.js";
 export { assertInstructionFieldWriteAllowed, assertIrreversibleOperationAllowed, isIrreversibleEntityVerb, } from "./irreversible-operation-gate.js";
 export { createLifecycleHooks } from "./lifecycle-pipeline.js";
 export { rebuildMultiStreamProjection } from "./msp-rebuild.js";
+export { createMultiStreamApplyContext } from "./multi-stream-apply-context.js";
 export { assertNotifyTargetsOwnTenant, createDeferringNotify } from "./notify-scope.js";
 export { getAllProjectionProgress, getProjectionState, listProjectionsWithState, rebuildProjection, } from "./projection-rebuild.js";
 export { createProjectionStateTable, ProjectionStatuses, projectionStateTable, } from "./projection-state.js";

package/dist/pipeline/multi-stream-apply-context.d.ts

@@ -14,5 +14,6 @@ export type MultiStreamApplyContextDeps = {
     readonly files?: FileContext;
     readonly derivatives?: DerivativesContext;
     readonly secrets?: SecretsContext;
+    readonly jobs?: MultiStreamApplyContext["jobs"];
 };
 export declare function createMultiStreamApplyContext(deps: MultiStreamApplyContextDeps): MultiStreamApplyContext;

package/dist/pipeline/multi-stream-apply-context.js

@@ -7,6 +7,7 @@ export function createMultiStreamApplyContext(deps) {
         ...(deps.files ? { files: deps.files } : {}),
         ...(deps.derivatives ? { derivatives: deps.derivatives } : {}),
         ...(deps.secrets ? { secrets: deps.secrets } : {}),
+        ...(deps.jobs ? { jobs: deps.jobs } : {}),
         appendEvent: (async (args) => {
             await appendDomainEventCore({
                 registry: deps.registry,

package/dist/pipeline/tenant-timezone-config-key.d.ts

@@ -0,0 +1 @@
+export declare const TENANT_TIMEZONE_CONFIG_KEY = "tenant:config:timezone";

package/dist/pipeline/tenant-timezone-config-key.js

@@ -0,0 +1,6 @@
+// Framework/pipeline stays bundled-features-free, so this can't import the
+// `tenant` feature — the literal below IS the coupling to its `timezone`
+// config key. Renaming that key (or the "tenant" feature name) must update
+// this constant too; tenant-timezone-boot.integration.test.ts boots the real
+// createTenantFeature() and would catch a drift.
+export const TENANT_TIMEZONE_CONFIG_KEY = "tenant:config:timezone";

package/dist/testing/index.d.ts

@@ -13,6 +13,7 @@ export { describeFileProviderContract } from "./file-provider-contract.js";
 export { bridgeStub } from "./handler-context.js";
 export { getSetCookieRaw, getSetCookies, getSetCookieValue, type ParsedSetCookie, } from "./http-cookies.js";
 export { createLateBoundHolder, type LateBoundHolder } from "./late-bound.js";
+export { createManualClock, type ManualClock } from "./manual-clock.js";
 export { buildMultipartBody, patchFileInstanceofForBunTest } from "./multipart-helper.js";
 export { createMutableMasterKeyProvider, createTestEnvelopeCipher, createTestMasterKeyProvider, type MutableMasterKeyProvider, } from "./mutable-master-key-provider.js";
 export { createRecordingProvider, type RecordingProvider, } from "./observability-recorder.js";

package/dist/testing/index.js

@@ -21,6 +21,7 @@ export { describeFileProviderContract } from "./file-provider-contract.js";
 export { bridgeStub } from "./handler-context.js";
 export { getSetCookieRaw, getSetCookies, getSetCookieValue, } from "./http-cookies.js";
 export { createLateBoundHolder } from "./late-bound.js";
+export { createManualClock } from "./manual-clock.js";
 export { buildMultipartBody, patchFileInstanceofForBunTest } from "./multipart-helper.js";
 export { createMutableMasterKeyProvider, createTestEnvelopeCipher, createTestMasterKeyProvider, } from "./mutable-master-key-provider.js";
 export { createRecordingProvider, } from "./observability-recorder.js";

package/dist/testing/manual-clock.d.ts

@@ -0,0 +1,14 @@
+import type { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import type { Clock } from "@cosmicdrift/kumiko-types/tz-context";
+type ClockStep = {
+    readonly hours?: number;
+    readonly minutes?: number;
+    readonly seconds?: number;
+    readonly milliseconds?: number;
+};
+export type ManualClock = Clock & {
+    set(instant: Temporal.Instant): void;
+    advance(step: ClockStep): void;
+};
+export declare function createManualClock(start: Temporal.Instant): ManualClock;
+export {};

package/dist/testing/manual-clock.js

@@ -0,0 +1,12 @@
+export function createManualClock(start) {
+    let current = start;
+    return {
+        now: () => current,
+        set: (instant) => {
+            current = instant;
+        },
+        advance: (step) => {
+            current = current.add(step);
+        },
+    };
+}

package/dist/time/index.d.ts

@@ -3,4 +3,4 @@ export type { GeoAddress, GeoCoordinates, GeoTzProvider } from "./geo-tz.js";
 export { isValidIanaTimeZone } from "./iana.js";
 export { instantToLegacyDate, legacyDateToInstant } from "./legacy-date.js";
 export { ensureTemporalPolyfill, getTemporal } from "./polyfill.js";
-export { createTzContext, createTzContextAsync, type LocatedTimestampJson, type TzContext, type TzContextOptions, } from "./tz-context.js";
+export { type Clock, createTzContext, createTzContextAsync, type LocatedTimestampJson, type TzContext, type TzContextOptions, } from "./tz-context.js";

package/dist/time/tz-context.d.ts

@@ -1,5 +1,5 @@
 import type { TzContext, TzContextOptions } from "@cosmicdrift/kumiko-types/tz-context";
-export type { LocatedTimestampJson, TzContext, TzContextOptions, } from "@cosmicdrift/kumiko-types/tz-context";
+export type { Clock, LocatedTimestampJson, TzContext, TzContextOptions, } from "@cosmicdrift/kumiko-types/tz-context";
 /**
  * Factory: creates a TzContext for the current request.
  * Uses the kumiko-types Temporal module export (not globalThis.Temporal) so

package/dist/time/tz-context.js

@@ -19,6 +19,9 @@
 // live in @cosmicdrift/kumiko-types/tz-context — only the factories are here.
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { ensureTemporalPolyfill } from "./polyfill.js";
+const SYSTEM_CLOCK = {
+    now: () => Temporal.Now.instant(), // @wrapper-known semantic-alias
+};
 /**
  * Factory: creates a TzContext for the current request.
  * Uses the kumiko-types Temporal module export (not globalThis.Temporal) so
@@ -28,14 +31,16 @@ export function createTzContext(options = {}) {
     const tenant = options.tenant ?? "UTC";
     const user = options.user ?? tenant;
     const geoTz = options.geoTz;
+    const clock = options.clock ?? SYSTEM_CLOCK;
+    const nowIn = (tz) => clock.now().toZonedDateTimeISO(tz);
     return {
         tenant,
         user,
-        now: () => Temporal.Now.instant(), // @wrapper-known semantic-alias
-        nowIn: (tz) => Temporal.Now.zonedDateTimeISO(tz), // @wrapper-known semantic-alias
-        today: (tz) => Temporal.Now.plainDateISO(tz), // @wrapper-known semantic-alias
+        now: () => clock.now(),
+        nowIn,
+        today: (tz) => nowIn(tz).toPlainDate(),
         todayRange: (tz) => {
-            const today = Temporal.Now.plainDateISO(tz);
+            const today = nowIn(tz).toPlainDate();
             const startZdt = today.toZonedDateTime({ timeZone: tz });
             const endZdt = today.add({ days: 1 }).toZonedDateTime({ timeZone: tz });
             return { start: startZdt.toInstant(), end: endZdt.toInstant() };

package/dist/upgrade-cli.js

@@ -297,6 +297,12 @@ export function manualEntryId(version, title) {
     const hash = createHash("sha256").update(title).digest("hex").slice(0, MANUAL_ID_HASH_LENGTH);
     return `${version}:${hash}`;
 }
+// Breaking entries that need hand work carry the id `kumiko-upgrade --resolve` takes.
+function manualIdOf(entry) {
+    return entry.type === "breaking" && needsManualMigration(entry)
+        ? manualEntryId(entry.version, entry.title)
+        : undefined;
+}
 function toMarkerManual(entry) {
     return {
         id: manualEntryId(entry.version, entry.title),
@@ -739,7 +745,11 @@ export async function runUpgradeCli(argv, cwd, out, options) {
     }
     if (jsonMode) {
         const { pendingManual } = carryOf(markerRead);
-        out.log(JSON.stringify({ currentVersion, installedVersion, pending, pendingManual }, null, 2));
+        const pendingWithManualId = pending.map((entry) => {
+            const manualId = manualIdOf(entry);
+            return manualId === undefined ? entry : { ...entry, manualId };
+        });
+        out.log(JSON.stringify({ currentVersion, installedVersion, pending: pendingWithManualId, pendingManual }, null, 2));
         return 0;
     }
     const breaking = pending.filter((e) => e.type === "breaking");
@@ -759,7 +769,8 @@ export async function runUpgradeCli(argv, cwd, out, options) {
         out.log(`  ⚠ BREAKING (${breaking.length})`);
         out.log("");
         for (const e of breaking) {
-            out.log(`    ${e.version} · ${e.title}`);
+            const manualId = manualIdOf(e);
+            out.log(`    ${e.version} · ${e.title}${manualId === undefined ? "" : `  [${manualId}]`}`);
             if (verbose && e.detail) {
                 out.log(`      ${e.detail}`);
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.365.0",
+  "version": "0.366.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -210,8 +210,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.365.0",
-    "@cosmicdrift/kumiko-types": "0.365.0",
+    "@cosmicdrift/kumiko-http": "0.366.0",
+    "@cosmicdrift/kumiko-types": "0.366.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -227,7 +227,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.365.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.366.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,62 @@
 [
+  {
+    "version": "0.366.0",
+    "type": "breaking",
+    "title": "One injectable Clock for ctx.tz in handlers and jobs",
+    "detail": "New type Clock and TzContextOptions.clock. AppContext.clock feeds ctx.tz.now() in handlers, and JobContext.tz gives jobs the same ctx.tz API (tenant timezone from tenant config, read once per job run, UTC fallback). The testing helper createManualClock(start) returns a clock with set and advance. The tenant-lifecycle job now reads time through ctx.tz.now().",
+    "migration": "Code that builds a JobContext literal itself (boot seeds, test doubles) adds `tz: createTzContext()`."
+  },
+  {
+    "version": "0.366.0",
+    "type": "improvement",
+    "title": "Handler input references work on nested fields and record keys",
+    "detail": "The references meta on handler input schemas is now found on fields inside arrays, nested objects and records, and on record keys. The new readHandlerFieldReferences and handlerFieldReferences return each hit with a path such as \"channels[].channelKey\" or \"labels{key}\" plus typed path segments. Boot validation checks nested references too and names the path in its error message. readHandlerFieldReference and handlerFieldReference behave as before."
+  },
+  {
+    "version": "0.366.0",
+    "type": "breaking",
+    "title": "Registrar methods take a single object, positional calls throw at registration",
+    "detail": "r.writeHandler, r.queryHandler, r.entity, r.requires and r.hook now take one object. The positional overloads are gone from the types and throw when the feature is defined, with a message that points at the codemod. The throw is removed in the first release after 2026-10-29.\n\nwriteHandler (queryHandler is the same shape):\n  before: r.writeHandler(\"order:archive\", schema, handler, { access });\n  after:  r.writeHandler({ name: \"order:archive\", schema, handler, access });\n\nhook (type picks the handler shape, target is a name, a list or { allOf }):\n  before: r.hook(\"postSave\", \"order\", handler, { escapeHatch });\n  after:  r.hook({ type: \"postSave\", target: \"order\", handler, escapeHatch });\n\nentity and requires:\n  before: r.entity(\"order\", definition, { table: ordersTable });  r.requires(\"auth\", \"tenant\");\n  after:  r.entity({ name: \"order\", ...definition, backingTable: ordersTable });  r.requires({ features: [\"auth\", \"tenant\"] });\n\nregisterEntityCrud is no longer exported from @cosmicdrift/kumiko-framework/engine; call r.crud(name, entity, options) instead. The entity option { table } is now backingTable on the r.entity object and lands in the feature's entityTables, not in its entities. HookDefinition and EntityObjectDefinition are exported from @cosmicdrift/kumiko-types. Hook definitions are checked per type: validation takes no escapeHatch, phase only exists on postSave and postDelete, and { allOf } is not accepted on preSave.",
+    "migration": "Run `bun kumiko-upgrade --apply`. It rewrites every positional r.writeHandler, r.queryHandler, r.entity, r.requires, r.hook and registerEntityCrud call to the object form. Calls it cannot resolve statically (a spread argument, a registrar that is not typed as FeatureRegistrar) are listed as manual work with file and line; rewrite those by hand.",
+    "codemod": "scripts/codemod/object-form.ts",
+    "manualAfterCodemod": true
+  },
+  {
+    "version": "0.366.0",
+    "type": "improvement",
+    "title": "The app schema no longer lists screens, navs and workspaces of features a tenant has switched off",
+    "detail": "A feature declared with r.toggleable() that is off for the caller's tenant (tier engine or feature toggles) used to stay in the nav while all its handlers answered 403 feature_disabled. GET /api/schema now drops its screens, navs, content collections and workspaces for that tenant, and every action, redirect, nav parent and workspace member that pointed at them is removed too. Entities and translations stay. The response is cached per role set and per set of disabled features, so tenants with the same set share one ETag. Without an effectiveFeatures resolver nothing changes."
+  },
+  {
+    "version": "0.366.0",
+    "type": "improvement",
+    "title": "selectMany supports column projection via SelectOptions.fields",
+    "detail": "SelectOptions gains fields, a list of entity field names. selectMany then selects only those columns instead of all of them. An empty list or a name that is not a column of the table throws."
+  },
+  {
+    "version": "0.366.0",
+    "type": "improvement",
+    "title": "kumiko-upgrade names each pending manual step by an id",
+    "detail": "Every pending manual step of kumiko-upgrade now has a stable id, derived from the release version and the step title. The text output shows it in brackets and the JSON output carries it as manualId, so a script or an agent can tell steps apart and record which ones it has done."
+  },
+  {
+    "version": "0.365.1",
+    "type": "fix",
+    "title": "App and worker boot wait for Postgres instead of crashing",
+    "detail": "runProdApp and worker processes now probe the database before the schema-drift check and retry with exponential backoff (1s to 15s, up to 90s) on transient connection errors such as too_many_connections or ECONNREFUSED. The KMS health check at boot retries the same way. Non-transient errors like auth failures still abort immediately."
+  },
+  {
+    "version": "0.365.1",
+    "type": "fix",
+    "title": "Restoring a soft-deleted row with a money field no longer fails with a 500",
+    "detail": "restore() wrote the raw stored row (money as bigint minor units) into payload.previous, and the jsonb bind threw. It now builds previous in the same domain form as delete(), so the restored event carries { amount, currency, ... } for money fields."
+  },
+  {
+    "version": "0.365.1",
+    "type": "fix",
+    "title": "version_conflict from delete, restore, forget and update reports the actual stream version",
+    "detail": "After a lost append race, delete, restore and forget returned currentVersion -1 and update returned the version read before the race, so expectedVersion and currentVersion looked equal. They now look up the stream version after the conflict; -1 remains only when that lookup fails."
+  },
   {
     "version": "0.365.0",
     "type": "improvement",

package/src/scripts/codemod/README.md

@@ -34,3 +34,26 @@ at — fix those by hand. The report also lists every field that newly
 gains `lookupable` (searchable-only fields resolving to `find: "fuzzy"`)
 — each of those needs a `_bidx` column migration, which this script does
 not write.
+
+## object-form.ts
+
+Rewrites the positional registrar calls `r.writeHandler(name, schema, handler, options)`,
+`r.queryHandler(…)`, `r.entity(name, definition, { table })`, `r.requires("a", "b")` and
+`r.hook(type, target, fn, options?)` to their object form, and
+`registerEntityCrud(r, name, entity, options?)` to `r.crud(name, entity, options?)`
+(the now-unused import is removed). Idempotent — object-form calls are left alone.
+
+A call is only touched when its receiver is provably a feature registrar: a parameter of
+the `defineFeature(name, (r) => …)` callback, or a binding typed `FeatureRegistrar`.
+Anything else (`sessions.requires("x")`, `foo.entity(…)`) stays untouched. A call on an
+untyped `r`/`registrar` it cannot resolve, a spread argument, too few arguments or
+`entity` options other than `{ table }` are reported as `manual` instead of guessed at.
+
+```bash
+bun node_modules/@cosmicdrift/kumiko-framework/src/scripts/codemod/object-form.ts <dir> [--check | --dry-run | --write] [--no-format]
+```
+
+Runs automatically via `bun kumiko-upgrade --apply`. Without a mode flag it writes, then
+formats the changed files with the Biome binary found in `node_modules/.bin` (`--no-format`
+skips that). `--dry-run` only reports; `--check` reports and exits 1 while any rewritable
+or manual site is left.