@cosmicdrift/kumiko-framework 0.328.0 → 0.329.0

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

@@ -0,0 +1,71 @@
+// Dead-letter storage for apply-handler failures during projection rebuild.
+//
+// Background: rebuildProjection / rebuildMultiStreamProjection replay the
+// event log through apply handlers inside ONE transaction. A single event
+// whose (possibly years-old) payload makes its apply throw rolls the whole
+// replay back — the projection stays permanently un-rebuildable until the
+// event is repaired by hand. The upcaster dead-letter only quarantines
+// upcast-TRANSFORM failures, not apply failures (#760).
+//
+// Quarantine mode (errorPolicy.skipApplyErrors on RebuildDeps, or
+// MspErrorMode.rebuild.skipApplyErrors on the MSP definition) confines each
+// apply to a savepoint: a throwing apply is rolled back, captured into
+// `kumiko_rebuild_dead_letters`, and the replay continues. Replay-after-fix
+// 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 "../stack/index.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.
+    id: bigint("id", { mode: "bigint" }).primaryKey().generatedAlwaysAsIdentity(),
+    projectionName: text("projection_name").notNull(),
+    // StoredEvent.id is surfaced as `string` (bigint serialised for JSON
+    // safety) — stored as text to keep the round-trip identity.
+    eventId: text("event_id").notNull(),
+    tenantId: uuid("tenant_id").notNull(),
+    aggregateId: text("aggregate_id").notNull(),
+    aggregateType: text("aggregate_type").notNull(),
+    eventType: text("event_type").notNull(),
+    errorMessage: text("error_message").notNull(),
+    payload: jsonb("payload").notNull(),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+}, (t) => ({
+    projectionIdx: index("rebuild_dead_letters_projection_idx").on(t.projectionName),
+    createdAtIdx: index("rebuild_dead_letters_created_at_idx").on(t.createdAt),
+}));
+// Idempotent table-create. The rebuild runners call this before the rebuild
+// tx whenever quarantine mode is active, so the opt-in works on databases
+// 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"))
+        return;
+    await unsafePushTables(db, { kumikoRebuildDeadLetters: rebuildDeadLetterTable });
+}
+// Bulk-write, called ONCE at the end of a quarantining rebuild (inside its
+// tx). Unqualified insert — during the rebuild the search_path points at the
+// shadow schema, and this table exists only in public, so it falls through.
+export async function recordRebuildDeadLetters(db, projectionName, skipped) {
+    const { insertMany } = await import("../bun-db/query.js");
+    await insertMany(db, rebuildDeadLetterTable, skipped.map(({ event, error }) => ({
+        projectionName,
+        eventId: event.id,
+        tenantId: event.tenantId,
+        aggregateId: event.aggregateId,
+        aggregateType: event.aggregateType,
+        eventType: event.type,
+        errorMessage: error instanceof Error ? error.message : String(error),
+        payload: event.payload,
+    })));
+}
+// Ops-side triage query, optionally scoped to one projection.
+export async function listRebuildDeadLetters(db, options = {}) {
+    const { selectMany } = await import("../bun-db/query.js");
+    const limit = options.limit ?? 100;
+    const where = options.projectionName !== undefined ? { projectionName: options.projectionName } : undefined;
+    return selectMany(db, rebuildDeadLetterTable, where, {
+        orderBy: { col: "createdAt", direction: "desc" },
+        limit,
+    });
+}

package/dist/event-store/row-to-stored-event.d.ts

@@ -0,0 +1,17 @@
+import type { TenantId } from "../engine/types/index.js";
+import type { EventMetadata, StoredEvent } from "./event-store.js";
+type EventRow = {
+    readonly id: bigint;
+    readonly aggregateId: string;
+    readonly aggregateType: string;
+    readonly tenantId: TenantId;
+    readonly version: number;
+    readonly type: string;
+    readonly eventVersion: number;
+    readonly payload: Record<string, unknown>;
+    readonly metadata: EventMetadata;
+    readonly createdAt: Temporal.Instant;
+    readonly createdBy: string;
+};
+export declare function toStoredEvent(row: EventRow): StoredEvent;
+export {};

