@cosmicdrift/kumiko-framework 0.366.0 → 0.368.0

package/agents/examples/user-data-rights.md

@@ -123,7 +123,7 @@ export const features = [
 //      löschen — Row bleibt für Multi-User-Refs intakt.
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
-import { authFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
+import { createAuthFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
 import {
   createComplianceProfilesFeature,
   tenantComplianceProfileEntity,
@@ -133,6 +133,10 @@ import {
   tenantRetentionOverrideEntity,
 } from "@cosmicdrift/kumiko-bundled-features/data-retention";
 import { createSessionsFeature } from "@cosmicdrift/kumiko-bundled-features/sessions";
+import {
+  tenantMembershipEntity,
+  tenantMembershipsTable,
+} from "@cosmicdrift/kumiko-bundled-features/tenant";
 import {
   createUserFeature,
   USER_STATUS,
@@ -144,15 +148,15 @@ import {
   runForgetCleanup,
   runUserExport,
 } from "@cosmicdrift/kumiko-bundled-features/user-data-rights";
-import { asRawClient, insertOne, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { insertOne, selectMany } from "@cosmicdrift/kumiko-framework/db";
 import { EXT_USER_DATA } from "@cosmicdrift/kumiko-framework/engine";
+import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
+import { seedRow } from "@cosmicdrift/kumiko-testing/helpers";
 import {
   setupTestStack,
   type TestStack,
   unsafeCreateEntityTable,
-} from "@cosmicdrift/kumiko-framework/stack";
-import { seedRow } from "@cosmicdrift/kumiko-framework/testing";
-import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
+} from "@cosmicdrift/kumiko-testing/stack";
 import { noteEntity, notesFeature, notesTable } from "../feature";
 
 let stack: TestStack;
@@ -173,7 +177,7 @@ beforeAll(async () => {
   stack = await setupTestStack({
     features: [
       createUserFeature(),
-      authFoundationFeature,
+      createAuthFoundationFeature(),
       createSessionsFeature(),
       createDataRetentionFeature(),
       createComplianceProfilesFeature(),
@@ -185,23 +189,7 @@ beforeAll(async () => {
   await unsafeCreateEntityTable(stack.db, noteEntity);
   await unsafeCreateEntityTable(stack.db, tenantRetentionOverrideEntity);
   await unsafeCreateEntityTable(stack.db, tenantComplianceProfileEntity);
-  await asRawClient(stack.db).unsafe(`
-    CREATE TABLE IF NOT EXISTS read_tenant_memberships (
-      id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-      tenant_id UUID NOT NULL,
-      user_id TEXT NOT NULL,
-      version INTEGER NOT NULL DEFAULT 0,
-      inserted_at TIMESTAMPTZ NOT NULL DEFAULT now(),
-      modified_at TIMESTAMPTZ NOT NULL DEFAULT now(),
-      inserted_by_id TEXT,
-      modified_by_id TEXT,
-      is_deleted BOOLEAN NOT NULL DEFAULT false,
-      deleted_at TIMESTAMPTZ,
-      deleted_by_id TEXT,
-      roles TEXT NOT NULL DEFAULT '[]',
-      UNIQUE(user_id, tenant_id)
-    )
-  `);
+  await unsafeCreateEntityTable(stack.db, tenantMembershipEntity);
 });
 
 afterAll(async () => {
@@ -233,14 +221,11 @@ async function seedAlice(opts: { gracePeriodEnd?: Instant; status?: string } = {
     status: opts.status ?? USER_STATUS.Active,
     gracePeriodEnd: opts.gracePeriodEnd ?? null,
   });
-  await asRawClient(stack.db).unsafe(
-    `
-    INSERT INTO read_tenant_memberships (tenant_id, user_id, roles)
-    VALUES ($1, $2, '["Member"]')
-    ON CONFLICT DO NOTHING
-  `,
-    [TENANT_A, ALICE_ID],
-  );
+  await seedRow(stack.db, tenantMembershipsTable, {
+    tenantId: TENANT_A,
+    userId: ALICE_ID,
+    roles: '["Member"]',
+  });
 }
 
 async function seedNote(id: string, title: string): Promise<void> {
@@ -336,8 +321,12 @@ describe("user-data-rights recipe :: EXT_USER_DATA-Hooks integrieren Notes-Domai
 //   - HTTP-Endpoints fuer create/list
 //   - Compliance-Profile-Wiring + Cron-Scheduling
 
-import { deleteMany, selectMany, updateMany } from "@cosmicdrift/kumiko-framework/bun-db";
-import { deriveEntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
+import {
+  deleteMany,
+  deriveEntityTableMeta,
+  selectMany,
+  updateMany,
+} from "@cosmicdrift/kumiko-framework/db";
 import {
   createEntity,
   createTextField,

package/agents/examples/user-profile.md

@@ -109,7 +109,7 @@ import {
   createRegistry,
   validateBoot as validateBootRaw,
 } from "@cosmicdrift/kumiko-framework/engine";
-import { withBootValidatorFixture } from "@cosmicdrift/kumiko-framework/testing";
+import { withBootValidatorFixture } from "@cosmicdrift/kumiko-testing/helpers";
 import { composeAccountApp } from "../feature";
 
 function validateBoot(features: Parameters<typeof validateBootRaw>[0]): void {
@@ -166,7 +166,7 @@ describe("user-profile recipe — boot validation", () => {
 //   })
 
 import { createAuthEmailPasswordFeature } from "@cosmicdrift/kumiko-bundled-features/auth-email-password";
-import { authFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
+import { createAuthFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
 import { createComplianceProfilesFeature } from "@cosmicdrift/kumiko-bundled-features/compliance-profiles";
 import { createConfigFeature } from "@cosmicdrift/kumiko-bundled-features/config";
 import { createDataRetentionFeature } from "@cosmicdrift/kumiko-bundled-features/data-retention";
@@ -211,7 +211,7 @@ export function composeAccountApp(): FeatureDefinition[] {
     createAuthEmailPasswordFeature(),
     createDataRetentionFeature(),
     createComplianceProfilesFeature(),
-    authFoundationFeature,
+    createAuthFoundationFeature(),
     createPersonalAccessTokensFeature({ scopes: {} }),
     createSessionsFeature(),
     createFilesFeature(),

package/agents/examples/webhook-step.md

@@ -91,15 +91,14 @@ import {
   createEnvMasterKeyProvider,
   type MasterKeyProvider,
 } from "@cosmicdrift/kumiko-framework/secrets";
+import { createTestUser, testTenantId } from "@cosmicdrift/kumiko-framework/seeding";
 import {
-  createTestUser,
   resetEventStore,
   setupTestStack,
   type TestStack,
-  testTenantId,
   unsafeCreateEntityTable,
   unsafePushTables,
-} from "@cosmicdrift/kumiko-framework/stack";
+} from "@cosmicdrift/kumiko-testing/stack";
 
 import { incidentEntity, incidentTable, webhookDemoFeature } from "../feature";
 

package/agents/examples/wizard-form.md

@@ -102,19 +102,18 @@ the draft (reopening the wizard starts fresh on step 1).
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { createConfigFeature } from "@cosmicdrift/kumiko-bundled-features/config";
 import {
+  createFormDraftFeature,
   FormDraftHandlers,
   FormDraftQueries,
   formDraftEntity,
-  formDraftFeature,
 } from "@cosmicdrift/kumiko-bundled-features/form-draft";
 import type { SaveContext } from "@cosmicdrift/kumiko-framework/engine";
+import { createTestUser, TestUsers } from "@cosmicdrift/kumiko-framework/seeding";
 import {
-  createTestUser,
   setupTestStack,
   type TestStack,
-  TestUsers,
   unsafeCreateEntityTable,
-} from "@cosmicdrift/kumiko-framework/stack";
+} from "@cosmicdrift/kumiko-testing/stack";
 import { listingEntity, listingsFeature } from "../feature";
 
 let stack: TestStack;
@@ -131,7 +130,7 @@ const DRAFT_KEY = "listing-wizard";
 beforeAll(async () => {
   // form-draft requires the "config" feature (its retention-days setting).
   stack = await setupTestStack({
-    features: [listingsFeature, formDraftFeature, createConfigFeature()],
+    features: [listingsFeature, createFormDraftFeature(), createConfigFeature()],
   });
   await unsafeCreateEntityTable(stack.db, listingEntity);
   await unsafeCreateEntityTable(stack.db, formDraftEntity);

package/agents/examples/workflow-engine.md

@@ -60,7 +60,8 @@ import {
   WORKFLOW_WAITING_TYPE,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { append, eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
-import { setupTestStack, type TestStack, TestUsers } from "@cosmicdrift/kumiko-framework/stack";
+import { TestUsers } from "@cosmicdrift/kumiko-framework/seeding";
+import { setupTestStack, type TestStack } from "@cosmicdrift/kumiko-testing/stack";
 import { createSuspendedRunFetcher } from "../postgres-resume-loop";
 
 let stack: TestStack;
@@ -982,8 +983,11 @@ export function startCronScheduler(
 ### src/db/queries/suspended-runs.ts
 
 ```ts
-import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
-import { type DbRunner, toPostgresArrayLiteral } from "@cosmicdrift/kumiko-framework/db";
+import {
+  asRawClient,
+  type DbRunner,
+  toPostgresArrayLiteral,
+} from "@cosmicdrift/kumiko-framework/db";
 
 export async function selectExpiredSuspensionEvents(
   db: DbRunner,

package/agents/examples/writeform-section.md

@@ -57,7 +57,7 @@ import {
   defineFeature,
   validateBoot as validateBootRaw,
 } from "@cosmicdrift/kumiko-framework/engine";
-import { withBootValidatorFixture } from "@cosmicdrift/kumiko-framework/testing";
+import { withBootValidatorFixture } from "@cosmicdrift/kumiko-testing/helpers";
 import { z } from "zod";
 import { noteDeskFeature } from "../feature";
 

package/agents/examples.md

@@ -35,6 +35,7 @@
 | `feature-toggles` | Runtime feature-toggle flip — two toggleable features, one registers a cross-feature hook on the other; disabling either has the documented effect without reboot. | `examples/feature-toggles.md` |
 | `field-access` | Field-level access control. When entity-level roles aren't granular enough. | `examples/field-access.md` |
 | `files-post-processing` | The three ways to generate an image variant: declarative field variants, imperative ctx.derivatives.variant() with region-blur, and the public route behind a default-deny predicate. | `examples/files-post-processing.md` |
+| `golden-path` | The smallest complete feature: entity, write handler, event, projection, screen and an integration test. | `examples/golden-path.md` |
 | `i18n` | Feature-scoped translations. 'Hallo' and 'Hello' in the same app. | `examples/i18n.md` |
 | `idempotency` | Same request, same result. Dedupes on request ID. | `examples/idempotency.md` |
 | `inbound-mail-triage` | Inbound-mail consumer pattern: inbound-mail-foundation + in-memory provider, a worker-lane triage job attached to the ingest handler, verified end-to-end through createAllInOneEntrypoint. | `examples/inbound-mail-triage.md` |

package/agents/features.md

@@ -106,7 +106,7 @@ Requires: `delivery`, `secrets`
 
 ## channel-email
 
-Wires an `EmailTransport` (typically `mail-transport-smtp` in production, `createInMemoryTransport()` in tests) into the delivery system as the `email` channel. Requires `delivery`; pass an `EmailChannelOptions` with a `transport` and a `resolveEmail` function that maps a user ID to their email address. Mails render from stored templates (`renderer-mail-html`): a notification routed to this channel needs `template` + `meta` on `r.notification`, otherwise its delivery fails.
+Wires an `EmailTransport` (typically `mail-transport-smtp` in production, `createInMemoryTransport()` in tests) into the delivery system as the `email` channel. Requires `delivery`; pass an `EmailChannelOptions` with a `transport` and a `resolveEmail` function that maps a user ID to their email address. Mails render from stored templates (`renderer-mail-html`): a notification routed to this channel needs `template` + `meta` on `r.notification`, otherwise its delivery fails. Pass `tenantTransport: tenantMailTransport` (from `mail-foundation`) to send each tenant's mail through its own configured provider: a broken provider fails the send, a tenant without one uses the app `transport`. Notifications declared with `unsubscribe: true` get a signed `data.unsubscribeUrl` from delivery, which turns into the `List-Unsubscribe` headers.
 
 Category: notifications
 
@@ -206,7 +206,7 @@ Exposes APIs: `retention.policyFor`
 
 ## delivery
 
-The notification dispatch core: call `ctx.notify(notificationType, { to, route, data, priority, idempotencyKey })` from any handler to fan out a notification across all registered channels (email, in-app, push). Inside a write handler the delivery runs after the write has committed (the call returns `{ kind: "deferred" }`, a rolled-back write sends nothing); `immediate: true` delivers synchronously and returns `{ kind: "dispatched", deliveries }`. It stores per-user channel preferences in the `notification-preference` entity, opt-outs for no-account recipient addresses in `notification-address-opt-out` (keyed by a blind-index hash, never the plaintext address), logs every attempt to `store_delivery_attempts`, and enforces idempotency and rate-limiting — add `channel-email`, `channel-in-app`, or `channel-push` on top to actually send anything. Unsubscribe/resubscribe links are served by `createUnsubscribeRoutes({ secret })` mounted via the app's `extraRoutes` at `/api/delivery/unsubscribe` and `/api/delivery/resubscribe`: `GET /unsubscribe?token=` renders a confirmation page (no write), `POST /unsubscribe` performs the opt-out (RFC 8058 one-click, token from the form body or query), `POST /resubscribe` undoes it (JSON `{token}` or form body only, never the query — reachable by a mail-client link prefetcher) — sign links with `signUnsubscribeToken` / `signAddressUnsubscribeToken` using the same secret. `channel-email` sets `List-Unsubscribe` / `List-Unsubscribe-Post` automatically when a message's `data.unsubscribeUrl` points at the unsubscribe route.
+The notification dispatch core: call `ctx.notify(notificationType, { to, route, data, priority, idempotencyKey })` from any handler to fan out a notification across all registered channels (email, in-app, push). Inside a write handler the delivery runs after the write has committed (the call returns `{ kind: "deferred" }`, a rolled-back write sends nothing); `immediate: true` delivers synchronously and returns `{ kind: "dispatched", deliveries }`. It stores per-user channel preferences in the `notification-preference` entity, opt-outs for no-account recipient addresses in `notification-address-opt-out` (keyed by a blind-index hash, never the plaintext address), logs every attempt to `store_delivery_attempts`, and enforces idempotency and rate-limiting — add `channel-email`, `channel-in-app`, or `channel-push` on top to actually send anything. Unsubscribe/resubscribe links are served by `createUnsubscribeRoutes({ secret })` mounted via the app's `extraRoutes` at `/api/delivery/unsubscribe` and `/api/delivery/resubscribe`: `GET /unsubscribe?token=` renders a confirmation page (no write), `POST /unsubscribe` performs the opt-out (RFC 8058 one-click, token from the form body or query), `POST /resubscribe` undoes it (JSON `{token}` or form body only, never the query — reachable by a mail-client link prefetcher) — sign links with `signUnsubscribeToken` / `signAddressUnsubscribeToken` using the same secret. `channel-email` sets `List-Unsubscribe` / `List-Unsubscribe-Post` automatically when a message's `data.unsubscribeUrl` points at the unsubscribe route. A notification declared with `unsubscribe: true` gets that link from delivery itself when the service has `unsubscribeLinks` (`runProdApp` option `unsubscribe: { secret }` mounts the routes and wires it; base URL from `auth.publicOrigin`, `auth.mail.baseUrl` or `APP_BASE_URL`): user recipients get a user token, `route` recipients an address token (needs a blind-index key, otherwise no link); a `data.unsubscribeUrl` from the caller wins. `unsubscribe.tenantOrigin: (ctx) => origin | null` points the link at the tenant's own host (subdomain or custom domain, must serve this app's `/api`); null, a throw or a non-https value fall back to the app origin. The token carries the mail's locale, so the confirmation and result pages render in the mail's language. To react to a no-account opt-out (e.g. remove the app's own subscriber row), declare `r.job(name, { trigger: { on: DeliveryHandlers.unsubscribeAddress } }, handler)` on a lane the app consumes: it runs after each committed opt-out, also an idempotent repeat, with `unsubscribeAddressPayloadSchema` (`addressHash`, `notificationType`, `channel`) as payload and the tenant in `ctx.triggeredBy.tenantId`; match the subscriber via `hashUnsubscribeAddress(email)`. Declare `unsubscribeUrl` as an optional template variable if the mail body shows it.
 
 Category: notifications
 
@@ -413,7 +413,7 @@ German UI and mail copy for framework screens. Opt-in; not included by includeBu
 
 ## mail-foundation
 
-Defines the `mailTransport` extension point and a per-tenant `provider` config key that selects which registered transport plugin to use at runtime. Call `createTransportForTenant(ctx, tenantId)` to get an `EmailTransport` ready for sending — use this feature together with at least one `mail-transport-*` feature; use `delivery` + `channel-email` instead when you need the full notification pipeline with delivery attempts and user preferences.
+Defines the `mailTransport` extension point and a per-tenant `provider` config key that selects which registered transport plugin to use at runtime. Call `createTransportForTenant(ctx, tenantId)` to get an `EmailTransport` ready for sending — use this feature together with at least one `mail-transport-*` feature; use `delivery` + `channel-email` instead when you need the full notification pipeline with delivery attempts and user preferences. Pass `tenantMailTransport` as `tenantTransport` to `createChannelEmailFeature` so a tenant with a provider configured sends delivery mails through its own transport and other tenants through the app transport.
 
 Category: notifications
 
@@ -538,7 +538,7 @@ Requires: `template-resolver`
 
 ## renderer-mail-html
 
-A `renderer-foundation` plugin that handles `RenderRequest { kind: "mail" }` and returns `{ subject, html, text, previewText? }` suitable for sending via `channel-email`. The mail template (`kind: "mail"`, document HTML, subject in `meta`) resolves through `template-resolver`'s DB fallback, its body is compiled to Handlebars by template-resolver and rendered with escaping, then placed into an MJML layout (`kind: "mail-layout"`, slug `default` unless `meta.layoutSlug` says otherwise, an in-code structured layout with the tenant branding logo and accent color as last resort) that `mjml()` compiles to email-safe table HTML, with `html-to-text` producing the plain-text alternative. An optional `footer` resolver adds the platform imprint, privacy link and footer text below every structured layout, and an optional `brandSuffix` resolver adds a word after the tenant name in the brand row of the in-code layout. Mail meta `headerChip`, `tone` and `footerNote` add a chip beside the brand, the tone of the top line and chip, and a note above the site and unsubscribe links of the card. Seed an editable system layout with `seedSystemMailLayout(db)`. Requires `renderer-foundation` + `template-resolver`.
+A `renderer-foundation` plugin that handles `RenderRequest { kind: "mail" }` and returns `{ subject, html, text, previewText? }` suitable for sending via `channel-email`. The mail template (`kind: "mail"`, document HTML, subject in `meta`) resolves through `template-resolver`'s DB fallback, its body is compiled to Handlebars by template-resolver and rendered with escaping, then placed into an MJML layout (`kind: "mail-layout"`, slug `default` unless `meta.layoutSlug` says otherwise, an in-code structured layout with the tenant branding logo and accent color as last resort) that `mjml()` compiles to email-safe table HTML, with `html-to-text` producing the plain-text alternative. An optional `footer` resolver adds the platform imprint, privacy link and footer text below every structured layout, an optional `brandSuffix` resolver adds a word after the tenant name in the brand row of the in-code layout, and an optional `siteUrl` resolver supplies the site link of the card when the tenant branding has no site URL (without either, the link is left out). The brand row and `data-resource="logo"` images use the branding logo upload, or the branding logo https address when no file is uploaded. Mail meta `headerChip`, `tone` and `footerNote` add a chip beside the brand, the tone of the top line and chip, and a note above the site and unsubscribe links of the card. Seed an editable system layout with `seedSystemMailLayout(db)`. Requires `renderer-foundation` + `template-resolver`.
 
 Requires: `renderer-foundation`, `template-resolver`
 

package/dist/consumer-cli.js

@@ -5,8 +5,7 @@
 // kumiko_event_consumers. Mirrors schema-cli.ts's shape (single runXCli(argv,
 // out) entry point, own DB connection) so `kumiko-consumer` ships the same
 // way `kumiko-schema` does.
-import { createConnection } from "./db/api.js";
-import { dbConnectionOptionsFromEnv } from "./db/connection.js";
+import { createDbConnection, dbConnectionOptionsFromEnv } from "./db/connection.js";
 import { getConsumerState, restartConsumer } from "./pipeline/index.js";
 import { ensureTemporalPolyfill } from "./time/index.js";
 // Single pass: pulls --instance-id (both "--instance-id <id>" and
@@ -80,7 +79,7 @@ export async function runConsumerCli(argv, out) {
         out.err("  DATABASE_URL not set.");
         return 1;
     }
-    const { db, close } = await createConnection(dbUrl, dbConnectionOptionsFromEnv());
+    const { db, close } = createDbConnection({ url: dbUrl, ...dbConnectionOptionsFromEnv() });
     try {
         if (sub === "status") {
             const state = await getConsumerState(db, name, instanceId);

package/dist/crypto/index.d.ts

@@ -8,4 +8,4 @@ export { type ActiveKmsWiring, buildPgKmsOptions, type KmsWiring, type KmsWiring
 export { createPgKmsAdapter, PgKmsAdapter, type PgKmsAdapterOptions, type RewrapOptions, type RewrapResult, rewrapSubjectKeys, } from "./pg-kms-adapter.js";
 export { configuredPiiSubjectKms, configurePiiSubjectKms, decryptPiiFieldValues, decryptPiiValueForSubject, type EncryptPiiOptions, encryptPiiFieldValues, encryptPiiJsonValueForSubject, encryptPiiValueForSubject, isPiiCiphertext, PII_CIPHERTEXT_PREFIX, PII_CIPHERTEXT_PREFIX_JSON, PII_ERASED_SENTINEL, } from "./pii-field-encryption.js";
 export { createRequestKmsCache, type RequestKmsCache, } from "./request-kms-cache.js";
-export { collectPiiEncryptedFields, collectPiiSubjectFields, collectSearchableSubjectFields, type ResolveSubjectOptions, resolveSubjectForField, SubjectResolutionError, } from "./subject-resolver.js";
+export { collectPiiEncryptedFields, collectPiiSubjectFields, collectSearchableSubjectFields, isRecordKeyedField, type ResolveSubjectOptions, resolveSubjectForField, SubjectResolutionError, } from "./subject-resolver.js";

package/dist/crypto/index.js

@@ -8,4 +8,4 @@ export { buildPgKmsOptions, requireKmsWiring, requireKmsWiringAsync, resolveKmsW
 export { createPgKmsAdapter, PgKmsAdapter, rewrapSubjectKeys, } from "./pg-kms-adapter.js";
 export { configuredPiiSubjectKms, configurePiiSubjectKms, decryptPiiFieldValues, decryptPiiValueForSubject, encryptPiiFieldValues, encryptPiiJsonValueForSubject, encryptPiiValueForSubject, isPiiCiphertext, PII_CIPHERTEXT_PREFIX, PII_CIPHERTEXT_PREFIX_JSON, PII_ERASED_SENTINEL, } from "./pii-field-encryption.js";
 export { createRequestKmsCache, } from "./request-kms-cache.js";
-export { collectPiiEncryptedFields, collectPiiSubjectFields, collectSearchableSubjectFields, resolveSubjectForField, SubjectResolutionError, } from "./subject-resolver.js";
+export { collectPiiEncryptedFields, collectPiiSubjectFields, collectSearchableSubjectFields, isRecordKeyedField, resolveSubjectForField, SubjectResolutionError, } from "./subject-resolver.js";

package/dist/crypto/owner-transition-rekey.js

@@ -12,6 +12,8 @@ export function isPlainUserOwnedField(field) {
 // owner. Returns the unchanged-by-the-caller values that must be written again
 // so they encrypt under the new owner. Owner → absent is not a transition:
 // the value stays with the last owner so that owner's forget still erases it.
+// Absent → owner moves a whenAbsent value (tenant or record key) to the owner's
+// key; the created event stays keyed under the whenAbsent subject.
 export function personalFieldsRekeyedOnOwnerTransition(entity, previous, mergedNew, submittedChanges) {
     const rekeyed = {};
     for (const [name, field] of Object.entries(entity.fields)) {

package/dist/crypto/pg-kms-adapter.js

@@ -1,6 +1,6 @@
 import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
 import postgres from "postgres";
-import { DEFAULT_DB_CLOSE_TIMEOUT_SECONDS } from "../db/api.js";
+import { DEFAULT_DB_CLOSE_TIMEOUT_SECONDS } from "../db/connection.js";
 import { KeyAlreadyExistsError, KeyErasedError, KeyNotFoundError, subjectIdToKey, } from "./kms-adapter.js";
 const IV_LENGTH = 12;
 const TAG_LENGTH = 16;

package/dist/crypto/subject-resolver.d.ts

@@ -28,6 +28,8 @@ export interface EventSubjectEnvelope {
     readonly aggregateId: string;
 }
 export declare function resolveEventSubject(fieldName: string, spec: EventPiiSubject, payload: Record<string, unknown>, envelope: EventSubjectEnvelope): SubjectId | null;
+/** True when the field can be keyed on the row's own `record:<entity>:<id>` subject. */
+export declare function isRecordKeyedField(field: EntityDefinition["fields"][string]): boolean;
 export declare function collectPiiSubjectFields(entity: EntityDefinition): readonly string[];
 export declare function collectPiiEncryptedFields(entity: EntityDefinition): readonly string[];
 export declare function collectPiiFileReferenceFields(entity: EntityDefinition): readonly string[];

package/dist/crypto/subject-resolver.js

@@ -34,10 +34,13 @@ function resolveUserOwnedSubject(userOwned, fieldName, row, opts) {
     const userId = nonEmptyString(row[ownerField]) ?? nonEmptyString(opts.ownerFallback?.[ownerField]);
     if (userId !== null)
         return { kind: "user", userId };
-    if (userOwned.whenAbsent === "tenant" && opts.ignoreWhenAbsent !== true) {
-        return resolveTenantSubject(fieldName, row, opts);
+    if (opts.ignoreWhenAbsent !== true) {
+        if (userOwned.whenAbsent === "tenant")
+            return resolveTenantSubject(fieldName, row, opts);
+        if (userOwned.whenAbsent === "self")
+            return resolveRecordSubject(fieldName, row, opts);
     }
-    throw new SubjectResolutionError(fieldName, `owner field "${ownerField}" is empty on the row and the field declares no whenAbsent — declare { personal: { of: "${ownerField}", whenAbsent: "tenant" } } (fw#3654)`);
+    throw new SubjectResolutionError(fieldName, `owner field "${ownerField}" is empty on the row and the field declares no whenAbsent — declare { personal: { of: "${ownerField}", whenAbsent: "tenant" } } or whenAbsent: "self" to key it on the row itself (fw#3654)`);
 }
 function resolveTenantSubject(fieldName, row, opts) {
     const tenantId = nonEmptyString(row["tenantId"]) ?? opts.tenantId;
@@ -87,6 +90,19 @@ function resolveEnvelopeTenant(fieldName, envelope) {
     }
     return { kind: "tenant", tenantId: envelope.tenantId };
 }
+function resolveEnvelopeRecordSubject(fieldName, envelope) {
+    if (nonEmptyString(envelope.aggregateType) === null ||
+        nonEmptyString(envelope.aggregateId) === null) {
+        throw new SubjectResolutionError(fieldName, "event envelope aggregateType/aggregateId is empty");
+    }
+    // aggregate_type is a free-form text column (events-schema.ts) — reject
+    // here rather than mint a record key that subjectIdSchema (kms-adapter.ts)
+    // would later refuse to shred.
+    if (!RECORD_ENTITY_PATTERN.test(envelope.aggregateType)) {
+        throw new SubjectResolutionError(fieldName, `event aggregateType "${envelope.aggregateType}" does not match ${RECORD_ENTITY_PATTERN} — not a shreddable record subject`);
+    }
+    return { kind: "record", entity: envelope.aggregateType, id: envelope.aggregateId };
+}
 // Same resolver for the live-append path (encryptEventPayloadPii) and the
 // backfill catalog path (backfillEventPiiEncryption) — the reason the two
 // can never encrypt the same field under different subjects. A "user"
@@ -101,34 +117,33 @@ export function resolveEventSubject(fieldName, spec, payload, envelope) {
             return { kind: "user", userId };
         if (normalized.whenAbsent === "tenant")
             return resolveEnvelopeTenant(fieldName, envelope);
+        if (normalized.whenAbsent === "self")
+            return resolveEnvelopeRecordSubject(fieldName, envelope);
         if (normalized.whenAbsent === "plaintext") {
             // skip: author declared whenAbsent: "plaintext" — value ships unencrypted by decision
             return null;
         }
         throw new SubjectResolutionError(fieldName, `owner field "${normalized.ownerField}" carries no id and the event declares no whenAbsent fallback — ` +
             `refusing to append plaintext PII. Declare { personal: { of: "${normalized.ownerField}", ` +
-            `whenAbsent: "tenant" } } to encrypt under the envelope tenant key, or whenAbsent: "plaintext" ` +
+            `whenAbsent: "tenant" } } to encrypt under the envelope tenant key, whenAbsent: "self" to encrypt ` +
+            `under the event's own record key, or whenAbsent: "plaintext" ` +
             "to acknowledge that this value cannot be crypto-shredded (fw#2776).");
     }
     if (normalized.kind === "tenant") {
         return resolveEnvelopeTenant(fieldName, envelope);
     }
     if (normalized.kind === "self") {
-        if (nonEmptyString(envelope.aggregateType) === null ||
-            nonEmptyString(envelope.aggregateId) === null) {
-            throw new SubjectResolutionError(fieldName, "event envelope aggregateType/aggregateId is empty");
-        }
-        // aggregate_type is a free-form text column (events-schema.ts) — reject
-        // here rather than mint a record key that subjectIdSchema (kms-adapter.ts)
-        // would later refuse to shred.
-        if (!RECORD_ENTITY_PATTERN.test(envelope.aggregateType)) {
-            throw new SubjectResolutionError(fieldName, `event aggregateType "${envelope.aggregateType}" does not match ${RECORD_ENTITY_PATTERN} — not a shreddable record subject`);
-        }
-        return { kind: "record", entity: envelope.aggregateType, id: envelope.aggregateId };
+        return resolveEnvelopeRecordSubject(fieldName, envelope);
     }
     const exhaustiveCheck = normalized;
     throw new Error(`Unhandled normalized event PII subject: ${JSON.stringify(exhaustiveCheck)}`);
 }
+/** True when the field can be keyed on the row's own `record:<entity>:<id>` subject. */
+export function isRecordKeyedField(field) {
+    if ("recordOwned" in field && field.recordOwned === true)
+        return true;
+    return "userOwned" in field && field.userOwned?.whenAbsent === "self";
+}
 function hasSubjectAnnotation(field) {
     return (("userOwned" in field && field.userOwned !== undefined) ||
         ("tenantOwned" in field && field.tenantOwned === true) ||

package/dist/db/bun-db-deprecated.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @deprecated Moved to `@cosmicdrift/kumiko-framework/db`. Run `bun kumiko-upgrade --apply`
+ * to rewrite imports. Removed in the first release after 2026-10-29.
+ */
+export type { DeleteManyBatchedOptions, DeleteManyBatchedResult, IncrementCounterOptions, InnerJoinRow, InnerJoinSpec, InsertOnConflictDoNothingOptions, JoinColumnPair, JsonTextMatch, SelectOptions, TableInfo, UpsertOnConflictOptions, WhereObject, WhereOperator, WhereValue, } from "./query.js";
+/**
+ * @deprecated Moved to `@cosmicdrift/kumiko-framework/db`. Run `bun kumiko-upgrade --apply`
+ * to rewrite imports. Removed in the first release after 2026-10-29.
+ */
+export { aggregateWhere, asEntityTableMeta, asRawClient, countWhere, deleteMany, deleteManyBatched, extractTableInfo, fetchOne, incrementCounter, insertMany, insertOnConflictDoNothing, insertOne, instantToTimestamptzParam, isTimestamptzType, requireEntityTableMeta, runInSavepoint, runInSavepointIfSupported, runnerCanBeginTransaction, selectInnerJoin, selectMany, transaction, unsafeReadRetrying, updateMany, upsertByPk, upsertOnConflict, } from "./query.js";

package/dist/{bun-db/index.js → db/bun-db-deprecated.js}

@@ -1,4 +1,5 @@
-// bun-db: Bun.sql-basierte DB-API ohne drizzle.
-// Production-Pfad nach drizzle-removal.
-export { bunDbConnectionOptionsFromEnv, createBunDbConnection } from "./connection.js";
+/**
+ * @deprecated Moved to `@cosmicdrift/kumiko-framework/db`. Run `bun kumiko-upgrade --apply`
+ * to rewrite imports. Removed in the first release after 2026-10-29.
+ */
 export { aggregateWhere, asEntityTableMeta, asRawClient, countWhere, deleteMany, deleteManyBatched, extractTableInfo, fetchOne, incrementCounter, insertMany, insertOnConflictDoNothing, insertOne, instantToTimestamptzParam, isTimestamptzType, requireEntityTableMeta, runInSavepoint, runInSavepointIfSupported, runnerCanBeginTransaction, selectInnerJoin, selectMany, transaction, unsafeReadRetrying, updateMany, upsertByPk, upsertOnConflict, } from "./query.js";

package/dist/db/config-seed.js

@@ -24,7 +24,7 @@ export async function seedConfigValues(seeds, table, entity, registry, db, ciphe
         return { created, skipped };
     const systemUser = createSystemUser(SYSTEM_TENANT_ID);
     const executor = createEventStoreExecutor(table, entity, { entityName: "config-value" });
-    const tdb = createTenantDb(db, SYSTEM_TENANT_ID, "system");
+    const tdb = createTenantDb({ db, tenantId: SYSTEM_TENANT_ID, mode: "system" });
     for (const seed of seeds) {
         const keyDef = registry.getConfigKey(seed.key);
         if (!keyDef) {

package/dist/db/connection.d.ts

@@ -1,12 +1,30 @@
 import type { DbConnection, PgClient } from "@cosmicdrift/kumiko-types/db-connection";
+import postgres from "postgres";
 export type * from "@cosmicdrift/kumiko-types/db-connection";
-export type { DbConnectionOptions, DbPoolHandle } from "./api.js";
-export { createConnection } from "./api.js";
-export declare function createDbConnection(url: string, options?: import("./api.js").DbConnectionOptions): {
+type PostgresDriverOptions = NonNullable<Parameters<typeof postgres>[1]>;
+export type DbConnectionOptions = {
+    readonly maxConnections?: number;
+    readonly idleTimeoutSeconds?: number;
+    readonly connectTimeoutSeconds?: number;
+    readonly closeTimeoutSeconds?: number;
+    readonly ssl?: PostgresDriverOptions["ssl"];
+    readonly onNotice?: (notice: postgres.Notice) => void;
+};
+export type CreateDbConnectionOptions = DbConnectionOptions & {
+    readonly url: string;
+};
+export type DbConnectionHandle = {
     db: DbConnection;
     client: PgClient;
     close: () => Promise<void>;
 };
-export declare function dbConnectionOptionsFromEnv(env?: Readonly<Record<string, string | undefined>>): import("./api.js").DbConnectionOptions;
+export declare const DEFAULT_DB_CLOSE_TIMEOUT_SECONDS = 5;
+export declare function createDbConnection(options: CreateDbConnectionOptions): DbConnectionHandle;
+/**
+ * @deprecated Positional form, use `createDbConnection({ url, ... })`. Run
+ * `bun kumiko-upgrade --apply` to rewrite call sites. Removed in the first release after 2026-10-29.
+ */
+export declare function createDbConnection(url: string, options?: DbConnectionOptions): DbConnectionHandle;
+export declare function dbConnectionOptionsFromEnv(env?: Readonly<Record<string, string | undefined>>): DbConnectionOptions;
 export declare const DEFAULT_OUTSIDE_TRANSACTION_POOL_MAX = 3;
-export declare function outsideTransactionPoolOptionsFromEnv(env?: Readonly<Record<string, string | undefined>>): import("./api.js").DbConnectionOptions;
+export declare function outsideTransactionPoolOptionsFromEnv(env?: Readonly<Record<string, string | undefined>>): DbConnectionOptions;

package/dist/db/connection.js

@@ -1,10 +1,11 @@
 import postgres from "postgres";
 import { readPositiveIntEnv } from "../utils/env-parse.js";
-import { DEFAULT_DB_CLOSE_TIMEOUT_SECONDS } from "./api.js";
-export { createConnection } from "./api.js";
-// Legacy: postgres-js only. Neue Aufrufer: createConnection() aus api.ts.
-// guard:dup-ok — andere Layer als createPgConnection (gibt DbConnection zurück, nicht postgres-Instanz)
-export function createDbConnection(url, options = {}) {
+// A DB outage can leave an in-flight query referenced on a dead connection,
+// so a plain end() (no timeout = wait for queries to finish) hangs forever —
+// close() must always bound how long shutdown waits.
+export const DEFAULT_DB_CLOSE_TIMEOUT_SECONDS = 5;
+export function createDbConnection(urlOrOptions, legacyOptions = {}) {
+    const { url, ...options } = typeof urlOrOptions === "string" ? { ...legacyOptions, url: urlOrOptions } : urlOrOptions;
     const pgOptions = {};
     if (options.maxConnections !== undefined)
         pgOptions.max = options.maxConnections;
@@ -13,6 +14,10 @@ export function createDbConnection(url, options = {}) {
     if (options.connectTimeoutSeconds !== undefined) {
         pgOptions.connect_timeout = options.connectTimeoutSeconds;
     }
+    if (options.ssl !== undefined)
+        pgOptions.ssl = options.ssl;
+    if (options.onNotice !== undefined)
+        pgOptions.onnotice = options.onNotice;
     const client = postgres(url, pgOptions);
     return {
         db: client,

package/dist/db/dialect.js

@@ -251,7 +251,7 @@ export function primaryKey(opts) {
 // Limits: no nested SqlExpression composition (drizzle's recursive
 // `sql\`${other}\``) — schema-files use single-level expressions only.
 // Unforgeable via JSON — a client-supplied jsonb value can fake `kind:
-// "sql-expr"` but can never carry a Symbol, so isSqlExpression() (bun-db/query.ts)
+// "sql-expr"` but can never carry a Symbol, so isSqlExpression() (db/query.ts)
 // can't be tricked into treating request data as a raw SQL literal. The same
 // brand gate is enforced here in the schema DSL (sql`...` interpolation +
 // literalDefault) and in entity-table-meta's sqlExpressionText — a duck-typed

package/dist/db/entity-field-encryption.d.ts

@@ -3,6 +3,11 @@ import { type Logger } from "../logging/index.js";
 import type { EnvelopeCipher } from "../secrets/envelope-cipher.js";
 export declare function collectEncryptedFieldNames(entity: EntityDefinition): ReadonlySet<string>;
 export declare function isSensitiveLabelField(entity: EntityDefinition, field: string): boolean;
+export declare function isListFilterAllowed(entity: EntityDefinition, field: string, filter: {
+    readonly op: string;
+    readonly value: unknown;
+}): boolean;
+export declare function isListSortAllowed(entity: EntityDefinition, field: string): boolean;
 export declare function hasSearchablePlaintext(entity: EntityDefinition, field: string): boolean;
 export declare function encryptEntityFieldValues(row: Record<string, unknown>, encryptedFields: ReadonlySet<string>, cipher: EnvelopeCipher, opts?: {
     onlyKeys?: Iterable<string>;

package/dist/db/entity-field-encryption.js

@@ -22,6 +22,35 @@ export function isSensitiveLabelField(entity, field) {
     return (collectEncryptedFieldNames(entity).has(field) ||
         collectPiiEncryptedFields(entity).includes(field));
 }
+// A `sensitive` (find: "secret") field is never comparable either, even while its value is still
+// legacy plaintext.
+function holdsCiphertextOrSecret(entity, field) {
+    const def = entity.fields[field];
+    if (def === undefined)
+        return false;
+    return ("sensitive" in def && def.sensitive === true) || isSensitiveLabelField(entity, field);
+}
+// Only a PII field with a blind index (`find: "exact" | "fuzzy"`) can be matched without reading
+// the stored value: the `<field>Bidx` HMAC arm of an equality filter.
+function isBlindIndexEqualityTarget(entity, field) {
+    const def = entity.fields[field];
+    return (def?.type === "text" &&
+        def.lookupable === true &&
+        def.sensitive !== true &&
+        !collectEncryptedFieldNames(entity).has(field));
+}
+// Filtering ciphertext (or a secret) turns hit/count into a value oracle, and for legacy plaintext
+// rows an `in`/range comparison into a prefix oracle. Blind-index equality is the one exception.
+export function isListFilterAllowed(entity, field, filter) {
+    if (!holdsCiphertextOrSecret(entity, field))
+        return true;
+    return (isBlindIndexEqualityTarget(entity, field) &&
+        filter.op === "eq" &&
+        typeof filter.value === "string");
+}
+export function isListSortAllowed(entity, field) {
+    return !holdsCiphertextOrSecret(entity, field);
+}
 // `searchable: true` on a text field means it is indexed plaintext
 // somewhere findable by term — a plain text field's own column, or (for a
 // personal-data field) the derived search index mirroring it.

package/dist/db/entity-table-meta.js

@@ -15,7 +15,7 @@
 //      entity-shaped base columns. Escape hatch: no forced audit trail for the
 //      hand-built path; app author owns tenant scoping / versioning. Prefer a
 //      `store_` table name — `read_` is reserved for managed projections (#1208/#1220).
-import { collectPiiEncryptedFields } from "../crypto/index.js";
+import { collectPiiEncryptedFields, isRecordKeyedField } from "../crypto/index.js";
 import { isSqlExpression } from "./dialect.js";
 import { READ_MODEL_PREFIX, SOFT_DELETE_LIVE_ROW_PREDICATE, toSnakeCase, toTableName, } from "./table-builder.js";
 // Standard base columns for event-sourced read-model tables. Mirrors
@@ -224,11 +224,12 @@ export function deriveEntityTableMeta(entityName, entity, options) {
     const idType = entity.idType ?? "uuid";
     if (source === "unmanaged" && idType === "serial") {
         // Unmanaged direct-write stores bypass validateRecordOwnedSubjects (it only walks
-        // feature.entities), yet encryptForDirectWrite still keys recordOwned fields as
-        // `record:<entity>:<id>`; forgetSubject requires a UUID, so the value could never be shredded.
-        const recordOwnedField = Object.entries(entity.fields).find(([, field]) => "recordOwned" in field && field.recordOwned === true);
+        // feature.entities), yet encryptForDirectWrite still keys recordOwned and
+        // whenAbsent: "self" fields as `record:<entity>:<id>`; forgetSubject requires a UUID,
+        // so the value could never be shredded.
+        const recordOwnedField = Object.entries(entity.fields).find(([, field]) => isRecordKeyedField(field));
         if (recordOwnedField) {
-            throw new Error(`deriveEntityTableMeta("${entityName}", { source: "unmanaged" }): field "${recordOwnedField[0]}" 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 could never be shredded. Use idType: "uuid", or give the field a different personal stance.`);
+            throw new Error(`deriveEntityTableMeta("${entityName}", { source: "unmanaged" }): field "${recordOwnedField[0]}" 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 could never be shredded. Use idType: "uuid", or give the field a different personal stance.`);
         }
     }
     // Base columns first, then user-fields. User-fields with the same