@cosmicdrift/kumiko-framework 0.338.0 → 0.340.0

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

@@ -23,6 +23,7 @@ export type AuthMiddlewareOptions = {
     readonly anonymousAccess?: AnonymousAccessResolved;
     readonly resolveTenantLifecycleStatus?: TenantLifecycleStatusResolver;
     readonly foreignCookieOrigins?: ReadonlySet<string>;
+    readonly isTenantlessAnonymousWrite?: (handlerQn: string) => boolean;
 };
 export type TenantResolver = (c: Context) => Promise<TenantId | null> | TenantId | null;
 export type TenantExists = (tenantId: TenantId) => Promise<boolean> | boolean;

package/dist/api/auth-middleware.js

@@ -1,7 +1,7 @@
 import { getCookie } from "hono/cookie";
 import { TENANT_TEARDOWN_STATUSES } from "../engine/active-membership.js";
 import { createAnonymousUser } from "../engine/system-user.js";
-import { parseTenantId } from "../engine/types/identifiers.js";
+import { parseTenantId, SYSTEM_TENANT_ID } from "../engine/types/identifiers.js";
 import { isSessionRequiredApiPath, TENANT_COOKIE_NAME, TENANT_HEADER_NAME, } from "./api-constants.js";
 import { isForeignCookieOrigin } from "./origin-middleware.js";
 const USER_KEY = "pipelineUser";
@@ -78,7 +78,7 @@ function extractToken(c) {
     return { error: "missing" };
 }
 export function authMiddleware(jwt, options = {}) {
-    const { sessionChecker, anonymousAccess, tokenVerifier, resolveTenantLifecycleStatus, foreignCookieOrigins, } = options;
+    const { sessionChecker, anonymousAccess, tokenVerifier, resolveTenantLifecycleStatus, foreignCookieOrigins, isTenantlessAnonymousWrite, } = options;
     // Fail loud at boot, not silently at request time: a tenantResolver
     // without a declared resolverTrust is an ambiguous trust decision no
     // sane default can make on the app's behalf (see AnonymousAccessConfig).
@@ -87,6 +87,7 @@ export function authMiddleware(jwt, options = {}) {
             'declare "authoritative" (resolver wins over client header/cookie) or ' +
             '"fallback-only" (client wins, resolver is a last resort).');
     }
+    const anonymousExtras = { isTenantlessAnonymousWrite };
     return async (c, next) => {
         const extracted = extractToken(c);
         if ("error" in extracted) {
@@ -117,7 +118,7 @@ export function authMiddleware(jwt, options = {}) {
                         i18nKey: "auth.errors.missingToken",
                     });
                 }