package/dist/event-store/row-to-stored-event.js

@@ -0,0 +1,15 @@
+export function toStoredEvent(row) {
+    return {
+        id: String(row.id),
+        aggregateId: row.aggregateId,
+        aggregateType: row.aggregateType,
+        tenantId: row.tenantId,
+        version: row.version,
+        type: row.type,
+        eventVersion: row.eventVersion,
+        payload: row.payload,
+        metadata: row.metadata,
+        createdAt: row.createdAt,
+        createdBy: row.createdBy,
+    };
+}

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

@@ -0,0 +1,26 @@
+import type { LoadAggregateWithSnapshotOptions, LoadAggregateWithSnapshotResult, SnapshotReducer } from "@cosmicdrift/kumiko-types/snapshot-types";
+import type { DbConnection, DbRunner } from "../db/connection.js";
+import type { TenantId } from "../engine/types/index.js";
+export declare const snapshotsTable: import("@cosmicdrift/kumiko-types/schema-table-types").SchemaTable;
+export declare function createSnapshotsTable(db: DbConnection): Promise<void>;
+export type Snapshot<TState extends Record<string, unknown> = Record<string, unknown>> = {
+    readonly aggregateId: string;
+    readonly tenantId: TenantId;
+    readonly aggregateType: string;
+    readonly version: number;
+    readonly state: TState;
+    readonly snapshotVersion: number;
+    readonly createdAt: Temporal.Instant;
+};
+export type SaveSnapshotArgs = {
+    readonly aggregateId: string;
+    readonly tenantId: TenantId;
+    readonly aggregateType: string;
+    readonly version: number;
+    readonly state: Record<string, unknown>;
+    readonly snapshotVersion?: number;
+};
+export declare function saveSnapshot(db: DbRunner, args: SaveSnapshotArgs): Promise<void>;
+export declare function loadLatestSnapshot<TState extends Record<string, unknown> = Record<string, unknown>>(db: DbRunner, aggregateId: string, tenantId: TenantId): Promise<Snapshot<TState> | null>;
+export type { LoadAggregateWithSnapshotOptions, LoadAggregateWithSnapshotResult, SnapshotReducer, } from "@cosmicdrift/kumiko-types/snapshot-types";
+export declare function loadAggregateWithSnapshot<TState extends Record<string, unknown>>(db: DbRunner, aggregateId: string, tenantId: TenantId, reducer: SnapshotReducer<TState>, initial: TState, options?: LoadAggregateWithSnapshotOptions): Promise<LoadAggregateWithSnapshotResult<TState>>;

package/dist/event-store/snapshot.js

