@cosmicdrift/kumiko-framework 0.377.0 → 0.379.0

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

@@ -5,16 +5,18 @@
 // true buys an entity restore + trash (ctx.includeDeleted) + this cleanup, with
 // no feature to wire.
 //
-// Hard-deleting the projection row leaves the event stream intact (source of
-// truth) — a full projection rebuild would replay created+deleted and
-// resurrect the row as isDeleted=true. That's acceptable: cleanup bounds LIVE
-// 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";
+// Each expired row is purged through the executor's forget verb: the `<entity>.forgotten`
+// event replays on a projection rebuild, so the purged row stays gone. The earlier events stay
+// in the log; irreversible event-log purging is data-retention's job (pruneEvents), a separate,
+// consumer-lag-guarded path.
+import { createEventStoreExecutor } from "../db/event-store-executor.js";
+import { asEntityTableMeta, selectMany } from "../db/query.js";
 import { hasFieldProperty } from "../db/table-introspection.js";
+import { reraiseAsKumikoError } from "../errors/index.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";
+import { createSystemUser, SYSTEM_USER_ID } from "./system-user.js";
+import { SYSTEM_TENANT_ID } from "./types/identifiers.js";
 // qualifyEntityName convention (feature:type:kebab-name) with a reserved
 // "soft-delete" owner — no real feature owns these; the framework synthesizes
 // them. The job-runner keys cron scheduling off the name, the config-resolver
