@cosmicdrift/kumiko-framework 0.361.0 → 0.363.0

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

package/dist/engine/schema-builder.js

@@ -358,9 +358,7 @@ function applyTotalsMatchRefinements(entity, schema) {
                     continue;
                 }
                 const sumMinor = rawRows.reduce((total, row) => {
-                    const value = typeof row === "object" && row !== null
-                        ? row[subFieldName]
-                        : undefined;
+                    const value = typeof row === "object" && row !== null ? Reflect.get(row, subFieldName) : undefined;
                     return total + (typeof value === "number" ? value : 0);
                 }, 0);
                 if (sumMinor !== siblingMinor) {

package/dist/engine/soft-delete-cleanup.js

@@ -11,6 +11,7 @@
 // table growth; irreversible event-log purging is data-retention's job
 // (pruneEvents), a separate, consumer-lag-guarded path.
 import { asEntityTableMeta, deleteMany } from "../db/query.js";
+import { hasFieldProperty } from "../db/table-introspection.js";
 import { purgeExpiredFileRefsWithBytes } from "../files/purge-expired-file-ref-bytes.js";
 import { FILE_REF_ENTITY_NAME } from "../files/types.js";
 import { SYSTEM_USER_ID } from "./system-user.js";
@@ -34,7 +35,7 @@ export const softDeleteGraceDaysConfig = {
     bounds: { min: 1 },
 };
 function hasTenantIdColumn(table) {
-    return table["tenantId"] !== undefined;
+    return hasFieldProperty(table, "tenantId");
 }
 // The entity declaration decides, not the column: a `tenancy: "global"` table
 // (e.g. user) still carries a tenantId column (SYSTEM_TENANT_ID), yet no

package/dist/engine/steps/call-feature.js

@@ -18,9 +18,7 @@ defineStep({
             // dispatcher's catch maps it back to a typed error response
             // (e.g. validation_failed stays validation_failed, not a
             // generic internal_error).
-            const err = new Error(`callFeature("${args.handler}") returned failure`);
-            err.cause = result.error;
-            throw err;
+            throw new Error(`callFeature("${args.handler}") returned failure`, { cause: result.error });
         }
         return result.data;
     },

package/dist/engine/steps/unsafe-projection-upsert.js

@@ -10,25 +10,14 @@
 // the owning feature. Aggregate-tables (registered via r.entity) are
 // rejected by boot-validation — domain mutation MUST go through
 // r.step.aggregate.*.
-import { KUMIKO_COLUMNS_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types";
 import { extractTableName } from "../../db/index.js";
 import { executeRawQuery } from "../../db/queries/raw-sql.js";
+import { columnSqlNameOf } from "../../db/table-introspection.js";
 import { tenantDbRunner } from "../../db/tenant-db-runner.js";
 import { defineStep } from "../define-step.js";
 import { resolveRequired } from "./_resolver-utils.js";
 function resolveColumnName(table, field) {
-    if (typeof table !== "object" || table === null)
-        return field;
-    const cols = table[KUMIKO_COLUMNS_SYMBOL];
-    if (typeof cols !== "object" || cols === null)
-        return field;
-    const col = cols[field];
-    if (typeof col === "object" && col !== null) {
-        const nameVal = col["name"];
-        if (typeof nameVal === "string")
-            return nameVal;
-    }
-    return field;
+    return columnSqlNameOf(table, field) ?? field;
 }
 function quoteIdent(name) {
     return `"${name.replace(/"/g, '""')}"`;

package/dist/engine/template-variables.d.ts

@@ -0,0 +1,29 @@
+import * as z from "zod";
+import type { Registry, TemplateListVariableDef, TemplateScalarVariableDef, TemplateVariables } from "./types/index.js";
+type CommonOptions = {
+    readonly label?: string;
+    readonly required?: boolean;
+};
+export declare const templateVariable: {
+    readonly text: (opts?: CommonOptions & {
+        readonly example?: string;
+    }) => TemplateScalarVariableDef;
+    readonly link: (opts?: CommonOptions & {
+        readonly example?: string;
+    }) => TemplateScalarVariableDef;
+    readonly money: (opts?: CommonOptions & {
+        readonly example?: number | {
+            readonly amount: number;
+            readonly currency: string;
+        };
+    }) => TemplateScalarVariableDef;
+    readonly date: (opts?: CommonOptions & {
+        readonly example?: string;
+    }) => TemplateScalarVariableDef;
+    readonly list: (item: Readonly<Record<string, TemplateScalarVariableDef>>, opts?: CommonOptions & {
+        readonly example?: readonly Readonly<Record<string, unknown>>[];
+    }) => TemplateListVariableDef;
+};
+export declare function templateVariablesToZod(variables: TemplateVariables): z.ZodObject;
+export declare function assertNotificationVariables(registry: Pick<Registry, "getAllNotifications">, notificationType: string, data: Readonly<Record<string, unknown>> | undefined): void;
+export {};

package/dist/engine/template-variables.js

@@ -0,0 +1,77 @@
+import * as z from "zod";
+import { InternalError } from "../errors/index.js";
+// Builders keep declarations terse and the `type` discriminant out of app code.
+export const templateVariable = {
+    text: (opts = {}) => ({
+        type: "text",
+        ...opts,
+    }),
+    link: (opts = {}) => ({
+        type: "link",
+        ...opts,
+    }),
+    money: (opts = {}) => ({ type: "money", ...opts }),
+    date: (opts = {}) => ({
+        type: "date",
+        ...opts,
+    }),
+    list: (item, opts = {}) => ({ type: "list", item, ...opts }),
+};
+const LINK_PROTOCOLS = new Set(["http:", "https:", "mailto:"]);
+function isSafeLinkUrl(value) {
+    try {
+        return LINK_PROTOCOLS.has(new URL(value).protocol);
+    }
+    catch {
+        return false;
+    }
+}
+const linkSchema = z.string().refine(isSafeLinkUrl, "must be an http, https or mailto URL");
+const moneySchema = z.union([
+    z.number().int(),
+    z.object({
+        amount: z.number().int(),
+        currency: z.string().regex(/^[A-Z]{3}$/),
+    }),
+]);
+const dateSchema = z.union([z.iso.date(), z.iso.datetime({ offset: true })]);
+function scalarToZod(def) {
+    switch (def.type) {
+        case "text":
+            return z.string();
+        case "link":
+            return linkSchema;
+        case "money":
+            return moneySchema;
+        case "date":
+            return dateSchema;
+    }
+}
+function variableToZod(def) {
+    if (def.type !== "list")
+        return scalarToZod(def);
+    return z.array(z.object(Object.fromEntries(Object.entries(def.item).map(([name, item]) => [name, withOptionality(item)]))));
+}
+function withOptionality(def) {
+    const schema = variableToZod(def);
+    return def.required === true ? schema : schema.optional();
+}
+export function templateVariablesToZod(variables) {
+    return z.object(Object.fromEntries(Object.entries(variables).map(([name, def]) => [name, withOptionality(def)])));
+}
+// Validates only: the caller keeps passing the original data on, because
+// parsing would strip keys the delivery adds itself (unsubscribeUrl, fromName).
+export function assertNotificationVariables(registry, notificationType, data) {
+    const definition = registry.getAllNotifications().get(notificationType);
+    if (definition?.template !== undefined && definition.variables !== undefined) {
+        const parsed = templateVariablesToZod(definition.variables).safeParse(data ?? {});
+        if (!parsed.success) {
+            const issues = parsed.error.issues
+                .map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`)
+                .join("; ");
+            throw new InternalError({
+                message: `notification "${notificationType}" has invalid variables: ${issues}`,
+            });
+        }
+    }
+}

package/dist/engine/tier-resolver-extension.js

@@ -19,6 +19,7 @@
 //
 // **Apps ohne tier-engine:** wenn keine plugin registriert ist, framework
 // macht nichts — `effectiveFeatures` bleibt undefined, alle features sind on.
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 /**
  * Extension-name unter dem ein tier-resolver-plugin im registry registriert
  * werden muss. Konstante damit `r.useExtension(TENANT_TIER_RESOLVER_EXT, ...)`
@@ -39,9 +40,7 @@ export const TENANT_TIER_RESOLVER_EXT = "tenantTierResolver";
  *  plugin shape — the only thing every implementation must provide is the
  *  `build` factory. */
 export function isTierResolverPlugin(v) {
-    return (typeof v === "object" &&
-        v !== null &&
-        typeof v["build"] === "function");
+    return isPlainObject(v) && typeof v["build"] === "function";
 }
 export function findTierResolverUsage(features) {
     for (const feature of features) {

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

@@ -1,5 +1,5 @@
 export { isAgentVisibleScreen, resolveAgentExposure, } from "@cosmicdrift/kumiko-types/agent-exposure";
-export type { ConfigAccessor, ConfigAccessorFactory, ConfigBacking, ConfigBounds, ConfigCascade, ConfigCascadeLevel, ConfigComputedContext, ConfigComputedFn, ConfigDefinition, ConfigKeyAccess, ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigMask, ConfigResolver, ConfigSecretsReader, ConfigSeedDef, ConfigStoredRow, ConfigStoredRowWithSource, ConfigValidateContext, ConfigValidateFn, ConfigValue, ConfigValueSource, ConfigValueWithSource, CreateSeedOptions, CreateTenantSeedOptions, CreateUserSeedOptions, ExtensionSelectorDef, ExtensionSelectorPanel, JobBackoff, JobBackoffStrategy, JobDefinition, JobHandlerFn, JobRunIn, JobTrigger, NotificationDataFn, NotificationDefinition, NotificationRecipientFn, NotificationTemplateFn, PluralForms, ReferenceDataDef, RegistrarExtensionDef, RegistrarExtensionHooks, RegistrarExtensionRegistration, RunIn, TranslationEntry, TranslationKeys, TranslationsDef, TranslationValue, UiExtensionDef, } from "@cosmicdrift/kumiko-types/config";
+export type { ConfigAccessor, ConfigAccessorFactory, ConfigBacking, ConfigBounds, ConfigCascade, ConfigCascadeLevel, ConfigComputedContext, ConfigComputedFn, ConfigDefinition, ConfigKeyAccess, ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigMask, ConfigResolver, ConfigSecretsReader, ConfigSeedDef, ConfigStoredRow, ConfigStoredRowWithSource, ConfigValidateContext, ConfigValidateFn, ConfigValue, ConfigValueSource, ConfigValueWithSource, CreateSeedOptions, CreateTenantSeedOptions, CreateUserSeedOptions, ExtensionSelectorDef, ExtensionSelectorPanel, JobBackoff, JobBackoffStrategy, JobDefinition, JobHandlerFn, JobRunIn, JobTrigger, NotificationDataFn, NotificationDefinition, NotificationLocalizedTemplate, NotificationRecipientFn, NotificationRecordMapping, NotificationTemplateBody, NotificationTemplateFn, NotificationTemplateMeta, PluralForms, ReferenceDataDef, RegistrarExtensionDef, RegistrarExtensionHooks, RegistrarExtensionRegistration, RunIn, TemplateListVariableDef, TemplateScalarVariableDef, TemplateVariableDef, TemplateVariables, TranslationEntry, TranslationKeys, TranslationsDef, TranslationValue, UiExtensionDef, } from "@cosmicdrift/kumiko-types/config";
 export type { QueryHandlerDefinition, StreamHandlerDefinition, WriteHandlerDefinition, WriteHandlerInput, } from "@cosmicdrift/kumiko-types/define-handler";
 export type { EntityCrudRegistrar, EntityCrudVerb, EntityHandlerOptions, EntityQueryHandlerOptions, EntityWriteHandlerOptions, RegisterEntityCrudOptions, } from "@cosmicdrift/kumiko-types/entity-handlers";
 export type { KumikoEntityTypeMap, KumikoEventTypeMap, KumikoHandlerPayloadMap, KumikoHandlerResultMap, } from "@cosmicdrift/kumiko-types/event-type-map";
@@ -7,7 +7,7 @@ export type { ExtensionOptionsArgs, ExtensionOptionsFor, KumikoExtensionOptionsM
 export type { BootCheckContext, BootCheckFn, FeatureDefinition, FeatureMetricDef, FeatureMetricType, FeatureRegistrar, MetricOptions, Registry, SecretKeyDefinition, SecretKeyHandle, SecretNamespaceDefinition, SecretNamespaceHandle, SecretNamespaceOptions, SecretOptions, StoreTableDef, StoreTableEntry, StoreTableOptions, UiHintOption, UiHints, } from "@cosmicdrift/kumiko-types/feature";
 export type { FieldIconKey } from "@cosmicdrift/kumiko-types/field-icon";
 export type { AnyFileFieldDef, BigIntFieldDef, BooleanFieldDef, ClientDerivedFieldDef, DateFieldDef, DecimalFieldDef, DefaultCurrency, DeriveContext, DerivedFieldDef, DerivedFieldsMap, DerivedValueType, EmbeddedDerivedCellDef, EmbeddedFieldDef, EmbeddedSubFieldDef, EntityDefinition, EntityEventMigration, EntityIndexDef, FieldAccess, FieldDefinition, FieldsMap, FileFieldDef, FilesFieldDef, Findability, ImageFieldDef, ImagesFieldDef, JsonbFieldDef, LocatedTimestampFieldDef, LongTextFieldDef, LongTextFindability, MoneyCurrencySource, MoneyFieldDef, MultiSelectFieldDef, NumberFieldDef, OptionsQueryPayload, OptionsQueryPayloadValue, ParentRefDef, PersonalAnnotations, PersonalAnnotationsLongText, PersonalAnnotationsNoFind, PersonalSubject, ReferenceFieldDef, ResolvedPiiFlags, RetentionDef, SelectFieldDef, SelectOptionTone, TextFieldDef, TimestampFieldDef, TransitionMap, TzFieldDef, } from "@cosmicdrift/kumiko-types/fields";
-export type { AccessRule, ActiveMembership, ActiveMembershipRejection, ActiveMembershipResult, AgentExposure, AgentHandlerHints, AgentRisk, AggregateStreamHandle, AppContext, AppendEventArgs, AppendEventFn, AuthClaimsContext, AuthClaimsFn, AuthClaimsHookDef, CamelToKebab, ChatSendFailureCode, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyJsType, ClaimKeyType, DeclarativeEventMigration, DeliveryErrorCode, DeliveryFailureCode, DeliverySkipReason, DispatchWriteRef, EntityRef, EscapeHatchAuditSink, EscapeHatchDeclaration, EscapeHatchKind, EscapeHatchReporter, EscapeHatchTarget, EscapeHatchUseEvent, EventDef, EventMigrationDef, EventPiiFields, EventPiiStance, EventUpcastCtx, EventUpcastFn, FetchForWritingArgs, HandlerContext, HandlerRef, JobContext, JobRunnerRef, JobTriggerEvent, MemberReader, NameOrRef, NotifyDelivery, NotifyDeliveryStatus, NotifyFactory, NotifyFn, NotifyJobDispatcher, NotifyOptions, NotifyPriority, NotifyResult, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, PayloadRateLimitOption, QualifiedEventName, QueryEvent, QueryHandlerDef, QueryHandlerFn, RateLimitDeclaration, RateLimitDisabled, RateLimitOption, RateLimitPer, RoleAccessPersonalData, RoleAccessRule, SessionUser, SessionUserOrigin, StreamHandlerDef, StreamHandlerFn, TenantWriteTarget, TryAppendEventFn, TryAppendEventResult, UnsafeAppendEventFn, WriteEvent, WriteHandlerDef, WriteHandlerFn, WriteResult, } from "@cosmicdrift/kumiko-types/handlers";
+export type { AccessRule, ActiveMembership, ActiveMembershipRejection, ActiveMembershipResult, AgentExposure, AgentHandlerHints, AgentRisk, AggregateStreamHandle, AppContext, AppendEventArgs, AppendEventFn, AuthClaimsContext, AuthClaimsFn, AuthClaimsHookDef, CamelToKebab, ChatSendFailureCode, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyJsType, ClaimKeyType, DeclarativeEventMigration, DeliveryErrorCode, DeliveryFailureCode, DeliverySkipReason, DispatchWriteRef, EntityRef, EscapeHatchAuditSink, EscapeHatchDeclaration, EscapeHatchKind, EscapeHatchReporter, EscapeHatchTarget, EscapeHatchUseEvent, EventDef, EventMigrationDef, EventPiiFields, EventPiiStance, EventUpcastCtx, EventUpcastFn, FetchForWritingArgs, HandlerContext, HandlerRef, JobContext, JobRunnerRef, JobTriggerEvent, MemberReader, NameOrRef, NotifyDeferred, NotifyDelivery, NotifyDeliveryStatus, NotifyDispatched, NotifyFactory, NotifyFn, NotifyJobDispatcher, NotifyOptions, NotifyPriority, NotifyResult, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, PayloadRateLimitOption, QualifiedEventName, QueryEvent, QueryHandlerDef, QueryHandlerFn, RateLimitDeclaration, RateLimitDisabled, RateLimitOption, RateLimitPer, RoleAccessPersonalData, RoleAccessRule, SessionUser, SessionUserOrigin, StreamHandlerDef, StreamHandlerFn, TenantWriteTarget, TryAppendEventFn, TryAppendEventResult, UnsafeAppendEventFn, WriteEvent, WriteHandlerDef, WriteHandlerFn, WriteResult, } from "@cosmicdrift/kumiko-types/handlers";
 export { DELIVERY_FAILURE_CODES, DELIVERY_SKIP_REASONS, HTTP_ERROR_CODE_PATTERN, isDeliveryErrorCode, isOpenToAllGranted, isRateLimitDisabled, isUiAccessGranted, } from "@cosmicdrift/kumiko-types/handlers";
 export type { DeleteContext, EntityHookMap, HookMap, HookOwner, HookPhase, LifecycleHookFn, LifecycleResult, OwnedFn, PhasedHook, PostDeleteBatchHookFn, PostDeleteHookFn, PostQueryHookFn, PostSaveBatchHookFn, PostSaveHookFn, PreDeleteHookFn, PreQueryHookFn, PreSaveHookFn, SaveContext, SearchPayloadContributorFn, ValidationError, ValidationHookFn, } from "@cosmicdrift/kumiko-types/hooks";
 export type { HttpRouteDefinition, HttpRouteHandler, HttpRouteHandlerDeps, HttpRouteMethod, } from "@cosmicdrift/kumiko-types/http-route";

package/dist/engine/validate-projection-allowlist.js

@@ -22,7 +22,8 @@
 // boot-time is surfaced cleanly; a quietly-different step-list is not
 // caught by this validator. A future lint-rule will enforce the contract
 // statically; today it lives in this comment + the StepBuilder doc.
-import { KUMIKO_META_SYMBOL, KUMIKO_NAME_SYMBOL, } from "@cosmicdrift/kumiko-types/schema-table-types";
+import { KUMIKO_META_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types";
+import { schemaTableName } from "../db/table-introspection.js";
 import { getStep } from "./define-step.js";
 import { buildPipelineSteps } from "./pipeline.js";
 // Listed step-kinds whose `args.table` must be in the owning feature's
@@ -57,21 +58,19 @@ function* walkAllSteps(steps) {
 function resolveTableNameFromStep(table) {
     if (typeof table === "object" && table !== null) {
         // Canonical meta under the unshadowable symbol — preferred path.
-        const meta = table[KUMIKO_META_SYMBOL];
-        if (meta !== null && typeof meta === "object") {
-            const metaName = meta["tableName"];
-            if (typeof metaName === "string")
-                return metaName;
+        const meta = Reflect.get(table, KUMIKO_META_SYMBOL);
+        if (typeof meta === "object" &&
+            meta !== null &&
+            "tableName" in meta &&
+            typeof meta.tableName === "string") {
+            return meta.tableName;
         }
         // Plain meta (deriveEntityTableMeta / defineUnmanagedTable — no handle-spread).
-        if ("source" in table &&
-            "tableName" in table &&
-            typeof table["tableName"] === "string") {
-            return table["tableName"];
+        if ("source" in table && "tableName" in table && typeof table.tableName === "string") {
+            return table.tableName;
         }
-        // drizzle pgTable
-        const name = table[KUMIKO_NAME_SYMBOL];
-        if (typeof name === "string")
+        const name = schemaTableName(table);
+        if (name !== undefined)
             return name;
     }
     throw new Error(`validate-projection-allowlist: cannot resolve table name from ${String(table)}`);

package/dist/engine/where-rule-lint.js

@@ -8,8 +8,8 @@
 // parser) that catches the two shapes that always mean "this rule is
 // broken": a bare column reference inside a subquery that shadows an outer
 // column, and a literal self-comparison.
-import { KUMIKO_COLUMNS_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types";
 import { toSnakeCase } from "../db/table-builder.js";
+import { tableColumnsOf } from "../db/table-introspection.js";
 const IDENT_SRC = `"(?:[^"]|"")+"|[A-Za-z_][A-Za-z0-9_$]*`;
 const QUALIFIED_SRC = `(?:${IDENT_SRC})(?:\\.(?:${IDENT_SRC}))?`;
 const TOKEN_RE = new RegExp(IDENT_SRC, "g");
@@ -23,14 +23,15 @@ const QUALIFIED_PARSE_RE = new RegExp(`^(${IDENT_SRC})(?:\\.(${IDENT_SRC}))?$`);
 export function tableColumnSqlNames(table) {
     if (table === null || typeof table !== "object")
         return new Set();
-    const cols = table[KUMIKO_COLUMNS_SYMBOL];
-    if (cols && typeof cols === "object") {
+    const cols = tableColumnsOf(table);
+    if (cols) {
         const names = new Set();
         for (const col of Object.values(cols)) {
-            if (col && typeof col === "object") {
-                const nameVal = col["name"];
-                if (typeof nameVal === "string")
-                    names.add(nameVal.toLowerCase());
+            if (typeof col === "object" &&
+                col !== null &&
+                "name" in col &&
+                typeof col.name === "string") {
+                names.add(col.name.toLowerCase());
             }
         }
         return names;

package/dist/errors/reasons.d.ts

@@ -7,6 +7,7 @@ export declare const FrameworkReasons: {
     readonly systemIdentitySwitchDenied: "system_identity_switch_denied";
     readonly identitySwitchDenied: "identity_switch_denied";
     readonly tenantOverrideRequiresSystemAdmin: "tenant_override_requires_system_admin";
+    readonly notifyForeignTenantBroadcast: "notify_foreign_tenant_broadcast";
     readonly unsafeAllTenantsDenied: "unsafe_all_tenants_denied";
     readonly memberResolutionDenied: "member_resolution_denied";
     readonly memberResolutionReadOnly: "member_resolution_read_only";

package/dist/errors/reasons.js

@@ -42,6 +42,8 @@ export const FrameworkReasons = {
     identitySwitchDenied: "identity_switch_denied",
     // AccessDeniedError: a payload carried tenantIdOverride but the caller is no SystemAdmin.
     tenantOverrideRequiresSystemAdmin: "tenant_override_requires_system_admin",
+    // AccessDeniedError: ctx.notify was called with `to: { tenant }` naming a tenant other than the caller's.
+    notifyForeignTenantBroadcast: "notify_foreign_tenant_broadcast",
     // AccessDeniedError: a handler/hook called ctx.queryProjection(..., { unsafeAllTenants: true })
     // without an r.systemScope() feature or a declared escapeHatch.
     unsafeAllTenantsDenied: "unsafe_all_tenants_denied",

package/dist/files/bind-referenced-files.write.d.ts

@@ -0,0 +1,16 @@
+import * as z from "zod";
+export type BindReferencedFilesResult = {
+    readonly bound: number;
+    readonly skipped: number;
+    readonly nextAfterId: string | null;
+};
+export declare const bindReferencedFilesWrite: import("@cosmicdrift/kumiko-types/define-handler").WriteHandlerDefinition<"bindReferencedFiles", z.ZodObject<{
+    entityType: z.ZodString;
+    entityIds: z.ZodOptional<z.ZodArray<z.ZodUUID>>;
+    afterId: z.ZodOptional<z.ZodUUID>;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>, {
+    bound: number;
+    skipped: number;
+    nextAfterId: string | null;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;