@cosmicdrift/kumiko-framework 0.367.0 → 0.368.0

package/dist/{stack/table-helpers.d.ts → db/table-push.d.ts}

@@ -1,13 +1,13 @@
-import type { DbConnection } from "../db/connection.js";
-import type { ColumnMeta, EntityTableMeta, IndexMeta } from "../db/entity-table-meta.js";
-import type { EventDispatcher } from "../pipeline/index.js";
+import type { EntityDefinition } from "../engine/types/index.js";
+import type { DbConnection } from "./connection.js";
+import type { ColumnMeta, EntityTableMeta, IndexMeta } from "./entity-table-meta.js";
 /**
  * Bypass: creates an entity-table directly without going through the
  * full registry. Reserved for framework-internal meta-tables and
  * test setup — apps declare data via `r.entity(...)`.
  */
-export declare function unsafeCreateEntityTable(db: DbConnection, entity: import("../engine/types/index.js").EntityDefinition, entityName?: string): Promise<void>;
-export declare function unsafeEnsureEntityTable(db: DbConnection, entity: import("../engine/types/index.js").EntityDefinition, entityName?: string): Promise<boolean>;
+export declare function unsafeCreateEntityTable(db: DbConnection, entity: EntityDefinition, entityName?: string): Promise<void>;
+export declare function unsafeEnsureEntityTable(db: DbConnection, entity: EntityDefinition, entityName?: string): Promise<boolean>;
 export declare function tableToMeta(table: unknown): EntityTableMeta;
 /** Applies ALTER TABLE ADD COLUMN for exactly the given columns. */
 export declare function addMissingColumns(db: DbConnection, tableName: string, columns: readonly ColumnMeta[]): Promise<void>;
@@ -22,13 +22,3 @@ export declare function addMissingIndexes(db: DbConnection, tableName: string, i
  * entities go through `kumiko schema apply` (committed SQL files).
  */
 export declare function unsafePushTables(db: DbConnection, tables: Record<string, unknown>, prevTables?: Record<string, unknown>): Promise<void>;
-/**
- * Wipes event store + framework-state + the given feature read-models in
- * one TRUNCATE, then re-registers the event-consumer state rows. Used in
- * test beforeEach-hooks to return the stack to a clean slate without
- * rebuilding it.
- */
-export declare function resetEventStore(stack: {
-    db: unknown;
-    eventDispatcher?: EventDispatcher;
-}, extraTables?: readonly (unknown | string)[]): Promise<void>;

package/dist/{stack/table-helpers.js → db/table-push.js}

@@ -1,21 +1,9 @@
-import { pgTypeToSqlType } from "../db/dialect.js";
-import { alterTableAddColumn, createIndexIfNotExists, executeDdlStatement, } from "../db/queries/ddl.js";
-import { truncateTablesRestartIdentity } from "../db/queries/test-stack.js";
-import { renderTableDdl } from "../db/render-ddl.js";
-import { tableExists } from "../db/schema-inspection.js";
-import { buildEntityTable, toTableName } from "../db/table-builder.js";
-import { asEntityTableMeta, schemaTableName } from "../db/table-introspection.js";
-function tableNameOf(table) {
-    if (typeof table !== "object" || table === null) {
-        throw new Error("table-helpers: table is not a SchemaTable object");
-    }
-    const symbolName = schemaTableName(table);
-    if (symbolName !== undefined)
-        return symbolName;
-    if ("tableName" in table && typeof table.tableName === "string")
-        return table.tableName;
-    throw new Error("table-helpers: table has no name");
-}
+import { pgTypeToSqlType } from "./dialect.js";
+import { alterTableAddColumn, createIndexIfNotExists, executeDdlStatement } from "./queries/ddl.js";
+import { renderTableDdl } from "./render-ddl.js";
+import { tableExists } from "./schema-inspection.js";
+import { buildEntityTable, toTableName } from "./table-builder.js";
+import { asEntityTableMeta } from "./table-introspection.js";
 /**
  * Bypass: creates an entity-table directly without going through the
  * full registry. Reserved for framework-internal meta-tables and
@@ -96,31 +84,3 @@ export async function unsafePushTables(db, tables, prevTables) {
 function renderColumnType(col) {
     return pgTypeToSqlType(col.pgType);
 }
-/**
- * Wipes event store + framework-state + the given feature read-models in
- * one TRUNCATE, then re-registers the event-consumer state rows. Used in
- * test beforeEach-hooks to return the stack to a clean slate without
- * rebuilding it.
- */
-export async function resetEventStore(stack, extraTables = []) {
-    const frameworkTables = [
-        "kumiko_events",
-        "kumiko_event_consumers",
-        "kumiko_archived_streams",
-        "kumiko_snapshots",
-        "kumiko_projections",
-    ];
-    const extraNames = extraTables.map((t) => (typeof t === "string" ? t : tableNameOf(t)));
-    const truncateAndReregister = async () => {
-        await truncateTablesRestartIdentity(stack.db, [...frameworkTables, ...extraNames]);
-        await stack.eventDispatcher?.ensureRegistered();
-    };
-    // The dispatcher's own timer/LISTEN must not start a pass between the
-    // TRUNCATE and the consumer re-registration, so they are paused for the whole reset.
-    if (stack.eventDispatcher) {
-        await stack.eventDispatcher.withBackgroundPassesPaused(truncateAndReregister);
-    }
-    else {
-        await truncateAndReregister();
-    }
-}

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

@@ -37,6 +37,17 @@ export declare function acknowledgeConventionCrossTenant(tenantDb: TenantDb, rea
 }): 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 type CreateTenantDbOptions = {
+    readonly db: DbRunner;
+    readonly tenantId: TenantId;
+    readonly mode?: TenantDbMode;
+    readonly tracer?: Tracer;
+    readonly meter?: Meter;
+    readonly signal?: AbortSignal;
+    readonly grants?: TenantDbGrants;
+};
+export declare function createTenantDb(options: CreateTenantDbOptions): TenantDb;
+/** @deprecated Positional form, use createTenantDb({ db, tenantId, ... }). Run `bun kumiko-upgrade --apply` to rewrite call sites. Removed in the first release after 2026-10-29. */
 export declare function createTenantDb(db: DbRunner, tenantId: TenantId, mode?: TenantDbMode, tracer?: Tracer, meter?: Meter, signal?: AbortSignal, grants?: TenantDbGrants): TenantDb;
 export declare function createProjectingTenantDb(db: DbRunner, tenantId: TenantId, projectionRegistry: Registry | undefined): TenantDb;
 export { asRawClient };

