@cosmicdrift/kumiko-framework 0.362.0 → 0.364.0

package/dist/engine/feature-config-events-jobs.d.ts

@@ -1,7 +1,7 @@
 import type * as z from "zod";
 import { type ZodType } from "zod";
 import type { FeatureBuilderState } from "./feature-builder-state.js";
-import type { AuthClaimsFn, ClaimKeyHandle, ClaimKeyType, ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigSeedDef, DeclarativeEventMigration, EventDef, EventPiiStance, EventUpcastFn, JobDefinition, JobHandlerFn, MetricOptions, NameOrRef, NotificationDataFn, NotificationRecipientFn, NotificationTemplateFn, QualifiedEventName, SecretKeyHandle, SecretNamespaceHandle, SecretNamespaceOptions, SecretOptions, TranslationsDef } from "./types/index.js";
+import type { AuthClaimsFn, ClaimKeyHandle, ClaimKeyType, ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigSeedDef, DeclarativeEventMigration, EventDef, EventPiiStance, EventUpcastFn, JobDefinition, JobHandlerFn, MetricOptions, NameOrRef, NotificationDataFn, NotificationLocalizedTemplate, NotificationRecipientFn, NotificationRecordMapping, NotificationTemplateBody, NotificationTemplateFn, NotificationTemplateMeta, QualifiedEventName, SecretKeyHandle, SecretNamespaceHandle, SecretNamespaceOptions, SecretOptions, TemplateVariables, TranslationsDef } from "./types/index.js";
 export declare function buildConfigEventsJobsMethods<TName extends string>(state: FeatureBuilderState, name: TName): {
     config: {
         <T extends ConfigKeyType>(keyName: string, def: ConfigKeyDefinition<T>): ConfigKeyHandle<T>;
@@ -14,19 +14,29 @@ export declare function buildConfigEventsJobsMethods<TName extends string>(state
     notification(notificationNameOrDefinition: string | ({
         readonly name: string;
     } & {
-        readonly trigger: {
+        readonly trigger?: {
             readonly on: NameOrRef;
         };
-        readonly recipient: NotificationRecipientFn;
-        readonly data: NotificationDataFn;
+        readonly recipient?: NotificationRecipientFn;
+        readonly data?: NotificationDataFn;
         readonly templates?: Readonly<Record<string, NotificationTemplateFn>>;
+        readonly variables?: TemplateVariables;
+        readonly record?: NotificationRecordMapping;
+        readonly template?: Readonly<Record<string, NotificationTemplateBody>>;
+        readonly meta?: Readonly<Record<string, NotificationTemplateMeta>>;
+        readonly localizedTemplate?: () => NotificationLocalizedTemplate;
     }), definition?: {
-        readonly trigger: {
+        readonly trigger?: {
             readonly on: NameOrRef;
         };
-        readonly recipient: NotificationRecipientFn;
-        readonly data: NotificationDataFn;
+        readonly recipient?: NotificationRecipientFn;
+        readonly data?: NotificationDataFn;
         readonly templates?: Readonly<Record<string, NotificationTemplateFn>>;
+        readonly variables?: TemplateVariables;
+        readonly record?: NotificationRecordMapping;
+        readonly template?: Readonly<Record<string, NotificationTemplateBody>>;
+        readonly meta?: Readonly<Record<string, NotificationTemplateMeta>>;
+        readonly localizedTemplate?: () => NotificationLocalizedTemplate;
     }): void;
     translations(def: TranslationsDef): void;
     defineEvent: <const TInner extends string, TPayload>(eventName: TInner, schema: ZodType<TPayload>, options: {

package/dist/engine/feature-config-events-jobs.js

@@ -1,4 +1,5 @@
 import { escapeHatchGrantsProblem, normalizeEventPiiSubject, } from "@cosmicdrift/kumiko-types/handlers";
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import { ZodObject } from "zod";
 import { isValidIanaTimeZone } from "../time/iana.js";
 import { resolveName } from "./handler-helpers.js";
@@ -197,10 +198,25 @@ export function buildConfigEventsJobsMethods(state, name) {
                 : splitNamedDefinition(notificationNameOrDefinition);
             state.notifications[notificationName] = {
                 name: notificationName,
-                trigger: { on: resolveName(resolvedDefinition.trigger.on) },
-                recipient: resolvedDefinition.recipient,
-                data: resolvedDefinition.data,
+                ...(resolvedDefinition.trigger !== undefined
+                    ? { trigger: { on: resolveName(resolvedDefinition.trigger.on) } }
+                    : {}),
+                ...(resolvedDefinition.recipient !== undefined
+                    ? { recipient: resolvedDefinition.recipient }
+                    : {}),
+                ...(resolvedDefinition.data !== undefined ? { data: resolvedDefinition.data } : {}),
                 templates: resolvedDefinition.templates,
+                ...(resolvedDefinition.variables !== undefined
+                    ? { variables: resolvedDefinition.variables }
+                    : {}),
+                ...(resolvedDefinition.record !== undefined ? { record: resolvedDefinition.record } : {}),
+                ...(resolvedDefinition.template !== undefined
+                    ? { template: resolvedDefinition.template }
+                    : {}),
+                ...(resolvedDefinition.meta !== undefined ? { meta: resolvedDefinition.meta } : {}),
+                ...(resolvedDefinition.localizedTemplate !== undefined
+                    ? { localizedTemplate: resolvedDefinition.localizedTemplate }
+                    : {}),
             };
         },
         translations(def) {
@@ -366,10 +382,9 @@ function compileEventMigration(spec) {
         renameTargets.set(to, from);
     }
     return (payload) => {
-        if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
+        if (!isPlainObject(payload)) {
             throw new Error("Declarative event migration expects an object payload");
         }
-        // @cast-boundary parse — payload is guarded as a plain object above
         const next = { ...payload };
         for (const [from, to] of Object.entries(spec.rename ?? {})) {
             if (from in next) {

package/dist/engine/feature-entity-handlers.d.ts

@@ -3,7 +3,7 @@ import type { ZodType } from "zod";
 import { type QueryHandlerDefinition, type StreamHandlerDefinition, type WriteHandlerDefinition } from "./define-handler.js";
 import type { RegisterEntityCrudOptions } from "./entity-handlers.js";
 import type { FeatureBuilderState } from "./feature-builder-state.js";
-import type { AccessRule, AgentHandlerHints, EntityDefinition, EntityRef, EscapeHatchDeclaration, HandlerRef, NameOrRef, PayloadRateLimitOption, QueryHandlerFn, RateLimitDeclaration, RelationDefinition, StreamHandlerFn, WriteHandlerFn } from "./types/index.js";
+import type { AccessRule, AgentHandlerHints, EntityDefinition, EntityRef, EscapeHatchDeclaration, HandlerRef, KumikoEventTypeMap, NameOrRef, PayloadRateLimitOption, QueryHandlerFn, RateLimitDeclaration, RelationDefinition, StreamHandlerFn, WriteHandlerFn } from "./types/index.js";
 export declare function buildEntityHandlerMethods<TName extends string>(state: FeatureBuilderState, name: TName): {
     entity(nameOrDefinition: string | ({
         readonly name: string;
@@ -14,7 +14,7 @@ export declare function buildEntityHandlerMethods<TName extends string>(state: F
         readonly entity: NameOrRef;
         readonly name: string;
     } & RelationDefinition), relationName?: string, definition?: RelationDefinition): void;
-    writeHandler<TName_1 extends string, TSchema extends ZodType>(nameOrDef: string | WriteHandlerDefinition<TName_1, TSchema>, schema?: TSchema, handler?: WriteHandlerFn<z.infer<TSchema>>, options?: {
+    writeHandler<TName_1 extends string, TSchema extends ZodType, TPrepared = undefined>(nameOrDef: string | WriteHandlerDefinition<TName_1, TSchema, unknown, KumikoEventTypeMap, TPrepared>, schema?: TSchema, handler?: WriteHandlerFn<z.infer<TSchema>>, options?: {
         access: AccessRule;
         rateLimit?: RateLimitDeclaration;
         additionalRateLimits?: readonly PayloadRateLimitOption[];

package/dist/engine/feature-entity-handlers.js

@@ -54,6 +54,17 @@ function agentSlots(source) {
         ...(source.agent && { agent: source.agent }),
     };
 }
+function transactionPhaseSlots(def) {
+    return {
+        ...(def.reserveBeforeTransaction && {
+            reserveBeforeTransaction: def.reserveBeforeTransaction,
+        }),
+        ...(def.beforeTransaction && {
+            beforeTransaction: def.beforeTransaction, // @cast-boundary engine-bridge
+        }),
+        ...(def.transaction && { transaction: def.transaction }),
+    };
+}
 function requireInlineHandlerArgs(kind, schema, handler, options) {
     if (!schema || !handler || !options?.access) {
         throw new Error(`${kind} inline form requires schema + handler + options.access`);
@@ -108,9 +119,7 @@ export function buildEntityHandlerMethods(state, name) {
                     ...(def.rateLimit && { rateLimit: def.rateLimit }),
                     ...(def.additionalRateLimits && { additionalRateLimits: def.additionalRateLimits }),
                     ...(def.escapeHatch && { escapeHatch: def.escapeHatch }),
-                    ...(def.reserveBeforeTransaction && {
-                        reserveBeforeTransaction: def.reserveBeforeTransaction,
-                    }),
+                    ...transactionPhaseSlots(def),
                     ...(def.tenantlessAnonymous && { tenantlessAnonymous: true }),
                     // Forward the pipeline-build closure so boot-validators and
                     // Designer/AI tooling can inspect the step list. Absent on

package/dist/engine/feature-ui-extensions.js

@@ -1,4 +1,5 @@
 import { escapeHatchGrantsProblem } from "@cosmicdrift/kumiko-types/handlers";
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import { WEBSOCKET_MAX_CONNECTIONS_PER_USER_LIMIT, WEBSOCKET_MAX_PAYLOAD_BYTES, WEBSOCKET_ROUTE_PATH_PREFIX, } from "@cosmicdrift/kumiko-types/websocket-route";
 import { bindHookEscapeHatchGrant } from "../pipeline/system-identity-switch.js";
 import { LifecycleHookTypes } from "./constants.js";
@@ -209,9 +210,7 @@ export function buildUiExtensionsMethods(state, name) {
             // for every extension regardless of its typed hook shape.
             const escapeHatch = optionsBag?.["escapeHatch"];
             if (escapeHatch !== undefined) {
-                const reason = typeof escapeHatch === "object" && escapeHatch !== null
-                    ? escapeHatch.reason
-                    : undefined;
+                const reason = isPlainObject(escapeHatch) ? escapeHatch["reason"] : undefined;
                 if (typeof reason !== "string" || reason.trim().length === 0) {
                     throw new Error(`[Feature ${name}] r.useExtension("${extensionName}", "${resolvedEntityName}", ...) declares an invalid { escapeHatch } — ` +
                         `must be { reason: "<non-empty string>" } explaining why this usage needs unfiltered db access.`);

package/dist/engine/handler-field-references.d.ts

@@ -1,3 +1,22 @@
-import { type ZodType } from "zod";
+import * as z from "zod";
 export declare const HANDLER_FIELD_REFERENCES_META_KEY = "references";
-export declare function handlerFieldReference(schema: ZodType, field: string): string | undefined;
+export type HandlerFieldReferenceMeta = string | {
+    readonly entity: string;
+    readonly by?: string;
+};
+export type HandlerFieldReference = {
+    readonly entity: string;
+    readonly by: string | undefined;
+    readonly multiple: boolean;
+};
+export type HandlerFieldReferenceReading = {
+    readonly kind: "none";
+} | {
+    readonly kind: "invalid";
+    readonly raw: unknown;
+} | {
+    readonly kind: "ok";
+    readonly reference: HandlerFieldReference;
+};
+export declare function readHandlerFieldReference(schema: z.ZodType, field: string): HandlerFieldReferenceReading;
+export declare function handlerFieldReference(schema: z.ZodType, field: string): HandlerFieldReference | undefined;

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

@@ -1,31 +1,69 @@
-import { ZodObject } from "zod";
+import * as z from "zod";
 import { zodDef, zodMeta, zodShapeField } from "../env/_zod-introspect.js";
 export const HANDLER_FIELD_REFERENCES_META_KEY = "references";
 const MAX_WRAPPER_DEPTH = 8;
-function referencesFromMeta(field) {
+const referenceMetaSchema = z.union([
+    z.string().min(1),
+    z.object({ entity: z.string().min(1), by: z.string().min(1).optional() }),
+]);
+function rawReferenceMeta(field) {
     const meta = zodMeta(field);
     if (typeof meta !== "object" || meta === null)
         return undefined;
-    const value = Reflect.get(meta, HANDLER_FIELD_REFERENCES_META_KEY);
-    return typeof value === "string" ? value : undefined;
+    return Reflect.get(meta, HANDLER_FIELD_REFERENCES_META_KEY);
 }
-// `.optional()` / `.nullable()` / `.default()` after `.meta()` hide the meta
-// from the outer type, so every wrapper layer is probed on the way in.
-export function handlerFieldReference(schema, field) {
+function unwrapObjectSchema(schema) {
     let current = schema;
     for (let depth = 0; depth < MAX_WRAPPER_DEPTH && current !== undefined; depth++) {
-        if (current instanceof ZodObject)
-            break;
+        if (current instanceof z.ZodObject)
+            return current;
         current = zodDef(current)?.innerType;
     }
-    if (!(current instanceof ZodObject))
-        return undefined;
-    let fieldSchema = zodShapeField(current, field);
-    for (let depth = 0; depth < MAX_WRAPPER_DEPTH && fieldSchema !== undefined; depth++) {
-        const reference = referencesFromMeta(fieldSchema);
-        if (reference !== undefined)
-            return reference;
-        fieldSchema = zodDef(fieldSchema)?.innerType;
+    return undefined;
+}
+// `.optional()` / `.nullable()` / `.default()` after `.meta()` hide the meta from the outer
+// type, so every wrapper layer is probed on the way in; array elements are probed too.
+function findRawReferenceMeta(field) {
+    let current = field;
+    for (let depth = 0; depth < MAX_WRAPPER_DEPTH && current !== undefined; depth++) {
+        const raw = rawReferenceMeta(current);
+        if (raw !== undefined)
+            return raw;
+        current = current instanceof z.ZodArray ? zodDef(current)?.element : zodDef(current)?.innerType;
     }
     return undefined;
 }
+function isArrayField(field) {
+    let current = field;
+    for (let depth = 0; depth < MAX_WRAPPER_DEPTH && current !== undefined; depth++) {
+        if (current instanceof z.ZodArray)
+            return true;
+        current = zodDef(current)?.innerType;
+    }
+    return false;
+}
+export function readHandlerFieldReference(schema, field) {
+    const objectSchema = unwrapObjectSchema(schema);
+    const fieldSchema = objectSchema && zodShapeField(objectSchema, field);
+    if (fieldSchema === undefined)
+        return { kind: "none" };
+    const raw = findRawReferenceMeta(fieldSchema);
+    if (raw === undefined)
+        return { kind: "none" };
+    const parsed = referenceMetaSchema.safeParse(raw);
+    if (!parsed.success)
+        return { kind: "invalid", raw };
+    const meta = parsed.data;
+    return {
+        kind: "ok",
+        reference: {
+            entity: typeof meta === "string" ? meta : meta.entity,
+            by: typeof meta === "string" ? undefined : meta.by,
+            multiple: isArrayField(fieldSchema),
+        },
+    };
+}
+export function handlerFieldReference(schema, field) {
+    const reading = readHandlerFieldReference(schema, field);
+    return reading.kind === "ok" ? reading.reference : undefined;
+}

package/dist/engine/index.d.ts

@@ -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, handlerFieldReference, } from "./handler-field-references.js";
+export { HANDLER_FIELD_REFERENCES_META_KEY, type HandlerFieldReference, type HandlerFieldReferenceMeta, handlerFieldReference, } 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";
@@ -77,10 +77,11 @@ export { describeWorkflowStepError } from "./steps/describe-workflow-step-error.
 export { unwrapWorkflowStepError, WorkflowStepError } from "./steps/workflow-step-error.js";
 export { WORKFLOW_SYSTEM_EVENT_DEFS } from "./steps/workflow-system-events.js";
 export { ANONYMOUS_ROLE, ANONYMOUS_USER_ID, createAnonymousUser, createSystemUser, SYSTEM_ROLE, SYSTEM_USER_ID, } from "./system-user.js";
+export { assertNotificationVariables, templateVariable, templateVariablesToZod, } from "./template-variables.js";
 export { type EffectiveFeaturesResolver, findTierResolverUsage, isTierResolverPlugin, 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, 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, MemberReader, MetricNavigate, MetricSpec, MspErrorMode, MspErrorPolicy, MultiSelectFieldDef, MultiStreamApplyFn, MultiStreamProjectionDefinition, NameOrRef, NavDefinition, NavIconKey, NotificationDataFn, NotificationDefinition, NotificationRecipientFn, NotificationTemplateFn, NotifyDelivery, NotifyDeliveryStatus, NotifyFactory, NotifyFn, NotifyJobDispatcher, NotifyOptions, NotifyPriority, NotifyResult, NumberFieldDef, OnDeleteStrategy, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, ParentRefDef, PersonalAnnotations, PersonalAnnotationsLongText, PersonalAnnotationsNoFind, PersonalSubject, PlatformComponent, PluralForms, PostDeleteHookFn, PostSaveHookFn, PreDeleteHookFn, 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, 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, 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, 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

@@ -70,6 +70,7 @@ export { describeWorkflowStepError } from "./steps/describe-workflow-step-error.
 export { unwrapWorkflowStepError, WorkflowStepError } from "./steps/workflow-step-error.js";
 export { WORKFLOW_SYSTEM_EVENT_DEFS } from "./steps/workflow-system-events.js";
 export { ANONYMOUS_ROLE, ANONYMOUS_USER_ID, createAnonymousUser, createSystemUser, SYSTEM_ROLE, SYSTEM_USER_ID, } from "./system-user.js";
+export { assertNotificationVariables, templateVariable, templateVariablesToZod, } from "./template-variables.js";
 export { findTierResolverUsage, isTierResolverPlugin, TENANT_TIER_RESOLVER_EXT, } from "./tier-resolver-extension.js";
 export { findOverDeepTransferChain, resolveTransferAdjacency as resolveEntityTransferAdjacency, } from "./transfer-adjacency.js";
 export { isSystemTenant, isUuid, parseTenantId, SYSTEM_TENANT_ID } from "./types/identifiers.js";

package/dist/engine/ownership.js

@@ -16,8 +16,9 @@
 //
 // Construction: use the `from(ref, column?)` helper. It returns a FromRule
 // ready to drop into an access map.
-import { KUMIKO_COLUMNS_SYMBOL, KUMIKO_NAME_SYMBOL, } from "@cosmicdrift/kumiko-types/schema-table-types";
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import { toSnakeCase } from "../db/table-builder.js";
+import { columnSqlNameOf, schemaTableName } from "../db/table-introspection.js";
 import { assertQualifiedWhereFragment, tableColumnSqlNames } from "./where-rule-lint.js";
 // Parse an OwnershipRef into kind + resolved path + default column.
 // Throws on malformed input so the error surfaces at `from()`-call-site (in
@@ -185,32 +186,18 @@ export function userCanCreateFieldRow(user, accessMap, newRow) {
 const PASS_CLAUSE = { kind: "pass" };
 const EMPTY_CLAUSE = { kind: "empty" };
 export function tableNameOf(table) {
-    if (table !== null && typeof table === "object") {
-        const sym = table[KUMIKO_NAME_SYMBOL];
-        if (typeof sym === "string")
-            return sym;
-    }
-    return "<unknown>";
+    return schemaTableName(table) ?? "<unknown>";
 }
 // Resolve a JS-field name on the table to its underlying SQL column name.
-// Drizzle tables carry the mapping under Symbol.for("kumiko:schema:Columns");
-// we read it without importing drizzle-orm at runtime.
 function columnSqlName(table, field) {
     if (table === null || typeof table !== "object")
         return null;
-    const cols = table[KUMIKO_COLUMNS_SYMBOL];
-    if (cols && typeof cols === "object") {
-        const col = cols[field];
-        if (col && typeof col === "object") {
-            const nameVal = col["name"];
-            if (typeof nameVal === "string")
-                return nameVal;
-        }
-    }
+    const handleName = columnSqlNameOf(table, field);
+    if (handleName !== undefined)
+        return handleName;
     // Field may already be the SQL column name on plain objects (tests, etc.).
-    if (table[field] !== undefined) {
+    if (isPlainObject(table) && table[field] !== undefined)
         return toSnakeCase(field);
-    }
     return null;
 }
 function quoteIdent(name) {

package/dist/engine/pattern-library/mixed-schemas.js

@@ -351,7 +351,6 @@ export const notificationSchema = {
             path: "trigger.on",
             label: { en: "Trigger on entity", de: "Trigger-Entität" },
             input: "entity-ref",
-            required: true,
         },
         {
             path: "recipientBody",

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

@@ -1,8 +1,9 @@
 import type { RegistryState } from "./registry-state.js";
-import type { FeatureDefinition } from "./types/index.js";
+import type { FeatureDefinition, NotificationDefinition } from "./types/index.js";
 export declare function populateFeatureCore(state: RegistryState, feature: FeatureDefinition): void;
 export declare function populateHandlers(state: RegistryState, feature: FeatureDefinition): void;
 export declare function populateConfigKeys(state: RegistryState, feature: FeatureDefinition): void;
+export declare function validateNotificationTemplate(featureName: string, notificationName: string, notifDef: NotificationDefinition): void;
 export declare function populateJobsAndNotifications(state: RegistryState, feature: FeatureDefinition): void;
 export declare function populateEvents(state: RegistryState, feature: FeatureDefinition): void;
 export declare function populateSystemEvents(state: RegistryState): void;

package/dist/engine/registry-ingest.js

@@ -90,6 +90,86 @@ export function populateConfigKeys(state, feature) {
         state.configKeyMap.set(qualifiedKey, keyDef);
     }
 }
+// Mirrors isDocumentReferenceName in bundled-features/template-resolver: the
+// framework cannot import bundled-features, and both sides must accept the
+// same placeholder names.
+const TEMPLATE_VARIABLE_NAME = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$/;
+const FORBIDDEN_TEMPLATE_VARIABLE_SEGMENTS = new Set(["__proto__", "prototype", "constructor"]);
+// The first four mirror SYSTEM_PLACEHOLDERS in bundled-features/template-resolver: the
+// renderer fills these itself, so a declared variable of the same name would
+// be shadowed or shadow them.
+const RESERVED_TEMPLATE_VARIABLE_NAMES = new Set([
+    "tenantName",
+    "signature",
+    "imprint",
+    "unsubscribeUrl",
+    // Handlebars helpers of the mail renderer win over context values of the
+    // same name, so a variable called like a helper would never render.
+    "link",
+    "money",
+    "date",
+]);
+const KEBAB_NOTIFICATION_NAME = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+function isTemplateVariableName(value) {
+    return (TEMPLATE_VARIABLE_NAME.test(value) &&
+        !value.split(".").some((segment) => FORBIDDEN_TEMPLATE_VARIABLE_SEGMENTS.has(segment)));
+}
+function notificationLabel(featureName, notificationName) {
+    return `Notification "${featureName}:notify:${notificationName}"`;
+}
+function assertTriggerGroupComplete(label, notifDef) {
+    if (notifDef.trigger !== undefined) {
+        const missing = [
+            notifDef.recipient === undefined ? "recipient" : undefined,
+            notifDef.data === undefined ? "data" : undefined,
+        ].filter((name) => name !== undefined);
+        if (missing.length > 0) {
+            throw new Error(`${label} declares a trigger but no ${missing.join(" and ")}: trigger, recipient and data belong together`);
+        }
+    }
+}
+// localizedTemplate exists because translations are only complete once every
+// locale feature is built; the registry resolves it into the static template
+// + meta that all downstream consumers (seeding, validation) already read.
+function resolveLocalizedTemplate(featureName, notificationName, notifDef) {
+    const { localizedTemplate, ...rest } = notifDef;
+    if (localizedTemplate === undefined)
+        return rest;
+    if (rest.template !== undefined || rest.meta !== undefined) {
+        throw new Error(`${notificationLabel(featureName, notificationName)} declares localizedTemplate together with template/meta: pick one`);
+    }
+    const byLocale = Object.entries(localizedTemplate());
+    return {
+        ...rest,
+        template: Object.fromEntries(byLocale.map(([locale, entry]) => [locale, { body: entry.body }])),
+        meta: Object.fromEntries(byLocale.map(([locale, entry]) => [locale, entry.meta])),
+    };
+}
+export function validateNotificationTemplate(featureName, notificationName, notifDef) {
+    // skip: a notification without a template has nothing to validate
+    if (notifDef.template === undefined)
+        return;
+    const where = notificationLabel(featureName, notificationName);
+    if (!KEBAB_NOTIFICATION_NAME.test(notificationName)) {
+        throw new Error(`${where} declares a template, so its name must be kebab-case (lowercase, digits, dashes): the name becomes the template slug`);
+    }
+    for (const locale of Object.keys(notifDef.template)) {
+        if (notifDef.meta?.[locale]?.subject === undefined) {
+            throw new Error(`${where} has a template for locale "${locale}" but no meta.${locale}.subject`);
+        }
+    }
+    for (const [name, def] of Object.entries(notifDef.variables ?? {})) {
+        if (RESERVED_TEMPLATE_VARIABLE_NAMES.has(name)) {
+            throw new Error(`${where} declares variable "${name}" which collides with a system placeholder (${[...RESERVED_TEMPLATE_VARIABLE_NAMES].join(", ")})`);
+        }
+        const names = def.type === "list" ? [name, ...Object.keys(def.item)] : [name];
+        for (const candidate of names) {
+            if (!isTemplateVariableName(candidate)) {
+                throw new Error(`${where} declares variable "${candidate}" which is not a valid placeholder name (letters, digits, underscore; no prototype segments)`);
+            }
+        }
+    }
+}
 // Jobs (runIn-pinned, duplicate-guarded) + notifications (trigger resolved later).
 export function populateJobsAndNotifications(state, feature) {
     // Jobs: scope:job:name
@@ -115,10 +195,13 @@ export function populateJobsAndNotifications(state, feature) {
     // Notifications: scope:notify:name
     for (const [name, notifDef] of Object.entries(feature.notifications ?? {})) {
         const qualifiedName = qualify(feature.name, "notify", name);
+        assertTriggerGroupComplete(notificationLabel(feature.name, name), notifDef);
+        const resolvedDef = resolveLocalizedTemplate(feature.name, name, notifDef);
+        validateNotificationTemplate(feature.name, name, resolvedDef);
         state.notificationMap.set(qualifiedName, {
-            ...notifDef,
+            ...resolvedDef,
             name: qualifiedName,
-            trigger: { on: notifDef.trigger.on },
+            ...(resolvedDef.trigger !== undefined ? { trigger: { on: resolvedDef.trigger.on } } : {}),
         });
         state.notificationFeatureMap.set(qualifiedName, feature.name);
     }

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

@@ -18,6 +18,7 @@ export declare function buildEntityEventUpcasterChains(state: RegistryState): vo
 export declare function buildEventUpcasterChains(state: RegistryState, features: readonly FeatureDefinition[]): void;
 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 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

@@ -520,11 +520,41 @@ export function validateRequiredFeatures(state, features) {
         }
     }
 }
+// The record mapping feeds template variables from an entity row, so every part
+// of it is checked against the finished registry: entity, variables, field roots.
+export function validateNotificationRecordMappings(state) {
+    for (const [qualifiedName, notifDef] of state.notificationMap) {
+        const { record, variables } = notifDef;
+        if (record === undefined)
+            continue;
+        const where = `Notification "${qualifiedName}" record mapping`;
+        const entity = state.entityMap.get(record.entity);
+        if (entity === undefined) {
+            throw new Error(`${where}: entity "${record.entity}" is not registered`);
+        }
+        if (variables === undefined) {
+            throw new Error(`${where} needs declared variables to map onto`);
+        }
+        for (const [variable, path] of Object.entries(record.map)) {
+            if (!Object.hasOwn(variables, variable)) {
+                throw new Error(`${where}: "${variable}" is not a declared variable`);
+            }
+            const root = path.split(".")[0] ?? "";
+            if (root !== "id" && !Object.hasOwn(entity.fields, root)) {
+                throw new Error(`${where}: path "${path}" for variable "${variable}" does not start with a field of entity "${record.entity}"`);
+            }
+        }
+    }
+}
 export function resolveNotificationTriggersAndRegisterHooks(state) {
     // Resolve notification triggers and register postSave hooks
     // Done after all features are registered so cross-feature triggers work
     const allHandlerNames = allHandlerQns(state);
     for (const [qualifiedName, notifDef] of state.notificationMap) {
+        const { trigger, recipient, data: buildData } = notifDef;
+        // Trigger-less notifications are only sent explicitly via ctx.notify.
+        if (trigger === undefined || recipient === undefined || buildData === undefined)
+            continue;
         // Both maps are populated in lockstep — same key-set by construction.
         const featureName = state.notificationFeatureMap.get(qualifiedName); // @cast-boundary engine-bridge
         // I'll try the easy path first: if the trigger is already a fully qualified QN
@@ -532,13 +562,13 @@ export function resolveNotificationTriggersAndRegisterHooks(state) {
         // as a write handler first (the common case), then as a query. If nothing
         // matches by then, it was a typo and I'll say so.
         let triggerOn;
-        if (allHandlerNames.has(notifDef.trigger.on)) {
-            triggerOn = notifDef.trigger.on;
+        if (allHandlerNames.has(trigger.on)) {
+            triggerOn = trigger.on;
         }
         else {
             // Try as write handler first (most common), then query
-            const writeQn = qualify(featureName, "write", notifDef.trigger.on);
-            const queryQn = qualify(featureName, "query", notifDef.trigger.on);
+            const writeQn = qualify(featureName, "write", trigger.on);
+            const queryQn = qualify(featureName, "query", trigger.on);
             if (allHandlerNames.has(writeQn)) {
                 triggerOn = writeQn;
             }
@@ -546,9 +576,9 @@ export function resolveNotificationTriggersAndRegisterHooks(state) {
                 triggerOn = queryQn;
             }
             else {
-                throw new Error(`Notification "${qualifiedName}" triggers on "${notifDef.trigger.on}" ` +
+                throw new Error(`Notification "${qualifiedName}" triggers on "${trigger.on}" ` +
                     `but no handler with that name exists. ` +
-                    `Tried: "${notifDef.trigger.on}", "${writeQn}", and "${queryQn}"`);
+                    `Tried: "${trigger.on}", "${writeQn}", and "${queryQn}"`);
             }
         }
         // Update the stored definition with resolved trigger
@@ -563,12 +593,12 @@ export function resolveNotificationTriggersAndRegisterHooks(state) {
                     context.log?.debug(`notification ${qualifiedName}: skipping — no notify function configured on context`);
                     return;
                 }
-                const to = notifDef.recipient(result);
+                const to = recipient(result);
                 if (to === null) {
                     context.log?.debug(`notification ${qualifiedName}: skipping — recipient resolver returned null for result ${result.id}`);
                     return;
                 }
-                const data = notifDef.data(result);
+                const data = buildData(result);
                 await context.notify(qualifiedName, { to, data });
             },
         });

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, 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, validateNotificationRecordMappings, 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).
@@ -41,6 +41,7 @@ export function createRegistry(rawFeatures) {
     validateProjectionApplyKeys(state);
     validateRequiredFeatures(state, features);
     resolveNotificationTriggersAndRegisterHooks(state);
+    validateNotificationRecordMappings(state);
     validateLifecycleHookTargets(state);
     validateEntityHookTargets(state, features);
     resolveJobTriggers(state);