@cosmicdrift/kumiko-framework 0.364.0 → 0.365.0

package/dist/db/queries/postgres-array-literal.d.ts

@@ -0,0 +1,2 @@
+export type PostgresArrayElement = string | number | bigint | null;
+export declare function toPostgresArrayLiteral(values: readonly PostgresArrayElement[]): string;

package/dist/db/queries/postgres-array-literal.js

@@ -0,0 +1,6 @@
+// Bun.SQL stringifies JS arrays via toString, so array params travel as a
+// Postgres array-literal string (`$1::text[]`) — identical on postgres-js and Bun.SQL.
+export function toPostgresArrayLiteral(values) {
+    const elements = values.map((value) => value === null ? "NULL" : `"${String(value).replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`);
+    return `{${elements.join(",")}}`;
+}

package/dist/db/queries/projection-rebuild.js

@@ -1,4 +1,5 @@
 import { asRawClient, unsafeReadRetrying } from "../query.js";
+import { toPostgresArrayLiteral } from "./postgres-array-literal.js";
 export async function markProjectionRebuilding(db, projectionName) {
     await asRawClient(db).unsafe(`INSERT INTO "kumiko_projections" ("name", "status") VALUES ($1, 'rebuilding')
      ON CONFLICT ("name") DO UPDATE SET
@@ -23,7 +24,7 @@ export async function selectEventsForProjectionRebuildBatch(db, aggregateTypes,
           WHERE a."tenant_id" = e."tenant_id" AND a."aggregate_id" = e."aggregate_id"
        )
      ORDER BY e."id" ASC
-     LIMIT $4`, [aggregateTypes, eventTypes, afterId, limit]);
+     LIMIT $4`, [toPostgresArrayLiteral(aggregateTypes), toPostgresArrayLiteral(eventTypes), afterId, limit]);
 }
 // Total subscribed events in the log — same source/type filter as
 // selectEventsForProjectionRebuildBatch, no id cursor. Under the cutover fence
@@ -39,7 +40,7 @@ export async function countSubscribedEvents(db, aggregateTypes, eventTypes) {
        AND NOT EXISTS (
          SELECT 1 FROM "kumiko_archived_streams" a
           WHERE a."tenant_id" = e."tenant_id" AND a."aggregate_id" = e."aggregate_id"
-       )`, [aggregateTypes, eventTypes]);
+       )`, [toPostgresArrayLiteral(aggregateTypes), toPostgresArrayLiteral(eventTypes)]);
     const raw = rows[0]?.n;
     if (typeof raw === "bigint")
         return raw;

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

@@ -9,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[], derivedRowIds?: Readonly<Record<string, ProjectionRowIdOf>>): Promise<void>;
+export declare function assertNoUnreachableLiveRows(tx: AnyDb, projectionName: string, tableName: string, aggregateTypes: readonly string[], derivedRowIds?: Readonly<Record<string, ProjectionRowIdOf>>, derivedRowIdBatchSize?: number): 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

@@ -22,6 +22,7 @@ import { configuredBlindIndexKey } from "../../crypto/index.js";
 import { asEntityTableMeta, asRawClient } from "../query.js";
 import { renderTableDdl } from "../render-ddl.js";
 import { columnNamesOf, tableExists } from "../schema-inspection.js";
+import { toPostgresArrayLiteral } from "./postgres-array-literal.js";
 import { quoteTableIdent } from "./table-ops.js";
 export const PROJECTION_REBUILD_SCHEMA = "kumiko_rebuild";
 const SCHEMA_IDENT = quoteTableIdent(PROJECTION_REBUILD_SCHEMA);
@@ -187,15 +188,18 @@ const UNREACHABLE_SAMPLE_LIMIT = 20;
 // 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) {
+async function fillDerivedRowIdTable(raw, projectionName, aggregateType, rowIdOf, batchSize) {
     let cursor;
     for (;;) {
-        const page = await raw.unsafe(`SELECT DISTINCT "tenant_id"::text AS tenant_id, "aggregate_id"::text AS aggregate_id
+        const page = await raw.unsafe(
+        // Selecting the uuid columns (no text alias) keeps ORDER BY and the keyset
+        // comparison on the same type; text ordering is collation-dependent.
+        `SELECT DISTINCT "tenant_id", "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]);
+        LIMIT ${batchSize}`, 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;
@@ -212,14 +216,14 @@ async function fillDerivedRowIdTable(raw, projectionName, aggregateType, rowIdOf
             }
             return derived;
         });
-        await raw.unsafe(`INSERT INTO ${DERIVED_ROW_ID_TABLE} ("id") SELECT unnest($1::uuid[]) ON CONFLICT DO NOTHING`, [derivedIds]);
+        await raw.unsafe(`INSERT INTO ${DERIVED_ROW_ID_TABLE} ("id") SELECT unnest($1::uuid[]) ON CONFLICT DO NOTHING`, [toPostgresArrayLiteral(derivedIds)]);
         // skip: a short page is the last one
-        if (page.length < DERIVED_ROW_ID_BATCH_SIZE)
+        if (page.length < batchSize)
             return;
         cursor = page[page.length - 1];
     }
 }
