@cosmicdrift/kumiko-framework 0.335.0 → 0.336.1

package/dist/api/anonymous-live-entities.d.ts

@@ -0,0 +1,2 @@
+import type { Registry } from "../engine/types/index.js";
+export declare function collectAnonymousLiveEntities(registry: Registry): ReadonlySet<string>;

package/dist/api/anonymous-live-entities.js

@@ -0,0 +1,17 @@
+import { hasAccess } from "../engine/access.js";
+import { ANONYMOUS_ROLE } from "../engine/system-user.js";
+const ANONYMOUS_PRINCIPAL = { roles: [ANONYMOUS_ROLE] };
+// Entities an anonymous /api/sse connection may receive change signals for:
+// only those an anonymously callable query declares via liveEntities. No
+// inference from the query name, because a signal carries the id of every
+// row of the entity, including rows that query filters out (drafts).
+export function collectAnonymousLiveEntities(registry) {
+    const entities = new Set();
+    for (const handler of registry.getAllQueryHandlers().values()) {
+        if (!hasAccess(ANONYMOUS_PRINCIPAL, handler.access))
+            continue;
+        for (const entityName of handler.liveEntities ?? [])
+            entities.add(entityName);
+    }
+    return entities;
+}

package/dist/api/index.d.ts

@@ -1,5 +1,6 @@
 export type { SetTenantCookieOptions } from "./anonymous-cookie.js";
 export { deleteTenantCookie, setTenantCookie } from "./anonymous-cookie.js";
+export { collectAnonymousLiveEntities } from "./anonymous-live-entities.js";
 export { LOCALE_HEADER_NAME, NO_ROUTE_MATCH_HEADER_NAME } from "./api-constants.js";
 export type { AnonymousAccessConfig, AnonymousAccessResolved, AuthMiddlewareOptions, AuthSessionChecker, AuthSessionCheckResult, AuthSessionStatus, TenantExists, TenantLifecycleStatusResolver, TenantResolver, TokenVerifier, } from "./auth-middleware.js";
 export { AUTH_COOKIE_NAME, authMiddleware, getUser, PAT_TOKEN_PREFIX, sessionCheckStatus, } from "./auth-middleware.js";
@@ -26,7 +27,7 @@ export type { KumikoServer, ServerOptions } from "./server.js";
 export { buildServer, makeDispatchSystemQuery, makeDispatchSystemWrite } from "./server.js";
 export type { SseBroker, SseClient, SseEvent } from "./sse-broker.js";
 export { createSseBroker } from "./sse-broker.js";
-export { createSseRoute, SSE_HEARTBEAT_INTERVAL_MS } from "./sse-route.js";
+export { createSseRoute, SSE_HEARTBEAT_INTERVAL_MS, type SseRouteOptions } from "./sse-route.js";
 export { generateToken } from "./tokens.js";
 export type { KumikoServeEnv, KumikoServerWebSocket, KumikoWebSocketData, WebSocketUpgradeServer, } from "./websocket-route.js";
 export { createKumikoWebSocketHandler, isWebSocketUpgradeRequest, kumikoWebSocketHandler, WEBSOCKET_BACKPRESSURE_LIMIT_BYTES, WEBSOCKET_DEFAULT_MAX_CONNECTIONS_PER_USER, WEBSOCKET_HEARTBEAT_INTERVAL_MS, WEBSOCKET_MAX_PAYLOAD_BYTES, WEBSOCKET_PENDING_BUFFER_LIMIT_BYTES, WEBSOCKET_REVALIDATION_FAILURE_LIMIT, WEBSOCKET_ROUTE_PATH_PREFIX, } from "./websocket-route.js";

package/dist/api/index.js

@@ -1,4 +1,5 @@
 export { deleteTenantCookie, setTenantCookie } from "./anonymous-cookie.js";
+export { collectAnonymousLiveEntities } from "./anonymous-live-entities.js";
 export { LOCALE_HEADER_NAME, NO_ROUTE_MATCH_HEADER_NAME } from "./api-constants.js";
 export { AUTH_COOKIE_NAME, authMiddleware, getUser, PAT_TOKEN_PREFIX, sessionCheckStatus, } from "./auth-middleware.js";
 export { createAuthRoutes, createInMemoryLoginRateLimiter, createRedisLoginRateLimiter, } from "./auth-routes.js";

package/dist/api/routes.js

@@ -301,7 +301,7 @@ function clientFaultLoggingEnabled() {
     return !FAULT_LOG_SILENCED_LEVELS.has(process.env["LOG_LEVEL"] ?? "");
 }
 // A failing request must leave a trace even when it ends in 4xx — a paid
