@cosmicdrift/kumiko-framework 0.353.0 → 0.354.0

package/dist/db/event-store-executor-write.js

@@ -1,6 +1,8 @@
 import { checkWriteFieldOwnership } from "../engine/field-access.js";
 import { instructionFieldNames } from "../engine/instruction-fields.js";
 import { userCanCreateFieldRow, userCanWriteFieldRow } from "../engine/ownership.js";
+import { buildInsertSchema, buildUpdateSchema } from "../engine/schema-builder.js";
+import { findUnavailableSelectOptions, } from "../engine/screen-helpers.js";
 import { SYSTEM_ROLE, SYSTEM_USER_ID } from "../engine/system-user.js";
 import { AccessDeniedError, VersionConflictError as FrameworkVersionConflict, IdempotentReplayError, InternalError, NotFoundError, PreconditionFailedError, UnprocessableError, writeFailure, } from "../errors/index.js";
 import { append, IdempotentAppendConflictError as EventStoreIdempotentAppendConflict, VersionConflictError as EventStoreVersionConflict, getStreamVersion, } from "../event-store/index.js";
@@ -51,12 +53,32 @@ function isFrameworkSystemUser(user) {
 function isUnchangedValue(a, b) {
     return JSON.stringify(a) === JSON.stringify(b);
 }
+function selectOptionNotAvailableFailure(entries) {
+    const [first] = entries;
+    if (!first)
+        return undefined;
+    const i18nKey = "kumiko.validation.optionNotAvailable";
+    return writeFailure(new UnprocessableError("select_option_not_available", {
+        i18nKey,
+        details: {
+            field: first.field,
+            value: first.value,
+            allowed: first.allowed,
+            fields: entries.map((entry) => ({
+                path: entry.field,
+                code: "select_option_not_available",
+                i18nKey,
+                params: { allowed: entry.allowed },
+            })),
+        },
+    }));
+}
 // preSave runs before ownership checks: authorization must evaluate the row
 // as it will actually be persisted, including hook-derived fields
 // (kumiko-framework#1672). A throwing hook is an app-author bug (bad
 // business rule, not a framework fault) — map it to a clean writeFailure
 // instead of letting it propagate as an internal_error 500.
-async function runPreSave(preSave, changes, previous, isNew, entityName, action) {
+async function runPreSave(preSave, changes, previous, isNew, entityName, action, outputSchema) {
     if (!preSave)
         return { data: changes };
     try {
@@ -65,6 +87,25 @@ async function runPreSave(preSave, changes, previous, isNew, entityName, action)
         // must not leak them into the persisted row — aggregateId already comes
         // from generateId()/the loaded row, not from hook output (fw#1685).
         const { id: _hookId, version: _hookVersion, ...safe } = hookResult;
+        // Hook output skips the handler's input validation yet goes straight into the projection.
+        // Validated only, not replaced by the parse result: hooks may set fields in storage form.
+        const parsed = outputSchema().safeParse(safe);
+        if (!parsed.success) {
+            return {
+                failure: writeFailure(new UnprocessableError("presave_hook_invalid_output", {
+                    i18nKey: "errors.presaveHookInvalidOutput",
+                    details: {
+                        entityName,
+                        action,
+                        handler: `${entityName}:${action}`,
+                        issues: parsed.error.issues.map((issue) => ({
+                            path: issue.path.join("."),
+                            message: issue.message,
+                        })),
+                    },
+                })),
+            };
+        }
         return { data: safe };
     }
     catch (e) {
@@ -79,6 +120,10 @@ async function runPreSave(preSave, changes, previous, isNew, entityName, action)
 export function createWriteVerbs(ctx) {
     const { table, entity, entityName, entityCache, softDelete, streamTenantFor, encryptForStorage, decryptForRead, applyDefaults, stripSensitive, loadById, assertStreamWritable, loadExpectSnapshot, } = ctx;
     const entityInstructionFieldNames = instructionFieldNames(entity);
+    let insertSchema;
+    let updateSchema;
+    const createOutputSchema = () => (insertSchema ??= buildInsertSchema(entity));
+    const updateOutputSchema = () => (updateSchema ??= buildUpdateSchema(entity));
     return {
         async create(payload, user, db, options) {
             if (isForeignTenantOnGlobalEntity(entity, payload["tenantId"])) {
@@ -94,7 +139,7 @@ export function createWriteVerbs(ctx) {
             const explicitId = typeof payload["id"] === "string" ? payload["id"] : undefined; // @cast-boundary engine-payload
             const aggregateId = explicitId ?? generateId();
             const { id: _id, ...payloadWithoutId } = payload;
-            const preSaveResult = await runPreSave(options?.preSave, applyDefaults(payloadWithoutId), {}, true, entityName, "create");
+            const preSaveResult = await runPreSave(options?.preSave, applyDefaults(payloadWithoutId), {}, true, entityName, "create", createOutputSchema);
             if ("failure" in preSaveResult)
                 return preSaveResult.failure;
             const data = preSaveResult.data;
@@ -132,6 +177,9 @@ export function createWriteVerbs(ctx) {
                     },
                 }));
             }
+            const unavailableOnCreate = selectOptionNotAvailableFailure(findUnavailableSelectOptions(entity.fields, data));
+            if (unavailableOnCreate)
+                return unavailableOnCreate;
             // Alle Compound-Types (locatedTimestamp, money, ...) gehen durch
             // dieselbe Pipeline. Caller schickt combined API-Form, Framework
             // speichert flat DB-Form. Siehe db/compound-types.ts.
@@ -261,7 +309,7 @@ export function createWriteVerbs(ctx) {
             const previous = await loadById(payload.id, db);
             if (!previous)
                 return writeFailure(new NotFoundError(entityName, payload.id));
-            const preSaveResult = await runPreSave(updateOptions?.preSave, payload.changes, previous, false, entityName, "update");
+            const preSaveResult = await runPreSave(updateOptions?.preSave, payload.changes, previous, false, entityName, "update", updateOutputSchema);
             if ("failure" in preSaveResult)
                 return preSaveResult.failure;
             const changes = preSaveResult.data;
@@ -316,6 +364,9 @@ export function createWriteVerbs(ctx) {
                     },
                 }));
             }
+            const unavailableOnUpdate = selectOptionNotAvailableFailure(findUnavailableSelectOptions(entity.fields, mergedNew, previous));
+            if (unavailableOnUpdate)
+                return unavailableOnUpdate;
             await assertStreamWritable(db, payload.id, streamTenantFor(user));
             // Stream-version is authoritative, not row.version. `ctx.appendEvent`
             // can bump the stream between CRUD writes (domain event on the same

package/dist/db/index.d.ts

@@ -9,7 +9,7 @@ export type { CursorQueryOptions, CursorResult, DecodedKeysetCursor } from "./cu
 export { decodeCursor, decodeKeysetCursor, encodeCursor, encodeKeysetCursor } from "./cursor.js";
 export type { SchemaTable, SelectQuery, TableColumns } from "./dialect.js";
 export { bigint, bigserial, boolean, extractTableName, index, instant, instantToDriver, integer, jsonb, moneyAmount, numeric, primaryKey, serial, sql, table, text, timestamp, uniqueIndex, uuid, } from "./dialect.js";
-export type { EagerLoadEntityResolver, EagerloadedRow } from "./eagerload.js";
+export type { EagerLoadEntityResolver, EagerLoadViewer, EagerloadedRow } from "./eagerload.js";
 export { collectReferenceFields, enrichRowWithReferences, enrichWithReferences, } from "./eagerload.js";
 export { collectEncryptedFieldNames, configuredEntityFieldEncryption, configureEntityFieldEncryption, decryptEntityFieldValues, encryptEntityFieldValues, } from "./entity-field-encryption.js";
 export { entityTableFromRegistry } from "./entity-table-from-registry.js";

package/dist/db/migrate-generator.js

@@ -336,7 +336,7 @@ export function renderMigrationSql(diff, options) {
     lines.push(`-- Migration ${seq}_${options.name}`);
     lines.push(`-- Generated: ${new Date().toISOString()}`);
     lines.push("-- ");
-    lines.push("-- This file is generated by `kumiko migrate generate`. You may");
+    lines.push("-- This file is generated by `kumiko-schema generate`. You may");
     lines.push("-- hand-edit it before committing — add partial-indexes, BRIN-");
     lines.push("-- variants, performance-tuning. After commit + apply, NEVER edit");
     lines.push("-- this file again (production-DBs already ran it). Write a new");

package/dist/db/queries/backfill-pii.d.ts

@@ -33,6 +33,7 @@ export type PiiBackfillOptions = {
 };
 export type PiiBackfillBatchOptions = PiiBackfillOptions & {
     readonly afterEventId?: bigint | string;
+    readonly eventIds?: readonly string[];
     readonly scanCache?: PiiBackfillScanCache;
 };
 export declare function backfillEventPiiEncryption(db: DbRunner, registry: Registry, options?: PiiBackfillOptions): Promise<PiiBackfillResult>;

package/dist/db/queries/backfill-pii.js

@@ -137,11 +137,16 @@ export async function backfillEventPiiEncryptionBatch(db, registry, options = {}
     });
     if (aggregateTypes.length === 0 && catalogTypes.length === 0)
         return emptyBatch();
-    const rows = (await raw.unsafe(`SELECT "id", "aggregate_id", "aggregate_type", "tenant_id", "type", "payload"
-       FROM "kumiko_events"
-      WHERE ("aggregate_type" = ANY($1::text[]) OR "type" = ANY($2::text[])) AND "id" > $3::bigint
-      ORDER BY "id" ASC
-      LIMIT $4`, [aggregateTypes, catalogTypes, String(options.afterEventId ?? 0), batchSize]));
+    const rows = (await (options.eventIds
+        ? raw.unsafe(`SELECT "id", "aggregate_id", "aggregate_type", "tenant_id", "type", "payload"
+           FROM "kumiko_events"
+          WHERE ("aggregate_type" = ANY($1::text[]) OR "type" = ANY($2::text[])) AND "id" = ANY($3::bigint[])
+          ORDER BY "id" ASC`, [aggregateTypes, catalogTypes, [...options.eventIds]])
+        : raw.unsafe(`SELECT "id", "aggregate_id", "aggregate_type", "tenant_id", "type", "payload"
+           FROM "kumiko_events"
+          WHERE ("aggregate_type" = ANY($1::text[]) OR "type" = ANY($2::text[])) AND "id" > $3::bigint
+          ORDER BY "id" ASC
+          LIMIT $4`, [aggregateTypes, catalogTypes, String(options.afterEventId ?? 0), batchSize])));
     const last = rows[rows.length - 1];
     if (last === undefined)
         return emptyBatch();
@@ -192,7 +197,7 @@ export async function backfillEventPiiEncryptionBatch(db, registry, options = {}
     return {
         ...result,
         lastEventId: String(last.id),
-        scannedAll: rows.length < batchSize,
+        scannedAll: options.eventIds !== undefined || rows.length < batchSize,
         firstFailedEventId,
         touchedAggregateTypes: [...touchedAggregateTypes],
         touchedEventTypes: [...touchedEventTypes],

package/dist/db/queries/event-consumer.d.ts

@@ -9,14 +9,13 @@ export declare function selectEventIdHorizonWithMissingRanges(db: AnyDb): Promis
     readonly gaps: PendingGapEntry[];
 }>;
 export declare function insertConsumerIfAbsent(db: AnyDb, name: string, instanceId: string, startFrom?: "beginning" | "now"): Promise<void>;
-export declare function deleteOrphanedPerInstanceConsumerRows(db: AnyDb, consumerNames: readonly string[], sharedInstanceSentinel: string): Promise<void>;
 export declare function selectProvablyIdleConsumerPairs(db: AnyDb, names: readonly string[], instanceIds: readonly string[], deadStatus: typeof ConsumerStatuses.dead): Promise<ReadonlyArray<{
     readonly name: string;
     readonly instanceId: string;
 }>>;
 export declare function selectConsumerForUpdateSkipLocked(db: AnyDb, name: string, instanceId: string): Promise<Record<string, unknown> | undefined>;
 export declare function markConsumerProcessing(db: AnyDb, name: string, instanceId: string): Promise<void>;
-export declare function recordConsumerPassFailure(db: AnyDb, name: string, instanceId: string, errorMessage: string): Promise<void>;
+export declare function recordConsumerPassFailure(db: AnyDb, name: string, instanceId: string, errorMessage: string, cursorBeforePass?: bigint): Promise<void>;
 export type ConsumerDeliveryOutcome = {
     readonly cursor: bigint;
     readonly attempts: number;
@@ -28,7 +27,7 @@ export type ConsumerDeliveryOutcome = {
 };
 export declare function updateConsumerDeliveryOutcome(db: AnyDb, name: string, instanceId: string, outcome: ConsumerDeliveryOutcome): Promise<void>;
 export declare function updateConsumerStatusReturning(db: AnyDb, name: string, instanceId: string, status: "idle" | "disabled"): Promise<Record<string, unknown> | undefined>;
-export declare function advanceConsumerPastEventReturning(db: AnyDb, name: string, instanceId: string, eventId: bigint, gapToAdd?: PendingGapEntry | null): Promise<Record<string, unknown> | undefined>;
+export declare function advanceConsumerPastEventReturning(db: AnyDb, name: string, instanceId: string, eventId: bigint, pendingGaps: readonly PendingGapEntry[]): Promise<Record<string, unknown> | undefined>;
 export declare function resetConsumerForMspRebuild(db: AnyDb, name: string, instanceId: string): Promise<void>;
 export declare function selectConsumerForUpdate(db: AnyDb, name: string, instanceId: string): Promise<Record<string, unknown> | undefined>;
 export declare function updateConsumerRebuildCursor(db: AnyDb, name: string, instanceId: string, lastProcessedEventId: bigint, pendingGaps: readonly PendingGapEntry[]): Promise<void>;

package/dist/db/queries/event-consumer.js

@@ -23,28 +23,46 @@ export async function lockEventConsumersShareMode(db) {
     await asRawClient(db).unsafe(`LOCK TABLE "kumiko_event_consumers" IN SHARE MODE`);
 }
 // The MAX(id) horizon plus every currently-open id gap below it, read from a
-// single snapshot (READ COMMITTED gives each statement its own). A gap can
-// only later fill in if some transaction holding a lower id was still
-// in-flight in that same snapshot — pg_snapshot_xip is empty otherwise, so
-// the gap CTEs short-circuit and the window scan over kumiko_events never
-// runs. Used both to seed startFrom "now" (#3231) and to seed an MSP
-// rebuild's handoff to the live dispatcher (msp-rebuild.ts).
+// single statement snapshot. Used both to seed startFrom "now" (#3231) and to
+// seed an MSP rebuild's handoff to the live dispatcher (msp-rebuild.ts).
+//
+// Scan lower bound: the consumer with the highest cursor already tracks every
+// open gap at or below that cursor in its own pending_gaps, so those are taken
+// over verbatim (keeping their xmax) and only ids above the cursor are scanned,
+// with the cursor itself as virtual predecessor. Without any consumer the
+// cursor is 0 and the scan covers the whole table. No bound derived from xmin or
+// id margins: ids and xids interleave, so such a bound cannot be proven safe.
+// Above the cursor a gap can only fill in if some transaction holding a lower id
+// is still in flight, which pg_snapshot_xip being empty rules out, so the window
+// scan is skipped then.
 export async function selectEventIdHorizonWithMissingRanges(db) {
-    const rows = (await asRawClient(db).unsafe(`WITH b AS (
-       SELECT COALESCE(MAX("id"), 0) AS horizon, MIN("id") AS min_id FROM "kumiko_events"
+    const rows = (await asRawClient(db).unsafe(`WITH a AS (
+       SELECT "last_processed_event_id" AS cursor, "pending_gaps" AS gaps
+         FROM "kumiko_event_consumers"
+        ORDER BY "last_processed_event_id" DESC
+        LIMIT 1
      ),
+     c AS (SELECT COALESCE((SELECT cursor FROM a), 0) AS v),
+     b AS (SELECT COALESCE(MAX("id"), 0) AS horizon FROM "kumiko_events"),
      r AS (
-       SELECT 1::bigint AS f, b.min_id - 1 AS t FROM b
-        WHERE b.min_id > 1 AND EXISTS (SELECT 1 FROM pg_snapshot_xip(pg_current_snapshot()))
+       SELECT (g ->> 'from')::bigint AS f, (g ->> 'to')::bigint AS t, g ->> 'xmax' AS x
+         FROM a,
+              jsonb_array_elements(CASE WHEN jsonb_typeof(a.gaps) = 'array' THEN a.gaps ELSE '[]'::jsonb END) AS g
+       UNION ALL
+       SELECT c.v + 1, m.min_id - 1, pg_snapshot_xmax(pg_current_snapshot())::text
+         FROM c,
+              (SELECT MIN(e."id") AS min_id FROM "kumiko_events" e WHERE e."id" > (SELECT v FROM c)) m
+        WHERE m.min_id > c.v + 1 AND EXISTS (SELECT 1 FROM pg_snapshot_xip(pg_current_snapshot()))
        UNION ALL
-       SELECT w."id" + 1, w.next_id - 1
-         FROM (SELECT "id", lead("id") OVER (ORDER BY "id") AS next_id FROM "kumiko_events") w
+       SELECT w."id" + 1, w.next_id - 1, pg_snapshot_xmax(pg_current_snapshot())::text
+         FROM (SELECT e."id", lead(e."id") OVER (ORDER BY e."id") AS next_id
+                 FROM "kumiko_events" e WHERE e."id" > (SELECT v FROM c)) w
         WHERE w.next_id > w."id" + 1 AND EXISTS (SELECT 1 FROM pg_snapshot_xip(pg_current_snapshot()))
      )
      SELECT b.horizon::text AS horizon,
-            pg_snapshot_xmax(pg_current_snapshot())::text AS xmax,
             r.f::text AS gap_from,
-            r.t::text AS gap_to
+            r.t::text AS gap_to,
+            r.x AS gap_xmax
        FROM b LEFT JOIN r ON true
       ORDER BY r.f`));
     const first = rows[0];
@@ -52,9 +70,9 @@ export async function selectEventIdHorizonWithMissingRanges(db) {
         throw new Error("selectEventIdHorizonWithMissingRanges: no row returned");
     const gaps = [];
     for (const row of rows) {
-        if (row.gap_from === null || row.gap_to === null)
+        if (row.gap_from === null || row.gap_to === null || row.gap_xmax === null)
             continue;
-        gaps.push({ from: row.gap_from, to: row.gap_to, xmax: row.xmax });
+        gaps.push({ from: row.gap_from, to: row.gap_to, xmax: row.gap_xmax });
     }
     return { horizon: BigInt(first.horizon), gaps };
 }
@@ -85,26 +103,6 @@ export async function insertConsumerIfAbsent(db, name, instanceId, startFrom = "
        ON CONFLICT ("name", "instance_id") DO NOTHING`, [name, instanceId]);
     }
 }
-// fw#2625: a consumer that moved from delivery: "per-instance" to "shared"
-// leaves its old per-instance rows behind — no dispatcher will ever advance
-// them again, and pruneEvents stays pinned to their stale cursor forever.
-// Scoped by name + "not the shared sentinel" so a still-per-instance
-// consumer's live rows (or an already-migrated __shared__ row) are never
-// touched.
-export async function deleteOrphanedPerInstanceConsumerRows(db, consumerNames, 
-// Passed in rather than imported from event-consumer-state.ts (which
-// defines SHARED_INSTANCE_SENTINEL): that module already imports from
-// this one for the DB queries it needs, so importing back would be a
-// require cycle. The one caller lives in that same file and has the
-// constant in scope.
-sharedInstanceSentinel) {
-    // skip: nothing to delete — an empty ANY($1) would still hit the table,
-    // pointlessly, on every boot for an app with no migrated consumers yet.
-    if (consumerNames.length === 0)
-        return;
-    await asRawClient(db).unsafe(`DELETE FROM "kumiko_event_consumers"
-     WHERE "name" = ANY($1) AND "instance_id" != $2`, [consumerNames, sharedInstanceSentinel]);
-}
 // Lock-free pre-check for doPass: which (name, instance_id) pairs are
 // provably idle — no locking, no xid, no WAL. A pair only qualifies when its
 // row exists, its status isn't dead (dead must still go through
@@ -115,7 +113,7 @@ sharedInstanceSentinel) {
 // `deadStatus` is passed in rather than imported as a value from
 // event-consumer-state.ts (which defines ConsumerStatuses) — that module
 // already imports from this one, so a value import back would be a require
-// cycle (same pattern as deleteOrphanedPerInstanceConsumerRows above). The
+// cycle. The
 // type-only import keeps the parameter pinned to the "dead" literal.
 export async function selectProvablyIdleConsumerPairs(db, names, instanceIds, deadStatus) {
     const rows = (await asRawClient(db).unsafe(`SELECT c."name" AS name, c."instance_id" AS instance_id
@@ -148,11 +146,24 @@ export async function markConsumerProcessing(db, name, instanceId) {
 // caller's console.error — status and the cursor are left as-is too, since
 // we don't know at this point whether the consumer should be "dead" (that's
 // the deliverEvents/maxAttempts contract, which never ran this pass).
-export async function recordConsumerPassFailure(db, name, instanceId, errorMessage) {
+//
+// Another replica sharing this (name, instance_id) may commit a successful
+// pass between the rollback and this write. `cursorBeforePass` pins the
+// write to the state the failed pass started from, so a stale error can't
+// overwrite that success; a row another pass currently holds is skipped
+// instead of blocking this catch path on its lock. Undefined when the pass
+// failed before it read the cursor.
+export async function recordConsumerPassFailure(db, name, instanceId, errorMessage, cursorBeforePass) {
     await asRawClient(db).unsafe(`UPDATE "kumiko_event_consumers" SET
        "last_error" = $1,
        "updated_at" = now()
-     WHERE "name" = $2 AND "instance_id" = $3`, [errorMessage, name, instanceId]);
+     WHERE "name" = $2 AND "instance_id" = $3
+       AND ($4::bigint IS NULL OR "last_processed_event_id" = $4::bigint)
+       AND ("name", "instance_id") IN (
+         SELECT "name", "instance_id" FROM "kumiko_event_consumers"
+         WHERE "name" = $2 AND "instance_id" = $3
+         FOR UPDATE SKIP LOCKED
+       )`, [errorMessage, name, instanceId, cursorBeforePass ?? null]);
 }
 export async function updateConsumerDeliveryOutcome(db, name, instanceId, outcome) {
     // Advancing the cursor proves this pass wasn't poison — reset the re-arm
@@ -189,8 +200,8 @@ export async function updateConsumerStatusReturning(db, name, instanceId, status
     return rows[0];
 }
 export async function advanceConsumerPastEventReturning(db, name, instanceId, eventId, 
-// Ids skipped over between the old cursor and eventId that were not visible yet.
-gapToAdd = null) {
+// Full list, including ids skipped over between the old cursor and eventId that were not visible yet.
+pendingGaps) {
     const rows = (await asRawClient(db).unsafe(`UPDATE "kumiko_event_consumers" SET
        "last_processed_event_id" = $1,
        "status" = 'idle',
@@ -199,10 +210,10 @@ gapToAdd = null) {
        "rearm_count" = 0,
        "last_failed_event_id" = NULL,
        -- text param + cast: a JS string bound straight to ::jsonb double-encodes under Bun.SQL
-       "pending_gaps" = CASE WHEN $4::text IS NULL THEN "pending_gaps" ELSE "pending_gaps" || $4::text::jsonb END,
+       "pending_gaps" = $4::text::jsonb,
        "updated_at" = now()
      WHERE "name" = $2 AND "instance_id" = $3
-     RETURNING *`, [eventId, name, instanceId, gapToAdd === null ? null : JSON.stringify([gapToAdd])]));
+     RETURNING *`, [eventId, name, instanceId, JSON.stringify(pendingGaps)]));
     return rows[0];
 }
 export async function resetConsumerForMspRebuild(db, name, instanceId) {

package/dist/db/queries/event-store.d.ts

@@ -1,8 +1,12 @@
+import type { DbRunner } from "@cosmicdrift/kumiko-types/db-connection";
 import type { AnyDb } from "../query.js";
 export declare function claimXactId(db: AnyDb): Promise<void>;
+export declare function runAtomicEventWrite<T>(db: DbRunner, write: (runner: DbRunner) => Promise<T>): Promise<T>;
 /** NOTIFY on commit — wakes LISTEN subscribers (event-dispatcher). */
 export declare function notifyPgChannel(db: AnyDb, channel: string): Promise<void>;
+export declare const MEMBERSHIP_PAYLOAD_TENANT_INDEX_NAME = "events_membership_payload_tenant_idx";
 export declare function ensureIdempotencyKeyIndex(db: AnyDb): Promise<void>;
+export declare function ensureMembershipPayloadTenantIndex(db: AnyDb): Promise<void>;
 export type SubsequentEventInsertParams = {
     readonly aggregateId: string;
     readonly aggregateType: string;

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

@@ -1,5 +1,5 @@
 import { constraintOf, isLockNotAvailable, isTableAlreadyExists, isUniqueViolation, } from "../pg-error.js";
-import { asRawClient, unsafeReadRetrying } from "../query.js";
+import { asRawClient, runInNewTransaction, unsafeReadRetrying } from "../query.js";
 // Gap-finality (event-dispatcher pending_gaps) needs every holder of an
 // event id to already have a *real* xact id by the time it inserts — Postgres
 // assigns those lazily on first write, so a bare INSERT alone doesn't
@@ -8,10 +8,25 @@ import { asRawClient, unsafeReadRetrying } from "../query.js";
 export async function claimXactId(db) {
     await asRawClient(db).unsafe(`SELECT pg_current_xact_id()`);
 }
+// Outside a transaction every statement commits on its own, so claim, insert and
+// notify would be three commits and the claimed xact id would be released before
+// the insert's. A pool runner (has begin()) therefore gets one transaction around
+// the whole write; inside a caller's tx or savepoint the caller's tx already is
+// that unit. Bun.SQL's TransactionSQL extends SQL and still exposes begin(), so
+// only a runner without savepoint() counts as a pool.
+export async function runAtomicEventWrite(db, write) {
+    const raw = asRawClient(db);
+    const isPool = typeof raw.begin === "function" && typeof raw.savepoint !== "function";
+    if (!isPool)
+        return write(db);
+    return runInNewTransaction(db, (tx) => write(tx));
+}
 /** NOTIFY on commit — wakes LISTEN subscribers (event-dispatcher). */
 export async function notifyPgChannel(db, channel) {
     await asRawClient(db).unsafe(`SELECT pg_notify($1, '')`, [channel]);
 }
+const IDEMPOTENCY_INDEX_NAME = "events_idempotency_uq";
+export const MEMBERSHIP_PAYLOAD_TENANT_INDEX_NAME = "events_membership_payload_tenant_idx";
 // Tenant-scoped partial unique index over metadata.idempotencyKey.
 // Expression index straight on the jsonb column — no dedicated key column,
 // so it needs no INSERT-path change and covers admin-api's raw appends too
@@ -30,9 +45,9 @@ export async function notifyPgChannel(db, channel) {
 // undefined = index doesn't exist at all (nothing to drop, CREATE below
 // handles it); false = exists but INVALID (crashed mid-build, needs DROP +
 // rebuild); true = exists and valid.
-async function indexValidity(client) {
+async function indexValidity(client, indexName = IDEMPOTENCY_INDEX_NAME) {
     const rows = await client.unsafe(`SELECT i.indisvalid FROM pg_class c JOIN pg_index i ON i.indexrelid = c.oid ` +
-        `WHERE c.relname = 'events_idempotency_uq' AND i.indrelid = '"kumiko_events"'::regclass`);
+        `WHERE c.relname = $1 AND i.indrelid = '"kumiko_events"'::regclass`, [indexName]);
     return rows[0]?.indisvalid;
 }
 export async function ensureIdempotencyKeyIndex(db) {
@@ -72,6 +87,28 @@ export async function ensureIdempotencyKeyIndex(db) {
         throw duplicateIdempotencyKeyErrorOr(e);
     }
 }
+// forget-cleanup reads the membership history by payload->>'tenantId' (not the
+// tenant_id column — cross-tenant SystemAdmin adds land under the actor's
+// tenant), which no other index covers: without this it scans every event.
+// Same CONCURRENTLY + INVALID-rebuild handling as the idempotency index.
+export async function ensureMembershipPayloadTenantIndex(db) {
+    const client = asRawClient(db);
+    try {
+        if ((await indexValidity(client, MEMBERSHIP_PAYLOAD_TENANT_INDEX_NAME)) === false) {
+            await client.unsafe(`DROP INDEX CONCURRENTLY IF EXISTS "${MEMBERSHIP_PAYLOAD_TENANT_INDEX_NAME}"`);
+        }
+        await client.unsafe(`CREATE INDEX CONCURRENTLY IF NOT EXISTS "${MEMBERSHIP_PAYLOAD_TENANT_INDEX_NAME}" ON "kumiko_events" ` +
+            `((("payload"->>'tenantId'))) WHERE "aggregate_type" = 'tenant-membership'`);
+    }
+    catch (e) {
+        if (isBenignConcurrentIndexBuildRace(e)) {
+            // skip: sibling pod already built a valid index — this race loser is done.
+            if ((await indexValidity(client, MEMBERSHIP_PAYLOAD_TENANT_INDEX_NAME)) === true)
+                return;
+        }
+        throw e;
+    }
+}
 // Two pods booting concurrently against the same DB (rolling deploy): both
 // see the index missing/invalid and both start a DROP/CREATE CONCURRENTLY
 // build. The loser typically does NOT get the plain duplicate-relation

package/dist/db/queries/pii-backfill-state.d.ts

@@ -2,6 +2,13 @@ import type { AnyDb } from "../query.js";
 export type PiiBackfillStateRow = {
     readonly cursor: string;
     readonly completed: boolean;
+    readonly failedEventIds: readonly string[];
 };
 export declare function readPiiBackfillState(db: AnyDb, fingerprint: string): Promise<PiiBackfillStateRow | null>;
-export declare function persistPiiBackfillState(db: AnyDb, fingerprint: string, cursor: bigint, markCompleted: boolean): Promise<void>;
+export type PiiBackfillStateUpdate = {
+    readonly cursor: bigint;
+    readonly markCompleted: boolean;
+    readonly addFailedEventIds: readonly string[];
+    readonly removeFailedEventIds: readonly string[];
+};
+export declare function persistPiiBackfillState(db: AnyDb, fingerprint: string, update: PiiBackfillStateUpdate): Promise<void>;

package/dist/db/queries/pii-backfill-state.js

@@ -1,14 +1,25 @@
 import { asRawClient } from "../query.js";
 export async function readPiiBackfillState(db, fingerprint) {
-    const rows = (await asRawClient(db).unsafe(`SELECT "cursor_event_id"::text AS "cursor", "completed_at" IS NOT NULL AS "completed"
+    const rows = (await asRawClient(db).unsafe(`SELECT "cursor_event_id"::text AS "cursor", "completed_at" IS NOT NULL AS "completed",
+            "failed_event_ids"::text[] AS "failedEventIds"
        FROM "kumiko_pii_backfill_state" WHERE "fingerprint" = $1`, [fingerprint]));
     return rows[0] ?? null;
 }
-export async function persistPiiBackfillState(db, fingerprint, cursor, markCompleted) {
-    await asRawClient(db).unsafe(`INSERT INTO "kumiko_pii_backfill_state" ("fingerprint", "cursor_event_id", "completed_at", "updated_at")
-     VALUES ($1, $2::bigint, CASE WHEN $3::boolean THEN now() ELSE NULL END, now())
+export async function persistPiiBackfillState(db, fingerprint, update) {
+    await asRawClient(db).unsafe(`INSERT INTO "kumiko_pii_backfill_state" ("fingerprint", "cursor_event_id", "completed_at", "failed_event_ids", "updated_at")
+     VALUES ($1, $2::bigint, CASE WHEN $3::boolean THEN now() ELSE NULL END, $4::bigint[], now())
      ON CONFLICT ("fingerprint") DO UPDATE SET
        "cursor_event_id" = GREATEST("kumiko_pii_backfill_state"."cursor_event_id", EXCLUDED."cursor_event_id"),
        "completed_at" = COALESCE("kumiko_pii_backfill_state"."completed_at", EXCLUDED."completed_at"),
-       "updated_at" = now()`, [fingerprint, cursor.toString(), markCompleted]);
+       "failed_event_ids" = ARRAY(
+         SELECT DISTINCT failed FROM unnest("kumiko_pii_backfill_state"."failed_event_ids" || EXCLUDED."failed_event_ids") AS failed
+          WHERE failed <> ALL($5::bigint[])
+          ORDER BY failed),
+       "updated_at" = now()`, [
+        fingerprint,
+        update.cursor.toString(),
+        update.markCompleted,
+        [...update.addFailedEventIds],
+        [...update.removeFailedEventIds],
+    ]);
 }

package/dist/db/queries/shadow-swap.js

@@ -266,21 +266,50 @@ export async function assertNoUnreachableLiveRows(tx, projectionName, tableName,
         `derived from the source event declare \`rowIdOf\` on r.extendEntityProjection. See ` +
         `docs/reference/entity-write-patterns.md. Rebuild aborted; live table untouched.`);
 }
+// A key is configured, but not necessarily the one the live bidx values were
+// computed with (typo'd secret, key rotated in only one of migrate-db / app).
+// The replay would then rewrite every bidx column with the wrong key and the
+// swap would succeed without any error. A NULL on either side is skipped: GDPR
+// shredding legitimately nulls a bidx, and a plaintext-era row has none yet.
+async function assertBlindIndexKeyMatchesLive(raw, tableName, quotedTable, bidxCols, projectionName) {
+    const differs = bidxCols
+        .map((c) => {
+        const col = quoteTableIdent(c.name);
+        return `(l.${col} IS NOT NULL AND s.${col} IS NOT NULL AND l.${col} IS DISTINCT FROM s.${col})`;
+    })
+        .join(" OR ");
+    const rows = await raw.unsafe(`SELECT count(*)::text AS total
+       FROM public.${quotedTable} l
+       JOIN ${SCHEMA_IDENT}.${quotedTable} s ON s."id" = l."id"
+      WHERE ${differs}`);
+    const count = Number(rows[0]?.total ?? "0");
+    // skip: every comparable bidx value matches the replay — same key as the live data
+    if (count === 0)
+        return;
+    throw new Error(`projection-rebuild "${projectionName}": "${tableName}" has ${count} row(s) whose blind-index ` +
+        `value differs from the replayed one. The KUMIKO_BLIND_INDEX_KEY in this process is not the ` +
+        `key those values were computed with, so the swap would break equality lookups on that ` +
+        `field (login, password reset) without any error. Use the same KUMIKO_BLIND_INDEX_KEY as ` +
+        `the running app in the process running this apply/rebuild. Rebuild aborted; live table ` +
+        `untouched.`);
+}
 // The bidx column is schema-driven, not key-driven: it exists NULL in a
 // plaintext install and in the fw#1610 case (KMS configured, no index key),
 // both of which are correct as-is. Only a POPULATED column with no key
 // configured in THIS process means the rebuild is about to overwrite proof
 // of a real index with NULL — that's the one provable data-loss case.
 export async function assertNoBlindIndexLoss(tx, tableName, meta, projectionName) {
-    // skip: a key is configured — the replay recomputes every bidx column with it
-    if (configuredBlindIndexKey() !== undefined)
-        return;
     const bidxCols = meta.columns.filter((c) => c.name.endsWith("_bidx"));
     // skip: no blind-index column on this table — nothing the rebuild could lose
     if (bidxCols.length === 0)
         return;
     const t = quoteTableIdent(tableName);
     const raw = asRawClient(tx);
+    if (configuredBlindIndexKey() !== undefined) {
+        await assertBlindIndexKeyMatchesLive(raw, tableName, t, bidxCols, projectionName);
+        // skip: a configured key is verified against live rows above, the null-count check below is for keyless boots
+        return;
+    }
     const where = bidxCols.map((c) => `${quoteTableIdent(c.name)} IS NOT NULL`).join(" OR ");
     const rows = await raw.unsafe(`SELECT count(*)::text AS total FROM public.${t} WHERE ${where}`);
     const count = Number(rows[0]?.total ?? "0");

package/dist/db/render-ddl.js

@@ -1,11 +1,11 @@
 // Pure renderer: EntityTableMeta → SQL DDL statements.
-// Wird vom Migrate-Generator (Phase 2 — CLI-Tool `kumiko migrate generate`)
-// genutzt um initial-SQL-Files zu schreiben. Output ist Start-Form für
-// User-Review — App-Author darf das SQL danach hand-editieren (extra-Index,
-// partial-Index, BRIN, custom-clauses) bevor committed wird.
+// The migrate generator (`kumiko-schema generate`) uses it to write the
+// initial SQL files. The output is a starting point for review: the app
+// author may hand-edit the SQL (extra index, partial index, BRIN, custom
+// clauses) before committing it.
 //
-// NO-MAGIC-ON-DATA: dieser Renderer wird NIE zur App-Runtime aufgerufen.
-// Nur Build-Step. Runner liest checked-in SQL, nicht Renderer-Output.
+// NO-MAGIC-ON-DATA: this renderer never runs at app runtime, only as a build
+// step. The runner reads the checked-in SQL, not renderer output.
 import { pgTypeToSqlType } from "./dialect.js";
 function quoteIdent(name) {
     return `"${name.replace(/"/g, '""')}"`;

package/dist/db/table-builder.js

@@ -253,17 +253,17 @@ const ROW_META_WITH_SOFT_DELETE = new Set(Object.keys(buildBaseColumns(true)));
 export function rowMetaFieldNames(softDelete) {
     return softDelete ? ROW_META_WITH_SOFT_DELETE : ROW_META_BASE;
 }
-function stampGlobalTenancyMeta(table, entity) {
-    // skip: non-global entities keep pgTable's default tenancy meta
-    if (entity.tenancy !== "global")
-        return;
+// pgTable's own meta stamp sees neither entity.tenancy nor that this table is an executor-managed projection;
+// patch both so db.global()'s runtime guards match the type brands.
+function stampEntityTableMeta(table, entity) {
     const meta = table[KUMIKO_META_SYMBOL];
     // skip: no meta stamp present — nothing to patch
     if (!meta)
         return;
     table[KUMIKO_META_SYMBOL] = {
         ...meta,
-        tenancy: "global",
+        source: "managed",
+        ...(entity.tenancy === "global" && { tenancy: "global" }),
     };
 }
 /**
@@ -416,7 +416,6 @@ export function buildEntityTable(entityName, entity, options) {
         }
         return indexes;
     });
-    // pgTable's own meta stamp doesn't see entity.tenancy — patch it so db.global()'s runtime guard matches the type brand.
-    stampGlobalTenancyMeta(built, entity);
+    stampEntityTableMeta(built, entity);
     return built;
 }

package/dist/db/tenant-db.d.ts

@@ -1,5 +1,5 @@
 import type { EntityTableMeta } from "@cosmicdrift/kumiko-types/entity-table-meta-types";
-import type { EscapeHatchDeclaration, EscapeHatchReporter } from "@cosmicdrift/kumiko-types/handlers";
+import type { EscapeHatchDeclaration, EscapeHatchReporter, EscapeHatchTarget } from "@cosmicdrift/kumiko-types/handlers";
 import { type SchemaTable } from "@cosmicdrift/kumiko-types/schema-table-types";
 import { type TenantDb, type TenantDbMode, type UncheckedSystemDb } from "@cosmicdrift/kumiko-types/tenant-db-types";
 import { asRawClient } from "../db/query.js";
@@ -28,7 +28,10 @@ export type TenantDbGrants = {
 };
 export type PersonalDataGate = (tableName: string, keys: readonly string[], entity?: EntityDefinition) => void;
 export declare function withUnsafeRawGrant(tenantDb: TenantDb, grant: EscapeHatchDeclaration | undefined): TenantDb;
-export declare function acknowledgeConventionCrossTenant(tenantDb: TenantDb, reason: string): TenantDb;
+export declare function acknowledgeConventionCrossTenant(tenantDb: TenantDb, reason: string, options?: {
+    readonly deferReport?: boolean;
+}): TenantDb;
+export declare function reportConventionCrossTenantUse(acknowledged: TenantDb, target?: EscapeHatchTarget): void;
 export declare function runInOwnTransaction<T>(tenantDb: TenantDb, fn: (txDb: TenantDb) => Promise<T>): Promise<T>;
 export declare function createTenantDb(db: DbRunner, tenantId: TenantId, mode?: TenantDbMode, tracer?: Tracer, meter?: Meter, signal?: AbortSignal, grants?: TenantDbGrants): TenantDb;
 export { asRawClient };