@@ -0,0 +1,155 @@
+// sql now comes from native dialect
+import { index, instant, integer, jsonb, table as pgTable, primaryKey, sql, text, uuid, } from "../db/dialect.js";
+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 "../stack/index.js";
+import { isStreamArchived } from "./archive.js";
+import { loadEventsAfterVersion } from "./event-store.js";
+// Marten-aligned snapshot store. A snapshot is a point-in-time materialised
+// state of an aggregate at a specific version, cached so rehydrating the
+// aggregate doesn't require replaying every historical event.
+//
+// Read path (loadAggregateWithSnapshot):
+//   1. isStreamArchived? → honour same semantics as loadAggregate
+//   2. loadLatestSnapshot → state + version N (or null)
+//   3. loadEventsAfterVersion(aggregate, N) → only the delta
+//   4. reducer(snapshot, delta) → current state
+//
+// Write path: manual via ctx.snapshotAggregate, or automatic via the
+// { snapshotEvery: N } load option — the read path persists a fresh
+// snapshot whenever it folded at least N delta events.
+//
+// Schema-migration policy: explicit generations, no reducer hashing. A
+// snapshot stores the aggregate state in the reducer's current shape plus
+// a caller-declared snapshot_version. Bump { snapshotVersion } when the
+// reducer's shape changes — stored snapshots with another generation are
+// ignored (full replay through the upcaster chain on events) and restamped
+// on the next auto-save. Snapshots stay a perf optimisation, not a source
+// of truth.
+//
+// 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
+// and runs upcastStoredEvents on the delta before calling the reducer, so
+// feature authors always see current-version payloads.
+export const snapshotsTable = pgTable("kumiko_snapshots", {
+    aggregateId: uuid("aggregate_id").notNull(),
+    tenantId: uuid("tenant_id").notNull(),
+    // Kept even though (aggregate_id, version) is globally unique: the
+    // schema-migration invalidation mechanism (see file header) filters by
+    // aggregate_type, so storing it avoids a join on events just to
+    // invalidate snapshots.
+    aggregateType: text("aggregate_type").notNull(),
+    // The version covered by this snapshot. `loadEventsAfterVersion`
+    // returns events with version > this value.
+    version: integer("version").notNull(),
+    state: jsonb("state").$type().notNull(),
+    // Reducer-shape generation — snapshots from another generation are
+    // ignored on load. See LoadAggregateWithSnapshotOptions.snapshotVersion.
+    snapshotVersion: integer("snapshot_version").notNull().default(sql `1`),
+    createdAt: instant("created_at", { precision: 3 }).notNull().default(sql `now()`),
+}, (t) => ({
+    pk: primaryKey({ columns: [t.aggregateId, t.version] }),
+    // Latest-snapshot lookup: WHERE aggregate_id = ? ORDER BY version DESC
+    // LIMIT 1. With this index the planner does one seek + backward scan
+    // instead of sort-and-limit.
+    latestIdx: index("kumiko_snapshots_latest_idx").on(t.aggregateId, t.tenantId, t.version),
+}));
+export async function createSnapshotsTable(db) {
+    // skip: table already exists — idempotent boot + test-setup call
+    if (await tableExists(db, "public.kumiko_snapshots")) {
+        // Installs that predate snapshot_version get healed by the same
+        // idempotent ensure that `kumiko schema apply` / test-setup already runs.
+        await ensureSnapshotVersionColumn(db);
+        // skip: table already ensured — only the column heal above was needed
+        return;
+    }
+    await unsafePushTables(db, { kumikoSnapshots: snapshotsTable });
+}
+// Upsert-style save so re-snapshotting the same (aggregateId, version) is
+// idempotent. Caller can retake a snapshot at the same version without
+// bespoke error handling — useful when a feature's snapshot policy runs
+// during a concurrent retake.
+export async function saveSnapshot(db, args) {
+    await upsertSnapshot(db, {
+        aggregateId: args.aggregateId,
+        tenantId: args.tenantId,
+        aggregateType: args.aggregateType,
+        version: args.version,
+        state: args.state,
+        snapshotVersion: args.snapshotVersion ?? 1,
+    });
+}
+// Latest snapshot lookup. Tenant filter is belt-and-suspenders — the
+// aggregate_id should already scope uniquely, but an accidentally-reused
+// UUID across tenants would otherwise silently leak.
+export async function loadLatestSnapshot(db, aggregateId, tenantId) {
+    const rows = await selectMany(db, snapshotsTable, { aggregateId, tenantId }, { orderBy: { col: "version", direction: "desc" }, limit: 1 });
+    const row = rows[0];
+    if (!row)
+        return null;
+    return {
+        aggregateId: row.aggregateId,
+        tenantId: row.tenantId,
+        aggregateType: row.aggregateType,
+        version: row.version,
+        state: row.state, // @cast-boundary engine-payload
+        snapshotVersion: row.snapshotVersion,
+        createdAt: row.createdAt,
+    };
+}
+// Snapshot-aware rehydrate. Loads the latest snapshot (if any), applies
+// events strictly newer than snapshot.version, and returns the fold.
+// Callers that want strictly-event-sourced loading should stick with
+// loadAggregate + reduce — this path exists for perf-critical aggregates.
+//
+// Archive behaviour mirrors loadAggregate: an archived stream returns
+// `initial` with version=0, snapshotHit=false, unless
+// { includeArchived: true } is passed. This keeps snapshot and raw
+// loadAggregate interchangeable from the caller's point of view.
+export async function loadAggregateWithSnapshot(db, aggregateId, tenantId, reducer, initial, options) {
+    if (options?.snapshotEvery !== undefined &&
+        (!Number.isInteger(options.snapshotEvery) || options.snapshotEvery < 1)) {
+        throw new Error(`loadAggregateWithSnapshot: snapshotEvery must be an integer >= 1, got ${String(options.snapshotEvery)}`);
+    }
+    if (!options?.includeArchived) {
+        const archived = await isStreamArchived(db, tenantId, aggregateId);
+        if (archived) {
+            return { state: initial, version: 0, snapshotHit: false };
+        }
+    }
+    const shapeVersion = options?.snapshotVersion ?? 1;
+    const stored = await loadLatestSnapshot(db, aggregateId, tenantId);
+    const snapshot = stored && stored.snapshotVersion === shapeVersion ? stored : null;
+    const baseState = snapshot ? snapshot.state : initial;
+    const afterVersion = snapshot ? snapshot.version : 0;
+    const delta = await loadEventsAfterVersion(db, aggregateId, tenantId, afterVersion);
+    let state = baseState;
+    for (const event of delta) {
+        const effective = options?.upcastEvent ? await options.upcastEvent(event) : event;
+        state = reducer(state, effective);
+    }
+    const lastDelta = delta[delta.length - 1];
+    const latestVersion = lastDelta ? lastDelta.version : afterVersion;
+    if (options?.snapshotEvery !== undefined && lastDelta && delta.length >= options.snapshotEvery) {
+        try {
+            await saveSnapshot(db, {
+                aggregateId,
+                tenantId,
+                aggregateType: lastDelta.aggregateType,
+                version: latestVersion,
+                state,
+                snapshotVersion: shapeVersion,
+            });
+        }
+        catch {
+            // Best-effort cache write — losing it only costs the next load a replay.
+        }
+    }
+    return {
+        state,
+        version: latestVersion,
+        snapshotHit: snapshot !== null,
+    };
+}

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

