@cosmicdrift/kumiko-framework 0.341.0 → 0.343.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/crypto/kek-source.d.ts

@@ -16,8 +16,7 @@ export type KekSourceOptions = {
     readonly logPrefix?: string;
     /** Where the boot line naming the KEK source goes. Defaults to `console.info`. */
     readonly log?: (message: string) => void;
-    /** Env names to resolve, e.g. `kmsSlotsOf(schema)`. Defaults to the three
-     *  platform slots. */
-    readonly slots?: readonly string[];
+    /** Env names to resolve, e.g. `kmsSlotsOf(schema)`. */
+    readonly slots: readonly string[];
 };
-export declare function resolvePlatformKeks(env: KekSourceEnv, options?: KekSourceOptions): Promise<KekSourceEnv>;
+export declare function resolvePlatformKeks(env: KekSourceEnv, options: KekSourceOptions): Promise<KekSourceEnv>;

package/dist/crypto/kek-source.js

@@ -7,9 +7,6 @@ const SCALEWAY_KEY_MANAGER_API_VERSION = "v1alpha1";
 const DEFAULT_REGION = "fr-par";
 const DECRYPT_TIMEOUT_MS = 5_000;
 const RETRY_DELAYS_MS = [200, 800];
-// Used when the caller names no slots. Apps that predate `kms` schema meta
-// rely on it; drop once every consumer declares its slots in the env schema.
-const LEGACY_SLOTS = ["PLATFORM_KEK", "PLATFORM_KEK_PREVIOUS", "KUMIKO_BLIND_INDEX_KEY"];
 function isRetryableStatus(status) {
     return status >= 500;
 }
