@cosmicdrift/kumiko-framework 0.367.0 → 0.369.0

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

@@ -35,8 +35,8 @@
 //   2. projection ({@link PiiBackfillOptions.resolveOwnerFromProjection}) —
 //      pre-owner-field-addition events don't carry it; read it from the
 //      entity's current projection row instead.
-//   2b. whenAbsent — the payload again, now falling back to the tenant key for
-//      fields that declare it.
+//   2b. whenAbsent — the payload again, now falling back to the tenant key (or
+//      the row's own record key for whenAbsent: "self") for fields that declare it.
 //   3. erase ({@link PiiBackfillOptions.eraseUnresolvableSubjects}) — still
 //      unresolvable (hard-deleted aggregate, no projection) → PII_ERASED_SENTINEL.
 //   Stages 2 and 3 are opt-in and off by default; without them an
@@ -48,13 +48,16 @@
 //   owner change made before owner transitions re-keyed the value). An owner
 //   cleared again (owner → none) is not recoverable from the projection: such
 //   values stay tenant-keyed, unlike the live path that keeps the last owner.
+//   For whenAbsent: "self" fields the same stage moves tenant-keyed ciphertext
+//   of a still-ownerless row under its record key (written before the field
+//   declared "self"); a later owner assignment keeps the created event
+//   record-keyed, like the tenant-keyed case.
 //
 // Snapshots of touched aggregates are dropped per batch (they may cache
 // plaintext); the next snapshotting load recreates them. AFTER a run, rebuild the
 // affected projections — applyEntityEvent materializes ciphertext AND the
 // blind-index columns, which keeps equality lookups (login by email) alive.
 import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
-import { asRawClient } from "../../bun-db/index.js";
 import { quoteIdent } from "../../crypto/ciphertext-pattern.js";
 import { configuredEventPiiCatalog } from "../../crypto/event-pii.js";
 import { isLocalKeyKmsAdapter, KeyErasedError, KeyNotFoundError, } from "../../crypto/kms-adapter.js";
@@ -62,6 +65,7 @@ import { isPlainUserOwnedField } from "../../crypto/owner-transition-rekey.js";
 import { configuredPiiSubjectKms, decryptPiiValueForSubject, encryptPiiValueForSubject, isPiiCiphertext, PII_ERASED_SENTINEL, piiCiphertextSubject, } from "../../crypto/pii-field-encryption.js";
 import { collectPiiEncryptedFields, nonEmptyString, resolveEventSubject, resolveSubjectForField, SubjectResolutionError, } from "../../crypto/subject-resolver.js";
 import { resolveTableName } from "../entity-table-meta.js";
+import { asRawClient } from "../query.js";
 import { tableExists } from "../schema-inspection.js";
 import { toSnakeCase } from "../table-builder.js";
 import { toPostgresArrayLiteral } from "./postgres-array-literal.js";
@@ -479,7 +483,7 @@ async function rekeyTenantKeyedValue(deps, target) {
         return { kind: "unchanged" };
     const keyedUnder = ciphertextSubjectOrNull(ciphertext);
     const userSubject = keyedUnder?.kind === "tenant" && keyedUnder.tenantId === target.tenantId
-        ? ownerOfTenantKeyedValue(target)
+        ? rekeyTargetOfTenantKeyedValue(target)
         : keyedUnder?.kind === "user"
             ? currentProjectionOwnerIfOther(target, keyedUnder.userId)
             : null;
@@ -505,12 +509,15 @@ async function rekeyTenantKeyedValue(deps, target) {
         throw e;
     }
 }