@@ -0,0 +1,13 @@
+import { AGGREGATE_TRANSFERRED_EVENT_TYPE } from "../crypto/system-event-pii.js";
+import type { DbRunner } from "../db/index.js";
+import type { TenantId } from "../engine/types/index.js";
+export declare const AGGREGATE_TRANSFER_STREAM_TYPE = "aggregate-transfer";
+export { AGGREGATE_TRANSFERRED_EVENT_TYPE };
+export type TransferAggregateStreamsArgs = {
+    readonly sourceTenantId: TenantId;
+    readonly destinationTenantId: TenantId;
+    readonly aggregateType: string;
+    readonly aggregateIds: readonly string[];
+    readonly transferredBy: string;
+};
+export declare function transferAggregateStreams(db: DbRunner, args: TransferAggregateStreamsArgs): Promise<number>;

package/dist/event-store/transfer.js

@@ -0,0 +1,62 @@
+// The event store's own tenant-transfer primitive: the ONE place allowed to
+// move a stream across the tenant boundary (enforced by
+// guard-event-store-writes' allowlist). Each move leaves an audit event in
+// the destination tenant.
+//
+// Runs entirely on the caller-supplied DbRunner, so the move rides whatever
+// transaction the caller is already inside (tenant-handover's claim handler
+// commits it together with the root row's ownership write — see
+// move-entity-graph.ts's file header for why that matters).
+import { AGGREGATE_TRANSFERRED_EVENT_TYPE } from "../crypto/system-event-pii.js";
+import { deleteSnapshotsForAggregates, transferArchivedStreamRows, transferEventRows, } from "../db/queries/event-store-transfer.js";
+import { generateId } from "../utils/ids.js";
+import { append } from "./event-store.js";
+export const AGGREGATE_TRANSFER_STREAM_TYPE = "aggregate-transfer";
+export { AGGREGATE_TRANSFERRED_EVENT_TYPE };
+// Moves one aggregate type's event history, drops its cached snapshots, and
+// carries any archive marker across the tenant boundary. Returns the number
+// of aggregates that actually had events (and therefore moved) — an id in
+// `aggregateIds` with no events under `sourceTenantId`/`aggregateType`
+// contributes nothing and gets no follow-up event.
+export async function transferAggregateStreams(db, args) {
+    if (args.aggregateIds.length === 0)
+        return 0;
+    const movedAggregateIds = await transferEventRows(db, {
+        sourceTenantId: args.sourceTenantId,
+        destinationTenantId: args.destinationTenantId,
+        aggregateType: args.aggregateType,
+        aggregateIds: args.aggregateIds,
+    });
+    if (movedAggregateIds.length === 0)
+        return 0;
+    await deleteSnapshotsForAggregates(db, {
+        tenantId: args.sourceTenantId,
+        aggregateIds: movedAggregateIds,
+    });
+    await transferArchivedStreamRows(db, {
+        sourceTenantId: args.sourceTenantId,
+        destinationTenantId: args.destinationTenantId,
+        aggregateType: args.aggregateType,
+        aggregateIds: movedAggregateIds,
+    });
+    for (const aggregateId of movedAggregateIds) {
+        // A fresh, own stream — not an append onto the moved aggregate's own
+        // stream — so the marker never bumps the moved aggregate's version or
+        // shows up when a projection replays that aggregate's history.
+        await append(db, {
+            aggregateId: generateId(),
+            aggregateType: AGGREGATE_TRANSFER_STREAM_TYPE,
+            tenantId: args.destinationTenantId,
+            expectedVersion: 0,
+            type: AGGREGATE_TRANSFERRED_EVENT_TYPE,
+            payload: {
+                aggregateType: args.aggregateType,
+                aggregateId,
+                sourceTenantId: args.sourceTenantId,
+                destinationTenantId: args.destinationTenantId,
+            },
+            metadata: { userId: args.transferredBy },
+        });
+    }
+    return movedAggregateIds.length;
+}

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

