@cosmicdrift/kumiko-framework 0.354.0 → 0.354.1

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

@@ -6,7 +6,7 @@ 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 { getStreamVersion } from "../event-store/index.js";
+import { getStreamVersion, getStreamVersions } 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";
@@ -64,6 +64,9 @@ function toCursorSortText(value) {
     }
     return undefined;
 }
+function withStreamVersion(row, streamVersion) {
+    return streamVersion > 0 ? { ...row, version: streamVersion } : row;
+}
 // Keyset boundary for `ORDER BY <sort> <dir>, id ASC` under Postgres' DEFAULT
 // null ordering (ASC → NULLS LAST, DESC → NULLS FIRST). An explicit NULLS clause
 // would change the visible order and cost the sort its index.
@@ -661,11 +664,17 @@ export function createReadVerbs(ctx) {
             // field (ciphertext leaked to the caller).
             const tableInfo = extractTableInfo(table);
             const encryptedRows = rawRows.map((r) => rehydrateCompoundTypes(coerceRow(r, tableInfo), entity));
-            const rows = await Promise.all(encryptedRows.map((r) => decryptForRead(r)));
-            // list rows carry the READ-ROW version (display-only), never an optimistic-lock
-            // base — edit flows reload via detail(), which reconciles the stream version.
-            // Cache the still-encrypted form: same at-rest guarantee as detail()'s
-            // encryptForStorage round-trip, without paying a re-encrypt.
+            const decryptedRows = await Promise.all(encryptedRows.map((r) => decryptForRead(r)));
+            // Stream version is authoritative (see detail()): ctx.appendEvent bumps the
+            // stream without touching row.version, so the raw row version would hand
+            // clients a stale optimistic-lock base. Rows without events keep theirs.
+            const streamVersions = decryptedRows.length > 0
+                ? await getStreamVersions(runner, decryptedRows.map((r) => String(r["id"])), streamTenantFor(user))
+                : new Map();
+            const rows = decryptedRows.map((r) => withStreamVersion(r, streamVersions.get(String(r["id"])) ?? 0));
+            // Cache the still-encrypted raw rows (read-row version): same at-rest guarantee as
+            // detail()'s encryptForStorage round-trip, without a re-encrypt; detail() rejects
+            // a cached version that differs from the stream.
             if (entityCache && entityName && rows.length > 0) {
                 await entityCache.mset(user.tenantId, entityName, encryptedRows.map((r) => ({ id: r["id"], data: r })));
             }
@@ -718,7 +727,6 @@ export function createReadVerbs(ctx) {
             // guaranteed version_conflict.
             // A cache hit only counts when its version equals the live stream version:
             // a late entityCache.set() can resurrect an old row after the writer's del().
-            const withVersion = (row, streamVersion) => (streamVersion > 0 ? { ...row, version: streamVersion } : row);
             if (entityCache && entityName) {
                 const cached = await entityCache.get(user.tenantId, entityName, payload.id);
                 if (cached) {
@@ -736,7 +744,7 @@ export function createReadVerbs(ctx) {
                         // Cached rows are stored re-encrypted (see the `set` below) so an
                         // `encrypted` field's plaintext never sits in a second at-rest
                         // store (Redis) the field-encryption feature doesn't cover.
-                        return withVersion(await decryptForRead(cached), streamVersion);
+                        return withStreamVersion(await decryptForRead(cached), streamVersion);
                     }
                 }
             }
@@ -748,7 +756,7 @@ export function createReadVerbs(ctx) {
             // is snake_case (raw SQL); coerceRow maps it to camelCase.
             const rowInfo = extractTableInfo(table);
             const coerced = await decryptForRead(rehydrateCompoundTypes(coerceRow(raw, rowInfo), entity));
-            const result = withVersion(coerced, snapshot.streamVersion);
+            const result = withStreamVersion(coerced, snapshot.streamVersion);
             if (entityCache && entityName) {
                 await entityCache.set(user.tenantId, entityName, payload.id, await encryptForStorage(result, user));
             }

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

@@ -27,6 +27,7 @@ export type SubsequentEventInsertRow = {
 /** 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>;
+export declare function selectStreamMaxVersions(db: AnyDb, aggregateIds: readonly string[], tenantId: string): Promise<Map<string, number>>;
 /** MAX(version) for one aggregate stream — no tenant filter (seed idempotency). */
 export declare function selectAggregateMaxVersion(db: AnyDb, aggregateId: string): Promise<number>;
 export declare function selectEventsHighWaterMark(db: AnyDb): Promise<bigint>;

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

@@ -171,6 +171,17 @@ export async function selectStreamMaxVersion(db, aggregateId, tenantId) {
     const rows = await unsafeReadRetrying(db, `SELECT MAX("version") AS v FROM "kumiko_events" WHERE "aggregate_id" = $1 AND "tenant_id" = $2`, [aggregateId, tenantId]);
     return rows[0]?.v ?? 0;
 }
+export async function selectStreamMaxVersions(db, aggregateIds, tenantId) {
+    const versions = new Map();
+    if (aggregateIds.length === 0)
+        return versions;
+    const rows = await unsafeReadRetrying(db, `SELECT "aggregate_id" AS id, MAX("version") AS v FROM "kumiko_events" WHERE "tenant_id" = $1 AND "aggregate_id" = ANY($2::uuid[]) GROUP BY "aggregate_id"`, [tenantId, [...aggregateIds]]);
+    for (const row of rows) {
+        if (row.v !== null)
+            versions.set(row.id, row.v);
+    }
+    return versions;
+}
 /** MAX(version) for one aggregate stream — no tenant filter (seed idempotency). */
 export async function selectAggregateMaxVersion(db, aggregateId) {
     const rows = await unsafeReadRetrying(db, `SELECT MAX("version") AS v FROM "kumiko_events" WHERE "aggregate_id" = $1`, [aggregateId]);

package/dist/engine/schema-builder.js

@@ -406,6 +406,38 @@ export function buildInsertSchema(entity, currencies = [...DEFAULT_CURRENCIES],
     }
     return applyTotalsMatchRefinements(entity, z.object(shape));
 }
+// Field types whose column is nullable and whose projection write accepts a
+// plain `null`. Excluded: select/writeOnly text (fieldToZod is already
+// nullable there), and types where null would not clear cleanly — NOT NULL
+// jsonb columns (multiSelect, embedded, jsonb, multi reference), files/images
+// (no column; stripped from updates), locatedTimestamp (split into _utc/_tz
+// columns, a bare null targets a column that does not exist) and money (the
+// currency column would keep its stale value).
+const NULL_CLEARABLE_FIELD_TYPES = new Set([
+    "text",
+    "longText",
+    "boolean",
+    "number",
+    "bigInt",
+    "decimal",
+    "reference",
+    "date",
+    "timestamp",
+    "tz",
+    "file",
+    "image",
+]);
+function isClearableByNull(field) {
+    if (!NULL_CLEARABLE_FIELD_TYPES.has(field.type))
+        return false;
+    if (field.type === "reference" && field.multiple === true)
+        return false;
+    if (field.type === "text" && field.writeOnly === true)
+        return false;
+    const isRequired = "required" in field && field.required === true;
+    const hasDefault = "default" in field && field.default !== undefined;
+    return !isRequired && !hasDefault;
+}
 export function buildUpdateSchema(entity, currencies = [...DEFAULT_CURRENCIES], excludedFields = []) {
     const shape = {};
     for (const [name, field] of Object.entries(entity.fields)) {
@@ -421,10 +453,11 @@ export function buildUpdateSchema(entity, currencies = [...DEFAULT_CURRENCIES],
         // fieldToZod still knows the default for its "" → default mapping
         // (e.g. select) — applyDefaults: false only suppresses the schema-level
         // `.default(...)` fallback for a genuinely omitted key.
-        shape[name] = fieldToZod(field, currencies, {
+        const zodField = fieldToZod(field, currencies, {
             applyDefaults: false,
             isUpdate: true,
-        }).optional();
+        });
+        shape[name] = (isClearableByNull(field) ? zodField.nullable() : zodField).optional();
     }
     return applyTotalsMatchRefinements(entity, z.object(shape));
 }

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

@@ -24,6 +24,7 @@ export declare function loadAggregateAsOf(db: DbRunner, aggregateId: string, ten
     readonly includeArchived?: boolean;
 }): Promise<readonly StoredEvent[]>;
 export declare function getStreamVersion(db: DbRunner, aggregateId: string, tenantId: TenantId): Promise<number>;
+export declare function getStreamVersions(db: DbRunner, aggregateIds: readonly string[], tenantId: TenantId): Promise<Map<string, number>>;
 /** MAX(version) for one aggregate — no tenant filter. SECURITY: existence-oracle,
  *  a caller can probe whether an aggregateId has any events regardless of tenant
  *  membership. Only call from seed/system-internal paths (idempotency checks

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

@@ -4,7 +4,7 @@ import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { requestContext } from "../api/request-context.js";
 import { encryptEventPayloadPii } from "../crypto/event-pii.js";
 import { constraintOf, isUniqueViolation } from "../db/pg-error.js";
-import { claimXactId, insertSubsequentEventRow, notifyPgChannel, runAtomicEventWrite, selectAggregateMaxVersion, selectEventsHighWaterMark, selectStreamMaxVersion, } from "../db/queries/event-store.js";
+import { claimXactId, insertSubsequentEventRow, notifyPgChannel, runAtomicEventWrite, selectAggregateMaxVersion, selectEventsHighWaterMark, selectStreamMaxVersion, selectStreamMaxVersions, } from "../db/queries/event-store.js";
 import { insertOne, selectMany } from "../db/query.js";
 import { isStreamArchived } from "./archive.js";
 import { IdempotentAppendConflictError, VersionConflictError } from "./errors.js";
@@ -223,6 +223,9 @@ export async function loadAggregateAsOf(db, aggregateId, tenantId, asOf, options
 export async function getStreamVersion(db, aggregateId, tenantId) {
     return selectStreamMaxVersion(db, aggregateId, tenantId);
 }
+export async function getStreamVersions(db, aggregateIds, tenantId) {
+    return selectStreamMaxVersions(db, aggregateIds, tenantId);
+}
 /** MAX(version) for one aggregate — no tenant filter. SECURITY: existence-oracle,
  *  a caller can probe whether an aggregateId has any events regardless of tenant
  *  membership. Only call from seed/system-internal paths (idempotency checks

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

@@ -2,7 +2,7 @@ export { APP_INSTANCE_STREAM_TYPE, APP_STARTED_EVENT_TYPE } from "../crypto/syst
 export { backfillEventPiiEncryption, backfillEventPiiEncryptionBatch, type PiiBackfillBatchOptions, type PiiBackfillBatchResult, type PiiBackfillFailure, type PiiBackfillOptions, type PiiBackfillResult, type PiiBackfillScanCache, } from "../db/queries/backfill-pii.js";
 export { type ArchiveStreamArgs, archivedStreamsTable, archiveStream, createArchivedStreamsTable, isStreamArchived, restoreStream, } from "./archive.js";
 export { ArchivedStreamError, IdempotentAppendConflictError, VersionConflictError, } from "./errors.js";
-export { append, EVENTS_PUBSUB_CHANNEL, type EventMetadata, type EventToAppend, getEventsHighWaterMark, getStreamVersion, getUnscopedAggregateStreamMaxVersion, getUnscopedStreamMaxVersionForSeed, LOAD_ALL_EVENTS_ROW_LIMIT, loadAggregate, loadAggregateAsOf, loadAllEventsByType, loadEventsAfterVersion, type StoredEvent, streamAllEventsByType, } from "./event-store.js";
+export { append, EVENTS_PUBSUB_CHANNEL, type EventMetadata, type EventToAppend, getEventsHighWaterMark, getStreamVersion, getStreamVersions, getUnscopedAggregateStreamMaxVersion, getUnscopedStreamMaxVersionForSeed, LOAD_ALL_EVENTS_ROW_LIMIT, loadAggregate, loadAggregateAsOf, loadAllEventsByType, loadEventsAfterVersion, type StoredEvent, streamAllEventsByType, } from "./event-store.js";
 export { createEventsTable, eventsTable } from "./events-schema.js";
 export { appendProvenanceEvent, type ProvenanceEventInput } from "./provenance-append.js";
 export { createRebuildDeadLetterTable, listRebuildDeadLetters, type RebuildDeadLetterRow, rebuildDeadLetterTable, recordRebuildDeadLetters, type SkippedApply, } from "./rebuild-dead-letter.js";

package/dist/event-store/index.js

@@ -2,7 +2,7 @@ export { APP_INSTANCE_STREAM_TYPE, APP_STARTED_EVENT_TYPE } from "../crypto/syst
 export { backfillEventPiiEncryption, backfillEventPiiEncryptionBatch, } from "../db/queries/backfill-pii.js";
 export { archivedStreamsTable, archiveStream, createArchivedStreamsTable, isStreamArchived, restoreStream, } from "./archive.js";
 export { ArchivedStreamError, IdempotentAppendConflictError, VersionConflictError, } from "./errors.js";
-export { append, EVENTS_PUBSUB_CHANNEL, getEventsHighWaterMark, getStreamVersion, getUnscopedAggregateStreamMaxVersion, getUnscopedStreamMaxVersionForSeed, LOAD_ALL_EVENTS_ROW_LIMIT, loadAggregate, loadAggregateAsOf, loadAllEventsByType, loadEventsAfterVersion, streamAllEventsByType, } from "./event-store.js";
+export { append, EVENTS_PUBSUB_CHANNEL, getEventsHighWaterMark, getStreamVersion, getStreamVersions, getUnscopedAggregateStreamMaxVersion, getUnscopedStreamMaxVersionForSeed, LOAD_ALL_EVENTS_ROW_LIMIT, loadAggregate, loadAggregateAsOf, loadAllEventsByType, loadEventsAfterVersion, streamAllEventsByType, } from "./event-store.js";
 export { createEventsTable, eventsTable } from "./events-schema.js";
 export { appendProvenanceEvent } from "./provenance-append.js";
 export { createRebuildDeadLetterTable, listRebuildDeadLetters, rebuildDeadLetterTable, recordRebuildDeadLetters, } from "./rebuild-dead-letter.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.354.0",
+  "version": "0.354.1",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -210,8 +210,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.354.0",
-    "@cosmicdrift/kumiko-types": "0.354.0",
+    "@cosmicdrift/kumiko-http": "0.354.1",
+    "@cosmicdrift/kumiko-types": "0.354.1",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -227,7 +227,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.354.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.354.1",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,15 @@
 [
+  {
+    "version": "0.354.1",
+    "type": "fix",
+    "title": "Executor list returns the stream version, so updates built on list rows no longer fail with version_conflict after ctx.appendEvent"
+  },
+  {
+    "version": "0.354.1",
+    "type": "fix",
+    "title": "Update schema accepts null on optional fields, so a preSave hook or client can clear a stored optional value",
+    "detail": "Update schema accepts null on optional fields, so a preSave hook or client can clear a stored optional value without presave_hook_invalid_output or a validation error"
+  },
   {
     "version": "0.354.0",
     "type": "fix",