-// Strict chain (payload, then projection), never whenAbsent.
-function ownerOfTenantKeyedValue(target) {
+// Strict chain (payload, then projection) names the owner; an ownerless row of a
+// whenAbsent: "self" field falls through to its record key. A whenAbsent: "tenant"
+// result is the key the value already sits under — nothing to move.
+function rekeyTargetOfTenantKeyedValue(target) {
     const resolution = resolveOwnerSubject(target.entity, target.field, target.subjectSource, target.ownerFallback, target.projectionOwnerRow, target.tenantId, target.aggregateType);
-    return resolution.kind === "resolved" && resolution.subject.kind === "user"
-        ? resolution.subject
-        : null;
+    if (resolution.kind !== "resolved")
+        return null;
+    const { subject } = resolution;
+    return subject.kind === "user" || subject.kind === "record" ? subject : null;
 }
 // A value keyed under a previous owner moves to the owner the row has now. The
 // projection of the event's own tenant is authoritative here: the payload of

package/dist/db/queries/ddl.js

@@ -1,6 +1,6 @@
 import { asRawClient } from "../query.js";
 import { quoteTableIdent } from "./table-ops.js";
-// Generic DDL helpers used on the prod-boot path (stack/table-helpers.ts's
+// Generic DDL helpers used on the prod-boot path (db/table-push.ts's
 // unsafePushTables, event-consumer-state.ts's multi-instance backfill) —
 // split out of queries/test-stack.ts so a prod-boot import doesn't point at
 // a module named for test-only concerns (truncate/create/drop-database).

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

@@ -24,6 +24,8 @@ export type SubsequentEventInsertRow = {
     readonly id: string | bigint;
     readonly created_at: Date | string;
 };
+export type FirstEventInsertParams = Omit<SubsequentEventInsertParams, "expectedVersion">;
+export declare function insertFirstEventRow(db: AnyDb, params: FirstEventInsertParams): Promise<SubsequentEventInsertRow | undefined>;
 /** INSERT … SELECT … WHERE EXISTS predecessor — stays raw (typed builder can't express this). */
 export declare function insertSubsequentEventRow(db: AnyDb, params: SubsequentEventInsertParams): Promise<SubsequentEventInsertRow | undefined>;
 export declare function selectStreamMaxVersion(db: AnyDb, aggregateId: string, tenantId: string): Promise<number>;

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

@@ -135,6 +135,31 @@ function duplicateIdempotencyKeyErrorOr(e) {
     }
     return e;
 }