@@ -0,0 +1 @@
+export type * from "@cosmicdrift/kumiko-types/event-store-types";

package/dist/event-store/types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,27 @@
+import type { DbConnection, DbRunner } from "../db/connection.js";
+import type { StoredEvent } from "./event-store.js";
+export declare const upcasterDeadLetterTable: import("@cosmicdrift/kumiko-types/schema-table-types").SchemaTable;
+export declare function createUpcasterDeadLetterTable(db: DbConnection): Promise<void>;
+export declare function recordUpcasterDeadLetter(db: DbRunner, args: {
+    event: StoredEvent;
+    fromVersion: number;
+    targetVersion: number;
+    error: unknown;
+}): Promise<void>;
+export type DeadLetterRow = {
+    readonly id: bigint;
+    readonly eventId: string;
+    readonly tenantId: string;
+    readonly aggregateId: string;
+    readonly aggregateType: string;
+    readonly eventType: string;
+    readonly fromVersion: number;
+    readonly targetVersion: number;
+    readonly errorMessage: string;
+    readonly originalPayload: Record<string, unknown>;
+    readonly createdAt: Date;
+};
+export declare function listDeadLetters(db: DbConnection, options?: {
+    eventType?: string;
+    limit?: number;
+}): Promise<readonly DeadLetterRow[]>;

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

