@cosmicdrift/kumiko-framework 0.367.0 → 0.368.0

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/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

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

@@ -5,12 +5,12 @@ import { executeRawQueryRead } from "../db/queries/raw-sql.js";
 import { coerceRow, extractTableInfo } from "../db/query.js";
 import { buildOwnershipClause, combineClauses, normalizeAccessEntry, shiftParams, } from "../engine/ownership.js";
 import { SYSTEM_TENANT_ID } from "../engine/types/identifiers.js";
-import { UnprocessableError } from "../errors/index.js";
+import { UnprocessableError, ValidationError } from "../errors/index.js";
 import { getStreamVersion } from "../event-store/index.js";
 import { LIST_ROW_META_REFERENCES } from "../ui-types/list-row-meta.js";
 import { rehydrateCompoundTypes } from "./compound-types.js";
 import { decodeKeysetCursor, encodeCursor, encodeKeysetCursor } from "./cursor.js";
-import { hasSearchablePlaintext, isSensitiveLabelField } from "./entity-field-encryption.js";
+import { hasSearchablePlaintext, isListFilterAllowed, isListSortAllowed, isSensitiveLabelField, } from "./entity-field-encryption.js";
 import { buildFilterWhere, } from "./event-store-executor-context.js";
 import { buildParentRefClause } from "./parent-ref-clause.js";
 import { buildEntityTable, physicalColumnName } from "./table-builder.js";
