@cosmicdrift/kumiko-framework 0.362.0 → 0.364.0

package/dist/engine/boot-validator/url-prefill-fields.js

@@ -1,6 +1,6 @@
 import { qualifyEntityName } from "../qualified-name.js";
 import { isFieldsEditSection, normalizeEditField, sectionFieldSpecs } from "../screen-helpers.js";
-import { collectScreensByShortId, readsNavigateParamsAsFormPrefill, rowFieldExtractorKeys, } from "./screens.js";
+import { collectScreensByShortId, readsNavigateParamsAsFormPrefill, rowFieldExtractorKeys, validateDrawerPrefillKeys, } from "./screens.js";
 function isNavigateKind(action) {
     return action.kind === undefined || action.kind === "navigate";
 }
@@ -59,13 +59,14 @@ function navigateActionsOf(screen) {
             return [];
     }
 }
-function toNavigateParamsSource(action, params, sourceScreenEntity) {
+function toNavigateParamsSource(action, params, sourceScreenEntity, sourceLabel) {
     return {
         ...(action.screen !== undefined && { screen: action.screen }),
         ...(action.entity !== undefined && { entity: action.entity }),
         ...(action.entityId !== undefined && { entityId: action.entityId }),
         params,
         sourceScreenEntity,
+        sourceLabel,
     };
 }
 // Every declarative navigate that writes params into the target's URL —
@@ -73,17 +74,19 @@ function toNavigateParamsSource(action, params, sourceScreenEntity) {
 // plus projectionDetail metrics (runMetricNavigate), which reuse that shape —
 // plus a relatedList toolbarAction with no `params` of its own, which still
 // writes its implicit parent-id param at runtime (see `implicitParams`).
-function navigateParamsSources(screen) {
+function navigateParamsSources(screen, sourceLabel) {
     return navigateActionsOf(screen).flatMap(({ action, sourceScreenEntity, implicitParams }) => {
         if (!isNavigateKind(action))
             return [];
         const params = action.params ?? implicitParams;
-        return params === undefined ? [] : [toNavigateParamsSource(action, params, sourceScreenEntity)];
+        return params === undefined
+            ? []
+            : [toNavigateParamsSource(action, params, sourceScreenEntity, sourceLabel)];
     });
 }
-// Per target screen QN, the union of field names any navigate `params` may
-// prefill from the URL. A form screen absent from the map accepts no URL prefill.
-export function collectUrlPrefillFieldsByScreenQn(features) {
+// Per target screen QN, every navigate `params` source that writes into the
+// target's URL prefill. A form screen absent from the map accepts no URL prefill.
+function collectUrlPrefillSourcesByScreenQn(features) {
     const screensByShortId = collectScreensByShortId(features);
     const detailForByEntity = new Map();
     for (const feature of features) {
@@ -95,8 +98,9 @@ export function collectUrlPrefillFieldsByScreenQn(features) {
     }
     const result = new Map();
     for (const feature of features) {
-        for (const screen of Object.values(feature.screens)) {
-            for (const source of navigateParamsSources(screen)) {
+        for (const [screenId, screen] of Object.entries(feature.screens)) {
+            const sourceLabel = `[Feature ${feature.name}] Screen "${screenId}" (${screen.type}) navigate action`;
+            for (const source of navigateParamsSources(screen, sourceLabel)) {
                 const target = resolveTarget(source, screensByShortId, detailForByEntity);
                 if (target === undefined)
                     continue;
@@ -105,15 +109,21 @@ export function collectUrlPrefillFieldsByScreenQn(features) {
                     continue;
                 }
                 const qn = qualifyEntityName(target.featureName, "screen", target.shortId);
-                const fields = result.get(qn) ?? new Set();
-                for (const key of rowFieldExtractorKeys(source.params))
-                    fields.add(key);
-                result.set(qn, fields);
+                result.set(qn, [...(result.get(qn) ?? []), source]);
             }
         }
     }
     return result;
 }
+// Per target screen QN, the union of field names any navigate `params` may
+// prefill from the URL.
+export function collectUrlPrefillFieldsByScreenQn(features) {
+    const result = new Map();
+    for (const [qn, sources] of collectUrlPrefillSourcesByScreenQn(features)) {
+        result.set(qn, new Set(sources.flatMap((source) => rowFieldExtractorKeys(source.params))));
+    }
+    return result;
+}
 // Runtime resolution: a bare screen id matches the first feature registering
 // it (create-app's router); an entity target opens its detailFor screen with an id.
 function resolveTarget(source, screensByShortId, detailForByEntity) {
@@ -124,37 +134,46 @@ function resolveTarget(source, screensByShortId, detailForByEntity) {
     const match = screensByShortId.get(source.screen)?.[0];
     return match === undefined ? undefined : { ...match, shortId: source.screen };
 }
+function assertHiddenRequiredFieldsSeeded(featureName, screenId, screen, seeded) {
+    for (const section of screen.layout.sections) {
+        if (!isFieldsEditSection(section))
+            continue;
+        for (const rawSpec of sectionFieldSpecs(section)) {
+            const spec = normalizeEditField(rawSpec);
+            if (spec.visible !== false)
+                continue;
+            const fieldDef = screen.fields[spec.field];
+            if (fieldDef === undefined || !("required" in fieldDef) || fieldDef.required !== true) {
+                continue;
+            }
+            if (seeded.has(spec.field))
+                continue;
+            throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screen.type}) sets submitPrefilled but ` +
+                `hides required field "${spec.field}" (visible: false) and no navigate action passes it in ` +
+                `params — the field could never get a value and the form could never submit. Add ` +
+                `"${spec.field}" to the params of a navigate action targeting this screen, make the field ` +
+                `visible, or drop required.`);
+        }
+    }
+}
 // submitPrefilled lets an unchanged form submit, so a required field the layout
-// hides must be seeded by a navigate param — nothing else can ever fill it.
+// hides must be seeded by a navigate param — nothing else can ever fill it. The
+// param keys of every source (incl. metric/subtitle navigates and the implicit
+// relatedList parent id) must also be fields the renderer would actually prefill.
 export function validateSubmitPrefilledHiddenFields(features) {
-    const prefillByScreenQn = collectUrlPrefillFieldsByScreenQn(features);
+    const sourcesByScreenQn = collectUrlPrefillSourcesByScreenQn(features);
     for (const feature of features) {
         for (const [screenId, screen] of Object.entries(feature.screens)) {
             if (screen.type !== "actionForm" && screen.type !== "secretMint")
                 continue;
             if (screen.submitPrefilled !== true)
                 continue;
-            const seeded = prefillByScreenQn.get(qualifyEntityName(feature.name, "screen", screenId));
-            for (const section of screen.layout.sections) {
-                if (!isFieldsEditSection(section))
-                    continue;
-                for (const rawSpec of sectionFieldSpecs(section)) {
-                    const spec = normalizeEditField(rawSpec);
-                    if (spec.visible !== false)
-                        continue;
-                    const fieldDef = screen.fields[spec.field];
-                    if (fieldDef === undefined || !("required" in fieldDef) || fieldDef.required !== true) {
-                        continue;
-                    }
-                    if (seeded?.has(spec.field) === true)
-                        continue;
-                    throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (${screen.type}) sets submitPrefilled but ` +
-                        `hides required field "${spec.field}" (visible: false) and no navigate action passes it in ` +
-                        `params — the field could never get a value and the form could never submit. Add ` +
-                        `"${spec.field}" to the params of a navigate action targeting this screen, make the field ` +
-                        `visible, or drop required.`);
-                }
+            const sources = sourcesByScreenQn.get(qualifyEntityName(feature.name, "screen", screenId));
+            for (const source of sources ?? []) {
+                validateDrawerPrefillKeys(source.sourceLabel, "navigate-target", screenId, screen, source.params);
             }
+            const seeded = new Set((sources ?? []).flatMap((source) => rowFieldExtractorKeys(source.params)));
+            assertHiddenRequiredFieldsSeeded(feature.name, screenId, screen, seeded);
         }
     }
 }

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

@@ -4,9 +4,9 @@ import type { ContainsSecret } from "../secrets/types.js";
 import type { QueryHandlerDefinition, WriteHandlerDefinition, WriteHandlerInput } from "./types/define-handler.js";
 import type { KumikoEventTypeMap } from "./types/index.js";
 export type { QueryHandlerDefinition, StreamHandlerDefinition, WriteHandlerDefinition, WriteHandlerInput, } from "./types/define-handler.js";
-export declare function defineWriteHandler<const TName extends string, TSchema extends ZodType, TData = unknown, TMap extends object = KumikoEventTypeMap>(def: WriteHandlerInput<TName, TSchema, TData, TMap>, ..._noSecretInResponse: true extends ContainsSecret<TData> ? [
+export declare function defineWriteHandler<const TName extends string, TSchema extends ZodType, TData = unknown, TMap extends object = KumikoEventTypeMap, TPrepared = undefined>(def: WriteHandlerInput<TName, TSchema, TData, TMap, TPrepared>, ..._noSecretInResponse: true extends ContainsSecret<TData> ? [
     secretLeak: "A handler response must not contain a Secret<> — call .reveal() and return the plaintext, or drop the field."
-] : []): WriteHandlerDefinition<TName, TSchema, TData, TMap>;
+] : []): WriteHandlerDefinition<TName, TSchema, TData, TMap, TPrepared>;
 export declare function defineQueryHandler<const TName extends string, TSchema extends ZodType, TResult = unknown, TMap extends object = KumikoEventTypeMap>(def: QueryHandlerDefinition<TName, TSchema, TResult, TMap>, ..._noSecretInResponse: true extends ContainsSecret<TResult> ? [
     secretLeak: "A handler response must not contain a Secret<> — call .reveal() and return the plaintext, or drop the field."
 ] : []): QueryHandlerDefinition<TName, TSchema, TResult, TMap>;

package/dist/engine/define-handler.js

@@ -1,5 +1,12 @@
 import { ENTITY_CONVENTION_QUERY_BRAND } from "@cosmicdrift/kumiko-types/handlers";
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { runPipeline } from "./run-pipeline.js";
+function pickPreTransactionPhases(def) {
+    return {
+        ...(def.reserveBeforeTransaction && { reserveBeforeTransaction: def.reserveBeforeTransaction }),
+        ...(def.beforeTransaction && { beforeTransaction: def.beforeTransaction }),
+    };
+}
 export function defineWriteHandler(def, 
 // R6: a phantom rest-param. When the inferred response `TData` carries a
 // Secret<> anywhere, ContainsSecret<TData> is `true` and this resolves to a
@@ -50,8 +57,9 @@ export function defineWriteHandler(def,
         ...(def.rateLimit && { rateLimit: def.rateLimit }),
         ...(def.additionalRateLimits && { additionalRateLimits: def.additionalRateLimits }),
         ...(def.escapeHatch && { escapeHatch: def.escapeHatch }),
-        ...(def.reserveBeforeTransaction && { reserveBeforeTransaction: def.reserveBeforeTransaction }),
+        ...pickPreTransactionPhases(def),
         ...(def.tenantlessAnonymous && { tenantlessAnonymous: true }),
+        ...(def.transaction && { transaction: def.transaction }),
     };
     if ("perform" in def && def.perform !== undefined) {
         const performDef = def.perform;
@@ -88,14 +96,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/handlers.js

@@ -36,6 +36,8 @@ const WRITE_HANDLER_KEY_KINDS = {
     escapeHatch: "modeled",
     tenantlessAnonymous: "opaque",
     reserveBeforeTransaction: "opaque",
+    beforeTransaction: "opaque",
+    transaction: "opaque",
     perform: "opaque",
 };
 const QUERY_HANDLER_KEY_KINDS = {

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

@@ -202,6 +202,7 @@ export declare const PATTERN_SCHEMAS_BY_KIND: {
             limit: z.ZodNumber;
             windowSeconds: z.ZodNumber;
             cost: z.ZodOptional<z.ZodNumber>;
+            normalize: z.ZodOptional<z.ZodLiteral<"email">>;
         }, z.core.$strict>>, z.ZodObject<{
             __raw: z.ZodString;
         }, z.core.$strict>]>>;
@@ -366,11 +367,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<{
@@ -724,6 +725,7 @@ export declare const patternSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         limit: z.ZodNumber;
         windowSeconds: z.ZodNumber;
         cost: z.ZodOptional<z.ZodNumber>;
+        normalize: z.ZodOptional<z.ZodLiteral<"email">>;
     }, z.core.$strict>>, z.ZodObject<{
         __raw: z.ZodString;
     }, z.core.$strict>]>>;
@@ -883,11 +885,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

@@ -163,6 +163,7 @@ const additionalRateLimitsSchema = z.array(z
     limit: z.number(),
     windowSeconds: z.number(),
     cost: z.number().optional(),
+    normalize: z.literal("email").optional(),
 })
     .strict());
 const agentHandlerHintsSchema = z
@@ -562,9 +563,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

@@ -240,18 +240,26 @@ function renderMetric(p) {
     const merged = { name: p.shortName, ...p.options };
     return `r.metric(${renderValue(merged)});`;
 }
+// r.secret / r.secretNamespace throw on an empty writeRoles list; the designer's
+// string-list input emits [] when cleared, which means "rely on handler access alone".
+function dropEmptyWriteRoles(options) {
+    if (options.writeRoles?.length !== 0)
+        return options;
+    const { writeRoles: _emptyWriteRoles, ...rest } = options;
+    return rest;
+}
 function renderSecret(p) {
     if (isRawRefSentinel(p.options)) {
         return `r.secret(${JSON.stringify(p.shortName)}, ${p.options.__raw});`;
     }
-    const merged = { name: p.shortName, ...p.options };
+    const merged = { name: p.shortName, ...dropEmptyWriteRoles(p.options) };
     return `r.secret(${renderValue(merged)});`;
 }
 function renderSecretNamespace(p) {
     if (isRawRefSentinel(p.options)) {
         return `r.secretNamespace(${JSON.stringify(p.shortName)}, ${p.options.__raw});`;
     }
-    const merged = { name: p.shortName, ...p.options };
+    const merged = { name: p.shortName, ...dropEmptyWriteRoles(p.options) };
     return `r.secretNamespace(${renderValue(merged)});`;
 }
 function renderClaimKey(p) {
@@ -497,9 +505,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;