@cosmicdrift/kumiko-framework 0.388.0 → 0.390.0

package/dist/event-store/event-store.js

@@ -12,6 +12,7 @@ import { IdempotentAppendConflictError, SeedTimeOrderError, VersionConflictError
 import { eventsTable } from "./events-schema.js";
 import { toStoredEvent } from "./row-to-stored-event.js";
 import { currentSeedCreatedAt } from "./seed-clock.js";
+import { inEventStreamScope } from "./stream-scope.js";
 // Append one event atomically. Two guarantees combined:
 //
 //   1. UNIQUE (tenant_id, aggregate_id, version) serializes concurrent writers
@@ -51,7 +52,7 @@ export async function append(db, event) {
     const newVersion = toStore.expectedVersion + 1;
     const eventVersion = toStore.eventVersion ?? 1;
     try {
-        const row = await runAtomicEventWrite(db, async (runner) => {
+        const row = await inEventStreamScope(toStore.tenantId, () => runAtomicEventWrite(db, async (runner) => {
             await claimXactId(runner);
             // Inside the write transaction so a concurrent live append cannot slip
             // between the check and the insert.
@@ -65,7 +66,7 @@ export async function append(db, event) {
             // commit, so the dispatcher cannot wake before the row is visible.
             await notifyPgChannel(runner, EVENTS_PUBSUB_CHANNEL);
             return inserted;
-        });
+        }));
         return buildStoredEvent(toStore, newVersion, eventVersion, row);
     }
     catch (e) {
@@ -208,15 +209,20 @@ export async function loadAggregate(db, aggregateId, tenantId, options) {
     if (options?.aggregateType === "") {
         throw new Error("loadAggregate: aggregateType must be a non-empty string when provided");
     }
-    if (!options?.includeArchived) {
-        const archived = await isStreamArchived(db, tenantId, aggregateId);
-        if (archived)
-            return [];
-    }
-    const rows = await selectMany(db, eventsTable, options?.aggregateType !== undefined
-        ? { aggregateId, tenantId, aggregateType: options.aggregateType }
-        : { aggregateId, tenantId }, { orderBy: { col: "version", direction: "asc" } });
-    return rows.map(toStoredEvent);
+    return inEventStreamScope(tenantId, async () => {
+        if (!options?.includeArchived) {
+            const archived = await isStreamArchived(db, tenantId, aggregateId);
+            if (archived)
+                return [];
+        }
+        const rows = await selectMany(db, eventsTable, {
+            aggregateId,
+            tenantId,
+            ...(options?.aggregateType !== undefined && { aggregateType: options.aggregateType }),
+            ...(options?.atVersion !== undefined && { version: options.atVersion }),
+        }, { orderBy: { col: "version", direction: "asc" } });
+        return rows.map(toStoredEvent);
+    });
 }
 // Events and the stream's latest version from ONE read, so both come from the same
 // snapshot: a commit landing between two separate statements would leave the caller
@@ -227,40 +233,44 @@ export async function loadAggregateForWriting(db, aggregateId, tenantId, options
     if (options.aggregateType === "") {
         throw new Error("loadAggregateForWriting: aggregateType must be a non-empty string");
     }
-    if (await isStreamArchived(db, tenantId, aggregateId)) {
-        return { events: [], streamVersion: await getStreamVersion(db, aggregateId, tenantId) };
-    }
-    const rows = await selectMany(db, eventsTable, { aggregateId, tenantId }, { orderBy: { col: "version", direction: "asc" } });
-    const all = rows.map(toStoredEvent);
-    return {
-        events: all.filter((e) => e.aggregateType === options.aggregateType),
-        streamVersion: all.at(-1)?.version ?? 0,
-    };
+    return inEventStreamScope(tenantId, async () => {
+        if (await isStreamArchived(db, tenantId, aggregateId)) {
+            return { events: [], streamVersion: await getStreamVersion(db, aggregateId, tenantId) };
+        }
+        const rows = await selectMany(db, eventsTable, { aggregateId, tenantId }, { orderBy: { col: "version", direction: "asc" } });
+        const all = rows.map(toStoredEvent);
+        return {
+            events: all.filter((e) => e.aggregateType === options.aggregateType),
+            streamVersion: all.at(-1)?.version ?? 0,
+        };
+    });
 }
 // Load events up to a point in time. Used for asOf queries that reconstruct
 // historical state. Includes events whose created_at is <= asOf. Same
 // archive semantics as loadAggregate.
 export async function loadAggregateAsOf(db, aggregateId, tenantId, asOf, options) {
-    if (!options?.includeArchived) {
-        const archived = await isStreamArchived(db, tenantId, aggregateId);
-        if (archived)
-            return [];
-    }
-    const rows = await selectMany(db, eventsTable, { aggregateId, tenantId, createdAt: { lte: asOf } }, { orderBy: { col: "version", direction: "asc" } });
-    return rows.map(toStoredEvent);
+    return inEventStreamScope(tenantId, async () => {
+        if (!options?.includeArchived) {
+            const archived = await isStreamArchived(db, tenantId, aggregateId);
+            if (archived)
+                return [];
+        }
+        const rows = await selectMany(db, eventsTable, { aggregateId, tenantId, createdAt: { lte: asOf } }, { orderBy: { col: "version", direction: "asc" } });
+        return rows.map(toStoredEvent);
+    });
 }
 // Cheapest possible read of "what's the latest version on this stream?". The
 // CRUD executor uses this as expectedVersion for its append, so a domain
-// event appended via ctx.appendEvent between two CRUD writes doesn't cause
+// event appended via ctx.events.append between two CRUD writes doesn't cause
 // the next CRUD write to fail with version_conflict. Indexed lookup on the
 // existing (aggregate_id, version) unique index. Returns 0 for empty/unknown
 // streams (matches create()'s expectedVersion=0 convention).
 // @wrapper-known semantic-alias
 export async function getStreamVersion(db, aggregateId, tenantId) {
-    return selectStreamMaxVersion(db, aggregateId, tenantId);
+    return inEventStreamScope(tenantId, () => selectStreamMaxVersion(db, aggregateId, tenantId));
 }
 export async function getStreamVersions(db, aggregateIds, tenantId) {
-    return selectStreamMaxVersions(db, aggregateIds, tenantId);
+    return inEventStreamScope(tenantId, () => selectStreamMaxVersions(db, aggregateIds, tenantId));
 }
 /** MAX(version) for one aggregate — no tenant filter. SECURITY: existence-oracle,
  *  a caller can probe whether an aggregateId has any events regardless of tenant
@@ -307,11 +317,11 @@ export async function loadEventsAfterVersion(db, aggregateId, tenantId, afterVer
 // The caller may pause / do async work between yields; the next batch is
 // only fetched when consumed.
 //
-// Cancellation: pass `signal` (typically `ctx.signal` from a handler) to
+// Cancellation: pass `signal` (typically `ctx.lifecycle.signal` from a handler) to
 // abort iteration. Checked both at batch boundaries (before the next
 // fetch) AND between yields (so abort lands within one event regardless
 // of batch size). Throws AbortError on the first check after abort;
-// in-flight queries are not actively cancelled (postgres-js connection-
+// in-flight queries are not actively cancelled (connection
 // cancel is a separate, riskier concern handled per-query at the TenantDb
 // boundary).
 export async function* streamAllEventsByType(db, aggregateType, batchSize = 1000, signal) {

package/dist/event-store/events-schema.js

@@ -2,7 +2,7 @@
 import { bigserial, index, instant, integer, jsonb, table as pgTable, sql, text, uniqueIndex, uuid, } from "../db/dialect.js";
 import { tableExists } from "../db/index.js";
 import { ensureIdempotencyKeyIndex, ensureMembershipPayloadTenantIndex, } from "../db/queries/event-store.js";
-import { unsafePushTables } from "../db/table-push.js";
+import { ensureTableRowLevelSecurity, unsafePushTables } from "../db/table-push.js";
 import { createArchivedStreamsTable } from "./archive.js";
 import { createSnapshotsTable } from "./snapshot.js";
 // Event-store schema as a Drizzle table. The typed select/insert path handles
@@ -57,6 +57,9 @@ export async function createEventsTable(db) {
     if (!(await tableExists(db, "public.kumiko_events"))) {
         await unsafePushTables(db, { kumikoEvents: eventsTable });
     }
+    else {
+        await ensureTableRowLevelSecurity(db, eventsTable);
+    }
     // Runs unconditionally (both fresh + already-existing table) so installs
     // that predate the idempotency-key index get healed the same way
     // ensureSnapshotVersionColumn heals kumiko_snapshots.

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

@@ -1,16 +1,14 @@
 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, loadAggregate, loadAggregateAsOf, loadEventsAfterVersion, type StoredEvent, streamAllEventsByType, } from "./event-store.ts";
+export { backfillEventPiiEncryption, backfillEventPiiEncryptionBatch, } from "../db/queries/backfill-pii.ts";
+export { deleteRowsWithoutReplayableStream } from "../db/queries/event-store-orphan-rows.ts";
+export { archivedStreamsTable, archiveStream, createArchivedStreamsTable, isStreamArchived, } from "./archive.ts";
+export { SeedTimeOrderError, VersionConflictError, } from "./errors.ts";
+export { append, type EventMetadata, getEventsHighWaterMark, getStreamVersion, getStreamVersions, getUnscopedAggregateStreamMaxVersion, getUnscopedStreamMaxVersionForSeed, loadAggregate, type StoredEvent, streamAllEventsByType, } from "./event-store.ts";
 export { createEventsTable, eventsTable } from "./events-schema.ts";
-export { appendProvenanceEvent, type ProvenanceEventInput } from "./provenance-append.ts";
-export { createRebuildDeadLetterTable, listRebuildDeadLetters, type RebuildDeadLetterRow, rebuildDeadLetterTable, recordRebuildDeadLetters, type SkippedApply, } from "./rebuild-dead-letter.ts";
-export { toStoredEvent } from "./row-to-stored-event.ts";
+export { appendProvenanceEvent } from "./provenance-append.ts";
 export { assertSeedModeNotInProduction, isSeedModeEnabled, runSeedWritesAt, SEED_MODE_ENV, SeedModeDisabledError, } from "./seed-clock.ts";
-export { createSnapshotsTable, type LoadAggregateWithSnapshotOptions, type LoadAggregateWithSnapshotResult, loadAggregateWithSnapshot, loadLatestSnapshot, type SaveSnapshotArgs, type Snapshot, type SnapshotReducer, saveSnapshot, snapshotsTable, } from "./snapshot.ts";
-export { type AppendEventInTenantDbOptions, appendEventInTenantDb, getStreamVersionInTenantDb, } from "./tenant-db-append.ts";
-export { AGGREGATE_TRANSFER_STREAM_TYPE, AGGREGATE_TRANSFERRED_EVENT_TYPE, type TransferAggregateStreamsArgs, transferAggregateStreams, } from "./transfer.ts";
-export { type EventUpcasters, makeUpcastCtx, type UpcasterErrorPolicy, type UpcastOptions, upcastStoredEvent, upcastStoredEvents, } from "./upcaster.ts";
-export { createUpcasterDeadLetterTable, type DeadLetterRow, listDeadLetters, recordUpcasterDeadLetter, upcasterDeadLetterTable, } from "./upcaster-dead-letter.ts";
+export { snapshotsTable } from "./snapshot.ts";
+export { appendEventInTenantDb, getStreamVersionInTenantDb, } from "./tenant-db-append.ts";
+export { AGGREGATE_TRANSFER_STREAM_TYPE, AGGREGATE_TRANSFERRED_EVENT_TYPE, transferAggregateStreams, } from "./transfer.ts";
+export { makeUpcastCtx, upcastStoredEvent, } from "./upcaster.ts";
+export { upcasterDeadLetterTable } from "./upcaster-dead-letter.ts";

package/dist/event-store/index.js

@@ -1,16 +1,14 @@
 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, loadAggregate, loadAggregateAsOf, loadEventsAfterVersion, streamAllEventsByType, } from "./event-store.js";
+export { deleteRowsWithoutReplayableStream } from "../db/queries/event-store-orphan-rows.js";
+export { archivedStreamsTable, archiveStream, createArchivedStreamsTable, isStreamArchived, } from "./archive.js";
+export { SeedTimeOrderError, VersionConflictError, } from "./errors.js";
+export { append, getEventsHighWaterMark, getStreamVersion, getStreamVersions, getUnscopedAggregateStreamMaxVersion, getUnscopedStreamMaxVersionForSeed, loadAggregate, streamAllEventsByType, } from "./event-store.js";
 export { createEventsTable, eventsTable } from "./events-schema.js";
 export { appendProvenanceEvent } from "./provenance-append.js";
-export { createRebuildDeadLetterTable, listRebuildDeadLetters, rebuildDeadLetterTable, recordRebuildDeadLetters, } from "./rebuild-dead-letter.js";
-export { toStoredEvent } from "./row-to-stored-event.js";
 export { assertSeedModeNotInProduction, isSeedModeEnabled, runSeedWritesAt, SEED_MODE_ENV, SeedModeDisabledError, } from "./seed-clock.js";
-export { createSnapshotsTable, loadAggregateWithSnapshot, loadLatestSnapshot, saveSnapshot, snapshotsTable, } from "./snapshot.js";
+export { snapshotsTable } from "./snapshot.js";
 export { appendEventInTenantDb, getStreamVersionInTenantDb, } from "./tenant-db-append.js";
 export { AGGREGATE_TRANSFER_STREAM_TYPE, AGGREGATE_TRANSFERRED_EVENT_TYPE, transferAggregateStreams, } from "./transfer.js";
-export { makeUpcastCtx, upcastStoredEvent, upcastStoredEvents, } from "./upcaster.js";
-export { createUpcasterDeadLetterTable, listDeadLetters, recordUpcasterDeadLetter, upcasterDeadLetterTable, } from "./upcaster-dead-letter.js";
+export { makeUpcastCtx, upcastStoredEvent, } from "./upcaster.js";
+export { upcasterDeadLetterTable } from "./upcaster-dead-letter.js";

package/dist/event-store/provenance-append.js

@@ -32,7 +32,7 @@ export async function appendProvenanceEvent(db, event) {
             message: `appendProvenanceEvent: event tenant "${event.tenantId}" does not match the TenantDb's tenant "${db.tenantId}".`,
         });
     }
-    // postgres-js aborts the whole surrounding begin() on a statement
+    // Postgres aborts the whole surrounding transaction on a statement
     // error (25P02) even when the caller's catch swallows it — the savepoint
     // confines that to this scope. Pool connections have no ambient tx to poison.
     await runInSavepointIfSupported(runner, async (sp) => {

package/dist/event-store/rebuild-dead-letter.js

@@ -14,7 +14,7 @@
 // is a separate ops step — same stance as the upcaster dead-letter.
 import { bigint, index, jsonb, table as pgTable, text, timestamp, uuid } from "../db/dialect.js";
 import { tableExists } from "../db/schema-inspection.js";
-import { unsafePushTables } from "../db/table-push.js";
+import { ensureTableRowLevelSecurity, unsafePushTables } from "../db/table-push.js";
 export const rebuildDeadLetterTable = pgTable("kumiko_rebuild_dead_letters", {
     // Surrogate PK — the same event can land here across multiple rebuild
     // attempts before the fix ships, without unique-violation noise.
@@ -39,8 +39,10 @@ export const rebuildDeadLetterTable = pgTable("kumiko_rebuild_dead_letters", {
 // provisioned before this table existed.
 export async function createRebuildDeadLetterTable(db) {
     // skip: table already exists — bootstrap called from multiple paths
-    if (await tableExists(db, "public.kumiko_rebuild_dead_letters"))
+    if (await tableExists(db, "public.kumiko_rebuild_dead_letters")) {
+        await ensureTableRowLevelSecurity(db, rebuildDeadLetterTable);
         return;
+    }
     await unsafePushTables(db, { kumikoRebuildDeadLetters: rebuildDeadLetterTable });
 }
 // Bulk-write, called ONCE at the end of a quarantining rebuild (inside its

package/dist/event-store/snapshot.js

@@ -4,7 +4,7 @@ import { index, instant, integer, jsonb, table as pgTable, primaryKey, sql, text
 import { ensureSnapshotVersionColumn, upsertSnapshot } from "../db/queries/event-store.js";
 import { selectMany } from "../db/query.js";
 import { tableExists } from "../db/schema-inspection.js";
-import { unsafePushTables } from "../db/table-push.js";
+import { ensureTableRowLevelSecurity, unsafePushTables } from "../db/table-push.js";
 import { createFallbackLogger, scrubLogText } from "../logging/index.js";
 import { isStreamArchived } from "./archive.js";
 import { loadEventsAfterVersion } from "./event-store.js";
@@ -18,7 +18,7 @@ import { loadEventsAfterVersion } from "./event-store.js";
 //   3. loadEventsAfterVersion(aggregate, N) → only the delta
 //   4. reducer(snapshot, delta) → current state
 //
-// Write path: manual via ctx.snapshotAggregate, or automatic via the
+// Write path: manual via ctx.events.snapshot, or automatic via the
 // { snapshotEvery: N } load option — the read path persists a fresh
 // snapshot whenever it folded at least N delta events.
 //
@@ -32,7 +32,7 @@ import { loadEventsAfterVersion } from "./event-store.js";
 //
 // Upcaster interaction: the raw API (loadAggregateWithSnapshot below) does
 // NOT apply the upcaster chain on delta events — same layering as raw
-// loadAggregate. The Dispatcher wraps this into ctx.loadAggregateWithSnapshot
+// loadAggregate. The Dispatcher wraps this into ctx.events.loadWithSnapshot
 // and runs upcastStoredEvents on the delta before calling the reducer, so
 // feature authors always see current-version payloads.
 export const snapshotsTable = pgTable("kumiko_snapshots", {
@@ -64,6 +64,7 @@ export async function createSnapshotsTable(db) {
         // Installs that predate snapshot_version get healed by the same
         // idempotent ensure that `kumiko schema apply` / test-setup already runs.
         await ensureSnapshotVersionColumn(db);
+        await ensureTableRowLevelSecurity(db, snapshotsTable);
         // skip: table already ensured — only the column heal above was needed
         return;
     }

package/dist/event-store/stream-scope.d.ts

@@ -0,0 +1,2 @@
+import type { TenantId } from "../engine/types/index.ts";
+export declare function inEventStreamScope<T>(streamTenantId: TenantId, work: () => Promise<T>): Promise<T>;

package/dist/event-store/stream-scope.js

@@ -0,0 +1,6 @@
+import { runInRowLevelSecurityScope, tenantRowLevelSecurityScope, } from "../db/row-level-security-scope.js";
+// A stream belongs to exactly one tenant; its rows are only writable and reliably readable in
+// that tenant's scope, which differs from the caller's for systemStream entities and ctx.tenants.writeTarget.
+export function inEventStreamScope(streamTenantId, work) {
+    return runInRowLevelSecurityScope(tenantRowLevelSecurityScope(streamTenantId), work);
+}

package/dist/event-store/upcaster-dead-letter.js

@@ -13,7 +13,7 @@
 // separate CLI step — not implemented here, tracked as follow-up.
 import { bigint, index, integer, jsonb, table as pgTable, text, timestamp, uuid, } from "../db/dialect.js";
 import { tableExists } from "../db/schema-inspection.js";
-import { unsafePushTables } from "../db/table-push.js";
+import { ensureTableRowLevelSecurity, unsafePushTables } from "../db/table-push.js";
 export const upcasterDeadLetterTable = pgTable("kumiko_upcaster_dead_letters", {
     // Surrogate PK. We don't reuse eventId so a single event can land
     // here multiple times (retry attempts across deploys before the fix
@@ -40,8 +40,10 @@ export const upcasterDeadLetterTable = pgTable("kumiko_upcaster_dead_letters", {
 // exercise the quarantine path; production boot uses drizzle-kit push.
 export async function createUpcasterDeadLetterTable(db) {
     // skip: table already exists — bootstrap called from multiple paths
-    if (await tableExists(db, "public.kumiko_upcaster_dead_letters"))
+    if (await tableExists(db, "public.kumiko_upcaster_dead_letters")) {
+        await ensureTableRowLevelSecurity(db, upcasterDeadLetterTable);
         return;
+    }
     await unsafePushTables(db, { kumikoUpcasterDeadLetters: upcasterDeadLetterTable });
 }
 // Writes a dead-letter row. Called by upcastStoredEvent when errorPolicy

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

@@ -1,5 +1,6 @@
+import type { EventUpcastCtx, EventUpcastFn } from "@cosmicdrift/kumiko-types/handlers";
 import type { DbRunner } from "../db/index.ts";
-import type { EventUpcastCtx, EventUpcastFn, TenantId } from "../engine/types/index.ts";
+import type { TenantId } from "../engine/types/index.ts";
 import type { StoredEvent } from "./event-store.ts";
 export type UpcasterErrorPolicy = "throw" | "quarantine";
 export type UpcastOptions = {

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

@@ -1,4 +1,5 @@
-import { type AnyFileFieldDef, type Registry, type SessionUser } from "../engine/types/index.ts";
+import type { AnyFileFieldDef } from "@cosmicdrift/kumiko-types/fields";
+import type { Registry, 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;

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

@@ -1,5 +1,5 @@
 import { hasAccess } from "../engine/access.js";
-import { isFileField, } from "../engine/types/index.js";
+import { isFileField } from "../engine/field-helpers.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_-]+$/;

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

@@ -1,4 +1,5 @@
-import { type Registry, type SaveContext } from "../engine/types/index.ts";
+import type { SaveContext } from "@cosmicdrift/kumiko-types/hooks";
+import type { Registry } from "../engine/types/index.ts";
 import type { FileRefRows } from "./load-save-file-refs.ts";
 export declare function assertFileRefsBelongToTenant(args: {
     readonly registry: Registry;

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

@@ -1,4 +1,4 @@
-import { isFileField } from "../engine/types/index.js";
+import { isFileField } from "../engine/field-helpers.js";
 import { ValidationError } from "../errors/index.js";
 import { fileRefIdsOf } from "./bind-pending-file-refs.js";
 import { FILE_REF_ENTITY_NAME } from "./file-ref-entity.js";

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

@@ -1,5 +1,6 @@
+import type { SaveContext } from "@cosmicdrift/kumiko-types/hooks";
 import type { TenantDb } from "../db/tenant-db.ts";
-import { type Registry, type SaveContext, type SessionUser } from "../engine/types/index.ts";
+import type { Registry, 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>>;

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

@@ -1,5 +1,6 @@
+import { isUuid } from "@cosmicdrift/kumiko-types/identifiers";
+import { isFileField } from "../engine/field-helpers.js";
 import { isAnonymousSessionUser } from "../engine/system-user.js";
-import { isFileField, isUuid, } from "../engine/types/index.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";

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

@@ -1,6 +1,6 @@
 import * as z from "zod";
+import { isFileField } from "../engine/field-helpers.js";
 import { defineWriteHandler, SYSTEM_ROLE, SYSTEM_USER_ID } from "../engine/index.js";
-import { isFileField } from "../engine/types/index.js";
 import { ValidationError } from "../errors/index.js";
 import { fileRefIdsOf } from "./bind-pending-file-refs.js";
 import { getFileRefExecutor } from "./create-file-ref.js";

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

@@ -1,11 +1,14 @@
+import type { BeforeTransactionResult, WriteResult } from "@cosmicdrift/kumiko-types/handlers";
 import type { TenantDb } from "../db/tenant-db.ts";
-import type { BeforeTransactionResult, Registry, SessionUser, WriteResult } from "../engine/types/index.ts";
+import type { Registry, SessionUser } from "../engine/types/index.ts";
 import { type CreatedFileRef, type UploadedFileBytes } from "./create-file-ref.ts";
 import type { FileContext } from "./file-handle.ts";
 export type { CreatedFileRef, UploadedFileBytes };
 export type CreateFileRefContext = {
     readonly db: TenantDb;
-    readonly files?: FileContext | undefined;
+    readonly services: {
+        readonly files?: FileContext | undefined;
+    };
     readonly registry: Registry;
     readonly user: SessionUser;
 };
@@ -21,6 +24,6 @@ export type CreateFileRefInput = {
 };
 export declare function filesUnavailableMessage(caller: string): string;
 export declare function createFileRefFromBytes(ctx: CreateFileRefContext, input: CreateFileRefInput): Promise<WriteResult<CreatedFileRef>>;
-export type UploadFileBytesContext = Pick<CreateFileRefContext, "db" | "files" | "registry" | "user">;
+export type UploadFileBytesContext = Pick<CreateFileRefContext, "db" | "services" | "registry" | "user">;
 export declare function uploadFileBytesBeforeTransaction(ctx: UploadFileBytesContext, input: CreateFileRefInput): Promise<BeforeTransactionResult<UploadedFileBytes>>;
 export declare function createFileRefFromUploadedBytes(ctx: Pick<CreateFileRefContext, "db" | "user">, uploaded: UploadedFileBytes): Promise<WriteResult<CreatedFileRef>>;

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

@@ -8,13 +8,13 @@ import { assertSafeStorageKey } from "./types.js";
 // 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) {
-    return `${caller}: ctx.files is unavailable because no file-provider resolver is wired on this dispatcher context. Mount a file-provider-* feature and build the dispatcher context with withFileProviderResolver (HTTP, job and seed dispatchers each need it)`;
+    return `${caller}: ctx.services.files is unavailable because no file-provider resolver is wired on this dispatcher context. Mount a file-provider-* feature and build the dispatcher context with withFileProviderResolver (HTTP, job and seed dispatchers each need it)`;
 }
 // Server-side counterpart of POST /files for handlers/jobs that produce bytes
 // themselves (generated PDFs, exports). Same validation, storage layout and
 // fileRef.created event as an upload; the tenant is always ctx.user.tenantId.
 export async function createFileRefFromBytes(ctx, input) {
-    const { files } = ctx;
+    const { files } = ctx.services;
     if (!files) {
         return writeFailure(new InternalError({
             message: filesUnavailableMessage("createFileRefFromBytes"),
@@ -46,6 +46,9 @@ export async function createFileRefFromBytes(ctx, input) {
             return fileRejectedFailure(outcome.error);
         case "failed":
             return outcome.failure;
+        case "target-locked":
+            // Only the HTTP route supplies the lock re-check, so this path cannot produce it.
+            return writeFailure(new InternalError({ message: "createFileRefFromBytes: unexpected target-locked outcome" }));
     }
 }
 function fileRejectedFailure(error) {
@@ -56,7 +59,7 @@ function fileRejectedFailure(error) {
 // A crash between this phase and the commit leaves the bytes in storage; the upload ledger sweep
 // removes them after its grace period.
 export async function uploadFileBytesBeforeTransaction(ctx, input) {
-    const { files } = ctx;
+    const { files } = ctx.services;
     if (!files) {
         return writeFailure(new InternalError({
             message: filesUnavailableMessage("uploadFileBytesBeforeTransaction"),

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

@@ -1,5 +1,6 @@
-import { type TenantDb } from "../db/tenant-db.ts";
-import { type AnyFileFieldDef, type Registry, type SessionUser } from "../engine/types/index.ts";
+import type { AnyFileFieldDef } from "@cosmicdrift/kumiko-types/fields";
+import type { TenantDb } from "../db/tenant-db.ts";
+import type { Registry, SessionUser } from "../engine/types/index.ts";
 import { type WriteFailure } from "../errors/index.ts";
 export declare const DEFAULT_MAX_UPLOAD_SIZE = "10mb";
 declare function buildFileRefExecutor(): import("@cosmicdrift/kumiko-types/event-store-executor-types").EventStoreExecutor<{
@@ -50,6 +51,7 @@ export type StoreFileDeps = {
     readonly defaultMaxUploadSize: string;
     readonly writeBytes: (storageKey: string, data: Uint8Array, mimeType: string) => Promise<void>;
     readonly deleteBytes: (storageKey: string) => Promise<void>;
+    readonly isAttachTargetLocked?: (rowDb: TenantDb) => Promise<boolean>;
 };
 export type CreatedFileRef = {
     readonly id: string;
@@ -80,6 +82,8 @@ export type StoreFileOutcome = {
 } | {
     readonly kind: "rejected";
     readonly error: string;
+} | {
+    readonly kind: "target-locked";
 } | {
     readonly kind: "failed";
     readonly failure: WriteFailure;

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

@@ -1,6 +1,6 @@
 import { createEventStoreExecutor } from "../db/event-store-executor.js";
-import { runInOwnTransaction } from "../db/tenant-db.js";
-import { isFileField, } from "../engine/types/index.js";
+import { runInOwnTransaction } from "../db/tenant-db-scoped-rebind.js";
+import { isFileField } from "../engine/field-helpers.js";
 import { InternalError } from "../errors/index.js";
 import { generateId } from "../utils/index.js";
 import { isActionFormScreenQn, resolveActionFormFileField } from "./action-form-upload.js";
@@ -41,6 +41,8 @@ export function resolveAttachedField(registry, entityType, fieldName) {
         return { kind: "unresolvable" };
     return { kind: "resolved", fieldDef };
 }
+class AttachTargetLockedError extends Error {
+}
 function resolveUploadField(registry, input) {
     const { entityType, entityId, fieldName, actionForm } = input;
     if (actionForm === undefined)
@@ -196,14 +198,21 @@ export async function storeFileAsFileRef(deps, input) {
             // skip: the create failure is the error worth reporting; the leftover bytes stay in storage.
         }
     };
+    const createRow = async (rowDb) => {
+        if (await deps.isAttachTargetLocked?.(rowDb))
+            throw new AttachTargetLockedError();
+        return createFileRefRow({ user: deps.user, tenantDb: rowDb }, upload.uploaded);
+    };
     let row;
     try {
         row = deps.rowInOwnTransaction
-            ? await runInOwnTransaction(deps.tenantDb, (txDb) => createFileRefRow({ user: deps.user, tenantDb: txDb }, upload.uploaded))
-            : await createFileRefRow(deps, upload.uploaded);
+            ? await runInOwnTransaction(deps.tenantDb, createRow)
+            : await createRow(deps.tenantDb);
     }
     catch (e) {
         await deleteUploadedBytes();
+        if (e instanceof AttachTargetLockedError)
+            return { kind: "target-locked" };
         throw e;
     }
     if ("failure" in row) {

package/dist/files/dispose-removed-file-refs.d.ts

@@ -1,5 +1,6 @@
+import type { SaveContext } from "@cosmicdrift/kumiko-types/hooks";
 import type { TenantDb } from "../db/tenant-db.ts";
-import { type Registry, type SaveContext, type SessionUser } from "../engine/types/index.ts";
+import type { Registry, SessionUser } from "../engine/types/index.ts";
 export declare function disposeRemovedFileRefs(args: {
     readonly registry: Registry;
     readonly result: SaveContext;

package/dist/files/dispose-removed-file-refs.js

@@ -1,4 +1,4 @@
-import { isFileField, } from "../engine/types/index.js";
+import { isFileField } from "../engine/field-helpers.js";
 import { reraiseAsKumikoError } from "../errors/index.js";
 import { fileRefIdsOf } from "./bind-pending-file-refs.js";
 import { getFileRefExecutor } from "./create-file-ref.js";

package/dist/files/feature.js

@@ -41,10 +41,10 @@ export function createFilesFeature(options = {}) {
             handler: async (_payload, ctx) => {
                 await sweepOrphanedUploads({
                     db: ctx.db,
-                    files: ctx.files,
+                    files: ctx.services.files,
                     now: ctx.tz.now(),
                     graceHours: uploadSweepGraceHours,
-                    log: ctx.log,
+                    log: ctx.obs.log,
                 });
             },
         });

package/dist/files/file-handle.js

@@ -3,7 +3,7 @@
 // The contract the framework exposes to hook/handler code: a FileHandle lets
 // you read/write/delete the binary behind a storage key without ever passing
 // the binary through event payloads, job queues, or hook signatures. Events
-// carry the key, hooks reach for `ctx.files.ref(key)` when they actually need
+// carry the key, hooks reach for `ctx.services.files.ref(key)` when they actually need
 // the bytes, and big files stay in the storage layer where they belong.
 //
 // `derive(suffix)` is the primitive for thumbnail/variant keys: it inserts a

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

@@ -1,7 +1,8 @@
+import type { RateLimitResolver } from "@cosmicdrift/kumiko-types/rate-limit-types";
 import type { WriteErrorInfo } from "@cosmicdrift/kumiko-types/write-error-info-types";
 import { Hono } from "hono";
 import type { DbConnection } from "../db/connection.ts";
-import { type Registry, type SessionUser, type TenantId } from "../engine/types/index.ts";
+import type { Registry, SessionUser, TenantId } from "../engine/types/index.ts";
 import type { FileProviderResolver } from "./provider-resolver.ts";
 import type { RecordReadCheck } from "./record-read-check.ts";
 import { type RecordWriteCheck } from "./record-write-check.ts";
@@ -30,6 +31,7 @@ export type FileAccessGuard = (args: {
 }) => FileAccessDecision | Promise<FileAccessDecision>;
 export type FileRoutesOptions = {
     readonly db: DbConnection;
+    readonly metaBatchRateLimitResolver?: RateLimitResolver;
     readonly resolveProvider: FileProviderResolver;
     readonly registry?: Registry;
     readonly maxUploadSize?: string;