@@ -144,7 +144,7 @@ function applyScreenFilter(table, colSql, whereSql, params, f) {
         return;
     }
     for (const [field, value] of Object.entries(screen)) {
-        // #2015: `x <> NULL` is never true — mirror buildWhereClause's IS [NOT] NULL handling in bun-db/query.ts.
+        // #2015: `x <> NULL` is never true — mirror buildWhereClause's IS [NOT] NULL handling in db/query.ts.
         if (value === null) {
             whereSql.push(`${colSql(field)} IS NULL`);
         }
@@ -176,7 +176,7 @@ function applyScreenFilter(table, colSql, whereSql, params, f) {
         }
         else {
             // Blind-index OR rewrite (#818), lock-step with buildWhereClause
-            // in bun-db/query.ts — equality on lookupable fields matches the
+            // in db/query.ts — equality on lookupable fields matches the
             // plaintext arm OR the HMAC arm.
             const bidxKey = configuredBlindIndexKey();
             if (bidxKey !== undefined && typeof value === "string" && table[`${field}Bidx`]) {
@@ -547,7 +547,12 @@ export function createReadVerbs(ctx) {
                 // tenant filter that follows.
                 whereSql.push(`(${orParts.join(" OR ")})`);
             }
-            const sortCandidate = payload.sort && table[payload.sort] && fieldReadClause(payload.sort).kind === "pass"
+            // A column sort must not 400 (the renderer sends one per header click), and the order of
+            // ciphertext carries no meaning for the user while leaking the order of the plaintext.
+            const sortCandidate = payload.sort &&
+                table[payload.sort] &&
+                fieldReadClause(payload.sort).kind === "pass" &&
+                isListSortAllowed(entity, payload.sort)
                 ? payload.sort
                 : undefined;
             const sortDescending = payload.sortDirection === "desc";
@@ -606,6 +611,22 @@ export function createReadVerbs(ctx) {
                     // itself confirm the field exists (field-access.ts strips silently)
                     return;
                 }
+                if (!isListFilterAllowed(entity, f.field, f)) {
+                    throw new ValidationError({
+                        fields: [
+                            {
+                                path: `filter.${f.field}`,
+                                code: "field_not_filterable",
+                                i18nKey: "errors.validation.invalid_value",
+                                params: {
+                                    field: f.field,
+                                    op: f.op,
+                                    hint: "Encrypted, personal and secret fields cannot be filtered; only equality on a field with find: exact or fuzzy.",
+                                },
+                            },
+                        ],
+                    });
+                }
                 if (readClause.kind === "sql") {
                     const shifted = shiftParams({ sqlText: readClause.sqlText, params: readClause.params }, params.length);
                     whereSql.push(shifted.sqlText);

package/dist/db/index.d.ts

@@ -3,7 +3,7 @@ export { nullBlindIndexesForSubject, recordEventsOwnedExclusivelyByTenant, recor
 export { collectTableMetas } from "./collect-table-metas.js";
 export { flattenCompoundTypes, rehydrateCompoundTypes } from "./compound-types.js";
 export { seedConfigValues } from "./config-seed.js";
-export type { DbConnection, DbConnectionOptions, DbPoolHandle, DbRow, DbRunner, DbTx, } from "./connection.js";
+export type { CreateDbConnectionOptions, DbConnection, DbConnectionHandle, DbConnectionOptions, DbRow, DbRunner, DbTx, } from "./connection.js";
 export { createDbConnection, DEFAULT_OUTSIDE_TRANSACTION_POOL_MAX, dbConnectionOptionsFromEnv, outsideTransactionPoolOptionsFromEnv, } from "./connection.js";
 export type { CursorQueryOptions, CursorResult, DecodedKeysetCursor } from "./cursor.js";
 export { decodeCursor, decodeKeysetCursor, encodeCursor, encodeKeysetCursor } from "./cursor.js";
@@ -26,8 +26,8 @@ export { constraintOf, extractPgError, isTableAlreadyExists, isUniqueViolation,
 export { acquireNamespacedAdvisoryLock } from "./queries/advisory-lock.js";
 export { toPostgresArrayLiteral } from "./queries/postgres-array-literal.js";
 export { executeRawQuery, executeRawQueryRead } from "./queries/raw-sql.js";
-export type { SelectOptions, WhereObject, WhereValue } from "./query-api.js";
-export { aggregateWhere, asRawClient, countWhere, deleteMany, fetchOne, insertMany, insertOne, runInSavepoint, selectMany, transaction, updateMany, } from "./query-api.js";
+export type { DeleteManyBatchedOptions, DeleteManyBatchedResult, IncrementCounterOptions, InnerJoinRow, InnerJoinSpec, InsertOnConflictDoNothingOptions, JoinColumnPair, JsonTextMatch, SelectOptions, TableInfo, UpsertOnConflictOptions, WhereObject, WhereOperator, WhereValue, } from "./query.js";
+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";
 export { readRebuildMarker, rebuildTablesFromDiff, writeRebuildMarker, } from "./rebuild-marker.js";
 export { seedReferenceData } from "./reference-data.js";
 export { renderTableDdl, renderTablesDdl } from "./render-ddl.js";
@@ -35,5 +35,5 @@ export { diffReplayAgainstSnapshot, type ReplayedSchema, type ReplayedTable, typ
 export { findCommentedDropTables, isRetiredFrameworkTable, type RetiredFrameworkTable, retiredFrameworkTables, } from "./retired-framework-tables.js";
 export { tableExists } from "./schema-inspection.js";
 export { buildBaseColumns, buildEntityTable, declareGlobalTenancy, type EntityTable, physicalColumnName, toSnakeCase, toTableName, } from "./table-builder.js";
-export type { TenantDb, TenantDbGrants, TenantDbMode, UncheckedSystemDb } from "./tenant-db.js";
+export type { CreateTenantDbOptions, TenantDb, TenantDbGrants, TenantDbMode, UncheckedSystemDb, } from "./tenant-db.js";
 export { castTenantRows, createSystemDbView, createTenantDb, runInOwnTransaction, SYSTEM_SCOPE_CHECK_BRAND, scopeTenantDbToTenant, } from "./tenant-db.js";

package/dist/db/index.js

@@ -20,7 +20,7 @@ export { constraintOf, extractPgError, isTableAlreadyExists, isUniqueViolation,
 export { acquireNamespacedAdvisoryLock } from "./queries/advisory-lock.js";
 export { toPostgresArrayLiteral } from "./queries/postgres-array-literal.js";
 export { executeRawQuery, executeRawQueryRead } from "./queries/raw-sql.js";
-export { aggregateWhere, asRawClient, countWhere, deleteMany, fetchOne, insertMany, insertOne, runInSavepoint, selectMany, transaction, updateMany, } from "./query-api.js";
+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";
 export { readRebuildMarker, rebuildTablesFromDiff, writeRebuildMarker, } from "./rebuild-marker.js";
 export { seedReferenceData } from "./reference-data.js";
 export { renderTableDdl, renderTablesDdl } from "./render-ddl.js";

package/dist/db/migrate-runner.js

@@ -17,7 +17,7 @@ import { createHash } from "node:crypto";
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
-import { asRawClient, hasBegin, } from "../bun-db/query.js";
+import { asRawClient, hasBegin, } from "./query.js";
 // Advisory-lock key (random 32-bit int, stable). Verhindert dass zwei
 // gleichzeitig bootende Pods beide migrate apply laufen lassen (zweiter
 // blockiert bis erster fertig).