@cosmicdrift/kumiko-framework 0.365.1 → 0.366.0

package/dist/engine/object-form.d.ts

@@ -2,3 +2,5 @@ export declare function splitNamedDefinition<T extends {
     readonly name: string;
 }>(definition: T): [string, Omit<T, "name">];
 export declare function unwrapArrayForm<K extends string>(args: readonly [Record<K, readonly string[]>] | readonly string[], key: K): readonly string[];
+export declare function isObjectArgument(value: unknown): boolean;
+export declare function throwPositionalFormRemoved(featureName: string, method: string): never;

package/dist/engine/object-form.js

@@ -1,17 +1,12 @@
-// Shared helper for registrar methods that accept an Object-Form call
-// (`r.entity({ name: "item", ... })`) alongside the classic positional form
-// (`r.entity("item", { ... })`). Object-Form is the shape the feature-ast
-// renderer emits for Designer/AI-generated code — a single object argument
-// with named fields is easier to generate correctly than positional args
-// whose count/order vary per method.
+// Shared helpers for registrar methods that take a single object argument
+// (`r.entity({ name: "item", ... })`). The positional overloads are gone; the
+// runtime check below turns a leftover positional call into a pointer at the codemod.
 export function splitNamedDefinition(definition) {
     const { name, ...rest } = definition;
     return [name, rest];
 }