@@ -46,6 +48,10 @@ export function isSystemScopedSoftDeleteTable(table, entity) {
 function isGlobalTenancyTable(table) {
     return asEntityTableMeta(table)?.tenancy === "global";
 }
+async function resolveGraceDays(ctx, tenantId, db) {
+    const resolved = await ctx.configResolver?.get(SOFT_DELETE_GRACE_DAYS_KEY, softDeleteGraceDaysConfig, tenantId, SYSTEM_USER_ID, db);
+    return typeof resolved === "number" && resolved >= 1 ? resolved : DEFAULT_GRACE_DAYS;
+}
 export const softDeleteCleanupJob = async (_payload, ctx) => {
     const { db, registry } = ctx;
     if (!db || !registry) {
@@ -61,10 +67,7 @@ export const softDeleteCleanupJob = async (_payload, ctx) => {
         // skip: cron fired without a perTenant fan-out tenant — nothing scoped to purge
         return;
     }
-    const resolved = ctx.configResolver
-        ? await ctx.configResolver.get(SOFT_DELETE_GRACE_DAYS_KEY, softDeleteGraceDaysConfig, tenantId, SYSTEM_USER_ID, db)
-        : undefined;
-    const graceDays = typeof resolved === "number" && resolved >= 1 ? resolved : DEFAULT_GRACE_DAYS;
+    const graceDays = await resolveGraceDays(ctx, tenantId, db);
     const cutoff = Temporal.Now.instant().subtract({ hours: graceDays * 24 });
     for (const proj of registry.getAllProjections().values()) {
         if (proj.isImplicit !== true || typeof proj.source !== "string" || !proj.table)
@@ -80,23 +83,49 @@ 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, cutoff, ctx);
+        const executor = createEventStoreExecutor(proj.table, entity, { entityName: proj.source });
+        await purgeExpiredRows({ db, executor, user: ctx.systemUser ?? createSystemUser(tenantId) }, proj.source, proj.table, where, cutoff, ctx);
     }
 };
-async function purgeExpiredRows(db, source, table, where, cutoff, ctx) {
+const PURGE_PAGE_SIZE = 500;
+async function forgetRow(writer, id) {
+    // ponytail: one append per expired row, batch when purge volume needs it
+    const result = await writer.executor.forget({ id }, writer.user, writer.db);
+    if (!result.isSuccess)
+        throw reraiseAsKumikoError(result.error);
+}
+async function purgeExpiredRows(writer, source, table, where, cutoff, ctx, readDb = writer.db) {
     if (source === FILE_REF_ENTITY_NAME) {
         // The row is the only record of the storageKey, so its bytes go first.
-        await purgeExpiredFileRefsWithBytes({
-            db,
+        return await purgeExpiredFileRefsWithBytes({
+            db: writer.db,
             table,
             where,
             expiredBefore: cutoff,
             files: ctx.files,
             log: ctx.log,
+            forgetRow: (id) => forgetRow(writer, id),
         });
     }
-    else {
-        await deleteMany(db, table, where);
+    await forgetExpiredPages(writer, source, table, where, ctx, readDb);
+}
+// Keyset on id: a row whose forget fails is logged and skipped, it must not hide the rows behind it.
+async function forgetExpiredPages(writer, source, table, where, ctx, readDb) {
+    let afterId;
+    for (;;) {
+        const page = await selectMany(readDb, table, { ...where, ...(afterId === undefined ? {} : { id: { gt: afterId } }) }, { orderBy: { col: "id", direction: "asc" }, limit: PURGE_PAGE_SIZE });
+        const last = page[page.length - 1];
+        if (last === undefined)
+            break;
+        for (const row of page) {
+            try {
+                await forgetRow(writer, row.id);
+            }
+            catch (err) {
+                ctx.log?.warn(`[soft-delete-cleanup] ${source} ${row.id} not purged: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        afterId = last.id;
     }
 }
 // System-global soft-deleted entities (tenancy "global" or no tenantId column) can't take a
@@ -119,13 +148,13 @@ export const softDeleteCleanupSystemJob = async (_payload, ctx) => {
         if (!isSystemScopedSoftDeleteTable(proj.table, entity))
             continue;
         const where = { isDeleted: true, deletedAt: { lt: cutoff } };
-        if (isGlobalTenancyTable(proj.table)) {
-            // db.global() rejects writes on executor-managed tables; a retention purge has no event to append.
-            await deleteMany(db.unsafeRaw(), proj.table, where);
-        }
-        else {
-            await deleteMany(db, proj.table, where);
-        }
+        const writer = {
+            db,
+            executor: createEventStoreExecutor(proj.table, entity, { entityName: proj.source }),
+            user: ctx.systemUser ?? createSystemUser(SYSTEM_TENANT_ID),
+        };
+        // A global-tenancy table is invisible to a tenant-mode ctx.db, so its candidates are read unscoped.
+        await purgeExpiredRows(writer, proj.source, proj.table, where, cutoff, ctx, isGlobalTenancyTable(proj.table) ? db.unsafeRaw() : db);
     }
 };
 export function buildSoftDeleteCleanupJob() {

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

@@ -16,6 +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 { withExecutorManagedWrites } from "../../db/tenant-db.js";
 import { tenantDbWriteRunner } from "../../db/tenant-db-runner.js";
 import { defineStep } from "../define-step.js";
 import { resolveRequired } from "./_resolver-utils.js";
@@ -27,7 +28,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(tenantDbWriteRunner(ctx.db, "unsafe projection delete"), args.table, where);
+        await deleteMany(withExecutorManagedWrites(tenantDbWriteRunner(ctx.db, "unsafe projection delete")), args.table, where);
     },
 });
 export function buildUnsafeProjectionDeleteStep(args) {

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

@@ -1,5 +1,5 @@
 import * as z from "zod";
-import type { Registry, TemplateListVariableDef, TemplateScalarVariableDef, TemplateVariables } from "./types/index.ts";
+import type { Registry, TemplateImagesVariableDef, TemplateListVariableDef, TemplateScalarVariableDef, TemplateVariables } from "./types/index.ts";
 type CommonOptions = {
     readonly label?: string;
     readonly required?: boolean;
@@ -26,6 +26,7 @@ export declare const templateVariable: {
     readonly percent: (opts?: CommonOptions & {
         readonly example?: number;
     }) => TemplateScalarVariableDef;
+    readonly images: (opts?: CommonOptions) => TemplateImagesVariableDef;
     readonly list: (item: Readonly<Record<string, TemplateScalarVariableDef>>, opts?: CommonOptions & {
         readonly example?: readonly Readonly<Record<string, unknown>>[];
     }) => TemplateListVariableDef;

package/dist/engine/template-variables.js

@@ -17,6 +17,7 @@ export const templateVariable = {
         ...opts,
     }),
     percent: (opts = {}) => ({ type: "percent", ...opts }),
+    images: (opts = {}) => ({ type: "images", ...opts }),
     list: (item, opts = {}) => ({ type: "list", item, ...opts }),
 };
 const LINK_PROTOCOLS = new Set(["http:", "https:", "mailto:"]);
@@ -53,7 +54,10 @@ function scalarToZod(def) {
             return z.number().finite();
     }
 }
+const imagesSchema = z.union([z.string(), z.array(z.string())]);
 function variableToZod(def) {
+    if (def.type === "images")
+        return imagesSchema;
     if (def.type !== "list")
         return scalarToZod(def);
     return z.array(z.object(Object.fromEntries(Object.entries(def.item).map(([name, item]) => [name, withOptionality(item)]))));

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, MaxPerTenantOptions, 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 { 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, MaxPerTenantOptions, NotificationDataFn, NotificationDefinition, NotificationLocalizedTemplate, NotificationRecipientFn, NotificationRecordMapping, NotificationTemplateBody, NotificationTemplateFn, NotificationTemplateMeta, PluralForms, ReferenceDataDef, RegistrarExtensionDef, RegistrarExtensionHooks, RegistrarExtensionRegistration, RunIn, TemplateImagesVariableDef, 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";
@@ -17,7 +17,7 @@ export type { ContentCollectionDefinition, NavDefinition, NavIconKey, } from "@c
 export type { FromRule, FromRuleKind, OwnershipClause, OwnershipMap, OwnershipRef, OwnershipRule, SqlFragment, WhereRule, WhereRuleContext, } from "@cosmicdrift/kumiko-types/ownership";
 export type { EntityProjectionExtension, MspErrorMode, MspErrorPolicy, MultiStreamApplyFn, MultiStreamProjectionDefinition, ProjectionDefinition, ProjectionRowIdOf, ProjectionTable, SingleStreamApplyFn, } from "@cosmicdrift/kumiko-types/projection";
 export type { BelongsToRelation, EntityRelations, HasManyRelation, ManyToManyRelation, RelationDefinition, } from "@cosmicdrift/kumiko-types/relations";
-export type { ActionFormScreenDefinition, ConfigEditScreenDefinition, CustomScreenDefinition, CustomScreenRoute, DashboardChartMarkerKind, DashboardChartPanel, DashboardChartRangeOption, DashboardChartRanges, DashboardCurrencyFormat, DashboardCustomPanel, DashboardDateParam, DashboardFeedPanel, DashboardFilterDefinition, DashboardI18nText, DashboardListPanel, DashboardMoneyParam, DashboardPanelDefinition, DashboardPanelGate, DashboardPanelVisibility, DashboardProgressListPanel, DashboardProgressTone, DashboardRecordBinding, DashboardRefresh, DashboardRelativeTimeFormat, DashboardRelativeTimeParam, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DashboardText, DashboardTextBlock, DashboardTextPanel, DashboardTextParam, DashboardValueFormat, EditExtensionSection, EditFieldPrefill, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EditWriteFormSection, EmbeddedListEditSpec, EntityEditAction, EntityEditActionPlacement, EntityEditScreenDefinition, EntityListExpandableRow, EntityListScreenDefinition, FieldCondition, FieldFormatRegistry, FieldRenderer, FormatSpec, FormWidth, ListColumnSpec, ListEmptyStateSpec, ListFacetSpec, ListPaginationMode, ListSortDir, ListSortSpec, MetricNavigate, MetricSpec, PlatformComponent, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, RecordHeaderSpec, RecordHeaderSubtitlePart, RowAction, RowActionNavigate, RowActionNavigateBase, RowActionWriteHandler, RowFieldExtractor, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenNavSugar, ScreenSlots, SecretMintConfirmStep, SecretMintScreenDefinition, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, ToolbarAction, UnitKey, } from "@cosmicdrift/kumiko-types/screen";
+export type { ActionFormScreenDefinition, ConfigEditScreenDefinition, CustomScreenDefinition, CustomScreenRoute, DashboardChartMarkerKind, DashboardChartPanel, DashboardChartRangeOption, DashboardChartRanges, DashboardCurrencyFormat, DashboardCustomPanel, DashboardDateParam, DashboardFeedPanel, DashboardFilterDefinition, DashboardI18nText, DashboardListPanel, DashboardMoneyParam, DashboardPanelDefinition, DashboardPanelGate, DashboardPanelVisibility, DashboardProgressListPanel, DashboardProgressTone, DashboardRecordBinding, DashboardRefresh, DashboardRelativeTimeFormat, DashboardRelativeTimeParam, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DashboardText, DashboardTextBlock, DashboardTextPanel, DashboardTextParam, DashboardValueFormat, EditExtensionSection, EditFieldPrefill, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EditWriteFormSection, EmbeddedListEditSpec, EntityEditAction, EntityEditActionPlacement, EntityEditScreenDefinition, EntityListExpandableRow, EntityListScreenDefinition, FieldCondition, FieldFormatRegistry, FieldRenderer, FormatSpec, FormFieldDerivation, FormWidth, ListColumnSpec, ListEmptyStateSpec, ListFacetSpec, ListPaginationMode, ListSortDir, ListSortSpec, MetricNavigate, MetricSpec, PlatformComponent, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, RecordHeaderSpec, RecordHeaderSubtitlePart, RowAction, RowActionNavigate, RowActionNavigateBase, RowActionWriteHandler, RowFieldExtractor, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenNavSugar, ScreenSlots, SecretMintConfirmStep, SecretMintScreenDefinition, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, ToolbarAction, UnitKey, } from "@cosmicdrift/kumiko-types/screen";
 export { metricField, relatedListGroupHeaderLabel, relatedListGroupKey, } from "@cosmicdrift/kumiko-types/screen";
 export type { TargetRef } from "@cosmicdrift/kumiko-types/target-ref";
 export type { Subscribe, TreeAction, TreeActionDef, TreeActionsHandle, TreeChildrenSubscribe, TreeNode, TreeNodeState, } from "@cosmicdrift/kumiko-types/tree-node";

package/dist/engine/with-form-derivations.d.ts

@@ -0,0 +1,9 @@
+import * as z from "zod";
+import { type FormDerivationScreen } from "./form-derivations.ts";
+import type { FormFieldDerivation } from "./types/screen.ts";
+/** The `derive` a schema was wrapped with via `withFormDerivations`, so the
+ *  boot validator can prove an actionForm's handler recomputes its totals. */
+export declare function formDerivationsOfSchema(schema: unknown): Readonly<Record<string, FormFieldDerivation>> | undefined;
+/** Server counterpart of an actionForm's `derive`: recomputes the derived head
+ *  fields before the schema validates them, so client-sent totals never count. */
+export declare function withFormDerivations<Schema extends z.ZodType>(schema: Schema, screen: FormDerivationScreen): z.ZodPreprocess<Schema, unknown>;

package/dist/engine/with-form-derivations.js

@@ -0,0 +1,16 @@
+import * as z from "zod";
+import { applyFormDerivations } from "./form-derivations.js";
+const derivationsBySchema = new WeakMap();
+/** The `derive` a schema was wrapped with via `withFormDerivations`, so the
+ *  boot validator can prove an actionForm's handler recomputes its totals. */
+export function formDerivationsOfSchema(schema) {
+    return schema instanceof z.ZodType ? derivationsBySchema.get(schema) : undefined;
+}
+/** Server counterpart of an actionForm's `derive`: recomputes the derived head
+ *  fields before the schema validates them, so client-sent totals never count. */
+export function withFormDerivations(schema, screen) {
+    const wrapped = z.preprocess((value) => applyFormDerivations(value, screen), schema);
+    if (screen.derive !== undefined)
+        derivationsBySchema.set(wrapped, screen.derive);
+    return wrapped;
+}

package/dist/entrypoint/index.d.ts

@@ -7,7 +7,7 @@ import type { PgClient, PgListenClient } from "../db/connection.ts";
 import type { AppContext, Registry } from "../engine/types/index.ts";
 import type { JobRunner, JobRunnerOptions } from "../jobs/job-runner.ts";
 import type { Lifecycle } from "../lifecycle/index.ts";
-import type { ObservabilityOptions, ObservabilityProvider } from "../observability/index.ts";
+import type { ObservabilityProvider } from "../observability/index.ts";
 import type { Dispatcher, DispatcherOptions } from "../pipeline/dispatcher.ts";
 import type { EventDedup, EventDispatcher } from "../pipeline/index.ts";
 import type { SystemHooks } from "../pipeline/lifecycle-pipeline.ts";
@@ -17,8 +17,6 @@ export type BaseEntrypointOptions = {
     readonly jwtSecret: string | JwtKeyring;
     readonly jwtIssuer?: string;
     readonly observability?: ObservabilityProvider;
-    /** @deprecated No effect: the HTTP route label carries no query string anymore, so there is nothing left to configure. */
-    readonly observabilityOptions?: ObservabilityOptions;
     readonly dispatcherOptions?: Omit<DispatcherOptions, "lifecycle">;
     readonly systemHooks?: SystemHooks;
     readonly eventDedup?: EventDedup;

package/dist/errors/reasons.d.ts

@@ -16,6 +16,7 @@ export declare const FrameworkReasons: {
     readonly instructionFieldWriteRequiresHighRisk: "instruction_field_write_requires_high_risk";
     readonly subjectErased: "subject_erased";
     readonly fileRejected: "file_rejected";
+    readonly fileViolatesBindTarget: "file_violates_bind_target";
 };
 export type FrameworkReason = (typeof FrameworkReasons)[keyof typeof FrameworkReasons];
 export declare const AgentReasons: {

package/dist/errors/reasons.js

@@ -4,7 +4,7 @@
 // framework-level reason (e.g. "is this a stale-state race? retry once").
 //
 // Features add their own local Reasons objects (see `samples/errors/` or
-// `packages/bundled-features/src/tenant/constants.ts` → TenantErrors). The
+// `packages/bundled-features/src/tenant/web/constants.ts` → TenantErrors). The
 // framework deliberately does NOT enforce uniqueness across features — two
 // features may use the same reason string if the semantics match. The
 // convention: snake_case, no spaces, no feature prefix for framework reasons.
@@ -71,6 +71,9 @@ export const FrameworkReasons = {
     // UnprocessableError: createFileRefFromBytes refused the file (size, type,
     // content or attach target). `details.error` carries the upload-route error string.
     fileRejected: "file_rejected",
+    // UnprocessableError: bindPendingFileRef({ bindTo }) found the pending upload outside the
+    // target field's accept/maxSize. `details.error` carries the validator's error string.
+    fileViolatesBindTarget: "file_violates_bind_target",
 };
 // Reason codes the AI-agent runtime surfaces via `details.reason`. Kept as a
 // sister catalog to FrameworkReasons instead of extending it — see the

package/dist/errors/serialize.d.ts

@@ -12,6 +12,7 @@ export type ErrorResponseBody = {
         readonly timestamp: string;
     };
 };
+export declare const exposesCauseDetails: () => boolean;
 export declare function serializeError(err: KumikoError, requestId?: string, errorDocs?: ErrorDocsConfig): ErrorResponseBody;
 export type ErrorLogEntry = {
     readonly name: string;

package/dist/errors/serialize.js

@@ -7,10 +7,14 @@ import { resolveErrorDocsUrl } from "./docs-url.js";
 // possible — without this, a crash in a handler comes back as a bare
 // "internal error" and developers have to add try/catch + UnprocessableError
 // just to see what went wrong (real footgun, not theoretical). The exposure
-// is gated on NODE_ENV !== "production" so a misconfigured prod deploy
-// doesn't leak stack traces over the wire.
+// is gated on NODE_ENV being explicitly "development" or "test": a missing or
+// misspelled NODE_ENV (a misconfigured prod deploy) must not leak stack traces,
+// paths or upstream URLs over the wire.
 const CODES_WITHOUT_CLIENT_DETAILS = new Set(["internal_error"]);
-const isProductionEnv = () => process.env["NODE_ENV"] === "production";
+export const exposesCauseDetails = () => {
+    const env = process.env["NODE_ENV"];
+    return env === "development" || env === "test";
+};
 function devCauseDetail(cause) {
     if (!(cause instanceof Error))
         return undefined;
@@ -21,7 +25,7 @@ function devCauseDetail(cause) {
     };
 }
 export function serializeError(err, requestId, errorDocs) {
-    const stripped = CODES_WITHOUT_CLIENT_DETAILS.has(err.code) && isProductionEnv();
+    const stripped = CODES_WITHOUT_CLIENT_DETAILS.has(err.code) && !exposesCauseDetails();
     const exposeDeclaredDetails = err.details !== undefined && !stripped;
     // For internal_error in dev/test, surface the cause chain so the
     // response body has something useful instead of "internal error".
@@ -30,7 +34,7 @@ export function serializeError(err, requestId, errorDocs) {
     const detailsForResponse = (() => {
         if (exposeDeclaredDetails)
             return err.details;
-        if (CODES_WITHOUT_CLIENT_DETAILS.has(err.code) && !isProductionEnv()) {
+        if (CODES_WITHOUT_CLIENT_DETAILS.has(err.code) && exposesCauseDetails()) {
             return devCauseDetail(err.cause);
         }
         return undefined;

package/dist/errors/write-error-info.js

@@ -1,6 +1,7 @@
 import { NotFoundError, UnprocessableError } from "./classes.js";
 import { KumikoError } from "./kumiko-error.js";
 import { FrameworkReasons } from "./reasons.js";
+import { exposesCauseDetails } from "./serialize.js";
 import { buildInvalidTransitionDetails } from "./transition-details.js";
 // Convenience for call sites that return a failed WriteResult. Keeps the
 // pattern `return writeFailure(new NotFoundError(...))` compact so handlers
@@ -49,9 +50,9 @@ export function toWriteErrorInfo(err) {
     // back to the client as a bare `{ message: "internal error" }` —
     // identical user-experience to a misconfigured prod, just slower
     // because the dev has to add try/catch + console.log to find the
-    // actual stack. Same gating as serializeError: NODE_ENV !== production.
+    // actual stack. Same gating as serializeError.
     const causeDetails = err.details === undefined && err.code === "internal_error" && err.cause instanceof Error
-        ? process.env["NODE_ENV"] !== "production"
+        ? exposesCauseDetails()
             ? {
                 causeName: err.cause.name,
                 causeMessage: err.cause.message,

package/dist/errors/zod-bridge.js

@@ -54,5 +54,12 @@ function extractIssueParams(issue) {
         if (bag[key] !== undefined)
             out[key] = bag[key];
     }
+    // A custom issue that overrides its i18n key also carries the values the text interpolates.
+    if (issue.code === "custom" && typeof issue.params?.["i18nKey"] === "string") {
+        for (const [key, value] of Object.entries(issue.params)) {
+            if (key !== "i18nKey" && value !== undefined)
+                out[key] = value;
+        }
+    }
     return Object.keys(out).length > 0 ? out : undefined;
 }

package/dist/event-store/index.d.ts

@@ -1,5 +1,6 @@
 export { APP_INSTANCE_STREAM_TYPE, APP_STARTED_EVENT_TYPE } from "../crypto/system-event-pii.ts";
 export { backfillEventPiiEncryption, backfillEventPiiEncryptionBatch, type PiiBackfillBatchOptions, type PiiBackfillBatchResult, type PiiBackfillFailure, type PiiBackfillOptions, type PiiBackfillResult, type PiiBackfillScanCache, } from "../db/queries/backfill-pii.ts";
+export { type DeleteRowsWithoutReplayableStreamArgs, deleteRowsWithoutReplayableStream, } from "../db/queries/event-store-orphan-rows.ts";
 export { type ArchiveStreamArgs, archivedStreamsTable, archiveStream, createArchivedStreamsTable, isStreamArchived, restoreStream, } from "./archive.ts";
 export { ArchivedStreamError, IdempotentAppendConflictError, SeedTimeOrderError, VersionConflictError, } from "./errors.ts";
 export { append, EVENTS_PUBSUB_CHANNEL, type EventMetadata, type EventToAppend, getEventsHighWaterMark, getStreamVersion, getStreamVersions, getUnscopedAggregateStreamMaxVersion, getUnscopedStreamMaxVersionForSeed, LOAD_ALL_EVENTS_ROW_LIMIT, loadAggregate, loadAggregateAsOf, loadAllEventsByType, loadEventsAfterVersion, type StoredEvent, streamAllEventsByType, } from "./event-store.ts";

package/dist/event-store/index.js

@@ -1,5 +1,6 @@
 export { APP_INSTANCE_STREAM_TYPE, APP_STARTED_EVENT_TYPE } from "../crypto/system-event-pii.js";
 export { backfillEventPiiEncryption, backfillEventPiiEncryptionBatch, } from "../db/queries/backfill-pii.js";
+export { deleteRowsWithoutReplayableStream, } from "../db/queries/event-store-orphan-rows.js";
 export { archivedStreamsTable, archiveStream, createArchivedStreamsTable, isStreamArchived, restoreStream, } from "./archive.js";
 export { ArchivedStreamError, IdempotentAppendConflictError, SeedTimeOrderError, VersionConflictError, } from "./errors.js";
 export { append, EVENTS_PUBSUB_CHANNEL, getEventsHighWaterMark, getStreamVersion, getStreamVersions, getUnscopedAggregateStreamMaxVersion, getUnscopedStreamMaxVersionForSeed, LOAD_ALL_EVENTS_ROW_LIMIT, loadAggregate, loadAggregateAsOf, loadAllEventsByType, loadEventsAfterVersion, streamAllEventsByType, } from "./event-store.js";

package/dist/files/action-form-upload.d.ts

@@ -0,0 +1,16 @@
+import { type AnyFileFieldDef, type Registry, type SessionUser } from "../engine/types/index.ts";
+export declare function isActionFormScreenQn(value: string): boolean;
+/** The files/images field `fieldName` of the registered actionForm screen `screenQn`, if any. */
+export declare function resolveActionFormFileField(registry: Pick<Registry, "getScreen"> | undefined, screenQn: string, fieldName: string): AnyFileFieldDef | undefined;
+export type ActionFormFileField = {
+    readonly screenQn: string;
+    readonly fieldName: string;
+    readonly fieldDef: AnyFileFieldDef;
+};
+export declare function listActionFormFileFields(registry: Pick<Registry, "getAllScreens"> | undefined): readonly ActionFormFileField[];
+/**
+ * Whether `user` may submit the actionForm `screenQn`: the screen's own access (when set) and
+ * the access of its handler must both pass, so an upload is never accepted for a form the
+ * caller could not submit.
+ */
+export declare function mayUseActionForm(registry: Pick<Registry, "getScreen" | "getWriteHandler">, screenQn: string, user: Pick<SessionUser, "roles">): boolean;

package/dist/files/action-form-upload.js

@@ -0,0 +1,45 @@
+import { hasAccess } from "../engine/access.js";
+import { isFileField, } from "../engine/types/index.js";
+// Same character set as the other upload identifiers: the screen QN is stored as the pending
+// upload's entityType and compared by exact match, never interpolated into a storage key.
+const ACTION_FORM_SCREEN_QN = /^[A-Za-z0-9_-]+:screen:[A-Za-z0-9_-]+$/;
+export function isActionFormScreenQn(value) {
+    return ACTION_FORM_SCREEN_QN.test(value);
+}
+function findActionFormScreen(registry, screenQn) {
+    if (!isActionFormScreenQn(screenQn))
+        return undefined;
+    const screen = registry.getScreen(screenQn);
+    return screen?.type === "actionForm" ? screen : undefined;
+}
+/** The files/images field `fieldName` of the registered actionForm screen `screenQn`, if any. */
+export function resolveActionFormFileField(registry, screenQn, fieldName) {
+    const screen = registry && findActionFormScreen(registry, screenQn);
+    const field = screen?.fields[fieldName];
+    return field !== undefined && isFileField(field) ? field : undefined;
+}
+export function listActionFormFileFields(registry) {
+    const found = [];
+    for (const [screenQn, screen] of registry?.getAllScreens() ?? []) {
+        if (screen.type !== "actionForm")
+            continue;
+        for (const [fieldName, fieldDef] of Object.entries(screen.fields)) {
+            if (isFileField(fieldDef))
+                found.push({ screenQn, fieldName, fieldDef });
+        }
+    }
+    return found;
+}
+/**
+ * Whether `user` may submit the actionForm `screenQn`: the screen's own access (when set) and
+ * the access of its handler must both pass, so an upload is never accepted for a form the
+ * caller could not submit.
+ */
+export function mayUseActionForm(registry, screenQn, user) {
+    const screen = findActionFormScreen(registry, screenQn);
+    if (screen === undefined)
+        return false;
+    if (screen.access !== undefined && !hasAccess(user, screen.access))
+        return false;
+    return hasAccess(user, registry.getWriteHandler(screen.handler)?.access);
+}

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

@@ -2,6 +2,7 @@ import type { TenantDb } from "../db/tenant-db.ts";
 import { type Registry, type SaveContext, type SessionUser } from "../engine/types/index.ts";
 import { type FileRefRows } from "./load-save-file-refs.ts";
 export declare function fileRefIdsOf(value: unknown): readonly string[];
+type FileRefRow = Readonly<Record<string, unknown>>;
 export declare function bindPendingFileRefs(args: {
     readonly registry: Registry;
     readonly result: SaveContext;
@@ -24,6 +25,11 @@ type PendingFileRefLookup = {
     readonly db: TenantDb;
 };
 export declare function loadPendingFileRef(lookup: PendingFileRefLookup): Promise<PendingFileRef | undefined>;
+export type PendingFileRefBindTarget = {
+    readonly entityName: string;
+    readonly fieldName: string;
+};
+export declare function assertRowFitsBindTarget(registry: Registry | undefined, bindTo: PendingFileRefBindTarget, row: FileRefRow): void;
 export type BindPendingFileRefOutcome = "bound" | "not-pending" | "version-conflict";
 /**
  * Binds one of the caller's own pending uploads to a record from a custom handler, with the
@@ -32,10 +38,18 @@ export type BindPendingFileRefOutcome = "bound" | "not-pending" | "version-confl
  * The helper checks the upload, not the target: the caller must already be authorized to write
  * `entityId` itself (for example a record the handler just wrote); `canWriteRecord` is not checked.
  *
+ * `bindTo` moves the upload onto an entity file field of its own: a form upload is pending under
+ * the actionForm screen (entityName = the screen QN), and the handler decides which entity field
+ * keeps it. The row is re-tagged to `bindTo` and must fit that field's `accept`/`maxSize`
+ * (UnprocessableError otherwise); the field must be registered, which needs `registry`
+ * (the handler's `ctx.registry`), else InternalError.
+ *
  * A parallel bind of the same fileRef loses with "version-conflict" (or "not-pending" once the
  * winner has committed); anything else throws.
  */
 export declare function bindPendingFileRef(args: PendingFileRefLookup & {
     readonly entityId: string;
+    readonly bindTo?: PendingFileRefBindTarget;
+    readonly registry?: Registry;
 }): Promise<BindPendingFileRefOutcome>;
 export {};

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

@@ -1,9 +1,10 @@
 import { isAnonymousSessionUser } from "../engine/system-user.js";
 import { isFileField, isUuid, } from "../engine/types/index.js";
-import { reraiseAsKumikoError } from "../errors/index.js";
-import { getFileRefExecutor } from "./create-file-ref.js";
+import { FrameworkReasons, InternalError, reraiseAsKumikoError, UnprocessableError, } from "../errors/index.js";
+import { getFileRefExecutor, resolveAttachedField } 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";
 export function fileRefIdsOf(value) {
     if (typeof value === "string")
         return isUuid(value) ? [value] : [];
@@ -21,10 +22,16 @@ function streamVersionOf(row) {
     return typeof row["version"] === "number" ? row["version"] : undefined;
 }
 async function bindPendingRow(args) {
-    const { row, fileRefId, entityName, fieldName, entityId, user, db } = args;
+    const { row, fileRefId, entityName, fieldName, entityId, bindTo, user, db } = args;
     if (!isPendingUploadFor(row, entityName, fieldName, user))
         return { kind: "not-pending" };
-    const bound = await getFileRefExecutor().update({ id: fileRefId, version: streamVersionOf(row), changes: { entityId } }, user, db);
+    const bound = await getFileRefExecutor().update({
+        id: fileRefId,
+        version: streamVersionOf(row),
+        changes: bindTo === undefined
+            ? { entityId }
+            : { entityId, entityType: bindTo.entityName, fieldName: bindTo.fieldName },
+    }, user, db);
     return bound.isSuccess ? { kind: "bound" } : { kind: "failed", error: bound.error };
 }
 // A form (or a server handler via createFileRefFromBytes) uploads before the
@@ -98,6 +105,31 @@ export async function loadPendingFileRef(lookup) {
     }
     return { id: lookup.fileRefId, storageKey, mimeType, size, version };
 }
+// The pending upload was checked against the form field it came in through; a different target
+// field may be stricter. Metadata only (bytes are not re-read): the extension comes from the
+// storage key, whose suffix is the sniffed type, because fileName may be encrypted personal data.
+export function assertRowFitsBindTarget(registry, bindTo, row) {
+    const target = resolveAttachedField(registry, bindTo.entityName, bindTo.fieldName);
+    if (target.kind !== "resolved") {
+        throw new InternalError({
+            message: `bindPendingFileRef: bindTo ${bindTo.entityName}.${bindTo.fieldName} is not a registered file field (pass the handler's ctx.registry)`,
+        });
+    }
+    const { storageKey, mimeType, size } = row;
+    if (typeof storageKey !== "string" || typeof mimeType !== "string" || typeof size !== "number") {
+        // A row without these can only come from corruption; letting it through would skip the check.
+        throw new InternalError({
+            message: `bindPendingFileRef: pending file_ref ${String(row["id"])} lacks storageKey, mimeType or size`,
+        });
+    }
+    const error = validateFile({ fileName: storageKey, mimeType, size }, { maxSize: target.fieldDef.maxSize, accept: target.fieldDef.accept });
+    if (error !== null) {
+        throw new UnprocessableError(FrameworkReasons.fileViolatesBindTarget, {
+            i18nKey: "errors.file.violatesBindTarget",
+            details: { error },
+        });
+    }
+}
 const CONCURRENT_BIND_ERROR_CODES = ["version_conflict", "unique_violation"];
 /**
  * Binds one of the caller's own pending uploads to a record from a custom handler, with the
@@ -106,6 +138,12 @@ const CONCURRENT_BIND_ERROR_CODES = ["version_conflict", "unique_violation"];
  * The helper checks the upload, not the target: the caller must already be authorized to write
  * `entityId` itself (for example a record the handler just wrote); `canWriteRecord` is not checked.
  *
+ * `bindTo` moves the upload onto an entity file field of its own: a form upload is pending under
+ * the actionForm screen (entityName = the screen QN), and the handler decides which entity field
+ * keeps it. The row is re-tagged to `bindTo` and must fit that field's `accept`/`maxSize`
+ * (UnprocessableError otherwise); the field must be registered, which needs `registry`
+ * (the handler's `ctx.registry`), else InternalError.
+ *
  * A parallel bind of the same fileRef loses with "version-conflict" (or "not-pending" once the
  * winner has committed); anything else throws.
  */
@@ -114,6 +152,8 @@ export async function bindPendingFileRef(args) {
     // Without a stream version the update would run unversioned and could overwrite a concurrent bind.
     if (row === undefined || streamVersionOf(row) === undefined)
         return "not-pending";
+    if (args.bindTo !== undefined)
+        assertRowFitsBindTarget(args.registry, args.bindTo, row);
     const outcome = await bindPendingRow({ ...args, row });
     switch (outcome.kind) {
         case "bound":

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

@@ -38,6 +38,9 @@ export type StoreFileInput = {
     readonly entityType?: string | undefined;
     readonly entityId?: string | undefined;
     readonly fieldName?: string | undefined;
+    /** Qualified name of a registered actionForm screen; `fieldName` then names one of its files
+     *  fields and the upload is stored as pending (entityType = the screen QN, no entityId). */
+    readonly actionForm?: string | undefined;
 };
 export type StoreFileDeps = {
     readonly user: SessionUser;