package/dist/db/tenant-db.js

@@ -225,7 +225,7 @@ export function createSystemDbView(db, dbOutsideTransaction, report = fallbackEs
 // same connection/transaction. For code that must run caller-supplied callbacks (e.g. config
 // validators) without handing them a cross-tenant view.
 export function scopeTenantDbToTenant(db, tenantId) {
-    return createTenantDb(tenantDbRunner(db), tenantId, "tenant");
+    return createTenantDb({ db: tenantDbRunner(db), tenantId, mode: "tenant" });
 }
 // @cast-boundary tenant-db-row
 export function castTenantRows(rows) {
@@ -311,7 +311,26 @@ export async function runInOwnTransaction(tenantDb, fn) {
     }
     return rebind(fn);
 }
-export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, signal, grants) {
+// Runners (postgres-js Sql/tx handles) are functions and RawDbClient mocks carry no own
+// `tenantId`/`db`, so a runner is never mistaken for the options object.
+function isCreateTenantDbOptions(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        Object.hasOwn(value, "tenantId") &&
+        Object.hasOwn(value, "db"));
+}
+export function createTenantDb(dbOrOptions, tenantId, mode, tracer, meter, signal, grants) {
+    if (isCreateTenantDbOptions(dbOrOptions))
+        return buildTenantDb(dbOrOptions);
+    return buildTenantDb({ db: dbOrOptions, tenantId, mode, tracer, meter, signal, grants });
+}
+// Untyped JS callers or an `as` cast can still hand in undefined; a scoped handle
+// without a tenant would bind `tenant_id = NULL` instead of failing loudly.
+function buildTenantDb(options) {
+    const { db, tenantId, mode = "tenant", tracer, meter, signal, grants } = options;
+    if (tenantId === undefined) {
+        throw new InternalError({ message: "createTenantDb: tenantId is required" });
+    }
     if (meter)
         registerStandardMetrics(meter);
     const report = grants?.report ?? fallbackEscapeHatchReporter(tenantId);
@@ -585,16 +604,32 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
         },
     };
     declaredUnsafeRawRunners.set(tenantDb, grantedUnsafeRawRunner);
