@cosmicdrift/kumiko-framework 0.387.0 → 0.389.0

package/dist/api/export/export-screen.js

@@ -0,0 +1,47 @@
+import { hasAccess } from "../../engine/access.js";
+import { toKebab } from "../../engine/qualified-name.js";
+import { DEFAULT_EXPORT_MAX_ROWS } from "../../engine/types/screen.js";
+import { AccessDeniedError } from "../../errors/index.js";
+import { resolveExportColumns } from "./export-columns.js";
+import { exportRejection } from "./export-errors.js";
+const SCREEN_QN = /^[A-Za-z0-9_-]+:screen:[A-Za-z0-9_-]+$/;
+function findExportScreen(registry, screenQn) {
+    // The client sends the feature name as authored (camelCase allowed); the registry keys are kebab.
+    const registryQn = toKebab(screenQn);
+    const screen = SCREEN_QN.test(screenQn) ? registry.getScreen(registryQn) : undefined;
+    if (screen === undefined || (screen.type !== "entityList" && screen.type !== "projectionList")) {
+        throw exportRejection("export_unknown_screen", "screen");
+    }
+    return { registryQn, screen };
+}
+export function resolveExportPlan(registry, screenQn, requestedColumns, user) {
+    const { registryQn, screen } = findExportScreen(registry, screenQn);
+    if (screen.table?.export?.xlsx !== true)
+        throw exportRejection("export_not_enabled", "screen");
+    if (screen.access !== undefined && !hasAccess(user, screen.access)) {
+        throw new AccessDeniedError({ details: { screen: screenQn } });
+    }
+    // Label keys use the feature name as authored, query types the kebab form.
+    const featureName = registry.getScreenFeature(registryQn) ?? "";
+    const screenShortId = registryQn.split(":")[2] ?? "";
+    const maxRows = screen.table.export.maxRows ?? DEFAULT_EXPORT_MAX_ROWS;
+    if (screen.type === "projectionList") {
+        return {
+            screenShortId,
+            queryType: screen.query,
+            screenFilter: screen.filter,
+            columns: resolveExportColumns({ featureName, columns: screen.columns, entity: undefined, entityName: undefined, user }, requestedColumns),
+            maxRows,
+        };
+    }
+    const entity = registry.getEntity(screen.entity);
+    if (entity === undefined)
+        throw exportRejection("export_unknown_screen", "screen");
+    return {
+        screenShortId,
+        queryType: `${toKebab(featureName)}:query:${toKebab(screen.entity)}:list`,
+        screenFilter: screen.filter,
+        columns: resolveExportColumns({ featureName, columns: screen.columns, entity, entityName: screen.entity, user }, requestedColumns),
+        maxRows,
+    };
+}

package/dist/api/export/export-xlsx-writer.d.ts

@@ -0,0 +1,4 @@
+import { type Translate } from "./export-cells.ts";
+import type { ExportColumn } from "./export-columns.ts";
+import type { ExportRow } from "./export-rows.ts";
+export declare function writeExportWorkbook(columns: readonly ExportColumn[], rows: readonly ExportRow[], translate: Translate, timeZone: string): Promise<Uint8Array<ArrayBuffer>>;

package/dist/api/export/export-xlsx-writer.js

@@ -0,0 +1,21 @@
+import writeXlsxFile, {} from "write-excel-file/node";
+import { toExportCell } from "./export-cells.js";
+import { guardSheetAgainstCiphertext } from "./export-ciphertext-guard.js";
+function headerLabel(column, translate) {
+    const translated = translate(column.headerKey);
+    return translated === column.headerKey ? column.headerFallback : translated;
+}
+export async function writeExportWorkbook(columns, rows, translate, timeZone) {
+    const header = columns.map((column) => ({
+        value: headerLabel(column, translate),
+        type: String,
+        fontWeight: "bold",
+    }));
+    const body = rows.map((row) => columns.map((column) => toExportCell(column, { row, translate, timeZone })));
+    const sheetData = guardSheetAgainstCiphertext([header, ...body]);
+    const buffer = await writeXlsxFile(sheetData, {}).toBuffer();
+    // Buffer is typed over ArrayBufferLike; a plain copy gives Response a BodyInit-compatible view.
+    const bytes = new Uint8Array(buffer.byteLength);
+    bytes.set(buffer);
+    return bytes;
+}

package/dist/api/extra-route.d.ts

