@cosmicdrift/kumiko-framework 0.336.1 → 0.337.1

package/dist/errors/classes.js

@@ -42,6 +42,21 @@ export class AccessDeniedError extends KumikoError {
         });
     }
 }
+// A caller without a signed-in principal (the synthesised anonymousAccess
+// user) hit a handler that needs one. 401, not 403: an expired auth cookie is
+// dropped by the browser, so this is how a lapsed session reaches the server.
+export class UnauthenticatedError extends KumikoError {
+    code = "unauthenticated";
+    httpStatus = 401;
+    constructor(opts) {
+        super({
+            message: opts?.message ?? "this handler requires a signed-in user",
+            i18nKey: "auth.errors.missingToken",
+            ...(opts?.details !== undefined && { details: opts.details }),
+            ...(opts?.cause && { cause: opts.cause }),
+        });
+    }
+}
 export class NotFoundError extends KumikoError {
     code = "not_found";
     httpStatus = 404;

package/dist/errors/index.d.ts

@@ -1,5 +1,5 @@
 export type { FeatureDisabledDetails, FieldIssue, NotFoundDetails, PreconditionFailedDetails, RateLimitDetails, UnconfiguredDetails, UniqueViolationDetails, UnprocessableOpts, ValidationDetails, VersionConflictDetails, } from "./classes.js";
-export { AccessDeniedError, ConflictError, FeatureDisabledError, IdempotentReplayError, InternalError, NotFoundError, PreconditionFailedError, RateLimitError, UnconfiguredError, UniqueViolationError, UnprocessableError, ValidationError, VersionConflictError, } from "./classes.js";
+export { AccessDeniedError, ConflictError, FeatureDisabledError, IdempotentReplayError, InternalError, NotFoundError, PreconditionFailedError, RateLimitError, UnauthenticatedError, UnconfiguredError, UniqueViolationError, UnprocessableError, ValidationError, VersionConflictError, } from "./classes.js";
 export type { ErrorCtorInput, ErrorOpts } from "./kumiko-error.js";
 export { isKumikoError, KumikoError } from "./kumiko-error.js";
 export { memberResolutionReadOnlyDenied } from "./member-resolution.js";

package/dist/errors/index.js

@@ -1,4 +1,4 @@
-export { AccessDeniedError, ConflictError, FeatureDisabledError, IdempotentReplayError, InternalError, NotFoundError, PreconditionFailedError, RateLimitError, UnconfiguredError, UniqueViolationError, UnprocessableError, ValidationError, VersionConflictError, } from "./classes.js";
+export { AccessDeniedError, ConflictError, FeatureDisabledError, IdempotentReplayError, InternalError, NotFoundError, PreconditionFailedError, RateLimitError, UnauthenticatedError, UnconfiguredError, UniqueViolationError, UnprocessableError, ValidationError, VersionConflictError, } from "./classes.js";
 export { isKumikoError, KumikoError } from "./kumiko-error.js";
 export { memberResolutionReadOnlyDenied } from "./member-resolution.js";
 export { AgentReasons, FrameworkReasons } from "./reasons.js";

package/dist/i18n/required-surface-keys.js

@@ -144,6 +144,9 @@ function pushRelatedListSectionKeys(out, section) {
     }
     for (const action of section.rowActions ?? [])
         pushRowActionKeys(out, action);
+    pushKey(out, section.groupBy?.label);
+    for (const label of Object.values(section.groupBy?.labels ?? {}))
+        pushKey(out, label);
 }
 function pushExpandableRowKeys(out, section) {
     pushRelatedListSectionKeys(out, section);
@@ -330,11 +333,6 @@ export function requiredKeysFromScreen(featureName, screen, options = {}) {
                 }
                 if (section.kind === "relatedList") {
                     pushRelatedListSectionKeys(out, section);
-                    if (section.groupBy !== undefined) {
-                        pushKey(out, section.groupBy.label);
-                        for (const label of Object.values(section.groupBy.labels ?? {}))
-                            pushKey(out, label);
-                    }
                     continue;
                 }
                 if (isWriteFormEditSection(section)) {

package/dist/migrations/pending-rebuilds.d.ts

@@ -1,6 +1,7 @@
 import type { DbConnection } from "../db/connection.js";
 import type { Registry } from "../engine/types/index.js";
 import type { JobRunner } from "../jobs/index.js";
+import type { Logger } from "../logging/types.js";
 import { type RebuildResult } from "../pipeline/index.js";
 export declare const pendingRebuildsTable: import("@cosmicdrift/kumiko-types/schema-table-types").SchemaTable;
 export declare function createPendingRebuildsTable(db: DbConnection): Promise<void>;
@@ -56,6 +57,7 @@ export declare function rebuildProjectionOrMultiStream(name: string, deps: {
     readonly errorPolicy?: {
         readonly skipApplyErrors?: boolean;
     };
+    readonly logger?: Pick<Logger, "error"> & Partial<Pick<Logger, "warn" | "debug">>;
 }): Promise<RebuildResult>;
 /** Logs a finished queue drain and throws when any projection failed; the
  *  failed tables stay queued. Shared by every `schema apply` entry point so the

package/dist/migrations/pending-rebuilds.js

@@ -72,6 +72,9 @@ export async function clearPendingRebuilds(db, rows) {
 export async function rebuildProjectionOrMultiStream(name, deps) {
     const { db, registry, signal, errorPolicy } = deps;
     if (registry.getAllMultiStreamProjections().has(name)) {
+        if (errorPolicy?.skipApplyErrors === true) {
+            createFallbackLogger("migrations:pending-rebuilds", deps.logger).warn(`skipApplyErrors ignored for multi-stream projection "${name}"; declare msp.errorMode.rebuild instead`, { projection: name });
+        }
         return rebuildMultiStreamProjection(name, {
             db,
             registry,

package/dist/pipeline/dispatch-query.js

@@ -1,8 +1,9 @@
 import { hasAccess } from "../engine/access.js";
 import { filterReadFields } from "../engine/field-access.js";
-import { AccessDeniedError, NotFoundError, validationErrorFromZod } from "../errors/index.js";
+import { NotFoundError, validationErrorFromZod } from "../errors/index.js";
 import { assertNoSecretLeak } from "../secrets/index.js";
 import { buildHandlerContext, enforceRateLimit, ensureFeatureEnabled, isMemberResolutionPrincipal, runHandlerInstrumented, } from "./dispatch-shared.js";
+import { handlerAccessError } from "./handler-access-error.js";
 import { runInMemberReadOnlyTransaction } from "./member-read-only-transaction.js";
 // Standalone query execution — used by the public dispatcher.query() and
 // by ctx.query/ctx.queryAs inside handlers. Runs the handler, applies
@@ -34,10 +35,7 @@ async function executeQueryInner(ctx, type, payload, user, origin, tx) {
     // so in normal boots this branch shouldn't fire — the guard is belt-and-
     // suspenders in case a handler sneaks through (e.g. runtime injection).
     if (!hasAccess(user, handler.access)) {
-        throw new AccessDeniedError({
-            message: `access denied for ${type}`,
-            details: { handler: type },
-        });
+        throw handlerAccessError(user, type);
     }
     const parsed = handler.schema.safeParse(payload);
     if (!parsed.success) {

package/dist/pipeline/dispatch-stream.js

@@ -3,6 +3,7 @@ import { hasAccess } from "../engine/access.js";
 import { AccessDeniedError, memberResolutionReadOnlyDenied, NotFoundError, validationErrorFromZod, } from "../errors/index.js";
 import { assertNoSecretLeak } from "../secrets/index.js";
 import { buildHandlerContext, enforceRateLimit, ensureFeatureEnabled, isMemberResolutionPrincipal, runStreamInstrumented, } from "./dispatch-shared.js";
+import { handlerAccessError } from "./handler-access-error.js";
 // Standalone stream execution — used by the public dispatcher.stream().
 // Chunk-by-chunk analog of executeQuery: same gate order (feature → rate-
 // limit → access → validation → handler), but yields incrementally instead
@@ -25,10 +26,7 @@ async function* executeStreamInner(ctx, type, payload, user, origin) {
     await ensureFeatureEnabled(ctx, type, user.tenantId);
     await enforceRateLimit(ctx, handler.rateLimit, type, user, registry.isHandlerSystemScoped(type));
     if (!hasAccess(user, handler.access)) {
-        throw new AccessDeniedError({
-            message: `access denied for ${type}`,
-            details: { handler: type },
-        });
+        throw handlerAccessError(user, type);
     }
     const parsed = handler.schema.safeParse(payload);
     if (!parsed.success) {

package/dist/pipeline/dispatch-write.js

@@ -13,6 +13,7 @@ import { AccessDeniedError, FrameworkReasons, InternalError, isKumikoError, memb
 import { assertNoSecretLeak } from "../secrets/index.js";
 import { buildHandlerContext, CONFIG_WRITE_RESET_TYPE, CONFIG_WRITE_SET_TYPE, checkFeatureEnabled, enforceRateLimit, isMemberResolutionPrincipal, resolveDbSource, runHandlerInstrumented, TENANT_TIMEZONE_CONFIG_KEY, } from "./dispatch-shared.js";
 import { describeShape, extractNestedSpecs, isLifecycleResult, isWriteResultShape, prefixValidationPath, wrapToKumiko, } from "./dispatcher-utils.js";
+import { handlerAccessError } from "./handler-access-error.js";
 import { runProjections } from "./projections-runner.js";
 function getTable(ctx, entityName) {
     const { registry, tableCache } = ctx;
@@ -322,10 +323,7 @@ async function executeWriteInner(ctx, type, payload, user, origin, tx, afterComm
     // so in normal boots this branch shouldn't fire — the guard is belt-and-
     // suspenders in case a handler sneaks through (e.g. runtime injection).
     if (!hasAccess(user, handler.access)) {
-        return writeFailure(new AccessDeniedError({
-            message: `access denied for ${type}`,
-            details: { handler: type },
-        }));
+        return writeFailure(handlerAccessError(user, type));
     }
     const parsed = handler.schema.safeParse(payload);
     if (!parsed.success) {

package/dist/pipeline/event-dispatcher-delivery.d.ts

@@ -67,5 +67,4 @@ export type PersistedConsumerOutcome = DeliveryOutcome & {
     readonly pendingGaps: readonly PendingGapEntry[];
 };
 export declare function persistConsumerOutcome(tx: DbTx, name: string, instanceId: string, outcome: PersistedConsumerOutcome): Promise<void>;
-export declare function persistConsumerPassFailure(tx: DbTx, name: string, instanceId: string, errorMessage: string): Promise<void>;
 export declare function emitLagFromTx(tx: DbTx, consumerName: string, instanceId: string, cursor: bigint, meter: Meter): Promise<void>;

package/dist/pipeline/event-dispatcher-delivery.js

@@ -4,7 +4,7 @@
 // resolve against (same #1438 dual-package-hazard pattern as event-store.ts).
 import { Temporal as TemporalPolyfill } from "temporal-polyfill";
 import { requestContext } from "../api/request-context.js";
-import { insertConsumerIfAbsent, markConsumerProcessing, rearmDeadConsumer, recordConsumerPassFailure, selectConsumerForUpdate, selectConsumerForUpdateSkipLocked, selectProvablyIdleConsumerPairs, updateConsumerDeliveryOutcome, } from "../db/queries/event-consumer.js";
+import { insertConsumerIfAbsent, markConsumerProcessing, rearmDeadConsumer, selectConsumerForUpdate, selectConsumerForUpdateSkipLocked, selectProvablyIdleConsumerPairs, updateConsumerDeliveryOutcome, } from "../db/queries/event-consumer.js";
 import { selectEventsHeadId, selectPendingAndNewEventRows, } from "../db/queries/event-store.js";
 import { coerceRow, extractTableInfo } from "../db/query.js";
 import { qnScope } from "../engine/qualified-name.js";
@@ -319,13 +319,6 @@ function reportSkippedEvent(consumer, eventId, e, errMessage, context) {
 export async function persistConsumerOutcome(tx, name, instanceId, outcome) {
     await updateConsumerDeliveryOutcome(tx, name, instanceId, outcome);
 }
-// Best-effort record of a pass that threw before persistConsumerOutcome
-// could run (event-dispatcher.ts's processConsumer catch). The caller opens
-// its OWN transaction for this — the one that rolled back never committed
-// anything, including this write, if it happened inside the same tx.
-export async function persistConsumerPassFailure(tx, name, instanceId, errorMessage) {
-    await recordConsumerPassFailure(tx, name, instanceId, errorMessage);
-}
 // Emit the lag gauge inside the consumer pass's tx so ops sees a snapshot
 // consistent with the cursor we just advanced to. `MAX(id)` on the events
 // table is an O(1) reverse-index scan — cheap even under load.

package/dist/pipeline/event-dispatcher.js

@@ -1,9 +1,9 @@
-import { selectSnapshotXmax, selectSnapshotXmin } from "../db/queries/event-consumer.js";
+import { recordConsumerPassFailure, selectSnapshotXmax, selectSnapshotXmin, } from "../db/queries/event-consumer.js";
 import { SYSTEM_TENANT_ID } from "../engine/types/identifiers.js";
 import { EVENTS_PUBSUB_CHANNEL } from "../event-store/index.js";
 import { emitEventConsumerPassOutcome, emitEventConsumerPassSkipped, emitEventConsumerRearmExhausted, emitEventDispatcherListenConnected, getFallbackMeter, getFallbackTracer, } from "../observability/index.js";
 import { SHARED_INSTANCE_SENTINEL } from "./event-consumer-state.js";
-import { acquireConsumerState, consumerInstanceId, deliverEvents, emitLagFromTx, fetchPendingEvents, markProcessing, persistConsumerOutcome, persistConsumerPassFailure, preRegisterConsumers, selectIdleConsumerKeys, } from "./event-dispatcher-delivery.js";
+import { acquireConsumerState, consumerInstanceId, deliverEvents, emitLagFromTx, fetchPendingEvents, markProcessing, persistConsumerOutcome, preRegisterConsumers, selectIdleConsumerKeys, } from "./event-dispatcher-delivery.js";
 import { partitionBurntGaps, splitRangeExcludingIds, toIdRanges } from "./pending-gap-ranges.js";
 const DEFAULT_BATCH_SIZE = 200;
 const DEFAULT_POLL_MS = 100;
@@ -35,6 +35,15 @@ export function createEventDispatcher(options) {
     }
     const tracer = options.tracer ?? getFallbackTracer();
     const meter = options.meter ?? getFallbackMeter();
+    // A standalone dispatcher has no logger on its context; console.error keeps the failure in pod logs.
+    const logDispatcherError = (message) => {
+        if (context.log) {
+            context.log.error(message);
+        }
+        else {
+            console.error(message);
+        }
+    };
     // Tracks which (consumer, instanceId) pairs already fired
     // kumiko_event_consumer_rearm_exhausted_total, so a consumer stuck dead
     // across many poll passes emits the ops-signal once, not every pass
@@ -220,7 +229,7 @@ export function createEventDispatcher(options) {
         //
         // A failure here (e.g. a transient DB blip) must not abort the whole
         // pass — timer/LISTEN callers swallow doPass()'s rejection silently
-        // (see start()), which would mean no log, no persistConsumerPassFailure,
+        // (see start()), which would mean no log, no recordConsumerPassFailure,
         // and no backoff for every consumer this tick. Falling back to "nothing
         // proven idle" instead routes every consumer through its normal
         // acquireConsumerState path, whose own try/catch already covers this.
@@ -254,12 +263,7 @@ export function createEventDispatcher(options) {
                 emitEventDispatcherListenConnected(meter, false);
                 const msg = e instanceof Error ? e.message : String(e);
                 const logMsg = `[event-dispatcher] idle pre-check failed, falling back to per-consumer locking every tick until it recovers: ${msg}`;
-                if (context.log) {
-                    context.log.error(logMsg);
-                }
-                else {
-                    console.error(logMsg);
-                }
+                logDispatcherError(logMsg);
             }
         }
         // Every consumer runs its own turn concurrently (own TX, own cursor,
@@ -396,15 +400,7 @@ export function createEventDispatcher(options) {
             // callers and at-least-once-with-duplicate-delivery on the next pass;
             // neither is what we want, so ops needs to see it.
             const msg = e instanceof Error ? e.message : String(e);
-            if (context.log) {
-                context.log.error(`[event-dispatcher] ${consumer.name} pass failed: ${msg}`);
-            }
-            else {
-                // No logger wired onto this context (e.g. createEventDispatcher used
-                // standalone) — console.error is the only way ops still sees this in
-                // pod logs instead of the failure vanishing with the rolled-back tx.
-                console.error(`[event-dispatcher] ${consumer.name} pass failed: ${msg}`);
-            }
+            logDispatcherError(`[event-dispatcher] ${consumer.name} pass failed: ${msg}`);
             span.setStatus("error", msg);
             // The whole pass rolled back, so markProcessing/persistConsumerOutcome
             // never committed — attempts/last_error are stuck at their pre-pass
@@ -413,18 +409,13 @@ export function createEventDispatcher(options) {
             // so any failure here is swallowed after logging.
             try {
                 await db.begin(async (tx) => {
-                    await persistConsumerPassFailure(tx, consumer.name, instanceId, msg);
+                    await recordConsumerPassFailure(tx, consumer.name, instanceId, msg);
                 });
             }
             catch (persistErr) {
                 const persistMsg = persistErr instanceof Error ? persistErr.message : String(persistErr);
                 const failureMsg = `[event-dispatcher] ${consumer.name} failed to persist pass-failure state: ${persistMsg}`;
-                if (context.log) {
-                    context.log.error(failureMsg);
-                }
-                else {
-                    console.error(failureMsg);
-                }
+                logDispatcherError(failureMsg);
             }
             // Escalate the backoff so this consumer isn't retried on the very
             // next tick — see PASS_FAILURE_BASE_BACKOFF_MS/MAX_MS above.

package/dist/pipeline/handler-access-error.d.ts

@@ -0,0 +1,3 @@
+import type { SessionUser } from "../engine/types/index.js";
+import { type KumikoError } from "../errors/index.js";
+export declare function handlerAccessError(user: Pick<SessionUser, "roles">, type: string): KumikoError;

package/dist/pipeline/handler-access-error.js

@@ -0,0 +1,17 @@
+import { isAnonymousSessionUser } from "../engine/system-user.js";
+import { AccessDeniedError, UnauthenticatedError } from "../errors/index.js";
+// Anonymous callers get 401 so a client whose session lapsed (browser dropped
+// the expired auth cookie) can tell "sign in again" apart from "signed in but
+// not allowed", which stays 403.
+export function handlerAccessError(user, type) {
+    if (isAnonymousSessionUser(user)) {
+        return new UnauthenticatedError({
+            message: `${type} requires a signed-in user`,
+            details: { handler: type },
+        });
+    }
+    return new AccessDeniedError({
+        message: `access denied for ${type}`,
+        details: { handler: type },
+    });
+}

package/dist/pipeline/irreversible-operation-gate.js

@@ -28,11 +28,17 @@ function assertEntryHandlerHighRisk(args) {
         },
     });
 }
+// Stream handlers have no agent hint, so the "declare risk high" advice cannot apply to them.
+function highRiskRemedy(entryHandler) {
+    return entryHandler.qn.includes(":stream:")
+        ? 'stream handlers cannot declare an agent risk and always resolve "mid" — dispatch a risk "high" write handler directly instead'
+        : `declare agent: { risk: "high" } on "${entryHandler.qn}"`;
+}
 export function assertIrreversibleOperationAllowed(operation) {
     assertEntryHandlerHighRisk({
         reason: FrameworkReasons.irreversibleOperationRequiresHighRisk,
         buildMessage: (entryHandler) => `Handler "${entryHandler.qn}" performs an irreversible ${operation} but resolves agent risk ` +
-            `"${entryHandler.risk}" — declare agent: { risk: "high" } on "${entryHandler.qn}". The ` +
+            `"${entryHandler.risk}" — ${highRiskRemedy(entryHandler)}. The ` +
             "directly called handler must carry it; delegating via ctx.write/writeAs does not.",
         details: { operation },
     });
@@ -49,8 +55,8 @@ export function assertInstructionFieldWriteAllowed(entityName, verb, writtenFiel
     assertEntryHandlerHighRisk({
         reason: FrameworkReasons.instructionFieldWriteRequiresHighRisk,
         buildMessage: (entryHandler) => `Handler "${entryHandler.qn}" ${verb}s "${entityName}" field(s) ${fields.join(", ")} ` +
-            `flagged readAsInstruction: true but resolves agent risk "${entryHandler.risk}" — declare ` +
-            `agent: { risk: "high" } on "${entryHandler.qn}". The directly called handler must carry ` +
+            `flagged readAsInstruction: true but resolves agent risk "${entryHandler.risk}" — ` +
+            `${highRiskRemedy(entryHandler)}. The directly called handler must carry ` +
             "it; delegating via ctx.write/writeAs does not.",
         details: { entityName, verb, fields },
     });

package/dist/pipeline/member-read-only-transaction.js

@@ -6,8 +6,13 @@ const PG_READ_ONLY_SQLSTATE = "25006";
 function isReadOnlyTransactionViolation(e) {
     return extractPgError(e)?.code === PG_READ_ONLY_SQLSTATE;
 }
+class SavepointDiscard extends Error {
+    constructor() {
+        super("savepoint discarded on purpose");
+        this.name = "SavepointDiscard";
+    }
+}
 async function runInDiscardedReadOnlySavepoint(tx, fn) {
-    const discardMarker = {};
     const settled = {};
     try {
         await runInSavepoint(tx, async (sp) => {
@@ -16,11 +21,11 @@ async function runInDiscardedReadOnlySavepoint(tx, fn) {
             // @cast-boundary driver savepoint handle — structurally a DbTx, same shape runInSavepoint's caller relies on
             settled.outcome = { value: await fn(sp) };
             // Always discarded: RELEASE SAVEPOINT would leave the outer tx read-only too.
-            throw discardMarker;
+            throw new SavepointDiscard();
         });
     }
     catch (e) {
-        if (e !== discardMarker)
+        if (!(e instanceof SavepointDiscard))
             throw e;
     }
     if (!settled.outcome) {

package/dist/pipeline/system-hooks.js

@@ -204,7 +204,13 @@ async function readProjectionRowForSearch(ctx, registry, entityName, entity, ten
     const row = await createTenantDb(baseDb, tenantId).fetchOne(table, where);
     if (!row)
         return undefined;
-    return rehydrateCompoundTypes(row, entity);
+    const state = rehydrateCompoundTypes(row, entity);
+    // The event payload never carries sensitive fields; extensions must not see them via the row either.
+    for (const [name, field] of Object.entries(entity.fields)) {
+        if ("sensitive" in field && field.sensitive === true)
+            delete state[name];
+    }
+    return state;
 }
 // #1610 — subject-annotated searchable fields are ciphertext in the event
 // payload; decrypt into the derived index only. No KMS → omit ciphertext

package/dist/pipeline/system-identity-switch.js

@@ -13,7 +13,7 @@ function hasSameClaims(caller, asUser) {
     if (keys.length !== Object.keys(asUserClaims).length)
         return false;
     return keys.every((key) => Object.hasOwn(asUserClaims, key) &&
-        JSON.stringify(callerClaims[key]) === JSON.stringify(asUserClaims[key]));
+        Bun.deepEquals(callerClaims[key], asUserClaims[key], true));
 }
 // claims drive ownership row filters and origin makes a ctx read-only, so both must match exactly.
 export function isSelfDelegation(caller, asUser) {

package/dist/search/meilisearch-adapter.js

@@ -153,7 +153,6 @@ export function createMeilisearchAdapter(options) {
             // skip: empty batch — avoid an unnecessary Meilisearch round-trip
             if (items.length === 0)
                 return;
-            await ensureConfigured(tenantId);
             const index = client.index(meilisearchTenantIndex(prefix, tenantId));
             const ids = items.map((i) => meilisearchDocId(i.entityType, i.entityId));
             await awaitSucceededTask(index.deleteDocuments(ids), REMOVE_TOLERATED_ERROR_CODES);
@@ -178,7 +177,6 @@ export function createMeilisearchAdapter(options) {
             }));
         },
         async remove(tenantId, entityType, entityId) {
-            await ensureConfigured(tenantId);
             const index = client.index(meilisearchTenantIndex(prefix, tenantId));
             await awaitSucceededTask(index.deleteDocument(meilisearchDocId(entityType, entityId)), REMOVE_TOLERATED_ERROR_CODES);
         },

package/dist/stack/push-entity-projection-tables.js

@@ -1,6 +1,6 @@
 import { KUMIKO_NAME_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types";
 import { columnNamesOf, tableExists } from "../db/schema-inspection.js";
-import { addMissingColumns, tableToMeta, unsafePushTables } from "./table-helpers.js";
+import { addMissingColumns, addMissingIndexes, tableToMeta, unsafePushTables, } from "./table-helpers.js";
 // biome-ignore lint/suspicious/noConsole: stack-internal status logging
 const logInfo = (msg) => console.log(msg);
 /**
@@ -44,7 +44,7 @@ export async function pushEntityProjectionTables(stack, registry) {
 function isUnsafeToAutoAdd(col) {
     return col.notNull && !col.primaryKey && col.defaultSql === undefined;
 }
-// Backfills columns a persistent dev DB predates; a required column with no
+// Backfills columns and indexes a persistent dev DB predates; a required column with no
 // default can't be added safely on a table that may hold rows, so that
 // stays a boot error instead.
 async function syncExistingProjectionTable(stack, physical, table) {
@@ -53,7 +53,8 @@ async function syncExistingProjectionTable(stack, physical, table) {
     const missingColumns = meta.columns.filter((c) => !liveColumns.has(c.name));
     if (missingColumns.length === 0) {
         logInfo(`[kumiko-stack] table ${physical} already exists — skipping create`);
-        // skip: live table already has every declared column
+        await addMissingIndexes(stack.db, physical, meta.indexes);
+        // skip: table is already in sync, only indexes needed backfilling
         return;
     }
     const unsafeColumns = missingColumns.filter(isUnsafeToAutoAdd);
@@ -70,4 +71,5 @@ async function syncExistingProjectionTable(stack, physical, table) {
     logInfo(`[kumiko-stack] table ${physical} is missing column(s) ` +
         `${missingColumns.map((c) => `"${c.name}"`).join(", ")} — adding`);
     await addMissingColumns(stack.db, physical, missingColumns);
+    await addMissingIndexes(stack.db, physical, meta.indexes);
 }

package/dist/stack/redis.d.ts

@@ -8,4 +8,5 @@ export type TestRedis = {
     flushNamespace: () => Promise<void>;
     cleanup: () => Promise<void>;
 };
+export declare function queueNamePrefixForTestRedis(keyPrefix: string): string;
 export declare function createTestRedis(): Promise<TestRedis>;

package/dist/stack/redis.js

@@ -1,5 +1,11 @@
 import { generateId } from "../utils/index.js";
 import { requireEnv } from "./db.js";
+// BullMQ queues live on the raw redisUrl, outside the test Redis keyPrefix, so
+// parallel stacks sharing the prod default queue name would consume each
+// other's jobs. BullMQ rejects `:` in queue names.
+export function queueNamePrefixForTestRedis(keyPrefix) {
+    return keyPrefix.split(":").filter(Boolean).join("-");
+}
 export async function createTestRedis() {
     const Redis = (await import("ioredis")).Redis;
     const redisUrl = requireEnv("REDIS_URL");
@@ -8,13 +14,13 @@ export async function createTestRedis() {
     // prefix space is unbounded. See Track B.3 in docs/plans/tests-refactor.
     const prefix = `kt:${generateId().slice(-8)}:`;
     const redis = new Redis(redisUrl, { keyPrefix: prefix });
-    async function flushNamespace() {
+    async function deleteKeysMatching(pattern) {
         // Open a prefix-less client for the scan — ioredis' keyPrefix is applied
         // per-command but SCAN's returned keys are full names, so managing the
         // del set with the prefix already on the connection is error-prone.
         const raw = new Redis(redisUrl);
         try {
-            const stream = raw.scanStream({ match: `${prefix}*`, count: 500 });
+            const stream = raw.scanStream({ match: pattern, count: 500 });
             const keys = [];
             for await (const batch of stream)
                 keys.push(...batch);
@@ -25,6 +31,7 @@ export async function createTestRedis() {
             raw.disconnect();
         }
     }
+    const flushNamespace = () => deleteKeysMatching(`${prefix}*`);
     return {
         redis,
         redisUrl,
@@ -32,6 +39,8 @@ export async function createTestRedis() {
         flushNamespace,
         cleanup: async () => {
             await flushNamespace();
+            // The derived per-stack JobRunner queues sit outside the keyPrefix.
+            await deleteKeysMatching(`bull:${queueNamePrefixForTestRedis(prefix)}-*`);
             redis.disconnect();
         },
     };

package/dist/stack/table-helpers.d.ts

@@ -1,5 +1,5 @@
 import type { DbConnection } from "../db/connection.js";
-import type { ColumnMeta, EntityTableMeta } from "../db/entity-table-meta.js";
+import type { ColumnMeta, EntityTableMeta, IndexMeta } from "../db/entity-table-meta.js";
 import type { EventDispatcher } from "../pipeline/index.js";
 /**
  * Bypass: creates an entity-table directly without going through the
@@ -11,6 +11,8 @@ export declare function unsafeEnsureEntityTable(db: DbConnection, entity: import
 export declare function tableToMeta(table: unknown): EntityTableMeta;
 /** Applies ALTER TABLE ADD COLUMN for exactly the given columns. */
 export declare function addMissingColumns(db: DbConnection, tableName: string, columns: readonly ColumnMeta[]): Promise<void>;
+/** CREATE [UNIQUE] INDEX IF NOT EXISTS for exactly the given indexes. */
+export declare function addMissingIndexes(db: DbConnection, tableName: string, indexes: readonly IndexMeta[]): Promise<void>;
 /**
  * Bypass: pushes table definitions to the database directly. Produces
  * CREATE TABLE IF NOT EXISTS + CREATE INDEX statements via renderTableDdl

package/dist/stack/table-helpers.js

@@ -66,6 +66,14 @@ export async function addMissingColumns(db, tableName, columns) {
         await alterTableAddColumn(db, tableName, col.name, type, defaultClause, notNull);
     }
 }
+/** CREATE [UNIQUE] INDEX IF NOT EXISTS for exactly the given indexes. */
+export async function addMissingIndexes(db, tableName, indexes) {
+    for (const idx of indexes) {
+        const kind = idx.unique ? "UNIQUE INDEX" : "INDEX";
+        const colList = idx.columns.map((c) => `"${c}"`).join(", ");
+        await createIndexIfNotExists(db, kind, idx.name, tableName, colList, idx.whereSql);
+    }
+}
 /**
  * Bypass: pushes table definitions to the database directly. Produces
  * CREATE TABLE IF NOT EXISTS + CREATE INDEX statements via renderTableDdl
@@ -90,13 +98,7 @@ export async function unsafePushTables(db, tables, prevTables) {
             const newCols = meta.columns.filter((c) => !prevCols.has(c.name));
             await addMissingColumns(db, meta.tableName, newCols);
             const prevIdxNames = new Set(prev.indexes.map((i) => i.name));
-            for (const idx of meta.indexes) {
-                if (!prevIdxNames.has(idx.name)) {
-                    const kind = idx.unique ? "UNIQUE INDEX" : "INDEX";
-                    const colList = idx.columns.map((c) => `"${c}"`).join(", ");
-                    await createIndexIfNotExists(db, kind, idx.name, meta.tableName, colList, idx.whereSql);
-                }
-            }
+            await addMissingIndexes(db, meta.tableName, meta.indexes.filter((i) => !prevIdxNames.has(i.name)));
         }
         else {
             const statements = renderTableDdl(meta);

package/dist/stack/test-stack.js

@@ -11,16 +11,10 @@ import { createInMemorySearchAdapter } from "../search/index.js";
 import { createTestDb } from "./db.js";
 import { createJobFailureTracker, drainJobs } from "./drain-jobs.js";
 import { createEventCollector } from "./event-collector.js";
-import { createTestRedis } from "./redis.js";
+import { createTestRedis, queueNamePrefixForTestRedis } from "./redis.js";
 import { createRequestHelper } from "./request-helper.js";
 import { unsafePushTables } from "./table-helpers.js";
 const DEFAULT_JWT_SECRET = "test-stack-secret-minimum-32-characters!!";
-// BullMQ queues live on the raw redisUrl, outside the test Redis keyPrefix, so
-// parallel stacks sharing the prod default queue name would consume each
-// other's jobs. BullMQ rejects `:` in queue names.
-function queueNamePrefixForTestRedis(keyPrefix) {
-    return keyPrefix.split(":").filter(Boolean).join("-");
-}
 export async function setupTestStack(options) {
     const jwtSecret = options.jwtSecret ?? DEFAULT_JWT_SECRET;
     const enabledHooks = options.systemHooks ?? ["sse", "search"];

package/dist/testing/handler-context.js

@@ -5,7 +5,7 @@
 // production services (delivery-service uses it to run cross-feature notify
 // calls without a real dispatcher). Hence the runtime classification despite
 // living under `testing/` — no vitest imports, no test side-effects.
-import { ANONYMOUS_ROLE } from "../engine/system-user.js";
+import { createAnonymousUser } from "../engine/system-user.js";
 import { DEFAULT_LOCALE } from "../i18n/request-locale.js";
 import { createNoopMetricsHandle, getFallbackTracer } from "../observability/index.js";
 import { createTzContext } from "../time/index.js";
@@ -31,11 +31,8 @@ export function bridgeStub(opts) {
     // anonymous default values when no user is passed explicitly. Test code
     // that cares about identity passes its own SessionUser here and gets it
     // back on ctx.
-    const stubUser = opts?.user ?? {
-        id: "00000000-0000-0000-0000-000000000000",
-        tenantId: "00000000-0000-0000-0000-000000000000", // @cast-boundary engine-bridge
-        roles: [ANONYMOUS_ROLE],
-    };
+    const stubUser = opts?.user ??
+        createAnonymousUser("00000000-0000-0000-0000-000000000000"); // @cast-boundary engine-bridge
     return {
         user: stubUser,
         query: notAvailable("query"), // @cast-boundary engine-bridge

package/dist/ui-types/index.d.ts

@@ -10,7 +10,7 @@ export type { AccessRule, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPe
 export { isOpenToAllGranted, isUiAccessGranted } from "../engine/types/handlers.js";
 export type { IconKey, NavDefinition, NavIconKey } from "../engine/types/nav.js";
 export type { ActionFormFooterAction, ActionFormRedirect, ActionFormScreenDefinition, ConfigEditScreenDefinition, CustomScreenDefinition, CustomScreenRoute, DashboardChartKind, DashboardChartPanel, DashboardChartTone, DashboardCustomPanel, DashboardFeedPanel, DashboardFilterDefinition, DashboardListPanel, DashboardPanelDefinition, DashboardPanelEmptyState, DashboardPanelQueryOptions, DashboardPanelSpan, DashboardPanelVisibility, DashboardProgressListPanel, DashboardScopeDefinition, DashboardScreenDefinition, DashboardScreenPanel, DashboardStatGroupPanel, DashboardStatPanel, DashboardTimeRangeDefinition, EditExtensionSection, EditFieldSpec, EditFieldsSection, EditLayout, EditRelatedListSection, EditSectionSpec, EditWriteFormSection, EntityEditScreenDefinition, EntityListExpandableRow, EntityListFacetConfig, EntityListFacetExtraOption, EntityListScreenDefinition, FieldCondition, FieldIconKey, FieldRenderer, FormWidth, ListBadgeTone, ListColumnDisplay, ListColumnSpec, ListFacetSpec, ListSortSpec, MetricNavigate, MetricSpec, PlatformComponent, ProjectionDetailScreenDefinition, ProjectionListScreenDefinition, RecordHeaderSubtitlePart, RelatedListGroupBy, RelatedListRowTone, RelatedListToolbarAction, RowAction, RowActionDisplay, RowActionDrawer, RowActionMode, RowActionNavigate, RowActionWriteHandler, RowFieldExtractor, ScreenDefinition, ScreenFilter, ScreenFilterOp, ScreenSlots, SecretMintConfirmStep, SecretMintScreenDefinition, SecretReveal, SecretRevealField, SecretsEditScreenDefinition, SecretsEditSection, ToolbarAction, } from "../engine/types/screen.js";
-export { metricField } from "../engine/types/screen.js";
+export { metricField, relatedListGroupHeaderLabel, relatedListGroupKey, } from "../engine/types/screen.js";
 export type { TargetRef } from "../engine/types/target-ref.js";
 export type { TreeAction, TreeNode, TreeNodeState } from "../engine/types/tree-node.js";
 export type { WorkspaceDefinition } from "../engine/types/workspace.js";

package/dist/ui-types/index.js

@@ -24,7 +24,7 @@ export { computeDerivedCellValue, roundDerivedCellValue } from "../engine/embedd
 export { parseRefTarget } from "../engine/parse-ref-target.js";
 export { evalFieldCondition, explicitListScreenId, isExtensionEditSection, isFieldsEditSection, isFormatSpec, isWriteFormEditSection, normalizeEditField, normalizeListColumn, resolveNavParentScreen, sectionFieldSpecs, } from "../engine/screen-helpers.js";
 export { isOpenToAllGranted, isUiAccessGranted } from "../engine/types/handlers.js";
-export { metricField } from "../engine/types/screen.js";
+export { metricField, relatedListGroupHeaderLabel, relatedListGroupKey, } from "../engine/types/screen.js";
 export { ACTION_FORM_ENTITY, PROJECTION_DETAIL_ENTITY, WRITE_FORM_SECTION_ENTITY, } from "../i18n/required-surface-keys.js";
 export { formalLocaleTag } from "./formality.js";
 export { LIST_ROW_META_COLUMNS, LIST_ROW_META_REFERENCES, REFERENCE_LOOKUP_SOURCES, SYSTEM_REFERENCE_LABELS, } from "./list-row-meta.js";