@cosmicdrift/kumiko-framework 0.338.0 → 0.339.0

package/dist/api/auth-middleware.d.ts

@@ -23,6 +23,7 @@ export type AuthMiddlewareOptions = {
     readonly anonymousAccess?: AnonymousAccessResolved;
     readonly resolveTenantLifecycleStatus?: TenantLifecycleStatusResolver;
     readonly foreignCookieOrigins?: ReadonlySet<string>;
+    readonly isTenantlessAnonymousWrite?: (handlerQn: string) => boolean;
 };
 export type TenantResolver = (c: Context) => Promise<TenantId | null> | TenantId | null;
 export type TenantExists = (tenantId: TenantId) => Promise<boolean> | boolean;

package/dist/api/auth-middleware.js

@@ -1,7 +1,7 @@
 import { getCookie } from "hono/cookie";
 import { TENANT_TEARDOWN_STATUSES } from "../engine/active-membership.js";
 import { createAnonymousUser } from "../engine/system-user.js";
-import { parseTenantId } from "../engine/types/identifiers.js";
+import { parseTenantId, SYSTEM_TENANT_ID } from "../engine/types/identifiers.js";
 import { isSessionRequiredApiPath, TENANT_COOKIE_NAME, TENANT_HEADER_NAME, } from "./api-constants.js";
 import { isForeignCookieOrigin } from "./origin-middleware.js";
 const USER_KEY = "pipelineUser";
@@ -78,7 +78,7 @@ function extractToken(c) {
     return { error: "missing" };
 }
 export function authMiddleware(jwt, options = {}) {
-    const { sessionChecker, anonymousAccess, tokenVerifier, resolveTenantLifecycleStatus, foreignCookieOrigins, } = options;
+    const { sessionChecker, anonymousAccess, tokenVerifier, resolveTenantLifecycleStatus, foreignCookieOrigins, isTenantlessAnonymousWrite, } = options;
     // Fail loud at boot, not silently at request time: a tenantResolver
     // without a declared resolverTrust is an ambiguous trust decision no
     // sane default can make on the app's behalf (see AnonymousAccessConfig).
@@ -87,6 +87,7 @@ export function authMiddleware(jwt, options = {}) {
             'declare "authoritative" (resolver wins over client header/cookie) or ' +
             '"fallback-only" (client wins, resolver is a last resort).');
     }
+    const anonymousExtras = { isTenantlessAnonymousWrite };
     return async (c, next) => {
         const extracted = extractToken(c);
         if ("error" in extracted) {
@@ -117,7 +118,7 @@ export function authMiddleware(jwt, options = {}) {
                         i18nKey: "auth.errors.missingToken",
                     });
                 }
