@cosmicdrift/kumiko-framework 0.339.0 → 0.341.0

package/dist/api/index.d.ts

@@ -21,7 +21,8 @@ export type { RedisSseBroker, RedisSseBrokerOptions } from "./redis-sse-broker.j
 export { createDefaultSseBroker, createRedisSseBroker, isRedisSseBroker, } from "./redis-sse-broker.js";
 export { type RequestContextData, requestContext, runAsDirectCallEntry, } from "./request-context.js";
 export { buildRequestContextDataFromRequest, requestIdMiddleware, } from "./request-id-middleware.js";
-export { DEFAULT_MAX_REQUEST_BYTES } from "./route-registrars.js";
+export type { MetricsRouteOptions } from "./route-registrars.js";
+export { createMetricsApp, DEFAULT_MAX_REQUEST_BYTES, isPrometheusMeter, } from "./route-registrars.js";
 export { createApiRoutes } from "./routes.js";
 export type { KumikoServer, ServerOptions } from "./server.js";
 export { buildServer, makeDispatchSystemQuery, makeDispatchSystemWrite } from "./server.js";

package/dist/api/index.js

@@ -12,7 +12,7 @@ export { isSafeLandingPath } from "./post-auth-landing.js";
 export { createDefaultSseBroker, createRedisSseBroker, isRedisSseBroker, } from "./redis-sse-broker.js";
 export { requestContext, runAsDirectCallEntry, } from "./request-context.js";
 export { buildRequestContextDataFromRequest, requestIdMiddleware, } from "./request-id-middleware.js";
-export { DEFAULT_MAX_REQUEST_BYTES } from "./route-registrars.js";
+export { createMetricsApp, DEFAULT_MAX_REQUEST_BYTES, isPrometheusMeter, } from "./route-registrars.js";
 export { createApiRoutes } from "./routes.js";
 export { buildServer, makeDispatchSystemQuery, makeDispatchSystemWrite } from "./server.js";
 export { createSseBroker } from "./sse-broker.js";

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

@@ -1,7 +1,7 @@
-import type { Hono } from "hono";
+import { Hono } from "hono";
 import type { DbConnection } from "../db/connection.js";
 import type { Lifecycle } from "../lifecycle/index.js";
-import type { Meter } from "../observability/index.js";
+import type { Meter, PrometheusMeter } from "../observability/index.js";
 import type { EventConsumer } from "../pipeline/event-dispatcher.js";
 export declare const DEFAULT_MAX_REQUEST_BYTES = 1048576;
 export declare function registerBodyLimit(app: Hono, maxBytes: number): void;
@@ -9,7 +9,9 @@ export type MetricsRouteOptions = {
     readonly token?: string;
     readonly path?: string;
 };
+export declare function isPrometheusMeter(m: Meter): m is PrometheusMeter;
 export declare function registerMetricsRoute(app: Hono, meter: Meter, options: MetricsRouteOptions): void;
