@cosmicdrift/kumiko-framework 0.361.0 → 0.363.0

package/dist/files/bind-referenced-files.write.js

@@ -0,0 +1,109 @@
+import * as z from "zod";
+import { defineWriteHandler, SYSTEM_ROLE, SYSTEM_USER_ID } from "../engine/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";
+import { findImplicitEntityTable } from "./record-write-check.js";
+const MAX_PAGE_SIZE = 500;
+const DEFAULT_PAGE_SIZE = 200;
+const payloadSchema = z.object({
+    entityType: z.string().min(1),
+    entityIds: z.array(z.uuid()).min(1).max(MAX_PAGE_SIZE).optional(),
+    afterId: z.uuid().optional(),
+    limit: z.number().int().min(1).max(MAX_PAGE_SIZE).default(DEFAULT_PAGE_SIZE),
+});
+function invalidEntityType() {
+    return new ValidationError({
+        fields: [
+            {
+                path: "entityType",
+                code: "invalid_value",
+                i18nKey: "errors.validation.invalid_value",
+            },
+        ],
+    });
+}
+// The entity must have an implicit table and declared file fields, and the files
+// feature must be mounted; anything else is a caller error, not an empty page.
+function resolveFileBearingEntity(registry, entityType) {
+    const entity = registry.getEntity(entityType);
+    const table = findImplicitEntityTable(registry, entityType);
+    if (entity === undefined || table === undefined)
+        throw invalidEntityType();
+    if (registry.getEntity(FILE_REF_ENTITY_NAME) === undefined)
+        throw invalidEntityType();
+    const fileFieldNames = Object.entries(entity.fields)
+        .filter(([, fieldDef]) => isFileField(fieldDef))
+        .map(([fieldName]) => fieldName);
+    if (fileFieldNames.length === 0)
+        throw invalidEntityType();
+    return { entity, table, fileFieldNames };
+}
+// Either the named records or one id-ordered page after afterId.
+function loadRecordPage(db, { entity, table }, { entityIds, afterId, limit }) {
+    return db.selectMany(table, {
+        ...(entity.softDelete === true && { isDeleted: false }),
+        ...(entityIds !== undefined
+            ? { id: entityIds }
+            : afterId !== undefined && { id: { gt: afterId } }),
+    }, { orderBy: { col: "id", direction: "asc" }, ...(entityIds === undefined && { limit }) });
+}
+// Unbound, same tenant, uploaded by the record's creator (or the system), and either
+// unclaimed or pending for exactly this entity field.
+function isBindableToRecord(fileRef, target) {
+    const uploader = fileRef["insertedById"];
+    return (typeof uploader === "string" &&
+        (uploader === target.record["insertedById"] || uploader === SYSTEM_USER_ID) &&
+        fileRef["tenantId"] === target.tenantId &&
+        fileRef["entityId"] === null &&
+        (fileRef["entityType"] === null ||
+            (fileRef["entityType"] === target.entityType && fileRef["fieldName"] === target.fieldName)));
+}
+// The binding follows only the record's declared file fields; the caller names
+// no file ids. The record's creator must have uploaded the file themselves (or the
+// system generated it), otherwise a foreign reference would pull someone else's
+// private upload into the referencing user's record and make it readable there.
+export const bindReferencedFilesWrite = defineWriteHandler({
+    name: "bindReferencedFiles",
+    schema: payloadSchema,
+    access: { roles: [SYSTEM_ROLE, "SystemAdmin"] },
+    // Maintenance backfill run by ops or system jobs, not a task an assistant performs.
+    agent: { expose: false },
+    description: "Binds the files a record references through its declared file fields to that record, so readers of the record see them through record access. Covers files uploaded before pending-upload binding existed (entityId null) and records created without a save lifecycle (custom handlers, system jobs). Binds only files uploaded by the record's creator or generated by the system; skips files already bound elsewhere, uploaded by someone else, of another tenant or missing; never rebinds.",
+    handler: async (event, ctx) => {
+        const { entityType, entityIds, limit } = event.payload;
+        const { fileFieldNames, ...source } = resolveFileBearingEntity(ctx.registry, entityType);
+        const records = await loadRecordPage(ctx.db, source, event.payload);
+        const executor = getFileRefExecutor();
+        let bound = 0;
+        let skipped = 0;
+        for (const record of records) {
+            for (const fieldName of fileFieldNames) {
+                for (const fileRefId of fileRefIdsOf(record[fieldName])) {
+                    const row = await executor.detail({ id: fileRefId }, event.user, ctx.db);
+                    if (row === null ||
+                        !isBindableToRecord(row, {
+                            record,
+                            entityType,
+                            fieldName,
+                            tenantId: event.user.tenantId,
+                        })) {
+                        skipped += 1;
+                        continue;
+                    }
+                    const version = typeof row["version"] === "number" ? row["version"] : undefined;
+                    const result = await executor.update({ id: fileRefId, version, changes: { entityType, entityId: record.id, fieldName } }, event.user, ctx.db);
+                    if (!result.isSuccess)
+                        return result;
+                    bound += 1;
+                }
+            }
+        }
+        const lastRecord = records[records.length - 1];
+        const pageIsFull = entityIds === undefined && records.length === limit;
+        const nextAfterId = pageIsFull ? (lastRecord?.id ?? null) : null;
+        return { isSuccess: true, data: { bound, skipped, nextAfterId } };
+    },
+});

