@cosmicdrift/kumiko-framework 0.338.0 → 0.340.0

package/dist/engine/steps/workflow-system-events.js

@@ -0,0 +1,89 @@
+// Registered-event declarations for the `kumiko:system:workflow.*` run-stream
+// events. The names stay the literal system types stored in kumiko_events;
+// registering them makes projections (r.extendEntityProjection / r.projection
+// with source `workflow-run`) valid apply-key targets and lists them in the
+// registry's event catalog.
+//
+// Appends of these types keep bypassing schema validation (append-event-core):
+// the schemas here document the payloads the writers append and tolerate the
+// legacy shapes still stored in old streams.
+import * as z from "zod";
+import { SYSTEM_EVENT_PII_STANCES } from "../../crypto/system-event-pii.js";
+import { WORKFLOW_RESUMED_TYPE, WORKFLOW_RETRY_SCHEDULED_TYPE, WORKFLOW_RUN_COMPLETED_TYPE, WORKFLOW_RUN_FAILED_TYPE, WORKFLOW_RUN_STARTED_TYPE, WORKFLOW_WAITING_FOR_EVENT_TYPE, WORKFLOW_WAITING_TYPE, } from "./_step-dispatch-constants.js";
+const triggerEventRefSchema = z.object({
+    eventId: z.string(),
+    aggregateId: z.string(),
+    version: z.number().int(),
+});
+// Optional on every step event: runs started before the Q7 fingerprint existed
+// have none.
+const stepContext = {
+    workflowName: z.string(),
+    stepIndex: z.number().int(),
+    triggerEventType: z.string(),
+    definitionFingerprint: z.string().optional(),
+};
+const WORKFLOW_SYSTEM_EVENT_SCHEMAS = [
+    [
+        WORKFLOW_RUN_STARTED_TYPE,
+        z.object({
+            workflowName: z.string(),
+            triggerEventType: z.string(),
+            // Current streams reference the trigger event; streams written before
+            // #3474 carry a copy of its payload instead.
+            triggerEventRef: triggerEventRefSchema.optional(),
+            triggerPayload: z.unknown().optional(),
+            definitionFingerprint: z.string().optional(),
+            idempotencyKey: z.string().optional(),
+        }),
+    ],
+    [
+        WORKFLOW_RUN_COMPLETED_TYPE,
+        z.object({ workflowName: z.string(), stepIndex: z.number().int() }),
+    ],
+    [
+        WORKFLOW_RUN_FAILED_TYPE,
+        z.object({
+            workflowName: z.string(),
+            stepIndex: z.number().int(),
+            error: z.string(),
+            reason: z.string().optional(),
+        }),
+    ],
+    [WORKFLOW_WAITING_TYPE, z.object({ ...stepContext, wakeAt: z.string() })],
+    [
+        WORKFLOW_WAITING_FOR_EVENT_TYPE,
+        z.object({
+            ...stepContext,
+            eventType: z.string(),
+            match: z.record(z.string(), z.unknown()).optional(),
+            timeoutAt: z.string(),
+        }),
+    ],
+    [
+        WORKFLOW_RESUMED_TYPE,
+        z.object({ stepIndex: z.number().int(), retryAttempt: z.number().int().optional() }),
+    ],
+    [
+        WORKFLOW_RETRY_SCHEDULED_TYPE,
+        z.object({
+            ...stepContext,
+            attempt: z.number().int(),
+            maxAttempts: z.number().int(),
+            wakeAt: z.string(),
+            error: z.string(),
+        }),
+    ],
+];
+function buildWorkflowSystemEventDefs() {
+    const defs = new Map();
+    for (const [name, schema] of WORKFLOW_SYSTEM_EVENT_SCHEMAS) {
+        const piiFields = SYSTEM_EVENT_PII_STANCES.get(name);
+        if (piiFields === undefined) {
+            throw new Error(`Workflow system event "${name}" has no entry in SYSTEM_EVENT_PII_STANCES`);
+        }
+        defs.set(name, { name, schema, version: 1, piiFields });
+    }
+    return defs;
+}
+export const WORKFLOW_SYSTEM_EVENT_DEFS = buildWorkflowSystemEventDefs();

package/dist/pipeline/append-event-core.d.ts

@@ -9,4 +9,6 @@ export type AppendDomainEventCoreDeps = {
     readonly callSiteLabel: string;
     readonly callerFeature?: string;
 };
-export declare function appendDomainEventCore(deps: AppendDomainEventCoreDeps, args: AppendEventArgs): Promise<StoredEvent>;
+export declare function appendDomainEventCore(deps: AppendDomainEventCoreDeps, args: AppendEventArgs & {
+    readonly expectedVersion?: number;
+}): Promise<StoredEvent>;

