@cosmicdrift/kumiko-framework 0.341.0 → 0.343.0

package/dist/errors/docs-url.js

@@ -0,0 +1,36 @@
+import { AgentReasons, FrameworkReasons } from "./reasons.js";
+const DEFAULT_DOCS_BASE_URL = "https://docs.kumiko.rocks";
+const REASON_SLUG_RE = /^[a-z0-9_.-]+$/;
+const frameworkReasons = new Set([
+    ...Object.values(FrameworkReasons),
+    ...Object.values(AgentReasons),
+]);
+function reasonOf(err) {
+    if (!err.details || typeof err.details !== "object")
+        return undefined;
+    // @cast-boundary error-details — per-error typed details; reflection shape only for the reason lookup.
+    const reason = err.details["reason"];
+    return typeof reason === "string" && REASON_SLUG_RE.test(reason) ? reason : undefined;
+}
+function isCoveredByConfig(reason, errorDocs) {
+    if (!errorDocs)
+        return false;
+    return errorDocs.reasons === "all" || (errorDocs.reasons?.includes(reason) ?? false);
+}
+function errorsUrl(baseUrl, slug) {
+    return `${baseUrl}/errors/${encodeURIComponent(slug)}`;
+}
+// A reason the framework documents (or the error code itself) links to the framework docs,
+// overridable via KUMIKO_DOCS_URL. An app's own reason links only where `errorDocs` covers it —
+// otherwise the framework docs would have no page for it.
+export function resolveErrorDocsUrl(err, errorDocs) {
+    const reason = reasonOf(err);
+    if (reason === undefined || reason === err.code || frameworkReasons.has(reason)) {
+        const baseUrl = process.env["KUMIKO_DOCS_URL"] ?? DEFAULT_DOCS_BASE_URL;
+        return errorsUrl(baseUrl, reason ?? err.code);
+    }
+    if (errorDocs && isCoveredByConfig(reason, errorDocs)) {
+        return errorsUrl(errorDocs.baseUrl, reason);
+    }
+    return undefined;
+}

package/dist/errors/index.d.ts

@@ -1,5 +1,7 @@
 export type { FeatureDisabledDetails, FieldIssue, NotFoundDetails, PreconditionFailedDetails, RateLimitDetails, UnconfiguredDetails, UniqueViolationDetails, UnprocessableOpts, ValidationDetails, VersionConflictDetails, } from "./classes.js";
 export { AccessDeniedError, ConflictError, FeatureDisabledError, IdempotentReplayError, InternalError, NotFoundError, PreconditionFailedError, RateLimitError, RateLimitUnavailableError, UnauthenticatedError, UnconfiguredError, UniqueViolationError, UnprocessableError, ValidationError, VersionConflictError, } from "./classes.js";
+export type { ErrorDocsConfig } from "./docs-url.js";
+export { resolveErrorDocsUrl } from "./docs-url.js";
 export type { ErrorCtorInput, ErrorOpts } from "./kumiko-error.js";
 export { isKumikoError, KumikoError } from "./kumiko-error.js";
 export { memberResolutionReadOnlyDenied } from "./member-resolution.js";

package/dist/errors/index.js

@@ -1,4 +1,5 @@
 export { AccessDeniedError, ConflictError, FeatureDisabledError, IdempotentReplayError, InternalError, NotFoundError, PreconditionFailedError, RateLimitError, RateLimitUnavailableError, UnauthenticatedError, UnconfiguredError, UniqueViolationError, UnprocessableError, ValidationError, VersionConflictError, } from "./classes.js";
+export { resolveErrorDocsUrl } from "./docs-url.js";
 export { isKumikoError, KumikoError } from "./kumiko-error.js";
 export { memberResolutionReadOnlyDenied } from "./member-resolution.js";
 export { AgentReasons, FrameworkReasons } from "./reasons.js";

package/dist/errors/kumiko-error.d.ts

@@ -19,7 +19,5 @@ export declare abstract class KumikoError extends Error {
     readonly i18nParams: Readonly<Record<string, unknown>> | undefined;
     readonly details: unknown;
     constructor(input: ErrorCtorInput);
-    get docsUrl(): string;
-    private get reasonSlug();
 }
 export declare function isKumikoError(e: unknown): e is KumikoError;

package/dist/errors/kumiko-error.js