@@ -70,6 +70,10 @@ export type SignatureExtraRouteDeps = {
      *  caller's authenticity (signature, HMAC state, etc.). */
     readonly dispatchSystemWrite: (args: SystemDispatchArgs) => Promise<WriteResult>;
     readonly dispatchSystemQuery: (args: SystemDispatchArgs) => Promise<unknown>;
+    /** Same trust as dispatchSystemWrite, but runs as the tenant's system user
+     *  with the "system" role plus exactly `roles` (no SystemAdmin), so the write
+     *  passes app-role access checks. */
+    readonly dispatchWriteAs: (args: RoleDispatchArgs) => Promise<WriteResult>;
 };
 export type SignatureExtraRoute<TVerified> = {
     readonly method: HttpRouteMethod;

package/dist/api/index.d.ts

@@ -27,7 +27,9 @@ export type { MetricsRouteOptions } from "./route-registrars.ts";
 export { createMetricsApp, DEFAULT_MAX_REQUEST_BYTES, isPrometheusMeter, } from "./route-registrars.ts";
 export { createApiRoutes } from "./routes.ts";
 export type { KumikoServer, ServerOptions } from "./server.ts";
-export { buildServer, makeDispatchSystemQuery, makeDispatchSystemWrite, makeDispatchWriteAs, withFileProviderResolver, } from "./server.ts";
+export { buildServer } from "./server.ts";
+export { makeDispatchSystemQuery, makeDispatchSystemWrite, makeDispatchWriteAs, } from "./server-extra-routes.ts";
+export { withFileProviderResolver } from "./server-wiring.ts";
 export type { ResolvedSessionCookies, SessionCookieBase, SessionCookieNames, } from "./session-cookies.ts";
 export { AUTH_COOKIE_BASE, CSRF_COOKIE_BASE, getSessionCookies, HOST_COOKIE_PREFIX, isHostPrefixedCookieName, resolveSessionCookieNames, resolveSessionCookies, sessionCookieName, sessionCookiesMiddleware, TENANT_COOKIE_BASE, } from "./session-cookies.ts";
 export type { SseBroker, SseClient, SseEvent } from "./sse-broker.ts";

package/dist/api/index.js

@@ -16,7 +16,9 @@ export { readonlyRequestContext as requestContext, } from "./request-context.js"
 export { buildRequestContextDataFromRequest, requestIdMiddleware, } from "./request-id-middleware.js";
 export { createMetricsApp, DEFAULT_MAX_REQUEST_BYTES, isPrometheusMeter, } from "./route-registrars.js";
 export { createApiRoutes } from "./routes.js";
-export { buildServer, makeDispatchSystemQuery, makeDispatchSystemWrite, makeDispatchWriteAs, withFileProviderResolver, } from "./server.js";
+export { buildServer } from "./server.js";
+export { makeDispatchSystemQuery, makeDispatchSystemWrite, makeDispatchWriteAs, } from "./server-extra-routes.js";
+export { withFileProviderResolver } from "./server-wiring.js";
 export { AUTH_COOKIE_BASE, CSRF_COOKIE_BASE, getSessionCookies, HOST_COOKIE_PREFIX, isHostPrefixedCookieName, resolveSessionCookieNames, resolveSessionCookies, sessionCookieName, sessionCookiesMiddleware, TENANT_COOKIE_BASE, } from "./session-cookies.js";
 export { createSseBroker } from "./sse-broker.js";
 export { createSseRoute, SSE_HEARTBEAT_INTERVAL_MS } from "./sse-route.js";

package/dist/api/pii-leak-guard.d.ts

@@ -1,2 +1,5 @@
 import type { MiddlewareHandler } from "hono";
+export declare const CIPHERTEXT_RE: RegExp;
+export declare const CIPHERTEXT_REDACT_RE: RegExp;
+export declare const CIPHERTEXT_REDACTION = "[pii-redacted]";
 export declare function piiCiphertextResponseGuard(): MiddlewareHandler;

package/dist/api/pii-leak-guard.js

@@ -8,8 +8,9 @@ const isProductionEnv = () => process.env["NODE_ENV"] === "production";
 // Bound to the full ciphertext shape (prefix, "<kind>:<id>" subject key, base64
 // blob of at least IV + GCM tag = 28 bytes) so a user-typed "kumiko-pii:v" in a
 // note or name field cannot turn every read of that record into a 500.
-const CIPHERTEXT_RE = /kumiko-pii:v\d+:[^:"\s<>\\]+:[^:"\s<>\\]+:[A-Za-z0-9+/=]{40,}/;
-const CIPHERTEXT_REDACT_RE = new RegExp(CIPHERTEXT_RE.source, "g");
+export const CIPHERTEXT_RE = /kumiko-pii:v\d+:[^:"\s<>\\]+:[^:"\s<>\\]+:[A-Za-z0-9+/=]{40,}/;
+export const CIPHERTEXT_REDACT_RE = new RegExp(CIPHERTEXT_RE.source, "g");
+export const CIPHERTEXT_REDACTION = "[pii-redacted]";
 // A PII subject ciphertext never belongs in an API response — its presence
 // means a raw DB read (fetchOne/selectMany) leaked to the surface. Dev/test
 // fail loud (500) so a forgotten decrypt turns the first integration test

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

@@ -41,6 +41,6 @@ export declare function runWithOrigin<T>(origin: {
         readonly risk: AgentRisk;
     };
 }, fn: () => T): T;