-    unsafeRawRebinders.set(tenantDb, (grant) => createTenantDb(db, tenantId, mode, tracer, meter, signal, {
-        ...rebindGrants,
-        unsafeRaw: grant,
-        // db.global() writes are write-handler-only: a rebind (a hook's own grant) must not inherit them.
-        globalWrites: undefined,
+    unsafeRawRebinders.set(tenantDb, (grant) => createTenantDb({
+        db,
+        tenantId,
+        mode,
+        tracer,
+        meter,
+        signal,
+        grants: {
+            ...rebindGrants,
+            unsafeRaw: grant,
+            // db.global() writes are write-handler-only: a rebind (a hook's own grant) must not inherit them.
+            globalWrites: undefined,
+        },
     }));
     crossTenantRebinders.set(tenantDb, (reason, deferReport) => {
         if (!deferReport)
             report("acknowledge-cross-tenant", reason);
-        const acknowledged = createTenantDb(db, tenantId, "system", tracer, meter, signal, rebindGrants);
+        const acknowledged = createTenantDb({
+            db,
+            tenantId,
+            mode: "system",
+            tracer,
+            meter,
+            signal,
+            grants: rebindGrants,
+        });
         crossTenantUseReporters.set(acknowledged, (target) => report("acknowledge-cross-tenant", reason, target));
         return acknowledged;
     });
@@ -607,7 +642,7 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
         }
         // Carries a runner-bound gate (grants.personalDataGate unset, resolved via the fallback above) forward explicitly, since the fresh tx-handle isn't itself registered in runnerPersonalDataGates.
         const txGrants = personalDataGate ? { ...rebindGrants, personalDataGate } : rebindGrants;
-        return runInNewTransaction(db, (tx) => fn(createTenantDb(tx, tenantId, mode, tracer, meter, signal, txGrants)));
+        return runInNewTransaction(db, (tx) => fn(createTenantDb({ db: tx, tenantId, mode, tracer, meter, signal, grants: txGrants })));
     });
     bindTenantDbRunner(tenantDb, db);
     if (grants?.writesDeniedReason !== undefined) {
@@ -619,9 +654,13 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
         bindProjectionRegistry(tenantDb, projectionRegistry);
     return tenantDb;
 }
-// Tenant-mode TenantDb whose writes reach the registry's custom projections. The positional
-// undefineds of createTenantDb would hide a moved grants parameter from the type checker.
+// Tenant-mode TenantDb whose writes reach the registry's custom projections.
 export function createProjectingTenantDb(db, tenantId, projectionRegistry) {
-    return createTenantDb(db, tenantId, "tenant", undefined, undefined, undefined, projectionRegistry ? { projectionRegistry } : undefined);
+    return createTenantDb({
+        db,
+        tenantId,
+        mode: "tenant",
+        grants: projectionRegistry ? { projectionRegistry } : undefined,
+    });
 }
 export { asRawClient };

package/dist/derivatives/derivatives-context.d.ts

@@ -1,5 +1,5 @@
 import type { DerivativeRendererPlugin, DerivativesContext } from "@cosmicdrift/kumiko-types/derivatives-types";
