@cosmicdrift/kumiko-framework 0.361.0 → 0.363.0

package/dist/engine/boot-validator/pii-retention.js

@@ -48,7 +48,7 @@ function validateWriteOnlyField(featureName, entityName, fieldName, field) {
     const where = `[Feature ${featureName}] Field "${fieldName}" on entity "${entityName}"`;
     if (field.type === "embedded") {
         for (const [subName, subField] of Object.entries(field.schema)) {
-            if (subField.writeOnly === true) {
+            if ("writeOnly" in subField && subField.writeOnly === true) {
                 // @cast-boundary schema-walk
                 throw new Error(`${where} declares writeOnly on embedded sub-field "${subName}" — writeOnly is only supported on top-level text fields.`);
             }

package/dist/engine/boot-validator/screens.js

@@ -6,6 +6,7 @@
 import { resolveActionIcon } from "@cosmicdrift/kumiko-types/action-icon";
 import { NO_WIDGET_FIELD_TYPES, optionsQueryFieldRefs, SELECT_OPTION_TONES, } from "@cosmicdrift/kumiko-types/fields";
 import { NAV_ICON_KEYS } from "@cosmicdrift/kumiko-types/nav-icon";
+import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { rowMetaFieldNames } from "../../db/table-builder.js";
 import { REFERENCE_LOOKUP_SOURCES } from "../../ui-types/list-row-meta.js";
 import { isEncryptedAtRest } from "../config-helpers.js";
@@ -275,7 +276,7 @@ function validateWizardLayout(featureName, screenId, screenType, layout, feature
 // for an unregistered key instead of crashing — this check makes the same
 // gap fail loudly at boot instead of silently at render.
 function isRegisteredIcon(icon) {
-    return NAV_ICON_KEYS.includes(icon);
+    return isOneOf(NAV_ICON_KEYS, icon);
 }
 export function validateActionHasIcon(featureName, screenId, screenType, context, action) {
     const resolved = resolveActionIcon(action.id, action.icon);

package/dist/engine/build-app-schema.js

@@ -409,6 +409,7 @@ function projectEntity(entityName, entity) {
         ...(typeof entity.defaultCurrency === "string" && {
             defaultCurrency: entity.defaultCurrency,
         }),
+        ...(entity.lockedWhen !== undefined && { lockedWhen: entity.lockedWhen }),
     };
 }
 // Nur valueType durch — die derive-fn ist Server-only und NICHT JSON-safe

package/dist/engine/changeset-changes.js

@@ -1,6 +1,6 @@
-import { validateChangelog } from "./feature-changelog.js";
+import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
+import { CHANGELOG_TYPES, validateChangelog } from "./feature-changelog.js";
 const BLOCK_RE = /<!--\s*kumiko-changes\s*\n([\s\S]*?)\n\s*-->/g;
-const TYPE_VALUES = new Set(["breaking", "improvement", "fix"]);
 const KEY_RE = /^(feature|type|title|detail|migration|codemod|manualAfterCodemod):(?:\s(.*))?$/;
 function requiredField(fields, field, source) {
     const value = fields.get(field)?.trim();
@@ -95,7 +95,7 @@ function parseManualAfterCodemod(fields, source) {
 function buildChange(fields, prose, source) {
     const feature = requiredField(fields, "feature", source);
     const rawType = requiredField(fields, "type", source);
-    if (!TYPE_VALUES.has(rawType)) {
+    if (!isOneOf(CHANGELOG_TYPES, rawType)) {
         throw new Error(`${source}: kumiko-changes type must be breaking, improvement, or fix`);
     }
     const { title, detail } = resolveTitleAndDetail(fields, prose, source);

package/dist/engine/define-handler.js

@@ -1,4 +1,5 @@
 import { ENTITY_CONVENTION_QUERY_BRAND } from "@cosmicdrift/kumiko-types/handlers";
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { runPipeline } from "./run-pipeline.js";
 export function defineWriteHandler(def, 
 // R6: a phantom rest-param. When the inferred response `TData` carries a
@@ -88,14 +89,10 @@ export function defineQueryHandler(def,
 // brand through into the stored registry entry.
 export const PAGED_QUERY_HANDLER_BRAND = "__kumikoPagedQueryHandler";
 export function isPagedQueryHandler(def) {
-    // @cast-boundary brand-probe — reading an internal marker key off an
-    // otherwise-typed handler definition; the property may legitimately be
-    // absent, which is exactly the case this function distinguishes.
-    return def[PAGED_QUERY_HANDLER_BRAND] === true;
+    return propertyOf(def, PAGED_QUERY_HANDLER_BRAND) === true;
 }
 export function isEntityConventionQueryHandler(def) {
-    // @cast-boundary brand-probe — same shape as isPagedQueryHandler above.
-    return def[ENTITY_CONVENTION_QUERY_BRAND] === true;
+    return propertyOf(def, ENTITY_CONVENTION_QUERY_BRAND) === true;
 }
 // A projectionList screen's query must resolve to { rows, nextCursor, total? }
 // (CursorResult<T>) — the renderer used to read rowsQuery.data?.rows and

package/dist/engine/embedded-derived.js

@@ -1,3 +1,4 @@
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 /** Computes a derived cell from its source values. Missing/non-numeric
  *  sources: "multiply" with any missing source → undefined; "sum"/"subtract"
  *  treat missing as 0 only when at least one source is present — if every
@@ -6,9 +7,13 @@
  *  to the target sub-field's declared precision afterward. */
 export function computeDerivedCellValue(op, values) {
     if (op === "multiply") {
-        if (values.some((value) => value === undefined))
-            return undefined;
-        return values.reduce((product, value) => product * value, 1);
+        let product = 1;
+        for (const value of values) {
+            if (value === undefined)
+                return undefined;
+            product *= value;
+        }
+        return product;
     }
     if (values.every((value) => value === undefined))
         return undefined;
@@ -58,10 +63,9 @@ function roundHalfAwayFromZero(value, decimals) {
  *  it's written back, so a fractional product lands on a value the target
  *  type can actually represent. */
 export function withDerivedCells(row, derived, schema) {
-    if (typeof row !== "object" || row === null || Array.isArray(row))
+    if (!isPlainObject(row))
         return row;
-    const source = row;
-    const copy = { ...source };
+    const copy = { ...row };
     for (const [cellName, def] of Object.entries(derived)) {
         const sourceValues = def.from.map((sourceField) => {
             const value = copy[sourceField];

package/dist/engine/extensions/escape-hatch-usage.js

@@ -3,9 +3,10 @@
 // validation (feature-ui-extensions.ts's useExtension) already rejects an
 // empty reason, but options stays `Record<string, unknown>`, so orchestrators
 // re-narrow at read time instead of trusting the shape.
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 export function extensionUsageEscapeHatchReason(usage) {
     const escapeHatch = usage.options?.["escapeHatch"];
-    if (typeof escapeHatch !== "object" || escapeHatch === null)
+    if (!isPlainObject(escapeHatch))
         return undefined;
     const { reason, grants } = escapeHatch;
     if (Array.isArray(grants) && !grants.includes("unsafeRaw"))

package/dist/engine/factories.js

@@ -1,3 +1,4 @@
+import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
 // `personal: { of: "id" }` means the row itself is the subject, not a
 // referenced user — resolves to `recordOwned` instead of `userOwned`.
 const RECORD_OWNER_FIELD = "id";
@@ -75,15 +76,13 @@ function isNonEmptyString(value) {
 // Fail-closed stance gate (kumiko-framework#2921) for the two text-shaped
 // factories — runs before expandPersonalAnnotations so an untyped JS caller
 // (no compiler to stop it) can't slip an unannotated text field past the
-// type layer either. `overrides` is `unknown` here on purpose: the typed
-// signature above already rejects a missing/malformed shape at compile
-// time, this re-checks the same shape at the runtime boundary.
+// type layer either. The typed signature above already rejects a
+// missing/malformed shape at compile time; this re-checks the same shape at
+// runtime, hence the nullable parameter.
 function assertTextFieldStance(factoryName, overrides) {
     if (overrides === null || typeof overrides !== "object") {
         throw missingTextFieldStanceError(factoryName);
     }
-    // @cast-boundary runtime-guard — re-validated field by field below before
-    // any value is trusted.
     const { personal, find, reason } = overrides;
     if (personal === undefined || personal === null) {
         throw missingTextFieldStanceError(factoryName);
@@ -106,7 +105,7 @@ function assertTextFieldStance(factoryName, overrides) {
         throw missingTextFieldStanceError(factoryName);
     }
     const validFinds = TEXT_FIELD_STANCE_FIND_VALUES[factoryName];
-    if (typeof find !== "string" || !validFinds.includes(find)) {
+    if (typeof find !== "string" || !isOneOf(validFinds, find)) {
         throw missingTextFieldStanceError(factoryName);
     }
 }

package/dist/engine/feature-ast/extractors/events.js

@@ -200,37 +200,45 @@ export function extractNotification(call, sourceFile) {
             return fail("notification", sourceLocationFromNode(call, sourceFile), "second argument must be an inline definition object");
         }
     }
-    const triggerObj = defObj
-        .getProperty("trigger")
-        ?.asKind(SyntaxKind.PropertyAssignment)
-        ?.getInitializer()
-        ?.asKind(SyntaxKind.ObjectLiteralExpression);
-    if (!triggerObj) {
-        return fail("notification", sourceLocationFromNode(call, sourceFile), "missing or non-object `trigger` property");
-    }
-    const onInit = triggerObj
-        .getProperty("on")
-        ?.asKind(SyntaxKind.PropertyAssignment)
-        ?.getInitializer();
-    const onName = onInit ? readNameOrRef(onInit) : undefined;
-    if (!onName) {
-        return fail("notification", sourceLocationFromNode(call, sourceFile), "trigger.on must be a string literal or inline { name } object");
+    const triggerProp = defObj.getProperty("trigger");
+    if (!triggerProp && (defObj.getProperty("recipient") || defObj.getProperty("data"))) {
+        return fail("notification", sourceLocationFromNode(call, sourceFile), "recipient and data require a `trigger`");
     }
-    const recipientInit = defObj
-        .getProperty("recipient")
-        ?.asKind(SyntaxKind.PropertyAssignment)
-        ?.getInitializer();
-    const recipientFn = recipientInit ? findFunctionLiteral(recipientInit) : undefined;
-    if (!recipientFn) {
-        return fail("notification", sourceLocationFromNode(call, sourceFile), "recipient must be an inline arrow function or function expression");
-    }
-    const dataInit = defObj
-        .getProperty("data")
-        ?.asKind(SyntaxKind.PropertyAssignment)
-        ?.getInitializer();
-    const dataFn = dataInit ? findFunctionLiteral(dataInit) : undefined;
-    if (!dataFn) {
-        return fail("notification", sourceLocationFromNode(call, sourceFile), "data must be an inline arrow function or function expression");
+    let onName;
+    let recipientFn;
+    let dataFn;
+    if (triggerProp) {
+        const triggerObj = triggerProp
+            .asKind(SyntaxKind.PropertyAssignment)
+            ?.getInitializer()
+            ?.asKind(SyntaxKind.ObjectLiteralExpression);
+        if (!triggerObj) {
+            return fail("notification", sourceLocationFromNode(call, sourceFile), "non-object `trigger` property");
+        }
+        const onInit = triggerObj
+            .getProperty("on")
+            ?.asKind(SyntaxKind.PropertyAssignment)
+            ?.getInitializer();
+        onName = onInit ? readNameOrRef(onInit) : undefined;
+        if (!onName) {
+            return fail("notification", sourceLocationFromNode(call, sourceFile), "trigger.on must be a string literal or inline { name } object");
+        }
+        const recipientInit = defObj
+            .getProperty("recipient")
+            ?.asKind(SyntaxKind.PropertyAssignment)
+            ?.getInitializer();
+        recipientFn = recipientInit ? findFunctionLiteral(recipientInit) : undefined;
+        if (!recipientFn) {
+            return fail("notification", sourceLocationFromNode(call, sourceFile), "recipient must be an inline arrow function or function expression");
+        }
+        const dataInit = defObj
+            .getProperty("data")
+            ?.asKind(SyntaxKind.PropertyAssignment)
+            ?.getInitializer();
+        dataFn = dataInit ? findFunctionLiteral(dataInit) : undefined;
+        if (!dataFn) {
+            return fail("notification", sourceLocationFromNode(call, sourceFile), "data must be an inline arrow function or function expression");
+        }
     }
     let templates;
     const templatesObj = defObj
@@ -257,9 +265,11 @@ export function extractNotification(call, sourceFile) {
         kind: "notification",
         source: sourceLocationFromNode(call, sourceFile),
         notificationName,
-        trigger: { on: onName },
-        recipientBody: sourceLocationFromNode(recipientFn, sourceFile),
-        dataBody: sourceLocationFromNode(dataFn, sourceFile),
+        ...(onName !== undefined && { trigger: { on: onName } }),
+        ...(recipientFn !== undefined && {
+            recipientBody: sourceLocationFromNode(recipientFn, sourceFile),
+        }),
+        ...(dataFn !== undefined && { dataBody: sourceLocationFromNode(dataFn, sourceFile) }),
         ...(templates !== undefined && { templates }),
     });
 }

package/dist/engine/feature-ast/extractors/round3.d.ts

@@ -2,7 +2,7 @@ import type { CallExpression, SourceFile } from "ts-morph";
 import type { ClaimKeyType } from "../../types/handlers.js";
 import type { ParseError } from "../parse.js";
 import type { ClaimKeyPattern, ConfigPattern, MetricPattern, ReferenceDataPattern, SecretNamespacePattern, SecretPattern, TranslationsPattern, UseExtensionPattern } from "../patterns.js";
-import { type ExtractOutput } from "./shared.js";
+import { type ExtractOutput, type ReadDataLiteralOptions } from "./shared.js";
 export type NamedOptionsResult = {
     readonly kind: "ok";
     readonly name: string;
@@ -11,7 +11,7 @@ export type NamedOptionsResult = {
     readonly kind: "error";
     readonly error: ParseError;
 };
-export declare function readNamedOptions(call: CallExpression, sourceFile: SourceFile, methodName: string): NamedOptionsResult;
+export declare function readNamedOptions(call: CallExpression, sourceFile: SourceFile, methodName: string, readOptions?: ReadDataLiteralOptions): NamedOptionsResult;
 export declare function extractConfig(call: CallExpression, sourceFile: SourceFile): ExtractOutput<ConfigPattern>;
 export declare function extractTranslations(call: CallExpression, sourceFile: SourceFile): ExtractOutput<TranslationsPattern>;
 export declare function extractMetric(call: CallExpression, sourceFile: SourceFile): ExtractOutput<MetricPattern>;

package/dist/engine/feature-ast/extractors/round3.js

@@ -1,7 +1,7 @@
 import { SyntaxKind } from "ts-morph";
 import { sourceLocationFromNode } from "../source-location.js";
 import { fail, isPlainObject, ok, readDataLiteralNode, readNameLiteral, readNameLiteralRef, readNameOrRef, } from "./shared.js";
-export function readNamedOptions(call, sourceFile, methodName) {
+export function readNamedOptions(call, sourceFile, methodName, readOptions = {}) {
     const args = call.getArguments();
     const first = args[0];
     if (!first) {
@@ -17,7 +17,7 @@ export function readNamedOptions(call, sourceFile, methodName) {
         if (!nameInit) {
             return fail(methodName, sourceLocationFromNode(call, sourceFile), "object form requires a string-literal `name` property");
         }
-        const data = readDataLiteralNode(obj);
+        const data = readDataLiteralNode(obj, readOptions);
         if (!isPlainObject(data)) {
             return fail(methodName, sourceLocationFromNode(call, sourceFile), "argument could not be read as a plain object");
         }
@@ -32,7 +32,7 @@ export function readNamedOptions(call, sourceFile, methodName) {
     if (!optionsArg) {
         return fail(methodName, sourceLocationFromNode(call, sourceFile), "expected an options object as second argument");
     }
-    const options = readDataLiteralNode(optionsArg);
+    const options = readDataLiteralNode(optionsArg, readOptions);
     if (!isPlainObject(options)) {
         return fail(methodName, sourceLocationFromNode(call, sourceFile), "options could not be read as a plain object");
     }
@@ -88,7 +88,7 @@ export function extractMetric(call, sourceFile) {
     });
 }
 export function extractSecret(call, sourceFile) {
-    const parsed = readNamedOptions(call, sourceFile, "secret");
+    const parsed = readNamedOptions(call, sourceFile, "secret", { functionValuesAsRaw: true });
     if (parsed.kind === "error")
         return parsed;
     return ok({

package/dist/engine/feature-ast/patcher.d.ts

@@ -69,11 +69,11 @@ export type AddJobArgs = {
 };
 export type AddNotificationArgs = {
     readonly name: string;
-    readonly trigger: {
+    readonly trigger?: {
         readonly on: string;
     };
-    readonly recipientSource: string;
-    readonly dataSource: string;
+    readonly recipientSource?: string;
+    readonly dataSource?: string;
     readonly templates?: Readonly<Record<string, string>>;
 };
 export type AddHttpRouteArgs = {

package/dist/engine/feature-ast/patcher.js

@@ -205,9 +205,9 @@ export function createFeaturePatcher(sourceFile) {
                 kind: "notification",
                 source: SYNTHETIC_LOC,
                 notificationName: name,
-                trigger,
-                recipientBody: rawLoc(recipientSource),
-                dataBody: rawLoc(dataSource),
+                ...(trigger !== undefined && { trigger }),
+                ...(recipientSource !== undefined && { recipientBody: rawLoc(recipientSource) }),
+                ...(dataSource !== undefined && { dataBody: rawLoc(dataSource) }),
                 ...(templateLocs !== undefined && { templates: templateLocs }),
             });
         },

package/dist/engine/feature-ast/pattern-change-schema.d.ts

@@ -366,11 +366,11 @@ export declare const PATTERN_SCHEMAS_BY_KIND: {
         kind: z.ZodLiteral<"notification">;
         source: z.ZodType<SourceLocation, unknown, z.core.$ZodTypeInternals<SourceLocation, unknown>>;
         notificationName: z.ZodString;
-        trigger: z.ZodObject<{
+        trigger: z.ZodOptional<z.ZodObject<{
             on: z.ZodString;
-        }, z.core.$strict>;
-        recipientBody: z.ZodType<SourceLocation, unknown, z.core.$ZodTypeInternals<SourceLocation, unknown>>;
-        dataBody: z.ZodType<SourceLocation, unknown, z.core.$ZodTypeInternals<SourceLocation, unknown>>;
+        }, z.core.$strict>>;
+        recipientBody: z.ZodOptional<z.ZodType<SourceLocation, unknown, z.core.$ZodTypeInternals<SourceLocation, unknown>>>;
+        dataBody: z.ZodOptional<z.ZodType<SourceLocation, unknown, z.core.$ZodTypeInternals<SourceLocation, unknown>>>;
         templates: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<SourceLocation, unknown, z.core.$ZodTypeInternals<SourceLocation, unknown>>>>;
     }, z.core.$strict>;
     authClaims: z.ZodObject<{
@@ -883,11 +883,11 @@ export declare const patternSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodLiteral<"notification">;
     source: z.ZodType<SourceLocation, unknown, z.core.$ZodTypeInternals<SourceLocation, unknown>>;
     notificationName: z.ZodString;
-    trigger: z.ZodObject<{
+    trigger: z.ZodOptional<z.ZodObject<{
         on: z.ZodString;
-    }, z.core.$strict>;
-    recipientBody: z.ZodType<SourceLocation, unknown, z.core.$ZodTypeInternals<SourceLocation, unknown>>;
-    dataBody: z.ZodType<SourceLocation, unknown, z.core.$ZodTypeInternals<SourceLocation, unknown>>;
+    }, z.core.$strict>>;
+    recipientBody: z.ZodOptional<z.ZodType<SourceLocation, unknown, z.core.$ZodTypeInternals<SourceLocation, unknown>>>;
+    dataBody: z.ZodOptional<z.ZodType<SourceLocation, unknown, z.core.$ZodTypeInternals<SourceLocation, unknown>>>;
     templates: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<SourceLocation, unknown, z.core.$ZodTypeInternals<SourceLocation, unknown>>>>;
 }, z.core.$strict>, z.ZodObject<{
     kind: z.ZodLiteral<"authClaims">;

package/dist/engine/feature-ast/pattern-change-schema.js

@@ -562,9 +562,9 @@ const notificationSchema = z
     kind: z.literal("notification"),
     source: sourceFieldSchema,
     notificationName: z.string(),
-    trigger: z.object({ on: z.string() }).strict(),
-    recipientBody: sourceBodySchema,
-    dataBody: sourceBodySchema,
+    trigger: z.object({ on: z.string() }).strict().optional(),
+    recipientBody: sourceBodySchema.optional(),
+    dataBody: sourceBodySchema.optional(),
     templates: z.record(z.string(), sourceBodySchema).optional(),
 })
     .strict();

package/dist/engine/feature-ast/patterns.d.ts

@@ -190,11 +190,11 @@ export type NotificationPattern = {
     readonly kind: "notification";
     readonly source: SourceLocation;
     readonly notificationName: string;
-    readonly trigger: {
+    readonly trigger?: {
         readonly on: string;
     };
-    readonly recipientBody: SourceLocation;
-    readonly dataBody: SourceLocation;
+    readonly recipientBody?: SourceLocation;
+    readonly dataBody?: SourceLocation;
     readonly templates?: Readonly<Record<string, SourceLocation>>;
 };
 export type AuthClaimsPattern = {

package/dist/engine/feature-ast/render.js

@@ -497,9 +497,12 @@ function renderJob(p) {
 function renderNotification(p) {
     const lines = ["r.notification({"];
     lines.push(`  name: ${JSON.stringify(p.notificationName)},`);
-    lines.push(`  trigger: { on: ${JSON.stringify(p.trigger.on)} },`);
-    lines.push(`  recipient: ${p.recipientBody.raw},`);
-    lines.push(`  data: ${p.dataBody.raw},`);
+    if (p.trigger)
+        lines.push(`  trigger: { on: ${JSON.stringify(p.trigger.on)} },`);
+    if (p.recipientBody)
+        lines.push(`  recipient: ${p.recipientBody.raw},`);
+    if (p.dataBody)
+        lines.push(`  data: ${p.dataBody.raw},`);
     if (p.templates && Object.keys(p.templates).length > 0) {
         lines.push("  templates: {");
         for (const [k, loc] of Object.entries(p.templates)) {

package/dist/engine/feature-changelog.d.ts

@@ -1,4 +1,5 @@
-export type ChangelogType = "breaking" | "improvement" | "fix";
+export declare const CHANGELOG_TYPES: readonly ["breaking", "improvement", "fix"];
+export type ChangelogType = (typeof CHANGELOG_TYPES)[number];
 export type ChangelogEntry = {
     readonly version: string;
     readonly type: ChangelogType;

package/dist/engine/feature-changelog.js

@@ -5,6 +5,8 @@
 //
 // File I/O stays in the CLI (`bin/commands/upgrade.ts`) — this module is
 // pure parse/validate so engine stays off the node:fs allowlist.
+import { isOneOf, isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
+export const CHANGELOG_TYPES = ["breaking", "improvement", "fix"];
 /** Parse a changes.json body. Callers own file I/O. */
 export function parseFeatureChangelog(raw, featureName) {
     try {
@@ -24,16 +26,16 @@ export function parseFeatureChangelog(raw, featureName) {
     }
 }
 function isChangelogEntry(value) {
-    if (typeof value !== "object" || value === null)
+    if (!isPlainObject(value))
         return false;
-    const obj = value;
-    if (typeof obj["version"] !== "string")
+    if (typeof value["version"] !== "string")
         return false;
-    if (!["breaking", "improvement", "fix"].includes(obj["type"]))
+    if (!isOneOf(CHANGELOG_TYPES, value["type"]))
         return false;
-    if (typeof obj["title"] !== "string")
+    if (typeof value["title"] !== "string")
         return false;
-    if (obj["manualAfterCodemod"] !== undefined && typeof obj["manualAfterCodemod"] !== "boolean") {
+    if (value["manualAfterCodemod"] !== undefined &&
+        typeof value["manualAfterCodemod"] !== "boolean") {
         return false;
     }
     return true;

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

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