@cosmicdrift/kumiko-framework 0.342.0 → 0.344.0

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

@@ -6,6 +6,7 @@ import { type AuthSessionChecker, type AuthSessionStatus, type TokenVerifier } f
 import { type ClientIpResolver } from "./client-ip.js";
 import type { JwtHelper } from "./jwt.js";
 import type { PostAuthLandingResolver } from "./post-auth-landing.js";
+export declare function assertRetiredCookieDomains(retiredCookieDomains: readonly string[] | undefined, cookieDomain: string | undefined): void;
 export type LoginRateLimiter = {
     check(key: string): Promise<boolean>;
     reset(key: string): Promise<void>;
@@ -48,6 +49,7 @@ export type AuthRoutesConfig = {
     invite?: InviteConfig;
     cookieSameSite?: "lax" | "strict";
     cookieDomain?: string;
+    retiredCookieDomains?: readonly string[];
     allowedOrigins?: readonly string[];
     unsafeSkipOriginCheck?: boolean;
     trustedProxyHops?: number;

package/dist/api/auth-routes.js

@@ -44,12 +44,18 @@ function setAuthCookies(c, opts) {
         deleteCookie(c, AUTH_COOKIE_NAME, { path: "/" });
         deleteCookie(c, CSRF_COOKIE_NAME, { path: "/" });
     }
+    // Must precede the setCookie calls: browsers apply Set-Cookie in order and
+    // a retired domain equal to the new one is rejected at config time.
+    for (const retiredDomain of opts.retiredDomains) {
+        deleteCookie(c, AUTH_COOKIE_NAME, { path: "/", domain: retiredDomain });
+        deleteCookie(c, CSRF_COOKIE_NAME, { path: "/", domain: retiredDomain });
+    }
     setCookie(c, AUTH_COOKIE_NAME, opts.token, { ...common, httpOnly: true });
     // Intentionally NOT HttpOnly — the web client has to read this from
     // document.cookie to include it in the X-CSRF-Token request header.
     setCookie(c, CSRF_COOKIE_NAME, opts.csrfToken, { ...common, httpOnly: false });
 }
-function clearAuthCookies(c, domain) {
+function clearAuthCookies(c, domain, retiredDomains) {
     // Beide Varianten löschen: mit Domain (aktuelle Cookies) UND host-only
     // (Bestand aus der Zeit vor cookieDomain) — sonst bleibt nach einem
     // Deploy mit neu gesetztem cookieDomain der alte Cookie liegen und der
@@ -60,6 +66,30 @@ function clearAuthCookies(c, domain) {
         deleteCookie(c, AUTH_COOKIE_NAME, { path: "/", domain });
         deleteCookie(c, CSRF_COOKIE_NAME, { path: "/", domain });
     }
+    for (const retiredDomain of retiredDomains) {
+        deleteCookie(c, AUTH_COOKIE_NAME, { path: "/", domain: retiredDomain });
+        deleteCookie(c, CSRF_COOKIE_NAME, { path: "/", domain: retiredDomain });
+    }
+}
+const INVALID_COOKIE_DOMAIN_CHARS = /[;,\s]/;
+function normalizeCookieDomain(domain) {
+    return domain.replace(/^\./, "").toLowerCase();
+}
+// A malformed entry would corrupt the Set-Cookie header; an entry equal to the
+// current cookieDomain would make login delete the cookie it just sets.
+export function assertRetiredCookieDomains(retiredCookieDomains, cookieDomain) {
+    const current = cookieDomain === undefined ? undefined : normalizeCookieDomain(cookieDomain);
+    for (const entry of retiredCookieDomains ?? []) {
+        if (entry === "" || normalizeCookieDomain(entry) === "") {
+            throw new Error("createAuthRoutes: retiredCookieDomains must not contain an empty entry");
+        }
+        if (INVALID_COOKIE_DOMAIN_CHARS.test(entry)) {
+            throw new Error(`createAuthRoutes: retiredCookieDomains entry "${entry}" contains an invalid character (;, comma or whitespace)`);
+        }
+        if (normalizeCookieDomain(entry) === current) {
+            throw new Error(`createAuthRoutes: retiredCookieDomains entry "${entry}" equals cookieDomain; login would delete its own cookie`);
+        }
+    }
 }
 // Body schema for POST /auth/login. Enforced BEFORE rate-limit so that a
 // malformed body (`email: 42`, missing password, …) returns 400 instead of
@@ -297,6 +327,8 @@ export function createAuthRoutes(dispatcher, jwt, config) {
     // working. High-security apps can opt into "strict" — see AuthRoutesConfig.
     const cookieSameSite = config.cookieSameSite ?? "lax";
     const cookieDomain = config.cookieDomain;
+    assertRetiredCookieDomains(config.retiredCookieDomains, cookieDomain);
+    const retiredCookieDomains = config.retiredCookieDomains ?? [];
     // Single hop-count-aware IP getter for every rate-limit call site below —
     // see AuthRoutesConfig.trustedProxyHops and client-ip.ts's resolveClientIp
     // doc comment. createClientIpResolver fails loud on a non-finite/negative
@@ -322,6 +354,7 @@ export function createAuthRoutes(dispatcher, jwt, config) {
             csrfToken,
             sameSite: cookieSameSite,
             domain: cookieDomain,
+            retiredDomains: retiredCookieDomains,
             ttlSeconds: jwt.ttlSeconds,
         });
         return token;
@@ -849,7 +882,7 @@ export function createAuthRoutes(dispatcher, jwt, config) {
         }
         // Clear cookies on the cookie-transport path. Idempotent — clearing a
         // missing cookie is a no-op, so bearer-only clients aren't affected.
-        clearAuthCookies(c, cookieDomain);
+        clearAuthCookies(c, cookieDomain, retiredCookieDomains);
         return c.json({ isSuccess: true });
     });
     // GET /auth/tenants — list tenants the current user belongs to