-// Shared helper for registrar methods that accept either variadic strings
-// (hand-written call sites) or a single Object-Form object wrapping the
-// same string array under `key` (the feature-ast renderer's canonical
-// shape for Designer/AI-generated code).
+// `optionalRequires` and `readConfig` still accept variadic strings next to a
+// single object wrapping the same string array under `key`.
 export function unwrapArrayForm(args, key) {
     const [first] = args;
     if (typeof first === "object" && first !== null && key in first) {
@@ -19,3 +14,11 @@ export function unwrapArrayForm(args, key) {
     }
     return args;
 }
+export function isObjectArgument(value) {
+    return typeof value === "object" && value !== null;
+}
+// Removed in the first release after 2026-10-29; until then a positional call fails with
+// a pointer at the codemod instead of an obscure "undefined is not a function".
+export function throwPositionalFormRemoved(featureName, method) {
+    throw new Error(`[Feature ${featureName}] positional r.${method}(…) removed in 0.366, run \`bun kumiko-upgrade --apply\``);
+}

package/dist/engine/registry-state.js

@@ -12,7 +12,7 @@ const IMPLICIT_PROJECTION_SUFFIX = "-entity";
 // durch implicit-projection-equivalence.integration.ts).
 export function buildImplicitProjection(featureName, entityName, entity, qualify, backingTable, extensions = []) {
     const name = qualify(featureName, "projection", `${entityName}${IMPLICIT_PROJECTION_SUFFIX}`);
-    // Backing table (r.entity(name, def, { table })) is the one physical table
+    // Backing table (r.entity({ name, ...def, backingTable })) is the one physical table
     // object shared by executor-writes, rebuild-replay, test-push and
     // collectTableMetas — restoring the #255 invariant (test-push == generate).
     // Validated as a superset of the field-derived columns so a field/table
@@ -107,7 +107,7 @@ function collectExtensionSources(projectionName, entityName, extensions) {
 function resolveBackingTable(entityName, entity, backingTable) {
     const tableMeta = asEntityTableMeta(backingTable);
     if (!tableMeta) {
-        throw new Error(`r.entity("${entityName}", …, { table }): the backing table carries no ` +
+        throw new Error(`r.entity({ name: "${entityName}", …, backingTable }): the backing table carries no ` +
             "EntityTableMeta — build it via table() / buildEntityTable.");
     }
     assertBackingTableSuperset(entityName, deriveEntityTableMeta(entityName, entity), tableMeta);

package/dist/engine/registry-validate.d.ts

@@ -19,6 +19,7 @@ export declare function buildEventUpcasterChains(state: RegistryState, features:
 export declare function validateProjectionApplyKeys(state: RegistryState): void;
 export declare function validateRequiredFeatures(state: RegistryState, features: readonly FeatureDefinition[]): void;
 export declare function validateNotificationRecordMappings(state: RegistryState): void;
+export declare function validateNotificationRenamedFrom(state: RegistryState): void;
 export declare function resolveNotificationTriggersAndRegisterHooks(state: RegistryState): void;
 export declare function validateLifecycleHookTargets(state: RegistryState): void;
 export declare function validateEntityHookTargets(state: RegistryState, features: readonly FeatureDefinition[]): void;

package/dist/engine/registry-validate.js

@@ -462,7 +462,7 @@ export function validateProjectionApplyKeys(state) {
         const validEventTypes = new Set();
         // Two source-modes are legal:
         //
-        //  (a) Registered entity (r.entity(src, ...)) — the "normal" case:
+        //  (a) Registered entity (r.entity({ name: src, ... })) — the "normal" case:
         //      auto-lifecycle events `<src>.created/.updated/.deleted/.restored`
         //      fire when the event-store-executor writes, and any domain-event
         //      (r.defineEvent) appended onto an aggregate of that type is
@@ -497,7 +497,7 @@ export function validateProjectionApplyKeys(state) {
                 throw new Error(`Projection "${projName}" declares source(s) [${unregistered.join(", ")}] that are not registered entities, ` +
                     `and has no domain-event apply-keys. This is either a typo or a missing r.defineEvent registration. ` +
                     `Events-only projections need at least one apply-key from r.defineEvent; ` +
-                    `CRUD-style projections need r.entity("${unregistered[0]}", ...).`);
+                    `CRUD-style projections need r.entity({ name: "${unregistered[0]}", ... }).`);
             }
         }
         for (const applyKey of Object.keys(projDef.apply)) {
@@ -547,6 +547,25 @@ export function validateNotificationRecordMappings(state) {
         }
     }
 }
+export function validateNotificationRenamedFrom(state) {
+    const ownerByAlias = new Map();
+    for (const [qualifiedName, notifDef] of state.notificationMap) {
+        for (const alias of notifDef.renamedFrom ?? []) {
+            const where = `Notification "${qualifiedName}" renamedFrom "${alias}"`;
+            if (alias === "*") {
+                throw new Error(`${where}: "*" is the preference wildcard, not a notification name`);
+            }
+            if (state.notificationMap.has(alias)) {
+                throw new Error(`${where} is a current notification name; remove it from renamedFrom or rename the notification`);
+            }
+            const otherOwner = ownerByAlias.get(alias);
+            if (otherOwner !== undefined && otherOwner !== qualifiedName) {
+                throw new Error(`${where} is also declared by notification "${otherOwner}"; an alias can have only one owner, remove it from one of them`);
+            }
+            ownerByAlias.set(alias, qualifiedName);
+        }
+    }
+}
 export function resolveNotificationTriggersAndRegisterHooks(state) {
     // Resolve notification triggers and register postSave hooks
     // Done after all features are registered so cross-feature triggers work

package/dist/engine/registry.js

@@ -3,7 +3,7 @@ import { dedupeFeatures } from "./dedupe-features.js";
 import { buildRegistryFacade } from "./registry-facade.js";
 import { populateClaimsAndAuth, populateConfigKeys, populateEvents, populateExtensionsAndSeeds, populateFeatureCore, populateHandlers, populateHooks, populateJobsAndNotifications, populateMetricsAndSecrets, populateProjectionsAndTables, populateScreensNavWorkspaces, populateSystemEvents, populateTranslations, } from "./registry-ingest.js";
 import { createInitialState } from "./registry-state.js";
-import { applyExtensionUsages, autoWireSoftDeleteJobs, buildEntityEventUpcasterChains, buildEventUpcasterChains, buildImplicitProjections, buildIncomingRelations, buildSearchableSortableCaches, computeHasRateLimitedHandler, finalizeWorkspaceNavMembership, populateHandlerEntityMappings, publishEventPiiCatalog, resolveJobTriggers, resolveNotificationTriggersAndRegisterHooks, validateBootGates, validateEntityHookTargets, validateEventMigrationVersions, validateExtensionSelectors, validateExtensionUsageTargets, validateFieldAccessHandlersAreEntityMapped, validateJobBackoff, validateLifecycleHookTargets, validateLiveEntities, validateMaxPerTenant, validateNotificationRecordMappings, validateProjectionApplyKeys, validateRelationTargetsExist, validateRequiredFeatures, } from "./registry-validate.js";
+import { applyExtensionUsages, autoWireSoftDeleteJobs, buildEntityEventUpcasterChains, buildEventUpcasterChains, buildImplicitProjections, buildIncomingRelations, buildSearchableSortableCaches, computeHasRateLimitedHandler, finalizeWorkspaceNavMembership, populateHandlerEntityMappings, publishEventPiiCatalog, resolveJobTriggers, resolveNotificationTriggersAndRegisterHooks, validateBootGates, validateEntityHookTargets, validateEventMigrationVersions, validateExtensionSelectors, validateExtensionUsageTargets, validateFieldAccessHandlersAreEntityMapped, validateJobBackoff, validateLifecycleHookTargets, validateLiveEntities, validateMaxPerTenant, validateNotificationRecordMappings, validateNotificationRenamedFrom, validateProjectionApplyKeys, validateRelationTargetsExist, validateRequiredFeatures, } from "./registry-validate.js";
 // This is where the magic happens. By "magic" I mean: precomputed maps.
 // I build everything once at boot (hooks, relations, searchable fields, ...)
 // so nothing has to iterate over objects at runtime. O(1) instead of O(n*m).
@@ -42,6 +42,7 @@ export function createRegistry(rawFeatures) {
     validateRequiredFeatures(state, features);
     resolveNotificationTriggersAndRegisterHooks(state);
     validateNotificationRecordMappings(state);
+    validateNotificationRenamedFrom(state);
     validateLifecycleHookTargets(state);
     validateEntityHookTargets(state, features);
     resolveJobTriggers(state);

package/dist/engine/strip-disabled-features-from-app-schema.d.ts

@@ -0,0 +1,6 @@
+import type { AppSchema } from "../ui-types/app-schema.js";
+import type { EffectiveFeaturesResolver } from "./tier-resolver-extension.js";
+import type { Registry } from "./types/feature.js";
+import type { TenantId } from "./types/identifiers.js";
+export declare function resolveDisabledFeatureNames(registry: Registry, effectiveFeatures: EffectiveFeaturesResolver, tenantId: TenantId): Promise<readonly string[]>;
+export declare function stripDisabledFeaturesFromAppSchema(schema: AppSchema, registry: Registry, disabledFeatureNames: readonly string[]): AppSchema;

package/dist/engine/strip-disabled-features-from-app-schema.js

@@ -0,0 +1,89 @@
+// Tenant-level counterpart to projectAppSchemaForRoles: removes the UI surface
+// (screens, navs, content collections, workspaces) of features the tenant has
+// switched off via r.toggleable(). Entities and translations stay — enabled
+// features may still reference them. Run BEFORE the role projection: it keeps
+// only targets that exist in the schema, so once the disabled screens/navs are
+// gone it also drops every action, redirect, nav and workspace member that
+// pointed at them. The one reference it does not resolve is a nav `parent`
+// pointing at a missing nav; that is pruned here.
+import { isToggleableFeature } from "./effective-features.js";
+import { isValidQn, qualifyEntityName } from "./qualified-name.js";
+// Sorted, so the result doubles as a stable cache key. The trial gate is
+// consulted like the dispatcher's feature gate does, but only for toggleable
+// features: a trial can only unlock tier (toggleable) features, so a
+// cascade-disabled always-on feature needs no gate call.
+export async function resolveDisabledFeatureNames(registry, effectiveFeatures, tenantId) {
+    const enabled = effectiveFeatures(tenantId);
+    const disabled = [];
+    for (const [featureName, feature] of registry.features) {
+        if (enabled.has(featureName))
+            continue;
+        if (isToggleableFeature(feature) &&
+            (await effectiveFeatures.trialGate?.(tenantId, featureName))) {
+            continue;
+        }
+        disabled.push(featureName);
+    }
+    return disabled.sort();
+}
+function navParentQn(featureName, parent) {
+    return isValidQn(parent) ? parent : qualifyEntityName(featureName, "nav", parent);
+}
+// Navs of enabled features whose parent chain ends in a removed nav.
+function collectOrphanedNavQns(features, removedNavQns) {
+    const orphaned = new Set();
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const feature of features) {
+            for (const nav of feature.navs ?? []) {
+                const qn = qualifyEntityName(feature.featureName, "nav", nav.id);
+                if (removedNavQns.has(qn) || nav.parent === undefined)
+                    continue;
+                if (removedNavQns.has(navParentQn(feature.featureName, nav.parent))) {
+                    removedNavQns.add(qn);
+                    orphaned.add(qn);
+                    changed = true;
+                }
+            }
+        }
+    }
+    return orphaned;
+}
+export function stripDisabledFeaturesFromAppSchema(schema, registry, disabledFeatureNames) {
+    if (disabledFeatureNames.length === 0)
+        return schema;
+    const disabled = new Set(disabledFeatureNames);
+    const removedNavQns = new Set();
+    for (const feature of schema.features) {
+        if (!disabled.has(feature.featureName))
+            continue;
+        for (const nav of feature.navs ?? []) {
+            removedNavQns.add(qualifyEntityName(feature.featureName, "nav", nav.id));
+        }
+    }
+    const orphanedNavQns = collectOrphanedNavQns(schema.features, removedNavQns);
+    const features = schema.features.map((feature) => {
+        if (disabled.has(feature.featureName)) {
+            const { navs: _navs, contentCollections: _collections, workspaces: _ws, ...rest } = feature;
+            return { ...rest, screens: [] };
+        }
+        if (orphanedNavQns.size === 0 || feature.navs === undefined)
+            return feature;
+        const navs = feature.navs.filter((nav) => !orphanedNavQns.has(qualifyEntityName(feature.featureName, "nav", nav.id)));
+        if (navs.length === feature.navs.length)
+            return feature;
+        const { navs: _navs, ...rest } = feature;
+        return navs.length > 0 ? { ...rest, navs } : rest;
+    });
+    // Workspace definitions carry the short id the author declared; the owning
+    // feature is only known to the registry.
+    const disabledWorkspaceIds = new Set(disabledFeatureNames.flatMap((featureName) => Object.keys(registry.features.get(featureName)?.workspaces ?? {})));
+    const workspaces = schema.workspaces?.filter((ws) => !disabledWorkspaceIds.has(ws.definition.id));
+    const { workspaces: _original, ...restSchema } = schema;
+    return {
+        ...restSchema,
+        features,
+        ...(workspaces !== undefined && workspaces.length > 0 && { workspaces }),
+    };
+}

package/dist/engine/types/index.d.ts

@@ -4,7 +4,7 @@ export type { QueryHandlerDefinition, StreamHandlerDefinition, WriteHandlerDefin
 export type { EntityCrudRegistrar, EntityCrudVerb, EntityHandlerOptions, EntityQueryHandlerOptions, EntityWriteHandlerOptions, RegisterEntityCrudOptions, } from "@cosmicdrift/kumiko-types/entity-handlers";
 export type { KumikoEntityTypeMap, KumikoEventTypeMap, KumikoHandlerPayloadMap, KumikoHandlerResultMap, } from "@cosmicdrift/kumiko-types/event-type-map";
 export type { ExtensionOptionsArgs, ExtensionOptionsFor, KumikoExtensionOptionsMap, } from "@cosmicdrift/kumiko-types/extension-options-map";
-export type { BootCheckContext, BootCheckFn, FeatureDefinition, FeatureMetricDef, FeatureMetricType, FeatureRegistrar, MetricOptions, Registry, SecretKeyDefinition, SecretKeyHandle, SecretNamespaceDefinition, SecretNamespaceHandle, SecretNamespaceOptions, SecretOptions, StoreTableDef, StoreTableEntry, StoreTableOptions, UiHintOption, UiHints, } from "@cosmicdrift/kumiko-types/feature";
+export type { BootCheckContext, BootCheckFn, EntityObjectDefinition, FeatureDefinition, FeatureMetricDef, FeatureMetricType, FeatureRegistrar, HookDefinition, MetricOptions, Registry, SecretKeyDefinition, SecretKeyHandle, SecretNamespaceDefinition, SecretNamespaceHandle, SecretNamespaceOptions, SecretOptions, StoreTableDef, StoreTableEntry, StoreTableOptions, UiHintOption, UiHints, } from "@cosmicdrift/kumiko-types/feature";
 export type { FieldIconKey } from "@cosmicdrift/kumiko-types/field-icon";
 export type { AnyFileFieldDef, BigIntFieldDef, BooleanFieldDef, ClientDerivedFieldDef, DateFieldDef, DecimalFieldDef, DefaultCurrency, DeriveContext, DerivedFieldDef, DerivedFieldsMap, DerivedValueType, EmbeddedDerivedCellDef, EmbeddedFieldDef, EmbeddedSubFieldDef, EntityDefinition, EntityEventMigration, EntityIndexDef, FieldAccess, FieldDefinition, FieldsMap, FileFieldDef, FilesFieldDef, Findability, ImageFieldDef, ImagesFieldDef, JsonbFieldDef, LocatedTimestampFieldDef, LongTextFieldDef, LongTextFindability, MoneyCurrencySource, MoneyFieldDef, MultiSelectFieldDef, NumberFieldDef, OptionsQueryPayload, OptionsQueryPayloadValue, ParentRefDef, PersonalAnnotations, PersonalAnnotationsLongText, PersonalAnnotationsNoFind, PersonalSubject, ReferenceFieldDef, ResolvedPiiFlags, RetentionDef, SelectFieldDef, SelectOptionTone, TextFieldDef, TimestampFieldDef, TransitionMap, TzFieldDef, } from "@cosmicdrift/kumiko-types/fields";
 export type { AccessRule, ActiveMembership, ActiveMembershipRejection, ActiveMembershipResult, AgentExposure, AgentHandlerHints, AgentRisk, AggregateStreamHandle, AppContext, AppendEventArgs, AppendEventFn, AuthClaimsContext, AuthClaimsFn, AuthClaimsHookDef, BeforeTransactionPhase, BeforeTransactionResult, CamelToKebab, ChatSendFailureCode, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyJsType, ClaimKeyType, DeclarativeEventMigration, DeliveryErrorCode, DeliveryFailureCode, DeliverySkipReason, DispatchWriteRef, EntityRef, EscapeHatchAuditSink, EscapeHatchDeclaration, EscapeHatchKind, EscapeHatchReporter, EscapeHatchTarget, EscapeHatchUseEvent, EventDef, EventMigrationDef, EventPiiFields, EventPiiStance, EventUpcastCtx, EventUpcastFn, FetchForWritingArgs, HandlerContext, HandlerRef, JobContext, JobRunnerRef, JobTriggerEvent, MemberReader, NameOrRef, NotifyDeferred, NotifyDelivery, NotifyDeliveryStatus, NotifyDispatched, NotifyFactory, NotifyFn, NotifyJobDispatcher, NotifyOptions, NotifyPriority, NotifyResult, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, PayloadBucketNormalization, PayloadRateLimitOption, PreparedWriteEvent, QualifiedEventName, QueryEvent, QueryHandlerDef, QueryHandlerFn, RateLimitDeclaration, RateLimitDisabled, RateLimitOption, RateLimitPer, RoleAccessPersonalData, RoleAccessRule, SessionUser, SessionUserOrigin, StreamHandlerDef, StreamHandlerFn, TenantWriteTarget, TryAppendEventFn, TryAppendEventResult, UnsafeAppendEventFn, WriteEvent, WriteHandlerDef, WriteHandlerFn, WriteResult, } from "@cosmicdrift/kumiko-types/handlers";

package/dist/files/feature.js

@@ -22,7 +22,7 @@ export function createFilesFeature(options = {}) {
             category: "storage",
             recommended: false,
         });
-        r.entity(FILE_REF_ENTITY_NAME, fileRefEntity);
+        r.entity({ name: FILE_REF_ENTITY_NAME, ...fileRefEntity });
         r.writeHandler(bindReferencedFilesWrite);
         return { routeOptions: options };
     });

package/dist/jobs/job-runner.js

@@ -1,3 +1,4 @@
+/// <reference types="temporal-polyfill/global" preserve="true" />
 import { escapeHatchFor } from "@cosmicdrift/kumiko-types/handlers";
 import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import { DelayedError, Queue, UnrecoverableError, Worker } from "bullmq";
@@ -16,8 +17,10 @@ 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`
@@ -201,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) {
@@ -984,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,
@@ -1060,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) {

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/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.1",
+  "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.1",
-    "@cosmicdrift/kumiko-types": "0.365.1",
+    "@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.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.366.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,44 @@
 [
+  {
+    "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",

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.