@@ -2,13 +2,6 @@
 // Anything that isn't a KumikoError is treated as an unexpected crash and
 // auto-wrapped into InternalError by the dispatcher — so the HTTP layer never
 // has to guess the status or the client-facing shape.
-// Default docs URL for self-service errors. Override via `KUMIKO_DOCS_URL`
-// (e.g. self-hosted customers pointing at their own docs instance).
-const DEFAULT_DOCS_BASE_URL = "https://docs.kumiko.rocks";
-const REASON_SLUG_RE = /^[a-z0-9_.-]+$/;
-function docsBaseUrl() {
-    return process.env["KUMIKO_DOCS_URL"] ?? DEFAULT_DOCS_BASE_URL;
-}
 export class KumikoError extends Error {
     i18nKey;
     i18nParams;
@@ -20,23 +13,6 @@ export class KumikoError extends Error {
         this.i18nParams = input.i18nParams;
         this.details = input.details;
     }
-    // Docs URL for self-service. Prefer a well-formed `details.reason` slug
-    // (e.g. ConflictError → "stale_state"); otherwise fall back to the error
-    // code. Encode the path segment so spaces/`../` in free-form reasons
-    // cannot break or redirect the link the default renderer shows.
-    get docsUrl() {
-        return `${docsBaseUrl()}/errors/${encodeURIComponent(this.reasonSlug)}`;
-    }
-    get reasonSlug() {
-        if (this.details && typeof this.details === "object") {
-            // @cast-boundary error-details — per-error typed details; reflection
-            // shape only for the reasonSlug lookup.
-            const r = this.details["reason"];
-            if (typeof r === "string" && REASON_SLUG_RE.test(r))
-                return r;
-        }
-        return this.code;
-    }
 }
 export function isKumikoError(e) {
     return e instanceof KumikoError;

package/dist/errors/serialize.d.ts

@@ -1,3 +1,4 @@
+import { type ErrorDocsConfig } from "./docs-url.js";
 import type { KumikoError } from "./kumiko-error.js";
 export type ErrorResponseBody = {
     readonly error: {
@@ -6,12 +7,12 @@ export type ErrorResponseBody = {
         readonly i18nParams?: Readonly<Record<string, unknown>>;
         readonly message: string;
         readonly details?: unknown;
-        readonly docsUrl: string;
+        readonly docsUrl?: string;
         readonly requestId?: string;
         readonly timestamp: string;
     };
 };
-export declare function serializeError(err: KumikoError, requestId?: string): ErrorResponseBody;
+export declare function serializeError(err: KumikoError, requestId?: string, errorDocs?: ErrorDocsConfig): ErrorResponseBody;
 export type ErrorLogEntry = {
     readonly name: string;
     readonly code: string;

package/dist/errors/serialize.js

@@ -1,3 +1,4 @@
+import { resolveErrorDocsUrl } from "./docs-url.js";
 // InternalError deliberately omits `details` from the response in production,
 // because that field often carries the internal cause. The log still has
 // everything (see buildErrorLog).
@@ -19,7 +20,7 @@ function devCauseDetail(cause) {
         ...(cause.stack && { causeStack: cause.stack.split("\n").slice(0, 8).join("\n") }),
     };
 }
-export function serializeError(err, requestId) {
+export function serializeError(err, requestId, errorDocs) {
     const stripped = CODES_WITHOUT_CLIENT_DETAILS.has(err.code) && isProductionEnv();
     const exposeDeclaredDetails = err.details !== undefined && !stripped;
     // For internal_error in dev/test, surface the cause chain so the
@@ -34,6 +35,7 @@ export function serializeError(err, requestId) {
         }
         return undefined;
     })();
+    const docsUrl = resolveErrorDocsUrl(err, errorDocs);
     return {
         error: {
             code: err.code,
@@ -41,7 +43,7 @@ export function serializeError(err, requestId) {
             ...(err.i18nParams && { i18nParams: err.i18nParams }),
             message: err.message,
             ...(detailsForResponse !== undefined && { details: detailsForResponse }),
-            docsUrl: err.docsUrl,
+            ...(docsUrl !== undefined && { docsUrl }),
             ...(requestId && { requestId }),
             timestamp: new Date().toISOString(),
         },

package/dist/jobs/job-runner.js

@@ -11,7 +11,7 @@ import { InternalError } from "../errors/index.js";
 import { isKumikoError } from "../errors/kumiko-error.js";
 import { createFileContext } from "../files/file-handle.js";
 import { createFallbackLogger } from "../logging/index.js";
-import { createEscapeHatchReporter, emitJobLastSuccess, emitJobQueueDepth, getFallbackTracer, registerStandardMetrics, } from "../observability/index.js";
+import { createEscapeHatchProcessDedup, createEscapeHatchReporter, emitJobLastSuccess, emitJobQueueDepth, getFallbackTracer, registerStandardMetrics, } from "../observability/index.js";
 import { createDistributedLock } from "../pipeline/distributed-lock.js";
 import { RedisKeys } from "../pipeline/redis-keys.js";
 import { buildPersonalDataGate, isPersonalDataGated, parseWriteOrigin, } from "../pipeline/write-origin.js";
@@ -159,6 +159,22 @@ function missingDbProxy(jobName) {
         },
     });
 }
+function createCrossTenantReads(systemModeDb, reason, report) {
+    return {
+        selectMany(table, where, options) {
+            report("cross-tenant-read", reason);
+            return systemModeDb.selectMany(table, where, options);
+        },
+        fetchOne(table, where) {
+            report("cross-tenant-read", reason);
+            return systemModeDb.fetchOne(table, where);
+        },
+        count(table, where) {
+            report("cross-tenant-read", reason);
+            return systemModeDb.count(table, where);
+        },
+    };
+}
 function priorAttemptsOf(data) {
     const value = data["_priorAttempts"];
     return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : 0;
@@ -316,6 +332,12 @@ export function createJobRunner(options) {
     // must not depend on buildServer having done it first. Idempotent.
     if (context.meter)
         registerStandardMetrics(context.meter);
+    // Instance-scoped, not module-level: each runner (and each test) audits a system cron's declared hatch once.
+    const systemCronEscapeHatchDedup = createEscapeHatchProcessDedup([
+        "unsafe-raw",
+        "global-write",
+        "cross-tenant-read",
+    ]);
     // Set at the top of stop() — a graceful shutdown closes the redis/BullMQ
     // clients itself, which fires the exact same 'error' listeners below with
     // an expected "Connection is closed." Downgrading to debug once stopping
@@ -688,16 +710,22 @@ export function createJobRunner(options) {
         // unchecked cross-tenant escape hatch for such a job. Gated like jobDb so
         // ctx.systemDb, built from it, is gated too.
         const tenantScopedDb = configDb
-            ? createTenantDb(configDb, tenantId, "system", undefined, undefined, undefined, jobPersonalDataGate ? { personalDataGate: jobPersonalDataGate } : undefined)
+            ? createTenantDb(configDb, tenantId, "system", undefined, undefined, undefined, {
+                projectionRegistry: registry,
+                ...(jobPersonalDataGate && { personalDataGate: jobPersonalDataGate }),
+            })
             : undefined;
         const isSystemJob = registry.isJobSystemScoped(jobName);
         // One reporter for ctx.systemDb and ctx.db.unsafeRaw() so both dedupe in the same window.
+        const isSystemCronRun = triggeredById === null && jobDef.escapeHatch !== undefined && "cron" in jobDef.trigger;
         const reportEscapeHatch = createEscapeHatchReporter({
             handler: jobName,
             tenantId,
             actor: jobSystemUser.id,
             sink: context._escapeHatchAuditSink,
             log: context.log,
+            ...(isSystemCronRun && { processDedup: systemCronEscapeHatchDedup }),
+            ...(context.meter && { meter: context.meter }),
         });
         const systemDb = isSystemJob && tenantScopedDb
             ? createUncheckedSystemDb(tenantScopedDb, undefined, reportEscapeHatch)
@@ -705,10 +733,16 @@ export function createJobRunner(options) {
         const jobDb = configDb
             ? createTenantDb(configDb, tenantId, "tenant", context.tracer, context.meter, undefined, {
                 unsafeRaw: escapeHatchFor(jobDef.escapeHatch, "unsafeRaw"),
+                globalWrites: escapeHatchFor(jobDef.escapeHatch, "globalWrites"),
                 report: reportEscapeHatch,
+                projectionRegistry: registry,
                 ...(jobPersonalDataGate && { personalDataGate: jobPersonalDataGate }),
             })
             : undefined;
+        const crossTenantReadsReason = escapeHatchFor(jobDef.escapeHatch, "unsafeRaw")?.reason;
+        const crossTenantReads = tenantScopedDb && crossTenantReadsReason !== undefined
+            ? createCrossTenantReads(tenantScopedDb, crossTenantReadsReason, reportEscapeHatch)
+            : undefined;
         const config = context._configAccessorFactory && tenantScopedDb
             ? context._configAccessorFactory({
                 user: { id: jobSystemUser.id, tenantId },
@@ -737,6 +771,7 @@ export function createJobRunner(options) {
             ...(notify !== undefined && { notify }),
             ...(config !== undefined && { config }),
             ...(systemDb && { systemDb }),
+            ...(crossTenantReads && { crossTenantReads }),
             // The runner owns the registry it resolved this job from — expose it so
             // workers can reach projections/jobs without the app author duplicating
             // it into `context` (the JobContext contract guarantees `registry`).

package/dist/observability/escape-hatch-report.d.ts

@@ -1,5 +1,6 @@
-import type { EscapeHatchAuditSink, EscapeHatchReporter, EscapeHatchUseEvent, TenantId } from "../engine/types/index.js";
+import type { EscapeHatchAuditSink, EscapeHatchKind, EscapeHatchReporter, EscapeHatchUseEvent, TenantId } from "../engine/types/index.js";
 import type { Logger } from "../logging/types.js";
+import type { Meter } from "./types/index.js";
 export declare const ESCAPE_HATCH_USED_SIGNAL = "security:escape-hatch-used";
 export type EscapeHatchReportWindow = {
     shouldReport(key: string, nowMs: number): boolean;
@@ -8,6 +9,11 @@ export declare function createEscapeHatchReportWindow(opts?: {
     readonly windowMs?: number;
     readonly maxEntries?: number;
 }): EscapeHatchReportWindow;
+export type EscapeHatchProcessDedup = {
+    readonly kinds: ReadonlySet<EscapeHatchKind>;
+    readonly seen: Set<string>;
+};
+export declare function createEscapeHatchProcessDedup(kinds: readonly EscapeHatchKind[]): EscapeHatchProcessDedup;
 export declare function reportEscapeHatchUse(event: EscapeHatchUseEvent, deps: {
     readonly sink?: EscapeHatchAuditSink;
     readonly log?: Logger;
@@ -19,6 +25,9 @@ export declare function createEscapeHatchReporter(opts: {
     readonly sink?: EscapeHatchAuditSink;
     readonly log?: Logger;
     readonly window?: EscapeHatchReportWindow;
+    readonly processDedup?: EscapeHatchProcessDedup;
+    readonly meter?: Meter;
+    readonly now?: () => number;
 }): EscapeHatchReporter;
 export declare const UNATTRIBUTED_ACTOR = "system";
 export declare function fallbackEscapeHatchReporter(tenantId: TenantId): EscapeHatchReporter;

package/dist/observability/escape-hatch-report.js

@@ -1,3 +1,4 @@
+import { emitEscapeHatchUse } from "./standard-metrics.js";
 export const ESCAPE_HATCH_USED_SIGNAL = "security:escape-hatch-used";
 const DEFAULT_WINDOW_MS = 60_000;
 const DEFAULT_MAX_ENTRIES = 1_000;
@@ -24,6 +25,9 @@ export function createEscapeHatchReportWindow(opts) {
         },
     };
 }
+export function createEscapeHatchProcessDedup(kinds) {
+    return { kinds: new Set(kinds), seen: new Set() };
+}
 // Default window for createEscapeHatchReporter callers that don't pass their own.
 const fallbackReportWindow = createEscapeHatchReportWindow();
 const consoleLogger = {
@@ -67,7 +71,21 @@ export function reportEscapeHatchUse(event, deps) {
 }
 export function createEscapeHatchReporter(opts) {
     const window = opts.window ?? fallbackReportWindow;
+    const now = opts.now ?? Date.now;
     return (kind, reason, target) => {
+        if (opts.meter)
+            emitEscapeHatchUse(opts.meter, opts.handler, kind);
+        const { processDedup } = opts;
+        if (processDedup?.kinds.has(kind)) {
+            const processKey = JSON.stringify([opts.handler, kind, opts.tenantId]);
+            // skip: this (handler, kind, tenant) was already audited by this process
+            if (processDedup.seen.has(processKey))
+                return;
+            processDedup.seen.add(processKey);
+            reportEscapeHatchUse({ handler: opts.handler, kind, reason, tenantId: opts.tenantId, actor: opts.actor, target }, { sink: opts.sink, log: opts.log });
+            // skip: audited above, the window dedup below only serves the other kinds
+            return;
+        }
         const key = JSON.stringify([
             opts.handler,
             kind,
@@ -78,7 +96,7 @@ export function createEscapeHatchReporter(opts) {
             target?.tenantId ?? null,
         ]);
         // skip: same (handler, kind, reason, target) already reported within the window — dedup
-        if (!window.shouldReport(key, Date.now()))
+        if (!window.shouldReport(key, now()))
             return;
         reportEscapeHatchUse({ handler: opts.handler, kind, reason, tenantId: opts.tenantId, actor: opts.actor, target }, { sink: opts.sink, log: opts.log });
     };

package/dist/observability/index.d.ts

@@ -1,6 +1,6 @@
 export { type ConsoleProviderOptions, createConsoleProvider } from "./console-provider.js";
 export { observabilityContext } from "./context.js";
-export { createEscapeHatchReporter, createEscapeHatchReportWindow, ESCAPE_HATCH_USED_SIGNAL, type EscapeHatchReportWindow, fallbackEscapeHatchReporter, reportEscapeHatchUse, UNATTRIBUTED_ACTOR, } from "./escape-hatch-report.js";
+export { createEscapeHatchProcessDedup, createEscapeHatchReporter, createEscapeHatchReportWindow, ESCAPE_HATCH_USED_SIGNAL, type EscapeHatchProcessDedup, type EscapeHatchReportWindow, fallbackEscapeHatchReporter, reportEscapeHatchUse, UNATTRIBUTED_ACTOR, } from "./escape-hatch-report.js";
 export { getFallbackMeter, getFallbackProvider, getFallbackTracer } from "./fallback.js";
 export { generateSpanId, generateTraceId } from "./ids.js";
 export { buildMetricName, validateLabelKey, validateMetricName, } from "./metric-validator.js";
@@ -12,5 +12,5 @@ export { type MetricEvent, type MetricEventHandler, RecordingMeter, } from "./re
 export { type RecordedSpan, RecordingTracer, type RecordingTracerOptions, serializeSpanContext, } from "./recording-tracer.js";
 export { wrapRedisClient } from "./redis-wrapper.js";
 export { DEFAULT_SENSITIVE_CONFIG, mergeSensitiveConfig, REDACTED, redactAttributes, redactHeaders, redactQueryString, redactValue, shouldRedactAttribute, } from "./sensitive-filter.js";
-export { emitDbQuery, emitDispatcherError, emitDispatcherHandler, emitEventConsumerLag, emitEventConsumerPassOutcome, emitEventConsumerPassSkipped, emitEventConsumerRearmExhausted, emitEventDispatcherListenConnected, emitHttpRequest, emitJobLastSuccess, emitJobQueueDepth, registerStandardMetrics, STANDARD_METRIC_DEFS, } from "./standard-metrics.js";
+export { emitDbQuery, emitDispatcherError, emitDispatcherHandler, emitEscapeHatchUse, emitEventConsumerLag, emitEventConsumerPassOutcome, emitEventConsumerPassSkipped, emitEventConsumerRearmExhausted, emitEventDispatcherListenConnected, emitHttpRequest, emitJobLastSuccess, emitJobQueueDepth, registerStandardMetrics, STANDARD_METRIC_DEFS, } from "./standard-metrics.js";
 export type { Counter, Gauge, Histogram, Meter, MetricDefinition, MetricLabels, MetricsHandle, MetricType, ObservabilityOptions, ObservabilityProvider, SamplingConfig, SensitiveFilterConfig, SerializedTraceContext, Span, SpanAttributes, SpanAttributeValue, SpanKind, SpanStatus, StartSpanOptions, Tracer, } from "./types/index.js";

package/dist/observability/index.js

@@ -1,7 +1,7 @@
 // Public surface of the observability module.
 export { createConsoleProvider } from "./console-provider.js";
 export { observabilityContext } from "./context.js";
-export { createEscapeHatchReporter, createEscapeHatchReportWindow, ESCAPE_HATCH_USED_SIGNAL, fallbackEscapeHatchReporter, reportEscapeHatchUse, UNATTRIBUTED_ACTOR, } from "./escape-hatch-report.js";
+export { createEscapeHatchProcessDedup, createEscapeHatchReporter, createEscapeHatchReportWindow, ESCAPE_HATCH_USED_SIGNAL, fallbackEscapeHatchReporter, reportEscapeHatchUse, UNATTRIBUTED_ACTOR, } from "./escape-hatch-report.js";
 export { getFallbackMeter, getFallbackProvider, getFallbackTracer } from "./fallback.js";
 export { generateSpanId, generateTraceId } from "./ids.js";
 export { buildMetricName, validateLabelKey, validateMetricName, } from "./metric-validator.js";
@@ -13,4 +13,4 @@ export { RecordingMeter, } from "./recording-meter.js";
 export { RecordingTracer, serializeSpanContext, } from "./recording-tracer.js";
 export { wrapRedisClient } from "./redis-wrapper.js";
 export { DEFAULT_SENSITIVE_CONFIG, mergeSensitiveConfig, REDACTED, redactAttributes, redactHeaders, redactQueryString, redactValue, shouldRedactAttribute, } from "./sensitive-filter.js";
-export { emitDbQuery, emitDispatcherError, emitDispatcherHandler, emitEventConsumerLag, emitEventConsumerPassOutcome, emitEventConsumerPassSkipped, emitEventConsumerRearmExhausted, emitEventDispatcherListenConnected, emitHttpRequest, emitJobLastSuccess, emitJobQueueDepth, registerStandardMetrics, STANDARD_METRIC_DEFS, } from "./standard-metrics.js";
+export { emitDbQuery, emitDispatcherError, emitDispatcherHandler, emitEscapeHatchUse, emitEventConsumerLag, emitEventConsumerPassOutcome, emitEventConsumerPassSkipped, emitEventConsumerRearmExhausted, emitEventDispatcherListenConnected, emitHttpRequest, emitJobLastSuccess, emitJobQueueDepth, registerStandardMetrics, STANDARD_METRIC_DEFS, } from "./standard-metrics.js";

package/dist/observability/standard-metrics.d.ts

@@ -43,3 +43,4 @@ export declare function emitEventConsumerPassOutcome(meter: Meter, labels: {
 }, processed: number, failed: number): void;
 export declare function emitJobQueueDepth(meter: Meter, lane: string, counts: Readonly<Record<string, number>>): void;
 export declare function emitJobLastSuccess(meter: Meter, job: string): void;
+export declare function emitEscapeHatchUse(meter: Meter, handler: string, kind: string): void;

package/dist/observability/standard-metrics.js

@@ -140,6 +140,15 @@ export const STANDARD_METRIC_DEFS = [
         description: "Unix timestamp of the last successful run, per registered job.",
         labels: ["job"],
     },
+    // Every escape-hatch use counts here, including the ones the audit sink
+    // dedups away: a system cron firing every minute writes one audit event per
+    // process, so this counter is the only record of how often it ran.
+    {
+        name: "kumiko_escape_hatch_uses_total",
+        type: "counter",
+        description: "Escape-hatch uses by handler and kind, whether or not an audit event was written.",
+        labels: ["handler", "kind"],
+    },
 ];
 export function registerStandardMetrics(meter) {
     for (const def of STANDARD_METRIC_DEFS) {
@@ -251,3 +260,8 @@ export function emitJobQueueDepth(meter, lane, counts) {
 export function emitJobLastSuccess(meter, job) {
     meter.gauge("kumiko_job_last_success_timestamp_seconds").set(Date.now() / 1000, { job });
 }
+// `handler` is a registry-declared handler/job name, `kind` a closed union —
+// no tenant or user input reaches the label set.
+export function emitEscapeHatchUse(meter, handler, kind) {
+    meter.counter("kumiko_escape_hatch_uses_total").inc(1, { handler, kind });
+}

package/dist/pipeline/dispatch-shared.js

@@ -178,6 +178,7 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
         report: reportEscapeHatch,
         memberReadOnly: isMemberResolutionPrincipal(user),
         personalDataGate: buildPersonalDataGate(registry, origin),
+        projectionRegistry: registry,
     });
     // Propagate the request's AbortSignal so every TenantDb query throws when
     // the client has disconnected — handlers with many sequential queries skip
@@ -244,7 +245,7 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
             const targetSystemUser = createSystemUser(targetTenantId);
             return configFactory({
                 user: { id: targetSystemUser.id, tenantId: targetTenantId },
-                db: createTenantDb(dbSource, targetTenantId, "tenant", context.tracer, context.meter),
+                db: createTenantDb(dbSource, targetTenantId, "tenant", context.tracer, context.meter, undefined, { projectionRegistry: registry }),
                 secrets: context.secrets,
             });
         }
@@ -983,6 +984,7 @@ function buildAuthClaimsContext(ctx, user) {
             log: context.log,
             window: ctx.escapeHatchReportWindow,
         }),
+        projectionRegistry: ctx.registry,
     });
     const configAccessor = context._configAccessorFactory
         ? context._configAccessorFactory({

package/dist/pipeline/event-retention.d.ts

@@ -4,6 +4,7 @@ export type PruneEventsOptions = {
     readonly olderThan?: Temporal.Instant;
     readonly olderThanDays?: number;
     readonly aggregateTypes: readonly string[];
+    readonly aggregateIds?: readonly string[];
     readonly dryRun?: boolean;
 };
 export type PruneEventsResult = {

package/dist/pipeline/event-retention.js

@@ -1,3 +1,4 @@
+/// <reference types="temporal-polyfill/global" preserve="true" />
 import { lockEventConsumersShareMode } from "../db/queries/event-consumer.js";
 import { deleteMany, selectMany, transaction } from "../db/query.js";
 import { eventsTable } from "../event-store/index.js";
@@ -30,7 +31,11 @@ export async function pruneEvents(db, options) {
     if (!options.aggregateTypes || options.aggregateTypes.length === 0) {
         throw new Error("pruneEvents: aggregateTypes is required and must be non-empty. Pruning the event log is destructive — name the aggregate types to delete explicitly.");
     }
+    if (options.aggregateIds !== undefined && options.aggregateIds.length === 0) {
+        throw new Error("pruneEvents: aggregateIds must be non-empty when set.");
+    }
     const aggregateTypes = options.aggregateTypes;
+    const aggregateIds = options.aggregateIds;
     const dryRun = options.dryRun === true;
     return transaction(db, async (tx) => {
         // Serialise against consumer-bootstrap INSERTs. Without this, the race
@@ -49,6 +54,7 @@ export async function pruneEvents(db, options) {
         // Step 1 — collect candidate event ids.
         const candidates = await selectMany(tx, eventsTable, {
             aggregateType: [...aggregateTypes],
+            ...(aggregateIds ? { aggregateId: [...aggregateIds] } : {}),
             createdAt: { lt: cutoff },
         });
         if (candidates.length === 0) {

package/dist/pipeline/index.d.ts

@@ -5,6 +5,8 @@ export { resolveAuthClaims } from "./auth-claims-resolver.js";
 export { createCascadeDeleteHook } from "./cascade-handler.js";
 export type { Dispatcher } from "./dispatcher.js";
 export { createDispatcher, dispatcherToWriteRef } from "./dispatcher.js";
+export type { FailedWriteResult } from "./dispatcher-utils.js";
+export { isFailedWriteResult } from "./dispatcher-utils.js";
 export type { DistributedLock } from "./distributed-lock.js";
 export { createDistributedLock } from "./distributed-lock.js";
 export type { EntityCache, EntityCacheOptions } from "./entity-cache.js";

package/dist/pipeline/index.js

@@ -2,6 +2,7 @@ export { createEscapeHatchReporter, createEscapeHatchReportWindow, ESCAPE_HATCH_
 export { resolveAuthClaims } from "./auth-claims-resolver.js";
 export { createCascadeDeleteHook } from "./cascade-handler.js";
 export { createDispatcher, dispatcherToWriteRef } from "./dispatcher.js";
+export { isFailedWriteResult } from "./dispatcher-utils.js";
 export { createDistributedLock } from "./distributed-lock.js";
 export { createEntityCache } from "./entity-cache.js";
 export { ConsumerStatuses, createEventConsumerStateTable, eventConsumerStateTable, SHARED_INSTANCE_SENTINEL, } from "./event-consumer-state.js";

package/dist/pipeline/projections-runner.d.ts

@@ -2,4 +2,5 @@ import type { DbRunner } from "../db/index.js";
 import type { LifecycleResult, Registry } from "../engine/types/index.js";
 import type { StoredEvent } from "../event-store/index.js";
 export declare function runProjections(result: LifecycleResult, registry: Registry, runner: DbRunner | undefined): Promise<void>;
+export declare function hasLiveProjectionsForEvent(event: StoredEvent, registry: Registry): boolean;
 export declare function runProjectionsForEvent(event: StoredEvent, registry: Registry, tx: DbRunner): Promise<void>;

package/dist/pipeline/projections-runner.js

@@ -36,22 +36,31 @@ export async function runProjections(result, registry, runner) {
 // CRUD path (via runProjections) and the ctx.appendEvent path (domain events
 // emitted inside a write handler). Keeping one function means an auto-event
 // and a r.defineEvent-event land in the same inline-projection pipeline.
+// Events whose projections already ran. The EventStoreExecutor projects right
+// after its write and hands the same object back on the LifecycleResult, so the
+// dispatcher's later runProjections() and manual calls become no-ops instead of
+// double-applying. Marked only after a successful run: a rolled-back write is
+// retried with a fresh event object, so a thrown projection never blocks a retry.
+const projectedEvents = new WeakSet();
+// Implicit projections exist only for rebuildProjection: the EventStoreExecutor
+// already writes their table on the live path, so applying them live would write
+// twice and hit a unique key violation.
+function liveProjectionsForEvent(event, registry) {
+    return registry
+        .getProjectionsForSource(event.aggregateType)
+        .filter((proj) => !proj.isImplicit && proj.apply[event.type] !== undefined);
+}
+export function hasLiveProjectionsForEvent(event, registry) {
+    return liveProjectionsForEvent(event, registry).length > 0;
+}
 export async function runProjectionsForEvent(event, registry, tx) {
-    const projections = registry.getProjectionsForSource(event.aggregateType);
-    // skip: no projection feeds off this entity — fast path for the common case
-    if (projections.length === 0)
+    // skip: this event object was already projected in this write
+    if (projectedEvents.has(event))
         return;
-    for (const proj of projections) {
-        // ImplicitProjections existieren nur für rebuildProjection — der
-        // EventStoreExecutor schreibt im Live-Pfad bereits direkt in die
-        // Tabelle. Live-Apply der Implicit würde doppelt schreiben → unique
-        // key violation. Filter ist Pflicht.
-        if (proj.isImplicit)
-            continue;
+    for (const proj of liveProjectionsForEvent(event, registry)) {
         const applyFn = proj.apply[event.type];
-        // skip: this projection doesn't care about this event type
-        if (!applyFn)
-            continue;
-        await applyFn(event, tx, proj.table);
+        if (applyFn)
+            await applyFn(event, tx, proj.table);
     }
+    projectedEvents.add(event);
 }

package/dist/rate-limit/middleware.js

@@ -128,5 +128,5 @@ function respondRateLimited(c, decision, bucket) {
     c.header("Retry-After", String(Math.max(1, decision.retryAfterSeconds)));
     setRateLimitHeaders(c, decision);
     const reqId = requestContext.get()?.requestId;
-    return c.json(serializeError(err, reqId), 429);
+    return c.json(serializeError(err, reqId, requestContext.get()?.errorDocs), 429);
 }

package/dist/schema-cli.d.ts

@@ -4,15 +4,17 @@ export type SchemaCliOut = {
     readonly err: (line: string) => void;
 };
 export type RunSchemaCliOptions = {
+    readonly features?: undefined;
+    readonly kmsSlots?: undefined;
+} | {
     /** Composed app features. When given, `apply` rebuilds the projections whose
      *  tables a freshly applied migration changed (via its `.rebuild.json`
      *  marker). Omitted (dev `kumiko schema`) → no rebuild, migrations only. */
-    readonly features?: readonly FeatureDefinition[];
-    /** Schema-declared Key Manager slots, typically `kmsSlotsOf(composedEnv.schema)`.
-     *  This CLI parses no env schema, so `apply`'s KMS wiring cannot derive them
-     *  itself; omitted, `resolvePlatformKeks` (inside `resolveKmsWiringAsync`)
-     *  falls back to its own default. */
-    readonly kmsSlots?: readonly string[];
+    readonly features: readonly FeatureDefinition[];
+    /** Schema-declared Key Manager slots, `kmsSlotsOf(composedEnv.schema)`, or
+     *  `[]` when the app wires none. This CLI parses no env schema, so the
+     *  rebuild's KMS wiring cannot derive them itself. */
+    readonly kmsSlots: readonly string[];
 };
 /**
  * Runs a schema-CLI subcommand. `appCwd` is the app workspace root (where