-import { type AnyDb } from "../bun-db/query.js";
+import { type AnyDb } from "../db/query.js";
 import type { Registry, TenantId } from "../engine/types/index.js";
 import type { FileContext } from "../files/file-handle.js";
 export type DerivativesContextDeps = {

package/dist/derivatives/derivatives-context.js

@@ -1,4 +1,4 @@
-import { fetchOne } from "../bun-db/query.js";
+import { fetchOne } from "../db/query.js";
 import { EXT_DERIVATIVE_OVERLAY_RESOLVER, EXT_DERIVATIVE_RENDERER, } from "../engine/extension-names.js";
 import { InternalError, NotFoundError } from "../errors/index.js";
 import { fileRefsTable } from "../files/file-ref-table.js";

package/dist/engine/boot-validator/gdpr-storage.js

@@ -1,7 +1,7 @@
 // Providers whose bytes do not survive a process restart. Only "inmemory"
 // today; extend if another ephemeral bundled provider lands.
 const EPHEMERAL_PROVIDERS = new Set(["inmemory"]);
-// Env vars file-provider-s3-env reads (see files-provider-s3/env-helper).
+// Env vars createFileProviderS3Feature({ fromEnv: true }) reads (see file-provider-s3/lib/env-helper).
 // Missing any → createS3ProviderFromEnv throws on the first file op.
 const S3_ENV_REQUIRED = ["S3_BUCKET", "S3_REGION", "S3_ACCESS_KEY", "S3_SECRET_KEY"];
 // Cross-feature GDPR storage guard (V1). Catches the failure class we shipped
@@ -31,7 +31,7 @@ export function validateGdprStoragePersistence(features) {
     const persistent = [...registeredProviders].filter((p) => !EPHEMERAL_PROVIDERS.has(p));
     if (persistent.length === 0) {
         // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
-        console.warn("[kumiko:boot] user-data-rights is mounted but no persistent file provider is — GDPR exports use an ephemeral/in-memory store and are LOST on restart (the download then 500s). Mount file-provider-s3 or file-provider-s3-env and select it via the file-foundation provider config.");
+        console.warn("[kumiko:boot] user-data-rights is mounted but no persistent file provider is — GDPR exports use an ephemeral/in-memory store and are LOST on restart (the download then 500s). Mount createFileProviderS3Feature() or createFileProviderS3Feature({ fromEnv: true }) and select it via the file-foundation provider config.");
         // skip: ephemeral store already warned; the s3-env env-var check below is moot
         return;
     }
@@ -42,7 +42,7 @@ export function validateGdprStoragePersistence(features) {
         const missing = S3_ENV_REQUIRED.filter((v) => !process.env[v]);
         if (missing.length > 0) {
             // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
-            console.warn(`[kumiko:boot] file-provider-s3-env is the GDPR file store but these env vars are unset: ${missing.join(", ")}. The provider throws on the first export (inside the cron), not here — set them so GDPR storage works.`);
+            console.warn(`[kumiko:boot] createFileProviderS3Feature({ fromEnv: true }) (provider "s3-env") is the GDPR file store but these env vars are unset: ${missing.join(", ")}. The provider throws on the first export (inside the cron), not here — set them so GDPR storage works.`);
         }
     }
 }

package/dist/engine/boot-validator/pii-retention.js

@@ -204,11 +204,11 @@ export function validatePiiAndRetention(feature) {
                     throw new Error(`[Feature ${feature.name}] personal.of "${ownerName}" on entity "${entityName}" must be a reference or text (userId) field, got type "${ownerField.type}"`);
                 }
                 const { whenAbsent } = annot.userOwned;
-                if (whenAbsent !== undefined && whenAbsent !== "tenant") {
-                    throw new Error(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" declares personal.whenAbsent "${String(whenAbsent)}" — entity fields only support whenAbsent: "tenant" (no plaintext fallback for stored PII). Remove whenAbsent or set it to "tenant".`);
+                if (whenAbsent !== undefined && whenAbsent !== "tenant" && whenAbsent !== "self") {
+                    throw new Error(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" declares personal.whenAbsent "${String(whenAbsent)}" — entity fields only support whenAbsent: "tenant" or "self" (no plaintext fallback for stored PII). Remove whenAbsent or set it to "tenant" (tenant key) or "self" (the row's own record key).`);
                 }
                 if (ownerField.required !== true && whenAbsent === undefined) {
-                    throw new Error(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" is personal: { of: "${ownerName}" }, but "${ownerName}" is not required — rows without an owner would fail to encrypt (SubjectResolutionError, HTTP 500) on update, delete and forget. Declare { personal: { of: "${ownerName}", whenAbsent: "tenant" } } to encrypt those rows under the tenant key, or make "${ownerName}" required: true. Entity fields have no plaintext fallback (fw#3654).`);
+                    throw new Error(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" is personal: { of: "${ownerName}" }, but "${ownerName}" is not required — rows without an owner would fail to encrypt (SubjectResolutionError, HTTP 500) on update, delete and forget. Declare { personal: { of: "${ownerName}", whenAbsent: "tenant" } } to encrypt those rows under the tenant key, whenAbsent: "self" to encrypt them under the row's own record key (shreddable per record), or make "${ownerName}" required: true. Entity fields have no plaintext fallback (fw#3654).`);
                 }
                 // Soft-Warning wenn das reference-target nicht offensichtlich user
                 // ist — custom subject-entities (HR-Mitarbeiter, Patient) sind

package/dist/engine/boot-validator/record-owned.js

@@ -1,4 +1,4 @@
-// A recordOwned field is encrypted under `record:<entity>:<id>` (kms-adapter-types.ts)
+// A recordOwned field (or one with whenAbsent: "self") is encrypted under `record:<entity>:<id>` (kms-adapter-types.ts)
 // and forgetSubject's subjectIdSchema (crypto/kms-adapter.ts) requires that id
 // to be a UUID — an entity with idType: "serial" would encrypt the field but
 // could never satisfy a forget-subject request for it.
@@ -8,9 +8,9 @@ export function validateRecordOwnedSubjects(feature) {
             continue;
         for (const [fieldName, field] of Object.entries(entity.fields)) {
             const annot = field; // @cast-boundary schema-walk
-            if (annot.recordOwned !== true)
+            if (annot.recordOwned !== true && annot.userOwned?.whenAbsent !== "self")
                 continue;
-            throw new Error(`[Feature ${feature.name}] entity "${entityName}" field "${fieldName}" is recordOwned but the entity declares idType: "serial" — the record subject key is "record:${entityName}:<id>" and forgetSubject validates that id as a UUID, so this field would be encrypted but could never be shredded. Set idType: "uuid" on entity "${entityName}", or give field "${fieldName}" a different personal stance (personal: "self" / "tenant" / { of: "<field>" }).`);
+            throw new Error(`[Feature ${feature.name}] entity "${entityName}" field "${fieldName}" is recordOwned (or whenAbsent: "self") but the entity declares idType: "serial" — the record subject key is "record:${entityName}:<id>" and forgetSubject validates that id as a UUID, so this field would be encrypted but could never be shredded. Set idType: "uuid" on entity "${entityName}", or give field "${fieldName}" a different personal stance (personal: "self" / "tenant" / { of: "<field>" }).`);
         }
     }
 }

package/dist/engine/boot-validator/screens.js

@@ -7,6 +7,7 @@ import { resolveActionIcon } from "@cosmicdrift/kumiko-types/action-icon";
 import { NO_WIDGET_FIELD_TYPES, optionsQueryFieldRefs, SELECT_OPTION_TONES, } from "@cosmicdrift/kumiko-types/fields";
 import { NAV_ICON_KEYS } from "@cosmicdrift/kumiko-types/nav-icon";
 import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
+import { isListFilterAllowed } from "../../db/entity-field-encryption.js";
 import { rowMetaFieldNames } from "../../db/table-builder.js";
 import { REFERENCE_LOOKUP_SOURCES } from "../../ui-types/list-row-meta.js";
 import { isEncryptedAtRest } from "../config-helpers.js";
@@ -230,7 +231,7 @@ function validateWizardLayout(featureName, screenId, screenType, layout, feature
         if (!featureMap.has("form-draft")) {
             throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) sets draft: true but the ` +
                 `bundled feature "form-draft" is not mounted — every resume would silently lose its ` +
-                `values. Add formDraftFeature() from @cosmicdrift/kumiko-bundled-features to the app's ` +
+                `values. Add createFormDraftFeature() from @cosmicdrift/kumiko-bundled-features to the app's ` +
                 `feature list.`);
         }
     }
@@ -1641,6 +1642,12 @@ export function validateScreens(feature, featureMap, allWriteHandlerQns, allScre
                     throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (entityList) filter references unknown ` +
                         `field "${filterField}". Known fields: ${[...fieldNames].sort().join(", ")}`);
                 }
+                if (!isListFilterAllowed(entityDef, filterField, screen.filter)) {
+                    throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (entityList) filter references field ` +
+                        `"${filterField}" which is encrypted, personal or secret, so the list handler rejects ` +
+                        `this filter at runtime. Only op "eq" works on a personal field with find: "exact" or ` +
+                        `"fuzzy"; otherwise drop the filter or filter on another field.`);
+                }
                 const fieldDef = entityDef.fields[filterField];
                 if (fieldDef !== undefined && !isFieldFilterable(fieldDef)) {
                     throw new Error(`[Feature ${feature.name}] Screen "${screenId}" (entityList) filter references field ` +

package/dist/engine/bridge-stub.d.ts

@@ -0,0 +1,4 @@
+import type { HandlerContext, SessionUser } from "./types/index.js";
+export declare function bridgeStub(opts?: {
+    readonly user?: SessionUser;
+}): Pick<HandlerContext, "query" | "queryAs" | "write" | "writeAs" | "appendEvent" | "unsafeAppendEvent" | "tryAppendEvent" | "fetchForWriting" | "loadAggregate" | "archiveStream" | "restoreStream" | "isStreamArchived" | "snapshotAggregate" | "loadAggregateWithSnapshot" | "queryProjection" | "resolveAuthClaims" | "resolveActiveMembership" | "queryAsMember" | "hasFeature" | "metrics" | "metricsFor" | "tracer" | "tz" | "locale" | "user">;

package/dist/engine/bridge-stub.js

@@ -0,0 +1,62 @@
+import { DEFAULT_LOCALE } from "../i18n/request-locale.js";
+import { createNoopMetricsHandle, getFallbackTracer } from "../observability/index.js";
+import { createTzContext } from "../time/index.js";
+import { createAnonymousUser } from "./system-user.js";
+// Test/service helper: cross-feature bridge methods that throw on use.
+//
+// Production code always receives a full HandlerContext from the Dispatcher's
+// buildHandlerContext (with real query/write closures). Some internal services
+// and tests construct a mini-context manually (typically just `{ db, registry }`)
+// to invoke a single handler. Those call sites don't use ctx.query/write —
+// the stubs make the TypeScript shape match while still failing loudly if
+// anything downstream accidentally reaches for them.
+//
+// Use: `{ db, registry, ...bridgeStub() }`
+const notAvailable = (what) => async () => {
+    throw new Error(`ctx.${what} not available in this context — use the dispatcher, not a stubbed handler context`);
+};
+// Noop observability — hand back the shared fallback tracer so ctx.tracer has
+// a valid Tracer shape. No allocations per call.
+const noopTracer = getFallbackTracer();
+export function bridgeStub(opts) {
+    // ctx.user is a convenience alias for event.user (see HandlerContext
+    // docs). Caller code expects the field; bridgeStub hands back a stub with
+    // anonymous default values when no user is passed explicitly. Test code
+    // that cares about identity passes its own SessionUser here and gets it
+    // back on ctx.
+    const stubUser = opts?.user ??
+        createAnonymousUser("00000000-0000-0000-0000-000000000000"); // @cast-boundary engine-bridge
+    return {
+        user: stubUser,
+        query: notAvailable("query"), // @cast-boundary engine-bridge
+        queryAs: notAvailable("queryAs"),
+        write: notAvailable("write"),
+        writeAs: notAvailable("writeAs"),
+        appendEvent: notAvailable("appendEvent"),
+        unsafeAppendEvent: notAvailable("unsafeAppendEvent"),
+        tryAppendEvent: notAvailable("tryAppendEvent"),
+        fetchForWriting: notAvailable("fetchForWriting"),
+        loadAggregate: notAvailable("loadAggregate"),
+        archiveStream: notAvailable("archiveStream"),
+        restoreStream: notAvailable("restoreStream"),
+        isStreamArchived: notAvailable("isStreamArchived"),
+        snapshotAggregate: notAvailable("snapshotAggregate"),
+        loadAggregateWithSnapshot: notAvailable("loadAggregateWithSnapshot"),
+        queryProjection: notAvailable("queryProjection"),
+        resolveAuthClaims: notAvailable("resolveAuthClaims"),
+        resolveActiveMembership: notAvailable("resolveActiveMembership"),
+        queryAsMember: notAvailable("queryAsMember"),
+        // Stub defaults to always-enabled — matches the dispatcher's behaviour
+        // when no effectiveFeatures resolver is wired (tests without toggles).
+        hasFeature: async () => true,
+        metrics: createNoopMetricsHandle(),
+        metricsFor: () => createNoopMetricsHandle(),
+        tracer: noopTracer,
+        // Real TzContext, not notAvailable — test code uses ctx.tz routinely,
+        // it isn't a "bridge" concept. Defaults to UTC.
+        tz: createTzContext(),
+        // Same reasoning as tz above — ctx.locale is always-present, not a
+        // bridge method. Defaults to DEFAULT_LOCALE.
+        locale: DEFAULT_LOCALE,
+    };
+}

package/dist/engine/event-helpers.d.ts

@@ -1,9 +1,10 @@
-import type { EventDef, HandlerContext } from "./types/handlers.js";
+import type { AppendEventArgs, EventDef, HandlerContext } from "./types/handlers.js";
 export type EmitCtx = Pick<HandlerContext, "unsafeAppendEvent">;
 export declare function emitEvent<TPayload>(ctx: EmitCtx, eventDef: EventDef<TPayload>, args: {
     readonly aggregateId: string;
     readonly aggregateType: string;
     readonly payload: TPayload;
+    readonly headers?: AppendEventArgs["headers"];
 }): Promise<void>;
 export declare function typedPayload<TPayload>(event: {
     readonly type: string;

package/dist/engine/event-helpers.js

@@ -21,6 +21,7 @@ export async function emitEvent(ctx, eventDef, args) {
         aggregateType: args.aggregateType,
         type: eventDef.name,
         payload: args.payload,
+        ...(args.headers !== undefined && { headers: args.headers }),
     };
     await ctx.unsafeAppendEvent(appendArgs);
 }

package/dist/engine/feature-config-events-jobs.js

@@ -40,12 +40,12 @@ function assertOwnerFieldYieldsPresentString(args) {
     const { featureName, eventName, field, ownerField, owner } = args;
     if (neverYieldsString(owner)) {
         throw new Error(`[Feature ${featureName}] defineEvent("${eventName}"): piiFields."${field}" is owned by "${ownerField}", whose payload schema is not a string — the subject id must be a non-empty string, so every append would fail. ` +
-            `Use a string owner field, or declare whenAbsent ("tenant" | "plaintext").`);
+            `Use a string owner field, or declare whenAbsent ("tenant" | "self" | "plaintext").`);
     }
     if (isAbsentable(owner)) {
         throw new Error(`[Feature ${featureName}] defineEvent("${eventName}"): piiFields."${field}" is owned by "${ownerField}", which the payload schema allows to be null/undefined. ` +
             `Declare what happens then: { personal: { of: "${ownerField}", whenAbsent: "tenant" } } encrypts under the envelope tenant key, ` +
-            `whenAbsent: "plaintext" acknowledges that the value ships unencrypted and cannot be crypto-shredded (fw#2776).`);
+            `whenAbsent: "self" under the event's own record key, whenAbsent: "plaintext" acknowledges that the value ships unencrypted and cannot be crypto-shredded (fw#2776).`);
     }
 }
 // Builds config/secrets/claims/events/jobs/notifications registrar methods.

package/dist/engine/index.d.ts

@@ -4,6 +4,7 @@ export { isPrincipalStatusPlugin, isTenantLifecycleStatusPlugin, type PrincipalP
 export { PII_DIRECT_NAME_HINTS, PII_USER_OWNED_NAME_HINTS, PII_USER_REFERENCE_NAME_HINTS, } from "./boot-validator/entity-handler.js";
 export { entityHasAnonymizableSubjectField } from "./boot-validator/pii-retention.js";
 export { type CardMetaOverflow, collectCardMetaOverflow, collectWriteHandlerQns, MAX_TRANSFER_DEPTH, SECURITY_BASELINE_FEATURE_NAMES, type ValidateBootOptions, validateAppCustomScreenWriteQns, validateBoot, } from "./boot-validator.js";
+export { bridgeStub } from "./bridge-stub.js";
 export { type BuildAppSchemaOptions, buildAppSchema } from "./build-app-schema.js";
 export type { ConfigFeatureSchema } from "./build-config-feature-schema.js";
 export { buildConfigFeatureSchema, SETTINGS_HUB_FEATURE, SETTINGS_HUB_WORKSPACE, } from "./build-config-feature-schema.js";

package/dist/engine/index.js

@@ -5,6 +5,7 @@ export { isPrincipalStatusPlugin, isTenantLifecycleStatusPlugin, TENANT_TEARDOWN
 export { PII_DIRECT_NAME_HINTS, PII_USER_OWNED_NAME_HINTS, PII_USER_REFERENCE_NAME_HINTS, } from "./boot-validator/entity-handler.js";
 export { entityHasAnonymizableSubjectField } from "./boot-validator/pii-retention.js";
 export { collectCardMetaOverflow, collectWriteHandlerQns, MAX_TRANSFER_DEPTH, SECURITY_BASELINE_FEATURE_NAMES, validateAppCustomScreenWriteQns, validateBoot, } from "./boot-validator.js";
+export { bridgeStub } from "./bridge-stub.js";
 export { buildAppSchema } from "./build-app-schema.js";
 export { buildConfigFeatureSchema, SETTINGS_HUB_FEATURE, SETTINGS_HUB_WORKSPACE, } from "./build-config-feature-schema.js";
 export { buildTarget } from "./build-target.js";

package/dist/es-ops/operations-schema.js

@@ -12,7 +12,7 @@
 import { index, integer, table as pgTable, sql, text, timestamp } from "../db/dialect.js";
 // sql now comes from native dialect
 import { tableExists } from "../db/index.js";
-import { unsafePushTables } from "../stack/index.js";
+import { unsafePushTables } from "../db/table-push.js";
 export const esOperationsTable = pgTable("kumiko_es_operations", {
     // Filename without extension serves as ID. Chronologically sortable
     // (date-prefix convention), human-meaningful, no separate hash needed.

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

@@ -7,10 +7,10 @@
 // Guard-Script `scripts/guard-admin-api.ts` blockt Aufrufe aus App-Code —
 // Allowlist: samples/*/migration/, scripts/migrations/, die Definition
 // selbst, das Guard-Script selbst.
-import { instantToTimestamptzParam } from "../bun-db/query.js";
 import { constraintOf, isUniqueViolation } from "../db/pg-error.js";
 import { claimXactId, runAtomicEventWrite } from "../db/queries/event-store.js";
 import { eventPredecessorExists, findExistingEventVersion, insertRawEventBatch, insertRawFirstEvent, insertRawSubsequentEvent, } from "../db/queries/event-store-admin.js";
+import { instantToTimestamptzParam } from "../db/query.js";
 import { IdempotentAppendConflictError, VersionConflictError } from "./errors.js";
 function mapEventUniqueViolation(e, event) {
     if (constraintOf(e) === "events_idempotency_uq" && event.metadata.idempotencyKey) {

package/dist/event-store/archive.js

@@ -3,7 +3,7 @@ import { instant, table as pgTable, sql, text, uniqueIndex, uuid } from "../db/d
 import { upsertArchivedStream } from "../db/queries/event-store.js";
 import { deleteMany, fetchOne } from "../db/query.js";
 import { tableExists } from "../db/schema-inspection.js";
-import { unsafePushTables } from "../stack/index.js";
+import { unsafePushTables } from "../db/table-push.js";
 // Marten-aligned stream archival. Archived streams become read-only: fresh
 // appendEvent on an archived aggregate throws, and loadAggregate returns
 // an empty slice unless the caller passes { includeArchived: true }.

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

@@ -2,7 +2,8 @@
 export declare class VersionConflictError extends Error {
     readonly aggregateId: string;
     readonly expectedVersion: number;
-    constructor(aggregateId: string, expectedVersion: number);
+    readonly currentVersion: number | undefined;
+    constructor(aggregateId: string, expectedVersion: number, currentVersion?: number);
 }
 export declare class IdempotentAppendConflictError extends Error {
     readonly tenantId: string;

package/dist/event-store/errors.js

@@ -9,8 +9,12 @@
 export class VersionConflictError extends Error {
     aggregateId;
     expectedVersion;
-    constructor(aggregateId, expectedVersion) {
-        super(`Version conflict on aggregate ${aggregateId}: expected predecessor version ${expectedVersion}`);
+    // Undefined when the conflict surfaced as a bare unique violation with no lookup possible.
+    currentVersion;
+    constructor(aggregateId, expectedVersion, currentVersion) {
+        super(`Version conflict on aggregate ${aggregateId}: expected predecessor version ${expectedVersion}` +
+            (currentVersion === undefined ? "" : `, stream is at version ${currentVersion}`));
+        this.currentVersion = currentVersion;
         this.name = "VersionConflictError";
         this.aggregateId = aggregateId;
         this.expectedVersion = expectedVersion;

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

@@ -2,11 +2,10 @@
 import { isPersonalDataGated, UNATTRIBUTED_ORIGIN, } from "@cosmicdrift/kumiko-types/event-store-types";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { requestContext } from "../api/request-context.js";
-import { instantToTimestamptzParam } from "../bun-db/query.js";
 import { encryptEventPayloadPii } from "../crypto/event-pii.js";
 import { constraintOf, isUniqueViolation } from "../db/pg-error.js";
-import { claimXactId, insertSubsequentEventRow, notifyPgChannel, runAtomicEventWrite, selectAggregateMaxVersion, selectEventsHighWaterMark, selectStreamMaxVersion, selectStreamMaxVersions, } from "../db/queries/event-store.js";
-import { insertOne, selectMany } from "../db/query.js";
+import { claimXactId, insertFirstEventRow, insertSubsequentEventRow, notifyPgChannel, runAtomicEventWrite, selectAggregateMaxVersion, selectEventsHighWaterMark, selectStreamMaxVersion, selectStreamMaxVersions, } from "../db/queries/event-store.js";
+import { instantToTimestamptzParam, selectMany } from "../db/query.js";
 import { isStreamArchived } from "./archive.js";
 import { IdempotentAppendConflictError, SeedTimeOrderError, VersionConflictError, } from "./errors.js";
 import { eventsTable } from "./events-schema.js";
@@ -112,21 +111,21 @@ async function assertSeedTimeNotBeforePredecessor(db, event, seedCreatedAt) {
     }
 }
 async function insertFirstEvent(db, event, newVersion, eventVersion, seedCreatedAt) {
-    const row = await insertOne(db, eventsTable, {
+    const row = await insertFirstEventRow(db, {
         aggregateId: event.aggregateId,
         aggregateType: event.aggregateType,
         tenantId: event.tenantId,
-        version: newVersion,
+        newVersion,
         type: event.type,
         eventVersion,
         payload: event.payload,
         metadata: event.metadata,
         createdBy: event.metadata.userId,
-        ...(seedCreatedAt !== undefined && { createdAt: seedCreatedAt }),
+        createdAt: seedCreatedAt && instantToTimestamptzParam(seedCreatedAt),
     });
     if (!row)
-        throw new Error("insertFirstEvent: INSERT RETURNING produced no row");
-    return { id: row.id, createdAt: row.createdAt };
+        throw await versionConflictWithCurrentVersion(db, event);
+    return insertReturnOf(row);
 }
 // Subsequent event — predecessor must exist AND belong to the same tenant.
 // INSERT … SELECT … WHERE EXISTS is awkward in the typed builder, so this
@@ -147,7 +146,10 @@ async function insertSubsequentEvent(db, event, newVersion, eventVersion, seedCr
         createdAt: seedCreatedAt && instantToTimestamptzParam(seedCreatedAt),
     });
     if (!row)
-        throw new VersionConflictError(event.aggregateId, event.expectedVersion);
+        throw await versionConflictWithCurrentVersion(db, event);
+    return insertReturnOf(row);
+}
+function insertReturnOf(row) {
     const createdAt = row.created_at instanceof Date
         ? Temporal.Instant.fromEpochMilliseconds(row.created_at.getTime())
         : Temporal.Instant.from(row.created_at);
@@ -156,6 +158,12 @@ async function insertSubsequentEvent(db, event, newVersion, eventVersion, seedCr
         createdAt,
     };
 }
+// Runs in the still-healthy write transaction: ON CONFLICT DO NOTHING left it
+// unaborted, so the stream version is readable here.
+async function versionConflictWithCurrentVersion(db, event) {
+    const currentVersion = await selectStreamMaxVersion(db, event.aggregateId, event.tenantId);
+    return new VersionConflictError(event.aggregateId, event.expectedVersion, currentVersion);
+}
 function buildStoredEvent(event, newVersion, eventVersion, row) {
     return {
         id: String(row.id),

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 "../stack/index.js";
+import { 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

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 "../stack/index.js";
+import { 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.
@@ -47,7 +47,7 @@ export async function createRebuildDeadLetterTable(db) {
 // 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");
+    const { insertMany } = await import("../db/query.js");
     await insertMany(db, rebuildDeadLetterTable, skipped.map(({ event, error }) => ({
         projectionName,
         eventId: event.id,
@@ -61,7 +61,7 @@ export async function recordRebuildDeadLetters(db, projectionName, skipped) {
 }
 // Ops-side triage query, optionally scoped to one projection.
 export async function listRebuildDeadLetters(db, options = {}) {
-    const { selectMany } = await import("../bun-db/query.js");
+    const { selectMany } = await import("../db/query.js");
     const limit = options.limit ?? 100;
     const where = options.projectionName !== undefined ? { projectionName: options.projectionName } : undefined;
     return selectMany(db, rebuildDeadLetterTable, where, {