package/dist/pipeline/append-event-core.js

@@ -33,10 +33,12 @@ export async function appendDomainEventCore(deps, args) {
             });
         }
     }
-    // System events skip schema validation — payload shape is owned by the
-    // framework step that emits + the bundled MSP that consumes.
+    // System events skip schema validation even when registered (workflow
+    // events are, so projections can apply them): payload shape is owned by the
+    // framework step that emits + the bundled MSP that consumes, and stored
+    // streams keep legacy shapes. Parsing would also strip unknown keys.
     let validatedPayload;
-    if (eventDef) {
+    if (eventDef && !isSystemEvent) {
         const parsed = eventDef.schema.safeParse(args.payload ?? {});
         if (!parsed.success)
             throw validationErrorFromZod(parsed.error);
@@ -53,7 +55,9 @@ export async function appendDomainEventCore(deps, args) {
     }
     // Stream-version authoritative. See Block 0 / getStreamVersion doc for
     // why row.version isn't sufficient once ctx.appendEvent enters the picture.
-    const expectedVersion = await getStreamVersion(deps.db, args.aggregateId, deps.tenantId);
+    // A caller-pinned version (fetchForWriting handles) must reach append() so a
+    // write landing between fetch and append conflicts instead of being re-read.
+    const expectedVersion = args.expectedVersion ?? (await getStreamVersion(deps.db, args.aggregateId, deps.tenantId));
     const reqCtx = requestContext.get();
     // metadata.requestId is a plain trace marker — no uniqueness constraint,
     // every event of the request carries it. HTTP-level idempotency runs in

package/dist/pipeline/dispatch-shared.js

@@ -399,8 +399,10 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
                     currentVersion: fetchedVersion,
                 });
             }
-            // Handle's internal version bumps on every appendOne so multiple
-            // appends in a row stay in order without re-reading the DB.
+            // Pinned into every append: a write landing between fetch and append
+            // fails with VersionConflictError instead of stacking on a state the
+            // caller's business rules never saw. Bumps per appendOne so consecutive
+            // appends stay in order without re-reading the DB.
             let handleVersion = fetchedVersion;
             const appendOne = async (appendArgs) => {
                 await appendDomainEvent(ctx, {
@@ -408,6 +410,7 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
                     aggregateType: args.aggregateType,
                     type: appendArgs.type,
                     payload: appendArgs.payload,
+                    expectedVersion: handleVersion,
                 }, user, tx, registry.getHandlerFeature(type));
                 handleVersion += 1;
             };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.338.0",
+  "version": "0.340.0",
   "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>",