@@ -0,0 +1,76 @@
+// Dead-letter storage for failed event upcasters.
+//
+// Background: upcastStoredEvent walks a stored event's payload through
+// r.eventMigration transforms until it matches the current schema. A
+// migration that throws (malformed legacy payload, DB-dependent
+// enrichment that fails) propagates to the dispatcher and kills the
+// pass — one bad event in a million can stall every projection behind
+// it. The same applies to MSP rebuild.
+//
+// Quarantine mode captures the failure into `kumiko_upcaster_dead_letters`,
+// lets the dispatcher skip the event, and surfaces the row count via
+// ops tooling. Replay (re-apply the migration after a code fix) is a
+// 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 "../stack/index.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
+    // lands) without unique-violation noise.
+    id: bigint("id", { mode: "bigint" }).primaryKey().generatedAlwaysAsIdentity(),
+    // StoredEvent.id is surfaced as `string` (bigint serialised for JSON
+    // safety). Storing as text keeps the round-trip identity without a
+    // coerce step at every write site.
+    eventId: text("event_id").notNull(),
+    tenantId: uuid("tenant_id").notNull(),
+    aggregateId: text("aggregate_id").notNull(),
+    aggregateType: text("aggregate_type").notNull(),
+    eventType: text("event_type").notNull(),
+    fromVersion: integer("from_version").notNull(),
+    targetVersion: integer("target_version").notNull(),
+    errorMessage: text("error_message").notNull(),
+    originalPayload: jsonb("original_payload").notNull(),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+}, (t) => ({
+    eventTypeIdx: index("upcaster_dead_letters_event_type_idx").on(t.eventType),
+    createdAtIdx: index("upcaster_dead_letters_created_at_idx").on(t.createdAt),
+}));
+// Idempotent table-create. Called from setupTestStack for suites that
+// 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"))
+        return;
+    await unsafePushTables(db, { kumikoUpcasterDeadLetters: upcasterDeadLetterTable });
+}
+// Writes a dead-letter row. Called by upcastStoredEvent when errorPolicy
+// is "quarantine" and a transform threw. Returns the inserted row id —
+// ops tooling uses it for correlate-and-replay flows.
+export async function recordUpcasterDeadLetter(db, args) {
+    const message = args.error instanceof Error ? args.error.message : String(args.error);
+    const { insertOne } = await import("../bun-db/query.js");
+    await insertOne(db, upcasterDeadLetterTable, {
+        eventId: args.event.id,
+        tenantId: args.event.tenantId,
+        aggregateId: args.event.aggregateId,
+        aggregateType: args.event.aggregateType,
+        eventType: args.event.type,
+        fromVersion: args.fromVersion,
+        targetVersion: args.targetVersion,
+        errorMessage: message,
+        originalPayload: args.event.payload,
+    });
+}
+// Ops-side query. Loads recent failures, optionally scoped by event-type
+// to triage a single broken migration without pulling the full table.
+export async function listDeadLetters(db, options = {}) {
+    const { selectMany } = await import("../bun-db/query.js");
+    const limit = options.limit ?? 100;
+    const where = options.eventType !== undefined ? { eventType: options.eventType } : undefined;
+    const rows = await selectMany(db, upcasterDeadLetterTable, where, {
+        orderBy: { col: "createdAt", direction: "desc" },
+        limit,
+    });
+    return rows;
+}

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

@@ -0,0 +1,14 @@
+import type { DbRunner } from "../db/index.js";
+import type { EventUpcastCtx, EventUpcastFn, TenantId } from "../engine/types/index.js";
+import type { StoredEvent } from "./event-store.js";
+export type UpcasterErrorPolicy = "throw" | "quarantine";
+export type UpcastOptions = {
+    readonly errorPolicy?: UpcasterErrorPolicy;
+};
+export type EventUpcasters = ReadonlyMap<string, {
+    readonly currentVersion: number;
+    readonly chain: ReadonlyMap<number, EventUpcastFn>;
+}>;
+export declare function upcastStoredEvent(event: StoredEvent, upcasters: EventUpcasters, ctx: EventUpcastCtx): Promise<StoredEvent>;
+export declare function upcastStoredEvents(events: readonly StoredEvent[], upcasters: EventUpcasters, ctx: EventUpcastCtx, options?: UpcastOptions): Promise<readonly StoredEvent[]>;
+export declare function makeUpcastCtx(db: DbRunner, tenantId: TenantId): EventUpcastCtx;