-export declare function runAsDirectCallEntry<T>(fn: () => T): T;
+export declare function runAsAgentToolCallEntry<T>(fn: () => T): T;
 export declare function isAgentToolCallScope(): boolean;
 export declare function runWithWriteOrigin<T>(origin: WriteOrigin, fn: () => T): T;

package/dist/api/request-context.js

@@ -53,7 +53,7 @@ export function runWithOrigin(origin, fn) {
 // surrounding turn/approve handler. Reserved for dispatchToolCall, so it also marks
 // the scope as an agent tool call; it always mints a scope, because an agent loop
 // running outside any request must still carry that marker.
-export function runAsDirectCallEntry(fn) {
+export function runAsAgentToolCallEntry(fn) {
     const current = requestContext.get();
     const requestId = current?.requestId ?? requestContext.generateId();
     const { entryHandler: _entryHandler, ...rest } = current ?? {};

package/dist/api/routes.d.ts

@@ -1,4 +1,5 @@
 import { type Context, Hono } from "hono";
+import { type KumikoError } from "../errors/index.ts";
 import type { Dispatcher } from "../pipeline/dispatcher.ts";
 export declare const StreamFrame: {
     readonly chunk: "chunk";
@@ -18,4 +19,19 @@ export type SseWriter = {
 };
 export declare function pumpStream(stream: SseWriter, generator: AsyncGenerator<unknown>, heartbeatMs: number, firstPull?: Promise<IteratorResult<unknown>>): Promise<void>;
 export declare const MAX_PAYLOAD_DEPTH = 20;
+export declare function assertPayloadDepthAllowed(payload: unknown): void;
+export declare function queryErrorResponse(c: Context, err: KumikoError, type?: unknown): (Response & import("hono").TypedResponse<{
+    readonly error: {
+        readonly code: string;
+        readonly i18nKey: string;
+        readonly i18nParams?: {
+            readonly [x: string]: import("hono/utils/types").JSONValue;
+        } | undefined;
+        readonly message: string;
+        readonly details?: import("hono/utils/types").JSONValue | undefined;
+        readonly docsUrl?: string;
+        readonly requestId?: string;
+        readonly timestamp: string;
+    };
+}, -1 | 100 | 102 | 103 | 200 | 201 | 202 | 203 | 206 | 207 | 208 | 226 | 300 | 301 | 302 | 303 | 305 | 306 | 307 | 308 | 400 | 401 | 402 | 403 | 404 | 405 | 406 | 407 | 408 | 409 | 410 | 411 | 412 | 413 | 414 | 415 | 416 | 417 | 418 | 421 | 422 | 423 | 424 | 425 | 426 | 428 | 429 | 431 | 451 | 500 | 501 | 502 | 503 | 504 | 505 | 506 | 507 | 508 | 510 | 511, "json">) | (Response & import("hono").TypedResponse<null, -1 | 100 | 102 | 103 | 200 | 201 | 202 | 203 | 206 | 207 | 208 | 226 | 300 | 301 | 302 | 303 | 305 | 306 | 307 | 308 | 400 | 401 | 402 | 403 | 404 | 405 | 406 | 407 | 408 | 409 | 410 | 411 | 412 | 413 | 414 | 415 | 416 | 417 | 418 | 421 | 422 | 423 | 424 | 425 | 426 | 428 | 429 | 431 | 451 | 500 | 501 | 502 | 503 | 504 | 505 | 506 | 507 | 508 | 510 | 511, "body">);
 export declare function handleUncaughtRouteError(err: Error, c: Context): Response | Promise<Response>;

package/dist/api/routes.js

@@ -312,7 +312,7 @@ async function readDispatchBody(c) {
 // jsonb serialization of custom-fields payloads) walks the same object
 // graph an attacker controls, so an uncapped depth is a stack-overflow /
 // CPU-DoS vector even under the 1MB body-byte limit.
-function assertPayloadDepthAllowed(payload) {
+export function assertPayloadDepthAllowed(payload) {
     if (payloadDepth(payload, 0) > MAX_PAYLOAD_DEPTH) {
         throw new ValidationError({
             fields: [
@@ -428,7 +428,7 @@ function clientAbortResponse(c, requestId, type) {
 }
 // For /query + /command: no isSuccess on success (just { data } / {ok}), so we
 // keep the same lean shape on failure — only the `error` key.
-function queryErrorResponse(c, err, type) {
+export function queryErrorResponse(c, err, type) {
     const requestId = requestContext.get()?.requestId;
     if (isClientAbort(err))
         return clientAbortResponse(c, requestId, type);

package/dist/api/server-boot-checks.d.ts

@@ -0,0 +1,10 @@
+import { type AppContext, type Registry } from "../engine/types/index.ts";
+import type { createFallbackLogger } from "../logging/index.ts";
+import type { AuthRoutesConfig } from "./auth-routes.ts";
+export type BootLogger = ReturnType<typeof createFallbackLogger>;
+export declare function assertNoPayloadRateLimitsWithoutResolver(registry: Registry): void;
+export declare function assertFileStorageProviderForFileFields(registry: Registry, context: AppContext): void;
+export declare function warnSearchableScreensWithoutSearchAdapter(registry: Registry, context: AppContext, bootLog: BootLogger): void;
+export declare function resolveServerInstanceId(explicitInstanceId: string | undefined, bootLog: BootLogger): string;
+export declare function warnUnlimitedSystemScopeFeatures(registry: Registry, bootLog: BootLogger): void;
+export declare function assertSinglePrincipalStatusProvider(registry: Registry, auth: AuthRoutesConfig): void;

package/dist/api/server-boot-checks.js

@@ -0,0 +1,157 @@
+import { EXT_FILE_PROVIDER, EXT_PRINCIPAL_STATUS } from "../engine/extension-names.js";
+import { isFileField } from "../engine/types/index.js";
+import { SHARED_INSTANCE_SENTINEL } from "../pipeline/event-consumer-state.js";
+import { generateId } from "../utils/index.js";
+// A payload-bucket handler without a resolver would answer every call with a
+// 500 at request time; fail at boot instead.
+export function assertNoPayloadRateLimitsWithoutResolver(registry) {
+    const offenders = [];
+    for (const feature of registry.features.values()) {
+        for (const [name, handler] of Object.entries(feature.writeHandlers)) {
+            if (handler.additionalRateLimits !== undefined) {
+                offenders.push(`${feature.name}:write:${name}`);
+            }
+        }
+    }
+    // skip: every handler's payload buckets are covered by the resolver
+    if (offenders.length === 0)
+        return;
+    throw new Error(`Handlers declare additionalRateLimits but no RateLimitResolver is configured: ${offenders.join(", ")}. ` +
+        "Wire a Redis client on context.redis (or pass context.rateLimit), or drop the payload buckets " +
+        "(for the waitlist: emailRateLimits: []).");
+}
+export function assertFileStorageProviderForFileFields(registry, context) {
+    // File-storage is resolved per-tenant through file-foundation: a mounted
+    // `file-provider-*` plugin (inmemory/s3/s3-env) is the single source for
+    // uploads, ctx.files and the GDPR jobs.
+    const hasFileProvider = registry.getExtensionUsages(EXT_FILE_PROVIDER).length > 0;
+    // A test/advanced caller may inject the resolver directly on the context
+    // (e.g. a static in-memory provider) instead of mounting a provider plugin.
+    const hasInjectedResolver = context._fileProviderResolver !== undefined;
+    // Hard-fail when the registry declares file/image fields but no provider
+    // plugin is mounted — uploads would otherwise fail at the first request
+    // instead of at boot. Proves a plugin is mounted, not that each tenant
+    // selected one; per-tenant misconfig surfaces via createFileProviderForTenant.
+    if (registryDeclaresFileFields(registry) && !hasFileProvider && !hasInjectedResolver) {
+        throw new Error("Features declare file/image fields but no file-storage provider is mounted — " +
+            "mount `file-foundation` + a `file-provider-*` feature (inmemory/s3/s3-env) and " +
+            "select one per tenant via the 'file-foundation:config:provider' config-key.");
+    }
+}
+export function warnSearchableScreensWithoutSearchAdapter(registry, context, bootLog) {
+    // A screen whose search box renders (kumiko-screen.tsx gates it on
+    // `screen.searchable ?? entity-has-searchable-field`, the same condition
+    // as entitiesWithSearchableScreen) sends `payload.search` on every query. Without a
+    // context.searchAdapter that throws UnprocessableError at request time
+    // — surface the misconfig at boot instead of on the first search.
+    // Warn, not throw: unlike missing file-storage (uploads always fail),
+    // list screens still work without search: only the search box is broken.
+    // Several deployed apps (offlot-app, publicstatus, kumiko-studio,
+    // kumiko-enterprise) currently run in exactly this state.
+    if (!context.searchAdapter) {
+        const unwiredEntities = entitiesWithSearchableScreen(registry);
+        if (unwiredEntities.length > 0) {
+            bootLog.warn(`${unwiredEntities.length} entit${unwiredEntities.length === 1 ? "y" : "ies"} ` +
+                `have a searchable list screen but no SearchAdapter is wired on context.searchAdapter: ` +
+                `${unwiredEntities.join(", ")}. Search requests against ${unwiredEntities.length === 1 ? "it" : "them"} will fail with a 422 (search_adapter_not_wired) at runtime. ` +
+                "Wire a SearchAdapter (e.g. createMeilisearchAdapter) on context.searchAdapter, or remove `searchable: true` from the affected fields.");
+        }
+    }
+}
+export function resolveServerInstanceId(explicitInstanceId, bootLog) {
+    // Resolve the per-process instance identifier. Prefer explicit
+    // ServerOptions.instanceId (tests, deliberate wiring), fall back to the
+    // deploy-env variable, finally a boot-time UUID. Validator rejects the
+    // sentinel — a deliberate collision attempt would silently merge this
+    // instance's per-instance cursors with the shared-row cursors and
+    // deliver events twice to one shard while starving the other.
+    const resolvedInstanceId = explicitInstanceId ?? process.env["KUMIKO_INSTANCE_ID"] ?? generateId();
+    if (resolvedInstanceId === SHARED_INSTANCE_SENTINEL) {
+        throw new Error(`ServerOptions.instanceId / KUMIKO_INSTANCE_ID cannot equal the reserved sentinel "${SHARED_INSTANCE_SENTINEL}" — ` +
+            `pick any other stable string.`);
+    }
+    // Warn when we fell back to a random UUID. The built-in SSE consumer is
+    // delivery="shared" (one cursor for all pods), so it no longer
+    // writes a row per instance. The id still labels this process in the
+    // app.started event and in per-instance consumers (opt-in delivery), where a
+    // fresh id per boot leaves an orphaned cursor-row that pins pruneEvents
+    // (retention-guard uses MIN(lastProcessedEventId) across all shards). Silent
+    // when explicitInstanceId or KUMIKO_INSTANCE_ID is explicit — those are
+    // deliberate choices (the test suite sets KUMIKO_INSTANCE_ID="test-instance").
+    const instanceIdWasRandom = explicitInstanceId === undefined && !process.env["KUMIKO_INSTANCE_ID"];
+    if (instanceIdWasRandom) {
+        bootLog.warn(`No ServerOptions.instanceId / KUMIKO_INSTANCE_ID set — generated a random UUID (${resolvedInstanceId}). ` +
+            `SSE no longer needs a per-instance cursor, but the id labels this process in the app.started event and in per-instance consumers; without a stable id each restart leaves an orphaned cursor-row behind for those and pins events-retention on its last cursor. ` +
+            `Set KUMIKO_INSTANCE_ID to the pod name (e.g. from the Kubernetes downward API metadata.name) in production.`);
+    }
+    return resolvedInstanceId;
+}
+export function warnUnlimitedSystemScopeFeatures(registry, bootLog) {
+    // The systemScope default limit only exists once a resolver does, and an app that
+    // declared no explicit rateLimit anywhere never gets one auto-wired (wantsL3 stays
+    // false) — so its cross-tenant handlers are silently unlimited.
+    const unlimitedSystemScopeFeatures = [...registry.features.values()]
+        .filter((feature) => feature.systemScope &&
+        Object.keys(feature.writeHandlers).length + Object.keys(feature.queryHandlers).length > 0)
+        .map((feature) => feature.name);
+    if (unlimitedSystemScopeFeatures.length > 0) {
+        bootLog.warn(`r.systemScope() features have handlers but no RateLimitResolver is configured, ` +
+            `so their default rate limit is not enforced: ${unlimitedSystemScopeFeatures.join(", ")}. ` +
+            "Wire a Redis client on context.redis and declare rateLimit on at least one handler (or pass " +
+            "context.rateLimit) to enable the resolver.");
+    }
+}
+export function assertSinglePrincipalStatusProvider(registry, auth) {
+    // A membershipQuery handler is registered but principalStatus is not provided by exactly
+    // one feature — surface that misconfig at boot instead of an InternalError on first login/switch-tenant.
+    if (registry.getQueryHandler(auth.membershipQuery)) {
+        const principalStatusProviders = registry.getExtensionUsages(EXT_PRINCIPAL_STATUS).length;
+        if (principalStatusProviders === 0) {
+            throw new Error(`[kumiko] auth membershipQuery "${auth.membershipQuery}" is registered but no feature ` +
+                'provides the "principalStatus" contract — mount the user feature (tenant switch and sign-in ' +
+                "need it to reject blocked principals).");
+        }
+        if (principalStatusProviders > 1) {
+            throw new Error(`[kumiko] auth membershipQuery "${auth.membershipQuery}" is registered but ` +
+                `${principalStatusProviders} features provide the "principalStatus" contract — exactly one ` +
+                "is expected (the bundled user feature already provides it).");
+        }
+    }
+}
+// Scans every feature's entities for a file/image/files/images field. Short-
+// circuits on the first hit — no need to build a full inventory, we only want
+// the yes/no answer for the boot check.
+function registryDeclaresFileFields(registry) {
+    for (const feature of registry.features.values()) {
+        for (const entity of Object.values(feature.entities ?? {})) {
+            for (const field of Object.values(entity.fields)) {
+                if (isFileField(field))
+                    return true;
+            }
+        }
+    }
+    return false;
+}
+// Entities whose entityList screen WOULD render a search box based on
+// screen/field config alone: `screen.searchable` wins when set, otherwise
+// the box shows iff the entity has ≥1 searchable field. `screen.searchable
+// === false` is excluded — the boot-validator (entity-list-screens.ts) only
+// allows that on the whitelisted download-attempt-list-style screens, which
+// never render the box. This is the config-only half of the rule; the
+// client additionally gates on FeatureSchema.searchAdapterMissing
+// (set from the same `!options.context.searchAdapter` check in mountSchemaRoute) so the
+// box is actually suppressed once this function finds a hit.
+function entitiesWithSearchableScreen(registry) {
+    const entities = new Set();
+    for (const feature of registry.features.values()) {
+        for (const screen of Object.values(feature.screens)) {
+            if (screen.type !== "entityList")
+                continue;
+            const isSearchable = screen.searchable === true ||
+                (screen.searchable === undefined && registry.getSearchableFields(screen.entity).length > 0);
+            if (isSearchable)
+                entities.add(screen.entity);
+        }
+    }
+    return [...entities];
+}

package/dist/api/server-event-dispatcher.d.ts

@@ -0,0 +1,26 @@
+import type { DbConnection } from "../db/connection.ts";
+import type { AppContext } from "../engine/types/index.ts";
+import type { Lifecycle } from "../lifecycle/index.ts";
+import type { ObservabilityProvider } from "../observability/index.ts";
+import { type EventConsumer, type EventDispatcher } from "../pipeline/event-dispatcher.ts";
+import type { ResolvedCacheSyncBus } from "../redis/cache-sync-bus.ts";
+import type { RedisSseBroker } from "./redis-sse-broker.ts";
+import type { ServerOptions } from "./server.ts";
+import type { SseBroker } from "./sse-broker.ts";
+export declare function createServerEventDispatcher(deps: {
+    readonly options: Pick<ServerOptions, "registry" | "eventDispatcher" | "dispatcherOptions" | "processLane">;
+    readonly context: AppContext;
+    readonly sseBroker: SseBroker;
+    readonly observability: ObservabilityProvider;
+    readonly fileProviderResolver: AppContext["_fileProviderResolver"];
+    readonly instanceId: string;
+}): {
+    readonly baseDb: DbConnection | undefined;
+    readonly consumers: readonly EventConsumer[];
+    readonly eventDispatcher: EventDispatcher | undefined;
+};
+export declare function registerOwnedShutdownHooks(lifecycle: Lifecycle | undefined, owned: {
+    readonly eventDispatcher: EventDispatcher | undefined;
+    readonly ownedRedisSseBroker: RedisSseBroker | undefined;
+    readonly ownedCacheSync: ResolvedCacheSyncBus["owned"];
+}): void;

package/dist/api/server-event-dispatcher.js

@@ -0,0 +1,208 @@
+import { withExecutorManagedWrites } from "../db/tenant-db.js";
+import { createDerivativesContext } from "../derivatives/derivatives-context.js";
+import { runsInLane } from "../engine/run-in.js";
+import { createTenantFileContext } from "../files/file-handle.js";
+import { createEventDispatcher, } from "../pipeline/event-dispatcher.js";
+import { createMultiStreamApplyContext } from "../pipeline/multi-stream-apply-context.js";
+import { createAccessInvalidationEventConsumer, createJobTriggerEventConsumer, createSearchEventConsumer, createSseBroadcastEventConsumer, } from "../pipeline/system-hooks.js";
+import { deriveSearchAdapterConfig } from "../search/derive-search-adapter-config.js";
+export function createServerEventDispatcher(deps) {
+    const { options, context, sseBroker, observability, fileProviderResolver, instanceId } = deps;
+    // Async event-dispatcher — the replacement for the old transactional
+    // outbox. Consumer sources:
+    //   1. System: SSE broadcast (iff sseBroker), Search index (iff
+    //      context.searchAdapter).
+    //   2. Features: every r.multiStreamProjection registered in the registry
+    //      becomes its own consumer row with an independent cursor. The MSP
+    //      apply map is routed by event.type; apply receives the raw DbRunner
+    //      of a TX-scoped, tenant-bound DB handle so per-tenant writes stay
+    //      isolated.
+    //
+    // The dispatcher is built but NOT started here. Production boot code
+    // must call `.start()`; test code typically calls `.runOnce()`.
+    const { baseDb, searchAdapter } = resolveBaseDbAndSearchAdapter(context, options.registry);
+    const systemConsumers = buildSystemEventConsumers(options, sseBroker, searchAdapter);
+    const mspConsumers = buildMultiStreamProjectionConsumers(options, {
+        baseDb,
+        context,
+        fileProviderResolver,
+    });
+    const consumers = [...systemConsumers, ...mspConsumers];
+    const { disabled: dispatcherDisabled, systemConsumers: _systemConsumersOpt, ...dispatcherTunables } = options.eventDispatcher ?? {};
+    let eventDispatcher;
+    if (consumers.length > 0 && baseDb && !dispatcherDisabled) {
+        eventDispatcher = createEventDispatcher({
+            db: baseDb,
+            consumers,
+            context,
+            tracer: observability.tracer,
+            meter: observability.meter,
+            instanceId,
+            ...dispatcherTunables,
+        });
+    }
+    return { baseDb, consumers, eventDispatcher };
+}
+function resolveBaseDbAndSearchAdapter(context, registry) {
+    // @cast-boundary engine-bridge — context.db union narrows to DbConnection here
+    const baseDb = context.db;
+    // @cast-boundary engine-bridge — searchAdapter is an optional context-extension
+    const searchAdapter = context.searchAdapter;
+    // Adapter is built before the registry exists (app boot order) — hand it
+    // the registry-derived default config here so it can lazily configure
+    // each tenant index on first access instead of requiring per-tenant app
+    // wiring.
+    const derivedSearchConfig = searchAdapter ? deriveSearchAdapterConfig(registry) : undefined;
+    if (searchAdapter && derivedSearchConfig) {
+        searchAdapter.setDefaultConfig?.(derivedSearchConfig);
+    }
+    return { baseDb, searchAdapter };
+}
+function buildSystemEventConsumers(options, sseBroker, searchAdapter) {
+    const sseConsumerEnabled = options.eventDispatcher?.systemConsumers?.sse ?? true;
+    const searchConsumerEnabled = options.eventDispatcher?.systemConsumers?.search ?? true;
+    const jobTriggerConsumerEnabled = options.eventDispatcher?.systemConsumers?.jobTrigger ?? true;
+    const jobRunnerForTriggers = options.dispatcherOptions?.jobRunner;
+    const systemConsumers = [];
+    if (sseConsumerEnabled) {
+        systemConsumers.push(createSseBroadcastEventConsumer(sseBroker));
+    }
+    if (searchConsumerEnabled && searchAdapter) {
+        systemConsumers.push(createSearchEventConsumer(searchAdapter, options.registry));
+    }
+    if (jobTriggerConsumerEnabled && jobRunnerForTriggers) {
+        systemConsumers.push(createJobTriggerEventConsumer(jobRunnerForTriggers, options.registry));
+    }
+    // Default ON (global-by-default). Tests that opt out of SSE via
+    // systemConsumers.accessInvalidation=false (test-stack mirrors sse off)
+    // skip the row so retention prune suites are not blocked by a lagging
+    // cursor=0 consumer they never drain.
+    const accessInvalidationEnabled = options.eventDispatcher?.systemConsumers?.accessInvalidation ?? true;
+    if (accessInvalidationEnabled) {
+        systemConsumers.push(createAccessInvalidationEventConsumer(sseBroker));
+    }
+    return systemConsumers;
+}
+function buildMultiStreamProjectionConsumers(options, deps) {
+    const jobRunnerForTriggers = options.dispatcherOptions?.jobRunner;
+    const mspJobs = jobRunnerForTriggers?.dispatch
+        ? {
+            dispatch: async (jobName, payload, dispatchOptions) => {
+                await jobRunnerForTriggers.dispatch?.(jobName, payload, dispatchOptions);
+            },
+        }
+        : undefined;
+    // MultiStreamProjections: one EventConsumer per MSP. Handler routes by
+    // event.type into the MSP's apply map. MSPs aggregate cross-aggregate but
+    // still within one tenant by default — the applier receives the plain
+    // baseDb DbRunner; tenant consistency comes from the triggering event's
+    // own tenantId, not a per-event TenantDb scope.
+    //
+    // Lane-filter: MSPs declare `runIn` to pin them to a
+    // deploy-lane. An MSP with `runIn: "api"` won't be wired into the
+    // worker-process dispatcher (and vice versa). `runIn: "both"` (or the
+    // legacy undefined default of "worker") runs wherever a dispatcher is
+    // started — SKIP LOCKED on the consumer-cursor handles the race between
+    // processes that both want the same event.
+    const processLane = options.processLane ?? "worker";
+    const mspDefs = [...options.registry.getAllMultiStreamProjections().values()].filter((msp) => runsInLane(msp.runIn, processLane));
+    return mspDefs.map((msp) => buildMultiStreamProjectionConsumer(msp, {
+        registry: options.registry,
+        mspJobs,
+        ...deps,
+    }));
+}
+function buildMultiStreamProjectionConsumer(msp, deps) {
+    const { registry, mspJobs, baseDb, context, fileProviderResolver } = deps;
+    return {
+        name: msp.name,
+        // Feature-toggle gating: carry the owning feature so the event-dispatcher
+        // can pause this consumer when the feature is globally disabled. Events
+        // queue up in the store and replay cleanly from the same cursor on resume.
+        ...(registry.getMultiStreamProjectionFeature(msp.name) && {
+            featureName: registry.getMultiStreamProjectionFeature(msp.name), // @cast-boundary engine-bridge
+        }),
+        // Copy the continuous-lifecycle error policy straight onto the consumer.
+        // Rebuild uses its own policy (rebuildProjection reads msp.errorMode.rebuild
+        // directly); steady-state delivery runs through this consumer.
+        ...(msp.errorMode?.continuous && { errorPolicy: msp.errorMode.continuous }),
+        // Carry the MSP's declared delivery semantic through to the consumer.
+        // Default (shared) is applied inside event-dispatcher, so omitting when
+        // the MSP didn't declare one keeps the existing behaviour.
+        ...(msp.delivery && { delivery: msp.delivery }),
+        // Carry the MSP's declared cursor-seed through to the consumer. Default
+        // (beginning) is applied inside insertConsumerIfAbsent.
+        ...(msp.startFrom && { startFrom: msp.startFrom }),
+        handler: async (event, ctx) => {
+            const applyFn = msp.apply[event.type];
+            // skip: this MSP doesn't care about this event type — fast path,
+            // every event type passes through every MSP consumer exactly once.
+            if (!applyFn)
+                return;
+            if (!baseDb) {
+                // skip: no baseDb wired — consumers.length > 0 + baseDb check in
+                // createServerEventDispatcher gates dispatcher creation, so we won't reach here in
+                // production. Defensive return for the type-narrowing path.
+                return;
+            }
+            // Saga/process-manager ctx: apply can call ctx.appendEvent to cascade
+            // a follow-up event onto another aggregate. Uses the triggering event's
+            // tenantId + userId so the causal chain stays tenant-consistent.
+            // MSP qualified names are "<feature>:projection:<short>" — the
+            // prefix before the first ":" owns the MSP. Used to reject
+            // cross-feature ctx.appendEvent calls at emit-site.
+            const mspOwner = msp.name.split(":")[0];
+            const mspFiles = fileProviderResolver
+                ? createTenantFileContext(fileProviderResolver, event.tenantId)
+                : undefined;
+            const mspDb = withExecutorManagedWrites(baseDb);
+            const applyCtx = createMultiStreamApplyContext({
+                registry,
+                db: mspDb,
+                tenantId: event.tenantId,
+                userId: event.metadata.userId,
+                ...(mspOwner && { callerFeature: mspOwner }),
+                ...(mspFiles && { files: mspFiles }),
+                ...(context.secrets && { secrets: context.secrets }),
+                ...(mspJobs && { jobs: mspJobs }),
+                ...(mspFiles && {
+                    derivatives: createDerivativesContext({
+                        files: mspFiles,
+                        registry,
+                        db: baseDb,
+                        tenantId: event.tenantId,
+                    }),
+                }),
+            });
+            await applyFn(event, mspDb, applyCtx);
+            // Keep ctx reachable to satisfy the EventConsumerHandler signature.
+            void ctx;
+        },
+    };
+}
+export function registerOwnedShutdownHooks(lifecycle, owned) {
+    const { eventDispatcher, ownedRedisSseBroker, ownedCacheSync } = owned;
+    // Wire the event-dispatcher shutdown into the lifecycle so the caller
+    // doesn't have to know the dispatcher exists. Hooks drain LIFO, so this
+    // runs before anything registered later by the caller (e.g. DB pool close).
+    if (lifecycle && eventDispatcher) {
+        const dispatcher = eventDispatcher;
+        lifecycle.registerShutdownHook("eventDispatcher", async () => {
+            await dispatcher.stop();
+        });
+    }
+    // Same reasoning, scoped to the broker this function created itself — an
+    // app-injected sseBroker (options.sseBroker) owns its own teardown.
+    if (lifecycle && ownedRedisSseBroker) {
+        const broker = ownedRedisSseBroker;
+        lifecycle.registerShutdownHook("redisSseBroker", async () => {
+            await broker.close();
+        });
+    }
+    if (lifecycle && ownedCacheSync) {
+        const bus = ownedCacheSync;
+        lifecycle.registerShutdownHook("cacheSync", async () => {
+            await bus.close();
+        });
+    }
+}

package/dist/api/server-extra-routes.d.ts

@@ -0,0 +1,11 @@
+import type { Context, Hono } from "hono";
+import type { WriteResult } from "../engine/types/index.ts";
+import type { Dispatcher } from "../pipeline/dispatcher.ts";
+import { type ExtraRouteDefinition, type RoleDispatchArgs, type SystemDispatchArgs } from "./extra-route.ts";
+import type { ServerWiring } from "./server-wiring.ts";
+export type PublicApiRequestMatcher = (c: Context) => boolean;
+export declare function compilePublicApiRequestMatcher(extraRoutes: readonly ExtraRouteDefinition[] | undefined): PublicApiRequestMatcher;
+export declare function mountExtraRoutes(app: Hono, wiring: Pick<ServerWiring, "options" | "dispatcher" | "context" | "clientIpResolver">): void;
+export declare function makeDispatchSystemWrite(dispatcher: Dispatcher): (args: SystemDispatchArgs) => Promise<WriteResult>;
+export declare function makeDispatchWriteAs(dispatcher: Dispatcher): (args: RoleDispatchArgs) => Promise<WriteResult>;
+export declare function makeDispatchSystemQuery(dispatcher: Dispatcher): (args: SystemDispatchArgs) => Promise<unknown>;