package/dist/api/request-context.d.ts

@@ -1,10 +1,12 @@
 import { type WriteOrigin } from "@cosmicdrift/kumiko-types/event-store-types";
 import type { AgentRisk } from "@cosmicdrift/kumiko-types/handlers";
+import type { ErrorDocsConfig } from "../errors/docs-url.js";
 export type RequestContextData = {
     readonly requestId: string;
     readonly correlationId: string;
     readonly causationId?: string;
     readonly signal?: AbortSignal;
+    readonly errorDocs?: ErrorDocsConfig;
     readonly ip?: string;
     readonly userAgent?: string;
     readonly locale?: string;

package/dist/api/request-id-middleware.d.ts

@@ -1,4 +1,5 @@
 import type { Context, Next } from "hono";
+import type { ErrorDocsConfig } from "../errors/docs-url.js";
 import { type ClientIpResolver } from "./client-ip.js";
 import { type RequestContextData } from "./request-context.js";
 /**
@@ -34,4 +35,5 @@ export declare function buildRequestContextData(c: Context, resolver?: ClientIpR
 export declare function requestIdMiddleware(options?: {
     readonly resolver?: ClientIpResolver;
     readonly trustedProxyHops?: number;
+    readonly errorDocs?: ErrorDocsConfig;
 }): (c: Context, next: Next) => Promise<void>;

package/dist/api/request-id-middleware.js

@@ -103,7 +103,10 @@ export function requestIdMiddleware(options) {
     const resolver = options?.resolver ??
         createClientIpResolver(options?.trustedProxyHops ?? 0, "requestIdMiddleware");
     return async (c, next) => {
-        const data = buildRequestContextData(c, resolver);
+        const data = {
+            ...buildRequestContextData(c, resolver),
+            ...(options?.errorDocs && { errorDocs: options.errorDocs }),
+        };
         c.header(REQUEST_ID_HEADER, data.requestId);
         c.header(CORRELATION_ID_HEADER, data.correlationId);
         c.set("requestId", data.requestId);

package/dist/api/routes.js

@@ -71,7 +71,7 @@ export function createApiRoutes(dispatcher, options = {}) {
                 const requestId = requestContext.get()?.requestId;
                 const failedType = result.failedIndex != null ? body.commands[result.failedIndex]?.type : undefined;
                 logServerFault(err, requestId, failedType);
-                const { error } = serializeError(err, requestId);
+                const { error } = serializeError(err, requestId, requestContext.get()?.errorDocs);
                 // Keep failedIndex + results alongside the error envelope so callers
                 // can tell which command in the batch failed and inspect the partial
                 // results from the successful commands before the rollback.
@@ -182,7 +182,7 @@ export function createApiRoutes(dispatcher, options = {}) {
             catch (e) {
                 const err = toKumiko(e);
                 logServerFault(err, requestId, body.type);
-                const { error } = serializeError(err, requestId);
+                const { error } = serializeError(err, requestId, requestContext.get()?.errorDocs);
                 await stream.writeSSE({ event: StreamFrame.error, data: stringifyJson(error) });
             }
         });
@@ -354,7 +354,7 @@ function logServerFault(err, requestId, type) {
 function writeErrorResponse(c, err, type) {
     const requestId = requestContext.get()?.requestId;
     logServerFault(err, requestId, type);
-    const { error } = serializeError(err, requestId);
+    const { error } = serializeError(err, requestId, requestContext.get()?.errorDocs);
     return c.json({ isSuccess: false, error }, err.httpStatus); // @cast-boundary engine-payload
 }
 function clientAbortResponse(c, requestId, type) {
@@ -370,7 +370,7 @@ function queryErrorResponse(c, err, type) {
     if (isClientAbort(err))
         return clientAbortResponse(c, requestId, type);
     logServerFault(err, requestId, type);
-    const body = serializeError(err, requestId);
+    const body = serializeError(err, requestId, requestContext.get()?.errorDocs);
     return c.json(body, err.httpStatus); // @cast-boundary engine-payload
 }
 // A raw throw under the request signal (signal.throwIfAborted(), an aborted
@@ -391,5 +391,5 @@ export function handleUncaughtRouteError(err, c) {
         return clientAbortResponse(c, requestId);
     const kumikoError = toKumiko(err);
     logServerFault(kumikoError, requestId);
-    return c.json(serializeError(kumikoError, requestId), kumikoError.httpStatus); // @cast-boundary engine-payload
+    return c.json(serializeError(kumikoError, requestId, requestContext.get()?.errorDocs), kumikoError.httpStatus); // @cast-boundary engine-payload
 }

package/dist/api/server.d.ts

@@ -2,6 +2,7 @@ import type { CacheSyncBus } from "@cosmicdrift/kumiko-types/cache-sync-types";
 import { Hono } from "hono";
 import type { PgClient } from "../db/connection.js";
 import { type AppContext, type Registry, type RunIn, type WriteResult } from "../engine/types/index.js";
+import type { ErrorDocsConfig } from "../errors/docs-url.js";
 import type { Lifecycle } from "../lifecycle/index.js";
 import { type ObservabilityOptions, type ObservabilityProvider } from "../observability/index.js";
 import type { DispatcherOptions } from "../pipeline/dispatcher.js";
@@ -27,6 +28,8 @@ export type ServerOptions = {
     sseBroker?: SseBroker;
     auth?: AuthRoutesConfig;
     trustedProxyHops?: number;
+    /** Links the app's own error reasons to its own docs (`docsUrl` in error responses). Framework reasons keep linking to the framework docs. */
+    errorDocs?: ErrorDocsConfig;
     eventDispatcher?: {
         pollIntervalMs?: number;
         batchSize?: number;

package/dist/api/server.js

@@ -422,7 +422,10 @@ export function buildServer(options) {
     if (options.metrics) {
         registerMetricsRoute(app, observability.meter, options.metrics);
     }
-    app.use("/api/*", requestIdMiddleware({ resolver: clientIpResolver }));
+    app.use("/api/*", requestIdMiddleware({
+        resolver: clientIpResolver,
+        ...(options.errorDocs && { errorDocs: options.errorDocs }),
+    }));
     // Cap JSON bodies before rate-limit/auth/observability even run. Header-
     // check is O(1); oversized requests never allocate memory for a full body
     // parse. Upload route keeps its own per-field maxSize.

package/dist/compliance/duration-spec.d.ts

@@ -1,7 +1,8 @@
 import { getTemporal } from "../time/index.js";
-import type { DurationSpec } from "./profiles.js";
+import type { DurationSpec, RetentionSpec } from "./profiles.js";
 type Instant = InstanceType<ReturnType<typeof getTemporal>["Instant"]>;
 export declare function durationSpecToMs(spec: DurationSpec): number;
 export declare function addDurationSpec(now: Instant, spec: DurationSpec): Instant;
 export declare function describeDurationSpec(spec: DurationSpec): string;
+export declare function subtractRetentionSpec(now: Instant, spec: RetentionSpec): Instant;
 export {};

package/dist/compliance/duration-spec.js

@@ -35,3 +35,14 @@ export function describeDurationSpec(spec) {
         return `${spec.days} day${spec.days === 1 ? "" : "s"}`;
     return `${spec.hours} hour${spec.hours === 1 ? "" : "s"}`;
 }
+// Calendar-aware cutoff: months/years are subtracted on a UTC calendar so
+// "24 months" is not approximated as 730 fixed days (leap years, month ends).
+export function subtractRetentionSpec(now, spec) {
+    if ("months" in spec) {
+        return now.toZonedDateTimeISO("UTC").subtract({ months: spec.months }).toInstant();
+    }
+    if ("years" in spec) {
+        return now.toZonedDateTimeISO("UTC").subtract({ years: spec.years }).toInstant();
+    }
+    return getTemporal().Instant.fromEpochMilliseconds(now.epochMilliseconds - durationSpecToMs(spec));
+}

package/dist/compliance/index.d.ts

@@ -1,6 +1,6 @@
-export { addDurationSpec, describeDurationSpec, durationSpecToMs, } from "./duration-spec.js";
+export { addDurationSpec, describeDurationSpec, durationSpecToMs, subtractRetentionSpec, } from "./duration-spec.js";
 export { complianceProfileOverrideSchema } from "./override-schema.js";
-export type { AuthorityNotificationDeadline, ComplianceProfile, ComplianceProfileKey, ComplianceProfileOverride, DurationSpec, EffectiveComplianceProfile, UserNotificationRequiredPolicy, } from "./profiles.js";
+export type { AuthorityNotificationDeadline, ComplianceProfile, ComplianceProfileKey, ComplianceProfileOverride, DurationSpec, EffectiveComplianceProfile, RetentionSpec, UserNotificationRequiredPolicy, } from "./profiles.js";
 export { COMPLIANCE_PROFILES, OVERRIDABLE_PROFILE_KEYS, resolveComplianceProfile, SELECTABLE_PROFILE_KEYS, } from "./profiles.js";
 export type { BundleTier, SubProcessor } from "./sub-processors.js";
 export { getActiveSubProcessors, getPlannedSubProcessors, KUMIKO_SUB_PROCESSORS, } from "./sub-processors.js";

package/dist/compliance/index.js

@@ -1,7 +1,7 @@
 // `@cosmicdrift/kumiko-framework/compliance` — Datenschutz/Compliance-
 // Foundation. Wird von Sprint-1+ Features genutzt (compliance-profiles,
 // data-retention, user-data-rights, ...).
-export { addDurationSpec, describeDurationSpec, durationSpecToMs, } from "./duration-spec.js";
+export { addDurationSpec, describeDurationSpec, durationSpecToMs, subtractRetentionSpec, } from "./duration-spec.js";
 export { complianceProfileOverrideSchema } from "./override-schema.js";
 export { COMPLIANCE_PROFILES, OVERRIDABLE_PROFILE_KEYS, resolveComplianceProfile, SELECTABLE_PROFILE_KEYS, } from "./profiles.js";
 export { getActiveSubProcessors, getPlannedSubProcessors, KUMIKO_SUB_PROCESSORS, } from "./sub-processors.js";

package/dist/compliance/profiles.d.ts

@@ -5,6 +5,11 @@ export type DurationSpec = {
 } | {
     readonly hours: number;
 };
+export type RetentionSpec = DurationSpec | {
+    readonly months: number;
+} | {
+    readonly years: number;
+};
 export type AuthorityNotificationDeadline = DurationSpec | "as-soon-as-feasible" | "in-most-expedient-time" | "manual";
 export type UserNotificationRequiredPolicy = "if-high-risk" | "if-real-risk-of-significant-harm" | "if-serious-risk-of-injury" | "always-if-encrypted-data-or-pii" | "always-without-undue-delay" | "manual";
 export interface ComplianceProfile {
@@ -42,11 +47,7 @@ export interface ComplianceProfile {
         readonly mandatoryRegisterOfBreaches?: boolean;
     };
     readonly auditLog: {
-        readonly retention: DurationSpec | {
-            readonly months: number;
-        } | {
-            readonly years: number;
-        };
+        readonly retention: RetentionSpec;
         readonly reportFrequency: "quarterly" | "yearly" | "annual-required" | "manual";
     };
     readonly subProcessor: {

package/dist/db/entity-field-encryption.d.ts

@@ -12,4 +12,4 @@ export declare function resolveEntityFieldEncryption(): EnvelopeCipher;
 export declare function configuredEntityFieldEncryption(): EnvelopeCipher | undefined;
 /** @internal test-only */
 export declare function resetEntityFieldEncryptionCacheForTests(): void;
-export declare function validateEntityFieldEncryptionAvailable(env?: Readonly<Record<string, string | undefined>>): void;
+export declare function validateEntityFieldEncryptionAvailable(env?: Readonly<Record<string, string | undefined>>, bootCipher?: EnvelopeCipher): void;

package/dist/db/entity-field-encryption.js

@@ -106,9 +106,9 @@ export function resetEntityFieldEncryptionCacheForTests() {
 // surfaces missing AND malformed keys (wrong length, bad base64) at boot
 // instead of on the first encrypted read in prod. validateBoot runs before
 // configureEntityFieldEncryption, so the env probe is the common path.
-export function validateEntityFieldEncryptionAvailable(env = process.env) {
-    // skip: an injected cipher (test seam / custom KMS) satisfies availability
-    if (injectedCipher)
+export function validateEntityFieldEncryptionAvailable(env = process.env, bootCipher) {
+    // skip: an injected cipher (test seam / custom KMS) or the runner's boot cipher satisfies availability
+    if (bootCipher ?? injectedCipher)
         return;
     try {
         createEnvMasterKeyProvider({
@@ -121,7 +121,7 @@ export function validateEntityFieldEncryptionAvailable(env = process.env) {
     catch (err) {
         const reason = err instanceof Error ? err.message : String(err);
         throw new Error(`encrypted entity fields in use but no usable master key (${reason}) — set ` +
-            "KUMIKO_SECRETS_MASTER_KEY_V1 (32 bytes, base64) or inject a cipher via " +
-            "configureEntityFieldEncryption().");
+            "KUMIKO_SECRETS_MASTER_KEY_V1 (32 bytes, base64) or pass `masterKey` to " +
+            "runProdApp/runWorkerApp (or inject a cipher via configureEntityFieldEncryption()).");
     }
 }

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

@@ -5,13 +5,28 @@ import { SYSTEM_ROLE, SYSTEM_USER_ID } from "../engine/system-user.js";
 import { AccessDeniedError, VersionConflictError as FrameworkVersionConflict, IdempotentReplayError, InternalError, NotFoundError, PreconditionFailedError, UnprocessableError, writeFailure, } from "../errors/index.js";
 import { append, IdempotentAppendConflictError as EventStoreIdempotentAppendConflict, VersionConflictError as EventStoreVersionConflict, getStreamVersion, } from "../event-store/index.js";
 import { assertInstructionFieldWriteAllowed, assertIrreversibleOperationAllowed, isIrreversibleEntityVerb, } from "../pipeline/irreversible-operation-gate.js";
+import { hasLiveProjectionsForEvent, runProjectionsForEvent, } from "../pipeline/projections-runner.js";
 import { generateId } from "../utils/index.js";
 import { applyEntityEvent } from "./apply-entity-event.js";
 import { flattenCompoundTypes, rehydrateCompoundTypes } from "./compound-types.js";
 import { buildEventMetadata, entityEventName, isForeignTenantOnGlobalEntity, tryMapUniqueViolation, } from "./event-store-executor-context.js";
+import { projectionRegistryOf } from "./projection-registry-binding.js";
 import { runInSavepointIfSupported } from "./query.js";
 import { assertPersonalDataWrite, tableNameOf } from "./tenant-db.js";
 import { tenantDbRunner } from "./tenant-db-runner.js";
+// Custom projections for a write that did not go through the dispatcher (hook or
+// job writing a second aggregate). Savepoint like applyEntityEvent: a throwing
+// projection fails the write and the caller's transaction rolls it back.
+async function projectEntityEvent(db, runner, event) {
+    const registry = projectionRegistryOf(db);
+    // skip: TenantDb not built by a dispatcher/job runner — nothing bound to project with
+    if (!registry)
+        return;
+    // skip: no live projection listens — avoid a SAVEPOINT round trip on every plain write
+    if (!hasLiveProjectionsForEvent(event, registry))
+        return;
+    await runInSavepointIfSupported(runner, (sp) => runProjectionsForEvent(event, registry, sp));
+}
 // Art. 17 erasure runs as the framework operator, not as a row owner; a
 // per-role ownership map can never cover it, and a silent deny means the
 // erasure never happened.
@@ -215,6 +230,10 @@ export function createWriteVerbs(ctx) {
             if (entityCache && entityName) {
                 await entityCache.del(user.tenantId, entityName, aggregateId);
             }
+            // The echoed event is the one projections see (and the dispatcher later
+            // skips), so build it before projecting.
+            const echoEvent = { ...event, payload: stripSensitive(flatCreateData) };
+            await projectEntityEvent(db, runner, echoEvent);
             return {
                 isSuccess: true,
                 data: {
@@ -227,7 +246,7 @@ export function createWriteVerbs(ctx) {
                     entityName,
                     // Persisted event carries ciphertext by design — the caller-facing
                     // echo must be plaintext like every other response field (#820).
-                    event: { ...event, payload: stripSensitive(flatCreateData) },
+                    event: echoEvent,
                 },
             };
         },
@@ -404,6 +423,14 @@ export function createWriteVerbs(ctx) {
                 if (entityCache && entityName) {
                     await entityCache.del(user.tenantId, entityName, payload.id);
                 }
+                const echoEvent = {
+                    ...event,
+                    payload: {
+                        changes: stripSensitive(flatChangesPlain),
+                        previous: stripSensitive(previous),
+                    },
+                };
+                await projectEntityEvent(db, runner, echoEvent);
                 return {
                     isSuccess: true,
                     data: {
@@ -414,13 +441,7 @@ export function createWriteVerbs(ctx) {
                         previous,
                         isNew: false,
                         entityName,
-                        event: {
-                            ...event,
-                            payload: {
-                                changes: stripSensitive(flatChangesPlain),
-                                previous: stripSensitive(previous),
-                            },
-                        },
+                        event: echoEvent,
                     },
                 };
             }
@@ -508,6 +529,8 @@ export function createWriteVerbs(ctx) {
             if (entityCache && entityName) {
                 await entityCache.del(user.tenantId, entityName, payload.id);
             }
+            const echoEvent = { ...event, payload: { previous: stripSensitive(existing) } };
+            await projectEntityEvent(db, runner, echoEvent);
             return {
                 isSuccess: true,
                 data: {
@@ -515,7 +538,7 @@ export function createWriteVerbs(ctx) {
                     id: payload.id,
                     data: existing,
                     entityName,
-                    event: { ...event, payload: { previous: stripSensitive(existing) } },
+                    event: echoEvent,
                 },
             };
         },
@@ -579,6 +602,8 @@ export function createWriteVerbs(ctx) {
             if (entityCache && entityName) {
                 await entityCache.del(user.tenantId, entityName, payload.id);
             }
+            const echoEvent = { ...event, payload: { previous: stripSensitive(existing) } };
+            await projectEntityEvent(db, runner, echoEvent);
             return {
                 isSuccess: true,
                 data: {
@@ -586,7 +611,7 @@ export function createWriteVerbs(ctx) {
                     id: payload.id,
                     data: existing,
                     entityName,
-                    event: { ...event, payload: { previous: stripSensitive(existing) } },
+                    event: echoEvent,
                 },
             };
         },
@@ -685,6 +710,8 @@ export function createWriteVerbs(ctx) {
             // (db.fetchOne / applyEntityEvent), never decrypted before this point.
             const restoredHydrated = await decryptForRead(rehydrateCompoundTypes(restored, entity));
             const previousPlain = await decryptForRead(data);
+            const echoEvent = { ...event, payload: { previous: stripSensitive(previousPlain) } };
+            await projectEntityEvent(db, runner, echoEvent);
             return {
                 isSuccess: true,
                 data: {
@@ -695,7 +722,7 @@ export function createWriteVerbs(ctx) {
                     previous: previousPlain,
                     isNew: false,
                     entityName,
-                    event: { ...event, payload: { previous: stripSensitive(previousPlain) } },
+                    event: echoEvent,
                 },
             };
         },

package/dist/db/projection-registry-binding.d.ts

@@ -0,0 +1,3 @@
+import type { Registry } from "../engine/types/index.js";
+export declare function bindProjectionRegistry(target: object, registry: Registry): void;
+export declare function projectionRegistryOf(target: object): Registry | undefined;

package/dist/db/projection-registry-binding.js

@@ -0,0 +1,12 @@
+// A WeakMap rather than a process-global registry: test files boot several
+// stacks in one process, each with its own Registry. Keys are TenantDbs and
+// per-grant runner proxies — never the shared pool or tx handle, which would
+// leak one dispatcher's registry onto sibling TenantDbs.
+const bindings = new WeakMap();
+export function bindProjectionRegistry(target, registry) {
+    bindings.set(target, registry);
+}
+// WeakMap.get never reads a property off target — safe for fail-closed guard Proxies.
+export function projectionRegistryOf(target) {
+    return bindings.get(target);
+}

package/dist/db/tenant-db.d.ts

@@ -5,6 +5,7 @@ import { type TenantDb, type TenantDbMode, type UncheckedSystemDb } from "@cosmi
 import { asRawClient } from "../db/query.js";
 import type { EntityDefinition } from "../engine/types/fields.js";
 import { type TenantId } from "../engine/types/identifiers.js";
+import type { Registry } from "../engine/types/index.js";
 import { type Meter, type Tracer } from "../observability/index.js";
 import type { DbRunner } from "./connection.js";
 type Table = SchemaTable;
@@ -23,6 +24,7 @@ export type TenantDbGrants = {
     readonly report?: EscapeHatchReporter;
     readonly memberReadOnly?: boolean;
     readonly personalDataGate?: PersonalDataGate;
+    readonly projectionRegistry?: Registry;
 };
 export type PersonalDataGate = (tableName: string, keys: readonly string[], entity?: EntityDefinition) => void;
 export declare function withUnsafeRawGrant(tenantDb: TenantDb, grant: EscapeHatchDeclaration | undefined): TenantDb;

package/dist/db/tenant-db.js

@@ -4,6 +4,7 @@ import { asEntityTableMeta, asRawClient, aggregateWhere as bunAggregateWhere, co
 import { SYSTEM_TENANT_ID } from "../engine/types/identifiers.js";
 import { AccessDeniedError, InternalError, memberResolutionReadOnlyDenied, } from "../errors/index.js";
 import { emitDbQuery, fallbackEscapeHatchReporter, registerStandardMetrics, } from "../observability/index.js";
+import { bindProjectionRegistry, projectionRegistryOf } from "./projection-registry-binding.js";
 import { bindTenantDbRunner, tenantDbRunner } from "./tenant-db-runner.js";
 export { SYSTEM_SCOPE_CHECK_BRAND, } from "@cosmicdrift/kumiko-types/tenant-db-types";
 const declaredUnsafeRawRunners = new WeakMap();
@@ -14,7 +15,7 @@ const personalDataGates = new WeakMap();
 // 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) {
+function gatedRunner(runner, gate, projectionRegistry) {
     const proxy = new Proxy(runner, {
         // Tagged-template calls need the real driver object as `this`.
         apply(target, _thisArg, args) {
@@ -33,7 +34,7 @@ function gatedRunner(runner, gate) {
                     }
                     const gatedArgs = [
                         ...args.slice(0, -1),
-                        (tx) => callback(gatedRunner(tx, gate)),
+                        (tx) => callback(gatedRunner(tx, gate, projectionRegistry)),
                     ];
                     return Reflect.apply(value, target, gatedArgs);
                 };
@@ -43,6 +44,8 @@ function gatedRunner(runner, gate) {
         // @cast-boundary proxy-erasure — Proxy<object> re-tags as the wrapped DbRunner shape.
     });
     runnerPersonalDataGates.set(proxy, gate);
+    if (projectionRegistry)
+        bindProjectionRegistry(proxy, projectionRegistry);
     return proxy;
 }
 // The executor passes its entity so the check does not depend on the table-name lookup.
@@ -119,7 +122,9 @@ function buildUncheckedSystemDb(db, dbOutsideTransaction, report, gate) {
         report("unsafe-raw", forwardedDeclaredStep ? reason : (gate?.grant?.reason ?? reason));
         const runner = tenantDbRunner(db);
         const personalDataGate = personalDataGates.get(db);
-        return personalDataGate ? gatedRunner(runner, personalDataGate) : runner;
+        return personalDataGate
+            ? gatedRunner(runner, personalDataGate, projectionRegistryOf(db))
+            : runner;
     }
     const uncheckedSystemDb = {
         [SYSTEM_SCOPE_CHECK_BRAND]: true,
@@ -272,6 +277,11 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
         registerStandardMetrics(meter);
     const report = grants?.report ?? fallbackEscapeHatchReporter(tenantId);
     const personalDataGate = grants?.personalDataGate ?? runnerPersonalDataGates.get(db);
+    const projectionRegistry = grants?.projectionRegistry ?? projectionRegistryOf(db);
+    // Rebinders carry the resolved registry explicitly: a fresh tx handle is not tagged.
+    const rebindGrants = projectionRegistry && grants?.projectionRegistry === undefined
+        ? { ...grants, projectionRegistry }
+        : grants;
     function withDbSpan(operation, table, runner) {
         signal?.throwIfAborted();
         if (!tracer && !meter)
@@ -446,7 +456,7 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
         }
         // 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;
+        return personalDataGate ? gatedRunner(db, personalDataGate, projectionRegistry) : db;
     }
     const tenantDb = {
         tenantId,
@@ -509,10 +519,13 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
         },
     };
     declaredUnsafeRawRunners.set(tenantDb, grantedUnsafeRawRunner);
-    unsafeRawRebinders.set(tenantDb, (grant) => createTenantDb(db, tenantId, mode, tracer, meter, signal, { ...grants, unsafeRaw: grant }));
+    unsafeRawRebinders.set(tenantDb, (grant) => createTenantDb(db, tenantId, mode, tracer, meter, signal, {
+        ...rebindGrants,
+        unsafeRaw: grant,
+    }));
     crossTenantRebinders.set(tenantDb, (reason) => {
         report("acknowledge-cross-tenant", reason);
-        return createTenantDb(db, tenantId, "system", tracer, meter, signal, grants);
+        return createTenantDb(db, tenantId, "system", tracer, meter, signal, rebindGrants);
     });
     ownTransactionRebinders.set(tenantDb, async (fn) => {
         if (grants?.memberReadOnly) {
@@ -522,12 +535,14 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
             });
         }
         // Carries a runner-bound gate (grants.personalDataGate unset, resolved via the fallback above) forward explicitly, since the fresh tx-handle isn't itself registered in runnerPersonalDataGates.
-        const txGrants = personalDataGate ? { ...grants, personalDataGate } : grants;
+        const txGrants = personalDataGate ? { ...rebindGrants, personalDataGate } : rebindGrants;
         return runInNewTransaction(db, (tx) => fn(createTenantDb(tx, tenantId, mode, tracer, meter, signal, txGrants)));
     });
     bindTenantDbRunner(tenantDb, db);
     if (personalDataGate)
         personalDataGates.set(tenantDb, personalDataGate);
+    if (projectionRegistry)
+        bindProjectionRegistry(tenantDb, projectionRegistry);
     return tenantDb;
 }
 export { asRawClient };

package/dist/engine/boot-validator/index.d.ts

@@ -1,3 +1,4 @@
+import type { EnvelopeCipher } from "../../secrets/envelope-cipher.js";
 import type { FeatureDefinition } from "../types/index.js";
 export { validateAppCustomScreenWriteQns } from "./custom-screen-write-qns.js";
 export { collectWriteHandlerQns } from "./nav.js";
@@ -26,7 +27,17 @@ export type ValidateBootOptions = {
      *  `process.env`; runners pass their resolved env so a ciphertext-only
      *  key (already decrypted at boot) is visible to the probe. */
     readonly env?: Readonly<Record<string, string | undefined>>;
+    /** The cipher the runner injects after validation (built from the app's
+     *  `masterKey` or the env keyring). Satisfies the availability check for
+     *  `encrypted: true` fields without an env KEK. */
+    readonly entityFieldCipher?: EnvelopeCipher;
 };
+/**
+ * Subset-safe slice of validateBoot for test stacks: nav references (screen,
+ * parent, workspace, tree actions), workspaces and nav cycles. The checks that
+ * need the whole app composition (screens, ref entities) run only in validateBoot.
+ */
+export declare function validateNavBootSubset(rawFeatures: readonly FeatureDefinition[]): void;
 /**
  * Validates all feature configurations at boot time.
  * Throws on the first error found — fail fast.