-                return await handleAnonymous(c, anonymousAccess, next, resolveTenantLifecycleStatus);
+                return await handleAnonymous(c, anonymousAccess, next, resolveTenantLifecycleStatus, anonymousExtras);
             }
             return middlewareReject(c, {
                 code: "missing_token",
@@ -136,7 +137,7 @@ export function authMiddleware(jwt, options = {}) {
             !c.req.path.startsWith("/api/auth/") &&
             foreignCookieOrigins &&
             isForeignCookieOrigin(c, foreignCookieOrigins)) {
-            return await handleAnonymous(c, anonymousAccess, next, resolveTenantLifecycleStatus);
+            return await handleAnonymous(c, anonymousAccess, next, resolveTenantLifecycleStatus, anonymousExtras);
         }
         // Generic bearer-verifier path: try the wired tokenVerifier (PAT, future
         // JWT-provider, ...) BEFORE jwt.verify. A hit short-circuits the JWT path
@@ -153,7 +154,7 @@ export function authMiddleware(jwt, options = {}) {
         const rejectInvalidCredential = async (rejection) => {
             if (isStaleCookieDowngradable(c, transport, anonymousAccess)) {
                 return await handleAnonymous(c, anonymousAccess, next, resolveTenantLifecycleStatus, {
-                    rejectionIfTenantUnresolved: rejection,
+                    staleCredential: { rejectionIfTenantUnresolved: rejection },
                 });
             }
             return middlewareReject(c, rejection);
@@ -271,7 +272,8 @@ async function handleVerifiedBearerUser(c, user, next, resolveTenantLifecycleSta
 //   5. Synthesise the anonymous SessionUser. The transport flag stays unset
 //      so csrf-middleware skips the double-submit check (no auth-cookie ⇒
 //      no CSRF vector to defend against).
-async function handleAnonymous(c, config, next, resolveTenantLifecycleStatus, staleCredential) {
+async function handleAnonymous(c, config, next, resolveTenantLifecycleStatus, extras = {}) {
+    const { staleCredential, isTenantlessAnonymousWrite } = extras;
     // A downgraded stale credential whose anonymous tenant can't be resolved or
     // is torn down answers with the credential's own 401: a tenant error would
     // hide the session end from the client.
@@ -292,11 +294,14 @@ async function handleAnonymous(c, config, next, resolveTenantLifecycleStatus, st
             ? { id: cookieCheck.tenantId, source: "cookie" }
             : null;
     // Step 3: pick the authoritative tenant.
-    const resolved = await resolveTenant(c, config, clientTenant);
+    const resolved = await resolveTenantOrTenantless(c, config, clientTenant, {
+        allowTenantless: staleCredential === undefined,
+        isTenantlessAnonymousWrite,
+    });
     if ("error" in resolved)
         return rejectTenant(resolved.error);
     // Step 4: existence check for untrusted sources.
-    if (resolved.source !== "default" && config.tenantExists) {
+    if (resolved.source !== "default" && resolved.source !== "tenantless" && config.tenantExists) {
         const exists = await config.tenantExists(resolved.tenantId);
         if (!exists) {
             return rejectTenant({
@@ -308,8 +313,10 @@ async function handleAnonymous(c, config, next, resolveTenantLifecycleStatus, st
             });
         }
     }
-    // Step 5: synthesise + continue.
-    const lifecycleReject = await rejectIfTenantTeardown(c, resolved.tenantId, resolveTenantLifecycleStatus);
+    // Step 5: synthesise + continue. SYSTEM_TENANT_ID is no lifecycle-managed tenant.
+    const lifecycleReject = resolved.source === "tenantless"
+        ? undefined
+        : await rejectIfTenantTeardown(c, resolved.tenantId, resolveTenantLifecycleStatus);
     if (lifecycleReject) {
         return staleCredential
             ? middlewareReject(c, staleCredential.rejectionIfTenantUnresolved)
@@ -321,6 +328,43 @@ async function handleAnonymous(c, config, next, resolveTenantLifecycleStatus, st
     // when next() ran; explicit return makes the union return-type honest.
     return;
 }
+// The exemption applies only where resolveTenant answers tenant_required:
+// never on tenant_mismatch, never when the client named a tenant via X-Tenant,
+// never for a downgraded stale credential. An ambient tenant cookie does not
+// block it: tenant_required with a client tenant only happens when an
+// authoritative resolver stayed silent, and that path ignores the cookie
+// anyway, so a customer who also uses the app on this host can still cancel.
+async function resolveTenantOrTenantless(c, config, clientTenant, tenantless) {
+    const resolved = await resolveTenant(c, config, clientTenant);
+    const { isTenantlessAnonymousWrite } = tenantless;
+    if ("error" in resolved &&
+        resolved.error.code === "tenant_required" &&
+        clientTenant?.source !== "header" &&
+        tenantless.allowTenantless &&
+        isTenantlessAnonymousWrite !== undefined &&
+        (await isFlaggedTenantlessWrite(c, isTenantlessAnonymousWrite))) {
+        return { tenantId: SYSTEM_TENANT_ID, source: "tenantless" };
+    }
+    return resolved;
+}
+// Body peek for the tenantless exemption: only a single-command POST
+// /api/write qualifies, never /api/batch. Parsing the clone leaves the body
+// intact for the dispatcher; the body-size limit already ran upstream.
+async function isFlaggedTenantlessWrite(c, isTenantlessAnonymousWrite) {
+    if (c.req.method !== "POST" || c.req.path !== "/api/write")
+        return false;
+    try {
+        const body = await c.req.raw.clone().json();
+        return (typeof body === "object" &&
+            body !== null &&
+            "type" in body &&
+            typeof body.type === "string" &&
+            isTenantlessAnonymousWrite(body.type));
+    }
+    catch {
+        return false;
+    }
+}
 // Validates an X-Tenant / cookie value against the tenantId format. Returns
 // `{tenantId: null}` when absent, `{tenantId: TenantId}` when valid, or
 // `{error: …}` when the value is non-empty junk (so the caller can return

package/dist/api/routes.d.ts

@@ -1,4 +1,4 @@
-import { Hono } from "hono";
+import { type Context, Hono } from "hono";
 import type { Dispatcher } from "../pipeline/dispatcher.js";
 export declare const StreamFrame: {
     readonly chunk: "chunk";
@@ -18,3 +18,4 @@ 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 handleUncaughtRouteError(err: Error, c: Context): Response | Promise<Response>;

package/dist/api/routes.js

@@ -1,4 +1,5 @@
 import { Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
 import { streamSSE } from "hono/streaming";
 import { AccessDeniedError, reraiseAsKumikoError, serializeError, toKumikoError, ValidationError, } from "../errors/index.js";
 import { createFallbackLogger } from "../logging/index.js";
@@ -356,17 +357,39 @@ function writeErrorResponse(c, err, type) {
     const { error } = serializeError(err, requestId);
     return c.json({ isSuccess: false, error }, err.httpStatus); // @cast-boundary engine-payload
 }
+function clientAbortResponse(c, requestId, type) {
+    logClientWarn("request aborted by client", requestId, type, {
+        status: CLIENT_CLOSED_REQUEST_STATUS,
+    });
+    return c.body(null, CLIENT_CLOSED_REQUEST_STATUS); // @cast-boundary non-standard client-closed-request status, Hono's union doesn't include it
+}
 // 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) {
     const requestId = requestContext.get()?.requestId;
-    if (isClientAbort(err)) {
-        logClientWarn("request aborted by client", requestId, type, {
-            status: CLIENT_CLOSED_REQUEST_STATUS,
-        });
-        return c.body(null, CLIENT_CLOSED_REQUEST_STATUS); // @cast-boundary non-standard client-closed-request status, Hono's union doesn't include it
-    }
+    if (isClientAbort(err))
+        return clientAbortResponse(c, requestId, type);
     logServerFault(err, requestId, type);
     const body = serializeError(err, requestId);
     return c.json(body, err.httpStatus); // @cast-boundary engine-payload
 }
+// A raw throw under the request signal (signal.throwIfAborted(), an aborted
+// fetch) is the signal's own reason or wraps it as `cause`.
+function isRequestAbortError(err, signal) {
+    return signal.aborted && (err === signal.reason || err.cause === signal.reason);
+}
+// Root `app.onError`: whatever a route rethrows instead of shaping itself.
+// Without it Hono's default handler console.error()s the bare error and
+// answers an unclassified 500 — including for a client that simply hung up.
+// requestContext only exists under /api/*, so the abort check reads the raw
+// request signal.
+export function handleUncaughtRouteError(err, c) {
+    if (err instanceof HTTPException)
+        return err.getResponse();
+    const requestId = requestContext.get()?.requestId;
+    if (isRequestAbortError(err, c.req.raw.signal))
+        return clientAbortResponse(c, requestId);
+    const kumikoError = toKumiko(err);
+    logServerFault(kumikoError, requestId);
+    return c.json(serializeError(kumikoError, requestId), kumikoError.httpStatus); // @cast-boundary engine-payload
+}

package/dist/api/server.js

@@ -39,7 +39,7 @@ import { createDefaultSseBroker } from "./redis-sse-broker.js";
 import { requestContext } from "./request-context.js";
 import { buildRequestContextData, requestIdMiddleware } from "./request-id-middleware.js";
 import { DEFAULT_MAX_REQUEST_BYTES, registerBodyLimit, registerHealthRoutes, registerMetricsRoute, registerVersionRoute, } from "./route-registrars.js";
-import { createApiRoutes } from "./routes.js";
+import { createApiRoutes, handleUncaughtRouteError } from "./routes.js";
 import { createSseRoute } from "./sse-route.js";
 import { buildWebSocketSessionRevalidator, createWebSocketConnectionLimiter, hasWebSocketUpgradeServer, isWebSocketUpgradeRequest, WEBSOCKET_DEFAULT_MAX_CONNECTIONS_PER_USER, WEBSOCKET_DEFAULT_MAX_MESSAGE_BYTES, } from "./websocket-route.js";
 // The per-tenant file-provider resolver, built once for a registry+context so
@@ -380,6 +380,8 @@ export function buildServer(options) {
         });
     }
     const app = new Hono();
+    // Sub-apps mounted via app.route() without their own handler inherit this one.
+    app.onError(handleUncaughtRouteError);
     // Only entry:"signature" bypasses jwtGuard (verify() authenticates
     // itself); entry:"anonymous" still needs the anonymousAccess fallthrough
     // (tenant-by-host), entry:"user" needs c.get("user") populated.
@@ -453,7 +455,13 @@ export function buildServer(options) {
     const normalizedForeignCookieOrigins = options.auth?.allowedOrigins?.length
         ? new Set(options.auth.allowedOrigins.map(normalizeOrigin))
         : undefined;
+    const tenantlessAnonymousQns = new Set([...options.registry.getAllWriteHandlers()]
+        .filter(([, handler]) => handler.tenantlessAnonymous === true)
+        .map(([qn]) => qn));
     const jwtGuard = authMiddleware(jwt, {
+        ...(tenantlessAnonymousQns.size > 0
+            ? { isTenantlessAnonymousWrite: (qn) => tenantlessAnonymousQns.has(qn) }
+            : {}),
         ...(options.auth?.sessionChecker ? { sessionChecker: options.auth.sessionChecker } : {}),
         ...(options.auth?.tokenVerifier ? { tokenVerifier: options.auth.tokenVerifier } : {}),
         ...(tenantLifecycleResolver ? { resolveTenantLifecycleStatus: tenantLifecycleResolver } : {}),

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

@@ -24,6 +24,7 @@ import { KUMIKO_META_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types
 import { Temporal } from "temporal-polyfill";
 import { requestContext } from "../api/request-context.js";
 import { computeBlindIndex, configuredBlindIndexKey } from "../crypto/blind-index.js";
+import { isPiiCiphertext } from "../crypto/pii-ciphertext-format.js";
 import { SQL_EXPR_BRAND } from "../db/dialect.js";
 import { extractPgError } from "../db/pg-error.js";
 import { toSnakeCase } from "../db/table-builder.js";
@@ -88,7 +89,7 @@ export function asRawClient(db) {
     // closed instead of silently unwrapping a tenant-scoped handle.
     if (isTenantDbShape(db)) {
         throw new Error("asRawClient: received a tenant-scoped TenantDb (ctx.db). Raw SQL helpers do not apply the " +
-            "tenant filter — use a ctx.db.<method>, or ctx.db.unsafeRaw(reason) with escapeHatch: " +
+            "tenant filter — use a ctx.db.<method>, or ctx.db.unsafeRaw() with escapeHatch: " +
             "{ reason } on the handler/hook (r.systemScope() features: ctx.systemDb.unsafeRaw(reason)).");
     }
     // Drizzle DbConnection (legacy compat): $client = postgres-js Sql.
@@ -174,11 +175,11 @@ function tenantDbDelegate(db) {
 function assertNotTenantScoped(db, fnName) {
     if (tenantDbDelegate(db) !== undefined) {
         throw new Error(`${fnName}: received a tenant-scoped db but this helper does not apply the tenant filter. ` +
-            "Pass ctx.db.unsafeRaw(reason) (with escapeHatch: { reason } on the handler/hook) for an " +
+            "Pass ctx.db.unsafeRaw() (with escapeHatch: { reason } on the handler/hook) for an " +
             "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) {
@@ -462,6 +463,11 @@ function prepareValue(value, pgType) {
     if (isSqlExpression(value)) {
         return { kind: "literal", literal: value.text };
     }
+    // A PII-encrypted jsonb field is a JSON string scalar; a raw string bound to
+    // ::jsonb would be parsed as JSON text (or double-encoded under Bun.SQL).
+    if (pgType === "jsonb" && isPiiCiphertext(value)) {
+        return { kind: "param", sql: "::text::jsonb", bound: JSON.stringify(value) };
+    }
     if (pgType === "jsonb" && value !== null) {
         const prepared = prepareJsonbValue(value);
         if (prepared)
@@ -477,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`
@@ -495,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);
             }
         }
@@ -508,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) {
@@ -529,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 = {
@@ -558,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);
                 }
             }
@@ -592,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(", ")})`);
                 }
             }
         }
@@ -602,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
@@ -617,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);
                 }
             }
@@ -814,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.
@@ -1058,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)
@@ -1156,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/crypto/event-pii.js

@@ -14,7 +14,7 @@
 // silent no-op (forgetting the option) is now either an explicit "none" or a
 // missing subject KMS at encrypt-time, both visible states, not a gap.
 import { requestContext } from "../api/request-context.js";
-import { configuredPiiSubjectKms, encryptPiiValueForSubject } from "./pii-field-encryption.js";
+import { configuredPiiSubjectKms, encryptPiiJsonValueForSubject, encryptPiiValueForSubject, } from "./pii-field-encryption.js";
 import { resolveEventSubject } from "./subject-resolver.js";
 import { SYSTEM_EVENT_PII_STANCES, SYSTEM_EVENT_PREFIX } from "./system-event-pii.js";
 // Boot-injected like configurePiiSubjectKms — createRegistry calls this with
@@ -41,6 +41,12 @@ function resolvePiiStance(eventType) {
     }
     return stance;
 }
+// The catalog carries no field types: strings keep the plain format, objects
+// and arrays (jsonb payload fields) use the self-describing JSON format.
+// Bare numbers/booleans stay a loud error so a mistyped string field is caught.
+function isStructuredJsonValue(value) {
+    return typeof value === "object" && value !== null;
+}
 // Encrypts catalogued payload fields under the declared subject's DEK
 // (user/tenant/self — resolveEventSubject, fw#2801). No-op when the event
 // type is uncatalogued or no subject KMS is configured (plaintext rollout
@@ -63,13 +69,16 @@ export async function encryptEventPayloadPii(eventType, payload, envelope) {
         const value = payload[field];
         if (value === null || value === undefined)
             continue;
-        if (typeof value !== "string") {
-            throw new Error(`Event "${eventType}" piiFields."${field}" must be a string payload field, got ${typeof value}`);
+        if (typeof value !== "string" && !isStructuredJsonValue(value)) {
+            throw new Error(`Event "${eventType}" piiFields."${field}" must be a string payload field (or an object/array for jsonb), got ${typeof value}`);
         }
         const subject = resolveEventSubject(field, spec, payload, envelope);
         if (subject === null)
             continue;
-        const encrypted = await encryptPiiValueForSubject(kms, subject, value, { requestId: requestContext.get()?.requestId ?? "append-event" }, field);
+        const kmsCtx = { requestId: requestContext.get()?.requestId ?? "append-event" };
+        const encrypted = typeof value === "string"
+            ? await encryptPiiValueForSubject(kms, subject, value, kmsCtx, field)
+            : await encryptPiiJsonValueForSubject(kms, subject, value, kmsCtx, field);
         if (encrypted !== value) {
             out ??= { ...payload };
             out[field] = encrypted;