+export declare function createMetricsApp(meter: Meter, options: MetricsRouteOptions): Hono;
 export declare function registerVersionRoute(app: Hono): void;
 export type HealthRoutesOptions = {
     readonly lifecycle?: Lifecycle;

package/dist/api/route-registrars.js

@@ -3,6 +3,7 @@
 // branches. Every registrar takes the Hono app + whatever state it
 // actually reads — no monolithic `options` parameter, because these
 // helpers exist to make each step's dependencies visible at the call-site.
+import { Hono } from "hono";
 import { bodyLimit } from "hono/body-limit";
 import { serializeOpenMetrics } from "../observability/index.js";
 import { BODY_LIMIT_OPT_OUT_PATHS, Routes } from "./api-constants.js";
@@ -45,7 +46,7 @@ function constantTimeEqual(a, b) {
 // Type-guard: duck-types the meter on `snapshot()`. An alternative
 // Prometheus-compatible meter (future OTLP bridge) works without an
 // explicit union — if it exposes `snapshot()` it's serialisable.
-function isPrometheusMeter(m) {
+export function isPrometheusMeter(m) {
     return typeof m.snapshot === "function"; // @cast-boundary schema-walk
 }
 // Mount `/metrics` (or the caller-supplied path). Takes just the Meter —
@@ -73,6 +74,13 @@ export function registerMetricsRoute(app, meter, options) {
         return c.body(body);
     });
 }
+// Standalone fetch-handler serving only the scrape route — for HTTP-less
+// processes (worker pods) that expose /metrics on their own port.
+export function createMetricsApp(meter, options) {
+    const app = new Hono();
+    registerMetricsRoute(app, meter, options);
+    return app;
+}
 // --- /version ---------------------------------------------------------------
 // Anonymous endpoint that returns build-identity. Used by ops tooling
 // (prod-version.sh) and the Telegram deploy notification so nobody needs

package/dist/api/server.d.ts

@@ -1,3 +1,4 @@
+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";
@@ -75,7 +76,7 @@ export type KumikoServer = {
     lifecycle?: Lifecycle;
     context: AppContext;
 };
-export declare function withFileProviderResolver(registry: Registry, context: AppContext): AppContext;
+export declare function withFileProviderResolver(registry: Registry, context: AppContext, cacheSync?: CacheSyncBus): AppContext;
 export declare function buildServer(options: ServerOptions): KumikoServer;
 export declare function makeDispatchSystemWrite(dispatcher: Dispatcher): (args: SystemDispatchArgs) => Promise<WriteResult>;
 export declare function makeDispatchSystemQuery(dispatcher: Dispatcher): (args: SystemDispatchArgs) => Promise<unknown>;

package/dist/api/server.js

@@ -19,7 +19,8 @@ import { createEventDispatcher } from "../pipeline/event-dispatcher.js";
 import { createLifecycleHooks } from "../pipeline/lifecycle-pipeline.js";
 import { createMultiStreamApplyContext } from "../pipeline/multi-stream-apply-context.js";
 import { createAccessInvalidationEventConsumer, createJobTriggerEventConsumer, createSearchEventConsumer, createSseBroadcastEventConsumer, } from "../pipeline/system-hooks.js";
-import { authEndpointRateLimit, createRateLimitResolver, globalIpRateLimit, } from "../rate-limit/index.js";
+import { authEndpointRateLimit, createPayloadDigest, createRateLimitResolver, globalIpRateLimit, httpRouteRateLimit, } from "../rate-limit/index.js";
+import { resolveCacheSyncBus } from "../redis/cache-sync-bus.js";
 import { deriveSearchAdapterConfig } from "../search/derive-search-adapter-config.js";
 import { assertUnreachable, generateId } from "../utils/index.js";
 import { collectAnonymousLiveEntities } from "./anonymous-live-entities.js";
@@ -47,7 +48,7 @@ import { buildWebSocketSessionRevalidator, createWebSocketConnectionLimiter, has
 // per-tenant provider cache). Mirrors buildServer's own resolution exactly —
 // including NOT inventing a resolver when no `file-provider-*` plugin is
 // mounted, which is what keeps buildServer's boot-guard below able to fire.
-export function withFileProviderResolver(registry, context) {
+export function withFileProviderResolver(registry, context, cacheSync) {
     if (context._fileProviderResolver !== undefined)
         return context;
     if (registry.getExtensionUsages(EXT_FILE_PROVIDER).length === 0)
@@ -59,6 +60,7 @@ export function withFileProviderResolver(registry, context) {
             _configAccessorFactory: context._configAccessorFactory,
             secrets: context.secrets,
             db: context.db,
+            ...(cacheSync ? { cacheSync } : {}),
         }),
     };
 }
@@ -127,6 +129,10 @@ export function buildServer(options) {
         sseBroker = defaults.sseBroker;
         ownedRedisSseBroker = defaults.ownedRedisSseBroker;
     }
+    // Same decision as the SSE broker: an explicit dispatcherOptions value
+    // (incl. null = opt out) wins, otherwise REDIS_URL turns on cross-replica
+    // cache invalidation (no REDIS_URL = process-local bus).
+    const { bus: cacheSync, owned: ownedCacheSync } = resolveCacheSyncBus(options.dispatcherOptions?.cacheSync);
     // 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
@@ -184,7 +190,7 @@ export function buildServer(options) {
     // resolver once (when a provider plugin is mounted) — the dispatcher uses it
     // to materialise `ctx.files`, the upload routes + MSP-applies share it. The
     // resolver reads config + the s3.secretAccessKey secret under SYSTEM identity.
-    const contextWithFiles = withFileProviderResolver(options.registry, options.context);
+    const contextWithFiles = withFileProviderResolver(options.registry, options.context, cacheSync);
     const fileProviderResolver = contextWithFiles._fileProviderResolver;
     // Auto-wire the rate-limit resolver, but ONLY when at least one
     // handler actually declared a rateLimit option. Apps that don't use
@@ -197,13 +203,22 @@ export function buildServer(options) {
     // both share the same instance to avoid duplicate Lua-script registration.
     const wantsL3 = options.registry.hasRateLimitedHandler();
     const wantsL1L2 = options.rateLimit?.global !== undefined || options.rateLimit?.auth !== undefined;
-    const wantsResolver = wantsL3 || wantsL1L2;
+    const wantsHttpRouteLimit = [...options.registry.features.values()].some((feature) => Object.values(feature.httpRoutes).some((route) => route.rateLimit !== undefined));
+    const wantsResolver = wantsL3 || wantsL1L2 || wantsHttpRouteLimit;
+    // Master for the payload-bucket HMAC: the current signing secret (the
+    // keyring's signKid for rotation setups). buildServer always has one, so
+    // the digest is available whenever a handler declares additionalRateLimits.
+    const payloadDigest = createPayloadDigest(typeof options.jwtSecret === "string"
+        ? options.jwtSecret
+        : (options.jwtSecret.keys[options.jwtSecret.signKid] ?? ""));
     const rateLimitResolver = options.context.rateLimit ??
         (wrappedRedis && wantsResolver ? createRateLimitResolver({ redis: wrappedRedis }) : undefined);
     const contextWithObservability = {
         ...contextWithFiles,
         ...(wrappedRedis ? { redis: wrappedRedis } : {}),
         ...(rateLimitResolver ? { rateLimit: rateLimitResolver } : {}),
+        _rateLimitPayloadDigest: payloadDigest,
+        ...(cacheSync ? { cacheSync } : {}),
         // Propagate the feature-toggle resolver to the context so the event-
         // dispatcher (and any future context-reading consumer) sees the same
         // source as the command dispatcher's handler-gate. Options take
@@ -220,6 +235,7 @@ export function buildServer(options) {
         ...options.dispatcherOptions,
         lifecycle,
         sseBroker,
+        cacheSync: cacheSync ?? null,
         ...(options.auth ? { membershipQuery: options.auth.membershipQuery } : {}),
     });
     // Async event-dispatcher — the replacement for the old transactional
@@ -379,6 +395,12 @@ export function buildServer(options) {
             await broker.close();
         });
     }
+    if (options.lifecycle && ownedCacheSync) {
+        const bus = ownedCacheSync;
+        options.lifecycle.registerShutdownHook("cacheSync", async () => {
+            await bus.close();
+        });
+    }
     const app = new Hono();
     // Sub-apps mounted via app.route() without their own handler inherit this one.
     app.onError(handleUncaughtRouteError);
@@ -657,7 +679,23 @@ export function buildServer(options) {
                 systemQuery: makeSystemQuery(c, dispatcher, clientIpResolver),
                 clientIp: clientIpResolver.resolve(clientIpSourceFromHonoContext(c)),
             });
