@cosmicdrift/kumiko-framework 0.362.0 → 0.363.0

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/file-routes.js

@@ -74,7 +74,7 @@ export function readFilesRouteOptions(registry) {
     if (exp && typeof exp === "object" && "routeOptions" in exp) {
         const ro = exp.routeOptions;
         if (ro && typeof ro === "object") {
-            // @cast-boundary feature-exports: engine-payload (unknown) → known shape
+            // @cast-boundary feature-exports — typeof-checked read-back from untyped feature.exports
             return ro;
         }
     }

package/dist/files/local-provider.js

@@ -2,6 +2,7 @@ import { createReadStream, createWriteStream } from "node:fs";
 import { mkdir, readdir, readFile, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
 import { dirname, join, relative, resolve, sep } from "node:path";
 import { pipeline } from "node:stream/promises";
+import { errorCodeOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { assertSafeStorageKey } from "./types.js";
 // Local-filesystem backend — intended for dev + tests. Production deploys
 // pick an object-store provider (S3/R2/…). mimeType is ignored here; the
@@ -112,7 +113,7 @@ export function createLocalProvider(basePath) {
                 entries = await readdir(walkRoot, { recursive: true, withFileTypes: true });
             }
             catch (err) {
-                const code = err.code;
+                const code = errorCodeOf(err);
                 if (code === "ENOENT" || code === "ENOTDIR")
                     return [];
                 throw err;

package/dist/i18n/index.d.ts

@@ -1,5 +1,5 @@
 import type { Registry } from "../engine/types/index.js";
-export { hasMailTranslations, mailT, registerMailTranslations, resolveMailLocale, } from "./mail-registry.js";
+export { hasMailTranslationKey, hasMailTranslations, listMailLocales, mailT, registerMailTranslations, resolveMailLocale, } from "./mail-registry.js";
 export { canonicalizeLocaleTag, DEFAULT_LOCALE, isValidLocaleTag, pickAcceptLanguage, resolveHeaderLocale, } from "./request-locale.js";
 export { SETTINGS_HUB_I18N } from "./settings-hub-keys.js";
 export type I18nOptions = {

package/dist/i18n/index.js

@@ -1,5 +1,5 @@
 import { resolveTranslationValue } from "../ui-types/plural.js";
-export { hasMailTranslations, mailT, registerMailTranslations, resolveMailLocale, } from "./mail-registry.js";
+export { hasMailTranslationKey, hasMailTranslations, listMailLocales, mailT, registerMailTranslations, resolveMailLocale, } from "./mail-registry.js";
 export { canonicalizeLocaleTag, DEFAULT_LOCALE, isValidLocaleTag, pickAcceptLanguage, resolveHeaderLocale, } from "./request-locale.js";
 export { SETTINGS_HUB_I18N } from "./settings-hub-keys.js";
 export function createI18n(registry, options) {

package/dist/i18n/mail-registry.d.ts

@@ -1,5 +1,7 @@
 import { type TranslationValue } from "../ui-types/plural.js";
 export declare function registerMailTranslations(locale: string, bundle: Readonly<Record<string, TranslationValue>>): void;
+export declare function listMailLocales(): readonly string[];
+export declare function hasMailTranslationKey(locale: string, key: string): boolean;
 export declare function hasMailTranslations(locale: string): boolean;
 export declare function mailT(locale: string, key: string, params?: Readonly<Record<string, string | number>>): string;
 /** Locale key mailT would actually use (exact → root → en). Use for appUrl

package/dist/i18n/mail-registry.js

@@ -4,6 +4,13 @@ export function registerMailTranslations(locale, bundle) {
     const prev = tables.get(locale) ?? {};
     tables.set(locale, { ...prev, ...bundle });
 }
+export function listMailLocales() {
+    return [...tables.keys()];
+}
+// Own key only, without the root/en fallback mailT applies.
+export function hasMailTranslationKey(locale, key) {
+    return tables.get(locale)?.[key] !== undefined;
+}
 export function hasMailTranslations(locale) {
     const root = locale.split("-")[0] ?? locale;
     return tables.has(locale) || tables.has(root);

package/dist/jobs/job-runner.js

@@ -1,4 +1,5 @@
 import { escapeHatchFor } from "@cosmicdrift/kumiko-types/handlers";
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import { Queue, UnrecoverableError, Worker } from "bullmq";
 import { Redis } from "ioredis";
 import { requestContext } from "../api/request-context.js";
@@ -24,12 +25,11 @@ import { cronRepeatOptions } from "./cron-repeat-options.js";
 // run proceeds without it rather than failing over what would be a framework
 // bug, not untrusted input.
 function isJobTriggerEvent(value) {
-    if (typeof value !== "object" || value === null)
+    if (!isPlainObject(value))
         return false;
-    const candidate = value;
-    if (typeof candidate["id"] !== "string")
+    if (typeof value["id"] !== "string")
         return false;
-    const headers = candidate["headers"];
+    const headers = value["headers"];
     if (typeof headers !== "object" || headers === null)
         return false;
     return Object.values(headers).every((v) => typeof v === "string" || typeof v === "number" || typeof v === "boolean");
@@ -834,7 +834,7 @@ export function createJobRunner(options) {
         // must resolve for jobs the same way they do for write-handlers, or an
         // app-author job calling ctx.notify(...)/ctx.config(...) hits a TypeError
         // at runtime the write-handler path never would (framework#1532).
-        const notify = context._notifyFactory?.(jobSystemUser, tenantId, selfRunner);
+        const notify = context._notifyFactory?.(jobSystemUser, tenantId, selfRunner, undefined, context._fileProviderResolver);
         const configDb = context.db; // @cast-boundary db-operator
         // Shared by the config accessor and ctx.derivatives below — both need the
         // same tenant-scoped db, and building it twice would let the two calls

package/dist/pipeline/dispatch-query.js

@@ -1,3 +1,4 @@
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { hasAccess } from "../engine/access.js";
 import { tenantOverrideDenied } from "../engine/cross-tenant.js";
 import { filterReadFields } from "../engine/field-access.js";
@@ -49,9 +50,7 @@ async function executeQueryInner(ctx, type, payload, user, origin, tx) {
     // schema (and custom query schemas that opt in) carries `includeDeleted`,
     // so other handlers never see the flag. Visibility filters still apply
     // downstream (see HandlerContext.includeDeleted) — safe from raw input.
-    const includeDeleted = typeof parsed.data === "object" &&
-        parsed.data !== null &&
-        parsed.data["includeDeleted"] === true; // @cast-boundary validated-payload
+    const includeDeleted = propertyOf(parsed.data, "includeDeleted") === true;
     // A resolved member (ctx.queryAsMember) runs in a Postgres READ ONLY transaction, not just the ctx surface below.
     return isMemberResolutionPrincipal(user)
         ? runInMemberReadOnlyTransaction(ctx, tx, (readOnlyTx) => runQueryHandler(ctx, type, handler, parsed.data, includeDeleted, user, origin, readOnlyTx))