@cosmicdrift/kumiko-framework 0.338.0 → 0.340.0

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/query-api.d.ts

@@ -1,2 +1,2 @@
-export type { SelectOptions, WhereObject, WhereOperator, WhereValue, } from "../db/query.js";
+export type { JsonTextMatch, SelectOptions, WhereObject, WhereOperator, WhereValue, } from "../db/query.js";
 export { aggregateWhere, asRawClient, countWhere, deleteMany, fetchOne, insertMany, insertOne, runInSavepoint, selectMany, transaction, updateMany, } from "../db/query.js";

package/dist/db/query.d.ts

@@ -1 +1 @@
-export { type AnyDb, aggregateWhere, asEntityTableMeta, asRawClient, coerceRow, countWhere, type DeleteManyBatchedOptions, type DeleteManyBatchedResult, deleteMany, deleteManyBatched, extractTableInfo, fetchOne, type IncrementCounterOptions, incrementCounter, insertMany, insertOne, type OrderByClause, runInNewTransaction, runInSavepoint, runInSavepointIfSupported, type SelectOptions, selectMany, type TableInfo, transaction, type UpsertOnConflictOptions, unsafeReadRetrying, updateMany, upsertByPk, upsertOnConflict, type WhereObject, type WhereOperator, type WhereValue, } from "../bun-db/query.js";
+export { type AnyDb, aggregateWhere, asEntityTableMeta, asRawClient, coerceRow, countWhere, type DeleteManyBatchedOptions, type DeleteManyBatchedResult, deleteMany, deleteManyBatched, extractTableInfo, fetchOne, type IncrementCounterOptions, incrementCounter, insertMany, insertOne, type JsonTextMatch, type OrderByClause, runInNewTransaction, runInSavepoint, runInSavepointIfSupported, type SelectOptions, selectMany, type TableInfo, transaction, type UpsertOnConflictOptions, unsafeReadRetrying, updateMany, upsertByPk, upsertOnConflict, type WhereObject, type WhereOperator, type WhereValue, } from "../bun-db/query.js";

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/unsafe-projection-upsert.js

@@ -4,7 +4,7 @@
 // natural key + tenantId). Skips lifecycle hooks, field-access,
 // crypto-shredding, schema-versioning, audit-trail, read-access-log.
 // See "Was unsafeProjection.* überspringt" in
-// docs/plans/architecture/intern/step-vocabulary.md.
+// kumiko-platform/docs/archive/plans/architecture/intern/step-vocabulary.md.
 //
 // Use only on tables explicitly declared via r.requires.projection in
 // the owning feature. Aggregate-tables (registered via r.entity) are

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>;