package/dist/event-store/upcaster.js

@@ -0,0 +1,86 @@
+import { recordUpcasterDeadLetter } from "./upcaster-dead-letter.js";
+// Upcast a single stored event through however many registered migrations
+// separate its stored eventVersion from the current schema version.
+//
+// Contract:
+//   - Event types with no registered upcaster pass through unchanged.
+//   - Event types whose stored version equals currentVersion pass through
+//     unchanged (fast path — hot on projection rebuild).
+//   - Gaps in the chain are a hard error. The registry validates chain
+//     completeness at boot, so this throw is a belt-and-suspenders signal
+//     that something wrote a version number the registry doesn't expect.
+//
+// `ctx` carries db + tenantId for async upcasters that need DB enrichment.
+// Sync transforms ignore ctx entirely.
+// Legacy throw-on-error API — preserved so existing callers (projection-
+// rebuild, msp-rebuild, feature tests) stay unchanged. Returns a
+// StoredEvent (never null); quarantine mode lives on the bulk helper.
+export async function upcastStoredEvent(event, upcasters, ctx) {
+    const result = await upcastStoredEventWithPolicy(event, upcasters, ctx, {
+        errorPolicy: "throw",
+    });
+    // `throw` mode can never return null — the catch-block rethrows. Narrow
+    // the type for callers without an `if (result === null)` check at every
+    // callsite.
+    if (result === null) {
+        throw new Error(`unreachable: upcastStoredEvent with errorPolicy="throw" returned null for "${event.type}"`);
+    }
+    return result;
+}
+// Underlying policy-aware worker. Returns null when the transform threw
+// AND errorPolicy="quarantine" — the event gets recorded in dead-letters
+// and the bulk helper filters it out.
+async function upcastStoredEventWithPolicy(event, upcasters, ctx, options) {
+    const info = upcasters.get(event.type);
+    if (!info)
+        return event;
+    if (event.eventVersion >= info.currentVersion)
+        return event;
+    let payload = event.payload; // @cast-boundary engine-payload
+    let v = event.eventVersion;
+    const startVersion = event.eventVersion;
+    while (v < info.currentVersion) {
+        const transform = info.chain.get(v);
+        if (!transform) {
+            // Missing chain is a boot-validator bug, not a data problem —
+            // always throw regardless of policy so the gap gets fixed rather
+            // than silently rotting every affected event into dead-letters.
+            throw new Error(`Missing upcaster for event "${event.type}" v${v} → v${v + 1}. ` +
+                `The registry should have caught this at boot — check the eventUpcasterMap wiring.`);
+        }
+        try {
+            payload = await transform(payload, ctx);
+            v++;
+        }
+        catch (err) {
+            if (options.errorPolicy === "quarantine") {
+                await recordUpcasterDeadLetter(ctx.db, {
+                    event,
+                    fromVersion: startVersion,
+                    targetVersion: info.currentVersion,
+                    error: err,
+                });
+                return null;
+            }
+            throw err;
+        }
+    }
+    return {
+        ...event,
+        payload: payload, // @cast-boundary engine-payload
+        eventVersion: v,
+    };
+}
+export async function upcastStoredEvents(events, upcasters, ctx, options = {}) {
+    // skip: no upcasters registered anywhere — common case when a project
+    // hasn't bumped any event version yet. Short-circuit keeps replay fast.
+    if (upcasters.size === 0)
+        return events;
+    const results = await Promise.all(events.map((e) => upcastStoredEventWithPolicy(e, upcasters, ctx, options)));
+    return results.filter((e) => e !== null);
+}
+// Convenience builder for callers that have db + tenantId at hand and want
+// to construct the ctx-arg without restating the field names everywhere.
+export function makeUpcastCtx(db, tenantId) {
+    return { db, tenantId };
+}

