@cosmicdrift/kumiko-framework 0.397.0 → 0.399.0

package/AGENTS.md

@@ -9,22 +9,31 @@ not exist in your version:
 
 | File | What it holds |
 | --- | --- |
-| `agents/features.md` | Every bundled feature: name, purpose, config keys, dependencies |
+| `agents/features-index.md` | One entry per bundled feature: purpose, factory import, required features, config keys without a default, secrets |
+| `agents/features.md` | Every bundled feature in detail: purpose, config keys, secrets, dependencies, APIs |
+| `agents/api.md` | Index of the API reference: one file per entry point an app imports |
+| `agents/api/<entry>.md` | Signatures of one entry point; options and screen types as property lists |
+| `agents/api/types.md` | Types the entry points use but do not export, such as nested option shapes |
 | `agents/widgets.md` | Every value export of `@cosmicdrift/kumiko-renderer/web` with its short description |
 | `agents/examples.md` | Index of the worked examples, one per concept |
 | `agents/examples/<name>.md` | One tested sample app: README plus every source and test file |
 
 The paths are relative to this file. From an app root they live under
-`node_modules/@cosmicdrift/kumiko-framework/`. Type signatures are in
-`dist/*.d.ts` of each package; this file does not repeat them.
+`node_modules/@cosmicdrift/kumiko-framework/`. For signatures and option
+types read `agents/api.md` and the file it points to. Do not read
+`dist/*.d.ts` in `node_modules`; the API files hold the same public
+signatures at a fraction of the size.
 
 Order of work for a new feature:
 
-1. Search `agents/features.md` for a bundled feature that already does it.
+1. Search `agents/features-index.md` for a bundled feature that already does
+   it. Open `agents/features.md` only for the feature you picked.
 2. Find the closest example in `agents/examples.md` and read it fully.
-3. Build the feature with the declarative building blocks below.
-4. Write an integration test against the real stack.
-5. Run boot validation and the tests. Boot errors name the fix; apply it.
+3. Look up every function, screen, column, action and field option you use in
+   `agents/api.md` instead of `dist/*.d.ts`.
+4. Build the feature with the declarative building blocks below.
+5. Write an integration test against the real stack.
+6. Run boot validation and the tests. Boot errors name the fix; apply it.
 
 ## Mental model
 
@@ -287,7 +296,7 @@ produces code that compiles and then fails in production.
 
 ## I need X, use Y
 
-Before building anything here, search `agents/features.md`: auth, tenants,
+Before building anything here, search `agents/features-index.md`: auth, tenants,
 mail, files, jobs, billing, audit, notifications and GDPR flows already exist
 as bundled features.
 
@@ -333,7 +342,8 @@ as bundled features.
 | Multi-step background flows | Workflow engine | `agents/examples/workflow-engine.md` |
 | A mount invariant for my feature | `r.bootCheck` | `agents/examples/boot-check.md` |
 | A widget for a custom screen | Search by concern | `agents/widgets.md` |
-| A bundled feature and its config | Search by name or purpose | `agents/features.md` |
+| A bundled feature and its config | Search by name or purpose | `agents/features-index.md`, then `agents/features.md` |
+| The options of a function, screen or field | Search by name | `agents/api.md` |
 
 ## Reading an example
 
@@ -350,15 +360,19 @@ isolate tests with one tenant each.
 
 ## Package entry points
 
-Import only from these subpaths of `@cosmicdrift/kumiko-framework`. Deep
-imports into `src/` or `dist/` break on the next release.
+Import only from these entry points. Deep imports into `src/` or `dist/`
+break on the next release. Each one has its signatures in the file named in
+`agents/api.md`.
 
-| Subpath | Use it for |
+| Entry point | Use it for |
 | --- | --- |
-| `/engine` | `defineFeature`, `createEntity`, field factories, handler helpers, executors, events |
-| `/errors` | Typed failures and error helpers |
-| `/stack` | Test stack, `TestUsers`, `createTestUser` |
-| `/testing` | Assertion helpers such as `expectErrorIncludes` |
-| `/ui-types` | Screen definition types (`EntityListScreenDefinition`, ...) |
-| `/db` | `buildEntityTable` and database helpers for tests and migrations |
-| `/event-store` | Event store helpers |
+| `@cosmicdrift/kumiko-framework/engine` | `defineFeature`, `createEntity`, field factories, handler helpers, executors, events |
+| `@cosmicdrift/kumiko-framework/errors` | Typed failures and error helpers |
+| `@cosmicdrift/kumiko-framework/ui-types` | Screen definition types (`EntityListScreenDefinition`, ...) |
+| `@cosmicdrift/kumiko-framework/db` | `buildEntityTable` and database helpers for tests and migrations |
+| `@cosmicdrift/kumiko-framework/event-store` | Event store helpers |
+| `@cosmicdrift/kumiko-framework/seeding` | `TestUsers`, `createTestUser`, seed helpers |
+| `@cosmicdrift/kumiko-renderer/web` | Widgets, hooks and the web app shell |
+| `@cosmicdrift/kumiko-dev-server/testing` | `setupAppTestStack`, `seedTenant` for app integration tests |
+| `@cosmicdrift/kumiko-testing/stack` | `setupTestStack`, the stack the samples use |
+| `@cosmicdrift/kumiko-testing/helpers` | Assertion helpers such as `expectErrorIncludes` |