-            mountHonoRoute(app, route.method, route.path, honoHandler, route.anonymous ? [] : sessionOnlyHttpRouteGuards);
+            // Without a resolver (no Redis in the context — dev/test stacks) the
+            // declared limit is skipped rather than failing the boot of every app
+            // that mounts a bundled feature whose routes carry a default limit.
+            const routeLimit = route.rateLimit && rateLimitResolver
+                ? [
+                    httpRouteRateLimit({
+                        resolver: rateLimitResolver,
+                        rateLimit: route.rateLimit,
+                        routeKey: `${route.method} ${route.path}`,
+                        clientIpResolver,
+                    }),
+                ]
+                : [];
+            mountHonoRoute(app, route.method, route.path, honoHandler, [
+                ...routeLimit,
+                ...(route.anonymous ? [] : sessionOnlyHttpRouteGuards),
+            ]);
         }
     }
     // r.webSocketRoute — GET routes under /api/ws/*, so the jwt/pat/rate-limit

package/dist/bun-db/index.d.ts

@@ -1,4 +1,4 @@
 export type { BunDbConnection, BunDbConnectionOptions, BunDbRunner, BunDbTx, PgListenClient, } from "./connection.js";
 export { bunDbConnectionOptionsFromEnv, createBunDbConnection } from "./connection.js";
-export type { SelectOptions, TableInfo, WhereObject, WhereOperator, WhereValue } from "./query.js";
-export { aggregateWhere, asEntityTableMeta, asRawClient, countWhere, type DeleteManyBatchedOptions, type DeleteManyBatchedResult, deleteMany, deleteManyBatched, extractTableInfo, fetchOne, type IncrementCounterOptions, incrementCounter, insertMany, insertOne, isTimestamptzType, requireEntityTableMeta, runInSavepoint, runInSavepointIfSupported, selectMany, transaction, type UpsertOnConflictOptions, unsafeReadRetrying, updateMany, upsertByPk, upsertOnConflict, } from "./query.js";
+export type { InnerJoinRow, InnerJoinSpec, InsertOnConflictDoNothingOptions, JoinColumnPair, JsonTextMatch, SelectOptions, TableInfo, WhereObject, WhereOperator, WhereValue, } from "./query.js";
+export { aggregateWhere, asEntityTableMeta, asRawClient, countWhere, type DeleteManyBatchedOptions, type DeleteManyBatchedResult, deleteMany, deleteManyBatched, extractTableInfo, fetchOne, type IncrementCounterOptions, incrementCounter, insertMany, insertOnConflictDoNothing, insertOne, isTimestamptzType, requireEntityTableMeta, runInSavepoint, runInSavepointIfSupported, selectInnerJoin, selectMany, transaction, type UpsertOnConflictOptions, unsafeReadRetrying, updateMany, upsertByPk, upsertOnConflict, } from "./query.js";

package/dist/bun-db/index.js

@@ -1,4 +1,4 @@
 // bun-db: Bun.sql-basierte DB-API ohne drizzle.
 // Production-Pfad nach drizzle-removal.
 export { bunDbConnectionOptionsFromEnv, createBunDbConnection } from "./connection.js";
-export { aggregateWhere, asEntityTableMeta, asRawClient, countWhere, deleteMany, deleteManyBatched, extractTableInfo, fetchOne, incrementCounter, insertMany, insertOne, isTimestamptzType, requireEntityTableMeta, runInSavepoint, runInSavepointIfSupported, selectMany, transaction, unsafeReadRetrying, updateMany, upsertByPk, upsertOnConflict, } from "./query.js";
+export { aggregateWhere, asEntityTableMeta, asRawClient, countWhere, deleteMany, deleteManyBatched, extractTableInfo, fetchOne, incrementCounter, insertMany, insertOnConflictDoNothing, insertOne, isTimestamptzType, requireEntityTableMeta, runInSavepoint, runInSavepointIfSupported, selectInnerJoin, selectMany, transaction, unsafeReadRetrying, updateMany, upsertByPk, upsertOnConflict, } from "./query.js";

package/dist/bun-db/query.d.ts

@@ -14,7 +14,7 @@ export declare function asRawClient(db: unknown): RawClient;
 export declare function runInSavepoint<T>(tx: unknown, fn: (sp: unknown) => Promise<T>): Promise<T>;
 export declare function runInSavepointIfSupported<T>(db: unknown, fn: (sp: DbRunner) => Promise<T>): Promise<T>;
 export type AnyDb = BunDbRunner | unknown;