package/dist/files/content-disposition.d.ts

@@ -0,0 +1,3 @@
+export declare function buildContentDispositionHeader(fileName: string): string;
+export declare function toAsciiFallback(name: string): string;
+export declare function encodeRFC5987(value: string): string;

package/dist/files/content-disposition.js

@@ -0,0 +1,50 @@
+// RFC-6266 + RFC-5987 compliant Content-Disposition builder.
+//
+// fileName reaches this module from the client's multipart upload — it is
+// effectively attacker-controlled. A name like
+// `foo.pdf"; filename*=utf-8''evil.exe` would break the `filename="..."`
+// header quoting and inject a second parameter if we interpolated the raw
+// string. Two-step fix:
+//
+//   1. ASCII fallback for `filename="..."` — strip anything outside a safe
+//      token set, keeping the name readable for legacy clients that don't
+//      understand RFC 5987.
+//   2. Percent-encoded UTF-8 for `filename*=UTF-8''...` — the modern
+//      parameter that every current browser honours. RFC 5987 requires a
+//      handful of reserved chars that encodeURIComponent leaves alone
+//      ('()*) to also be escaped.
+//
+// Lives in its own module so the sanitisation is unit-testable in
+// isolation — the HTTP route exercises integration; edge cases around
+// encoding + fallback live in content-disposition.test.ts.
+const MAX_FALLBACK_LENGTH = 100;
+const SAFE_FALLBACK_CHARS = /[^A-Za-z0-9.\-_()]/g;
+const RFC_5987_EXTRA_ESCAPES = /['()*]/g;
+export function buildContentDispositionHeader(fileName) {
+    const asciiFallback = toAsciiFallback(fileName);
+    const encoded = encodeRFC5987(fileName);
+    return `attachment; filename="${asciiFallback}"; filename*=UTF-8''${encoded}`;
+}
+// Collapse everything outside a safe token set (letters, digits, dot, dash,
+// underscore, parens) to underscore. Bounded length so a giant client-
+// supplied name can't balloon the header.
+//
+// Falls back to "download" in two cases: (1) the stripped result is empty,
+// and (2) nothing alphanumeric survived — a filename like "_______.png" is
+// legal but useless. "download" is readable; the original bytes still
+// reach the browser losslessly via filename* in the surrounding header.
+export function toAsciiFallback(name) {
+    const stripped = name.replace(SAFE_FALLBACK_CHARS, "_").slice(0, MAX_FALLBACK_LENGTH);
+    if (stripped.length === 0)
+        return "download";
+    if (!/[A-Za-z0-9]/.test(stripped))
+        return "download";
+    return stripped;
+}
+// encodeURIComponent handles the UTF-8 → percent-encoding step but leaves
+// a handful of characters unescaped that RFC 5987 calls out as reserved
+// ( ' ( ) * ). Escape those explicitly so the output is strictly
+// conformant and safe to drop into the `ext-value` production.
+export function encodeRFC5987(value) {
+    return encodeURIComponent(value).replace(RFC_5987_EXTRA_ESCAPES, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+}

package/dist/files/feature.d.ts

@@ -0,0 +1,9 @@
+import { type FeatureDefinition } from "../engine/index.js";
+import type { FileAccessGuard } from "./file-routes.js";
+export { fileRefEntity } from "./file-ref-entity.js";
+export type FilesFeatureOptions = {
+    readonly accessGuard?: FileAccessGuard;
+    readonly privilegedRoles?: readonly string[];
+    readonly maxUploadSize?: string;
+};
+export declare function createFilesFeature(options?: FilesFeatureOptions): FeatureDefinition;