package/agents/api/dev-server-testing.md

@@ -0,0 +1,23 @@
+<!-- Generated by `bun run gen:agent-docs` from packages/dev-server/src/testing.ts. Do not edit. -->
+
+# @cosmicdrift/kumiko-dev-server/testing
+
+Import from `@cosmicdrift/kumiko-dev-server/testing`. Types used here but not exported by any entry point are in `api/types.md`.
+
+## Functions
+
+```ts
+function createE2eSeedRoutes(options?: E2eSeedRoutesOptions): ExtraRouteDefinition[];
+function persistTenantRows(write: SeedWriter, options?: { name?: string; users?: number; admin?: SeedTenantOptions["admin"]; }): Promise<PersistedTenant>;
+function seedTenant(stack: TestStack, options?: SeedTenantOptions): Promise<InProcessSeededTenant>;
+function setupAppTestStack(features: FeatureDefinition[], options?: SetupAppTestStackOptions): Promise<TestStack>;
+```
+
+## Types
+
+```ts
+type SetupAppTestStackOptions = SetupTestStackFromFeaturesOptions & {
+  registryTables?: boolean;
+  featureToggles?: boolean; // Same as `RunDevAppOptions["featureToggles"]`: mounts `feature-toggles` (do not list it in `features`) and layers its operator switches over the dispatcher's feature gate.
+};
+```

package/agents/api/framework-db.md