@@ -97,10 +94,10 @@ async function resolveSlot(name, env, options, fetchImpl) {
 // another slot's fallback path — the trio check downstream still applies.
 // Slots resolve in parallel: sequentially, a slow Key Manager would cost up to
 // ~16 s per slot (3 x 5 s timeout + backoff) and could trip startup probes.
-export async function resolvePlatformKeks(env, options = {}) {
+export async function resolvePlatformKeks(env, options) {
     const fetchImpl = options.fetch ?? globalThis.fetch;
     const prefix = options.logPrefix ? `${options.logPrefix} ` : "";
-    const slots = options.slots ?? LEGACY_SLOTS;
+    const { slots } = options;
     // Misconfiguration must not cost a Key Manager round trip.
     if (slots.includes("PLATFORM_KEK_PREVIOUS") &&
         (env.PLATFORM_KEK_PREVIOUS || env.PLATFORM_KEK_PREVIOUS_CIPHERTEXT) &&

package/dist/crypto/kms-wiring.d.ts

@@ -62,6 +62,6 @@ export declare function requireKmsWiring(env: KmsWiringEnv, options?: KmsWiringO
  *  from a Key Manager ciphertext first when no plaintext is set — see
  *  `resolvePlatformKeks`. The validation stays in the sync function; this only
  *  adds the KEK-fetching step in front of it. */
-export declare function resolveKmsWiringAsync(env: KmsWiringEnv, options?: KmsWiringOptions & KekSourceOptions): Promise<KmsWiring>;
+export declare function resolveKmsWiringAsync(env: KmsWiringEnv, options: KmsWiringOptions & KekSourceOptions): Promise<KmsWiring>;
 /** Async counterpart to `requireKmsWiring`, KEK-resolving like `resolveKmsWiringAsync`. */
-export declare function requireKmsWiringAsync(env: KmsWiringEnv, options?: KmsWiringOptions & KekSourceOptions): Promise<ActiveKmsWiring>;
+export declare function requireKmsWiringAsync(env: KmsWiringEnv, options: KmsWiringOptions & KekSourceOptions): Promise<ActiveKmsWiring>;

package/dist/crypto/kms-wiring.js

@@ -116,10 +116,10 @@ export function requireKmsWiring(env, options = {}) {
  *  from a Key Manager ciphertext first when no plaintext is set — see
  *  `resolvePlatformKeks`. The validation stays in the sync function; this only
  *  adds the KEK-fetching step in front of it. */
-export async function resolveKmsWiringAsync(env, options = {}) {
+export async function resolveKmsWiringAsync(env, options) {
     return resolveKmsWiring(await resolvePlatformKeks(env, options), options);
 }
 /** Async counterpart to `requireKmsWiring`, KEK-resolving like `resolveKmsWiringAsync`. */
-export async function requireKmsWiringAsync(env, options = {}) {
+export async function requireKmsWiringAsync(env, options) {
     return requireKmsWiring(await resolvePlatformKeks(env, options), options);
 }

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

@@ -20,7 +20,7 @@ export { createEventStoreExecutor, entityEventName } from "./event-store-executo
 export { enumerateFeatureTableSources, type FeatureTableSource, } from "./feature-table-sources.js";
 export { flattenLocatedTimestamp, rehydrateLocatedTimestamp } from "./located-timestamp.js";
 export { assertValidMigrationName, diffSnapshots, type GenerateMigrationInput, type GenerateMigrationOutput, generateMigration, loadSnapshotJson, renderMigrationSql, type SchemaDiff, type Snapshot, snapshotFromMetas, writeSnapshotJson, } from "./migrate-generator.js";
-export { type AppliedMigration, type ApplyResult, type BaselineResult, baselineMigrations, fetchAppliedMigrations, loadMigrationsFromDir, type Migration, MigrationChecksumMismatchError, runMigrations, runMigrationsFromDir, splitSqlStatements, } from "./migrate-runner.js";
+export { type AppliedMigration, type ApplyResult, type BaselineResult, baselineMigrations, fetchAppliedMigrations, loadMigrationsFromDir, type Migration, MigrationChecksumMismatchError, readMigrationSqlTexts, runMigrations, runMigrationsFromDir, splitSqlStatements, } from "./migrate-runner.js";
 export { flattenMoney, type MoneyRead, moneyPayloadToMinorUnits, rehydrateMoney } from "./money.js";
 export { constraintOf, extractPgError, isTableAlreadyExists, isUniqueViolation, type PgErrorInfo, } from "./pg-error.js";
 export { acquireNamespacedAdvisoryLock } from "./queries/advisory-lock.js";
@@ -31,6 +31,7 @@ export { readRebuildMarker, rebuildTablesFromDiff, writeRebuildMarker, } from ".
 export { seedReferenceData } from "./reference-data.js";
 export { renderTableDdl, renderTablesDdl } from "./render-ddl.js";
 export { diffReplayAgainstSnapshot, type ReplayedSchema, type ReplayedTable, type ReplayMismatch, replayMigrationsDir, } from "./replay-migration-sql.js";
+export { findCommentedDropTables, isRetiredFrameworkTable, type RetiredFrameworkTable, retiredFrameworkTables, } from "./retired-framework-tables.js";
 export { tableExists } from "./schema-inspection.js";
 export { buildBaseColumns, buildEntityTable, declareGlobalTenancy, type EntityTable, physicalColumnName, toSnakeCase, toTableName, } from "./table-builder.js";
 export type { TenantDb, TenantDbGrants, TenantDbMode, UncheckedSystemDb } from "./tenant-db.js";

package/dist/db/index.js

@@ -14,7 +14,7 @@ export { createEventStoreExecutor, entityEventName } from "./event-store-executo
 export { enumerateFeatureTableSources, } from "./feature-table-sources.js";
 export { flattenLocatedTimestamp, rehydrateLocatedTimestamp } from "./located-timestamp.js";
 export { assertValidMigrationName, diffSnapshots, generateMigration, loadSnapshotJson, renderMigrationSql, snapshotFromMetas, writeSnapshotJson, } from "./migrate-generator.js";
-export { baselineMigrations, fetchAppliedMigrations, loadMigrationsFromDir, MigrationChecksumMismatchError, runMigrations, runMigrationsFromDir, splitSqlStatements, } from "./migrate-runner.js";
+export { baselineMigrations, fetchAppliedMigrations, loadMigrationsFromDir, MigrationChecksumMismatchError, readMigrationSqlTexts, runMigrations, runMigrationsFromDir, splitSqlStatements, } from "./migrate-runner.js";
 export { flattenMoney, moneyPayloadToMinorUnits, rehydrateMoney } from "./money.js";
 export { constraintOf, extractPgError, isTableAlreadyExists, isUniqueViolation, } from "./pg-error.js";
 export { acquireNamespacedAdvisoryLock } from "./queries/advisory-lock.js";
@@ -24,6 +24,7 @@ export { readRebuildMarker, rebuildTablesFromDiff, writeRebuildMarker, } from ".
 export { seedReferenceData } from "./reference-data.js";
 export { renderTableDdl, renderTablesDdl } from "./render-ddl.js";
 export { diffReplayAgainstSnapshot, replayMigrationsDir, } from "./replay-migration-sql.js";
+export { findCommentedDropTables, isRetiredFrameworkTable, retiredFrameworkTables, } from "./retired-framework-tables.js";
 export { tableExists } from "./schema-inspection.js";
 export { buildBaseColumns, buildEntityTable, declareGlobalTenancy, physicalColumnName, toSnakeCase, toTableName, } from "./table-builder.js";
 export { castTenantRows, createSystemDbView, createTenantDb, runInOwnTransaction, SYSTEM_SCOPE_CHECK_BRAND, } from "./tenant-db.js";

package/dist/db/migrate-generator.d.ts

@@ -1,4 +1,5 @@
 import type { ColumnMeta, EntityTableMeta, IndexMeta } from "./entity-table-meta.js";
+import { type RetiredFrameworkTable } from "./retired-framework-tables.js";
 declare const SNAPSHOT_VERSION: 1;
 export type Snapshot = {
     readonly version: typeof SNAPSHOT_VERSION;
@@ -62,18 +63,23 @@ export declare function managedChangeRequiresRecreate(td: TableDiff): boolean;
 export declare function renderMigrationSql(diff: SchemaDiff, options: {
     readonly name: string;
     readonly sequenceNumber: number;
+    readonly retiredDrops?: readonly RetiredFrameworkTable[];
 }): string;
 export type GenerateMigrationInput = {
     readonly metas: readonly EntityTableMeta[];
     readonly prevSnapshot: Snapshot | null;
     readonly name: string;
     readonly sequenceNumber: number;
+    /** Raw SQL of all earlier migrations, in order — lets the generator decide
+     *  whether a retired framework table still needs its executable drop. */
+    readonly priorMigrationsSql?: readonly string[];
 };
 export type GenerateMigrationOutput = {
     readonly filename: string;
     readonly sqlContent: string;
     readonly snapshot: Snapshot;
     readonly diff: SchemaDiff;
+    readonly retiredDrops: readonly RetiredFrameworkTable[];
 };
 export declare const MIGRATION_NAME_RE: RegExp;
 export declare function assertValidMigrationName(name: string): void;

package/dist/db/migrate-generator.js

@@ -17,6 +17,7 @@
 import { readFileSync, writeFileSync } from "node:fs";
 import { compareByCodepoint } from "../utils/index.js";
 import { renderIndex, renderTableDdl } from "./render-ddl.js";
+import { findRetiredTableDrops } from "./retired-framework-tables.js";
 const SNAPSHOT_VERSION = 1;
 export function snapshotFromMetas(metas) {
     // Stable ordering by tableName so the snapshot.json diff in PRs is
@@ -321,6 +322,7 @@ function describeIndexChange(change) {
 // the index serves performance) are emitted as commented-out statements
 // for explicit reviewer-action.
 export function renderMigrationSql(diff, options) {
+    const retiredDrops = options.retiredDrops ?? [];
     const lines = [];
     const seq = options.sequenceNumber.toString().padStart(4, "0");
     lines.push(`-- Migration ${seq}_${options.name}`);
@@ -393,9 +395,18 @@ export function renderMigrationSql(diff, options) {
         }
         lines.push("");
     }
+    if (retiredDrops.length > 0) {
+        lines.push("-- === Retired framework tables ===");
+        for (const retired of retiredDrops) {
+            lines.push(`-- ${retired.tableName}: retired since framework ${retired.sinceVersion} — ${retired.explanation}`);
+            lines.push(`DROP TABLE IF EXISTS ${quoteIdent(retired.tableName)};`);
+        }
+        lines.push("");
+    }
     if (diff.newTables.length === 0 &&
         diff.changedTables.length === 0 &&
-        diff.droppedTables.length === 0) {
+        diff.droppedTables.length === 0 &&
+        retiredDrops.length === 0) {
         lines.push("-- No schema changes detected.");
     }
     return lines.join("\n");
@@ -413,9 +424,11 @@ export function generateMigration(input) {
     assertValidMigrationName(input.name);
     const nextSnapshot = snapshotFromMetas(input.metas);
     const diff = diffSnapshots(input.prevSnapshot, nextSnapshot);
+    const retiredDrops = findRetiredTableDrops(input.priorMigrationsSql ?? [], nextSnapshot);
     const sqlContent = renderMigrationSql(diff, {
         name: input.name,
         sequenceNumber: input.sequenceNumber,
+        retiredDrops,
     });
     const seq = input.sequenceNumber.toString().padStart(4, "0");
     return {
@@ -423,5 +436,6 @@ export function generateMigration(input) {
         sqlContent,
         snapshot: nextSnapshot,
         diff,
+        retiredDrops,
     };
 }

package/dist/db/migrate-runner.d.ts

@@ -14,6 +14,7 @@ export type ApplyResult = {
 };
 export declare function splitSqlStatements(sqlText: string): readonly string[];
 export declare function loadMigrationsFromDir(dir: string, preprocess?: (sql: string) => string): readonly Migration[];
+export declare function readMigrationSqlTexts(dir: string): readonly string[];
 export declare function fetchAppliedMigrations(db: DbConnection): Promise<readonly AppliedMigration[]>;
 export declare class MigrationChecksumMismatchError extends Error {
     readonly migrationId: string;