-// external call that 422s was invisible before (offlot#117). Status, error
+// external call that 422s was invisible before. Status, error
 // code and duration only: message/details/stack can carry submitted values.
 function logClientWarn(message, requestId, type, fields) {
     if (!clientFaultLoggingEnabled()) {

package/dist/api/server.js

@@ -5,7 +5,7 @@ import { buildAppSchema } from "../engine/build-app-schema.js";
 import { EXT_FILE_PROVIDER, EXT_PRINCIPAL_STATUS } from "../engine/extension-names.js";
 import { projectAppSchemaForRoles } from "../engine/project-app-schema-for-roles.js";
 import { runsInLane } from "../engine/run-in.js";
-import { ANONYMOUS_ROLE, createAnonymousUser, createSystemUser } from "../engine/system-user.js";
+import { createAnonymousUser, createSystemUser, isAnonymousSessionUser, } from "../engine/system-user.js";
 import { isFileField, } from "../engine/types/index.js";
 import { createFileContext } from "../files/file-handle.js";
 import { createFileRoutes, readFilesRouteOptions } from "../files/file-routes.js";
@@ -22,6 +22,7 @@ import { createAccessInvalidationEventConsumer, createJobTriggerEventConsumer, c
 import { authEndpointRateLimit, createRateLimitResolver, globalIpRateLimit, } from "../rate-limit/index.js";
 import { deriveSearchAdapterConfig } from "../search/derive-search-adapter-config.js";
 import { assertUnreachable, generateId } from "../utils/index.js";
+import { collectAnonymousLiveEntities } from "./anonymous-live-entities.js";
 import { NO_ROUTE_MATCH_HEADER_NAME, PUBLIC_API_PATHS, Routes } from "./api-constants.js";
 import { authMiddleware, getAuthTokenExpiry, getUser, } from "./auth-middleware.js";
 import { createAuthRoutes } from "./auth-routes.js";
@@ -557,7 +558,9 @@ export function buildServer(options) {
     app.route("/api", createApiRoutes(dispatcher, {
         ...(options.sseHeartbeatMs !== undefined ? { sseHeartbeatMs: options.sseHeartbeatMs } : {}),
     }));
-    app.route("/api", createSseRoute(sseBroker));
+    app.route("/api", createSseRoute(sseBroker, {
+        anonymousLiveEntities: collectAnonymousLiveEntities(options.registry),
+    }));
     // GET /api/schema — the only way a client obtains the AppSchema. Behind
     // jwtGuard (NON_PUBLIC_API_PATHS), so anonymousAccess's synthesised user
     // also gets rejected below — the schema never reaches an unauthenticated
@@ -850,7 +853,7 @@ c, dispatcher) {
 // real, signed-in principal and reject the synthesised anonymousAccess user
 // (SessionUser.roles includes ANONYMOUS_ROLE) the same way.
 function isMissingOrAnonymousUser(user) {
-    return !user || user.roles.includes(ANONYMOUS_ROLE);
+    return !user || isAnonymousSessionUser(user);
 }
 function unauthenticatedResponse(c) {
     return c.json({

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

@@ -21,4 +21,7 @@ import { type SseBroker } from "./sse-broker.js";
  * gegen versehentliches Hochsetzen.
  */
 export declare const SSE_HEARTBEAT_INTERVAL_MS = 15000;
-export declare function createSseRoute(broker: SseBroker): Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
+export type SseRouteOptions = {
+    readonly anonymousLiveEntities: ReadonlySet<string>;
+};
+export declare function createSseRoute(broker: SseBroker, options: SseRouteOptions): Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;

package/dist/api/sse-route.js

@@ -1,6 +1,7 @@
 import { Hono } from "hono";
 import { streamSSE } from "hono/streaming";
 import { tenantChannel } from "../engine/constants.js";
+import { isAnonymousSessionUser } from "../engine/system-user.js";
 import { Routes } from "./api-constants.js";
 import { getUser } from "./auth-middleware.js";
 import { accessInvalidationCredentialFor } from "./sse-broker.js";
@@ -33,13 +34,41 @@ export const SSE_HEARTBEAT_INTERVAL_MS = 15_000;
 function isEntityEventData(data) {
     return typeof data["aggregateType"] === "string";
 }
-// The tenant channel fans out to every member; user-addressed frames
-// (e.g. channel-in-app:event:delivered) would otherwise reach the whole tenant.
-function isAddressedToOtherUser(event, userId) {
+// Whitelist, never a spread: the wire frame is a signal without field
+// values even if a broker or pusher put a payload into event.data.
+function toEntitySignalWire(event, data) {
+    return {
+        id: data["id"],
+        aggregateType: data.aggregateType,
+        eventType: event.type,
+        version: data["version"],
+        createdAt: data["createdAt"],
+    };
+}
+// The tenant channel fans out to every member, so a frame without an entity
+// (e.g. channel-in-app:event:delivered) reaches only its addressee; a frame
+// lacking userId is dropped (fail-closed).
+function isAddressedTo(event, userId) {
     const addressee = event.data["userId"];
-    return typeof addressee === "string" && addressee !== userId;
+    return typeof addressee === "string" && addressee === userId;
+}
+function mayReceiveEntitySignal(user, aggregateType, options) {
+    return !isAnonymousSessionUser(user) || options.anonymousLiveEntities.has(aggregateType);
+}
+function decideWireFrame(event, user, options) {
+    const data = event.data;
+    if (isEntityEventData(data)) {
+        // skip: anonymous connections only get signals for entities an anonymous query declares
+        if (!mayReceiveEntitySignal(user, data.aggregateType, options))
+            return undefined;
+        return { name: data.aggregateType, data: toEntitySignalWire(event, data) };
+    }
+    // skip: frames without an entity belong to their addressee only
+    if (!isAddressedTo(event, user.id))
+        return undefined;
+    return { name: event.type, data };
 }
-export function createSseRoute(broker) {
+export function createSseRoute(broker, options) {
     const route = new Hono();
     route.get(Routes.sse, async (c) => {
         const user = getUser(c);
@@ -56,13 +85,11 @@ export function createSseRoute(broker) {
                 void stream.close();
             };
             const clientId = broker.addClient(channel, (event) => {
-                // skip: user-addressed frames on the shared tenant channel belong to their recipient only
-                if (isAddressedToOtherUser(event, user.id))
+                const frame = decideWireFrame(event, user, options);
+                // skip: decideWireFrame withholds frames this user must not see
+                if (!frame)
                     return;
-                const wireEventName = isEntityEventData(event.data)
-                    ? event.data.aggregateType
-                    : event.type;
-                stream.writeSSE({ event: wireEventName, data: JSON.stringify(event.data) });
+                stream.writeSSE({ event: frame.name, data: JSON.stringify(frame.data) });
             }, closeStream);
             const unsubscribeAccessInvalidation = broker.subscribeAccessInvalidation(user.id, closeStream, accessInvalidationCredentialFor(user));
             let released = false;

package/dist/crypto/event-pii.js

@@ -45,9 +45,9 @@ function resolvePiiStance(eventType) {
 // (user/tenant/self — resolveEventSubject, fw#2801). No-op when the event
 // type is uncatalogued or no subject KMS is configured (plaintext rollout
 // mode — the hard boot gate governs whether that is acceptable). A
-// user-subject field with no resolvable owner (system cron runs,
-// recipient-less skip attempts) leaves the value plaintext: there is no
-// user key to shred. This is the ONLY live-write encrypt path — the backfill
+// user-subject field with an empty owner follows its declared `whenAbsent`
+// (tenant key or acknowledged plaintext) and aborts the append when none is
+// declared. This is the ONLY live-write encrypt path — the backfill
 // catalog branch (`backfill-pii.ts`) resolves through the same
 // resolveEventSubject so a field never ends up encrypted under different
 // subjects depending on which path wrote it.

package/dist/db/blind-index-cleanup.js

@@ -19,6 +19,7 @@ import { executeRawQuery, executeRawQueryRead } from "./queries/raw-sql.js";
 import { columnNamesOf, tableExists } from "./schema-inspection.js";
 export async function nullBlindIndexesForSubject(db, features, subjectKey) {
     const likePattern = subjectCiphertextLikePattern(subjectKey);
+    const candidates = [];
     for (const feature of features.values()) {
         for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
             const lookupable = collectLookupableFields(entity);
@@ -27,26 +28,36 @@ export async function nullBlindIndexesForSubject(db, features, subjectKey) {
             // No featureName prefix — the dispatcher builds entity tables without
             // one (buildEntityTable with no featureName option), the sweep has to
             // hit the same names.
-            const tableName = resolveTableName(entityName, entity, undefined);
-            // Skip entities whose projection was never migrated — same class as
-            // subjectRowExistsInTenant (fw#2348). A throw here runs AFTER eraseKey
-            // in forget-subject and would leave deterministic bidx columns still
-            // linkable (fw#2550).
-            if (!(await tableExists(db, tableName)))
+            candidates.push({ tableName: resolveTableName(entityName, entity, undefined), lookupable });
+        }
+    }
+    // Skip entities whose projection was never migrated — same class as
+    // subjectRowExistsInTenant (fw#2348). A throw here runs AFTER eraseKey
+    // in forget-subject and would leave deterministic bidx columns still
+    // linkable (fw#2550). One batched existence query instead of one
+    // roundtrip per entity.
+    const existing = await existingTableNames(db, candidates.map((c) => c.tableName));
+    for (const { tableName, lookupable } of candidates) {
+        if (!existing.has(tableName))
+            continue;
+        // Same hazard for a migrated table that predates a later-added
+        // lookupable field: skip fields whose columns are missing instead of
+        // aborting the sweep for the remaining ones.
+        const columns = await columnNamesOf(db, tableName);
+        for (const fieldName of lookupable) {
+            const snake = toSnakeCase(fieldName);
+            if (!columns.has(snake) || !columns.has(`${snake}_bidx`))
                 continue;
-            // Same hazard for a migrated table that predates a later-added
-            // lookupable field: skip fields whose columns are missing instead of
-            // aborting the sweep for the remaining ones.
-            const columns = await columnNamesOf(db, tableName);
-            for (const fieldName of lookupable) {
-                const snake = toSnakeCase(fieldName);
-                if (!columns.has(snake) || !columns.has(`${snake}_bidx`))
-                    continue;
-                await executeRawQuery(db, `UPDATE ${quoteIdent(tableName)} SET ${quoteIdent(`${snake}_bidx`)} = NULL WHERE ${quoteIdent(snake)} LIKE $1`, [likePattern]);
-            }
+            await executeRawQuery(db, `UPDATE ${quoteIdent(tableName)} SET ${quoteIdent(`${snake}_bidx`)} = NULL WHERE ${quoteIdent(snake)} LIKE $1`, [likePattern]);
         }
     }
 }
+async function existingTableNames(db, tableNames) {
+    if (tableNames.length === 0)
+        return new Set();
+    const rows = await executeRawQueryRead(db, `SELECT t.name FROM unnest($1::text[]) AS t(name) WHERE to_regclass(quote_ident(t.name)) IS NOT NULL`, [tableNames]);
+    return new Set(rows.map((r) => r.name));
+}
 // Tenant-scope oracle for crypto-shredding's forget-subject (mh#349): a
 // "user"-kind subject id is often not a real user (share-token recipient,
 // email subscriber, ...) — those entities self-own their PII (`pii: true`,

package/dist/db/event-store-executor-read.js

@@ -568,8 +568,12 @@ export function createReadVerbs(ctx) {
                 : referenceSortExpr !== undefined
                     ? referenceSortExpr(params)
                     : colSql(sortField);
-            const orderByClause = sortSql !== undefined
-                ? ` ORDER BY ${sortSql} ${sortDescending ? "DESC" : "ASC"}, ${colSql("id")} ASC`
+            // The projected label alias is ordered by directly, so Postgres evaluates
+            // the correlated subquery once per row instead of once for ORDER BY and
+            // once for the SELECT list.
+            const orderBySortSql = referenceSortExpr !== undefined ? `"${SORT_LABEL_ALIAS}"` : sortSql;
+            const orderByClause = orderBySortSql !== undefined
+                ? ` ORDER BY ${orderBySortSql} ${sortDescending ? "DESC" : "ASC"}, ${colSql("id")} ASC`
                 : ` ORDER BY ${colSql("id")} ASC`;
             const useOffset = !payload.cursor && offset > 0;
             const offsetClause = useOffset ? ` OFFSET ${offset}` : "";

package/dist/engine/boot-validator/access-declarations.js

@@ -53,7 +53,8 @@ function validateEscapeHatchReason(feature, kind, handlerName, escapeHatch) {
         return;
     throw new Error(`[Feature ${feature.name}] ${kind} handler "${handlerName}" declares ` +
         `{ escapeHatch: { reason: "" } } — the reason must be a non-empty string ` +
-        "explaining why this handler needs db.global() write access or a SYSTEM identity switch.");
+        "explaining why this handler needs db.global() write access, a SYSTEM identity switch " +
+        "or a cross-tenant ctx.queryProjection({ unsafeAllTenants: true }) read.");
 }
 function validatePersonalDataOnlyOnWrite(feature, kind, handlerName, access) {
     // skip: write handlers may declare personalData, or it wasn't declared here

package/dist/engine/boot-validator/query-output-columns.js

@@ -164,6 +164,15 @@ function checkDashboardStatPanelFields(queryHandlers, featureName, screenId, pan
     checkPanelField("deltaDirectionField", panel.deltaDirectionField);
     checkPanelField("deltaToneField", panel.deltaToneField);
 }
+// visibleWhen reads a flat record like stat panels; a typo'd field would hide
+// the panel forever without any message.
+function checkScreenPanelVisibleWhenField(queryHandlers, featureName, screenId, panel) {
+    // skip: panel is always visible, no field to check
+    if (panel.visibleWhen === undefined)
+        return;
+    const { query, field } = panel.visibleWhen;
+    checkFieldExists(getZodObjectShape(queryHandlers.get(query)?.outputSchema), field, () => `[Feature ${featureName}] Screen "${screenId}" (dashboard) screen-panel "${panel.id}" visibleWhen references field "${field}" which is not present in query "${query}"'s outputSchema.`);
+}
 function checkDashboardOutputFields(queryHandlers, featureName, screenId, screen) {
     for (const panel of screen.panels) {
         if (panel.kind === "stat") {
@@ -174,6 +183,9 @@ function checkDashboardOutputFields(queryHandlers, featureName, screenId, screen
                 checkDashboardStatPanelFields(queryHandlers, featureName, screenId, stat);
             }
         }
+        else if (panel.kind === "screen") {
+            checkScreenPanelVisibleWhenField(queryHandlers, featureName, screenId, panel);
+        }
         else if (panel.kind === "list") {
             const rowShape = resolveListRowShape(queryHandlers, panel.query, `[Feature ${featureName}] Screen "${screenId}" (dashboard) panel "${panel.id}"`);
             for (const column of panel.columns) {

package/dist/engine/boot-validator/screens.js

@@ -690,20 +690,30 @@ function validateSecretMintConfirm(feature, screenId, screen, allWriteHandlerQns
         }
     }
 }
-// nav.screen is a full QN (cross-feature), so a standalone r.nav() pointing
-// at `targetQn` must be found by scanning every feature's nav entries and actions.
-function hasStandaloneNavEntry(targetQn, featureMap) {
+// validateScreenHasNavArea runs once per screen; the index is built once per
+// featureMap (immutable during boot) instead of re-scanning every feature each call.
+const navAreaIndexByFeatureMap = new WeakMap();
+function navTargetScreenQns(nav) {
+    return [nav.screen, nav.createAction?.screen, ...(nav.actions ?? []).map((a) => a.screen)].filter((qn) => qn !== undefined);
+}
+function getNavAreaIndex(featureMap) {
+    const cached = navAreaIndexByFeatureMap.get(featureMap);
+    if (cached !== undefined)
+        return cached;
+    const navTargetQns = new Set();
+    const allScreens = [];
+    let anyNavRegistered = false;
     for (const f of featureMap.values()) {
+        allScreens.push(...Object.values(f.screens));
         for (const nav of Object.values(f.navs)) {
-            if (nav.screen === targetQn)
-                return true;
-            if (nav.createAction?.screen === targetQn)
-                return true;
-            if (nav.actions?.some((a) => a.screen === targetQn))
-                return true;
+            anyNavRegistered = true;
+            for (const qn of navTargetScreenQns(nav))
+                navTargetQns.add(qn);
         }
     }
-    return false;
+    const index = { anyNavRegistered, navTargetQns, allScreens };
+    navAreaIndexByFeatureMap.set(featureMap, index);
+    return index;
 }
 // Every screen must resolve nav via `nav`, `r.nav()`, a parent list, or
 // `dormant: true`. Skipped when the composed set has no nav entries at all.
@@ -714,16 +724,15 @@ function validateScreenHasNavArea(feature, screenId, screen, featureMap) {
     // skip: explicitly opted out via `dormant: true`.
     if (screen.dormant === true)
         return;
-    const anyNavRegistered = [...featureMap.values()].some((f) => Object.keys(f.navs).length > 0);
+    const { anyNavRegistered, navTargetQns, allScreens } = getNavAreaIndex(featureMap);
     // skip: no nav entries exist anywhere in the composed set — a feature/
     // recipe/test fixture booted without an app shell, not an omission.
     if (!anyNavRegistered)
         return;
     const targetQn = qualifyEntityName(feature.name, "screen", screenId);
     // skip: a standalone r.nav() elsewhere already points at this screen.
-    if (hasStandaloneNavEntry(targetQn, featureMap))
+    if (navTargetQns.has(targetQn))
         return;
-    const allScreens = [...featureMap.values()].flatMap((f) => Object.values(f.screens));
     // skip: resolves to a parent list via listScreenId/rowAction-target/same-entity.
     if (resolveNavParentScreen(allScreens, screen, (s) => s.id) !== undefined)
         return;

package/dist/engine/build-app-schema.js

@@ -38,7 +38,9 @@ export function buildAppSchema(registry, options = {}) {
     ]);
     const encryptedConfigKeyQns = collectEncryptedConfigKeyQns(registry);
     for (const [featureName, feature] of registry.features) {
-        const navs = Object.values(feature.navs);
+        // r.nav() may carry explicit `undefined` optionals; drop them so the
+        // schema stays free of non-JSON-safe values.
+        const navs = Object.values(feature.navs).map((nav) => Object.fromEntries(Object.entries(nav).filter(([, value]) => value !== undefined)));
         // The nav entry alone doesn't say which kind a collection lists, so the
         // client can't derive its tree provider from `navs` — project the
         // collections separately, with the nav QN already qualified.
@@ -430,7 +432,8 @@ function projectField(fieldDef) {
         out["multiple"] = def["multiple"];
     // MultiSelect: display picks checkboxes vs. combobox in the renderer,
     // columns/maxRows size the checkbox grid — without these the renderer
-    // always falls back to the combobox (fw#2494).
+    // always falls back to the combobox (fw#2494). Select: display picks
+    // "radio" | "dropdown" the same way.
     if (typeof def["display"] === "string")
         out["display"] = def["display"];
     if (typeof def["columns"] === "number")

package/dist/engine/create-app.js

@@ -17,7 +17,16 @@ function inlineFormFieldMaps(screen) {
 function validateLiteralCurrencyCode(where, field, currencies) {
     // @cast-boundary schema-walk — feature-config inspection (Author may circumvent type-check)
     const shape = field;
-    if (shape.type === "money" && shape.currency?.kind === "literal") {
+    // skip: not a money field, or no currency source declared; nothing to validate.
+    if (shape.type !== "money" || shape.currency === undefined)
+        return;
+    // An unknown kind would project through to the renderer, which silently falls
+    // back to entity.defaultCurrency instead of failing.
+    if (shape.currency.kind !== "literal" && shape.currency.kind !== "tenant") {
+        throw new Error(`${where} declares an unknown currency kind ${JSON.stringify(shape.currency.kind)}. ` +
+            `Expected { kind: "tenant" } or { kind: "literal", code }.`);
+    }
+    if (shape.currency.kind === "literal") {
         const code = shape.currency.code;
         if (typeof code !== "string" || !currencies.includes(code)) {
             throw new Error(`${where} declares currency: { kind: "literal", code: ${JSON.stringify(code)} } which is ` +

package/dist/engine/define-handler.js

@@ -70,11 +70,9 @@ export function defineQueryHandler(def,
     return def;
 }
 // Runtime marker set only by definePagedQueryHandler. A plain
-// defineQueryHandler-built object never carries it. Kept as a type-level
-// signal (fw#2216) even though no validator gates on it — QueryHandlerDef
-// has no output schema, so a boot check can't distinguish "returns
-// PagedRows" from "doesn't" without running the handler; the actual
-// enforcement is a runtime shape guard in the renderer (kumiko-screen.tsx).
+// defineQueryHandler-built object never carries it. query-output-columns.ts
+// reads it to gate the paged envelope check on outputSchema; the renderer's
+// runtime shape guard (kumiko-screen.tsx) remains as a second line.
 //
 // A string key, not a Symbol: bundled-features imports this module through
 // the package's "@cosmicdrift/kumiko-framework/engine" subpath (symlinked

package/dist/engine/extension-names.d.ts

@@ -101,6 +101,10 @@ export declare const EXT_DERIVATIVE_PUBLIC_PREDICATE: "derivativePublicPredicate
  * an image silently rendered without its QR would look correct while being
  * wrong.
  *
+ * `resolve()` runs on every `variant()` call — including cache hits on the
+ * anonymous public route — because the spec hash needs the resolved value.
+ * It must be cheap or cache its own lookups.
+ *
  * Registered/consumed by: `file-derivatives`'s `variant()`
  * (derivatives-context.ts), before the variant's spec hash is computed.
  */

package/dist/engine/extension-names.js

@@ -130,6 +130,10 @@ export const EXT_DERIVATIVE_PUBLIC_PREDICATE = "derivativePublicPredicate";
  * an image silently rendered without its QR would look correct while being
  * wrong.
  *
+ * `resolve()` runs on every `variant()` call — including cache hits on the
+ * anonymous public route — because the spec hash needs the resolved value.
+ * It must be cheap or cache its own lookups.
+ *
  * Registered/consumed by: `file-derivatives`'s `variant()`
  * (derivatives-context.ts), before the variant's spec hash is computed.
  */

package/dist/engine/feature-ast/extractors/handlers.js

@@ -44,6 +44,7 @@ const QUERY_HANDLER_KEY_KINDS = {
     agent: "modeled",
     rateLimit: "modeled",
     outputSchema: "opaque",
+    liveEntities: "opaque",
     escapeHatch: "modeled",
 };
 const STREAM_HANDLER_KEY_KINDS = {

package/dist/engine/feature-entity-handlers.d.ts

@@ -25,6 +25,7 @@ export declare function buildEntityHandlerMethods<TName extends string>(state: F
         access: AccessRule;
         rateLimit?: RateLimitDeclaration;
         outputSchema?: ZodType;
+        liveEntities?: readonly string[];
         description?: string;
         agent?: AgentHandlerHints;
         escapeHatch?: EscapeHatchDeclaration;

package/dist/engine/feature-entity-handlers.js

@@ -146,6 +146,7 @@ export function buildEntityHandlerMethods(state, name) {
                     ...agentSlots(def),
                     ...(def.rateLimit && { rateLimit: def.rateLimit }),
                     ...(def.outputSchema && { outputSchema: def.outputSchema }),
+                    ...(def.liveEntities && { liveEntities: def.liveEntities }),
                     ...(def.escapeHatch && { escapeHatch: def.escapeHatch }),
                     // Carry the definePagedQueryHandler brand through — this rebuild
                     // drops any field not explicitly listed.
@@ -167,6 +168,7 @@ export function buildEntityHandlerMethods(state, name) {
                 ...agentSlots(inline.options),
                 ...(inline.options.rateLimit && { rateLimit: inline.options.rateLimit }),
                 ...(inline.options.outputSchema && { outputSchema: inline.options.outputSchema }),
+                ...(inline.options.liveEntities && { liveEntities: inline.options.liveEntities }),
                 ...(inline.options.escapeHatch && { escapeHatch: inline.options.escapeHatch }),
             };
             tryMapEntity(state, name, nameOrDef);

package/dist/engine/registry-validate.d.ts

@@ -17,6 +17,7 @@ export declare function resolveNotificationTriggersAndRegisterHooks(state: Regis
 export declare function validateLifecycleHookTargets(state: RegistryState): void;
 export declare function validateEntityHookTargets(state: RegistryState, features: readonly FeatureDefinition[]): void;
 export declare function validateJobTriggers(state: RegistryState): void;
+export declare function validateLiveEntities(state: RegistryState): void;
 export declare function validateBootGates(state: RegistryState): void;
 export declare function validateJobBackoff(state: RegistryState): void;
 export declare function validateExtensionUsageTargets(state: RegistryState): void;

package/dist/engine/registry-validate.js

@@ -568,6 +568,15 @@ export function validateJobTriggers(state) {
         }
     }
 }
+export function validateLiveEntities(state) {
+    for (const [handlerQn, handler] of state.queryHandlerMap) {
+        for (const entityName of handler.liveEntities ?? []) {
+            if (state.entityMap.has(entityName))
+                continue;
+            throw new Error(`Query handler "${handlerQn}" declares liveEntities "${entityName}" but no entity with that name is registered`);
+        }
+    }
+}
 export function validateBootGates(state) {
     // Boot gates run inline in JobRunner.start(), which has neither the
     // per-tenant fan-out (that re-enqueues) nor the sequential lock's
@@ -582,6 +591,11 @@ export function validateBootGates(state) {
         if (jobDef.concurrency === "sequential") {
             throw new Error(`Job "${jobName}" cannot combine bootGate with concurrency "sequential"`);
         }
+        // The gate already runs inline each start; runOnBoot would enqueue the same
+        // handler again under the same boot job id (runs twice, shared bull_job_id).
+        if (jobDef.runOnBoot) {
+            throw new Error(`Job "${jobName}" cannot combine bootGate with runOnBoot`);
+        }
     }
 }
 export function validateJobBackoff(state) {

package/dist/engine/registry.js

@@ -3,7 +3,7 @@ import { dedupeFeatures } from "./dedupe-features.js";
 import { buildRegistryFacade } from "./registry-facade.js";
 import { populateClaimsAndAuth, populateConfigKeys, populateEvents, populateExtensionsAndSeeds, populateFeatureCore, populateHandlers, populateHooks, populateJobsAndNotifications, populateMetricsAndSecrets, populateProjectionsAndTables, populateScreensNavWorkspaces, populateTranslations, } from "./registry-ingest.js";
 import { createInitialState } from "./registry-state.js";
-import { applyExtensionUsages, autoWireSoftDeleteJobs, buildEventUpcasterChains, buildImplicitProjections, buildIncomingRelations, buildSearchableSortableCaches, computeHasRateLimitedHandler, finalizeWorkspaceNavMembership, populateHandlerEntityMappings, publishEventPiiCatalog, resolveNotificationTriggersAndRegisterHooks, validateBootGates, validateEntityHookTargets, validateEventMigrationVersions, validateExtensionSelectors, validateExtensionUsageTargets, validateFieldAccessHandlersAreEntityMapped, validateJobBackoff, validateJobTriggers, validateLifecycleHookTargets, validateProjectionApplyKeys, validateRelationTargetsExist, validateRequiredFeatures, } from "./registry-validate.js";
+import { applyExtensionUsages, autoWireSoftDeleteJobs, buildEventUpcasterChains, buildImplicitProjections, buildIncomingRelations, buildSearchableSortableCaches, computeHasRateLimitedHandler, finalizeWorkspaceNavMembership, populateHandlerEntityMappings, publishEventPiiCatalog, resolveNotificationTriggersAndRegisterHooks, validateBootGates, validateEntityHookTargets, validateEventMigrationVersions, validateExtensionSelectors, validateExtensionUsageTargets, validateFieldAccessHandlersAreEntityMapped, validateJobBackoff, validateJobTriggers, validateLifecycleHookTargets, validateLiveEntities, validateProjectionApplyKeys, validateRelationTargetsExist, validateRequiredFeatures, } from "./registry-validate.js";
 // This is where the magic happens. By "magic" I mean: precomputed maps.
 // I build everything once at boot (hooks, relations, searchable fields, ...)
 // so nothing has to iterate over objects at runtime. O(1) instead of O(n*m).
@@ -43,6 +43,7 @@ export function createRegistry(rawFeatures) {
     validateEntityHookTargets(state, features);
     validateJobTriggers(state);
     validateBootGates(state);
+    validateLiveEntities(state);
     validateJobBackoff(state);
     validateExtensionUsageTargets(state);
     computeHasRateLimitedHandler(state);

package/dist/engine/steps/_event-match.js

@@ -5,14 +5,16 @@
 function isRecord(value) {
     return typeof value === "object" && value !== null;
 }
+// A missing path must stay distinguishable from a present-but-undefined value:
+// `ne` would otherwise match events that lack the field entirely.
 function resolvePath(payload, path) {
     let current = payload;
     for (const segment of path) {
-        if (!isRecord(current))
-            return undefined;
+        if (!isRecord(current) || !Object.hasOwn(current, segment))
+            return { found: false };
         current = current[segment];
     }
-    return current;
+    return { found: true, value: current };
 }
 function compareOrdered(actual, expected, kind) {
     if (typeof actual === "number" && typeof expected === "number") {
@@ -73,6 +75,12 @@ function evaluateOp(op, actual) {
 function malformed(what) {
     return new Error(`Malformed EventMatch: ${what}`);
 }
+function evaluateExprAtom(op, resolved) {
+    // Evaluate before checking `found` so a malformed op still throws on a
+    // payload that lacks the path.
+    const matched = evaluateOp(op, resolved.found ? resolved.value : undefined);
+    return resolved.found && matched;
+}
 function evaluateExpr(expr, payload) {
     if (!isRecord(expr))
         throw malformed("expr is not an object");
@@ -90,7 +98,7 @@ function evaluateExpr(expr, payload) {
                 throw malformed(`"atom" expr has no "path" array`);
             if (!isRecord(expr.op))
                 throw malformed(`"atom" expr has no "op" object`);
-            return evaluateOp(expr.op, resolvePath(payload, expr.path));
+            return evaluateExprAtom(expr.op, resolvePath(payload, expr.path));
         default: {
             const unrecognized = expr;
             throw new Error(`Unknown EventMatchExpr kind "${unrecognized.kind}"`);

package/dist/engine/system-user.d.ts

@@ -5,4 +5,5 @@ export declare const SYSTEM_ROLE: "system";
 export declare function createSystemUser(tenantId: TenantId, extraRoles?: readonly string[]): SessionUser;
 export declare const ANONYMOUS_USER_ID = "anonymous";
 export declare const ANONYMOUS_ROLE: "anonymous";
+export declare function isAnonymousSessionUser(user: Pick<SessionUser, "roles">): boolean;
 export declare function createAnonymousUser(tenantId: TenantId): SessionUser;

package/dist/engine/system-user.js

@@ -20,6 +20,9 @@ export function createSystemUser(tenantId, extraRoles = []) {
 // custom roles.
 export const ANONYMOUS_USER_ID = "anonymous";
 export const ANONYMOUS_ROLE = "anonymous";
+export function isAnonymousSessionUser(user) {
+    return user.roles.includes(ANONYMOUS_ROLE);
+}
 export function createAnonymousUser(tenantId) {
     return {
         id: ANONYMOUS_USER_ID,