@@ -206,8 +206,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.338.0",
-    "@cosmicdrift/kumiko-types": "0.338.0",
+    "@cosmicdrift/kumiko-http": "0.340.0",
+    "@cosmicdrift/kumiko-types": "0.340.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -223,7 +223,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.338.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.340.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,52 @@
 [
+  {
+    "version": "0.340.0",
+    "type": "improvement",
+    "title": "Typed bun-db helpers for insert-ignore, inner joins, jsonb text filters and key-ordered aggregates",
+    "detail": "`insertOnConflictDoNothing(db, table, values, { conflictKeys? })` returns the inserted row, or `undefined` when the conflict target already exists. `selectInnerJoin(db, { left, right, on, leftWhere?, rightWhere?, leftFields?, rightFields?, limit? })` joins two tables on one or more column pairs (casting to text only when the column types differ) and returns `{ left, right }` rows; `rightFields` defaults to none, so secrets on the joined table are only read when named. The where operator `jsonText: { keys, eq }` compares `col->>key` on jsonb columns, with several keys combined through `COALESCE`. `aggregateWhere` accepts `orderByKeys: \"asc\" | \"desc\"` to sort groups by their key before `limit`. All identifiers come from the table metadata and all values are bound parameters. The helpers refuse tenant-scoped tables like the other raw-connection helpers; use the `TenantDb` methods there.",
+    "migration": "keine"
+  },
+  {
+    "version": "0.339.0",
+    "type": "improvement",
+    "title": "Write handlers can declare tenantlessAnonymous",
+    "detail": "`r.writeHandler({ ..., tenantlessAnonymous: true })` lets an anonymous `POST /api/write` for exactly that handler run under `SYSTEM_TENANT_ID` where the anonymous middleware would otherwise answer `400 tenant_required` (resolver silent, no client tenant). It never applies to `/api/batch`, to a client-supplied `X-Tenant` or `kumiko_tenant`, to `tenant_mismatch` or when a tenant resolved; `tenantExists` and the lifecycle gate are skipped for the system tenant. Boot rejects the flag unless `access.roles` is exactly `[\"anonymous\"]` and a real `rateLimit` (not `{ disabled: true }`) is declared. `authMiddleware` gets the option `isTenantlessAnonymousWrite`, which `buildServer` builds from the registry.",
+    "migration": "keine"
+  },
+  {
+    "version": "0.339.0",
+    "type": "breaking",
+    "title": "fetchForWriting handles reject appends after a concurrent write",
+    "migration": "Appends through a ctx.fetchForWriting handle now use the version the handle was read at. When two requests write the same aggregate concurrently, the later append no longer stacks on top silently: the request fails with 409 version_conflict (no automatic retry), and its transaction rolls back. Tests that fire concurrent writes on one aggregate and expected both to succeed must expect exactly one success. Clients should treat 409 version_conflict like a stale form: reload and retry."
+  },
+  {
+    "version": "0.339.0",
+    "type": "improvement",
+    "title": "PII encryption for jsonb fields",
+    "detail": "`createJsonbField({ personal: \"tenant\" })` (or `\"self\"` / `{ of }`) is encrypted per subject like a text field, so crypto-shredding applies: after the key is erased, list and detail return `[[erased]]` for the field. The ciphertext uses the self-describing format `kumiko-pii:v3:` (v2 plus a JSON-typed plaintext, AAD-bound to subject and field), so a string, number or object round-trips by type. Existing plaintext objects, arrays and strings are read as-is and are not re-encrypted; they become ciphertext on the next write of the field, and the backfill skips jsonb fields. There is no search, filter, sort or index inside an encrypted jsonb field: boot rejects `personal` on a jsonb field that is in an entity index, has `sortable`, `filterable`, `searchable` or `lookupable`, or is the custom-fields `customFields` column. Event payload fields declared in `piiFields` may now be objects or arrays; they are encrypted in the same JSON format. Non-jsonb fields still require a string.",
+    "migration": "Runtimes before this release cannot read `kumiko-pii:v3:` ciphertext. Before annotating a jsonb field with `personal`, roll this version out to every instance, so a rolling deploy never has an old instance reading a value a new one wrote."
+  },
+  {
+    "version": "0.339.0",
+    "type": "fix",
+    "title": "Uncaught route errors and client aborts go through one error handler",
+    "detail": "`buildServer` calls `app.onError(handleUncaughtRouteError)`, which reuses the `/api/query` helpers: a rethrown abort of the request signal maps to 499, everything else is classified with `toKumikoError`, logged with `logServerFault` and serialized with `serializeError`. Sub-apps mounted via `app.route()` inherit it.",
+    "migration": "keine"
+  },
+  {
+    "version": "0.339.0",
+    "type": "breaking",
+    "title": "ctx.db.unsafeRaw() takes no reason; the audit uses the declared escapeHatch reason",
+    "detail": "`TenantDb.unsafeRaw` is now `unsafeRaw(): DbRunner`. The `unsafe-raw` audit entry carries the reason from the `escapeHatch` declaration, as before. Calls without a matching declaration are still rejected with an `AccessDeniedError`.",
+    "migration": "Replace `ctx.db.unsafeRaw(\"...\")` with `ctx.db.unsafeRaw()`. The reason lives only in `escapeHatch: { reason }` on the handler, hook or job; TypeScript flags old calls. `ctx.systemDb.unsafeRaw(reason)` is unchanged."
+  },
+  {
+    "version": "0.339.0",
+    "type": "improvement",
+    "title": "Workflow run-stream events are registered, so projections can apply them",
+    "detail": "`WORKFLOW_SYSTEM_EVENT_DEFS` declares the seven `kumiko:system:workflow.*` events with a payload schema, version 1 and the stance from `SYSTEM_EVENT_PII_STANCES`. `createRegistry` seeds them into the event map next to `r.defineEvent` events, so apply-key validation, the PII catalog and the upcaster chain see them. A typo such as `kumiko:system:workflow.run-faild` still fails boot. `appendDomainEventCore` keeps skipping schema validation for `kumiko:system:*` types. The feature manifest gains an optional top-level `systemEvents` list.",
+    "migration": "A projection whose row ids are not the workflow-run aggregate id (for example uuidv5-derived ids) still cannot pass the ghost-row guard and needs its own change: its row id must equal the workflow-run aggregate id (this applies to kumiko-enterprise's run-state projection). Hand-built `FeatureManifest` objects stay valid because `systemEvents` is optional; regenerate committed manifests with `bun run gen:manifest` in `samples/apps/use-all-bundled` to pick the list up."
+  },
   {
     "version": "0.338.0",
     "type": "improvement",