@cosmicdrift/kumiko-framework 0.362.0 → 0.364.0

package/dist/engine/schema-builder.js

@@ -288,7 +288,8 @@ export function fieldToZod(field, currencies, opts = {}) {
             // Multi file: array of fileRef UUIDs. Same story as the singular
             // variant — the element type has to match the UUID column on
             // fileRefsTable.id.
-            return z.array(z.uuid());
+            const ids = z.array(z.uuid());
+            return field.maxCount === undefined ? ids : ids.max(field.maxCount);
         }
         case "reference":
             // Tier 2.7e-3: Validiert UUID-shape. Existenz-Check der Reference
@@ -358,9 +359,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
@@ -79,13 +80,20 @@ export const softDeleteCleanupJob = async (_payload, ctx) => {
         if (isSystemScopedSoftDeleteTable(proj.table, entity))
             continue;
         const where = { isDeleted: true, deletedAt: { lt: cutoff }, tenantId };
-        await purgeExpiredRows(db, proj.source, proj.table, where, ctx);
+        await purgeExpiredRows(db, proj.source, proj.table, where, cutoff, ctx);
     }
 };
-async function purgeExpiredRows(db, source, table, where, ctx) {
+async function purgeExpiredRows(db, source, table, where, cutoff, ctx) {
     if (source === FILE_REF_ENTITY_NAME) {
         // The row is the only record of the storageKey, so its bytes go first.
-        await purgeExpiredFileRefsWithBytes({ db, table, where, files: ctx.files, log: ctx.log });
+        await purgeExpiredFileRefsWithBytes({
+            db,
+            table,
+            where,
+            expiredBefore: cutoff,
+            files: ctx.files,
+            log: ctx.log,
+        });
     }
     else {
         await deleteMany(db, table, where);

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/retry.js

@@ -11,6 +11,7 @@ import { defineStep } from "../define-step.js";
 import { runStepList } from "../run-pipeline.js";
 import { SUSPEND_SENTINEL, WORKFLOW_AGGREGATE_TYPE, WORKFLOW_RETRY_SCHEDULED_TYPE, } from "./_step-dispatch-constants.js";
 import { describeWorkflowStepError } from "./describe-workflow-step-error.js";
+import { unwrapWorkflowStepError } from "./workflow-step-error.js";
 const log = createFallbackLogger("workflow-retry");
 defineStep({
     kind: "workflow.retry",
@@ -38,7 +39,7 @@ defineStep({
                 workflowName: ctx.workflow.workflowName,
                 stepIndex: ctx.workflow.stepIndex,
                 attempt,
-                error: String(error),
+                error: String(unwrapWorkflowStepError(error)),
             });
             const backoffMs = calculateBackoff(attempt, args.backoff);
             const wakeAt = Temporal.Now.instant().add({ milliseconds: backoffMs }).toString();

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

@@ -16,7 +16,7 @@
 // must commit in the same TX as the aggregate-mutation that triggered
 // it (stronger consistency than an async projection). Reviewer judges.
 import { deleteMany } from "../../db/query.js";
-import { tenantDbRunner } from "../../db/tenant-db-runner.js";
+import { tenantDbWriteRunner } from "../../db/tenant-db-runner.js";
 import { defineStep } from "../define-step.js";
 import { resolveRequired } from "./_resolver-utils.js";
 defineStep({
@@ -27,7 +27,7 @@ defineStep({
         // The `unsafe*`-step IS the sanctioned direct projection write — it exists
         // to bypass the executor deliberately (boot-validated allowlist + reviewer
         // gate). The brand-strip cast makes that explicit at the one blessed seam.
-        await deleteMany(tenantDbRunner(ctx.db), args.table, where);
+        await deleteMany(tenantDbWriteRunner(ctx.db, "unsafe projection delete"), args.table, where);
     },
 });
 export function buildUnsafeProjectionDeleteStep(args) {

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 { tenantDbRunner } from "../../db/tenant-db-runner.js";
+import { columnSqlNameOf } from "../../db/table-introspection.js";
+import { tenantDbWriteRunner } 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, '""')}"`;
@@ -65,7 +54,7 @@ defineStep({
         }
         const sqlText = `INSERT INTO ${quoteIdent(tableName)} (${colNames.join(", ")}) VALUES (${placeholders.join(", ")}) ` +
             `ON CONFLICT (${conflictCols}) DO UPDATE SET ${setClauses.join(", ")}`;
-        await executeRawQuery(tenantDbRunner(ctx.db), sqlText, params);
+        await executeRawQuery(tenantDbWriteRunner(ctx.db, "unsafe projection upsert"), sqlText, params);
     },
 });
 export function buildUnsafeProjectionUpsertStep(args) {

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

@@ -0,0 +1,32 @@
+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 richText: (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,80 @@
+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,
+    }),
+    richText: (opts = {}) => ({ type: "richText", ...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 "richText":
+            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, BeforeTransactionPhase, BeforeTransactionResult, 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, PayloadBucketNormalization, PayloadRateLimitOption, PreparedWriteEvent, 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/env/_zod-introspect.d.ts

@@ -2,6 +2,7 @@ import type * as z from "zod";
 export type ZodDef = {
     readonly innerType?: z.ZodType;
     readonly in?: z.ZodType;
+    readonly element?: z.ZodType;
     readonly defaultValue?: unknown;
 };
 /** Read Zod v4 `.meta()` value. Undefined when no meta is set. */

package/dist/errors/classes.js

@@ -223,6 +223,7 @@ export class RateLimitError extends KumikoError {
             message: `rate limited: ${details.bucket} (limit ${details.limit} per ${details.windowSeconds}s)`,
             i18nKey: opts?.i18nKey ?? "errors.rate_limited",
             details,
+            retryAfterSeconds: details.retryAfterSeconds,
             ...(opts?.cause && { cause: opts.cause }),
         });
         this.details = details;

package/dist/errors/kumiko-error.d.ts

@@ -11,6 +11,7 @@ export type ErrorCtorInput = {
     readonly i18nParams?: Readonly<Record<string, unknown>>;
     readonly details?: unknown;
     readonly cause?: Error;
+    readonly retryAfterSeconds?: number;
 };
 export declare abstract class KumikoError extends Error {
     abstract readonly code: string;
@@ -18,6 +19,7 @@ export declare abstract class KumikoError extends Error {
     readonly i18nKey: string;
     readonly i18nParams: Readonly<Record<string, unknown>> | undefined;
     readonly details: unknown;
+    readonly retryAfterSeconds: number | undefined;
     constructor(input: ErrorCtorInput);
 }
 export declare function isKumikoError(e: unknown): e is KumikoError;

package/dist/errors/kumiko-error.js

@@ -6,12 +6,14 @@ export class KumikoError extends Error {
     i18nKey;
     i18nParams;
     details;
+    retryAfterSeconds;
     constructor(input) {
         super(input.message, input.cause ? { cause: input.cause } : undefined);
         this.name = new.target.name;
         this.i18nKey = input.i18nKey;
         this.i18nParams = input.i18nParams;
         this.details = input.details;
+        this.retryAfterSeconds = input.retryAfterSeconds;
     }
 }
 export function isKumikoError(e) {

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/errors/write-error-info.js

@@ -69,6 +69,7 @@ export function toWriteErrorInfo(err) {
         message: err.message,
         ...(err.i18nParams && { i18nParams: err.i18nParams }),
         ...(effectiveDetails !== undefined && { details: effectiveDetails }),
+        ...(err.retryAfterSeconds !== undefined && { retryAfterSeconds: err.retryAfterSeconds }),
     };
     if (err.cause instanceof Error)
         causeByWriteErrorInfo.set(info, err.cause);
@@ -91,6 +92,7 @@ class ReraisedError extends KumikoError {
             i18nKey: info.i18nKey,
             ...(info.i18nParams && { i18nParams: info.i18nParams }),
             ...(info.details !== undefined && { details: info.details }),
+            ...(info.retryAfterSeconds !== undefined && { retryAfterSeconds: info.retryAfterSeconds }),
             ...(cause && { cause }),
         });
         this.code = info.code;

package/dist/event-store/tenant-db-append.js

@@ -1,11 +1,11 @@
-import { tenantDbRunner } from "../db/tenant-db-runner.js";
+import { tenantDbRunner, tenantDbWriteRunner } from "../db/tenant-db-runner.js";
 import { runProjectionsForEvent } from "../pipeline/projections-runner.js";
 import { append, getStreamVersion } from "./event-store.js";
 // Appends on the connection or transaction the TenantDb is bound to. The tenant is always the
 // TenantDb's own, so a caller cannot write into another tenant's stream; a TenantDb the framework
 // did not build (or a fail-closed systemScope guard) is rejected by tenantDbRunner.
 export async function appendEventInTenantDb(tenantDb, event, options = {}) {
-    const runner = tenantDbRunner(tenantDb);
+    const runner = tenantDbWriteRunner(tenantDb, "appendEventInTenantDb");
     const stored = await append(runner, { ...event, tenantId: tenantDb.tenantId });
     if (options.registry)
         await runProjectionsForEvent(stored, options.registry, runner);

package/dist/files/assert-file-refs-belong-to-tenant.d.ts

@@ -1,8 +1,7 @@
-import type { TenantDb } from "../db/tenant-db.js";
-import { type Registry, type SaveContext, type SessionUser } from "../engine/types/index.js";
+import { type Registry, type SaveContext } from "../engine/types/index.js";
+import type { FileRefRows } from "./load-save-file-refs.js";
 export declare function assertFileRefsBelongToTenant(args: {
     readonly registry: Registry;
     readonly result: SaveContext;
-    readonly user: SessionUser;
-    readonly db: TenantDb;
-}): Promise<void>;
+    readonly fileRefRows: FileRefRows;
+}): void;

package/dist/files/assert-file-refs-belong-to-tenant.js

@@ -1,16 +1,17 @@
-import { isFileField, isUuid, } from "../engine/types/index.js";
+import { isFileField } from "../engine/types/index.js";
 import { ValidationError } from "../errors/index.js";
 import { fileRefIdsOf } from "./bind-pending-file-refs.js";
-import { getFileRefExecutor } from "./create-file-ref.js";
 import { FILE_REF_ENTITY_NAME } from "./file-ref-entity.js";
 // A file field only stores an id, and the file routes authorize by tenant at
 // read time: without this check a writer could name another tenant's fileRef
 // and make the record point at it. Only newly written values are checked (all
 // of a create, `changes` of an update), so existing data is left alone. The
 // error is the same for "missing" and "belongs to another tenant" so the id
-// cannot be probed across tenants.
-export async function assertFileRefsBelongToTenant(args) {
-    const { registry, result, user, db } = args;
+// cannot be probed across tenants. `fileRefRows` holds only the writer's own
+// tenant's live rows, so a missing entry is exactly those two cases. Values
+// that are not UUIDs are skipped by fileRefIdsOf and never reach this check.
+export function assertFileRefsBelongToTenant(args) {
+    const { registry, result, fileRefRows } = args;
     // skip: saves of unregistered aggregates (custom executors) declare no file fields
     if (result.entityName === undefined)
         return;
@@ -21,12 +22,11 @@ export async function assertFileRefsBelongToTenant(args) {
     // skip: without the files feature the file_refs table is not part of the schema
     if (registry.getEntity(FILE_REF_ENTITY_NAME) === undefined)
         return;
-    const executor = getFileRefExecutor();
     for (const [fieldName, fieldDef] of Object.entries(entity.fields)) {
         if (!isFileField(fieldDef))
             continue;
         for (const fileRefId of fileRefIdsOf(result.changes[fieldName])) {
-            if (await isFileRefOfTenant(executor, fileRefId, user, db))
+            if (fileRefRows.has(fileRefId))
                 continue;
             throw new ValidationError({
                 fields: [
@@ -40,11 +40,3 @@ export async function assertFileRefsBelongToTenant(args) {
         }
     }
 }
-async function isFileRefOfTenant(executor, fileRefId, user, db) {
-    if (!isUuid(fileRefId))
-        return false;
-    // detail() widens its tenant filter to (self, SYSTEM); only the writer's own
-    // tenant counts here, same as GET /files/:id/meta.
-    const row = await executor.detail({ id: fileRefId }, user, db);
-    return row !== null && row["tenantId"] === user.tenantId;
-}

package/dist/files/bind-pending-file-refs.d.ts

@@ -1,9 +1,11 @@
 import type { TenantDb } from "../db/tenant-db.js";
 import { type Registry, type SaveContext, type SessionUser } from "../engine/types/index.js";
+import type { FileRefRows } from "./load-save-file-refs.js";
 export declare function fileRefIdsOf(value: unknown): readonly string[];
 export declare function bindPendingFileRefs(args: {
     readonly registry: Registry;
     readonly result: SaveContext;
     readonly user: SessionUser;
     readonly db: TenantDb;
+    readonly fileRefRows: FileRefRows;
 }): Promise<void>;

package/dist/files/bind-pending-file-refs.js

@@ -23,7 +23,7 @@ function isPendingUploadFor(row, entityName, fieldName, user) {
 // someone else's upload id in a save payload must not pull that file into a
 // record the caller controls.
 export async function bindPendingFileRefs(args) {
-    const { registry, result, user, db } = args;
+    const { registry, result, user, db, fileRefRows } = args;
     // skip: saves of unnamed aggregates declare no file fields
     if (result.entityName === undefined)
         return;
@@ -42,8 +42,8 @@ export async function bindPendingFileRefs(args) {
         // changes, not data: an update's row carries every stored file id, including
         // ones bound earlier; only the ids this save names can be pending uploads.
         for (const fileRefId of fileRefIdsOf(result.changes[fieldName])) {
-            const row = await executor.detail({ id: fileRefId }, user, db);
-            if (row === null || !isPendingUploadFor(row, entityName, fieldName, user))
+            const row = fileRefRows.get(fileRefId);
+            if (row === undefined || !isPendingUploadFor(row, entityName, fieldName, user))
                 continue;
             const version = typeof row["version"] === "number" ? row["version"] : undefined;
             const bound = await executor.update({ id: fileRefId, version, changes: { entityId: String(result.id) } }, user, db);

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

@@ -13,4 +13,4 @@ export declare const bindReferencedFilesWrite: import("@cosmicdrift/kumiko-types
     bound: number;
     skipped: number;
     nextAfterId: string | null;
-}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;