package/dist/files/feature.d.ts

@@ -4,6 +4,7 @@ export { fileRefEntity } from "./file-ref-entity.js";
 export type FilesFeatureOptions = {
     readonly accessGuard?: FileAccessGuard;
     readonly privilegedRoles?: readonly string[];
+    readonly unclaimedUploadReaders?: readonly string[];
     readonly maxUploadSize?: string;
 };
 export declare function createFilesFeature(options?: FilesFeatureOptions): FeatureDefinition;

package/dist/files/feature.js

@@ -1,4 +1,5 @@
 import { defineFeature } from "../engine/index.js";
+import { bindReferencedFilesWrite } from "./bind-referenced-files.write.js";
 import { FILE_REF_ENTITY_NAME, fileRefEntity } from "./file-ref-entity.js";
 export { fileRefEntity } from "./file-ref-entity.js";
 // files — `fileRef` als ganz normales ES-Entity. Upload/Delete laufen über
@@ -21,6 +22,7 @@ export function createFilesFeature(options = {}) {
             recommended: false,
         });
         r.entity(FILE_REF_ENTITY_NAME, fileRefEntity);
+        r.writeHandler(bindReferencedFilesWrite);
         return { routeOptions: options };
     });
 }

package/dist/files/file-routes.d.ts

@@ -28,10 +28,11 @@ export type FileRoutesOptions = {
     readonly registry?: Registry;
     readonly maxUploadSize?: string;
     readonly privilegedRoles?: readonly string[];
+    readonly unclaimedUploadReaders?: readonly string[];
     readonly accessGuard?: FileAccessGuard;
     readonly canReadRecord?: RecordReadCheck;
     readonly canWriteRecord?: RecordWriteCheck;
 };
 export declare function resolveMaxUploadBodyBytes(options: Pick<FileRoutesOptions, "registry" | "maxUploadSize">): number;
-export declare function readFilesRouteOptions(registry: Registry): Pick<FileRoutesOptions, "accessGuard" | "privilegedRoles" | "maxUploadSize">;
+export declare function readFilesRouteOptions(registry: Registry): Pick<FileRoutesOptions, "accessGuard" | "privilegedRoles" | "unclaimedUploadReaders" | "maxUploadSize">;
 export declare function createFileRoutes(options: FileRoutesOptions): Hono;

package/dist/files/file-routes.js

@@ -26,12 +26,18 @@ const SIGNED_URL_DEFAULT_EXPIRY_SECONDS = 15 * 60;
 // files. Pending uploads (entityType set, record not yet created) are the
 // uploader's own until bound; so are uploads without an entityType, which no
 // record can ever claim.