+// ON CONFLICT on the version index only: a lost race returns no row instead of
+// a 23505, which would abort the caller's transaction (25P02) and make the
+// current stream version unreadable. The idempotency index still raises 23505.
+export async function insertFirstEventRow(db, params) {
+    const rows = await asRawClient(db).unsafe(`INSERT INTO "kumiko_events" (
+       aggregate_id, aggregate_type, tenant_id, version,
+       type, event_version, payload, metadata, created_by, created_at
+     )
+     VALUES ($1::uuid, $2, $3::uuid, $4, $5, $6, $7::jsonb, $8::jsonb, $9,
+             COALESCE($10::timestamptz, now()))
+     ON CONFLICT (tenant_id, aggregate_id, version) DO NOTHING
+     RETURNING id, created_at`, [
+        params.aggregateId,
+        params.aggregateType,
+        params.tenantId,
+        params.newVersion,
+        params.type,
+        params.eventVersion,
+        params.payload,
+        params.metadata,
+        params.createdBy,
+        params.createdAt ?? null,
+    ]);
+    return rows[0];
+}
 /** INSERT … SELECT … WHERE EXISTS predecessor — stays raw (typed builder can't express this). */
 export async function insertSubsequentEventRow(db, params) {
     const rows = await asRawClient(db).unsafe(`INSERT INTO "kumiko_events" (
@@ -150,6 +175,7 @@ export async function insertSubsequentEventRow(db, params) {
          AND version = $10
          AND tenant_id = $3::uuid
      )
+     ON CONFLICT (tenant_id, aggregate_id, version) DO NOTHING
      RETURNING id, created_at`, [
         params.aggregateId,
         params.aggregateType,

package/dist/db/queries/test-stack.js

@@ -1,7 +1,7 @@
 import { asRawClient } from "../query.js";
 import { quoteTableIdent } from "./table-ops.js";
 // Re-exported for back-compat — the generic DDL helpers moved to ./ddl so
-// the prod-boot path (stack/table-helpers.ts, pipeline/event-consumer-state.ts)
+// the prod-boot path (db/table-push.ts, pipeline/event-consumer-state.ts)
 // doesn't import from a module named for test-only concerns.
 export { alterTableAddColumn, createIndexIfNotExists, executeDdlStatement } from "./ddl.js";
 export async function truncateTablesRestartIdentity(db, tableNames) {

package/dist/db/query.d.ts

@@ -1 +1,105 @@
-export { type AnyDb, aggregateWhere, asEntityTableMeta, asRawClient, coerceRow, countWhere, type DeleteManyBatchedOptions, type DeleteManyBatchedResult, deleteMany, deleteManyBatched, extractTableInfo, fetchOne, type IncrementCounterOptions, incrementCounter, insertMany, insertOne, type JsonTextMatch, type OrderByClause, runInNewTransaction, runInSavepoint, runInSavepointIfSupported, runnerCanBeginTransaction, type SelectOptions, selectMany, type TableInfo, transaction, type UpsertOnConflictOptions, unsafeReadRetrying, updateMany, upsertByPk, upsertOnConflict, type WhereObject, type WhereOperator, type WhereValue, } from "../bun-db/query.js";
+import type { AggregateRow, AggregateSpec } from "@cosmicdrift/kumiko-types/aggregate-types";
+import type { DbRunner, DbTx } from "@cosmicdrift/kumiko-types/db-connection";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import type { SelectOptions, WhereObject } from "@cosmicdrift/kumiko-types/where-clause-types";
+import type { EntityTableMeta } from "./entity-table-meta.js";
+import { type NotExecutorOnly } from "./table-builder.js";
+import { asEntityTableMeta, requireEntityTableMeta } from "./table-introspection.js";
+export { asEntityTableMeta, requireEntityTableMeta };
+export type ReservedClient = {
+    unsafe: RawClient["unsafe"];
+    release: () => unknown;
+};
+export type RawClient = {
+    unsafe: <TRow = unknown>(sql: string, params?: readonly unknown[]) => Promise<readonly TRow[]>;
+    begin?: <T>(fn: (tx: DbTx) => Promise<T>) => Promise<T>;
+    savepoint?: <T>(fn: (sp: unknown) => Promise<T>) => Promise<T>;
+    release?: unknown;
+    reserve?: () => Promise<ReservedClient>;
+};
+export type RawClientWithBegin = RawClient & {
+    begin: NonNullable<RawClient["begin"]>;
+};
+export declare function hasBegin(client: RawClient): client is RawClientWithBegin;
+export declare function asRawClient(db: unknown): RawClient;
+export declare function runnerCanBeginTransaction(db: unknown): boolean;
+export declare function runInSavepoint<T>(tx: unknown, fn: (sp: unknown) => Promise<T>): Promise<T>;
+export declare function runInSavepointIfSupported<T>(db: unknown, fn: (sp: DbRunner) => Promise<T>): Promise<T>;
+export type AnyDb = DbRunner | unknown;
+export type { JsonTextMatch, OrderByClause, SelectOptions, WhereObject, WhereOperator, WhereValue, } from "@cosmicdrift/kumiko-types/where-clause-types";
+type TableLike = EntityTableMeta | any;
+type WritableTable = EntityTableMeta & NotExecutorOnly;
+export type TableInfo = {
+    readonly name: string;
+    readonly columnOf: (field: string) => string;
+    readonly pgTypeOf: (column: string) => string | undefined;
+    readonly bigintJsModeOf: (column: string) => "number" | "bigint" | undefined;
+    readonly fieldOf: (column: string) => string;
+    readonly hasColumn: (fieldOrColumn: string) => boolean;
+};
+export declare function extractTableInfo(table: TableLike): TableInfo;
+export declare function coerceRow<TOut = Record<string, unknown>>(row: Record<string, unknown>, info: TableInfo): TOut;
+export declare function instantToTimestamptzParam(instant: Temporal.Instant): string;
+export declare function isClosedConnectionError(err: unknown): boolean;
+export declare function describeClosedConnectionFailure(raw: unknown, err: unknown, attempts: number): Record<string, unknown> | undefined;
+export declare function unsafeReadRetrying<TRow>(db: AnyDb, sqlText: string, params: readonly unknown[]): Promise<readonly TRow[]>;
+export declare function selectMany<TRow = any>(db: AnyDb, table: TableLike, where?: WhereObject, options?: SelectOptions): Promise<readonly TRow[]>;
+export declare function fetchOne<TRow = any>(db: AnyDb, table: TableLike, where: WhereObject): Promise<TRow | undefined>;
+export type JoinColumnPair = {
+    readonly left: string;
+    readonly right: string;
+};
+export type InnerJoinSpec = {
+    readonly left: TableLike;
+    readonly right: TableLike;
+    readonly on: readonly [JoinColumnPair, ...JoinColumnPair[]];
+    readonly leftWhere?: WhereObject;
+    readonly rightWhere?: WhereObject;
+    /** Fields to return per side; default: all columns of `left`, none of `right`. */
+    readonly leftFields?: readonly string[];
+    readonly rightFields?: readonly string[];
+    readonly limit?: number;
+};
+export type InnerJoinRow<TLeft, TRight> = {
+    readonly left: TLeft;
+    readonly right: TRight;
+};
+export declare function selectInnerJoin<TLeft = Record<string, unknown>, TRight = Record<string, unknown>>(db: AnyDb, spec: InnerJoinSpec): Promise<readonly InnerJoinRow<TLeft, TRight>[]>;
+export declare function insertMany<TRow = any>(db: AnyDb, table: WritableTable, rows: ReadonlyArray<Record<string, unknown>>): Promise<readonly TRow[]>;
+export declare function insertOne<TRow = any>(db: AnyDb, table: WritableTable, values: Record<string, unknown>): Promise<TRow | undefined>;
+export declare function updateMany<TRow = any>(db: AnyDb, table: WritableTable, set: Record<string, unknown>, where: WhereObject): Promise<readonly TRow[]>;
+export declare function deleteMany(db: AnyDb, table: WritableTable, where: WhereObject): Promise<void>;
+export declare function resolveConflictColumns(table: TableLike, info: TableInfo, conflictKeys: readonly string[] | undefined): readonly string[];
+export type UpsertOnConflictOptions = {
+    readonly conflictKeys: readonly string[];
+    /** Columns to set on conflict. Default: EXCLUDED for every inserted non-key column. */
+    readonly update?: Record<string, unknown>;
+};
+export type DeleteManyBatchedOptions = {
+    readonly limit: number;
+    readonly maxBatches?: number;
+    /** Row id field for the LIMIT subquery. Default `id`. */
+    readonly idColumn?: string;
+};
+export type DeleteManyBatchedResult = {
+    readonly deleted: number;
+    readonly batches: number;
+};
+export declare function countWhere(db: AnyDb, table: TableLike, where?: WhereObject): Promise<number>;
+export declare function isTimestamptzType(pgType: string | undefined): boolean;
+export declare function aggregateWhere(db: AnyDb, table: TableLike, spec: AggregateSpec, where?: WhereObject): Promise<readonly AggregateRow[]>;
+export declare function upsertOnConflict<TRow = any>(db: AnyDb, table: WritableTable, values: Record<string, unknown>, options: UpsertOnConflictOptions): Promise<TRow | undefined>;
+export declare function upsertByPk<TRow = any>(db: AnyDb, table: WritableTable, values: Record<string, unknown>, updateOnConflict?: Record<string, unknown>): Promise<TRow | undefined>;
+export type InsertOnConflictDoNothingOptions = {
+    readonly conflictKeys?: readonly string[];
+};
+export declare function insertOnConflictDoNothing<TRow = any>(db: AnyDb, table: WritableTable, values: Record<string, unknown>, options?: InsertOnConflictDoNothingOptions): Promise<TRow | undefined>;
+export type IncrementCounterOptions = {
+    readonly conflictKeys?: readonly string[];
+    /** Extra SET clauses on conflict (e.g. lastUpdatedAt: sql\`NOW()\`). */
+    readonly set?: Record<string, unknown>;
+};
+export declare function incrementCounter<TRow = any>(db: AnyDb, table: WritableTable, values: Record<string, unknown>, increments: Record<string, number>, options?: IncrementCounterOptions): Promise<TRow | undefined>;
+export declare function deleteManyBatched(db: AnyDb, table: WritableTable, where: WhereObject, options: DeleteManyBatchedOptions): Promise<DeleteManyBatchedResult>;
+export declare function transaction<T>(db: AnyDb, fn: (tx: DbTx) => Promise<T>): Promise<T>;
+export declare function runInNewTransaction<T>(db: unknown, fn: (tx: DbRunner) => Promise<T>): Promise<T>;