@cosmicdrift/kumiko-framework 0.378.0 → 0.380.0

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/es-ops/operations-schema.d.ts

@@ -1,5 +1,5 @@
 import { type DbConnection } from "../db/index.ts";
 export type EsOperationType = "seed-migration";
 export type EsOperationAppliedBy = "boot" | "cli" | "ci-pipeline";
-export declare const esOperationsTable: import("@cosmicdrift/kumiko-types/schema-table-types").SchemaTable;
+export declare const esOperationsTable: import("@cosmicdrift/kumiko-types/executor-brand").WritableSchemaTable;
 export declare function createEsOperationsTable(db: DbConnection): Promise<void>;

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

@@ -1,6 +1,6 @@
 import type { DbConnection, DbRunner } from "../db/connection.ts";
 import type { TenantId } from "../engine/types/index.ts";
-export declare const archivedStreamsTable: import("@cosmicdrift/kumiko-types/schema-table-types").SchemaTable;
+export declare const archivedStreamsTable: import("@cosmicdrift/kumiko-types/executor-brand").WritableSchemaTable;
 export declare function createArchivedStreamsTable(db: DbConnection): Promise<void>;
 export type ArchiveStreamArgs = {
     readonly tenantId: TenantId;

package/dist/event-store/events-schema.d.ts

@@ -1,3 +1,3 @@
 import { type DbConnection } from "../db/index.ts";
-export declare const eventsTable: import("@cosmicdrift/kumiko-types/schema-table-types").SchemaTable;
+export declare const eventsTable: import("@cosmicdrift/kumiko-types/executor-brand").WritableSchemaTable;
 export declare function createEventsTable(db: DbConnection): Promise<void>;

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/event-store/rebuild-dead-letter.d.ts

@@ -1,6 +1,6 @@
 import type { DbConnection, DbRunner } from "../db/connection.ts";
 import type { StoredEvent } from "./event-store.ts";
-export declare const rebuildDeadLetterTable: import("@cosmicdrift/kumiko-types/schema-table-types").SchemaTable;
+export declare const rebuildDeadLetterTable: import("@cosmicdrift/kumiko-types/executor-brand").WritableSchemaTable;
 export declare function createRebuildDeadLetterTable(db: DbConnection): Promise<void>;
 export type SkippedApply = {
     readonly event: StoredEvent;

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

@@ -2,7 +2,7 @@
 import type { LoadAggregateWithSnapshotOptions, LoadAggregateWithSnapshotResult, SnapshotReducer } from "@cosmicdrift/kumiko-types/snapshot-types";
 import type { DbConnection, DbRunner } from "../db/connection.ts";
 import type { TenantId } from "../engine/types/index.ts";
-export declare const snapshotsTable: import("@cosmicdrift/kumiko-types/schema-table-types").SchemaTable;
+export declare const snapshotsTable: import("@cosmicdrift/kumiko-types/executor-brand").WritableSchemaTable;
 export declare function createSnapshotsTable(db: DbConnection): Promise<void>;
 export declare function effectiveSnapshotGeneration(callerVersion: number, entityEventVersion: number | undefined): number;
 export type Snapshot<TState extends Record<string, unknown> = Record<string, unknown>> = {

package/dist/event-store/upcaster-dead-letter.d.ts

@@ -1,6 +1,6 @@
 import type { DbConnection, DbRunner } from "../db/connection.ts";
 import type { StoredEvent } from "./event-store.ts";
-export declare const upcasterDeadLetterTable: import("@cosmicdrift/kumiko-types/schema-table-types").SchemaTable;
+export declare const upcasterDeadLetterTable: import("@cosmicdrift/kumiko-types/executor-brand").WritableSchemaTable;
 export declare function createUpcasterDeadLetterTable(db: DbConnection): Promise<void>;
 export declare function recordUpcasterDeadLetter(db: DbRunner, args: {
     event: StoredEvent;

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;

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

@@ -3,6 +3,7 @@ import { runInOwnTransaction } from "../db/tenant-db.js";
 import { isFileField, } from "../engine/types/index.js";
 import { InternalError } from "../errors/index.js";
 import { generateId } from "../utils/index.js";
+import { isActionFormScreenQn, resolveActionFormFileField } from "./action-form-upload.js";
 import { FILE_REF_ENTITY_NAME, fileRefEntity } from "./file-ref-entity.js";
 import { fileRefsTable } from "./file-ref-table.js";
 import { resolveContentType } from "./resolve-content-type.js";
@@ -23,6 +24,7 @@ export function getFileRefExecutor() {
     fileRefExecutor ??= buildFileRefExecutor();
     return fileRefExecutor;
 }
+const ACTION_FORM_STORAGE_SEGMENT = "action-form";
 const SAFE_IDENTIFIER = /^[A-Za-z0-9_-]+$/;
 // entityType/fieldName drive the GDPR-forget decision downstream
 // (fileRefDeleteHook resolves the field's PII annotation from exactly this
@@ -39,6 +41,33 @@ export function resolveAttachedField(registry, entityType, fieldName) {
         return { kind: "unresolvable" };
     return { kind: "resolved", fieldDef };
 }
+function resolveUploadField(registry, input) {
+    const { entityType, entityId, fieldName, actionForm } = input;
+    if (actionForm === undefined)
+        return resolveAttachedField(registry, entityType, fieldName);
+    if (entityType !== undefined || entityId !== undefined) {
+        return {
+            kind: "rejected",
+            error: "invalid_action_form: actionForm cannot be combined with entityType/entityId",
+        };
+    }
+    if (!isActionFormScreenQn(actionForm)) {
+        return {
+            kind: "rejected",
+            error: "invalid_action_form: expected a screen QN like <feature>:screen:<id>",
+        };
+    }
+    const fieldDef = fieldName !== undefined
+        ? resolveActionFormFileField(registry, actionForm, fieldName)
+        : undefined;
+    if (fieldDef === undefined) {
+        return {
+            kind: "rejected",
+            error: "unresolvable_field: actionForm and fieldName must name a files/image field of a registered actionForm screen",
+        };
+    }
+    return { kind: "resolved", fieldDef };
+}
 function acceptFile(deps, input) {
     const { fileName, declaredMimeType, data, entityType, entityId, fieldName } = input;
     const rejected = (error) => ({ kind: "rejected", error });
@@ -54,18 +83,15 @@ function acceptFile(deps, input) {
             return rejected(`invalid_${field}: must match /^[A-Za-z0-9_-]+$/`);
         }
     }
-    let maxSize = deps.defaultMaxUploadSize;
-    let accept;
-    const attachedField = resolveAttachedField(deps.registry, entityType, fieldName);
-    if (attachedField.kind === "unresolvable") {
+    const field = resolveUploadField(deps.registry, input);
+    if (field.kind === "rejected")
+        return field;
+    if (field.kind === "unresolvable") {
         return rejected("unresolvable_field: entityType/fieldName must resolve to a registered file field, or both must be omitted for an unattached upload");
     }
-    if (attachedField.kind === "resolved") {
-        if (attachedField.fieldDef.maxSize)
-            maxSize = attachedField.fieldDef.maxSize;
-        if (attachedField.fieldDef.accept)
-            accept = attachedField.fieldDef.accept;
-    }
+    const fieldDef = field.kind === "resolved" ? field.fieldDef : undefined;
+    const maxSize = fieldDef?.maxSize || deps.defaultMaxUploadSize;
+    const accept = fieldDef?.accept;
     const validationError = validateFile({ fileName, mimeType: declaredMimeType, size: data.byteLength }, { maxSize, accept });
     if (validationError)
         return rejected(validationError);
@@ -98,12 +124,14 @@ function acceptFile(deps, input) {
 // Upload step: validates and writes the binary. Outside any transaction on purpose — network/disk
 // I/O doesn't belong inside a PG connection's tx window.
 export async function writeAcceptedFileBytes(deps, input) {
-    const { fileName, data, entityType, entityId, fieldName } = input;
+    const { fileName, data, entityType, entityId, fieldName, actionForm } = input;
     const accepted = acceptFile(deps, input);
     if (accepted.kind === "rejected")
         return accepted;
     const { mimeType, extension } = accepted;
-    const storageKey = buildStorageKey(deps.user.tenantId, entityType ?? "unattached", entityId, fieldName ?? "file", fileName, generateId(), extension);
+    const storageKey = buildStorageKey(deps.user.tenantId, 
+    // The screen QN stays out of the key: a fixed segment keeps it a plain path part.
+    actionForm !== undefined ? ACTION_FORM_STORAGE_SEGMENT : (entityType ?? "unattached"), entityId, fieldName ?? "file", fileName, generateId(), extension);
     await deps.writeBytes(storageKey, data, mimeType);
     return {
         kind: "uploaded",
@@ -112,7 +140,7 @@ export async function writeAcceptedFileBytes(deps, input) {
             fileName,
             mimeType,
             size: data.byteLength,
-            entityType,
+            entityType: actionForm ?? entityType,
             entityId,
             fieldName,
         },

package/dist/files/file-routes.js

@@ -6,8 +6,9 @@ import { collectPiiSubjectFields, configuredPiiSubjectKms, decryptPiiFieldValues
 import { selectMany } from "../db/query.js";
 import { createProjectingTenantDb } from "../db/tenant-db.js";
 import { createDerivativesContext, resolveFieldVariant, resolveRenderer, } from "../derivatives/index.js";
-import { SYSTEM_USER_ID } from "../engine/system-user.js";
+import { isAnonymousSessionUser, SYSTEM_USER_ID } from "../engine/system-user.js";
 import { isFileField, isUuid, } from "../engine/types/index.js";
+import { listActionFormFileFields, mayUseActionForm } from "./action-form-upload.js";
 import { buildContentDispositionHeader } from "./content-disposition.js";
 import { DEFAULT_MAX_UPLOAD_SIZE, getFileRefExecutor, storeFileAsFileRef, } from "./create-file-ref.js";
 import { createFileContext } from "./file-handle.js";
@@ -70,6 +71,10 @@ export function resolveMaxUploadBodyBytes(options) {
             }
         }
     }
+    for (const { fieldDef } of listActionFormFileFields(options.registry)) {
+        if (fieldDef.maxSize)
+            maxBytes = Math.max(maxBytes, parseMaxSize(fieldDef.maxSize));
+    }
     return maxBytes + MULTIPART_OVERHEAD_MARGIN_BYTES;
 }
 // Upload-route policy carried by createFilesFeature(opts?) — read from the
@@ -148,6 +153,20 @@ export function createFileRoutes(options) {
         // store it in the text entityId column.
         const entityId = typeof body["entityId"] === "string" ? body["entityId"] : undefined;
         const fieldName = typeof body["fieldName"] === "string" ? body["fieldName"] : undefined;
+        const actionForm = typeof body["actionForm"] === "string" ? body["actionForm"] : undefined;
+        // Ahead of the record check below, which would answer 404/403 for the entity half.
+        if (actionForm !== undefined && (entityType !== undefined || entityId !== undefined)) {
+            return c.json({ error: "invalid_action_form: actionForm cannot be combined with entityType or entityId" }, 400);
+        }
+        // Before any bytes are written, like the record check below. An unresolvable screen falls
+        // through to storeFileAsFileRef, which answers 400; a known one must be submittable by the
+        // caller. Anonymous callers cannot bind pending uploads, so they get no upload either.
+        if (actionForm !== undefined &&
+            options.registry !== undefined &&
+            options.registry.getScreen(actionForm)?.type === "actionForm" &&
+            (isAnonymousSessionUser(user) || !mayUseActionForm(options.registry, actionForm, user))) {
+            return c.json({ error: "forbidden: no access to this form" }, 403);
+        }
         if (entityId !== undefined) {
             if (entityType === undefined) {
                 return c.json({ error: "missing_entity_type: entityId requires entityType" }, 400);
@@ -184,7 +203,15 @@ export function createFileRoutes(options) {
                 await storageProvider.write(key, bytes, mimeType);
             },
             deleteBytes: (key) => storageProvider.delete(key),
-        }, { fileName: file.name, declaredMimeType: file.type, data, entityType, entityId, fieldName });
+        }, {
+            fileName: file.name,
+            declaredMimeType: file.type,
+            data,
+            entityType,
+            entityId,
+            fieldName,
+            actionForm,
+        });
         if (outcome.kind === "rejected")
             return c.json({ error: outcome.error }, 400);
         if (outcome.kind === "failed")

package/dist/files/index.d.ts

@@ -1,4 +1,5 @@
-export type { BindPendingFileRefOutcome, PendingFileRef } from "./bind-pending-file-refs.ts";
+export { listActionFormFileFields, resolveActionFormFileField } from "./action-form-upload.ts";
+export type { BindPendingFileRefOutcome, PendingFileRef, PendingFileRefBindTarget, } from "./bind-pending-file-refs.ts";
 export { bindPendingFileRef, loadPendingFileRef } from "./bind-pending-file-refs.ts";
 export type { CreatedFileRef, CreateFileRefContext, CreateFileRefInput, UploadedFileBytes, UploadFileBytesContext, } from "./create-file-ref-from-bytes.ts";
 export { createFileRefFromBytes, createFileRefFromUploadedBytes, uploadFileBytesBeforeTransaction, } from "./create-file-ref-from-bytes.ts";

package/dist/files/index.js

@@ -1,3 +1,4 @@
+export { listActionFormFileFields, resolveActionFormFileField } from "./action-form-upload.js";
 export { bindPendingFileRef, loadPendingFileRef } from "./bind-pending-file-refs.js";
 export { createFileRefFromBytes, createFileRefFromUploadedBytes, uploadFileBytesBeforeTransaction, } from "./create-file-ref-from-bytes.js";
 export { createFilesFeature, FILES_FEATURE } from "./feature.js";

package/dist/files/purge-expired-file-ref-bytes.d.ts

@@ -1,10 +1,10 @@
 import type { FileContext } from "@cosmicdrift/kumiko-types/file-handle-types";
 import type { Logger } from "@cosmicdrift/kumiko-types/logger";
-import { deleteMany, type WhereObject } from "../db/query.ts";
+import { selectMany, type WhereObject } from "../db/query.ts";
 import type { TenantDb } from "../db/tenant-db.ts";
 export declare const EXPIRED_FILE_REF_PURGE_BATCH = 500;
 type PurgeLog = Pick<Logger, "warn"> | undefined;
-type PurgeTable = Parameters<typeof deleteMany>[1];
+type PurgeTable = Parameters<typeof selectMany>[1];
 export declare function purgeExpiredFileRefsWithBytes(args: {
     readonly db: TenantDb;
     readonly table: PurgeTable;
@@ -12,6 +12,7 @@ export declare function purgeExpiredFileRefsWithBytes(args: {
     readonly expiredBefore: Temporal.Instant;
     readonly files: FileContext | undefined;
     readonly log: PurgeLog;
+    readonly forgetRow: (id: string) => Promise<void>;
     readonly pageSize?: number;
 }): Promise<void>;
 export {};

package/dist/files/purge-expired-file-ref-bytes.js

@@ -1,4 +1,4 @@
-import { deleteMany, selectMany } from "../db/query.js";
+import { selectMany } from "../db/query.js";
 import { deleteFileRefBytes } from "../derivatives/delete-stored-file.js";
 export const EXPIRED_FILE_REF_PURGE_BATCH = 500;
 const PAGE_ORDER = [
@@ -20,12 +20,12 @@ async function selectNextPage(args) {
     return [...sameInstant, ...later];
 }
 // Deletes the bytes (original + derivatives) of expired soft-deleted fileRef rows, then the
-// rows. Bytes first and fail-closed: once the row is gone nobody knows the storageKey, so a
+// rows (forgotten through the executor, so a rebuild keeps them gone). Bytes first and fail-closed: once the row is gone nobody knows the storageKey, so a
 // row whose bytes could not be removed stays and the next run retries it. A run walks the
 // expired rows page by page along (deletedAt, id), so rows that keep failing cannot hide the
 // rows behind them; the run ends on the first empty page.
 export async function purgeExpiredFileRefsWithBytes(args) {
-    const { db, table, where, expiredBefore, files, log } = args;
+    const { db, table, where, expiredBefore, files, log, forgetRow } = args;
     const pageSize = args.pageSize ?? EXPIRED_FILE_REF_PURGE_BATCH;
     if (!files) {
         log?.warn("[soft-delete-cleanup] no file storage available, expired fileRef rows kept");
@@ -53,7 +53,13 @@ export async function purgeExpiredFileRefsWithBytes(args) {
                 log?.warn(`[soft-delete-cleanup] bytes of fileRef ${row.id} not deleted, row kept: ${err instanceof Error ? err.message : String(err)}`);
             }
         }
-        if (purgedIds.length > 0)
-            await deleteMany(db, table, { ...where, id: { in: purgedIds } });
+        for (const id of purgedIds) {
+            try {
+                await forgetRow(id);
+            }
+            catch (err) {
+                log?.warn(`[soft-delete-cleanup] fileRef ${id} bytes deleted but row not forgotten: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
     }
 }