-function createDefaultGuard(privilegedRoles, canReadRecord) {
+function createDefaultGuard(privilegedRoles, canReadRecord, unclaimedUploadReaders) {
     return async ({ fileRef, user, operation }) => {
         if (fileRef.insertedById === user.id)
             return "allow";
         if (privilegedRoles.some((role) => user.roles.includes(role)))
             return "allow";
+        const isUnclaimed = fileRef.entityType === null && fileRef.entityId === null;
+        if (isUnclaimed &&
+            operation === "read" &&
+            unclaimedUploadReaders.some((role) => user.roles.includes(role))) {
+            return "allow";
+        }
         if (fileRef.entityType === null || fileRef.entityId === null)
             return "deny";
         if (operation !== "read" || canReadRecord === undefined)
@@ -68,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;
         }
     }
@@ -77,7 +83,8 @@ export function readFilesRouteOptions(registry) {
 export function createFileRoutes(options) {
     const { db } = options;
     const privilegedRoles = options.privilegedRoles ?? DEFAULT_PRIVILEGED_ROLES;
-    const guard = options.accessGuard ?? createDefaultGuard(privilegedRoles, options.canReadRecord);
+    const guard = options.accessGuard ??
+        createDefaultGuard(privilegedRoles, options.canReadRecord, options.unclaimedUploadReaders ?? []);
     const executor = getFileRefExecutor();
     const piiSubjectFields = collectPiiSubjectFields(fileRefEntity);
     const api = new Hono();

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/files/record-write-check.d.ts

@@ -14,6 +14,7 @@ export type RecordWriteCheck = (args: {
     readonly fieldName: string | undefined;
     readonly user: SessionUser;
 }) => Promise<RecordWriteDecision>;
+export declare function findImplicitEntityTable(registry: Registry, entityType: string): import("@cosmicdrift/kumiko-types/schema-table-types").SchemaTable | undefined;
 export declare function createRecordWriteCheck(args: {
     readonly registry: Registry;
     readonly canReadRecord: RecordReadCheck;

package/dist/files/record-write-check.js

@@ -8,6 +8,14 @@ export const RecordWriteDecisions = {
     forbidden: "forbidden",
     locked: "locked",
 };
+export function findImplicitEntityTable(registry, entityType) {
+    for (const projection of registry.getAllProjections().values()) {
+        if (projection.isImplicit === true && projection.source === entityType) {
+            return projection.table;
+        }
+    }
+    return undefined;
+}
 function isEntityUpdateWrite(qn, entityName) {
     return qn.endsWith(`:write:${toKebab(entityName)}:update`);
 }
@@ -25,20 +33,12 @@ export function createRecordWriteCheck(args) {
         }
         return undefined;
     }
-    function findEntityTable(entityType) {
-        for (const projection of registry.getAllProjections().values()) {
-            if (projection.isImplicit === true && projection.source === entityType) {
-                return projection.table;
-            }
-        }
-        return undefined;
-    }
     return async ({ entityType, entityId, fieldName, user }) => {
         if (!(await canReadRecord({ entityType, entityId, user }))) {
             return RecordWriteDecisions.notFound;
         }
         const entity = registry.getEntity(entityType);
-        const table = findEntityTable(entityType);
+        const table = findImplicitEntityTable(registry, entityType);
         if (!entity || !table)
             return RecordWriteDecisions.notFound;
         // The stored row, not the detail output: the detail query can hide ownership fields.

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

package/dist/pipeline/dispatch-shared.js

@@ -27,6 +27,7 @@ import { executeQuery } from "./dispatch-query.js";
 import { executeWrite } from "./dispatch-write.js";
 import { dispatcherSpanAttributes, isFailedWriteResult, NestedWriteRollback, } from "./dispatcher-utils.js";
 import { createMemberReaderFn } from "./member-reader.js";
+import { createDeferringNotify } from "./notify-scope.js";
 import { createGatedIdentitySwitch, createGatedMemberReader, createGatedProjectionReader, isSystemIdentity, systemIdentitySwitchDenied, } from "./system-identity-switch.js";
 import { buildPersonalDataGate, rootWriteOrigin } from "./write-origin.js";
 // Framework/pipeline stays bundled-features-free, so this can't import the
@@ -47,8 +48,10 @@ export const DEFAULT_MEMBER_READ_TIMEOUT_MS = 10_000;
 // dispatch-Pfade brauchen DbConnection (oder DbTx aus Caller-Scope) für
 // appendEvent/projection-writes; TenantDb-Branch wird hier ausgeschlossen.
 export function resolveDbSource(ctx, tx) {
-    const { appContext: context } = ctx;
-    return tx ?? context.db; // @cast-boundary db-operator
+    return tx ?? resolveAppPoolDb(ctx);
+}
+function resolveAppPoolDb(ctx) {
+    return ctx.appContext.db; // @cast-boundary db-operator
 }
 // ctx.appendEvent — append a domain event onto a specific aggregate stream
 // in the current tx, then fire matching inline projections. Core logic
@@ -248,7 +251,7 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
     // that is meant to outlive the request. Computed before `systemDb` below
     // so its guarded escape hatch (ctx.systemDb.outsideTransaction) can wrap
     // this same TenantDb instead of a second, independently-built one.
-    const outsideTxSource = ctx.outsideTransactionDb ?? resolveDbSource(ctx, undefined);
+    const outsideTxSource = ctx.outsideTransactionDb ?? resolveAppPoolDb(ctx);
     const rawDbOutsideTransaction = outsideTxSource
         ? buildTenantScopedDb(outsideTxSource, undefined)
         : undefined;
@@ -279,9 +282,40 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
         userId: user.id,
         ...(reqCtx && { requestId: reqCtx.requestId }),
     });
-    const notify = context._notifyFactory
-        ? context._notifyFactory(user, user.tenantId, isNotifyJobDispatcher(jobRunner) ? jobRunner : undefined)
+    // Cross-feature bridge: ctx.query/write share the current tx + afterCommitHooks sink.
+    // queryAs/writeAs to anyone but the caller itself needs r.systemScope() or { escapeHatch } (system-identity-switch.ts).
+    const bridgeSink = afterCommitHooks ?? [];
+    // Query bridges and post-commit contexts get a throwaway sink: hooks pushed there never run.
+    const hasLiveCommitSink = afterCommitHooks !== undefined && isPostCommit !== true;
+    const scheduleAfterCommit = (hook) => {
+        bridgeSink.push(hook);
+    };
+    const notifyFactory = context._notifyFactory;
+    const notifyJobDispatcher = isNotifyJobDispatcher(jobRunner) ? jobRunner : undefined;
+    // Inside the write tx the app pool's slots can all be held by waiting write txs, so the
+    // delivery's own DB work (broadcast lookup, attempt log, channel sends) runs on the outside-tx pool.
+    const notifyInTransactionFactory = notifyFactory && tx !== undefined
+        ? (notifyUser, notifyTenantId) => notifyFactory(notifyUser, notifyTenantId, notifyJobDispatcher, outsideTxSource, context._fileProviderResolver)
         : undefined;
+    const notify = buildNotify();
+    function buildNotify() {
+        if (!notifyFactory)
+            return undefined;
+        const notifyAfterCommit = notifyFactory(user, user.tenantId, notifyJobDispatcher, undefined, context._fileProviderResolver);
+        if (!notifyInTransactionFactory)
+            return notifyAfterCommit;
+        const notifyInTransaction = notifyInTransactionFactory(user, user.tenantId);
+        // A rolled-back write must leave no notification behind.
+        if (!hasLiveCommitSink)
+            return notifyInTransaction;
+        return createDeferringNotify({
+            registry,
+            tenantId: user.tenantId,
+            notifyAfterCommit,
+            notifyNow: notifyInTransaction,
+            scheduleAfterCommit,
+        });
+    }
     // Mirror notify: only built when the config feature wired its factory.
     const config = context._configAccessorFactory && db
         ? context._configAccessorFactory({
@@ -361,9 +395,6 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
     const metricsFor = meter
         ? (targetFeatureName) => createSafeMetricsHandle(meter, targetFeatureName)
         : () => createNoopMetricsHandle();
-    // Cross-feature bridge: ctx.query/write share the current tx + afterCommitHooks sink.
-    // queryAs/writeAs to anyone but the caller itself needs r.systemScope() or { escapeHatch } (system-identity-switch.ts).
-    const bridgeSink = afterCommitHooks ?? [];
     // A failed inner write has already appended its event and projections when a later
     // step (e.g. an inTransaction hook) fails, and the outer handler may swallow the
     // failure result. The savepoint makes the failure undo exactly the inner write; the
@@ -374,7 +405,7 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
         const innerAfterCommitHooks = [];
         try {
             const result = await runInSavepoint(tx, async (savepointTx) => {
-                const innerResult = await executeWrite(ctx, targetType, payload, asUser, origin, savepointTx, // @cast-boundary driver savepoint handle is a transaction handle
+                const innerResult = await executeWrite(ctx, targetType, payload, asUser, origin, savepointTx, // @cast-boundary db-runner savepoint handle is a transaction handle
                 innerAfterCommitHooks);
                 if (isFailedWriteResult(innerResult))
                     throw new NestedWriteRollback(innerResult);
@@ -396,9 +427,6 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
     const writeAsUser = async (asUser, targetType, payload) => isPostCommit
         ? unwrapSingle(await runBatch(ctx, [{ type: targetType, payload }], asUser, undefined, origin))
         : executeNestedWriteInSavepoint(asUser, targetType, payload);
-    const scheduleAfterCommit = (hook) => {
-        bridgeSink.push(hook);
-    };
     const identitySwitchAudit = { reason: identitySwitchGrantReason, report: reportEscapeHatch };
     const identitySwitch = createGatedIdentitySwitch(`handler "${type}"`, user, hasIdentitySwitchGrant, {
         // Inherits the caller's origin, so switching to SYSTEM cannot shed an anonymous root.
@@ -733,9 +761,12 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
     const locale = reqCtx?.locale ?? safeUserLocale ?? context.defaultLocale ?? DEFAULT_LOCALE;
     // The payload-bucket digest is dispatcher-internal; handlers must not be
     // able to compute bucket keys.
-    const { _rateLimitPayloadDigest: _omitPayloadDigest, ...contextForHandler } = context;
+    const { _rateLimitPayloadDigest: _omitPayloadDigest, 
+    // Bound to this call's tx: an outer context's factory must not leak into a tx-less one.
+    _notifyInTransactionFactory: _omitOuterNotifyInTransactionFactory, ...contextForHandler } = context;
     const handlerContext = {
         ...contextForHandler,
+        ...(notifyInTransactionFactory && { _notifyInTransactionFactory: notifyInTransactionFactory }),
         registry,
         db: exposedDb,
         dbOutsideTransaction,
@@ -781,7 +812,7 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
         _userId: user.id,
         _tenantId: user.tenantId,
         _handlerType: type,
-        scheduleAfterCommit,
+        ...(hasLiveCommitSink && { scheduleAfterCommit }),
         ...(includeDeleted && { includeDeleted: true }),
         ...bridge,
     }; // @cast-boundary engine-bridge

package/dist/pipeline/event-dispatcher-delivery.js

@@ -57,8 +57,7 @@ export async function acquireConsumerState(tx, name, instanceId, rearmCooldownMs
         const cooldownElapsed = Temporal.Instant.compare(state.updatedAt, cooldownDeadline) <= 0;
         if (cooldownElapsed && state.rearmCount < maxRearmCount) {
             const rearmed = await rearmDeadConsumer(tx, name, instanceId);
-            const rearmedState = rearmed &&
-                coerceRow(rearmed, extractTableInfo(eventConsumerStateTable));
+            const rearmedState = rearmed && coerceRow(rearmed, extractTableInfo(eventConsumerStateTable));
             if (rearmedState)
                 return { state: rearmedState, skip: null };
         }
@@ -149,7 +148,7 @@ export async function markProcessing(tx, name, instanceId) {
 export async function fetchPendingEvents(tx, cursor, batchSize, pendingRanges = []) {
     const rawRows = await selectPendingAndNewEventRows(tx, cursor, pendingRanges, batchSize);
     const info = extractTableInfo(eventsTable);
-    return rawRows.map((row) => coerceRow(row, info)); // @cast-boundary db-row
+    return rawRows.map((row) => coerceRow(row, info));
 }
 // Deliver events to the consumer's handler in events.id order, or — when
 // the consumer wires a batchHandler — through it in one call first. Halt-

package/dist/pipeline/index.d.ts

@@ -30,6 +30,7 @@ export type { LifecycleHooks, SystemHookDef, SystemHooks } from "./lifecycle-pip
 export { createLifecycleHooks } from "./lifecycle-pipeline.js";
 export type { MspRebuildDeps } from "./msp-rebuild.js";
 export { rebuildMultiStreamProjection } from "./msp-rebuild.js";
+export { assertNotifyTargetsOwnTenant, createDeferringNotify } from "./notify-scope.js";
 export type { ProjectionProgress, RebuildResult } from "./projection-rebuild.js";
 export { getAllProjectionProgress, getProjectionState, listProjectionsWithState, rebuildProjection, } from "./projection-rebuild.js";
 export type { ProjectionStatus } from "./projection-state.js";

package/dist/pipeline/index.js

@@ -15,6 +15,7 @@ export { createIdempotencyGuard } from "./idempotency.js";
 export { assertInstructionFieldWriteAllowed, assertIrreversibleOperationAllowed, isIrreversibleEntityVerb, } from "./irreversible-operation-gate.js";
 export { createLifecycleHooks } from "./lifecycle-pipeline.js";
 export { rebuildMultiStreamProjection } from "./msp-rebuild.js";
+export { assertNotifyTargetsOwnTenant, createDeferringNotify } from "./notify-scope.js";
 export { getAllProjectionProgress, getProjectionState, listProjectionsWithState, rebuildProjection, } from "./projection-rebuild.js";
 export { createProjectionStateTable, ProjectionStatuses, projectionStateTable, } from "./projection-state.js";
 export { runProjectionsForEvent } from "./projections-runner.js";

package/dist/pipeline/member-read-only-transaction.js

@@ -34,7 +34,7 @@ async function runInDiscardedReadOnlySavepoint(tx, timeoutMs, bindIdleTimeout, f
         await runInSavepoint(tx, async (sp) => {
             // kumiko-lint-ignore raw-sql transaction characteristic, no query helper
             await asRawClient(sp).unsafe(memberReadSessionSettingsSql(timeoutMs, bindIdleTimeout));
-            // @cast-boundary driver savepoint handle — structurally a DbTx, same shape runInSavepoint's caller relies on
+            // @cast-boundary db-runner savepoint handle — structurally a DbTx, same shape runInSavepoint's caller relies on
             settled.outcome = { value: await fn(sp) };
             // Always discarded: RELEASE SAVEPOINT would leave the outer tx read-only too.
             throw new SavepointDiscard();

package/dist/pipeline/notify-scope.d.ts

@@ -0,0 +1,13 @@
+import type { TenantId } from "../engine/types/identifiers.js";
+import type { NotifyFn, NotifyOptions, Registry } from "../engine/types/index.js";
+import type { AfterCommitHook } from "./dispatcher-utils.js";
+export declare function assertNotifyTargetsOwnTenant(options: NotifyOptions, tenantId: TenantId): void;
+type DeferringNotifyDeps = {
+    readonly registry: Pick<Registry, "getAllNotifications"> | undefined;
+    readonly tenantId: TenantId;
+    readonly notifyAfterCommit: NotifyFn;
+    readonly notifyNow: NotifyFn;
+    readonly scheduleAfterCommit: (hook: AfterCommitHook) => void;
+};
+export declare function createDeferringNotify(deps: DeferringNotifyDeps): NotifyFn;
+export {};

package/dist/pipeline/notify-scope.js

@@ -0,0 +1,32 @@
+import { assertNotificationVariables } from "../engine/template-variables.js";
+import { AccessDeniedError, FrameworkReasons } from "../errors/index.js";
+function isTenantBroadcast(to) {
+    return typeof to === "object" && to !== null && !Array.isArray(to) && "tenant" in to;
+}
+export function assertNotifyTargetsOwnTenant(options, tenantId) {
+    const { to } = options;
+    if (isTenantBroadcast(to) && to.tenant !== tenantId) {
+        throw new AccessDeniedError({
+            message: "ctx.notify can only broadcast to the caller's own tenant",
+            details: { reason: FrameworkReasons.notifyForeignTenantBroadcast },
+        });
+    }
+}
+// Without `immediate`, a notify inside a write transaction waits for the commit so a
+// rolled-back write leaves no notification behind.
+export function createDeferringNotify(deps) {
+    const { registry, tenantId, notifyAfterCommit, notifyNow, scheduleAfterCommit } = deps;
+    async function notifyDeferringUntilCommit(notificationType, options) {
+        assertNotifyTargetsOwnTenant(options, tenantId);
+        // Fail the write now: after the commit the problem would only surface in the render job.
+        if (registry)
+            assertNotificationVariables(registry, notificationType, options.data);
+        if (options.immediate === true)
+            return notifyNow(notificationType, options);
+        scheduleAfterCommit(async () => {
+            await notifyAfterCommit(notificationType, options);
+        });
+        return { kind: "deferred" };
+    }
+    return notifyDeferringUntilCommit;
+}

package/dist/pipeline/system-hooks.js

@@ -1,3 +1,4 @@
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import { readNonEmptyStringArray, } from "../api/sse-broker.js";
 import { collectSearchableSubjectFields, configuredPiiSubjectKms, decryptPiiFieldValues, isPiiCiphertext, PII_ERASED_SENTINEL, } from "../crypto/index.js";
 import { createTenantDb, entityTableFromRegistry, rehydrateCompoundTypes } from "../db/index.js";
@@ -520,7 +521,7 @@ const TENANT_MEMBERSHIP_UPDATED_EVENT_TYPE = "tenant-membership.updated";
 const TENANT_MEMBERSHIP_DELETED_EVENT_TYPE = "tenant-membership.deleted";
 function readUserIdFromPreviousSnapshot(payload) {
     const previous = payload["previous"];
-    if (typeof previous !== "object" || previous === null)
+    if (!isPlainObject(previous))
         return undefined;
     const userId = previous["userId"];
     return typeof userId === "string" && userId.length > 0 ? userId : undefined;

package/dist/pipeline/system-identity-switch.js

@@ -124,14 +124,14 @@ export function createGatedProjectionReader(callerLabel, hasGrant, ungated, audi
 function readIdentitySwitchFn(context, key) {
     if (!(key in context))
         return undefined;
-    const value = context[key];
+    const value = Reflect.get(context, key);
     return typeof value === "function" ? value : undefined; // @cast-boundary engine-bridge — checked via typeof above
 }
 // context's own keys only — never touch a property of the resolved value, which may be a Proxy that throws on any get.
 function readDbLikeValue(context, key) {
     if (!(key in context))
         return undefined;
-    const value = context[key];
+    const value = Reflect.get(context, key);
     return typeof value === "object" && value !== null ? value : undefined;
 }
 function unavailableIdentitySwitchFn(callerLabel, kind) {

package/dist/pipeline/write-origin.js

@@ -39,11 +39,11 @@ function declaresPublicIntake(access) {
 // Only the public dispatcher entry points compute a root; every nested call inherits
 // it, so switching identity via ctx.writeAs(SYSTEM, ...) cannot shed an anonymous root.
 export function rootWriteOrigin(registry, type, user) {
-    const writeHandler = registry.getWriteHandler(type);
+    const rootHandler = registry.getWriteHandler(type) ?? registry.getQueryHandler(type);
     return {
         rootHandler: type,
         anonymousRoot: user.roles.includes(ANONYMOUS_ROLE),
-        publicIntake: writeHandler !== undefined && declaresPublicIntake(writeHandler.access),
+        publicIntake: rootHandler !== undefined && declaresPublicIntake(rootHandler.access),
     };
 }
 // Owner binding is ignored (honorOwnerBinding=false): all anonymous callers share one

package/dist/search/meilisearch-adapter.js

@@ -1,3 +1,4 @@
+import { errorCodeOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { ErrorStatusCode, Meilisearch } from "meilisearch";
 // meilisearch's waitTask() RESOLVES (never rejects) once the server task
 // reaches a terminal state, even "failed" — a rejected doc (e.g. an id over
@@ -23,10 +24,8 @@ const INDEX_LIST_PAGE_SIZE = 100;
 // What an unconfigured Meilisearch index reports as searchableAttributes.
 const MEILI_ALL_ATTRIBUTES = "*";
 function isIndexNotFound(err) {
-    const cause = typeof err === "object" && err !== null ? err.cause : null;
-    return (typeof cause === "object" &&
-        cause !== null &&
-        cause.code === ErrorStatusCode.INDEX_NOT_FOUND);
+    const cause = typeof err === "object" && err !== null && "cause" in err ? err.cause : null;
+    return errorCodeOf(cause) === ErrorStatusCode.INDEX_NOT_FOUND;
 }
 // Exported for unit tests (index-name / primary-key shape) without a live Meili.
 export function meilisearchTenantIndex(prefix, tenantId) {