@cosmicdrift/kumiko-framework 0.365.1 → 0.367.0

package/dist/engine/handler-field-references.js

@@ -1,7 +1,8 @@
 import * as z from "zod";
-import { zodDef, zodMeta, zodShapeField } from "../env/_zod-introspect.js";
+import { zodDef, zodMeta, zodShape, zodShapeField } from "../env/_zod-introspect.js";
 export const HANDLER_FIELD_REFERENCES_META_KEY = "references";
 const MAX_WRAPPER_DEPTH = 8;
+const MAX_NESTING_DEPTH = 8;
 const referenceMetaSchema = z.union([
     z.string().min(1),
     z.object({ entity: z.string().min(1), by: z.string().min(1).optional() }),
@@ -42,11 +43,7 @@ function isArrayField(field) {
     }
     return false;
 }
-export function readHandlerFieldReference(schema, field) {
-    const objectSchema = unwrapObjectSchema(schema);
-    const fieldSchema = objectSchema && zodShapeField(objectSchema, field);
-    if (fieldSchema === undefined)
-        return { kind: "none" };
+function readFieldReference(fieldSchema) {
     const raw = findRawReferenceMeta(fieldSchema);
     if (raw === undefined)
         return { kind: "none" };
@@ -63,6 +60,83 @@ export function readHandlerFieldReference(schema, field) {
         },
     };
 }
+export function readHandlerFieldReference(schema, field) {
+    const objectSchema = unwrapObjectSchema(schema);
+    const fieldSchema = objectSchema && zodShapeField(objectSchema, field);
+    if (fieldSchema === undefined)
+        return { kind: "none" };
+    return readFieldReference(fieldSchema);
+}
+function pathOf(segments) {
+    let path = "";
+    for (const segment of segments) {
+        if (segment.kind === "field")
+            path += path === "" ? segment.name : `.${segment.name}`;
+        else if (segment.kind === "element")
+            path += "[]";
+        else if (segment.kind === "recordKey")
+            path += "{key}";
+        else
+            path += "{}";
+    }
+    return path;
+}
+function collectAt(schema, segments, out) {
+    const reading = readFieldReference(schema);
+    if (reading.kind !== "none")
+        out.push({ path: pathOf(segments), segments, reading });
+}
+function walkNested(schema, segments, depth, out) {
+    // skip: schemas nested deeper than MAX_NESTING_DEPTH are not inspected
+    if (depth > MAX_NESTING_DEPTH)
+        return;
+    let current = schema;
+    let currentSegments = segments;
+    for (let layer = 0; layer < MAX_WRAPPER_DEPTH && current !== undefined; layer++) {
+        if (current instanceof z.ZodObject) {
+            walkObject(current, currentSegments, depth, out);
+            break;
+        }
+        if (current instanceof z.ZodRecord) {
+            const { keyType, valueType } = current;
+            if (keyType instanceof z.ZodType) {
+                collectAt(keyType, [...currentSegments, { kind: "recordKey" }], out);
+            }
+            if (valueType instanceof z.ZodType) {
+                const valueSegments = [...currentSegments, { kind: "recordValue" }];
+                collectAt(valueType, valueSegments, out);
+                walkNested(valueType, valueSegments, depth + 1, out);
+            }
+            break;
+        }
+        if (current instanceof z.ZodArray) {
+            currentSegments = [...currentSegments, { kind: "element" }];
+            current = zodDef(current)?.element;
+            continue;
+        }
+        current = zodDef(current)?.innerType;
+    }
+}
+function walkObject(objectSchema, segments, depth, out) {
+    for (const [name, fieldSchema] of Object.entries(zodShape(objectSchema))) {
+        const fieldSegments = [...segments, { kind: "field", name }];
+        collectAt(fieldSchema, fieldSegments, out);
+        walkNested(fieldSchema, fieldSegments, depth + 1, out);
+    }
+}
+/** All reference metas of a handler input schema, including fields nested in arrays,
+ *  objects and records. `z.lazy()` is not followed. */
+export function readHandlerFieldReferences(schema) {
+    const objectSchema = unwrapObjectSchema(schema);
+    if (objectSchema === undefined)
+        return [];
+    const out = [];
+    walkObject(objectSchema, [], 0, out);
+    return out;
+}
+export function handlerFieldReferences(schema) {
+    return readHandlerFieldReferences(schema).flatMap(({ path, segments, reading }) => reading.kind === "ok" ? [{ path, segments, reference: reading.reference }] : []);
+}
 export function handlerFieldReference(schema, field) {
     const reading = readHandlerFieldReference(schema, field);
     return reading.kind === "ok" ? reading.reference : undefined;

package/dist/engine/index.d.ts

@@ -25,7 +25,7 @@ export type { WorkflowDefinition, WorkflowInput, WorkflowTrigger } from "./defin
 export { computeDefinitionFingerprint, defineWorkflow } from "./define-workflow.js";
 export type { ToggleReader } from "./effective-features.js";
 export { computeEffectiveFeatures, isToggleableFeature } from "./effective-features.js";
-export { createEntityExecutor, defineEntityCreateHandler, defineEntityDeleteHandler, defineEntityDetailHandler, defineEntityListHandler, defineEntityQueryHandler, defineEntityRestoreHandler, defineEntityUpdateHandler, defineEntityWriteHandler, defineProjectionQueryHandler, type EntityCrudRegistrar, entityListSchema, MAX_LIST_LIMIT, type RegisterEntityCrudOptions, registerEntityCrud, } from "./entity-handlers.js";
+export { createEntityExecutor, defineEntityCreateHandler, defineEntityDeleteHandler, defineEntityDetailHandler, defineEntityListHandler, defineEntityQueryHandler, defineEntityRestoreHandler, defineEntityUpdateHandler, defineEntityWriteHandler, defineProjectionQueryHandler, type EntityCrudRegistrar, entityListSchema, MAX_LIST_LIMIT, type RegisterEntityCrudOptions, } from "./entity-handlers.js";
 export { declareEscapeHatch } from "./escape-hatch-declaration.js";
 export type { EmitCtx } from "./event-helpers.js";
 export { emitEvent, typedPayload } from "./event-helpers.js";
@@ -43,7 +43,7 @@ export { addPattern, applyChanges, createFeaturePatcher, getPatternSchema, group
 export { type ChangelogEntry, type ChangelogType, compareVersions, type FeatureChangelog, filterEntriesAfter, parseFeatureChangelog, sortEntries, validateChangelog, } from "./feature-changelog.js";
 export { type BuildManifestOptions, buildManifestFromRegistry, type FeatureManifest, type ManifestConfigKey, type ManifestExtension, type ManifestFeature, type ManifestSecret, type ManifestSystemEvent, serializeManifest, } from "./feature-manifest.js";
 export { checkWriteFieldOwnership, checkWriteFieldRoles, filterReadFields, maskWriteOnlyFields, } from "./field-access.js";
-export { HANDLER_FIELD_REFERENCES_META_KEY, type HandlerFieldReference, type HandlerFieldReferenceMeta, handlerFieldReference, } from "./handler-field-references.js";
+export { HANDLER_FIELD_REFERENCES_META_KEY, type HandlerFieldPathSegment, type HandlerFieldReference, type HandlerFieldReferenceAtPath, type HandlerFieldReferenceMeta, handlerFieldReference, handlerFieldReferences, readHandlerFieldReferences, } from "./handler-field-references.js";
 export { resolveName, withResponseData } from "./handler-helpers.js";
 export { i18nKey } from "./i18n-key.js";
 export { buildSessionRoles, findForbiddenMembershipRole, isForbiddenMembershipRole, stripForbiddenMembershipRoles, } from "./membership-roles.js";
@@ -81,7 +81,7 @@ export { assertNotificationVariables, templateVariable, templateVariablesToZod,
 export { type EffectiveFeaturesResolver, findTierResolverUsage, isTierResolverPlugin, requireTierResolverPlugin, TENANT_TIER_RESOLVER_EXT, type TierResolverPlugin, type TrialGate, } from "./tier-resolver-extension.js";
 export { findOverDeepTransferChain, resolveTransferAdjacency as resolveEntityTransferAdjacency, type TransferAdjacency, type TransferEdge, type TransferEdgeLink, } from "./transfer-adjacency.js";
 export { isSystemTenant, isUuid, parseTenantId, SYSTEM_TENANT_ID } from "./types/identifiers.js";
-export type { AccessRule, ActionFormScreenDefinition, ActiveMembership, ActiveMembershipRejection, ActiveMembershipResult, AgentExposure, AgentHandlerHints, AgentRisk, AppContext, AppendEventArgs, AppendEventFn, AuthClaimsContext, AuthClaimsFn, AuthClaimsHookDef, BeforeTransactionPhase, BeforeTransactionResult, BelongsToRelation, BigIntFieldDef, BooleanFieldDef, CamelToKebab, ChatSendFailureCode, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyJsType, ClaimKeyType, ConcurrencyMode, ConfigAccessor, ConfigAccessorFactory, ConfigBacking, ConfigCascade, ConfigCascadeLevel, ConfigDefinition, ConfigEditScreenDefinition, ConfigKeyAccess, ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigMask, ConfigResolver, ConfigScope, ConfigSecretsReader, ConfigSeedDef, ConfigStoredRow, ConfigStoredRowWithSource, ConfigValidateContext, ConfigValidateFn, ConfigValue, ConfigValueSource, ConfigValueWithSource, ContentCollectionDefinition, CreateSeedOptions, CreateTenantSeedOptions, CreateUserSeedOptions, CustomScreenDefinition, CustomScreenRoute, DashboardChartPanel, DashboardCustomPanel, DashboardDateParam, DashboardFeedPanel, DashboardFilterDefinition, DashboardI18nText, DashboardListPanel, DashboardMoneyParam, DashboardPanelDefinition, DashboardPanelVisibility, DashboardProgressListPanel, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DashboardText, DashboardTextParam, DashboardValueFormat, DateFieldDef, DecimalFieldDef, DeleteContext, DeliveryErrorCode, DeliveryFailureCode, DeliverySkipReason, DeriveContext, DerivedFieldDef, DerivedFieldsMap, DerivedValueType, EditExtensionSection, EditFieldPrefill, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EmbeddedListEditSpec, EntityDefinition, EntityEditAction, EntityEditActionPlacement, EntityEditScreenDefinition, EntityId, EntityListExpandableRow, EntityListScreenDefinition, EntityRef, EntityRelations, EscapeHatchAuditSink, EscapeHatchDeclaration, EscapeHatchKind, EscapeHatchReporter, EscapeHatchTarget, EscapeHatchUseEvent, EventDef, ExtensionOptionsArgs, ExtensionOptionsFor, FeatureDefinition, FeatureRegistrar, FieldAccess, FieldCondition, FieldDefinition, FieldFormatRegistry, FieldIconKey, FieldRenderer, FileFieldDef, FilesFieldDef, Findability, FormatSpec, FormWidth, HandlerContext, HasManyRelation, HookMap, ImageFieldDef, ImagesFieldDef, JobBackoff, JobBackoffStrategy, JobContext, JobDefinition, JobHandlerFn, JobTrigger, JobTriggerEvent, JsonbFieldDef, KumikoEntityTypeMap, KumikoEventTypeMap, KumikoExtensionOptionsMap, KumikoHandlerPayloadMap, KumikoHandlerResultMap, LifecycleHookType, ListColumnSpec, ListFacetSpec, ListPaginationMode, ListSortDir, ListSortSpec, LongTextFindability, ManyToManyRelation, MaxPerTenantOptions, MemberReader, MetricNavigate, MetricSpec, MspErrorMode, MspErrorPolicy, MultiSelectFieldDef, MultiStreamApplyFn, MultiStreamProjectionDefinition, NameOrRef, NavDefinition, NavIconKey, NotificationDataFn, NotificationDefinition, NotificationLocalizedTemplate, NotificationRecipientFn, NotificationRecordMapping, NotificationTemplateBody, NotificationTemplateFn, NotificationTemplateMeta, NotifyDeferred, NotifyDelivery, NotifyDeliveryStatus, NotifyDispatched, NotifyFactory, NotifyFn, NotifyJobDispatcher, NotifyOptions, NotifyPriority, NotifyResult, NumberFieldDef, OnDeleteStrategy, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, ParentRefDef, PersonalAnnotations, PersonalAnnotationsLongText, PersonalAnnotationsNoFind, PersonalSubject, PlatformComponent, PluralForms, PostDeleteHookFn, PostSaveHookFn, PreDeleteHookFn, PreparedWriteEvent, PreQueryHookFn, PreSaveHookFn, ProjectionDefinition, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, ProjectionTable, QualifiedEventName, QueryEvent, QueryHandlerDef, QueryHandlerFn, RateLimitPer, RecordHeaderSpec, RecordHeaderSubtitlePart, ReferenceDataDef, Registry, RelationDefinition, ResolvedPiiFlags, RetentionDef, RoleAccessPersonalData, RoleAccessRule, RowAction, RowActionNavigate, RowActionNavigateBase, RowActionWriteHandler, RowFieldExtractor, SaveContext, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenNavSugar, ScreenSlots, SecretKeyDefinition, SecretKeyHandle, SecretMintConfirmStep, SecretMintScreenDefinition, SecretNamespaceDefinition, SecretNamespaceHandle, SecretNamespaceOptions, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, SelectFieldDef, SessionUser, SessionUserOrigin, StreamHandlerDef, StreamHandlerFn, Subscribe, TargetRef, TemplateListVariableDef, TemplateScalarVariableDef, TemplateVariableDef, TemplateVariables, TenantId, TenantWriteTarget, TextFieldDef, ToolbarAction, TranslationEntry, TranslationKeys, TranslationsDef, TranslationValue, TreeAction, TreeActionDef, TreeActionsHandle, TreeChildrenSubscribe, TreeNode, TreeNodeState, UnitKey, UnsafeAppendEventFn, ValidationError, ValidationHookFn, WorkspaceDefinition, WriteEvent, WriteHandlerDef, WriteHandlerFn, WriteResult, } from "./types/index.js";
+export type { AccessRule, ActionFormScreenDefinition, ActiveMembership, ActiveMembershipRejection, ActiveMembershipResult, AgentExposure, AgentHandlerHints, AgentRisk, AppContext, AppendEventArgs, AppendEventFn, AuthClaimsContext, AuthClaimsFn, AuthClaimsHookDef, BeforeTransactionPhase, BeforeTransactionResult, BelongsToRelation, BigIntFieldDef, BooleanFieldDef, CamelToKebab, ChatSendFailureCode, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyJsType, ClaimKeyType, ConcurrencyMode, ConfigAccessor, ConfigAccessorFactory, ConfigBacking, ConfigCascade, ConfigCascadeLevel, ConfigDefinition, ConfigEditScreenDefinition, ConfigKeyAccess, ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigMask, ConfigResolver, ConfigScope, ConfigSecretsReader, ConfigSeedDef, ConfigStoredRow, ConfigStoredRowWithSource, ConfigValidateContext, ConfigValidateFn, ConfigValue, ConfigValueSource, ConfigValueWithSource, ContentCollectionDefinition, CreateSeedOptions, CreateTenantSeedOptions, CreateUserSeedOptions, CustomScreenDefinition, CustomScreenRoute, DashboardChartPanel, DashboardCustomPanel, DashboardDateParam, DashboardFeedPanel, DashboardFilterDefinition, DashboardI18nText, DashboardListPanel, DashboardMoneyParam, DashboardPanelDefinition, DashboardPanelVisibility, DashboardProgressListPanel, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DashboardText, DashboardTextParam, DashboardValueFormat, DateFieldDef, DecimalFieldDef, DeleteContext, DeliveryErrorCode, DeliveryFailureCode, DeliverySkipReason, DeriveContext, DerivedFieldDef, DerivedFieldsMap, DerivedValueType, EditExtensionSection, EditFieldPrefill, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EmbeddedListEditSpec, EntityDefinition, EntityEditAction, EntityEditActionPlacement, EntityEditScreenDefinition, EntityId, EntityListExpandableRow, EntityListScreenDefinition, EntityObjectDefinition, EntityRef, EntityRelations, EscapeHatchAuditSink, EscapeHatchDeclaration, EscapeHatchKind, EscapeHatchReporter, EscapeHatchTarget, EscapeHatchUseEvent, EventDef, ExtensionOptionsArgs, ExtensionOptionsFor, FeatureDefinition, FeatureRegistrar, FieldAccess, FieldCondition, FieldDefinition, FieldFormatRegistry, FieldIconKey, FieldRenderer, FileFieldDef, FilesFieldDef, Findability, FormatSpec, FormWidth, HandlerContext, HasManyRelation, HookDefinition, HookMap, ImageFieldDef, ImagesFieldDef, JobBackoff, JobBackoffStrategy, JobContext, JobDefinition, JobHandlerFn, JobTrigger, JobTriggerEvent, JsonbFieldDef, KumikoEntityTypeMap, KumikoEventTypeMap, KumikoExtensionOptionsMap, KumikoHandlerPayloadMap, KumikoHandlerResultMap, LifecycleHookType, ListColumnSpec, ListFacetSpec, ListPaginationMode, ListSortDir, ListSortSpec, LongTextFindability, ManyToManyRelation, MaxPerTenantOptions, MemberReader, MetricNavigate, MetricSpec, MspErrorMode, MspErrorPolicy, MultiSelectFieldDef, MultiStreamApplyFn, MultiStreamProjectionDefinition, NameOrRef, NavDefinition, NavIconKey, NotificationDataFn, NotificationDefinition, NotificationLocalizedTemplate, NotificationRecipientFn, NotificationRecordMapping, NotificationTemplateBody, NotificationTemplateFn, NotificationTemplateMeta, NotifyDeferred, NotifyDelivery, NotifyDeliveryStatus, NotifyDispatched, NotifyFactory, NotifyFn, NotifyJobDispatcher, NotifyOptions, NotifyPriority, NotifyResult, NumberFieldDef, OnDeleteStrategy, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, ParentRefDef, PersonalAnnotations, PersonalAnnotationsLongText, PersonalAnnotationsNoFind, PersonalSubject, PlatformComponent, PluralForms, PostDeleteHookFn, PostSaveHookFn, PreDeleteHookFn, PreparedWriteEvent, PreQueryHookFn, PreSaveHookFn, ProjectionDefinition, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, ProjectionTable, QualifiedEventName, QueryEvent, QueryHandlerDef, QueryHandlerFn, RateLimitPer, RecordHeaderSpec, RecordHeaderSubtitlePart, ReferenceDataDef, Registry, RelationDefinition, ResolvedPiiFlags, RetentionDef, RoleAccessPersonalData, RoleAccessRule, RowAction, RowActionNavigate, RowActionNavigateBase, RowActionWriteHandler, RowFieldExtractor, SaveContext, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenNavSugar, ScreenSlots, SecretKeyDefinition, SecretKeyHandle, SecretMintConfirmStep, SecretMintScreenDefinition, SecretNamespaceDefinition, SecretNamespaceHandle, SecretNamespaceOptions, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, SelectFieldDef, SessionUser, SessionUserOrigin, StreamHandlerDef, StreamHandlerFn, Subscribe, TargetRef, TemplateListVariableDef, TemplateScalarVariableDef, TemplateVariableDef, TemplateVariables, TenantId, TenantWriteTarget, TextFieldDef, ToolbarAction, TranslationEntry, TranslationKeys, TranslationsDef, TranslationValue, TreeAction, TreeActionDef, TreeActionsHandle, TreeChildrenSubscribe, TreeNode, TreeNodeState, UnitKey, UnsafeAppendEventFn, ValidationError, ValidationHookFn, WorkspaceDefinition, WriteEvent, WriteHandlerDef, WriteHandlerFn, WriteResult, } from "./types/index.js";
 export { DEFAULT_CURRENCIES, DEFAULT_LOCALES, DELIVERY_FAILURE_CODES, DELIVERY_SKIP_REASONS, HookPhases, HTTP_ERROR_CODE_PATTERN, isAgentVisibleScreen, isDeliveryErrorCode, isOpenToAllGranted, resolveAgentExposure, } from "./types/index.js";
 export type { AwaitedEventType, PipelineBuildCtx, PipelineCtx, PipelineDef, StepBuilder, StepDef, StepFailureStrategy, StepInstance, StepKind, StepNamespace, StepResolver, } from "./types/step.js";
 export { runValidation } from "./validation.js";

package/dist/engine/index.js

@@ -25,7 +25,7 @@ export { createEntityExecutor, defineEntityCreateHandler, defineEntityDeleteHand
 // Apps nehmen die verb-spezifischen Wrapper oben. Existierende
 // Caller (Integration-Tests, alte bundled-features) bleiben so
 // unverändert lauffähig.
-defineEntityQueryHandler, defineEntityRestoreHandler, defineEntityUpdateHandler, defineEntityWriteHandler, defineProjectionQueryHandler, entityListSchema, MAX_LIST_LIMIT, registerEntityCrud, } from "./entity-handlers.js";
+defineEntityQueryHandler, defineEntityRestoreHandler, defineEntityUpdateHandler, defineEntityWriteHandler, defineProjectionQueryHandler, entityListSchema, MAX_LIST_LIMIT, } from "./entity-handlers.js";
 export { declareEscapeHatch } from "./escape-hatch-declaration.js";
 export { emitEvent, typedPayload } from "./event-helpers.js";
 export { EXT_ASSIGNABLE_ROLE, EXT_DERIVATIVE_OVERLAY_RESOLVER, EXT_DERIVATIVE_PUBLIC_PREDICATE, EXT_DERIVATIVE_RENDERER, EXT_EXTERNAL_RESOURCE, EXT_FILE_PROVIDER, EXT_INFRA_RESOURCE, EXT_PRINCIPAL_STATUS, EXT_SEARCH_ADAPTER, EXT_STORAGE_PROVIDER, EXT_TENANT_DATA, EXT_TENANT_LIFECYCLE_STATUS, EXT_USER_DATA, EXT_USER_DATA_ORDER, FILE_PROVIDER_CONFIG_KEY, FILE_STORAGE_PROVIDER_BOOT_SENTINEL, FILE_STORAGE_PROVIDER_ENV, TENANT_MEMBERSHIPS_QUERY, } from "./extension-names.js";
@@ -38,7 +38,7 @@ export { addPattern, applyChanges, createFeaturePatcher, getPatternSchema, group
 export { compareVersions, filterEntriesAfter, parseFeatureChangelog, sortEntries, validateChangelog, } from "./feature-changelog.js";
 export { buildManifestFromRegistry, serializeManifest, } from "./feature-manifest.js";
 export { checkWriteFieldOwnership, checkWriteFieldRoles, filterReadFields, maskWriteOnlyFields, } from "./field-access.js";
-export { HANDLER_FIELD_REFERENCES_META_KEY, handlerFieldReference, } from "./handler-field-references.js";
+export { HANDLER_FIELD_REFERENCES_META_KEY, handlerFieldReference, handlerFieldReferences, readHandlerFieldReferences, } from "./handler-field-references.js";
 export { resolveName, withResponseData } from "./handler-helpers.js";
 export { i18nKey } from "./i18n-key.js";
 // findForbiddenMembershipRole/isForbiddenMembershipRole/

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-ingest.js

@@ -108,6 +108,9 @@ const RESERVED_TEMPLATE_VARIABLE_NAMES = new Set([
     "link",
     "money",
     "date",
+    "richText",
+    "stepIs",
+    "percent",
 ]);
 const KEBAB_NOTIFICATION_NAME = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 function isTemplateVariableName(value) {

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/template-variables.d.ts

@@ -23,6 +23,9 @@ export declare const templateVariable: {
     readonly date: (opts?: CommonOptions & {
         readonly example?: string;
     }) => TemplateScalarVariableDef;
+    readonly percent: (opts?: CommonOptions & {
+        readonly example?: number;
+    }) => TemplateScalarVariableDef;
     readonly list: (item: Readonly<Record<string, TemplateScalarVariableDef>>, opts?: CommonOptions & {
         readonly example?: readonly Readonly<Record<string, unknown>>[];
     }) => TemplateListVariableDef;

package/dist/engine/template-variables.js

@@ -16,6 +16,7 @@ export const templateVariable = {
         type: "date",
         ...opts,
     }),
+    percent: (opts = {}) => ({ type: "percent", ...opts }),
     list: (item, opts = {}) => ({ type: "list", item, ...opts }),
 };
 const LINK_PROTOCOLS = new Set(["http:", "https:", "mailto:"]);
@@ -48,6 +49,8 @@ function scalarToZod(def) {
             return moneySchema;
         case "date":
             return dateSchema;
+        case "percent":
+            return z.number().finite();
     }
 }
 function variableToZod(def) {

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/create-file-ref-from-bytes.d.ts

@@ -19,6 +19,7 @@ export type CreateFileRefInput = {
         readonly entityId?: string;
     };
 };
+export declare function filesUnavailableMessage(caller: string): string;
 export declare function createFileRefFromBytes(ctx: CreateFileRefContext, input: CreateFileRefInput): Promise<WriteResult<CreatedFileRef>>;
 export type UploadFileBytesContext = Pick<CreateFileRefContext, "db" | "files" | "registry" | "user">;
 export declare function uploadFileBytesBeforeTransaction(ctx: UploadFileBytesContext, input: CreateFileRefInput): Promise<BeforeTransactionResult<UploadedFileBytes>>;

package/dist/files/create-file-ref-from-bytes.js

@@ -4,6 +4,11 @@ import { createFileRefRow, DEFAULT_MAX_UPLOAD_SIZE, storeFileAsFileRef, writeAcc
 import { fileRefsTable } from "./file-ref-table.js";
 import { readFilesRouteOptions } from "./file-routes.js";
 import { assertSafeStorageKey } from "./types.js";
+// The handler context has no HTTP/job/seed marker to name, so the message states the actual
+// cause: the dispatcher's AppContext carries no file-provider resolver.
+export function filesUnavailableMessage(caller) {
+    return `${caller}: ctx.files is unavailable because no file-provider resolver is wired on this dispatcher context. Mount a file-provider-* feature and build the dispatcher context with withFileProviderResolver (HTTP, job and seed dispatchers each need it)`;
+}
 // Server-side counterpart of POST /files for handlers/jobs that produce bytes
 // themselves (generated PDFs, exports). Same validation, storage layout and
 // fileRef.created event as an upload; the tenant is always ctx.user.tenantId.
@@ -11,7 +16,7 @@ export async function createFileRefFromBytes(ctx, input) {
     const { files } = ctx;
     if (!files) {
         return writeFailure(new InternalError({
-            message: "createFileRefFromBytes: ctx.files is unavailable — mount a file-provider feature to store files",
+            message: filesUnavailableMessage("createFileRefFromBytes"),
         }));
     }
     const outcome = await storeFileAsFileRef({
@@ -48,7 +53,7 @@ export async function uploadFileBytesBeforeTransaction(ctx, input) {
     const { files } = ctx;
     if (!files) {
         return writeFailure(new InternalError({
-            message: "uploadFileBytesBeforeTransaction: ctx.files is unavailable — mount a file-provider feature to store files",
+            message: filesUnavailableMessage("uploadFileBytesBeforeTransaction"),
         }));
     }
     const outcome = await writeAcceptedFileBytes({

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";