-export type { OrderByClause, SelectOptions, WhereObject, WhereOperator, WhereValue, } from "@cosmicdrift/kumiko-types/where-clause-types";
+export type { JsonTextMatch, OrderByClause, SelectOptions, WhereObject, WhereOperator, WhereValue, } from "@cosmicdrift/kumiko-types/where-clause-types";
 type TableLike = EntityTableMeta | any;
 type WritableTable = EntityTableMeta & NotExecutorOnly;
 export type TableInfo = {
@@ -32,6 +32,26 @@ export declare function describeClosedConnectionFailure(raw: unknown, err: unkno
 export declare function unsafeReadRetrying<TRow>(db: AnyDb, sqlText: string, params: readonly unknown[]): Promise<readonly TRow[]>;
 export declare function selectMany<TRow = any>(db: AnyDb, table: TableLike, where?: WhereObject, options?: SelectOptions): Promise<readonly TRow[]>;
 export declare function fetchOne<TRow = any>(db: AnyDb, table: TableLike, where: WhereObject): Promise<TRow | undefined>;
+export type JoinColumnPair = {
+    readonly left: string;
+    readonly right: string;
+};
+export type InnerJoinSpec = {
+    readonly left: TableLike;
+    readonly right: TableLike;
+    readonly on: readonly [JoinColumnPair, ...JoinColumnPair[]];
+    readonly leftWhere?: WhereObject;
+    readonly rightWhere?: WhereObject;
+    /** Fields to return per side; default: all columns of `left`, none of `right`. */
+    readonly leftFields?: readonly string[];
+    readonly rightFields?: readonly string[];
+    readonly limit?: number;
+};
+export type InnerJoinRow<TLeft, TRight> = {
+    readonly left: TLeft;
+    readonly right: TRight;
+};
+export declare function selectInnerJoin<TLeft = Record<string, unknown>, TRight = Record<string, unknown>>(db: AnyDb, spec: InnerJoinSpec): Promise<readonly InnerJoinRow<TLeft, TRight>[]>;
 export declare function insertMany<TRow = any>(db: AnyDb, table: WritableTable, rows: ReadonlyArray<Record<string, unknown>>): Promise<readonly TRow[]>;
 export declare function insertOne<TRow = any>(db: AnyDb, table: WritableTable, values: Record<string, unknown>): Promise<TRow | undefined>;
 export declare function updateMany<TRow = any>(db: AnyDb, table: WritableTable, set: Record<string, unknown>, where: WhereObject): Promise<readonly TRow[]>;
@@ -57,6 +77,10 @@ export declare function isTimestamptzType(pgType: string | undefined): boolean;
 export declare function aggregateWhere(db: AnyDb, table: TableLike, spec: AggregateSpec, where?: WhereObject): Promise<readonly AggregateRow[]>;
 export declare function upsertOnConflict<TRow = any>(db: AnyDb, table: WritableTable, values: Record<string, unknown>, options: UpsertOnConflictOptions): Promise<TRow | undefined>;
 export declare function upsertByPk<TRow = any>(db: AnyDb, table: WritableTable, values: Record<string, unknown>, updateOnConflict?: Record<string, unknown>): Promise<TRow | undefined>;
+export type InsertOnConflictDoNothingOptions = {
+    readonly conflictKeys?: readonly string[];
+};
+export declare function insertOnConflictDoNothing<TRow = any>(db: AnyDb, table: WritableTable, values: Record<string, unknown>, options?: InsertOnConflictDoNothingOptions): Promise<TRow | undefined>;
 export type IncrementCounterOptions = {
     readonly conflictKeys?: readonly string[];
     /** Extra SET clauses on conflict (e.g. lastUpdatedAt: sql\`NOW()\`). */

package/dist/bun-db/query.js

@@ -179,7 +179,7 @@ function assertNotTenantScoped(db, fnName) {
             "explicit cross-tenant op, or use a scoped TenantDb method.");
     }
 }
-const WHERE_OPERATOR_KEYS = ["gt", "gte", "lt", "lte", "ne", "in", "like"];
+const WHERE_OPERATOR_KEYS = ["gt", "gte", "lt", "lte", "ne", "in", "like", "jsonText"];
 const _whereOperatorKeysExhaustive = true;
 void _whereOperatorKeysExhaustive;
 function isWhereOperator(v) {
@@ -483,10 +483,13 @@ function prepareValue(value, pgType) {
     }
     return { kind: "param", sql: "", bound: value };
 }
-function buildWhereClause(info, where, startIndex) {
+function buildWhereClause(info, where, startIndex, qualifier) {
     const conditions = [];
     const values = [];
     let idx = startIndex;
+    // Single place that renders a column reference, so a join qualifier reaches
+    // every arm (blind index, jsonb containment, IS NULL, jsonText) alike.
+    const ref = (column) => qualifier === undefined ? quoteIdent(column) : `${quoteIdent(qualifier)}.${quoteIdent(column)}`;
     // multiSelect (and any other jsonb-array-of-scalars column) stores an
     // array — a filter value is one option, not the whole array, so eq/ne/in
     // must check array containment (`@>`) instead of scalar `=`/`<>`/`IN`
@@ -501,7 +504,7 @@ function buildWhereClause(info, where, startIndex) {
             // prepareJsonbValue never returns kind:"literal" (only prepareValue's
             // isSqlExpression branch does) — narrow anyway, PreparedValue is a union.
             if (p && p.kind === "param") {
-                parts.push(`${quoteIdent(col)} @> $${idx++}${p.sql}`);
+                parts.push(`${ref(col)} @> $${idx++}${p.sql}`);
                 values.push(p.bound);
             }
         }
@@ -514,7 +517,7 @@ function buildWhereClause(info, where, startIndex) {
         const col = info.columnOf(field);
         const pgType = info.pgTypeOf(col);
         if (value === null) {
-            conditions.push(`${quoteIdent(col)} IS NULL`);
+            conditions.push(`${ref(col)} IS NULL`);
         }
         else if (Array.isArray(value)) {
             if (value.length === 0) {
@@ -535,12 +538,37 @@ function buildWhereClause(info, where, startIndex) {
                         values.push(p.bound);
                     }
                 }
-                conditions.push(`${quoteIdent(col)} IN (${parts.join(", ")})`);
+                conditions.push(`${ref(col)} IN (${parts.join(", ")})`);
             }
         }
         else if (isWhereOperator(value)) {
+            if (value.jsonText !== undefined) {
+                if (Object.keys(value).length > 1) {
+                    throw new Error(`where: jsonText on column "${col}" cannot be combined with other operators`);
+                }
+                if (pgType !== "jsonb") {
+                    throw new Error(`where: jsonText requires a jsonb column, "${col}" is ${pgType}`);
+                }
+                const matches = Array.isArray(value.jsonText) ? value.jsonText : [value.jsonText];
+                for (const match of matches) {
+                    if (!Array.isArray(match.keys) ||
+                        match.keys.length === 0 ||
+                        !match.keys.every((k) => typeof k === "string") ||
+                        typeof match.eq !== "string") {
+                        throw new Error(`where: jsonText on column "${col}" needs non-empty string keys and a string eq`);
+                    }
+                    const lookups = match.keys.map((key) => {
+                        values.push(key);
+                        return `${ref(col)}->>$${idx++}::text`;
+                    });
+                    const lhs = lookups.length === 1 ? lookups[0] : `COALESCE(${lookups.join(", ")})`;
+                    values.push(match.eq);
+                    conditions.push(`(${lhs} = $${idx++})`);
+                }
+                continue;
+            }
             if (value.ne === null && Object.keys(value).length === 1) {
-                conditions.push(`${quoteIdent(col)} IS NOT NULL`);
+                conditions.push(`${ref(col)} IS NOT NULL`);
                 continue;
             }
             const opMap = {
@@ -564,17 +592,17 @@ function buildWhereClause(info, where, startIndex) {
                 if (opKey === "ne" && pgType === "jsonb" && isJsonbScalar(opVal)) {
                     const p = prepareJsonbValue([opVal]);
                     if (p && p.kind === "param") {
-                        conditions.push(`(${quoteIdent(col)} IS NULL OR NOT (${quoteIdent(col)} @> $${idx++}${p.sql}))`);
+                        conditions.push(`(${ref(col)} IS NULL OR NOT (${ref(col)} @> $${idx++}${p.sql}))`);
                         values.push(p.bound);
                         continue;
                     }
                 }
                 const p = prepareValue(opVal, pgType);
                 if (p.kind === "literal") {
-                    conditions.push(`${quoteIdent(col)} ${opSym} ${p.literal}`);
+                    conditions.push(`${ref(col)} ${opSym} ${p.literal}`);
                 }
                 else {
-                    conditions.push(`${quoteIdent(col)} ${opSym} $${idx++}${p.sql}`);
+                    conditions.push(`${ref(col)} ${opSym} $${idx++}${p.sql}`);
                     values.push(p.bound);
                 }
             }
@@ -598,7 +626,7 @@ function buildWhereClause(info, where, startIndex) {
                             values.push(p.bound);
                         }
                     }
-                    conditions.push(`${quoteIdent(col)} IN (${parts.join(", ")})`);
+                    conditions.push(`${ref(col)} IN (${parts.join(", ")})`);
                 }
             }
         }
@@ -608,7 +636,7 @@ function buildWhereClause(info, where, startIndex) {
         else {
             const p = prepareValue(value, pgType);
             if (p.kind === "literal") {
-                conditions.push(`${quoteIdent(col)} = ${p.literal}`);
+                conditions.push(`${ref(col)} = ${p.literal}`);
             }
             else {
                 // Blind-index OR rewrite (#818): if the column has a bidx
@@ -623,11 +651,11 @@ function buildWhereClause(info, where, startIndex) {
                     typeof value === "string" &&
                     !col.endsWith("_bidx") &&
                     info.hasColumn(bidxCol)) {
-                    conditions.push(`(${quoteIdent(col)} = $${idx++} OR ${quoteIdent(bidxCol)} = $${idx++})`);
+                    conditions.push(`(${ref(col)} = $${idx++} OR ${ref(bidxCol)} = $${idx++})`);
                     values.push(p.bound, computeBlindIndex(bidxKey, value));
                 }
                 else {
-                    conditions.push(`${quoteIdent(col)} = $${idx++}${p.sql}`);
+                    conditions.push(`${ref(col)} = $${idx++}${p.sql}`);
                     values.push(p.bound);
                 }
             }
@@ -820,6 +848,76 @@ export async function fetchOne(db, table, where) {
     const rows = await selectMany(db, table, where, { limit: 1 });
     return rows[0];
 }
+const JOIN_LEFT_ALIAS = "l";
+const JOIN_RIGHT_ALIAS = "r";
+function requireJoinColumn(info, field, role) {
+    if (!info.hasColumn(field)) {
+        throw new Error(`selectInnerJoin: ${role} "${field}" is not a column of "${info.name}"`);
+    }
+    return info.columnOf(field);
+}
+export async function selectInnerJoin(db, spec) {
+    assertNotTenantScoped(db, "selectInnerJoin");
+    const leftInfo = extractTableInfo(spec.left);
+    const rightInfo = extractTableInfo(spec.right);
+    if (spec.limit !== undefined && (!Number.isInteger(spec.limit) || spec.limit < 0)) {
+        throw new Error(`selectInnerJoin: limit must be a non-negative integer, got ${spec.limit}`);
+    }
+    const leftColumns = (spec.leftFields ??
+        requireEntityTableMeta(spec.left, "selectInnerJoin").columns.map((c) => c.name)).map((field) => requireJoinColumn(leftInfo, field, "leftFields entry"));
+    const rightColumns = (spec.rightFields ?? []).map((field) => requireJoinColumn(rightInfo, field, "rightFields entry"));
+    // Positional aliases: a `<side>__<column>` scheme would hit Postgres' 63-byte
+    // identifier truncation for long column names.
+    const projected = [
+        ...leftColumns.map((column) => ({ side: "left", column })),
+        ...rightColumns.map((column) => ({ side: "right", column })),
+    ];
+    if (projected.length === 0) {
+        throw new Error("selectInnerJoin: no columns selected");
+    }
+    const selectList = projected
+        .map(({ side, column }, index) => `${quoteIdent(side === "left" ? JOIN_LEFT_ALIAS : JOIN_RIGHT_ALIAS)}.${quoteIdent(column)} AS "c${index}"`)
+        .join(", ");
+    const onPairs = spec.on.map((pair) => {
+        const leftColumn = requireJoinColumn(leftInfo, pair.left, "on.left");
+        const rightColumn = requireJoinColumn(rightInfo, pair.right, "on.right");
+        const leftRef = `${quoteIdent(JOIN_LEFT_ALIAS)}.${quoteIdent(leftColumn)}`;
+        const rightRef = `${quoteIdent(JOIN_RIGHT_ALIAS)}.${quoteIdent(rightColumn)}`;
+        return leftInfo.pgTypeOf(leftColumn) === rightInfo.pgTypeOf(rightColumn)
+            ? `${leftRef} = ${rightRef}`
+            : `${leftRef}::text = ${rightRef}::text`;
+    });
+    let sqlText = `SELECT ${selectList} FROM ${quoteIdent(leftInfo.name)} AS ${quoteIdent(JOIN_LEFT_ALIAS)} ` +
+        `INNER JOIN ${quoteIdent(rightInfo.name)} AS ${quoteIdent(JOIN_RIGHT_ALIAS)} ON ${onPairs.join(" AND ")}`;
+    const conditions = [];
+    const values = [];
+    if (spec.leftWhere && Object.keys(spec.leftWhere).length > 0) {
+        const w = buildWhereClause(leftInfo, spec.leftWhere, values.length + 1, JOIN_LEFT_ALIAS);
+        conditions.push(w.sqlText);
+        values.push(...w.values);
+    }
+    if (spec.rightWhere && Object.keys(spec.rightWhere).length > 0) {
+        const w = buildWhereClause(rightInfo, spec.rightWhere, values.length + 1, JOIN_RIGHT_ALIAS);
+        conditions.push(w.sqlText);
+        values.push(...w.values);
+    }
+    if (conditions.length > 0)
+        sqlText += ` WHERE ${conditions.join(" AND ")}`;
+    if (spec.limit !== undefined)
+        sqlText += ` LIMIT ${spec.limit}`;
+    const raw = (await unsafeReadRetrying(db, sqlText, values));
+    return raw.map((row) => {
+        const leftRow = {};
+        const rightRow = {};
+        projected.forEach(({ side, column }, index) => {
+            (side === "left" ? leftRow : rightRow)[column] = row[`c${index}`];
+        });
+        return {
+            left: coerceRow(leftRow, leftInfo),
+            right: coerceRow(rightRow, rightInfo),
+        };
+    });
+}
 // Bulk INSERT — same shape as insertOne but takes an array of rows and
 // produces one multi-VALUES statement. Mirrors drizzle's
 // `db.insert(t).values(rows[])`. Empty input is a no-op.
@@ -1064,15 +1162,20 @@ function assertValidAggregateLimits(spec) {
     if (spec.orderByValue !== undefined && !AGGREGATE_ORDER_DIRECTIONS.includes(spec.orderByValue)) {
         throw new Error(`aggregateWhere: unknown orderByValue "${String(spec.orderByValue)}"`);
     }
+    if (spec.orderByKeys !== undefined && !AGGREGATE_ORDER_DIRECTIONS.includes(spec.orderByKeys)) {
+        throw new Error(`aggregateWhere: unknown orderByKeys "${String(spec.orderByKeys)}"`);
+    }
 }
 function aggregateGroupOrderLimitSql(spec, dimensionCount) {
     let sqlText = "";
     if (dimensionCount > 0) {
         const positions = Array.from({ length: dimensionCount }, (_, index) => String(index + 1));
         sqlText += ` GROUP BY ${positions.join(", ")}`;
+        const keyDirection = spec.orderByKeys === "desc" ? "DESC" : "ASC";
+        const keyParts = positions.map((position) => `${position} ${keyDirection}`);
         const orderParts = spec.orderByValue === undefined
-            ? positions
-            : [`${dimensionCount + 1} ${spec.orderByValue === "desc" ? "DESC" : "ASC"}`, ...positions];
+            ? keyParts
+            : [`${dimensionCount + 1} ${spec.orderByValue === "desc" ? "DESC" : "ASC"}`, ...keyParts];
         sqlText += ` ORDER BY ${orderParts.join(", ")}`;
     }
     if (spec.limit !== undefined)
@@ -1162,6 +1265,24 @@ export async function upsertByPk(db, table, values, updateOnConflict) {
     });
 }
 // biome-ignore lint/suspicious/noExplicitAny: see selectMany default
+export async function insertOnConflictDoNothing(db, table, values, options) {
+    assertNotTenantScoped(db, "insertOnConflictDoNothing");
+    const info = extractTableInfo(table);
+    const entries = insertEntries(info, values);
+    const conflictCols = resolveConflictColumns(table, info, options?.conflictKeys);
+    const { sqlPrefix, params } = buildInsertSql(info, entries);
+    const conflictList = conflictCols.map((c) => quoteIdent(c)).join(", ");
+    const sqlText = `${sqlPrefix} ON CONFLICT (${conflictList}) DO NOTHING RETURNING *`;
+    const rows = (await unsafeLoggingClosedConnection(db, sqlText, params, {
+        operation: "insertOnConflictDoNothing",
+        table: info.name,
+    }));
+    const first = rows[0];
+    if (!first)
+        return undefined;
+    return coerceRow(first, info);
+}
+// biome-ignore lint/suspicious/noExplicitAny: see selectMany default
 export async function incrementCounter(db, table, values, increments, options = {}) {
     assertNotTenantScoped(db, "incrementCounter");
     const info = extractTableInfo(table);

package/dist/db/queries/shadow-swap.d.ts

@@ -1,3 +1,4 @@
+import type { ProjectionRowIdOf } from "@cosmicdrift/kumiko-types/projection";
 import type { DbConnection, DbTx } from "../connection.js";
 import type { EntityTableMeta } from "../entity-table-meta.js";
 import { type AnyDb } from "../query.js";
@@ -8,7 +9,7 @@ export declare function assertLiveColumnsMatchMeta(db: DbConnection | DbTx, meta
 export declare function assertLiveTableHasNoRowLevelSecurity(tx: AnyDb, tableName: string, projectionName?: string): Promise<void>;
 export declare function buildShadowTable(tx: AnyDb, meta: EntityTableMeta): Promise<void>;
 export declare function fenceLiveTable(tx: AnyDb, tableName: string, lockTimeoutMs: number): Promise<void>;
-export declare function assertNoUnreachableLiveRows(tx: AnyDb, projectionName: string, tableName: string, aggregateTypes: readonly string[]): Promise<void>;
+export declare function assertNoUnreachableLiveRows(tx: AnyDb, projectionName: string, tableName: string, aggregateTypes: readonly string[], derivedRowIds?: Readonly<Record<string, ProjectionRowIdOf>>): Promise<void>;
 export declare function assertNoBlindIndexLoss(tx: AnyDb, tableName: string, meta: EntityTableMeta, projectionName: string): Promise<void>;
 export type ColumnDriftResult = {
     readonly rowCount: number;

package/dist/db/queries/shadow-swap.js

@@ -17,6 +17,7 @@
 // Boundary: the shadow table is rebuilt from EntityTableMeta, so any index NOT
 // expressed in meta (hand-added in a migration) is not reconstructed, and a
 // partial index whose WHERE the renderer can't express is rejected up-front.
+import { isUuid, parseTenantId } from "@cosmicdrift/kumiko-types/identifiers";
 import { configuredBlindIndexKey } from "../../crypto/index.js";
 import { asEntityTableMeta, asRawClient } from "../query.js";
 import { renderTableDdl } from "../render-ddl.js";
@@ -178,19 +179,80 @@ const UNREACHABLE_SAMPLE_LIMIT = 20;
 //
 // Implicit projections only (caller-gated). aggregate_id and the entity id are
 // both uuid, so the anti-join probes the events index without a cast.
-export async function assertNoUnreachableLiveRows(tx, projectionName, tableName, aggregateTypes) {
+//
+// Source streams whose rows are keyed by a DERIVED id (r.extendEntityProjection
+// `rowIdOf`, e.g. tenant-salted) cannot be matched on aggregate_id: their
+// distinct (tenant, aggregate) pairs are mapped through rowIdOf into a temp
+// table, and a live row is backed when its id is in that set. The guard stays
+// strict — a row keyed by the raw aggregate id of a derived stream is a ghost.
+const DERIVED_ROW_ID_BATCH_SIZE = 5000;
+const DERIVED_ROW_ID_TABLE = "pg_temp.kumiko_derived_row_ids";
+async function fillDerivedRowIdTable(raw, projectionName, aggregateType, rowIdOf) {
+    let cursor;
+    for (;;) {
+        const page = await raw.unsafe(`SELECT DISTINCT "tenant_id"::text AS tenant_id, "aggregate_id"::text AS aggregate_id
+         FROM "kumiko_events"
+        WHERE "aggregate_type" = $1
+          ${cursor ? `AND ("tenant_id", "aggregate_id") > ($2::uuid, $3::uuid)` : ""}
+        ORDER BY "tenant_id", "aggregate_id"
+        LIMIT ${DERIVED_ROW_ID_BATCH_SIZE}`, cursor ? [aggregateType, cursor.tenant_id, cursor.aggregate_id] : [aggregateType]);
+        // skip: keyset exhausted — every source event of this type has been mapped
+        if (page.length === 0)
+            return;
+        const derivedIds = page.map((row) => {
+            const tenantId = parseTenantId(row.tenant_id);
+            if (tenantId === null) {
+                throw new Error(`projection-rebuild "${projectionName}": event of aggregate type "${aggregateType}" ` +
+                    `carries a non-uuid tenant_id "${row.tenant_id}".`);
+            }
+            const derived = rowIdOf({ tenantId, aggregateId: row.aggregate_id });
+            if (!isUuid(derived)) {
+                throw new Error(`projection-rebuild "${projectionName}": rowIdOf for aggregate type "${aggregateType}" ` +
+                    `returned "${String(derived)}", which is not a uuid (aggregate ${row.aggregate_id}).`);
+            }
+            return derived;
+        });
+        await raw.unsafe(`INSERT INTO ${DERIVED_ROW_ID_TABLE} ("id") SELECT unnest($1::uuid[]) ON CONFLICT DO NOTHING`, [derivedIds]);
+        // skip: a short page is the last one
+        if (page.length < DERIVED_ROW_ID_BATCH_SIZE)
+            return;
+        cursor = page[page.length - 1];
+    }
+}
+export async function assertNoUnreachableLiveRows(tx, projectionName, tableName, aggregateTypes, derivedRowIds = {}) {
     // skip: no source streams → no events could back any row anyway; a rebuild
     // of a subscription-less projection swaps an empty shadow (handled upstream).
     if (aggregateTypes.length === 0)
         return;
     const raw = asRawClient(tx);
     const t = quoteTableIdent(tableName);
+    const derivedTypes = aggregateTypes.filter((type) => derivedRowIds[type] !== undefined);
+    const directTypes = aggregateTypes.filter((type) => derivedRowIds[type] === undefined);
+    if (derivedTypes.length > 0) {
+        // search_path points at the shadow schema here; pg_temp is addressed explicitly.
+        await raw.unsafe(`CREATE TEMP TABLE IF NOT EXISTS kumiko_derived_row_ids ("id" uuid PRIMARY KEY) ON COMMIT DROP`);
+        await raw.unsafe(`TRUNCATE ${DERIVED_ROW_ID_TABLE}`);
+        for (const aggregateType of derivedTypes) {
+            const rowIdOf = derivedRowIds[aggregateType];
+            // skip: filtered by derivedTypes above, narrows the Record lookup for the compiler
+            if (rowIdOf === undefined)
+                continue;
+            await fillDerivedRowIdTable(raw, projectionName, aggregateType, rowIdOf);
+        }
+    }
+    const unbackedClauses = [];
+    if (directTypes.length > 0) {
+        unbackedClauses.push(`NOT EXISTS (
+         SELECT 1 FROM "kumiko_events" e
+          WHERE e."aggregate_id" = l."id" AND e."aggregate_type" = ANY($1::text[])
+       )`);
+    }
+    if (derivedTypes.length > 0) {
+        unbackedClauses.push(`NOT EXISTS (SELECT 1 FROM ${DERIVED_ROW_ID_TABLE} d WHERE d."id" = l."id")`);
+    }
     const ghosts = await raw.unsafe(`SELECT l."id" FROM public.${t} l
-     WHERE NOT EXISTS (
-       SELECT 1 FROM "kumiko_events" e
-        WHERE e."aggregate_id" = l."id" AND e."aggregate_type" = ANY($1::text[])
-     )
-     LIMIT ${UNREACHABLE_SAMPLE_LIMIT}`, [aggregateTypes]);
+     WHERE ${unbackedClauses.join(" AND ")}
+     LIMIT ${UNREACHABLE_SAMPLE_LIMIT}`, directTypes.length > 0 ? [directTypes] : []);
     // skip: every live row has a backing event — nothing unreachable, swap is safe
     if (ghosts.length === 0)
         return;
@@ -200,7 +262,8 @@ export async function assertNoUnreachableLiveRows(tx, projectionName, tableName,
         `event in the projection's source streams and cannot be reconstructed by replay — the swap ` +
         `would silently drop them (ids: ${ids.join(", ")}). A handler direct-inserted these rows ` +
         `without emitting a .created event. Fix: register the table with r.storeTable(meta, ` +
-        `{ reason }) to opt out of rebuild, or emit the missing events. See ` +
+        `{ reason }) to opt out of rebuild, or emit the missing events. Rows keyed by an id ` +
+        `derived from the source event declare \`rowIdOf\` on r.extendEntityProjection. See ` +
         `docs/reference/entity-write-patterns.md. Rebuild aborted; live table untouched.`);
 }
 // The bidx column is schema-driven, not key-driven: it exists NULL in a