-export async function assertNoUnreachableLiveRows(tx, projectionName, tableName, aggregateTypes, derivedRowIds = {}) {
+export async function assertNoUnreachableLiveRows(tx, projectionName, tableName, aggregateTypes, derivedRowIds = {}, derivedRowIdBatchSize = DERIVED_ROW_ID_BATCH_SIZE) {
     // 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)
@@ -237,7 +241,7 @@ export async function assertNoUnreachableLiveRows(tx, projectionName, tableName,
             // skip: filtered by derivedTypes above, narrows the Record lookup for the compiler
             if (rowIdOf === undefined)
                 continue;
-            await fillDerivedRowIdTable(raw, projectionName, aggregateType, rowIdOf);
+            await fillDerivedRowIdTable(raw, projectionName, aggregateType, rowIdOf, derivedRowIdBatchSize);
         }
     }
     const unbackedClauses = [];
@@ -252,7 +256,7 @@ export async function assertNoUnreachableLiveRows(tx, projectionName, tableName,
     }
     const ghosts = await raw.unsafe(`SELECT l."id" FROM public.${t} l
      WHERE ${unbackedClauses.join(" AND ")}
-     LIMIT ${UNREACHABLE_SAMPLE_LIMIT}`, directTypes.length > 0 ? [directTypes] : []);
+     LIMIT ${UNREACHABLE_SAMPLE_LIMIT}`, directTypes.length > 0 ? [toPostgresArrayLiteral(directTypes)] : []);
     // skip: every live row has a backing event — nothing unreachable, swap is safe
     if (ghosts.length === 0)
         return;

package/dist/db/query.d.ts

@@ -1 +1 @@
-export { type AnyDb, aggregateWhere, asEntityTableMeta, asRawClient, coerceRow, countWhere, type DeleteManyBatchedOptions, type DeleteManyBatchedResult, deleteMany, deleteManyBatched, extractTableInfo, fetchOne, type IncrementCounterOptions, incrementCounter, insertMany, insertOne, type JsonTextMatch, type OrderByClause, runInNewTransaction, runInSavepoint, runInSavepointIfSupported, type SelectOptions, selectMany, type TableInfo, transaction, type UpsertOnConflictOptions, unsafeReadRetrying, updateMany, upsertByPk, upsertOnConflict, type WhereObject, type WhereOperator, type WhereValue, } from "../bun-db/query.js";
+export { type AnyDb, aggregateWhere, asEntityTableMeta, asRawClient, coerceRow, countWhere, type DeleteManyBatchedOptions, type DeleteManyBatchedResult, deleteMany, deleteManyBatched, extractTableInfo, fetchOne, type IncrementCounterOptions, incrementCounter, insertMany, insertOne, type JsonTextMatch, type OrderByClause, runInNewTransaction, runInSavepoint, runInSavepointIfSupported, runnerCanBeginTransaction, type SelectOptions, selectMany, type TableInfo, transaction, type UpsertOnConflictOptions, unsafeReadRetrying, updateMany, upsertByPk, upsertOnConflict, type WhereObject, type WhereOperator, type WhereValue, } from "../bun-db/query.js";

package/dist/db/query.js

@@ -1,3 +1,3 @@
 // Provider-neutrale Query-API. Re-exported aus bun-db/query.
 // Alle Consumer importieren von hier, nicht direkt aus bun-db/.
-export { aggregateWhere, asEntityTableMeta, asRawClient, coerceRow, countWhere, deleteMany, deleteManyBatched, extractTableInfo, fetchOne, incrementCounter, insertMany, insertOne, runInNewTransaction, runInSavepoint, runInSavepointIfSupported, selectMany, transaction, unsafeReadRetrying, updateMany, upsertByPk, upsertOnConflict, } from "../bun-db/query.js";
+export { aggregateWhere, asEntityTableMeta, asRawClient, coerceRow, countWhere, deleteMany, deleteManyBatched, extractTableInfo, fetchOne, incrementCounter, insertMany, insertOne, runInNewTransaction, runInSavepoint, runInSavepointIfSupported, runnerCanBeginTransaction, selectMany, transaction, unsafeReadRetrying, updateMany, upsertByPk, upsertOnConflict, } from "../bun-db/query.js";

package/dist/db/retired-framework-tables.js

@@ -14,10 +14,23 @@ export const retiredFrameworkTables = [
         explanation: "replaced by store_job_runs; the job run history was not migrated (operational data, not a system of record)",
     },
 ];
-const IDENT = `"?([^"\\s(;,.]+)"?`;
+// Optional schema prefix is skipped; only the table name is captured.
+const IDENT = `(?:"?[^"\\s(;,.]+"?\\.)?"?([^"\\s(;,.]+)"?`;
 const CREATE_TABLE_RE = new RegExp(`^CREATE TABLE\\s+(?:IF NOT EXISTS\\s+)?${IDENT}`, "i");
-const DROP_TABLE_RE = new RegExp(`^DROP TABLE\\s+(?:IF EXISTS\\s+)?${IDENT}`, "i");
+// DROP TABLE accepts a comma list; the list is split and each entry parsed with IDENT.
+const DROP_TABLE_LIST_RE = /^DROP TABLE\s+(?:IF EXISTS\s+)?([^;]+)/i;
+const IDENT_ONLY_RE = new RegExp(`^\\s*${IDENT}`);
+const RENAME_TABLE_RE = new RegExp(`^ALTER TABLE\\s+(?:IF EXISTS\\s+)?(?:ONLY\\s+)?${IDENT}\\s+RENAME TO\\s+${IDENT}`, "i");
 const COMMENTED_DROP_TABLE_RE = new RegExp(`^--\\s*DESTRUCTIVE:\\s*DROP TABLE\\s+(?:IF EXISTS\\s+)?${IDENT}`, "i");
+function droppedTableNames(line) {
+    const list = DROP_TABLE_LIST_RE.exec(line)?.[1];
+    if (list === undefined)
+        return [];
+    return list
+        .split(",")
+        .map((entry) => IDENT_ONLY_RE.exec(entry)?.[1])
+        .filter((name) => name !== undefined);
+}
 // Last known state per table across all migrations, in order — so a
 // DROP followed by a re-CREATE (managed-projection recreate) counts as
 // "created", and a commented drop followed by an executable one as "dropped".
@@ -38,8 +51,13 @@ function scanTableLifecycle(sqlTexts) {
                 states.set(created, "created");
                 continue;
             }