-                return await handleAnonymous(c, anonymousAccess, next, resolveTenantLifecycleStatus);
+                return await handleAnonymous(c, anonymousAccess, next, resolveTenantLifecycleStatus, anonymousExtras);
             }
             return middlewareReject(c, {
                 code: "missing_token",
@@ -136,7 +137,7 @@ export function authMiddleware(jwt, options = {}) {
             !c.req.path.startsWith("/api/auth/") &&
             foreignCookieOrigins &&
             isForeignCookieOrigin(c, foreignCookieOrigins)) {
-            return await handleAnonymous(c, anonymousAccess, next, resolveTenantLifecycleStatus);
+            return await handleAnonymous(c, anonymousAccess, next, resolveTenantLifecycleStatus, anonymousExtras);
         }
         // Generic bearer-verifier path: try the wired tokenVerifier (PAT, future
         // JWT-provider, ...) BEFORE jwt.verify. A hit short-circuits the JWT path
@@ -153,7 +154,7 @@ export function authMiddleware(jwt, options = {}) {
         const rejectInvalidCredential = async (rejection) => {
             if (isStaleCookieDowngradable(c, transport, anonymousAccess)) {
                 return await handleAnonymous(c, anonymousAccess, next, resolveTenantLifecycleStatus, {
-                    rejectionIfTenantUnresolved: rejection,
+                    staleCredential: { rejectionIfTenantUnresolved: rejection },
                 });
             }
             return middlewareReject(c, rejection);
@@ -271,7 +272,8 @@ async function handleVerifiedBearerUser(c, user, next, resolveTenantLifecycleSta
 //   5. Synthesise the anonymous SessionUser. The transport flag stays unset
 //      so csrf-middleware skips the double-submit check (no auth-cookie ⇒
 //      no CSRF vector to defend against).
-async function handleAnonymous(c, config, next, resolveTenantLifecycleStatus, staleCredential) {
+async function handleAnonymous(c, config, next, resolveTenantLifecycleStatus, extras = {}) {
+    const { staleCredential, isTenantlessAnonymousWrite } = extras;
     // A downgraded stale credential whose anonymous tenant can't be resolved or
     // is torn down answers with the credential's own 401: a tenant error would
     // hide the session end from the client.
@@ -292,11 +294,14 @@ async function handleAnonymous(c, config, next, resolveTenantLifecycleStatus, st
             ? { id: cookieCheck.tenantId, source: "cookie" }
             : null;
     // Step 3: pick the authoritative tenant.
-    const resolved = await resolveTenant(c, config, clientTenant);
+    const resolved = await resolveTenantOrTenantless(c, config, clientTenant, {
+        allowTenantless: staleCredential === undefined,
+        isTenantlessAnonymousWrite,
+    });
     if ("error" in resolved)
         return rejectTenant(resolved.error);
     // Step 4: existence check for untrusted sources.
-    if (resolved.source !== "default" && config.tenantExists) {
+    if (resolved.source !== "default" && resolved.source !== "tenantless" && config.tenantExists) {
         const exists = await config.tenantExists(resolved.tenantId);
         if (!exists) {
             return rejectTenant({
@@ -308,8 +313,10 @@ async function handleAnonymous(c, config, next, resolveTenantLifecycleStatus, st
             });
         }
     }
-    // Step 5: synthesise + continue.
-    const lifecycleReject = await rejectIfTenantTeardown(c, resolved.tenantId, resolveTenantLifecycleStatus);
+    // Step 5: synthesise + continue. SYSTEM_TENANT_ID is no lifecycle-managed tenant.
+    const lifecycleReject = resolved.source === "tenantless"
+        ? undefined
+        : await rejectIfTenantTeardown(c, resolved.tenantId, resolveTenantLifecycleStatus);
     if (lifecycleReject) {
         return staleCredential
             ? middlewareReject(c, staleCredential.rejectionIfTenantUnresolved)
@@ -321,6 +328,43 @@ async function handleAnonymous(c, config, next, resolveTenantLifecycleStatus, st
     // when next() ran; explicit return makes the union return-type honest.
     return;
 }
+// The exemption applies only where resolveTenant answers tenant_required:
+// never on tenant_mismatch, never when the client named a tenant via X-Tenant,
+// never for a downgraded stale credential. An ambient tenant cookie does not
+// block it: tenant_required with a client tenant only happens when an
+// authoritative resolver stayed silent, and that path ignores the cookie
+// anyway, so a customer who also uses the app on this host can still cancel.
+async function resolveTenantOrTenantless(c, config, clientTenant, tenantless) {
+    const resolved = await resolveTenant(c, config, clientTenant);
+    const { isTenantlessAnonymousWrite } = tenantless;
+    if ("error" in resolved &&
+        resolved.error.code === "tenant_required" &&
+        clientTenant?.source !== "header" &&
+        tenantless.allowTenantless &&
+        isTenantlessAnonymousWrite !== undefined &&
+        (await isFlaggedTenantlessWrite(c, isTenantlessAnonymousWrite))) {
+        return { tenantId: SYSTEM_TENANT_ID, source: "tenantless" };
+    }
+    return resolved;
+}
+// Body peek for the tenantless exemption: only a single-command POST
+// /api/write qualifies, never /api/batch. Parsing the clone leaves the body
+// intact for the dispatcher; the body-size limit already ran upstream.
+async function isFlaggedTenantlessWrite(c, isTenantlessAnonymousWrite) {
+    if (c.req.method !== "POST" || c.req.path !== "/api/write")
+        return false;
+    try {
+        const body = await c.req.raw.clone().json();
+        return (typeof body === "object" &&
+            body !== null &&
+            "type" in body &&
+            typeof body.type === "string" &&
+            isTenantlessAnonymousWrite(body.type));
+    }
+    catch {
+        return false;
+    }
+}
 // Validates an X-Tenant / cookie value against the tenantId format. Returns
 // `{tenantId: null}` when absent, `{tenantId: TenantId}` when valid, or
 // `{error: …}` when the value is non-empty junk (so the caller can return

package/dist/api/routes.d.ts

@@ -1,4 +1,4 @@
-import { Hono } from "hono";
+import { type Context, Hono } from "hono";
 import type { Dispatcher } from "../pipeline/dispatcher.js";
 export declare const StreamFrame: {
     readonly chunk: "chunk";
@@ -18,3 +18,4 @@ export type SseWriter = {
 };
 export declare function pumpStream(stream: SseWriter, generator: AsyncGenerator<unknown>, heartbeatMs: number, firstPull?: Promise<IteratorResult<unknown>>): Promise<void>;
 export declare const MAX_PAYLOAD_DEPTH = 20;
+export declare function handleUncaughtRouteError(err: Error, c: Context): Response | Promise<Response>;

package/dist/api/routes.js

@@ -1,4 +1,5 @@
 import { Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
 import { streamSSE } from "hono/streaming";
 import { AccessDeniedError, reraiseAsKumikoError, serializeError, toKumikoError, ValidationError, } from "../errors/index.js";
 import { createFallbackLogger } from "../logging/index.js";
@@ -356,17 +357,39 @@ function writeErrorResponse(c, err, type) {
     const { error } = serializeError(err, requestId);
     return c.json({ isSuccess: false, error }, err.httpStatus); // @cast-boundary engine-payload
 }
+function clientAbortResponse(c, requestId, type) {
+    logClientWarn("request aborted by client", requestId, type, {
+        status: CLIENT_CLOSED_REQUEST_STATUS,
+    });
+    return c.body(null, CLIENT_CLOSED_REQUEST_STATUS); // @cast-boundary non-standard client-closed-request status, Hono's union doesn't include it
+}
 // For /query + /command: no isSuccess on success (just { data } / {ok}), so we
 // keep the same lean shape on failure — only the `error` key.
 function queryErrorResponse(c, err, type) {
     const requestId = requestContext.get()?.requestId;
-    if (isClientAbort(err)) {
-        logClientWarn("request aborted by client", requestId, type, {
-            status: CLIENT_CLOSED_REQUEST_STATUS,
-        });
-        return c.body(null, CLIENT_CLOSED_REQUEST_STATUS); // @cast-boundary non-standard client-closed-request status, Hono's union doesn't include it
-    }
+    if (isClientAbort(err))
+        return clientAbortResponse(c, requestId, type);
     logServerFault(err, requestId, type);
     const body = serializeError(err, requestId);
     return c.json(body, err.httpStatus); // @cast-boundary engine-payload
 }
+// A raw throw under the request signal (signal.throwIfAborted(), an aborted
+// fetch) is the signal's own reason or wraps it as `cause`.
+function isRequestAbortError(err, signal) {
+    return signal.aborted && (err === signal.reason || err.cause === signal.reason);
+}
+// Root `app.onError`: whatever a route rethrows instead of shaping itself.
+// Without it Hono's default handler console.error()s the bare error and
+// answers an unclassified 500 — including for a client that simply hung up.
+// requestContext only exists under /api/*, so the abort check reads the raw
+// request signal.
+export function handleUncaughtRouteError(err, c) {
+    if (err instanceof HTTPException)
+        return err.getResponse();
+    const requestId = requestContext.get()?.requestId;
+    if (isRequestAbortError(err, c.req.raw.signal))
+        return clientAbortResponse(c, requestId);
+    const kumikoError = toKumiko(err);
+    logServerFault(kumikoError, requestId);
+    return c.json(serializeError(kumikoError, requestId), kumikoError.httpStatus); // @cast-boundary engine-payload
+}

package/dist/api/server.js

@@ -39,7 +39,7 @@ import { createDefaultSseBroker } from "./redis-sse-broker.js";
 import { requestContext } from "./request-context.js";
 import { buildRequestContextData, requestIdMiddleware } from "./request-id-middleware.js";
 import { DEFAULT_MAX_REQUEST_BYTES, registerBodyLimit, registerHealthRoutes, registerMetricsRoute, registerVersionRoute, } from "./route-registrars.js";
-import { createApiRoutes } from "./routes.js";
+import { createApiRoutes, handleUncaughtRouteError } from "./routes.js";
 import { createSseRoute } from "./sse-route.js";
 import { buildWebSocketSessionRevalidator, createWebSocketConnectionLimiter, hasWebSocketUpgradeServer, isWebSocketUpgradeRequest, WEBSOCKET_DEFAULT_MAX_CONNECTIONS_PER_USER, WEBSOCKET_DEFAULT_MAX_MESSAGE_BYTES, } from "./websocket-route.js";
 // The per-tenant file-provider resolver, built once for a registry+context so
@@ -380,6 +380,8 @@ export function buildServer(options) {
         });
     }
     const app = new Hono();
+    // Sub-apps mounted via app.route() without their own handler inherit this one.
+    app.onError(handleUncaughtRouteError);
     // Only entry:"signature" bypasses jwtGuard (verify() authenticates
     // itself); entry:"anonymous" still needs the anonymousAccess fallthrough
     // (tenant-by-host), entry:"user" needs c.get("user") populated.
@@ -453,7 +455,13 @@ export function buildServer(options) {
     const normalizedForeignCookieOrigins = options.auth?.allowedOrigins?.length
         ? new Set(options.auth.allowedOrigins.map(normalizeOrigin))
         : undefined;
+    const tenantlessAnonymousQns = new Set([...options.registry.getAllWriteHandlers()]
+        .filter(([, handler]) => handler.tenantlessAnonymous === true)
+        .map(([qn]) => qn));
     const jwtGuard = authMiddleware(jwt, {
+        ...(tenantlessAnonymousQns.size > 0
+            ? { isTenantlessAnonymousWrite: (qn) => tenantlessAnonymousQns.has(qn) }
+            : {}),
         ...(options.auth?.sessionChecker ? { sessionChecker: options.auth.sessionChecker } : {}),
         ...(options.auth?.tokenVerifier ? { tokenVerifier: options.auth.tokenVerifier } : {}),
         ...(tenantLifecycleResolver ? { resolveTenantLifecycleStatus: tenantLifecycleResolver } : {}),

package/dist/bun-db/query.js

@@ -24,6 +24,7 @@ import { KUMIKO_META_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types
 import { Temporal } from "temporal-polyfill";
 import { requestContext } from "../api/request-context.js";
 import { computeBlindIndex, configuredBlindIndexKey } from "../crypto/blind-index.js";
+import { isPiiCiphertext } from "../crypto/pii-ciphertext-format.js";
 import { SQL_EXPR_BRAND } from "../db/dialect.js";
 import { extractPgError } from "../db/pg-error.js";
 import { toSnakeCase } from "../db/table-builder.js";
@@ -88,7 +89,7 @@ export function asRawClient(db) {
     // closed instead of silently unwrapping a tenant-scoped handle.
     if (isTenantDbShape(db)) {
         throw new Error("asRawClient: received a tenant-scoped TenantDb (ctx.db). Raw SQL helpers do not apply the " +
-            "tenant filter — use a ctx.db.<method>, or ctx.db.unsafeRaw(reason) with escapeHatch: " +
+            "tenant filter — use a ctx.db.<method>, or ctx.db.unsafeRaw() with escapeHatch: " +
             "{ reason } on the handler/hook (r.systemScope() features: ctx.systemDb.unsafeRaw(reason)).");
     }
     // Drizzle DbConnection (legacy compat): $client = postgres-js Sql.
@@ -174,7 +175,7 @@ function tenantDbDelegate(db) {
 function assertNotTenantScoped(db, fnName) {
     if (tenantDbDelegate(db) !== undefined) {
         throw new Error(`${fnName}: received a tenant-scoped db but this helper does not apply the tenant filter. ` +
-            "Pass ctx.db.unsafeRaw(reason) (with escapeHatch: { reason } on the handler/hook) for an " +
+            "Pass ctx.db.unsafeRaw() (with escapeHatch: { reason } on the handler/hook) for an " +
             "explicit cross-tenant op, or use a scoped TenantDb method.");
     }
 }
@@ -462,6 +463,11 @@ function prepareValue(value, pgType) {
     if (isSqlExpression(value)) {
         return { kind: "literal", literal: value.text };
     }
+    // A PII-encrypted jsonb field is a JSON string scalar; a raw string bound to
+    // ::jsonb would be parsed as JSON text (or double-encoded under Bun.SQL).
+    if (pgType === "jsonb" && isPiiCiphertext(value)) {
+        return { kind: "param", sql: "::text::jsonb", bound: JSON.stringify(value) };
+    }
     if (pgType === "jsonb" && value !== null) {
         const prepared = prepareJsonbValue(value);
         if (prepared)

package/dist/crypto/event-pii.js

@@ -14,7 +14,7 @@
 // silent no-op (forgetting the option) is now either an explicit "none" or a
 // missing subject KMS at encrypt-time, both visible states, not a gap.
 import { requestContext } from "../api/request-context.js";
-import { configuredPiiSubjectKms, encryptPiiValueForSubject } from "./pii-field-encryption.js";
+import { configuredPiiSubjectKms, encryptPiiJsonValueForSubject, encryptPiiValueForSubject, } from "./pii-field-encryption.js";
 import { resolveEventSubject } from "./subject-resolver.js";
 import { SYSTEM_EVENT_PII_STANCES, SYSTEM_EVENT_PREFIX } from "./system-event-pii.js";
 // Boot-injected like configurePiiSubjectKms — createRegistry calls this with
@@ -41,6 +41,12 @@ function resolvePiiStance(eventType) {
     }
     return stance;
 }
+// The catalog carries no field types: strings keep the plain format, objects
+// and arrays (jsonb payload fields) use the self-describing JSON format.
+// Bare numbers/booleans stay a loud error so a mistyped string field is caught.
+function isStructuredJsonValue(value) {
+    return typeof value === "object" && value !== null;
+}
 // Encrypts catalogued payload fields under the declared subject's DEK
 // (user/tenant/self — resolveEventSubject, fw#2801). No-op when the event
 // type is uncatalogued or no subject KMS is configured (plaintext rollout
@@ -63,13 +69,16 @@ export async function encryptEventPayloadPii(eventType, payload, envelope) {
         const value = payload[field];
         if (value === null || value === undefined)
             continue;
-        if (typeof value !== "string") {
-            throw new Error(`Event "${eventType}" piiFields."${field}" must be a string payload field, got ${typeof value}`);
+        if (typeof value !== "string" && !isStructuredJsonValue(value)) {
+            throw new Error(`Event "${eventType}" piiFields."${field}" must be a string payload field (or an object/array for jsonb), got ${typeof value}`);
         }
         const subject = resolveEventSubject(field, spec, payload, envelope);
         if (subject === null)
             continue;
-        const encrypted = await encryptPiiValueForSubject(kms, subject, value, { requestId: requestContext.get()?.requestId ?? "append-event" }, field);
+        const kmsCtx = { requestId: requestContext.get()?.requestId ?? "append-event" };
+        const encrypted = typeof value === "string"
+            ? await encryptPiiValueForSubject(kms, subject, value, kmsCtx, field)
+            : await encryptPiiJsonValueForSubject(kms, subject, value, kmsCtx, field);
         if (encrypted !== value) {
             out ??= { ...payload };
             out[field] = encrypted;

package/dist/crypto/index.d.ts

@@ -6,6 +6,6 @@ export { type KekSourceEnv, type KekSourceOptions, resolvePlatformKeks } from ".
 export { isLocalKeyKmsAdapter, KeyAlreadyExistsError, KeyErasedError, KeyNotFoundError, type KmsAdapter, type KmsContext, type KmsHealth, type LocalKeyKmsAdapter, RECORD_ENTITY_PATTERN, type RemoteCryptoKmsAdapter, type SubjectDek, type SubjectId, type SubjectKey, subjectIdFromKey, subjectIdSchema, subjectIdToKey, subjectKeyForRecord, subjectKeyForTenant, subjectKeyForUser, } from "./kms-adapter.js";
 export { type ActiveKmsWiring, buildPgKmsOptions, type KmsWiring, type KmsWiringEnv, type KmsWiringOptions, type KmsWiringRelease, type PgKmsRotationEnv, type PlaintextPiiWiring, requireKmsWiring, requireKmsWiringAsync, resolveKmsWiring, resolveKmsWiringAsync, } from "./kms-wiring.js";
 export { createPgKmsAdapter, PgKmsAdapter, type PgKmsAdapterOptions, type RewrapOptions, type RewrapResult, rewrapSubjectKeys, } from "./pg-kms-adapter.js";
-export { configuredPiiSubjectKms, configurePiiSubjectKms, decryptPiiFieldValues, decryptPiiValueForSubject, type EncryptPiiOptions, encryptPiiFieldValues, encryptPiiValueForSubject, isPiiCiphertext, PII_CIPHERTEXT_PREFIX, PII_ERASED_SENTINEL, } from "./pii-field-encryption.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 { collectPiiSubjectFields, collectSearchableSubjectFields, type ResolveSubjectOptions, resolveSubjectForField, SubjectResolutionError, } from "./subject-resolver.js";

package/dist/crypto/index.js

@@ -6,6 +6,6 @@ export { resolvePlatformKeks } from "./kek-source.js";
 export { isLocalKeyKmsAdapter, KeyAlreadyExistsError, KeyErasedError, KeyNotFoundError, RECORD_ENTITY_PATTERN, subjectIdFromKey, subjectIdSchema, subjectIdToKey, subjectKeyForRecord, subjectKeyForTenant, subjectKeyForUser, } from "./kms-adapter.js";
 export { buildPgKmsOptions, requireKmsWiring, requireKmsWiringAsync, resolveKmsWiring, resolveKmsWiringAsync, } from "./kms-wiring.js";
 export { createPgKmsAdapter, PgKmsAdapter, rewrapSubjectKeys, } from "./pg-kms-adapter.js";
-export { configuredPiiSubjectKms, configurePiiSubjectKms, decryptPiiFieldValues, decryptPiiValueForSubject, encryptPiiFieldValues, encryptPiiValueForSubject, isPiiCiphertext, PII_CIPHERTEXT_PREFIX, PII_ERASED_SENTINEL, } from "./pii-field-encryption.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 { collectPiiSubjectFields, collectSearchableSubjectFields, resolveSubjectForField, SubjectResolutionError, } from "./subject-resolver.js";

package/dist/crypto/pii-ciphertext-format.d.ts

@@ -0,0 +1,4 @@
+export declare const PII_CIPHERTEXT_PREFIX_V1 = "kumiko-pii:v1:";
+export declare const PII_CIPHERTEXT_PREFIX = "kumiko-pii:v2:";
+export declare const PII_CIPHERTEXT_PREFIX_JSON = "kumiko-pii:v3:";
+export declare function isPiiCiphertext(value: unknown): value is string;

package/dist/crypto/pii-ciphertext-format.js

@@ -0,0 +1,11 @@
+// Leaf module (no engine imports) so bun-db and the executors can sniff PII
+// ciphertext without pulling the KMS/pipeline graph into an import cycle.
+export const PII_CIPHERTEXT_PREFIX_V1 = "kumiko-pii:v1:";
+export const PII_CIPHERTEXT_PREFIX = "kumiko-pii:v2:";
+export const PII_CIPHERTEXT_PREFIX_JSON = "kumiko-pii:v3:";
+export function isPiiCiphertext(value) {
+    return (typeof value === "string" &&
+        (value.startsWith(PII_CIPHERTEXT_PREFIX) ||
+            value.startsWith(PII_CIPHERTEXT_PREFIX_JSON) ||
+            value.startsWith(PII_CIPHERTEXT_PREFIX_V1)));
+}

package/dist/crypto/pii-field-encryption.d.ts

@@ -1,10 +1,11 @@
 import type { EntityDefinition } from "../engine/types/fields.js";
 import type { TenantId } from "../engine/types/identifiers.js";
 import { type KmsAdapter, type KmsContext, type LocalKeyKmsAdapter, type SubjectId } from "./kms-adapter.js";
+import { isPiiCiphertext, PII_CIPHERTEXT_PREFIX, PII_CIPHERTEXT_PREFIX_JSON } from "./pii-ciphertext-format.js";
+export { isPiiCiphertext, PII_CIPHERTEXT_PREFIX, PII_CIPHERTEXT_PREFIX_JSON };
 export declare const PII_ERASED_SENTINEL = "[[erased]]";
-export declare const PII_CIPHERTEXT_PREFIX = "kumiko-pii:v2:";
-export declare function isPiiCiphertext(value: unknown): value is string;
 export declare function encryptPiiValueForSubject(kms: LocalKeyKmsAdapter, subject: SubjectId, value: string, kmsCtx: KmsContext, field: string): Promise<string>;
+export declare function encryptPiiJsonValueForSubject(kms: LocalKeyKmsAdapter, subject: SubjectId, value: unknown, kmsCtx: KmsContext, field: string): Promise<string>;
 export declare function decryptPiiValueForSubject(kms: LocalKeyKmsAdapter, value: string, kmsCtx: KmsContext, field: string): Promise<string>;
 export interface EncryptPiiOptions {
     readonly onlyKeys?: Iterable<string>;
@@ -13,6 +14,7 @@ export interface EncryptPiiOptions {
     readonly entityName: string;
 }
 export declare function encryptPiiFieldValues(row: Record<string, unknown>, entity: EntityDefinition, piiFields: readonly string[], kms: LocalKeyKmsAdapter, kmsCtx: KmsContext, opts: EncryptPiiOptions): Promise<Record<string, unknown>>;
+export declare function serializeJsonbValue(field: string, value: unknown): string;
 export declare function decryptPiiFieldValues(row: Record<string, unknown>, piiFields: readonly string[], kms: LocalKeyKmsAdapter, kmsCtx: KmsContext): Promise<Record<string, unknown>>;
 export declare function configurePiiSubjectKms(adapter: KmsAdapter | undefined): void;
 export declare function configuredPiiSubjectKms(): LocalKeyKmsAdapter | undefined;

package/dist/crypto/pii-field-encryption.js

@@ -9,34 +9,41 @@
 // SAME subject (same DEK, so key selection alone can't catch that) from
 // decrypting silently. v1 (no AAD) stays decrypt-only for pre-#1263 rows;
 // every new write emits v2.
+// v3 = v2 for jsonb fields: the plaintext is JSON.stringify(value) and decrypt
+// JSON.parses it back, so a jsonb string/number/object round-trips by type.
+// The version digit (not a suffix) keeps `kumiko-pii:v\d+:` leak guards and
+// the `kumiko-pii:v%:` LIKE sweeps matching. The AAD carries a "json" tag so
+// a v2<->v3 prefix swap fails GCM instead of silently changing the type.
 import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
 import { assertIrreversibleOperationAllowed } from "../pipeline/irreversible-operation-gate.js";
 import { isLocalKeyKmsAdapter, KeyAlreadyExistsError, KeyErasedError, KeyNotFoundError, subjectIdFromKey, subjectIdToKey, } from "./kms-adapter.js";
+import { isPiiCiphertext, PII_CIPHERTEXT_PREFIX, PII_CIPHERTEXT_PREFIX_JSON, PII_CIPHERTEXT_PREFIX_V1, } from "./pii-ciphertext-format.js";
 import { resolveSubjectForField } from "./subject-resolver.js";
 // Spec value (crypto-shredding.md) — renderers show it verbatim.
+export { isPiiCiphertext, PII_CIPHERTEXT_PREFIX, PII_CIPHERTEXT_PREFIX_JSON };
 export const PII_ERASED_SENTINEL = "[[erased]]";
-const PII_CIPHERTEXT_PREFIX_V1 = "kumiko-pii:v1:";
-export const PII_CIPHERTEXT_PREFIX = "kumiko-pii:v2:";
 const IV_LENGTH = 12;
 const AUTH_TAG_LENGTH = 16;
-export function isPiiCiphertext(value) {
-    return (typeof value === "string" &&
-        (value.startsWith(PII_CIPHERTEXT_PREFIX) || value.startsWith(PII_CIPHERTEXT_PREFIX_V1)));
+function buildAad(subject, field, isJson) {
+    return Buffer.from(`${subjectIdToKey(subject)}|${field}${isJson ? "|json" : ""}`, "utf8");
 }
-function buildAad(subject, field) {
-    return Buffer.from(`${subjectIdToKey(subject)}|${field}`, "utf8");
-}
-function encryptValue(subject, dek, plaintext, field) {
+function encryptValue(subject, dek, plaintext, field, isJson = false) {
     const iv = randomBytes(IV_LENGTH);
     const cipher = createCipheriv("aes-256-gcm", dek, iv);
-    cipher.setAAD(buildAad(subject, field));
+    cipher.setAAD(buildAad(subject, field, isJson));
     const ciphertext = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
     const blob = Buffer.concat([iv, cipher.getAuthTag(), ciphertext]);
-    return `${PII_CIPHERTEXT_PREFIX}${subjectIdToKey(subject)}:${blob.toString("base64")}`;
+    const prefix = isJson ? PII_CIPHERTEXT_PREFIX_JSON : PII_CIPHERTEXT_PREFIX;
+    return `${prefix}${subjectIdToKey(subject)}:${blob.toString("base64")}`;
 }
 function parseCiphertext(value) {
-    const hasAad = value.startsWith(PII_CIPHERTEXT_PREFIX);
-    const prefix = hasAad ? PII_CIPHERTEXT_PREFIX : PII_CIPHERTEXT_PREFIX_V1;
+    const isJson = value.startsWith(PII_CIPHERTEXT_PREFIX_JSON);
+    const hasAad = isJson || value.startsWith(PII_CIPHERTEXT_PREFIX);
+    const prefix = isJson
+        ? PII_CIPHERTEXT_PREFIX_JSON
+        : hasAad
+            ? PII_CIPHERTEXT_PREFIX
+            : PII_CIPHERTEXT_PREFIX_V1;
     const rest = value.slice(prefix.length);
     // subjectKey itself contains ":" ("user:<id>") — base64 never does, so the
     // last ":" is always the key/blob separator.
@@ -47,15 +54,16 @@ function parseCiphertext(value) {
         subject: subjectIdFromKey(rest.slice(0, sep)),
         blob: Buffer.from(rest.slice(sep + 1), "base64"),
         hasAad,
+        isJson,
     };
 }
-function decryptValue(dek, blob, subject, field, hasAad) {
+function decryptValue(dek, blob, subject, field, hasAad, isJson) {
     const iv = blob.subarray(0, IV_LENGTH);
     const tag = blob.subarray(IV_LENGTH, IV_LENGTH + AUTH_TAG_LENGTH);
     const ciphertext = blob.subarray(IV_LENGTH + AUTH_TAG_LENGTH);
     const decipher = createDecipheriv("aes-256-gcm", dek, iv);
     if (hasAad)
-        decipher.setAAD(buildAad(subject, field));
+        decipher.setAAD(buildAad(subject, field, isJson));
     decipher.setAuthTag(tag);
     return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString("utf8");
 }
@@ -91,6 +99,12 @@ export async function encryptPiiValueForSubject(kms, subject, value, kmsCtx, fie
     const dek = await getOrCreateDek(kms, subject, kmsCtx);
     return encryptValue(subject, dek, value, field);
 }
+// Event-payload variant for non-string values (jsonb-typed payload fields):
+// same DEK path, but the self-describing v3 format so decrypt restores the type.
+export async function encryptPiiJsonValueForSubject(kms, subject, value, kmsCtx, field) {
+    const dek = await getOrCreateDek(kms, subject, kmsCtx);
+    return encryptValue(subject, dek, serializeJsonbValue(field, value), field, true);
+}
 // Single-value decrypt for callers that don't have an entity/field-map to
 // pass through decryptPiiFieldValues (config values). The subject lives
 // inside the ciphertext itself, so no subject/scope resolution is needed
@@ -99,9 +113,12 @@ export async function encryptPiiValueForSubject(kms, subject, value, kmsCtx, fie
 export async function decryptPiiValueForSubject(kms, value, kmsCtx, field) {
     if (!isPiiCiphertext(value))
         return value;
-    const { subject, blob, hasAad } = parseCiphertext(value);
+    const { subject, blob, hasAad, isJson } = parseCiphertext(value);
+    if (isJson) {
+        throw new Error(`PII field "${field}" holds a jsonb ciphertext — decrypt it via decryptPiiFieldValues`);
+    }
     try {
-        return decryptValue(await kms.getKey(subject, kmsCtx), blob, subject, field, hasAad);
+        return decryptValue(await kms.getKey(subject, kmsCtx), blob, subject, field, hasAad, false);
     }
     catch (e) {
         if (!(e instanceof KeyErasedError))
@@ -127,9 +144,11 @@ export async function encryptPiiFieldValues(row, entity, piiFields, kms, kmsCtx,
         // are already ciphertext or the erased sentinel — both stay as-is.
         if (isPiiCiphertext(value) || value === PII_ERASED_SENTINEL)
             continue;
-        if (typeof value !== "string") {
+        const isJsonbField = entity.fields[name]?.type === "jsonb";
+        if (!isJsonbField && typeof value !== "string") {
             throw new Error(`PII field "${name}" must be a string, got ${typeof value}`);
         }
+        const plaintext = isJsonbField ? serializeJsonbValue(name, value) : String(value);
         const subject = resolveSubjectForField(entity, name, subjectSource, {
             entityName: opts.entityName,
             ...(opts.tenantId !== undefined && { tenantId: opts.tenantId }),
@@ -138,10 +157,17 @@ export async function encryptPiiFieldValues(row, entity, piiFields, kms, kmsCtx,
         if (subject === null)
             continue;
         const dek = await getOrCreateDek(kms, subject, kmsCtx);
-        out[name] = encryptValue(subject, dek, value, name);
+        out[name] = encryptValue(subject, dek, plaintext, name, isJsonbField);
     }
     return out;
 }
+export function serializeJsonbValue(field, value) {
+    const json = JSON.stringify(value);
+    // undefined/function/symbol serialize to undefined — never storable as jsonb
+    if (json === undefined)
+        throw new Error(`PII jsonb field "${field}" is not JSON-serializable`);
+    return json;
+}
 export async function decryptPiiFieldValues(row, piiFields, kms, kmsCtx) {
     if (piiFields.length === 0)
         return row;
@@ -152,9 +178,12 @@ export async function decryptPiiFieldValues(row, piiFields, kms, kmsCtx) {
         // work during rollout; backfill is tracked in kumiko-framework#799).
         if (!isPiiCiphertext(value))
             continue;
-        const { subject, blob, hasAad } = parseCiphertext(value);
+        const { subject, blob, hasAad, isJson } = parseCiphertext(value);
         try {
-            out[name] = decryptValue(await kms.getKey(subject, kmsCtx), blob, subject, name, hasAad);
+            const key = await kms.getKey(subject, kmsCtx);
+            const plain = decryptValue(key, blob, subject, name, hasAad, isJson);
+            // @cast-boundary crypto-decrypt — AEAD-authenticated plaintext that this module serialized
+            out[name] = isJson ? JSON.parse(plain) : plain;
         }
         catch (e) {
             // KeyNotFound deliberately propagates: ciphertext without a key row

package/dist/crypto/system-event-pii.js

@@ -9,8 +9,8 @@ export const SYSTEM_EVENT_PREFIX = "kumiko:system:";
 // an event-store import cycle; transfer.ts re-exports it.
 export const AGGREGATE_TRANSFERRED_EVENT_TYPE = `${SYSTEM_EVENT_PREFIX}aggregate.transferred`;
 const SELF = { personal: "self" };
-// Workflow payloads carry `triggerPayload`, the stored payload of the trigger
-// event: catalogued fields there are already ciphertext, so "none" leaks nothing.
+// Workflow run-stream payloads carry references and step bookkeeping only,
+// never a copy of a foreign event payload, so "none" leaves nothing to shred.
 export const SYSTEM_EVENT_PII_STANCES = new Map([
     [
         STEP_DISPATCH_REQUESTED_TYPE,

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

@@ -300,6 +300,10 @@ export async function backfillEventPiiEncryptionBatch(db, registry, options = {}
                     const value = section[field];
                     if (value === null || value === undefined)
                         continue;
+                    // jsonb PII is not retro-encrypted (consumer wave); a legacy string
+                    // value here would otherwise get the v2 text format into a jsonb column.
+                    if (target.entity.fields[field]?.type === "jsonb")
+                        continue;
                     if (typeof value !== "string")
                         continue;
                     // Already-ciphertext/sentinel fields must never enter owner

package/dist/db/tenant-db.js

@@ -11,7 +11,7 @@ const declaredUnsafeRawRunners = new WeakMap();
 // TenantDb it was handed for its gate. Bound inside createTenantDb so rebound instances
 // (withUnsafeRawGrant, acknowledgeConventionCrossTenant) carry it too.
 const personalDataGates = new WeakMap();
-// Lets createTenantDb(ctx.db.unsafeRaw(reason), ...) inherit the gate. Keyed by a
+// Lets createTenantDb(ctx.db.unsafeRaw(), ...) inherit the gate. Keyed by a
 // per-grant proxy, never the shared pool/tx: tagging that would gate every sibling TenantDb.
 const runnerPersonalDataGates = new WeakMap();
 function gatedRunner(runner, gate) {
@@ -61,7 +61,7 @@ export function unsafeRawForDeclaredStep(holder, reason) {
                 "createUncheckedSystemDb, or createSystemDbView — no declared unsafeRaw runner bound.",
         });
     }
-    return runner(reason, true);
+    return runner(reason);
 }
 const systemDbRebinders = new WeakMap();
 // Rebinds a hook's own escapeHatch onto ctx.systemDb, mirroring withUnsafeRawGrant: always
@@ -104,7 +104,7 @@ function buildUncheckedSystemDb(db, dbOutsideTransaction, report, gate) {
                     message: "createSystemDbView received a TenantDb with no declared unsafeRaw runner bound.",
                 });
             }
-            return sourceRunner(reason, forwardedDeclaredStep);
+            return sourceRunner(forwardedDeclaredStep ? reason : undefined);
         }
         if (reason.trim().length === 0) {
             throw new Error("unsafeRaw requires a non-empty reason");
@@ -170,7 +170,14 @@ function buildUncheckedSystemDb(db, dbOutsideTransaction, report, gate) {
             },
         },
     };
-    declaredUnsafeRawRunners.set(uncheckedSystemDb, grantedUnsafeRawRunner);
+    declaredUnsafeRawRunners.set(uncheckedSystemDb, (declaredStepReason) => {
+        if (declaredStepReason === undefined) {
+            throw new InternalError({
+                message: "A declared unsafeRaw runner on a system db requires the step reason.",
+            });
+        }
+        return grantedUnsafeRawRunner(declaredStepReason, true);
+    });
     if (gate?.kind !== "source-tenant-db") {
         systemDbRebinders.set(uncheckedSystemDb, (grant, deniedCallerLabel) => buildUncheckedSystemDb(withUnsafeRawGrant(db, grant), dbOutsideTransaction && withUnsafeRawGrant(dbOutsideTransaction, grant), report, { kind: "hook-grant", grant, deniedCallerLabel }));
     }
@@ -426,29 +433,26 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
             // @cast-boundary type-brand — GlobalWrites is only present in the type when TTable is not ExecutorOnly; the object above always carries the methods.
         };
     }
-    function grantedUnsafeRawRunner(reason, forwardedDeclaredStep) {
-        if (reason.trim().length === 0) {
-            throw new Error("unsafeRaw requires a non-empty reason");
-        }
+    function grantedUnsafeRawRunner(declaredStepReason) {
         // Ahead of the grant check: a declared escapeHatch must not buy a raw runner here either.
         if (grants?.memberReadOnly) {
             throw memberResolutionReadOnlyDenied();
         }
         if (!hasGrant(grants?.unsafeRaw)) {
             throw new AccessDeniedError({
-                message: 'ctx.db.unsafeRaw(reason): rejected — declare `escapeHatch: { reason: "..." }` on ' +
+                message: 'ctx.db.unsafeRaw(): rejected — declare `escapeHatch: { reason: "..." }` on ' +
                     "the handler or hook to allow unsafeRaw.",
             });
         }
-        // Engine-forwarded steps carry their own declared reason; a caller-supplied one never reaches the audit trail.
-        report("unsafe-raw", forwardedDeclaredStep ? reason : (grants?.unsafeRaw?.reason ?? reason));
+        // Engine-forwarded steps carry their own declared reason; otherwise the grant's reason is audited.
+        report("unsafe-raw", declaredStepReason ?? grants?.unsafeRaw?.reason ?? "");
         return personalDataGate ? gatedRunner(db, personalDataGate) : db;
     }
     const tenantDb = {
         tenantId,
         mode,
         global: globalTable,
-        unsafeRaw: (reason) => grantedUnsafeRawRunner(reason, false),
+        unsafeRaw: () => grantedUnsafeRawRunner(),
         selectMany(table, where, options) {
             const filter = readWhere(table, where);
             return withDbSpan("select", table, async () => bunSelectMany(db, table, filter, options));

package/dist/engine/boot-validator/entity-handler.d.ts

@@ -6,6 +6,7 @@ export declare const PII_USER_REFERENCE_NAME_HINTS: ReadonlySet<string>;
 /** Extensions with preSave must target an entity that has mapped write handlers. */
 export declare function validateExtensionPreSaveWiring(features: readonly FeatureDefinition[]): void;
 export declare function validateHandlerAccess(feature: FeatureDefinition): void;
+export declare function validateTenantlessAnonymous(featureName: string, handlerName: string, handler: FeatureDefinition["writeHandlers"][string]): void;
 export declare function validateRateLimitDisabledReason(featureName: string, kind: "write" | "query" | "stream", handlerName: string, rateLimit: FeatureDefinition["writeHandlers"][string]["rateLimit"]): void;
 export declare function validateNoAllRoleInHandlerAccess(featureName: string, kind: "write" | "query" | "stream", handlerName: string, access: NonNullable<FeatureDefinition["writeHandlers"][string]["access"]>): void;
 export declare function validateAnonymousRateLimit(featureName: string, kind: "write" | "query" | "stream", handlerName: string, access: NonNullable<FeatureDefinition["writeHandlers"][string]["access"]>, rateLimit: FeatureDefinition["writeHandlers"][string]["rateLimit"]): void;

package/dist/engine/boot-validator/entity-handler.js

@@ -134,6 +134,25 @@ export function validateHandlerAccess(feature) {
             validateRateLimitDisabledReason(feature.name, kind, name, handler.rateLimit);
         }
     }
+    for (const [name, handler] of Object.entries(feature.writeHandlers)) {
+        validateTenantlessAnonymous(feature.name, name, handler);
+    }
+}
+export function validateTenantlessAnonymous(featureName, handlerName, handler) {
+    // skip: handler does not opt into tenantless anonymous calls
+    if (!handler.tenantlessAnonymous)
+        return;
+    const where = `write handler "${featureName}:write:${handlerName}" declares tenantlessAnonymous`;
+    const { access } = handler;
+    const isAnonymousOnly = "roles" in access && access.roles.length === 1 && access.roles[0] === "anonymous";
+    if (!isAnonymousOnly) {
+        throw new Error(`${where} but its access is not exactly { roles: ["anonymous"] } — a tenantless request ` +
+            `carries no principal beyond the anonymous visitor.`);
+    }
+    if (!handler.rateLimit || isRateLimitDisabled(handler.rateLimit)) {
+        throw new Error(`${where} without a rateLimit — a handler reachable on hosts that resolve no tenant ` +
+            `needs a real upper bound (rateLimit: { per: "ip", ... }); { disabled: true } does not count.`);
+    }
 }
 export function validateRateLimitDisabledReason(featureName, kind, handlerName, rateLimit) {
     // skip: rate limit isn't disabled, so no reason is required

package/dist/engine/boot-validator/pii-retention.js

@@ -71,6 +71,33 @@ function validateWriteOnlyField(featureName, entityName, fieldName, field) {
         }
     }
 }
+// A personal jsonb field is stored as a ciphertext JSON string scalar, so
+// anything that reads inside the column (index, filter, sort, search, jsonb
+// operators/merges such as the custom-fields column) sees only ciphertext.
+const JSONB_PERSONAL_FORBIDDEN_FLAGS = [
+    "sortable",
+    "filterable",
+    "searchable",
+    "lookupable",
+];
+const CUSTOM_FIELDS_COLUMN = "customFields";
+function validatePersonalJsonbField(featureName, entityName, entity, fieldName, field) {
+    const where = `[Feature ${featureName}] Field "${fieldName}" on entity "${entityName}"`;
+    const reason = "a personal jsonb field is stored as a ciphertext string, so nothing inside it can be indexed, filtered, sorted, searched or merged";
+    const flags = field; // @cast-boundary schema-walk
+    for (const flag of JSONB_PERSONAL_FORBIDDEN_FLAGS) {
+        if (flags[flag] !== undefined && flags[flag] !== false) {
+            throw new Error(`${where} combines a personal annotation on a jsonb field with { ${flag} } — ${reason}.`);
+        }
+    }
+    const index = entity.indexes?.find((def) => def.columns.includes(fieldName));
+    if (index) {
+        throw new Error(`${where} is a personal jsonb field used in an entity index — ${reason}. Drop the index or the personal annotation.`);
+    }
+    if (fieldName === CUSTOM_FIELDS_COLUMN) {
+        throw new Error(`${where} is the custom-fields jsonb column — its values are merged and searched per key, which ciphertext cannot support. Drop the personal annotation.`);
+    }
+}
 // --- PII / Subject-Key Annotations + Retention validation ---
 //
 // Drei Klassen von Checks:
@@ -153,6 +180,9 @@ export function validatePiiAndRetention(feature) {
                     throw new Error(`[Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" combines { sensitive: true } with { searchable: true } — sensitive means ciphertext at rest, never searchable, stripped from event echoes — authorized readers can still read it back (passwords, tokens, tax IDs). Subject-annotated identity fields may be searchable (#1610); sensitive fields may not. To never return the value at all, add { writeOnly: true }.`);
                 }
             }
+            if (field.type === "jsonb" && annotCount > 0) {
+                validatePersonalJsonbField(feature.name, entityName, entity, fieldName, field);
+            }
             if (annot.userOwned) {
                 const ownerName = annot.userOwned.ownerField;
                 if (!ownerName || typeof ownerName !== "string") {

package/dist/engine/define-handler.js

@@ -51,6 +51,7 @@ export function defineWriteHandler(def,
         }),
         ...(def.rateLimit && { rateLimit: def.rateLimit }),
         ...(def.escapeHatch && { escapeHatch: def.escapeHatch }),
+        ...(def.tenantlessAnonymous && { tenantlessAnonymous: true }),
     };
     if ("perform" in def && def.perform !== undefined) {
         const performDef = def.perform;

package/dist/engine/extensions/user-data.d.ts

@@ -30,7 +30,7 @@ export type TenantUserModel = "single-user" | "multi-user";
  * fw#2914 — `db` is a tenant-filtered `TenantDb`, bound to `tenantId`
  * (or the per-user sub-tx in the forget path). Unfiltered access needs
  * `escapeHatch: { reason }` on the `r.useExtension(...)` registration,
- * then `ctx.db.unsafeRaw(reason)`.
+ * then `ctx.db.unsafeRaw()`.
  */
 /**
  * Minimal storage surface a file-aware forget hook needs to erase binaries.

package/dist/engine/feature-ast/extractors/handlers.js

@@ -32,6 +32,7 @@ const WRITE_HANDLER_KEY_KINDS = {
     unsafeSkipTransitionGuard: "modeled",
     rateLimit: "modeled",
     escapeHatch: "modeled",
+    tenantlessAnonymous: "opaque",
     perform: "opaque",
 };
 const QUERY_HANDLER_KEY_KINDS = {

package/dist/engine/feature-entity-handlers.js

@@ -106,6 +106,7 @@ export function buildEntityHandlerMethods(state, name) {
                     ...(def.unsafeSkipTransitionGuard && { unsafeSkipTransitionGuard: true }),
                     ...(def.rateLimit && { rateLimit: def.rateLimit }),
                     ...(def.escapeHatch && { escapeHatch: def.escapeHatch }),
+                    ...(def.tenantlessAnonymous && { tenantlessAnonymous: true }),
                     // Forward the pipeline-build closure so boot-validators and
                     // Designer/AI tooling can inspect the step list. Absent on
                     // free-form handlers — defineWriteHandler only sets `perform`

package/dist/engine/feature-manifest.d.ts

@@ -30,6 +30,12 @@ export type ManifestExtension = {
     readonly extensionName: string;
     readonly entityName: string;
 };
+/** Framework-owned registered event (`kumiko:system:*`), e.g. the workflow
+ *  run-stream events a projection can apply. Not owned by any feature. */
+export type ManifestSystemEvent = {
+    readonly name: string;
+    readonly version: number;
+};
 export type ManifestFeature = {
     readonly name: string;
     readonly description: string | null;
@@ -58,6 +64,7 @@ export type FeatureManifest = {
     readonly source: string;
     readonly featureCount: number;
     readonly features: readonly ManifestFeature[];
+    readonly systemEvents?: readonly ManifestSystemEvent[];
     readonly tier?: string;
 };
 export type BuildManifestOptions = {

package/dist/engine/feature-manifest.js

@@ -5,6 +5,7 @@
 // die Kopie still. Quelle der Wahrheit ist die GEBOOTETE Registry — der
 // AST-Parser kann die imperativen Factory-Helper der bundled features nicht
 // lesen.
+import { SYSTEM_EVENT_PREFIX } from "../crypto/system-event-pii.js";
 import { compareByCodepoint } from "../utils/index.js";
 import { isEncryptedAtRest } from "./config-helpers.js";
 import { qualifyEntityName } from "./qualified-name.js";
@@ -76,10 +77,17 @@ export function buildManifestFromRegistry(registry, options) {
         });
     }
     manifestFeatures.sort((a, b) => compareByCodepoint(a.name, b.name));
+    const systemEvents = [];
+    for (const [name, info] of registry.getEventUpcasters()) {
+        if (name.startsWith(SYSTEM_EVENT_PREFIX))
+            systemEvents.push({ name, version: info.currentVersion });
+    }
+    systemEvents.sort((a, b) => compareByCodepoint(a.name, b.name));
     return {
         source: options.source,
         featureCount: manifestFeatures.length,
         features: manifestFeatures,
+        systemEvents,
         ...(options.tier !== undefined && { tier: options.tier }),
     };
 }

package/dist/engine/index.d.ts

@@ -40,7 +40,7 @@ export { createBigIntField, createBooleanField, createDateField, createDecimalFi
 export type { AddEntityArgs, AddHookArgs, AddRelationArgs, AddWriteHandlerArgs, FeaturePatcher, FeaturePattern, FeaturePatternKind, FormFieldLabel, FormFieldSpec, FormInputType, HandlerHeaderUpdate, ParseError, ParseResult, PatternCategory, PatternChange, PatternChangeIssue, PatternChangesParseResult, PatternFormSchema, PatternId, RenderFeatureFileInput, SourceLocation, } from "./feature-ast/index.js";
 export { addPattern, applyChanges, createFeaturePatcher, getPatternSchema, groupByCategory, PATTERN_LIBRARY, parseFeatureFile, parsePatternChanges, parseSourceFile, removePattern, renderFeatureFile, renderPattern, replacePattern, updatePattern, VERSION_HEADER, } from "./feature-ast/index.js";
 export { type ChangelogEntry, type ChangelogType, compareVersions, type FeatureChangelog, filterEntriesAfter, parseFeatureChangelog, sortEntries, validateChangelog, } from "./feature-changelog.js";
-export { type BuildManifestOptions, buildManifestFromRegistry, type FeatureManifest, type ManifestConfigKey, type ManifestExtension, type ManifestFeature, type ManifestSecret, serializeManifest, } from "./feature-manifest.js";
+export { type BuildManifestOptions, buildManifestFromRegistry, type FeatureManifest, type ManifestConfigKey, type ManifestExtension, type ManifestFeature, type ManifestSecret, type ManifestSystemEvent, serializeManifest, } from "./feature-manifest.js";
 export { checkWriteFieldOwnership, checkWriteFieldRoles, filterReadFields, maskWriteOnlyFields, } from "./field-access.js";
 export { resolveName, withResponseData } from "./handler-helpers.js";
 export { i18nKey } from "./i18n-key.js";
@@ -70,6 +70,7 @@ export { defineTransitions, guardTransition } from "./state-machine.js";
 export { evaluateEventMatch } from "./steps/_event-match.js";
 export { STEP_DISPATCH_AGGREGATE_TYPE, STEP_DISPATCH_FAILED_TYPE, STEP_DISPATCH_REQUESTED_TYPE, STEP_DISPATCHED_TYPE, SUSPEND_SENTINEL, WORKFLOW_AGGREGATE_TYPE, 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 "./steps/_step-dispatch-constants.js";
 export { describeWorkflowStepError } from "./steps/describe-workflow-step-error.js";
+export { WORKFLOW_SYSTEM_EVENT_DEFS } from "./steps/workflow-system-events.js";
 export { ANONYMOUS_ROLE, ANONYMOUS_USER_ID, createAnonymousUser, createSystemUser, SYSTEM_ROLE, SYSTEM_USER_ID, } from "./system-user.js";
 export { type EffectiveFeaturesResolver, findTierResolverUsage, isTierResolverPlugin, TENANT_TIER_RESOLVER_EXT, type TierResolverPlugin, type TrialGate, } from "./tier-resolver-extension.js";
 export { isSystemTenant, isUuid, parseTenantId, SYSTEM_TENANT_ID } from "./types/identifiers.js";

package/dist/engine/index.js

@@ -64,6 +64,7 @@ export { defineTransitions, guardTransition } from "./state-machine.js";
 export { evaluateEventMatch } from "./steps/_event-match.js";
 export { STEP_DISPATCH_AGGREGATE_TYPE, STEP_DISPATCH_FAILED_TYPE, STEP_DISPATCH_REQUESTED_TYPE, STEP_DISPATCHED_TYPE, SUSPEND_SENTINEL, WORKFLOW_AGGREGATE_TYPE, 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 "./steps/_step-dispatch-constants.js";
 export { describeWorkflowStepError } from "./steps/describe-workflow-step-error.js";
+export { WORKFLOW_SYSTEM_EVENT_DEFS } from "./steps/workflow-system-events.js";
 export { ANONYMOUS_ROLE, ANONYMOUS_USER_ID, createAnonymousUser, createSystemUser, SYSTEM_ROLE, SYSTEM_USER_ID, } from "./system-user.js";
 export { findTierResolverUsage, isTierResolverPlugin, TENANT_TIER_RESOLVER_EXT, } from "./tier-resolver-extension.js";
 export { isSystemTenant, isUuid, parseTenantId, SYSTEM_TENANT_ID } from "./types/identifiers.js";

package/dist/engine/registry-ingest.d.ts

@@ -5,6 +5,7 @@ export declare function populateHandlers(state: RegistryState, feature: FeatureD
 export declare function populateConfigKeys(state: RegistryState, feature: FeatureDefinition): void;
 export declare function populateJobsAndNotifications(state: RegistryState, feature: FeatureDefinition): void;
 export declare function populateEvents(state: RegistryState, feature: FeatureDefinition): void;
+export declare function populateSystemEvents(state: RegistryState): void;
 export declare function populateTranslations(state: RegistryState, feature: FeatureDefinition): void;
 export declare function populateHooks(state: RegistryState, feature: FeatureDefinition): void;
 export declare function populateExtensionsAndSeeds(state: RegistryState, feature: FeatureDefinition): void;

package/dist/engine/registry-ingest.js

@@ -1,6 +1,7 @@
 import { resolveTableName } from "../db/entity-table-meta.js";
 import { buildMetricName, validateMetricName } from "../observability/index.js";
 import { mergeHookList, mergeHookListQualified, qualify } from "./registry-state.js";
+import { WORKFLOW_SYSTEM_EVENT_DEFS } from "./steps/workflow-system-events.js";
 // Feature registration + entities (globally-unique, physical-table-checked) + relations
 // (additive per entity, duplicate-per-name guarded).
 export function populateFeatureCore(state, feature) {
@@ -132,6 +133,14 @@ export function populateEvents(state, feature) {
         state.eventMap.set(qualified, { ...eventDef, name: qualified });
     }
 }
+// Framework-owned events outside any feature namespace (kumiko:system:workflow.*).
+// Seeded into the same eventMap as r.defineEvent so apply-key validation, the
+// PII catalog and the upcaster chain see them through one path.
+export function populateSystemEvents(state) {
+    for (const [name, eventDef] of WORKFLOW_SYSTEM_EVENT_DEFS) {
+        state.eventMap.set(name, eventDef);
+    }
+}
 export function populateTranslations(state, feature) {
     // Translations prefixed with featureName: (i18next namespace convention).
     // Keys that already carry the feature's own namespace prefix (e.g. a nav

package/dist/engine/registry.js

@@ -1,7 +1,7 @@
 import { validateExtensionPreSaveWiring } from "./boot-validator/entity-handler.js";
 import { dedupeFeatures } from "./dedupe-features.js";
 import { buildRegistryFacade } from "./registry-facade.js";
-import { populateClaimsAndAuth, populateConfigKeys, populateEvents, populateExtensionsAndSeeds, populateFeatureCore, populateHandlers, populateHooks, populateJobsAndNotifications, populateMetricsAndSecrets, populateProjectionsAndTables, populateScreensNavWorkspaces, populateTranslations, } from "./registry-ingest.js";
+import { populateClaimsAndAuth, populateConfigKeys, populateEvents, populateExtensionsAndSeeds, populateFeatureCore, populateHandlers, populateHooks, populateJobsAndNotifications, populateMetricsAndSecrets, populateProjectionsAndTables, populateScreensNavWorkspaces, populateSystemEvents, populateTranslations, } from "./registry-ingest.js";
 import { createInitialState } from "./registry-state.js";
 import { applyExtensionUsages, autoWireSoftDeleteJobs, buildEventUpcasterChains, buildImplicitProjections, buildIncomingRelations, buildSearchableSortableCaches, computeHasRateLimitedHandler, finalizeWorkspaceNavMembership, populateHandlerEntityMappings, publishEventPiiCatalog, resolveJobTriggers, resolveNotificationTriggersAndRegisterHooks, validateBootGates, validateEntityHookTargets, validateEventMigrationVersions, validateExtensionSelectors, validateExtensionUsageTargets, validateFieldAccessHandlersAreEntityMapped, validateJobBackoff, validateLifecycleHookTargets, validateLiveEntities, validateProjectionApplyKeys, validateRelationTargetsExist, validateRequiredFeatures, } from "./registry-validate.js";
 // This is where the magic happens. By "magic" I mean: precomputed maps.
@@ -24,6 +24,7 @@ export function createRegistry(rawFeatures) {
         populateClaimsAndAuth(state, feature);
         populateScreensNavWorkspaces(state, feature);
     }
+    populateSystemEvents(state);
     finalizeWorkspaceNavMembership(state);
     populateHandlerEntityMappings(state, features);
     validateExtensionSelectors(state);

package/dist/engine/steps/retry.js

@@ -54,7 +54,6 @@ defineStep({
                     workflowName: ctx.workflow.workflowName,
                     error: describeWorkflowStepError(error),
                     triggerEventType: ctx.event.type,
-                    triggerPayload: ctx.event.payload,
                     ...(ctx.workflow.definitionFingerprint && {
                         definitionFingerprint: ctx.workflow.definitionFingerprint,
                     }),

package/dist/engine/steps/wait-for-event.js

@@ -49,7 +49,6 @@ defineStep({
                 stepIndex: ctx.workflow.stepIndex,
                 workflowName: ctx.workflow.workflowName,
                 triggerEventType: ctx.event.type,
-                triggerPayload: ctx.event.payload,
                 ...(ctx.workflow.definitionFingerprint && {
                     definitionFingerprint: ctx.workflow.definitionFingerprint,
                 }),

package/dist/engine/steps/wait.js

@@ -32,11 +32,7 @@ defineStep({
                 wakeAt,
                 stepIndex: ctx.workflow.stepIndex,
                 workflowName: ctx.workflow.workflowName,
-                // Trigger snapshot: pinned so the resume-loop re-feeds the
-                // pipeline with what the original run saw. event-sourcing across
-                // suspensions hinges on this being stable.
                 triggerEventType: ctx.event.type,
-                triggerPayload: ctx.event.payload,
                 ...(ctx.workflow.definitionFingerprint && {
                     definitionFingerprint: ctx.workflow.definitionFingerprint,
                 }),

package/dist/engine/steps/workflow-system-events.d.ts

@@ -0,0 +1,2 @@
+import type { EventDef } from "@cosmicdrift/kumiko-types/handlers";
+export declare const WORKFLOW_SYSTEM_EVENT_DEFS: ReadonlyMap<string, EventDef>;

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.339.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.339.0",
+    "@cosmicdrift/kumiko-types": "0.339.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.339.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,45 @@
 [
+  {
+    "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",