@@ -0,0 +1,277 @@
+<!-- Generated by `bun run gen:agent-docs` from packages/framework/src/db/index.ts. Do not edit. -->
+
+# @cosmicdrift/kumiko-framework/db
+
+Import from `@cosmicdrift/kumiko-framework/db`. Types used here but not exported by any entry point are in `api/types.md`.
+
+## Functions
+
+```ts
+function acquireNamespacedAdvisoryLock(db: AnyDb, namespace: number, key: string): Promise<void>; // pg_advisory_xact_lock keyed on namespace+key hash — xact-scoped, auto-released at commit/rollback.
+function aggregateWhere(db: AnyDb, table: TableLike, spec: AggregateSpec, where?: WhereObject): Promise<AggregateRow[]>;
+function answerListAggregate(executor: Pick<EventStoreExecutor, "aggregate">, request: AggregateRequest, user: Parameters<EventStoreExecutor["aggregate"]>[1], db: TenantDb, runtimeOptions: Parameters<EventStoreExecutor["aggregate"]>[3], labelDeps: LabelDeps): Promise<ListAggregateResult>;
+function applyEntityEvent(event: StoredEvent, table: Table, entity: EntityDefinition, tx: ExecutorManagedRunner): Promise<ApplyResult>; // Applies an auto-event idempotently to the entity table.
+function asEntityTableMeta(table: unknown): EntityTableMeta | undefined;
+function asRawClient(db: unknown): RawClient;
+function assertExistsIn(db: DbConnection | TenantDb, entity: any, options: { field: string; value: unknown; tenantId?: TenantId; where?: Record<string, unknown>; entityName?: string; }): Promise<NotFoundError | null>; // Generic constraint helper: asserts a value exists in a table.
+function assertNoActiveRowLevelSecurityScope(startingWhat: string): void;
+function assertRowLevelSecurityBootState(db: AnyDb, mode: RowLevelSecurityMode, knownTables: KnownTables): Promise<void>;
+function assertRowLevelSecurityTableState(db: AnyDb, mode: RowLevelSecurityMode, knownTables: KnownTables, scope?: RowLevelSecurityCheckScope): Promise<void>;
+function boolean(name: string): ColumnBuilder<boolean>;
+function buildBaseColumns(softDelete: boolean, idType?: "serial" | "uuid"): …;
+function buildEntityTable<E extends EntityDefinition>(entityName: string, entity: E, options?: BuildEntityTableOptions): EntityTable<E>;
+function castTenantRows<T>(rows: Record<string, unknown>[]): T[];
+function collectEncryptedFieldNames(entity: EntityDefinition): ReadonlySet<string>;
+function collectTableMetas(features: FeatureDefinition[]): EntityTableMeta[];
+function configureEntityFieldEncryption(cipher: EnvelopeCipher | undefined): void;
+function configuredEntityFieldEncryption(): EnvelopeCipher | undefined;
+function countWhere(db: AnyDb, table: TableLike, where?: WhereObject): Promise<number>;
+function createDbConnection(props: CreateDbConnectionOptions): DbConnectionHandle;
+function createEventStoreExecutor<E extends EntityDefinition>(table: Table, entity: E, options: EventStoreExecutorOptions): EventStoreExecutor<EntityRow<E>>;
+function createEventStoreExecutor<E extends EntityDefinition>(table: Table, entity: E, options: EventStoreExecutorOptions): EventStoreExecutor<EntityRow<E>>;
+function createSystemDbView(db: TenantDb, dbOutsideTransaction?: TenantDb, report?: EscapeHatchReporter): UncheckedSystemDb;
+function createTenantDataDestroyDb(options: Omit<CreateTenantDbOptions, "mode" | "reason">): ExecutorManagedTenantDb;
+function createTenantDb(options: CreateTenantDbOptions & { db: ExecutorManagedRunner; }): ExecutorManagedTenantDb;
+function createTenantDb(options: CreateTenantDbOptions): TenantDb;
+function createTenantDb(options: CreateTenantDbOptions & { db: ExecutorManagedRunner; }): ExecutorManagedTenantDb;
+function createTenantDb(options: CreateTenantDbOptions): TenantDb;
+function createTenantDb(options: CreateTenantDbOptions & { db: ExecutorManagedRunner; }): ExecutorManagedTenantDb;
+function createTenantDb(options: CreateTenantDbOptions): TenantDb;
+function dbConnectionOptionsFromEnv(env?: Readonly<Record<string, string | undefined>>): DbConnectionOptions;
+function declareGlobalTenancy<T extends SchemaTable>(table: T): T & TenancyBrand<"global">; // Stamps `tenancy: "global"` onto a `table()`/SchemaTable's meta in place.
+function decodeCursor(cursor: string): string;
+function decodeKeysetCursor(cursor: string): DecodedKeysetCursor;
+function decryptEntityFieldValues(row: Record<string, unknown>, encryptedFields: ReadonlySet<string>, cipher: EnvelopeCipher, opts?: { onFieldError?: (field: string, error: unknown) => void; }): Promise<Record<string, unknown>>;
+function defineUnmanagedTable<const T extends EntityTenancy = "tenant">(input: UnmanagedTableInput & { tenancy?: T; }): EntityTableMeta & TenancyBrand<T> & Writable; // Hand-built EntityTableMeta for direct-write stores (no entity base columns).
+function deleteMany(db: AnyDb, table: WritableTable, where: WhereObject): Promise<number>;
+function deleteMany(db: ExecutorManagedWriteCapability, table: EntityTableMeta, where: WhereObject): Promise<number>;
+function deleteMany(db: AnyDb, table: WritableTable, where: WhereObject): Promise<number>;
+function deleteMany(db: ExecutorManagedWriteCapability, table: EntityTableMeta, where: WhereObject): Promise<number>;
+function deleteMany(db: AnyDb, table: WritableTable, where: WhereObject): Promise<number>;
+function deleteMany(db: ExecutorManagedWriteCapability, table: EntityTableMeta, where: WhereObject): Promise<number>;
+function deleteManyBatched(db: AnyDb, table: WritableTable, where: WhereObject, options: DeleteManyBatchedOptions): Promise<DeleteManyBatchedResult>;
+function deleteManyBatched(db: ExecutorManagedWriteCapability, table: EntityTableMeta, where: WhereObject, options: DeleteManyBatchedOptions): Promise<DeleteManyBatchedResult>;
+function deleteManyBatched(db: AnyDb, table: WritableTable, where: WhereObject, options: DeleteManyBatchedOptions): Promise<DeleteManyBatchedResult>;
+function deleteManyBatched(db: ExecutorManagedWriteCapability, table: EntityTableMeta, where: WhereObject, options: DeleteManyBatchedOptions): Promise<DeleteManyBatchedResult>;
+function deleteManyBatched(db: AnyDb, table: WritableTable, where: WhereObject, options: DeleteManyBatchedOptions): Promise<DeleteManyBatchedResult>;
+function deleteManyBatched(db: ExecutorManagedWriteCapability, table: EntityTableMeta, where: WhereObject, options: DeleteManyBatchedOptions): Promise<DeleteManyBatchedResult>;
+function deriveEntityTableMeta(entityName: string, entity: EntityDefinition, options: BuildEntityTableMetaOptions & { source: "unmanaged"; }): EntityTableMeta & Writable; // Derive EntityTableMeta from an EntityDefinition (base columns + field DDL).
+function deriveEntityTableMeta(entityName: string, entity: EntityDefinition, options?: BuildEntityTableMetaOptions): EntityTableMeta;
+function deriveEntityTableMeta(entityName: string, entity: EntityDefinition, options: BuildEntityTableMetaOptions & { source: "unmanaged"; }): EntityTableMeta & Writable; // Derive EntityTableMeta from an EntityDefinition (base columns + field DDL).
+function deriveEntityTableMeta(entityName: string, entity: EntityDefinition, options?: BuildEntityTableMetaOptions): EntityTableMeta;
+function deriveEntityTableMeta(entityName: string, entity: EntityDefinition, options: BuildEntityTableMetaOptions & { source: "unmanaged"; }): EntityTableMeta & Writable; // Derive EntityTableMeta from an EntityDefinition (base columns + field DDL).
+function deriveEntityTableMeta(entityName: string, entity: EntityDefinition, options?: BuildEntityTableMetaOptions): EntityTableMeta;
+function encodeCursor(id: string | number): string;
+function encodeKeysetCursor(sortValue: string | null, id: string): string;
+function entityEventName(entityName: string, verb: EntityLifecycleVerb): string;
+function entityTableFromRegistry(registry: Registry, entityName: string, entity: Parameters<typeof buildEntityTable>[1]): SchemaTable;
+function enumerateFeatureTableSources(feature: FeatureDefinition): FeatureTableSource[];
+function executeRawQuery<T = Record<string, unknown>>(db: AnyDb, sqlText: string, params?: unknown[]): Promise<T[]>; // Escape hatch for caller-built SQL that may write (or lock).
+function extractPgError(e: unknown): PgErrorInfo | null;
+function extractTableInfo(table: TableLike): TableInfo;
+function extractTableName(table: unknown, context?): string; // Reads the `kumiko:schema:Name` symbol from a table object.
+function fetchOne<TRow = AnyRow>(db: AnyDb, table: TableLike, where: WhereObject): Promise<TRow | undefined>;
+function generateMigration(input: GenerateMigrationInput): GenerateMigrationOutput;
+function incrementCounter<TRow = AnyRow>(db: AnyDb, table: WritableTable, values: Record<string, unknown>, increments: Record<string, number>, options?: IncrementCounterOptions): Promise<TRow | undefined>;
+function incrementCounter<TRow = AnyRow>(db: ExecutorManagedWriteCapability, table: EntityTableMeta, values: Record<string, unknown>, increments: Record<string, number>, options?: IncrementCounterOptions): Promise<TRow | undefined>;
+function incrementCounter<TRow = AnyRow>(db: AnyDb, table: WritableTable, values: Record<string, unknown>, increments: Record<string, number>, options?: IncrementCounterOptions): Promise<TRow | undefined>;
+function incrementCounter<TRow = AnyRow>(db: ExecutorManagedWriteCapability, table: EntityTableMeta, values: Record<string, unknown>, increments: Record<string, number>, options?: IncrementCounterOptions): Promise<TRow | undefined>;
+function incrementCounter<TRow = AnyRow>(db: AnyDb, table: WritableTable, values: Record<string, unknown>, increments: Record<string, number>, options?: IncrementCounterOptions): Promise<TRow | undefined>;
+function incrementCounter<TRow = AnyRow>(db: ExecutorManagedWriteCapability, table: EntityTableMeta, values: Record<string, unknown>, increments: Record<string, number>, options?: IncrementCounterOptions): Promise<TRow | undefined>;
+function index(name: string): IndexBuilder;
+function insertMany<TRow = AnyRow>(db: AnyDb, table: WritableTable, rows: ReadonlyArray<Record<string, unknown>>): Promise<TRow[]>;
+function insertMany<TRow = AnyRow>(db: ExecutorManagedWriteCapability, table: EntityTableMeta, rows: ReadonlyArray<Record<string, unknown>>): Promise<TRow[]>;
+function insertMany<TRow = AnyRow>(db: AnyDb, table: WritableTable, rows: ReadonlyArray<Record<string, unknown>>): Promise<TRow[]>;
+function insertMany<TRow = AnyRow>(db: ExecutorManagedWriteCapability, table: EntityTableMeta, rows: ReadonlyArray<Record<string, unknown>>): Promise<TRow[]>;
+function insertMany<TRow = AnyRow>(db: AnyDb, table: WritableTable, rows: ReadonlyArray<Record<string, unknown>>): Promise<TRow[]>;
+function insertMany<TRow = AnyRow>(db: ExecutorManagedWriteCapability, table: EntityTableMeta, rows: ReadonlyArray<Record<string, unknown>>): Promise<TRow[]>;
+function insertOnConflictDoNothing<TRow = AnyRow>(db: AnyDb, table: WritableTable, values: Record<string, unknown>, options?: InsertOnConflictDoNothingOptions): Promise<TRow | undefined>;
+function insertOnConflictDoNothing<TRow = AnyRow>(db: ExecutorManagedWriteCapability, table: EntityTableMeta, values: Record<string, unknown>, options?: InsertOnConflictDoNothingOptions): Promise<TRow | undefined>;
+function insertOnConflictDoNothing<TRow = AnyRow>(db: AnyDb, table: WritableTable, values: Record<string, unknown>, options?: InsertOnConflictDoNothingOptions): Promise<TRow | undefined>;
+function insertOnConflictDoNothing<TRow = AnyRow>(db: ExecutorManagedWriteCapability, table: EntityTableMeta, values: Record<string, unknown>, options?: InsertOnConflictDoNothingOptions): Promise<TRow | undefined>;
+function insertOnConflictDoNothing<TRow = AnyRow>(db: AnyDb, table: WritableTable, values: Record<string, unknown>, options?: InsertOnConflictDoNothingOptions): Promise<TRow | undefined>;
+function insertOnConflictDoNothing<TRow = AnyRow>(db: ExecutorManagedWriteCapability, table: EntityTableMeta, values: Record<string, unknown>, options?: InsertOnConflictDoNothingOptions): Promise<TRow | undefined>;
+function insertOne<TRow = AnyRow>(db: AnyDb, table: WritableTable, values: Record<string, unknown>): Promise<TRow | undefined>;
+function insertOne<TRow = AnyRow>(db: ExecutorManagedWriteCapability, table: EntityTableMeta, values: Record<string, unknown>): Promise<TRow | undefined>;
+function insertOne<TRow = AnyRow>(db: AnyDb, table: WritableTable, values: Record<string, unknown>): Promise<TRow | undefined>;
+function insertOne<TRow = AnyRow>(db: ExecutorManagedWriteCapability, table: EntityTableMeta, values: Record<string, unknown>): Promise<TRow | undefined>;
+function insertOne<TRow = AnyRow>(db: AnyDb, table: WritableTable, values: Record<string, unknown>): Promise<TRow | undefined>;
+function insertOne<TRow = AnyRow>(db: ExecutorManagedWriteCapability, table: EntityTableMeta, values: Record<string, unknown>): Promise<TRow | undefined>;
+function instant(name: string, opts?: { precision?: 0 | 1 | 2 | 3 | 4 | 5 | 6; }): ColumnBuilder<Temporal.Instant>;
+function instantToTimestamptzParam(instant: Temporal.Instant): string;
+function integer(name: string): ColumnBuilder<number>;
+function isTimestamptzType(pgType: string | undefined): boolean;
+function isUndefinedTable(e: unknown): boolean;
+function isUniqueViolation(e: unknown): boolean;
+function jsonb(name: string): ColumnBuilder<Record<string, unknown>>;
+function knownTablesOf(features: FeatureDefinition[]): KnownTables;
+function listEventTenantIds(db: AnyDb): Promise<string[]>;
+function loadSnapshotJson(path: string): Snapshot | null;
+function nullBlindIndexesForSubject(db: DbRunner, features: ReadonlyMap<string, FeatureDefinition>, subjectKey: string): Promise<void>;
+function outsideTransactionPoolOptionsFromEnv(env?: Readonly<Record<string, string | undefined>>): DbConnectionOptions;
+function physicalColumnName(table: Table, field: string): string;
+function primaryKey(opts: { columns: ColumnHandle[]; name?: string; }): PrimaryKeyDescriptor;
+function readDatabaseNow(db: TenantDb): Promise<Date>; // Postgres clock; inside a transaction `now()` is the transaction start, so repeated reads agree.
+function recordEventsOwnedExclusivelyByTenant(db: DbRunner, aggregateType: string, aggregateId: string, tenantId: string): Promise<boolean>;
+function recordRowExistsInTenant(db: DbRunner, features: ReadonlyMap<string, FeatureDefinition>, entityName: string, recordId: string, tenantId: string): Promise<boolean>;
+function recordRowOwningTenantId(db: DbRunner, features: ReadonlyMap<string, FeatureDefinition>, entityName: string, recordId: string): Promise<string | undefined>;
+function rehydrateMoney(row: Record<string, unknown>, entity: EntityDefinition): Record<string, unknown>; // Rehydrate two flat DB columns into a combined `{ amount, currency }` value.
+function renderTablesDdl(metas: EntityTableMeta[], options?: RenderDdlOptions): string[];
+function requireEntityTableMeta(table: unknown, tableName: string): EntityTableMeta;
+function rowLevelSecurityModeOf(db: unknown): RowLevelSecurityMode;
+function runInOwnTransaction<T>(tenantDb: TenantDb, fn: (txDb: TenantDb) => Promise<T>): Promise<T>;
+function runInSavepointIfSupported<T>(db: ExecutorManagedRunner, fn: (sp: ExecutorManagedRunner) => Promise<T>): Promise<T>;
+function runInSavepointIfSupported<T>(db: unknown, fn: (sp: DbRunner) => Promise<T>): Promise<T>;
+function runInSavepointIfSupported<T>(db: ExecutorManagedRunner, fn: (sp: ExecutorManagedRunner) => Promise<T>): Promise<T>;
+function runInSavepointIfSupported<T>(db: unknown, fn: (sp: DbRunner) => Promise<T>): Promise<T>;
+function runInSavepointIfSupported<T>(db: ExecutorManagedRunner, fn: (sp: ExecutorManagedRunner) => Promise<T>): Promise<T>;
+function runInSavepointIfSupported<T>(db: unknown, fn: (sp: DbRunner) => Promise<T>): Promise<T>;
+function runMigrationsFromDir(db: DbConnection, dir: string): Promise<ApplyResult>;
+function runnerCanBeginTransaction(db: unknown): boolean;
+function scopeTenantDbToTenant(db: TenantDb, tenantId: TenantId): TenantDb;
+function seedConfigValues<E extends EntityDefinition>(seeds: ConfigSeedDef[], table: EntityTable<E>, entity: E, registry: Registry, db: DbConnection, cipher?: EnvelopeCipher): Promise<{ created: number; skipped: number; }>; // Seed config values at boot time via the event-store executor.
+function seedReferenceData(defs: ReferenceDataDef[], registry: Registry, db: DbConnection): Promise<{ inserted: number; updated: number; }>; // Seed reference data at boot time.
+function selectInnerJoin<TLeft = Record<string, unknown>, TRight = Record<string, unknown>>(db: AnyDb, spec: InnerJoinSpec): Promise<InnerJoinRow<TLeft, TRight>[]>;
+function selectMany<TRow = AnyRow>(db: AnyDb, table: TableLike, where?: WhereObject, options?: SelectOptions): Promise<TRow[]>;
+function serial(name: string): ColumnBuilder<number>;
+function serverTimeoutOptionsFromEnv(env?: Readonly<Record<string, string | undefined>>): DbConnectionOptions;
+function sql(strings: TemplateStringsArray, ...values: unknown[]): SqlExpression;
+function subjectRowExistsInTenant(db: DbRunner, features: ReadonlyMap<string, FeatureDefinition>, subjectId: string, tenantId: string): Promise<boolean>;
+function table<TCols extends ColumnMap>(tableName: string, cols: TCols, optsFn?: (t: { [K in keyof TCols]: ColumnHandle; }) => Record<string, IndexOrPk> | ReadonlyArray<IndexOrPk>): WritableSchemaTable;
+function tableExists(db: DbConnection | DbTx, fullyQualifiedName: string): Promise<boolean>;
+function text(name: string): ColumnBuilder<string>;
+function timestamp(name: string, _opts?: { withTimezone?: boolean; mode?: "string" | "date"; }): ColumnBuilder<Temporal.Instant | string>;
+function toPostgresArrayLiteral(values: PostgresArrayElement[]): string;
+function transaction<T>(db: AnyDb, fn: (tx: DbTx) => Promise<T>): Promise<T>;
+function uniqueIndex(name: string): IndexBuilder;
+function unsafeReadRetrying<TRow>(db: AnyDb, sqlText: string, params: unknown[]): Promise<TRow[]>;
+function updateMany<TRow = AnyRow>(db: AnyDb, table: WritableTable, set: Record<string, unknown>, where: WhereObject): Promise<TRow[]>;
+function updateMany<TRow = AnyRow>(db: ExecutorManagedWriteCapability, table: EntityTableMeta, set: Record<string, unknown>, where: WhereObject): Promise<TRow[]>;
+function updateMany<TRow = AnyRow>(db: AnyDb, table: WritableTable, set: Record<string, unknown>, where: WhereObject): Promise<TRow[]>;
+function updateMany<TRow = AnyRow>(db: ExecutorManagedWriteCapability, table: EntityTableMeta, set: Record<string, unknown>, where: WhereObject): Promise<TRow[]>;
+function updateMany<TRow = AnyRow>(db: AnyDb, table: WritableTable, set: Record<string, unknown>, where: WhereObject): Promise<TRow[]>;
+function updateMany<TRow = AnyRow>(db: ExecutorManagedWriteCapability, table: EntityTableMeta, set: Record<string, unknown>, where: WhereObject): Promise<TRow[]>;
+function upsertByPk<TRow = AnyRow>(db: AnyDb, table: WritableTable, values: Record<string, unknown>, updateOnConflict?: Record<string, unknown>): Promise<TRow | undefined>;
+function upsertByPk<TRow = AnyRow>(db: ExecutorManagedWriteCapability, table: EntityTableMeta, values: Record<string, unknown>, updateOnConflict?: Record<string, unknown>): Promise<TRow | undefined>;
+function upsertByPk<TRow = AnyRow>(db: AnyDb, table: WritableTable, values: Record<string, unknown>, updateOnConflict?: Record<string, unknown>): Promise<TRow | undefined>;
+function upsertByPk<TRow = AnyRow>(db: ExecutorManagedWriteCapability, table: EntityTableMeta, values: Record<string, unknown>, updateOnConflict?: Record<string, unknown>): Promise<TRow | undefined>;
+function upsertByPk<TRow = AnyRow>(db: AnyDb, table: WritableTable, values: Record<string, unknown>, updateOnConflict?: Record<string, unknown>): Promise<TRow | undefined>;
+function upsertByPk<TRow = AnyRow>(db: ExecutorManagedWriteCapability, table: EntityTableMeta, values: Record<string, unknown>, updateOnConflict?: Record<string, unknown>): Promise<TRow | undefined>;
+function upsertOnConflict<TRow = AnyRow>(db: AnyDb, table: WritableTable, values: Record<string, unknown>, options: UpsertOnConflictOptions): Promise<TRow | undefined>;
+function upsertOnConflict<TRow = AnyRow>(db: ExecutorManagedWriteCapability, table: EntityTableMeta, values: Record<string, unknown>, options: UpsertOnConflictOptions): Promise<TRow | undefined>;
+function upsertOnConflict<TRow = AnyRow>(db: AnyDb, table: WritableTable, values: Record<string, unknown>, options: UpsertOnConflictOptions): Promise<TRow | undefined>;
+function upsertOnConflict<TRow = AnyRow>(db: ExecutorManagedWriteCapability, table: EntityTableMeta, values: Record<string, unknown>, options: UpsertOnConflictOptions): Promise<TRow | undefined>;
+function upsertOnConflict<TRow = AnyRow>(db: AnyDb, table: WritableTable, values: Record<string, unknown>, options: UpsertOnConflictOptions): Promise<TRow | undefined>;
+function upsertOnConflict<TRow = AnyRow>(db: ExecutorManagedWriteCapability, table: EntityTableMeta, values: Record<string, unknown>, options: UpsertOnConflictOptions): Promise<TRow | undefined>;
+function uuid(name: string): ColumnBuilder<string>;
+function withSessionAdvisoryLock<T>(db: AnyDb, key: number, fn: () => Promise<T>): Promise<T>;
+function writeSnapshotJson(path: string, snapshot: Snapshot): void;
+```
+
+## Constants
+
+```ts
+const DEFAULT_OUTSIDE_TRANSACTION_POOL_MAX: 3;
+const ROW_LEVEL_SECURITY_MODES: ["off", "on"];
+const WritePurposes: { retention: "retention"; erasure: "erasure"; };
+```
+
+## Types
+
+```ts
+type ColumnMeta = {
+  name: string;
+  pgType: PgType;
+  notNull: boolean;
+  defaultSql?: string;
+  primaryKey?: boolean;
+  identity?: boolean;
+  bigintJsMode?: "number" | "bigint";
+};
+type DbConnection = SQL | RawDbClient;
+type DbRow = Record<string, unknown>;
+type DbRunner = DbConnection | DbTx;
+type DbTx = TransactionSQL | RawDbClient;
+type EntityTable<E extends EntityDefinition = EntityDefinition> = TableColumns & BaseColumnsType<E> & SoftDeleteColumnsType & ColumnsForEntity<E["fields"]> & TenancyBrand<EntityTableTenancy<E>>;
+type EntityTableMeta = {
+  tableName: string;
+  columns: ColumnMeta[];
+  indexes: IndexMeta[];
+  compositePrimaryKey?: CompositePrimaryKeyMeta;
+  source: "managed" | "unmanaged";
+  piiSubjectFields?: string[];
+  tenancy?: "global";
+};
+type EventStoreExecutor<Row extends Record<string, unknown> = Record<string, unknown>> = {
+  create: (payload: Record<string, unknown>, user: SessionUser, db: TenantDb, options?: StreamTenantOption & { preSave?: PreSaveRunner; }) => Promise<WriteResult<SaveContext>>;
+  update: (payload: { id: EntityId; version?: number | undefined; changes: Record<string, unknown>; }, user: SessionUser, db: TenantDb, options?: StreamTenantOption & LockGuardOption & ParentVisibilityGateOption & { skipOptimisticLock?: boolean; ski…;
+  delete: (payload: { id: EntityId; }, user: SessionUser, db: TenantDb, options?: StreamTenantOption & LockGuardOption & ParentVisibilityGateOption) => Promise<WriteResult<DeleteContext>>;
+  forget: (payload: { id: EntityId; }, user: SessionUser, db: TenantDb, options?: StreamTenantOption & ParentVisibilityGateOption) => Promise<WriteResult<DeleteContext>>;
+  restore: (payload: { id: EntityId; }, user: SessionUser, db: TenantDb, options?: StreamTenantOption & ParentVisibilityGateOption) => Promise<WriteResult<SaveContext>>;
+  list: (payload: { cursor?: string | undefined; limit?: number | undefined; search?: string | undefined; sort?: string | undefined; sortDirection?: "asc" | "desc" | undefined; offset?: number | undefined; totalCount?: boolean | undefined; filter?…;
+  aggregate: (payload: ListAggregateRequest, user: SessionUser, db: TenantDb, runtimeOptions?: ListRuntimeOptions) => Promise<ListAggregateResult>; // Groups and measures over the same WHERE as `list` (filters, search, ownership, field-read gates); paging and sort are ignored.
+  detail: (payload: { id: EntityId; }, user: SessionUser, db: TenantDb, options?: { parentVisibility?: ParentVisibilityOption; }) => Promise<Row | null>;
+};
+type ExecutorManagedRunner = DbRunner & ExecutorManagedWriteCapability;
+type ExecutorManagedTenantDb = TenantDbNonWrites & TenantDbWrites<EntityTableMeta> & ExecutorManagedWriteCapability;
+type JsonTextMatch = {
+  keys: [ string, ...string[] ]; // Top-level keys, tried in order; the first non-null text value is compared (COALESCE).
+  eq: string;
+};
+type KnownTables = {
+  has: (tableName: string) => boolean;
+};
+type MoneyRead = { // Shape of a single rehydrated money field — {amount major, currency, amountScaled exact integer value in MINOR_UNIT_SCALE units}.
+  amount: number;
+  currency: string;
+  amountScaled: number;
+  amountMinor: number;
+};
+type RowLevelSecurityMode = (typeof ROW_LEVEL_SECURITY_MODES)[number];
+type RowLevelSecurityScope =
+  | {
+    kind: "tenant";
+    tenantId: TenantId;
+  }
+  | {
+    kind: "system";
+    reason: string;
+  }
+;
+type SchemaTable = EntityTableMeta & {
+  [KUMIKO_NAME_SYMBOL]: string;
+  [KUMIKO_COLUMNS_SYMBOL]: Record<string, ColumnHandle>;
+  [KUMIKO_META_SYMBOL]: EntityTableMeta;
+  [field: string]: unknown;
+};
+type SelectOptions = {
+  limit?: number;
+  fields?: string[];
+  orderBy?: OrderByClause | OrderByClause[];
+  distinctOn?: [ string, ...string[] ];
+};
+type TableInfo = {
+  name: string;
+  columnOf: (field: string) => string;
+  pgTypeOf: (column: string) => string | undefined;
+  bigintJsModeOf: (column: string) => "number" | "bigint" | undefined;
+  fieldOf: (column: string) => string;
+  hasColumn: (fieldOrColumn: string) => boolean;
+};
+type TenantDb = TenantDbNonWrites & TenantDbWrites<WritableTable>;
+type UncheckedSystemDb = {
+  [SYSTEM_SCOPE_CHECK_BRAND]: true;
+  assertTenantMatch(tenantId: TenantId): TenantDb;
+  assertRowsTenant<T>(rows: T[], tenantField: keyof T): T[];
+  acknowledgeCrossTenant(reason: string): TenantDb;
+  unsafeRaw(reason: string): DbRunner; // Raw unfiltered DbRunner, gated behind a mandatory non-empty `reason` for auditability.
+  outsideTransaction: {
+    assertTenantMatch(tenantId: TenantId): TenantDb;
+    acknowledgeCrossTenant(reason: string): TenantDb;
+  };
+};
+type WhereObject = Record<string, WhereValue | unknown>;
+type WritableSchemaTable = SchemaTable & Writable;
+type WritableTable = EntityTableMeta & Writable;
+type WritePurpose = (typeof WritePurposes)[keyof typeof WritePurposes];
+```