-            const dropped = DROP_TABLE_RE.exec(line)?.[1];
-            if (dropped !== undefined)
+            const renamed = RENAME_TABLE_RE.exec(line);
+            if (renamed?.[1] !== undefined && renamed[2] !== undefined) {
+                states.set(renamed[1], "dropped");
+                states.set(renamed[2], "created");
+                continue;
+            }
+            for (const dropped of droppedTableNames(line))
                 states.set(dropped, "dropped");
         }
     }

package/dist/db/table-builder.js

@@ -378,8 +378,12 @@ export function buildEntityTable(entityName, entity, options) {
             // entity.indexes[].where is now a SqlExpression (was drizzle SQL).
             // Pass through to the IndexBuilderWithCols.where()-API.
             if (def.where !== undefined) {
-                if (isSqlExpression(def.where))
-                    chain = chain.where(def.where);
+                // A silently dropped where would build a full (unique) index that
+                // entity-table-meta flags as needsManualWhere.
+                if (!isSqlExpression(def.where)) {
+                    throw new Error(`[${tableName}] index "${indexName}": where must be a sql\`...\` expression`);
+                }
+                chain = chain.where(def.where);
             }
             else if (def.unique === true && entity.softDelete === true) {
                 // Soft-deleted rows keep their value, so a full unique index would

package/dist/db/tenant-db.d.ts

@@ -19,6 +19,7 @@ export declare function createSystemDbView(db: TenantDb, dbOutsideTransaction?:
 export declare function scopeTenantDbToTenant(db: TenantDb, tenantId: TenantId): TenantDb;
 export declare function castTenantRows<T>(rows: readonly Record<string, unknown>[]): readonly T[];
 export { tableNameOf };
+export declare function requestedTenantIds(requested: unknown): readonly unknown[] | undefined;
 export declare function hasTenantColumn(table: Table | EntityTableMeta): boolean;
 export type TenantDbGrants = {
     readonly globalWrites?: EscapeHatchDeclaration;
@@ -37,4 +38,5 @@ export declare function acknowledgeConventionCrossTenant(tenantDb: TenantDb, rea
 export declare function reportConventionCrossTenantUse(acknowledged: TenantDb, target?: EscapeHatchTarget): void;
 export declare function runInOwnTransaction<T>(tenantDb: TenantDb, fn: (txDb: TenantDb) => Promise<T>): Promise<T>;
 export declare function createTenantDb(db: DbRunner, tenantId: TenantId, mode?: TenantDbMode, tracer?: Tracer, meter?: Meter, signal?: AbortSignal, grants?: TenantDbGrants): TenantDb;
+export declare function createProjectingTenantDb(db: DbRunner, tenantId: TenantId, projectionRegistry: Registry | undefined): TenantDb;
 export { asRawClient };

package/dist/db/tenant-db.js

@@ -1,4 +1,5 @@
 import { SYSTEM_SCOPE_CHECK_BRAND, } from "@cosmicdrift/kumiko-types/tenant-db-types";
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import { asEntityTableMeta, asRawClient, aggregateWhere as bunAggregateWhere, countWhere as bunCountWhere, deleteMany as bunDeleteMany, fetchOne as bunFetchOne, insertOne as bunInsertOne, selectMany as bunSelectMany, updateMany as bunUpdateMany, runInNewTransaction, } from "../db/query.js";
 import { SYSTEM_TENANT_ID } from "../engine/types/identifiers.js";
 import { AccessDeniedError, InternalError, memberResolutionReadOnlyDenied, } from "../errors/index.js";
@@ -235,6 +236,19 @@ export { tableNameOf };
 function hasGrant(decl) {
     return decl !== undefined && decl.reason.trim().length > 0;
 }
+// Tenant ids a where.tenantId filter asks for; undefined for operator forms
+// that cannot narrow to a tenant list (ne, like, ...).
+export function requestedTenantIds(requested) {
+    if (Array.isArray(requested))
+        return requested;
+    if (!isPlainObject(requested))
+        return [requested];
+    if (Array.isArray(requested["in"]))
+        return requested["in"];
+    if ("eq" in requested)
+        return [requested["eq"]];
+    return undefined;
+}
 function isForeignTenantId(tenantIdValue) {
     return tenantIdValue !== undefined && tenantIdValue !== SYSTEM_TENANT_ID;
 }
@@ -360,7 +374,7 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
         const allowed = [tenantId, SYSTEM_TENANT_ID];
         const requested = where?.["tenantId"];
         if (requested !== undefined) {
-            const requestedList = Array.isArray(requested) ? requested : [requested];
+            const requestedList = requestedTenantIds(requested) ?? [];
             const narrowed = requestedList.filter((t) => typeof t === "string" && allowed.includes(t));
             return { ...where, tenantId: narrowed.length > 0 ? narrowed : allowed };
         }
@@ -605,4 +619,9 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
         bindProjectionRegistry(tenantDb, projectionRegistry);
     return tenantDb;
 }
+// Tenant-mode TenantDb whose writes reach the registry's custom projections. The positional
+// undefineds of createTenantDb would hide a moved grants parameter from the type checker.
+export function createProjectingTenantDb(db, tenantId, projectionRegistry) {
+    return createTenantDb(db, tenantId, "tenant", undefined, undefined, undefined, projectionRegistry ? { projectionRegistry } : undefined);
+}
 export { asRawClient };

package/dist/derivatives/delete-stored-file.d.ts

@@ -1,6 +1,10 @@
+import type { FileContext } from "@cosmicdrift/kumiko-types/file-handle-types";
 export type StoredFileStore = {
     list(prefix: string): Promise<readonly string[]>;
     delete(key: string): Promise<void>;
 };
 export declare function listDerivativeKeys(originalKey: string, store: Pick<StoredFileStore, "list">, errorContext: string): Promise<readonly string[]>;
 export declare function deleteStoredFileAndDerivatives(originalKey: string, store: StoredFileStore, errorContext: string): Promise<readonly string[]>;
+export declare function deleteFileRefBytes(files: FileContext, row: {
+    readonly storageKey: string;
+}, errorContext: string): Promise<readonly string[]>;

package/dist/derivatives/delete-stored-file.js

@@ -68,3 +68,12 @@ export async function deleteStoredFileAndDerivatives(originalKey, store, errorCo
     }
     return failedKeys;
 }
+// deleteStoredFileAndDerivatives through ctx.files for a key read from a tenant-filtered fileRef
+// row. After a tenant handover the key keeps the previous tenant's prefix, which ref() and list()
+// reject; every key the helper deletes is the original or one of its derivatives.
+export function deleteFileRefBytes(files, row, errorContext) {
+    return deleteStoredFileAndDerivatives(row.storageKey, {
+        list: () => files.listFromFileRef(row),
+        delete: (key) => files.refFromFileRef({ storageKey: key }).delete(),
+    }, errorContext);
+}

package/dist/derivatives/index.d.ts

@@ -1,5 +1,5 @@
 export type { StoredFileStore } from "./delete-stored-file.js";
-export { deleteStoredFileAndDerivatives, listDerivativeKeys } from "./delete-stored-file.js";
+export { deleteFileRefBytes, deleteStoredFileAndDerivatives, listDerivativeKeys, } from "./delete-stored-file.js";
 export type { DerivativesContextDeps } from "./derivatives-context.js";
 export { createDerivativesContext, resolveRenderer } from "./derivatives-context.js";
 export { resolveFieldVariant } from "./field-variants.js";

package/dist/derivatives/index.js

@@ -1,4 +1,4 @@
-export { deleteStoredFileAndDerivatives, listDerivativeKeys } from "./delete-stored-file.js";
+export { deleteFileRefBytes, deleteStoredFileAndDerivatives, listDerivativeKeys, } from "./delete-stored-file.js";
 export { createDerivativesContext, resolveRenderer } from "./derivatives-context.js";
 export { resolveFieldVariant } from "./field-variants.js";
 export { canonicalJson, derivativeListPrefix, isDerivativeKeyOf, parseDerivativeKey, specHash, VARIANT_NAME_PATTERN, variantSuffix, } from "./variant-key.js";

package/dist/engine/boot-validator/entity-handler.js

@@ -929,6 +929,9 @@ export function validateLockedWhen(feature) {
         if (isCiphertextAtRest(field)) {
             throw new Error(`${where} is personal or encrypted — the lock condition is evaluated on the stored value, which is ciphertext. Use a plaintext field.`);
         }
+        if (field.access?.read !== undefined) {
+            throw new Error(`${where} has a read restriction — roles that cannot read it get records without it, and the client would show every record as locked. Drop field access.read or use another field.`);
+        }
         if (!LOCKABLE_FIELD_TYPES.has(field.type)) {
             throw new Error(`${where} has type "${field.type}", which does not store a plain scalar the condition can compare. Use a text, select, boolean, number or reference field.`);
         }

package/dist/engine/boot-validator/query-refs.js

@@ -11,6 +11,18 @@ export function checkQueryRef(queryHandlers, query, buildPrefix) {
         return;
     throw new Error(`${buildPrefix()} query "${query}" ${NOT_REGISTERED_SUFFIX}`);
 }
+// visibleWhen queries are run with an empty payload by the client gate, so a query
+// that requires input would fail on every call and the screen/panel would stay
+// unavailable with no hint.
+function checkVisibleWhenQueryRef(queryHandlers, query, buildPrefix) {
+    checkQueryRef(queryHandlers, query, buildPrefix);
+    const handler = queryHandlers.get(query);
+    // skip: nothing to check for an unknown handler (checkQueryRef already threw) or an input-free query
+    if (handler === undefined || handler.schema.safeParse({}).success)
+        return;
+    throw new Error(`${buildPrefix()} query "${query}" requires input; visibleWhen queries run with an empty payload. ` +
+        "Make the query's input fields optional or use a query without required input.");
+}
 // relatedList is currently only reachable on projectionDetail — screens.ts
 // rejects it outright on entityEdit/actionForm/configEdit (fw#2166). Walking
 // the shared EditLayout uniformly here (instead of excluding those three
@@ -27,7 +39,7 @@ function checkDashboardQueryRefs(queryHandlers, featureName, screenId, screen) {
         if (panel.kind === "custom")
             continue;
         if (panel.visibleWhen !== undefined) {
-            checkQueryRef(queryHandlers, panel.visibleWhen.query, () => `[Feature ${featureName}] Screen "${screenId}" (dashboard) ${panel.kind === "screen" ? "screen-panel" : "panel"} "${panel.id}" visibleWhen`);
+            checkVisibleWhenQueryRef(queryHandlers, panel.visibleWhen.query, () => `[Feature ${featureName}] Screen "${screenId}" (dashboard) ${panel.kind === "screen" ? "screen-panel" : "panel"} "${panel.id}" visibleWhen`);
         }
         if (panel.kind === "screen")
             continue;
@@ -60,7 +72,7 @@ function checkFormFieldQueryRefs(queryHandlers, featureName, screenId, screenTyp
 }
 function checkScreenQueryRefs(queryHandlers, featureName, screenId, screen) {
     if (screen.visibleWhen !== undefined) {
-        checkQueryRef(queryHandlers, screen.visibleWhen.query, () => `[Feature ${featureName}] Screen "${screenId}" (${screen.type}) visibleWhen`);
+        checkVisibleWhenQueryRef(queryHandlers, screen.visibleWhen.query, () => `[Feature ${featureName}] Screen "${screenId}" (${screen.type}) visibleWhen`);
     }
     if (screen.type === "projectionList") {
         checkQueryRef(queryHandlers, screen.query, () => `[Feature ${featureName}] Screen "${screenId}" (projectionList)`);

package/dist/engine/dedupe-features.js

@@ -11,13 +11,40 @@ function sameKeys(a, b) {
     const bKeys = new Set(Object.keys(b ?? {}));
     return aKeys.length === bKeys.size && aKeys.every((key) => bKeys.has(key));
 }
+const KEYED_SURFACE_PROPERTIES = [
+    "entities",
+    "writeHandlers",
+    "queryHandlers",
+    "streamHandlers",
+    "screens",
+    "navs",
+    "jobs",
+    "events",
+    "translations",
+    "configKeys",
+    "notifications",
+    "metrics",
+];
+// Hooks are keyed per phase, then per target: flatten so a hook added under an
+// existing phase still shows up as a difference.
+function hookKeys(feature) {
+    const keys = new Set();
+    for (const [phase, byTarget] of Object.entries(feature.hooks ?? {})) {
+        for (const target of Object.keys(byTarget ?? {}))
+            keys.add(`${phase}/${target}`);
+    }
+    return keys;
+}
+function sameHookKeys(a, b) {
+    const aKeys = hookKeys(a);
+    const bKeys = hookKeys(b);
+    return aKeys.size === bKeys.size && [...aKeys].every((key) => bKeys.has(key));
+}
 // dedupeOptions is a declaration, not proof: two same-named features that both
 // carry `{}` but register different surface must still clash, not silently drop one.
 function sameRegisteredSurface(a, b) {
-    return (sameKeys(a.entities, b.entities) &&
-        sameKeys(a.writeHandlers, b.writeHandlers) &&
-        sameKeys(a.queryHandlers, b.queryHandlers) &&
-        sameKeys(a.streamHandlers, b.streamHandlers));
+    return (KEYED_SURFACE_PROPERTIES.every((property) => sameKeys(a[property], b[property])) &&
+        sameHookKeys(a, b));
 }
 function isInterchangeable(existing, next) {
     if (existing === next)

package/dist/engine/entity-handlers.js

@@ -4,6 +4,7 @@ import { collectReferenceFields, enrichRowWithReferences, enrichWithReferences,
 import { createEventStoreExecutor } from "../db/event-store-executor.js";
 import { buildEntityTable } from "../db/table-builder.js";
 import { acknowledgeConventionCrossTenant, reportConventionCrossTenantUse, } from "../db/tenant-db.js";
+import { InternalError } from "../errors/index.js";
 import { isSystemIdentity } from "../pipeline/system-identity-switch.js";
 import { assertUnreachable } from "../utils/index.js";
 import { PAGED_QUERY_HANDLER_BRAND } from "./define-handler.js";
@@ -49,8 +50,8 @@ const WRITE_VERBS = ["create", "update", "delete", "restore"];
 const QUERY_VERBS = ["list", "detail"];
 const idSchema = z.object({ id: z.uuid() });
 const SYSTEM_ADMIN_ROLE = "SystemAdmin";
-// A write handler with escapeHatch reads/writes rows of every tenant, so only an operator
-// role may reach it — otherwise any tenant-level role holder could mutate foreign tenants.
+// A handler with escapeHatch reads/writes rows of every tenant, so only an operator
+// role may reach it — otherwise any tenant-level role holder could read or mutate foreign tenants.
 function isSystemAdminOnly(access) {
     return ("roles" in access &&
         access.roles.length > 0 &&
@@ -65,8 +66,8 @@ function resolveCrossTenantReason(name, options, kind) {
     const placeholderProblem = codemodPlaceholderReasonProblem(options.escapeHatch.reason);
     if (placeholderProblem !== undefined)
         throw new Error(`"${name}": ${placeholderProblem}`);
-    if (kind === "write" && !isSystemAdminOnly(options.access)) {
-        throw new Error(`"${name}": a write handler with escapeHatch reaches across every tenant, so its access must be SystemAdmin-only ({ roles: ["${SYSTEM_ADMIN_ROLE}"] }); got ${JSON.stringify(options.access)}.`);
+    if (!isSystemAdminOnly(options.access)) {
+        throw new Error(`"${name}": a ${kind} handler with escapeHatch reaches across every tenant, so its access must be SystemAdmin-only ({ roles: ["${SYSTEM_ADMIN_ROLE}"] }); got ${JSON.stringify(options.access)}.`);
     }
     return options.escapeHatch.reason;
 }
@@ -235,7 +236,13 @@ export function defineEntityWriteHandler(name, entity, options) {
         }
         if (typeof rowTenantId !== "string" || rowTenantId === user.tenantId)
             return undefined;
-        return parseTenantId(rowTenantId) ?? undefined;
+        const streamTenantId = parseTenantId(rowTenantId);
+        if (streamTenantId === null) {
+            throw new InternalError({
+                message: `"${name}": row ${String(id)} has tenantId "${rowTenantId}" which is not a TenantId; refusing to append to the wrong stream.`,
+            });
+        }
+        return streamTenantId;
     };
     let schema;
     let handler;
@@ -569,7 +576,7 @@ export function registerEntityCrud(r, entityName, entity, options) {
             ...writeOpts,
             access: requireAccess(verb, options?.verbAccess?.[verb] ?? writeOpts?.access),
             description: options?.descriptions?.[verb] ?? writeOpts?.description,
-            ...(verbAgent !== undefined && { agent: verbAgent }),
+            ...(verbAgent !== undefined && { agent: { ...writeOpts?.agent, ...verbAgent } }),
             ...(excludeFields !== undefined && { excludeFields }),
         };
     };
@@ -579,7 +586,7 @@ export function registerEntityCrud(r, entityName, entity, options) {
             ...readOpts,
             access: requireAccess(verb, options?.verbAccess?.[verb] ?? readOpts?.access),
             description: options?.descriptions?.[verb] ?? readOpts?.description,
-            ...(verbAgent !== undefined && { agent: verbAgent }),
+            ...(verbAgent !== undefined && { agent: { ...readOpts?.agent, ...verbAgent } }),
         };
     };
     if (verbs.create) {

package/dist/engine/index.d.ts

@@ -78,7 +78,7 @@ export { unwrapWorkflowStepError, WorkflowStepError } from "./steps/workflow-ste
 export { WORKFLOW_SYSTEM_EVENT_DEFS } from "./steps/workflow-system-events.js";
 export { ANONYMOUS_ROLE, ANONYMOUS_USER_ID, createAnonymousUser, createSystemUser, SYSTEM_ROLE, SYSTEM_USER_ID, } from "./system-user.js";
 export { assertNotificationVariables, templateVariable, templateVariablesToZod, } from "./template-variables.js";
-export { type EffectiveFeaturesResolver, findTierResolverUsage, isTierResolverPlugin, TENANT_TIER_RESOLVER_EXT, type TierResolverPlugin, type TrialGate, } from "./tier-resolver-extension.js";
+export { type EffectiveFeaturesResolver, findTierResolverUsage, isTierResolverPlugin, requireTierResolverPlugin, TENANT_TIER_RESOLVER_EXT, type TierResolverPlugin, type TrialGate, } from "./tier-resolver-extension.js";
 export { findOverDeepTransferChain, resolveTransferAdjacency as resolveEntityTransferAdjacency, type TransferAdjacency, type TransferEdge, type TransferEdgeLink, } from "./transfer-adjacency.js";
 export { isSystemTenant, isUuid, parseTenantId, SYSTEM_TENANT_ID } from "./types/identifiers.js";
 export type { AccessRule, ActionFormScreenDefinition, ActiveMembership, ActiveMembershipRejection, ActiveMembershipResult, AgentExposure, AgentHandlerHints, AgentRisk, AppContext, AppendEventArgs, AppendEventFn, AuthClaimsContext, AuthClaimsFn, AuthClaimsHookDef, BeforeTransactionPhase, BeforeTransactionResult, BelongsToRelation, BigIntFieldDef, BooleanFieldDef, CamelToKebab, ChatSendFailureCode, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyJsType, ClaimKeyType, ConcurrencyMode, ConfigAccessor, ConfigAccessorFactory, ConfigBacking, ConfigCascade, ConfigCascadeLevel, ConfigDefinition, ConfigEditScreenDefinition, ConfigKeyAccess, ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigMask, ConfigResolver, ConfigScope, ConfigSecretsReader, ConfigSeedDef, ConfigStoredRow, ConfigStoredRowWithSource, ConfigValidateContext, ConfigValidateFn, ConfigValue, ConfigValueSource, ConfigValueWithSource, ContentCollectionDefinition, CreateSeedOptions, CreateTenantSeedOptions, CreateUserSeedOptions, CustomScreenDefinition, CustomScreenRoute, DashboardChartPanel, DashboardCustomPanel, DashboardDateParam, DashboardFeedPanel, DashboardFilterDefinition, DashboardI18nText, DashboardListPanel, DashboardMoneyParam, DashboardPanelDefinition, DashboardPanelVisibility, DashboardProgressListPanel, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DashboardText, DashboardTextParam, DashboardValueFormat, DateFieldDef, DecimalFieldDef, DeleteContext, DeliveryErrorCode, DeliveryFailureCode, DeliverySkipReason, DeriveContext, DerivedFieldDef, DerivedFieldsMap, DerivedValueType, EditExtensionSection, EditFieldPrefill, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EmbeddedListEditSpec, EntityDefinition, EntityEditAction, EntityEditActionPlacement, EntityEditScreenDefinition, EntityId, EntityListExpandableRow, EntityListScreenDefinition, EntityRef, EntityRelations, EscapeHatchAuditSink, EscapeHatchDeclaration, EscapeHatchKind, EscapeHatchReporter, EscapeHatchTarget, EscapeHatchUseEvent, EventDef, ExtensionOptionsArgs, ExtensionOptionsFor, FeatureDefinition, FeatureRegistrar, FieldAccess, FieldCondition, FieldDefinition, FieldFormatRegistry, FieldIconKey, FieldRenderer, FileFieldDef, FilesFieldDef, Findability, FormatSpec, FormWidth, HandlerContext, HasManyRelation, HookMap, ImageFieldDef, ImagesFieldDef, JobBackoff, JobBackoffStrategy, JobContext, JobDefinition, JobHandlerFn, JobTrigger, JobTriggerEvent, JsonbFieldDef, KumikoEntityTypeMap, KumikoEventTypeMap, KumikoExtensionOptionsMap, KumikoHandlerPayloadMap, KumikoHandlerResultMap, LifecycleHookType, ListColumnSpec, ListFacetSpec, ListPaginationMode, ListSortDir, ListSortSpec, LongTextFindability, ManyToManyRelation, MemberReader, MetricNavigate, MetricSpec, MspErrorMode, MspErrorPolicy, MultiSelectFieldDef, MultiStreamApplyFn, MultiStreamProjectionDefinition, NameOrRef, NavDefinition, NavIconKey, NotificationDataFn, NotificationDefinition, NotificationLocalizedTemplate, NotificationRecipientFn, NotificationRecordMapping, NotificationTemplateBody, NotificationTemplateFn, NotificationTemplateMeta, NotifyDeferred, NotifyDelivery, NotifyDeliveryStatus, NotifyDispatched, NotifyFactory, NotifyFn, NotifyJobDispatcher, NotifyOptions, NotifyPriority, NotifyResult, NumberFieldDef, OnDeleteStrategy, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, ParentRefDef, PersonalAnnotations, PersonalAnnotationsLongText, PersonalAnnotationsNoFind, PersonalSubject, PlatformComponent, PluralForms, PostDeleteHookFn, PostSaveHookFn, PreDeleteHookFn, PreparedWriteEvent, PreQueryHookFn, PreSaveHookFn, ProjectionDefinition, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, ProjectionTable, QualifiedEventName, QueryEvent, QueryHandlerDef, QueryHandlerFn, RateLimitPer, RecordHeaderSpec, RecordHeaderSubtitlePart, ReferenceDataDef, Registry, RelationDefinition, ResolvedPiiFlags, RetentionDef, RoleAccessPersonalData, RoleAccessRule, RowAction, RowActionNavigate, RowActionNavigateBase, RowActionWriteHandler, RowFieldExtractor, SaveContext, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenNavSugar, ScreenSlots, SecretKeyDefinition, SecretKeyHandle, SecretMintConfirmStep, SecretMintScreenDefinition, SecretNamespaceDefinition, SecretNamespaceHandle, SecretNamespaceOptions, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, SelectFieldDef, SessionUser, SessionUserOrigin, StreamHandlerDef, StreamHandlerFn, Subscribe, TargetRef, TemplateListVariableDef, TemplateScalarVariableDef, TemplateVariableDef, TemplateVariables, TenantId, TenantWriteTarget, TextFieldDef, ToolbarAction, TranslationEntry, TranslationKeys, TranslationsDef, TranslationValue, TreeAction, TreeActionDef, TreeActionsHandle, TreeChildrenSubscribe, TreeNode, TreeNodeState, UnitKey, UnsafeAppendEventFn, ValidationError, ValidationHookFn, WorkspaceDefinition, WriteEvent, WriteHandlerDef, WriteHandlerFn, WriteResult, } from "./types/index.js";

package/dist/engine/index.js

@@ -71,7 +71,7 @@ export { unwrapWorkflowStepError, WorkflowStepError } from "./steps/workflow-ste
 export { WORKFLOW_SYSTEM_EVENT_DEFS } from "./steps/workflow-system-events.js";
 export { ANONYMOUS_ROLE, ANONYMOUS_USER_ID, createAnonymousUser, createSystemUser, SYSTEM_ROLE, SYSTEM_USER_ID, } from "./system-user.js";
 export { assertNotificationVariables, templateVariable, templateVariablesToZod, } from "./template-variables.js";
-export { findTierResolverUsage, isTierResolverPlugin, TENANT_TIER_RESOLVER_EXT, } from "./tier-resolver-extension.js";
+export { findTierResolverUsage, isTierResolverPlugin, requireTierResolverPlugin, TENANT_TIER_RESOLVER_EXT, } from "./tier-resolver-extension.js";
 export { findOverDeepTransferChain, resolveTransferAdjacency as resolveEntityTransferAdjacency, } from "./transfer-adjacency.js";
 export { isSystemTenant, isUuid, parseTenantId, SYSTEM_TENANT_ID } from "./types/identifiers.js";
 export { DEFAULT_CURRENCIES, DEFAULT_LOCALES, DELIVERY_FAILURE_CODES, DELIVERY_SKIP_REASONS, HookPhases, HTTP_ERROR_CODE_PATTERN, isAgentVisibleScreen, isDeliveryErrorCode, isOpenToAllGranted, resolveAgentExposure, } from "./types/index.js";

package/dist/engine/screen-helpers.d.ts

@@ -34,6 +34,7 @@ export type UnavailableSelectOption = {
 };
 /** Options of a select field that are offered for the given row values, in declaration order. */
 export declare function availableSelectOptions(field: SelectOptionRules, values: Record<string, unknown>): readonly string[];
+export declare function isUnchangedValue(a: unknown, b: unknown): boolean;
 /** Select values that violate a `conditionalOptions` rule. With `previous`, a field is only
  *  checked when it or one of its condition fields changed, so legacy rows stay editable. */
 export declare function findUnavailableSelectOptions(fields: Readonly<Record<string, FieldDefinition>>, values: Record<string, unknown>, previous?: Record<string, unknown>): readonly UnavailableSelectOption[];

package/dist/engine/screen-helpers.js

@@ -126,7 +126,7 @@ export function availableSelectOptions(field, values) {
         return field.options;
     return field.options.filter((option) => rules.every((rule) => !rule.options.includes(option) || evalFieldCondition(rule.when, values)));
 }
-function isSameValue(a, b) {
+export function isUnchangedValue(a, b) {
     return JSON.stringify(a) === JSON.stringify(b);
 }
 /** Select values that violate a `conditionalOptions` rule. With `previous`, a field is only
@@ -141,7 +141,7 @@ export function findUnavailableSelectOptions(fields, values, previous) {
             continue;
         if (previous) {
             const watched = [name, ...def.conditionalOptions.map((rule) => rule.when.field)];
-            if (watched.every((key) => isSameValue(values[key], previous[key])))
+            if (watched.every((key) => isUnchangedValue(values[key], previous[key])))
                 continue;
         }
         const allowed = availableSelectOptions(def, values);

package/dist/engine/steps/_read-source.js

@@ -1,4 +1,4 @@
-import { unsafeRawForDeclaredStep } from "../../db/tenant-db.js";
+import { requestedTenantIds, unsafeRawForDeclaredStep } from "../../db/tenant-db.js";
 import { InternalError } from "../../errors/classes.js";
 import { SYSTEM_TENANT_ID } from "../types/identifiers.js";
 // unsafeRaw fails closed without the handler's escapeHatch (or systemScope) and reports the use.
@@ -25,7 +25,10 @@ export function warnOnNarrowedForeignTenantFilter(ctx, stepKind, stepName, where
     if (requested === undefined)
         return;
     const allowed = [ctx.db.tenantId, SYSTEM_TENANT_ID];
-    const requestedList = Array.isArray(requested) ? requested : [requested];
+    const requestedList = requestedTenantIds(requested);
+    // skip: unrecognised operator form, narrowing cannot be judged.
+    if (requestedList === undefined)
+        return;
     // skip: every requested tenant is within the caller's scope.
     if (requestedList.every((t) => typeof t === "string" && allowed.includes(t)))
         return;

package/dist/engine/tier-resolver-extension.d.ts

@@ -61,4 +61,5 @@ export type TierResolverPlugin = {
  *  plugin shape — the only thing every implementation must provide is the
  *  `build` factory. */
 export declare function isTierResolverPlugin(v: unknown): v is TierResolverPlugin;
+export declare function requireTierResolverPlugin(usage: RegistrarExtensionRegistration): TierResolverPlugin;
 export declare function findTierResolverUsage(features: readonly FeatureDefinition[]): RegistrarExtensionRegistration | undefined;

package/dist/engine/tier-resolver-extension.js

@@ -42,6 +42,12 @@ export const TENANT_TIER_RESOLVER_EXT = "tenantTierResolver";
 export function isTierResolverPlugin(v) {
     return isPlainObject(v) && typeof v["build"] === "function";
 }
+export function requireTierResolverPlugin(usage) {
+    if (!isTierResolverPlugin(usage.options)) {
+        throw new Error("tier-resolver registration options must provide a build() factory");
+    }
+    return usage.options;
+}
 export function findTierResolverUsage(features) {
     for (const feature of features) {
         for (const usage of feature.extensionUsages) {

package/dist/entrypoint/index.d.ts

@@ -3,7 +3,7 @@ import type { AuthRoutesConfig } from "../api/auth-routes.js";
 import type { JwtHelper, JwtKeyring } from "../api/jwt.js";
 import type { ServerOptions } from "../api/server.js";
 import type { SseBroker } from "../api/sse-broker.js";
-import type { PgClient } from "../db/connection.js";
+import type { PgClient, PgListenClient } from "../db/connection.js";
 import type { AppContext, Registry } from "../engine/types/index.js";
 import type { JobRunner, JobRunnerOptions } from "../jobs/job-runner.js";
 import type { Lifecycle } from "../lifecycle/index.js";
@@ -82,4 +82,4 @@ export type AllInOneEntrypoint = Omit<ApiEntrypoint, "mode"> & Omit<WorkerEntryp
 export declare function createApiEntrypoint(options: ApiEntrypointOptions): ApiEntrypoint;
 export declare function createWorkerEntrypoint(options: WorkerEntrypointOptions): WorkerEntrypoint;
 export declare function createAllInOneEntrypoint(options: AllInOneEntrypointOptions): AllInOneEntrypoint;
-export type { PgClient };
+export type { PgClient, PgListenClient };

package/dist/errors/docs-url.js

@@ -20,17 +20,17 @@ function isCoveredByConfig(reason, errorDocs) {
 function errorsUrl(baseUrl, slug) {
     return `${baseUrl}/errors/${encodeURIComponent(slug)}`;
 }
-// A reason the framework documents (or the error code itself) links to the framework docs,
-// overridable via KUMIKO_DOCS_URL. An app's own reason links only where `errorDocs` covers it —
-// otherwise the framework docs would have no page for it.
+// A reason the framework documents (or no reason, or the code itself) links to the framework docs, overridable via
+// KUMIKO_DOCS_URL. An app's own reason links to the app docs where `errorDocs` covers it; every
+// other reason falls back to the framework page of the error code, which exists for each code.
 export function resolveErrorDocsUrl(err, errorDocs) {
     const reason = reasonOf(err);
+    const frameworkBaseUrl = process.env["KUMIKO_DOCS_URL"] ?? DEFAULT_DOCS_BASE_URL;
     if (reason === undefined || reason === err.code || frameworkReasons.has(reason)) {
-        const baseUrl = process.env["KUMIKO_DOCS_URL"] ?? DEFAULT_DOCS_BASE_URL;
-        return errorsUrl(baseUrl, reason ?? err.code);
+        return errorsUrl(frameworkBaseUrl, reason ?? err.code);
     }
     if (errorDocs && isCoveredByConfig(reason, errorDocs)) {
         return errorsUrl(errorDocs.baseUrl, reason);
     }
-    return undefined;
+    return errorsUrl(frameworkBaseUrl, err.code);
 }

package/dist/errors/index.d.ts

@@ -9,7 +9,7 @@ export type { AgentReason, FrameworkReason } from "./reasons.js";
 export { AgentReasons, FrameworkReasons } from "./reasons.js";
 export type { ErrorLogEntry, ErrorResponseBody } from "./serialize.js";
 export { buildErrorLog, serializeError } from "./serialize.js";
-export { subjectErasedConflict } from "./subject-erased.js";
+export { isSubjectErasedConflict, subjectErasedConflict } from "./subject-erased.js";
 export { toKumikoError } from "./to-kumiko-error.js";
 export type { InvalidTransitionDetails } from "./transition-details.js";
 export { buildInvalidTransitionDetails } from "./transition-details.js";

package/dist/errors/index.js

@@ -4,7 +4,7 @@ export { isKumikoError, KumikoError } from "./kumiko-error.js";
 export { memberResolutionReadOnlyDenied } from "./member-resolution.js";
 export { AgentReasons, FrameworkReasons } from "./reasons.js";
 export { buildErrorLog, serializeError } from "./serialize.js";
-export { subjectErasedConflict } from "./subject-erased.js";
+export { isSubjectErasedConflict, subjectErasedConflict } from "./subject-erased.js";
 export { toKumikoError } from "./to-kumiko-error.js";
 export { buildInvalidTransitionDetails } from "./transition-details.js";
 export { failNotFound, failTransition, failUnprocessable, reraiseAsKumikoError, toWriteErrorInfo, writeFailure, } from "./write-error-info.js";

package/dist/errors/subject-erased.d.ts

@@ -1,2 +1,3 @@
 import { ConflictError } from "./classes.js";
 export declare function subjectErasedConflict(cause?: unknown): ConflictError;
+export declare function isSubjectErasedConflict(e: unknown): e is ConflictError;