@cosmicdrift/kumiko-framework 0.393.0 → 0.395.0

package/dist/engine/boot-validator/screens-kind-projection-list.js

@@ -2,6 +2,7 @@ import { normalizeListColumn } from "../screen-helpers.js";
 import { validateListBulkActions } from "./list-bulk-actions.js";
 import { validateListTableOptions } from "./list-table-options.js";
 import { assertWriteHandlerRegistered, resolveRowActionNavigateTarget, validateAtMostOneRowClick, validateDrawerTargetAction, } from "./screens-actions.js";
+import { validateDashboardPanelVisibleWhen } from "./screens-dashboard.js";
 import { listActionContext, rejectEmptyColumns, rejectMissingQuery, rejectNonArrayInFilter, validateListColumnRendering, } from "./screens-kind-shared.js";
 import { validateListActionTargets, validateListFacets } from "./screens-lists.js";
 function validateProjectionListRowActions(ctx, screenId, rowActions) {
@@ -15,6 +16,7 @@ function validateProjectionListRowActions(ctx, screenId, rowActions) {
 function validateProjectionListToolbarActions(ctx, screenId, toolbarActions) {
     const featureName = ctx.feature.name;
     for (const action of toolbarActions) {
+        validateDashboardPanelVisibleWhen(`[Feature ${featureName}] Screen "${screenId}" (projectionList) toolbarAction "${action.id}"`, action.visibleWhen);
         if (action.kind === "drawer") {
             validateDrawerTargetAction(featureName, screenId, "projectionList", "toolbarAction", action, ctx.feature.screens);
         }

package/dist/engine/boot-validator/screens-lists.js

@@ -201,6 +201,9 @@ function validateRelatedListDefaultSort(args, defaultSort) {
 function validateRelatedListToolbarActions(args, toolbarActions) {
     const { featureName, screenId, screenType, screens, allScreenQns, navTargetShortIds, screensByShortId, detailForScreens, } = args;
     for (const action of toolbarActions) {
+        if (action.visibleWhen !== undefined) {
+            throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) relatedList toolbarAction "${action.id}" sets visibleWhen, which only list-screen toolbars support. Use visible (a condition on the enclosing record) instead.`);
+        }
         if (action.kind === "drawer") {
             validateDrawerTargetAction(featureName, screenId, screenType, "toolbarAction", action, screens);
         }

package/dist/engine/boot-validator/selector-owner-panels.js

@@ -15,7 +15,7 @@ export function validateExtensionSelectorPanels(features) {
                     validateDashboardCustomPanel(feature.name, where, panel);
                     continue;
                 }
-                validateDashboardScreenPanel(feature.name, where, panel, featureMap);
+                validateDashboardScreenPanel(feature.name, where, panel, featureMap, undefined);
                 if (panel.visibleWhen !== undefined) {
                     checkQueryRef(queryHandlers, panel.visibleWhen.query, () => `${context} visibleWhen`);
                 }

package/dist/engine/boot-validator/transaction-phases.d.ts

@@ -0,0 +1,3 @@
+import type { FeatureDefinition } from "../types/index.ts";
+export declare function validatePerCommandTransaction(featureName: string, handlerName: string, handler: FeatureDefinition["writeHandlers"][string]): void;
+export declare function validateBeforeTransactionWhenNested(featureName: string, handlerName: string, handler: FeatureDefinition["writeHandlers"][string]): void;

package/dist/engine/boot-validator/transaction-phases.js

@@ -0,0 +1,28 @@
+function perCommandConflict(handler) {
+    if (handler.transaction !== "perCommand")
+        return undefined;
+    if (handler.beforeTransaction)
+        return "beforeTransaction";
+    if (handler.reserveBeforeTransaction)
+        return "reserveBeforeTransaction";
+    return undefined;
+}
+export function validatePerCommandTransaction(featureName, handlerName, handler) {
+    const conflicting = perCommandConflict(handler);
+    if (conflicting !== undefined) {
+        throw new Error(`write handler "${featureName}:write:${handlerName}" declares transaction: "perCommand" together with ${conflicting} — ` +
+            "a perCommand handler holds no transaction, so move the phase into the commands it issues via ctx.dispatch.write.");
+    }
+}
+export function validateBeforeTransactionWhenNested(featureName, handlerName, handler) {
+    // skip: handler does not opt into running nested without the phase
+    if (handler.beforeTransactionWhenNested === undefined)
+        return;
+    const where = `write handler "${featureName}:write:${handlerName}" declares beforeTransactionWhenNested`;
+    if (!handler.beforeTransaction) {
+        throw new Error(`${where} without beforeTransaction — there is no phase to skip.`);
+    }
+    if (handler.reserveBeforeTransaction) {
+        throw new Error(`${where} together with reserveBeforeTransaction — a nested run cannot skip the reservation, it would run unreserved.`);
+    }
+}

package/dist/engine/define-handler.d.ts

@@ -1,12 +1,13 @@
 import type { CursorResult } from "@cosmicdrift/kumiko-types/cursor-types";
 import type { KumikoEventTypeMap } from "@cosmicdrift/kumiko-types/event-type-map";
+import type { BeforeTransactionWhenNested } from "@cosmicdrift/kumiko-types/handlers";
 import type { ZodType } from "zod";
 import type { ContainsSecret } from "../secrets/types.ts";
 import type { QueryHandlerDefinition, WriteHandlerDefinition, WriteHandlerInput } from "./types/define-handler.ts";
 export type { QueryHandlerDefinition, StreamHandlerDefinition, WriteHandlerDefinition, WriteHandlerInput, } from "./types/define-handler.ts";
-export declare function defineWriteHandler<const TName extends string, TSchema extends ZodType, TData = unknown, TMap extends object = KumikoEventTypeMap, TPrepared = undefined>(def: WriteHandlerInput<TName, TSchema, TData, TMap, TPrepared>, ..._noSecretInResponse: true extends ContainsSecret<TData> ? [
+export declare function defineWriteHandler<const TName extends string, TSchema extends ZodType, TData = unknown, TMap extends object = KumikoEventTypeMap, TPrepared = undefined, TWhenNested extends BeforeTransactionWhenNested | undefined = undefined>(def: WriteHandlerInput<TName, TSchema, TData, TMap, TPrepared, TWhenNested>, ..._noSecretInResponse: true extends ContainsSecret<TData> ? [
     secretLeak: "A handler response must not contain a Secret<> — call .reveal() and return the plaintext, or drop the field."
-] : []): WriteHandlerDefinition<TName, TSchema, TData, TMap, TPrepared>;
+] : []): WriteHandlerDefinition<TName, TSchema, TData, TMap, TPrepared, TWhenNested>;
 export declare function defineQueryHandler<const TName extends string, TSchema extends ZodType, TResult = unknown, TMap extends object = KumikoEventTypeMap>(def: QueryHandlerDefinition<TName, TSchema, TResult, TMap>, ..._noSecretInResponse: true extends ContainsSecret<TResult> ? [
     secretLeak: "A handler response must not contain a Secret<> — call .reveal() and return the plaintext, or drop the field."
 ] : []): QueryHandlerDefinition<TName, TSchema, TResult, TMap>;

package/dist/engine/define-handler.js

@@ -5,6 +5,9 @@ function pickPreTransactionPhases(def) {
     return {
         ...(def.reserveBeforeTransaction && { reserveBeforeTransaction: def.reserveBeforeTransaction }),
         ...(def.beforeTransaction && { beforeTransaction: def.beforeTransaction }),
+        ...(def.beforeTransactionWhenNested && {
+            beforeTransactionWhenNested: def.beforeTransactionWhenNested,
+        }),
     };
 }
 // `in` keeps both branches of the discriminated union readable regardless of narrowing.

package/dist/engine/factories.d.ts

@@ -199,4 +199,6 @@ export declare function createEntity<const F, const T extends EntityTenancy = "t
     readonly tenancy?: T;
     /** See EntityDefinition.transferable. */
     readonly transferable?: boolean;
+    /** See EntityDefinition.attachedFileAccess. */
+    readonly attachedFileAccess?: EntityDefinition["attachedFileAccess"];
 }): F extends FieldsMap ? EntityDefinition<F, T> : never;

package/dist/engine/feature-config-events-jobs.js

@@ -108,6 +108,9 @@ export function buildConfigEventsJobsMethods(state, name) {
                     ...(jobOptions.trigger.where !== undefined
                         ? { where: jobOptions.trigger.where }
                         : {}),
+                    ...(jobOptions.trigger.catchUp !== undefined
+                        ? { catchUp: jobOptions.trigger.catchUp }
+                        : {}),
                 }
                 : jobOptions.trigger;
             state.jobs[jobName] = { ...jobOptions, trigger, name: jobName, handler: jobHandler };

package/dist/engine/feature-entity-handlers.d.ts

@@ -1,7 +1,7 @@
 import type { KumikoEventTypeMap } from "@cosmicdrift/kumiko-types/event-type-map";
 import type { EntityObjectDefinition } from "@cosmicdrift/kumiko-types/feature-registrar";
 import type { EntityDefinition } from "@cosmicdrift/kumiko-types/fields";
-import type { AccessRule, EntityRef, EscapeHatchDeclaration, HandlerRef, NameOrRef, RateLimitDeclaration, StreamHandlerFn } from "@cosmicdrift/kumiko-types/handlers";
+import type { AccessRule, BeforeTransactionWhenNested, EntityRef, EscapeHatchDeclaration, HandlerRef, NameOrRef, RateLimitDeclaration, StreamHandlerFn } from "@cosmicdrift/kumiko-types/handlers";
 import type { RelationDefinition } from "@cosmicdrift/kumiko-types/relations";
 import type * as z from "zod";
 import type { ZodType } from "zod";
@@ -14,7 +14,7 @@ export declare function buildEntityHandlerMethods<TName extends string>(state: F
         readonly entity: NameOrRef;
         readonly name: string;
     } & RelationDefinition), relationName?: string, definition?: RelationDefinition): void;
-    writeHandler<TName_1 extends string, TSchema extends ZodType, TPrepared = undefined>(def: WriteHandlerDefinition<TName_1, TSchema, unknown, KumikoEventTypeMap, TPrepared>): HandlerRef;
+    writeHandler<TName_1 extends string, TSchema extends ZodType, TPrepared = undefined, TWhenNested extends BeforeTransactionWhenNested | undefined = undefined>(def: WriteHandlerDefinition<TName_1, TSchema, unknown, KumikoEventTypeMap, TPrepared, TWhenNested>): HandlerRef;
     queryHandler<TName_1 extends string, TSchema extends ZodType>(def: QueryHandlerDefinition<TName_1, TSchema>): HandlerRef;
     streamHandler<TName_1 extends string, TSchema extends ZodType>(nameOrDef: string | StreamHandlerDefinition<TName_1, TSchema>, schema?: TSchema, handler?: StreamHandlerFn<z.infer<TSchema>>, options?: {
         access: AccessRule;

package/dist/engine/feature-entity-handlers.js

@@ -2,6 +2,7 @@ import { ENTITY_CONVENTION_QUERY_BRAND } from "@cosmicdrift/kumiko-types/handler
 import { toTableName } from "../db/table-builder.js";
 import { isEntityConventionQueryHandler, isPagedQueryHandler, PAGED_QUERY_HANDLER_BRAND, } from "./define-handler.js";
 import { assertEscapeHatchAccessIsSystemAdminOnly, registerCrudHandlers, } from "./entity-handlers.js";
+import { agentSlots, transactionPhaseSlots } from "./handler-definition-slots.js";
 import { resolveName } from "./handler-helpers.js";
 import { isObjectArgument, requireArgument, throwObjectArgumentRequired } from "./object-form.js";
 const CRUD_VERBS = new Set(["create", "update", "delete"]);
@@ -48,23 +49,6 @@ function tryMapEntity(state, name, handlerName) {
         }
     }
 }
-function agentSlots(source) {
-    return {
-        ...(source.description !== undefined && { description: source.description }),
-        ...(source.agent && { agent: source.agent }),
-    };
-}
-function transactionPhaseSlots(def) {
-    return {
-        ...(def.reserveBeforeTransaction && {
-            reserveBeforeTransaction: def.reserveBeforeTransaction,
-        }),
-        ...(def.beforeTransaction && {
-            beforeTransaction: def.beforeTransaction, // @cast-boundary engine-bridge
-        }),
-        ...(def.transaction && { transaction: def.transaction }),
-    };
-}
 // Typed callers cannot omit `access`; untyped ones (JS, designer output) must not get a
 // handler that silently falls through to the boot-time default-deny.
 function assertHandlerHasAccess(featureName, method, handlerName, access) {

package/dist/engine/handler-definition-slots.d.ts

@@ -0,0 +1,17 @@
+import type { KumikoEventTypeMap } from "@cosmicdrift/kumiko-types/event-type-map";
+import type { AgentHandlerHints, BeforeTransactionPhase, BeforeTransactionWhenNested } from "@cosmicdrift/kumiko-types/handlers";
+import type { ZodType } from "zod";
+import type { WriteHandlerDefinition } from "./define-handler.ts";
+export declare function agentSlots(source: {
+    readonly description?: string;
+    readonly agent?: AgentHandlerHints;
+}): {
+    description?: string;
+    agent?: AgentHandlerHints;
+};
+export declare function transactionPhaseSlots<TSchema extends ZodType, TPrepared, TWhenNested extends BeforeTransactionWhenNested | undefined>(def: Pick<WriteHandlerDefinition<string, TSchema, unknown, KumikoEventTypeMap, TPrepared, TWhenNested>, "reserveBeforeTransaction" | "beforeTransaction" | "beforeTransactionWhenNested" | "transaction">): {
+    reserveBeforeTransaction?: import("@cosmicdrift/kumiko-types/handlers").PreTransactionReservation | undefined;
+    beforeTransaction?: BeforeTransactionPhase | undefined;
+    beforeTransactionWhenNested?: NonNullable<TWhenNested> | undefined;
+    transaction?: "perCommand" | undefined;
+};

package/dist/engine/handler-definition-slots.js

@@ -0,0 +1,20 @@
+export function agentSlots(source) {
+    return {
+        ...(source.description !== undefined && { description: source.description }),
+        ...(source.agent && { agent: source.agent }),
+    };
+}
+export function transactionPhaseSlots(def) {
+    return {
+        ...(def.reserveBeforeTransaction && {
+            reserveBeforeTransaction: def.reserveBeforeTransaction,
+        }),
+        ...(def.beforeTransaction && {
+            beforeTransaction: def.beforeTransaction, // @cast-boundary engine-bridge
+        }),
+        ...(def.beforeTransactionWhenNested && {
+            beforeTransactionWhenNested: def.beforeTransactionWhenNested,
+        }),
+        ...(def.transaction && { transaction: def.transaction }),
+    };
+}

package/dist/engine/qualified-name.d.ts

@@ -1,3 +1,5 @@
+import { toKebab } from "@cosmicdrift/kumiko-types/kebab-case";
+export { toKebab };
 export declare const QnTypes: {
     readonly write: "write";
     readonly query: "query";
@@ -24,4 +26,3 @@ export declare function isValidQn(value: string): boolean;
 export declare function isKebabSegment(name: string): boolean;
 export declare function qnScope(qualifiedName: string): string | undefined;
 export declare function qualifyEntityName(featureName: string, type: QnType, shortName: string): string;
-export declare function toKebab(input: string): string;

package/dist/engine/qualified-name.js

@@ -8,6 +8,8 @@
 //   "tasks:write:task:create"      → scope=tasks, type=write, name=task:create
 //   "system:hook:search-index"     → scope=system, type=hook, name=search-index
 //   "billing:notify:invoice-sent"  → scope=billing, type=notify, name=invoice-sent
+import { toKebab } from "@cosmicdrift/kumiko-types/kebab-case";
+export { toKebab };
 // Built-in QN types used by the framework.
 // Features can define additional types — the type segment is validated for format only, not membership.
 export const QnTypes = {
@@ -122,17 +124,3 @@ export function qnScope(qualifiedName) {
 export function qualifyEntityName(featureName, type, shortName) {
     return qn(toKebab(featureName), type, toKebab(shortName));
 }
-// Convert camelCase or dot.separated strings to kebab-case.
-// "task.create" → "task-create"
-// "ticketAssigned" → "ticket-assigned"
-// "billing-period.create" → "billing-period-create"
-// "monthlyReport" → "monthly-report"
-// Already kebab-case → unchanged
-// Colons are preserved: "task:create" → "task:create"
-export function toKebab(input) {
-    return input
-        .replace(/\./g, "-") // dots → dashes
-        .replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2") // consecutive uppercase: SSEBroadcast → SSE-Broadcast
-        .replace(/([a-z0-9])([A-Z])/g, "$1-$2") // camelCase boundaries: ticketAssigned → ticket-Assigned
-        .toLowerCase();
-}

package/dist/engine/registry-facade.js

@@ -15,6 +15,12 @@ export function buildRegistryFacade(state) {
         getEntity(name) {
             return state.entityMap.get(name);
         },
+        getReadModelEntity(name) {
+            return state.readModelEntityMap.get(name)?.entity;
+        },
+        getReadModelEntityOwner(name) {
+            return state.readModelEntityMap.get(name)?.featureName;
+        },
         getAllEntities() {
             return state.entityMap;
         },

package/dist/engine/registry-read-models.d.ts

@@ -0,0 +1,2 @@
+import type { RegistryState } from "./registry-state.ts";
+export declare function populateReadModelEntities(state: RegistryState): void;

package/dist/engine/registry-read-models.js

@@ -0,0 +1,24 @@
+// Explicit projections that carry an entity make that entity addressable by file
+// bindings and the file read check, keyed by the source aggregate type. They stay out of
+// entityMap on purpose: CRUD, preSave, write checks and soft-delete cleanup hang off it.
+export function populateReadModelEntities(state) {
+    const registeredBy = new Map();
+    for (const [qualifiedName, projection] of state.projectionMap) {
+        const { entity, source } = projection;
+        if (projection.isImplicit || entity === undefined || typeof source !== "string")
+            continue;
+        if (state.entityMap.has(source))
+            continue;
+        const previous = registeredBy.get(source);
+        if (previous !== undefined) {
+            throw new Error(`Read-model entity "${source}" is declared by two projections ("${previous}" and ` +
+                `"${qualifiedName}"). File bindings address the entity by its source, so each ` +
+                "source may carry an entity in one projection only.");
+        }
+        registeredBy.set(source, qualifiedName);
+        state.readModelEntityMap.set(source, {
+            entity,
+            featureName: qualifiedName.split(":")[0] ?? qualifiedName,
+        });
+    }
+}

package/dist/engine/registry-state.d.ts

@@ -27,6 +27,10 @@ export declare const qualify: typeof qualifyEntityName;
 export type RegistryState = {
     featureMap: Map<string, FeatureDefinition>;
     entityMap: Map<string, EntityDefinition>;
+    readModelEntityMap: Map<string, {
+        readonly entity: EntityDefinition;
+        readonly featureName: string;
+    }>;
     relationMap: Map<string, Record<string, RelationDefinition>>;
     writeHandlerMap: Map<string, WriteHandlerDef>;
     queryHandlerMap: Map<string, QueryHandlerDef>;

package/dist/engine/registry-state.js

@@ -123,6 +123,7 @@ export function createInitialState() {
     return {
         featureMap: new Map(),
         entityMap: new Map(),
+        readModelEntityMap: new Map(),
         relationMap: new Map(),
         writeHandlerMap: new Map(),
         queryHandlerMap: new Map(),

package/dist/engine/registry-validate.js

@@ -682,7 +682,7 @@ export function resolveJobTriggers(state) {
     // existing r.defineEvent registration. The latter is delivered async via the
     // job-trigger event-consumer (server.ts), not the synchronous write-handler
     // dispatch path — see createJobTriggerEventConsumer in
-    // pipeline/system-hooks.ts. Short names are qualified against the job's own
+    // pipeline/job-trigger-consumer.ts. Short names are qualified against the job's own
     // feature and written back, because the job runner matches by exact QN.
     const allHandlers = allHandlerQns(state);
     for (const [jobName, jobDef] of state.jobMap) {
@@ -694,6 +694,14 @@ export function resolveJobTriggers(state) {
         const resolvedOn = isNameOrRefList(triggerOn)
             ? triggerOn.map(resolveTrigger)
             : resolveTrigger(triggerOn);
+        if (jobDef.trigger.catchUp) {
+            const targets = isNameOrRefList(resolvedOn) ? resolvedOn : [resolvedOn];
+            const notEvents = targets.filter((qn) => !state.eventMap.has(qn) || allHandlers.has(qn));
+            if (notEvents.length > 0) {
+                throw new Error(`Job "${jobName}" sets trigger.catchUp but ${notEvents.map((qn) => `"${qn}"`).join(", ")} ` +
+                    `is not an r.defineEvent event. catchUp replays stored events, so every "on" entry must be an event.`);
+            }
+        }
         state.jobMap.set(jobName, { ...jobDef, trigger: { ...jobDef.trigger, on: resolvedOn } });
     }
 }
@@ -783,6 +791,9 @@ export function validateMaxPerTenant(state) {
         if (!Number.isInteger(resolved.limit) || resolved.limit <= 0) {
             throw new Error(`Job "${jobName}" maxPerTenant limit must be a positive integer (got ${resolved.limit})`);
         }
+        if (resolved.onLimit === "skip" && "on" in jobDef.trigger && jobDef.trigger.catchUp) {
+            throw new Error(`Job "${jobName}" cannot combine trigger.catchUp with maxPerTenant onLimit "skip" (a plain number is skip): a replay must not discard history. Use onLimit "defer".`);
+        }
         if (typeof jobDef.maxPerTenant !== "object")
             continue;
         const { deferMs } = jobDef.maxPerTenant;

package/dist/engine/registry.js

@@ -2,6 +2,7 @@ import { validateExtensionPreSaveWiring } from "./boot-validator/entity-handler.
 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 { populateReadModelEntities } from "./registry-read-models.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, validateMaxDefers, validateMaxPerTenant, validateNotificationRecordMappings, validateNotificationRenamedFrom, validateProjectionApplyKeys, validateRelationTargetsExist, validateRequiredFeatures, } from "./registry-validate.js";
 // This is where the magic happens. By "magic" I mean: precomputed maps.
@@ -31,6 +32,7 @@ export function createRegistry(rawFeatures) {
     applyExtensionUsages(state);
     buildSearchableSortableCaches(state);
     buildImplicitProjections(state, features);
+    populateReadModelEntities(state);
     buildIncomingRelations(state);
     validateFieldAccessHandlersAreEntityMapped(state, features);
     validateExtensionPreSaveWiring(features);

package/dist/engine/strip-disabled-features-from-app-schema.js

@@ -11,6 +11,7 @@
 // gone it also drops every action, redirect, nav and workspace member that
 // pointed at them. The one reference it does not resolve is a nav `parent`
 // pointing at a missing nav; that is pruned here.
+import { fallbackTargets } from "@cosmicdrift/kumiko-types/screen";
 import { createFallbackLogger, scrubLogText } from "../logging/index.js";
 import { resolveScreenTargetQn } from "./boot-validator/screens.js";
 import { workspaceOwnerOf } from "./build-app-schema.js";
@@ -107,12 +108,14 @@ function screensKeptForFallback(feature) {
         const fallback = pending.pop()?.fallback;
         if (fallback === undefined)
             continue;
-        const targetQn = resolveScreenTargetQn(feature.featureName, fallback);
-        const target = byQn.get(targetQn);
-        if (target === undefined || kept.has(targetQn))
-            continue;
-        kept.add(targetQn);
-        pending.push(target);
+        for (const fallbackTarget of fallbackTargets(fallback)) {
+            const targetQn = resolveScreenTargetQn(feature.featureName, fallbackTarget);
+            const target = byQn.get(targetQn);
+            if (target === undefined || kept.has(targetQn))
+                continue;
+            kept.add(targetQn);
+            pending.push(target);
+        }
     }
     return feature.screens.filter((screen) => kept.has(qnOf(screen.id)));
 }

package/dist/events-cli.d.ts

@@ -0,0 +1,19 @@
+import type { ConsumerCliOut } from "./consumer-cli-internals.ts";
+import { type RowLevelSecurityMode } from "./db/render-rls-ddl.ts";
+import type { FeatureDefinition } from "./engine/types/feature.ts";
+export type RunEventsCliOptions = {
+    /** The composed app features: needed to validate types and to find the projections they feed. */
+    readonly features: readonly FeatureDefinition[];
+    /** The mode the app runs with (`AppConfig.rowLevelSecurity`); the removal runs in system scope. */
+    readonly rowLevelSecurity?: RowLevelSecurityMode;
+};
+export type ParsedEventsPruneArgs = {
+    readonly ok: true;
+    readonly types: readonly string[];
+    readonly apply: boolean;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+export declare function parseEventsPruneArgs(argv: readonly string[]): ParsedEventsPruneArgs;
+export declare function runEventsCli(argv: readonly string[], out: ConsumerCliOut, options: RunEventsCliOptions): Promise<number>;

package/dist/events-cli.js

@@ -0,0 +1,121 @@
+// Standalone event-log ops CLI (`kumiko events prune`) for the production bundle, same shape as
+// consumer-cli.ts: one runEventsCli(argv, out, options) entry point with its own DB connection.
+// Exists because old events of a retired aggregate type can fail the rebuild that `schema apply`
+// runs, and no other surface removes a type from the log.
+import { createDbConnection, dbConnectionOptionsFromEnv } from "./db/connection.js";
+import { DEFAULT_ROW_LEVEL_SECURITY_MODE } from "./db/render-rls-ddl.js";
+import { createRegistry } from "./engine/registry.js";
+import { removeAggregateTypes, } from "./pipeline/aggregate-type-removal.js";
+import { ensureTemporalPolyfill } from "./time/index.js";
+const AGGREGATE_TYPE_FLAG = "--aggregate-type";
+// Accepts "--aggregate-type <t>" and "--aggregate-type=<t>", repeatable. An unknown flag is an
+// error rather than ignored: a typo such as "--aggregate-types" must not turn into "delete nothing"
+// or, worse, into a partial selection.
+export function parseEventsPruneArgs(argv) {
+    const types = [];
+    let apply = false;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === undefined)
+            continue;
+        if (arg === "--apply") {
+            apply = true;
+        }
+        else if (arg === AGGREGATE_TYPE_FLAG) {
+            const value = argv[i + 1];
+            if (value === undefined || value.startsWith("--")) {
+                return { ok: false, error: `${AGGREGATE_TYPE_FLAG} needs a value.` };
+            }
+            types.push(value);
+            i++;
+        }
+        else if (arg.startsWith(`${AGGREGATE_TYPE_FLAG}=`)) {
+            types.push(arg.slice(AGGREGATE_TYPE_FLAG.length + 1));
+        }
+        else {
+            return { ok: false, error: `Unknown argument: ${arg}` };
+        }
+    }
+    if (types.length === 0) {
+        return { ok: false, error: `At least one ${AGGREGATE_TYPE_FLAG} is required.` };
+    }
+    if (types.some((type) => type.trim().length === 0)) {
+        return { ok: false, error: `${AGGREGATE_TYPE_FLAG} must not be empty.` };
+    }
+    return { ok: true, types: [...new Set(types)], apply };
+}
+function printHelp(write) {
+    write("");
+    write("  Subcommands:");
+    write("    prune --aggregate-type <type> [--aggregate-type <type> ...] [--apply]");
+    write("      Removes every event, snapshot, archive marker and dead letter of the given");
+    write("      aggregate types, and empties the projections fed only by them.");
+    write("      Without --apply it only reports counts.");
+    write("");
+}
+function report(out, result) {
+    const { plan, deleted } = result;
+    out.log("");
+    for (const s of plan.stats) {
+        out.log(`  ${s.aggregateType}: ${s.events} events, ${s.aggregates} aggregates, ${s.tenants} tenants`);
+    }
+    for (const wiped of plan.wipedProjections) {
+        const rows = deleted?.projectionRows[wiped.projection];
+        out.log(`  projection ${wiped.projection} (${wiped.table.tableName}): ${rows === undefined ? "all rows would be deleted" : `${rows} rows deleted`}`);
+    }
+    if (deleted === undefined) {
+        out.log("");
+        out.log("  Dry run, nothing deleted. Re-run with --apply to remove the above.");
+    }
+    else {
+        out.log("");
+        out.log(`  Deleted ${deleted.events} events, ${deleted.snapshots} snapshots, ${deleted.archivedStreams} archive markers, ` +
+            `${deleted.upcasterDeadLetters + deleted.rebuildDeadLetters} dead letters.`);
+    }
+    out.log("");
+}
+export async function runEventsCli(argv, out, options) {
+    // The standalone bundle never runs the app boot that installs Temporal; event rows carry
+    // Temporal.Instant values.
+    await ensureTemporalPolyfill();
+    const [sub, ...rest] = argv;
+    if (sub !== "prune") {
+        if (sub !== undefined)
+            out.err(`  Unknown subcommand: ${sub}`);
+        printHelp(sub === undefined ? out.log : out.err);
+        return sub === undefined ? 0 : 1;
+    }
+    const parsed = parseEventsPruneArgs(rest);
+    if (!parsed.ok) {
+        out.err(`  ${parsed.error}`);
+        return 1;
+    }
+    const dbUrl = process.env["DATABASE_URL"];
+    if (!dbUrl) {
+        out.err("  DATABASE_URL not set.");
+        return 1;
+    }
+    const { db, close } = createDbConnection({
+        url: dbUrl,
+        rowLevelSecurity: options.rowLevelSecurity ?? DEFAULT_ROW_LEVEL_SECURITY_MODE,
+        ...dbConnectionOptionsFromEnv(),
+    });
+    try {
+        const result = await removeAggregateTypes(db, createRegistry(options.features), {
+            types: parsed.types,
+            apply: parsed.apply,
+        });
+        report(out, result);
+        return 0;
+    }
+    catch (e) {
+        out.err("");
+        // Message only: a driver error's stack can carry connection details.
+        out.err(`  ${e instanceof Error ? e.message : String(e)}`);
+        out.err("");
+        return 1;
+    }
+    finally {
+        await close();
+    }
+}

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

@@ -2,10 +2,11 @@ import { isUuid } from "@cosmicdrift/kumiko-types/identifiers";
 import { isFileField } from "../engine/field-helpers.js";
 import { isAnonymousSessionUser } from "../engine/system-user.js";
 import { FrameworkReasons, InternalError, reraiseAsKumikoError, UnprocessableError, } from "../errors/index.js";
-import { getFileRefExecutor, resolveAttachedField } from "./create-file-ref.js";
+import { getFileRefExecutor } from "./create-file-ref.js";
 import { FILE_REF_ENTITY_NAME } from "./file-ref-entity.js";
 import { loadFileRefRows } from "./load-save-file-refs.js";
 import { validateFile } from "./types.js";
+import { resolveAttachedField } from "./upload-field-resolution.js";
 export function fileRefIdsOf(value) {
     if (typeof value === "string")
         return isUuid(value) ? [value] : [];

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, undefined>;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined, undefined>;

package/dist/files/can-caller-read-file-ref.d.ts

@@ -0,0 +1,10 @@
+import type { Registry, SessionUser } from "../engine/types/index.ts";
+import { type FileRef } from "./file-routes.ts";
+export type CanReadFileRefContext = {
+    readonly registry: Registry;
+    readonly user: SessionUser;
+    readonly dispatch: {
+        readonly query: (qn: string, payload: unknown) => Promise<unknown>;
+    };
+};
+export declare function canCallerReadFileRef(ctx: CanReadFileRefContext, fileRef: FileRef): Promise<boolean>;

package/dist/files/can-caller-read-file-ref.js

@@ -0,0 +1,12 @@
+import { createDefaultGuard, DEFAULT_PRIVILEGED_ROLES } from "./default-file-guard.js";
+import { readFilesRouteOptions } from "./file-routes.js";
+import { collectRecordOnlyFileEntityTypes } from "./record-only-file-entity-types.js";
+import { createRecordReadCheck } from "./record-read-check.js";
+// Same decision as GET /files/:id: the app's accessGuard when configured, otherwise the
+// default guard with the configured privileged roles and record-read check.
+export async function canCallerReadFileRef(ctx, fileRef) {
+    const options = readFilesRouteOptions(ctx.registry);
+    const guard = options.accessGuard ??
+        createDefaultGuard(options.privilegedRoles ?? DEFAULT_PRIVILEGED_ROLES, createRecordReadCheck(ctx.registry, (qn, payload) => ctx.dispatch.query(qn, payload)), options.unclaimedUploadReaders ?? [], collectRecordOnlyFileEntityTypes(ctx.registry));
+    return (await guard({ fileRef, user: ctx.user, operation: "read" })) === "allow";
+}

package/dist/files/create-file-ref-from-bytes.d.ts

@@ -21,6 +21,8 @@ export type CreateFileRefInput = {
         readonly fieldName: string;
         readonly entityId?: string;
     };
+    /** Byte limit replacing the configured default upload limit; a file field's own maxSize still applies first. */
+    readonly maxSize?: number;
 };
 export declare function filesUnavailableMessage(caller: string): string;
 export declare function createFileRefFromBytes(ctx: CreateFileRefContext, input: CreateFileRefInput): Promise<WriteResult<CreatedFileRef>>;

package/dist/files/create-file-ref-from-bytes.js

@@ -5,6 +5,9 @@ import { createFileRefRow, DEFAULT_MAX_UPLOAD_SIZE, storeFileAsFileRef, writeAcc
 import { fileRefsTable } from "./file-ref-table.js";
 import { readFilesRouteOptions } from "./file-routes.js";
 import { assertSafeStorageKey } from "./types.js";
+function defaultUploadLimit(registry, input) {
+    return input.maxSize ?? readFilesRouteOptions(registry).maxUploadSize ?? DEFAULT_MAX_UPLOAD_SIZE;
+}
 // The handler context has no HTTP/job/seed marker to name, so the message states the actual
 // cause: the dispatcher's AppContext carries no file-provider resolver.
 export function filesUnavailableMessage(caller) {
@@ -25,7 +28,8 @@ export async function createFileRefFromBytes(ctx, input) {
         tenantDb: ctx.db,
         rowInOwnTransaction: runnerCanBeginTransaction(tenantDbRunner(ctx.db)),
         registry: ctx.registry,
-        defaultMaxUploadSize: readFilesRouteOptions(ctx.registry).maxUploadSize ?? DEFAULT_MAX_UPLOAD_SIZE,
+        attachTargets: "entities-and-read-models",
+        defaultMaxUploadSize: defaultUploadLimit(ctx.registry, input),
         writeBytes: (key, data, mimeType) => files.writeUploadBytes(key, data, mimeType),
         deleteBytes: async (key) => {
             await files.ref(key).delete();
@@ -68,7 +72,8 @@ export async function uploadFileBytesBeforeTransaction(ctx, input) {
     const outcome = await writeAcceptedFileBytes({
         user: ctx.user,
         registry: ctx.registry,
-        defaultMaxUploadSize: readFilesRouteOptions(ctx.registry).maxUploadSize ?? DEFAULT_MAX_UPLOAD_SIZE,
+        attachTargets: "entities-and-read-models",
+        defaultMaxUploadSize: defaultUploadLimit(ctx.registry, input),
         writeBytes: (key, data, mimeType) => files.writeUploadBytes(key, data, mimeType),
     }, {
         fileName: input.fileName,