@cosmicdrift/kumiko-framework 0.364.0 → 0.365.1

package/dist/pipeline/dispatch-shared.js

@@ -9,13 +9,13 @@ import { isRateLimitDisabled, resolveAgentExposure } from "../engine/types/index
 import { AccessDeniedError, FeatureDisabledError, FrameworkReasons, InternalError, memberResolutionReadOnlyDenied, RateLimitError, RateLimitUnavailableError, VersionConflictError, writeFailure, } from "../errors/index.js";
 import { archiveStream as archiveStreamHelper, isStreamArchived, restoreStream as restoreStreamHelper, } from "../event-store/archive.js";
 import { IdempotentAppendConflictError as EventStoreIdempotentAppendConflictError, VersionConflictError as EventStoreVersionConflictError, } from "../event-store/errors.js";
-import { getStreamVersion, loadAggregate, loadAggregateAsOf, } from "../event-store/event-store.js";
+import { loadAggregate, loadAggregateAsOf, loadAggregateForWriting, } from "../event-store/event-store.js";
 import { effectiveSnapshotGeneration, loadAggregateWithSnapshot, saveSnapshot, } from "../event-store/snapshot.js";
 import { upcastStoredEvent, upcastStoredEvents } from "../event-store/upcaster.js";
 import { createFileContext } from "../files/file-handle.js";
 import { DEFAULT_LOCALE, isValidLocaleTag } from "../i18n/request-locale.js";
 import { createFallbackLogger } from "../logging/utils.js";
-import { createEscapeHatchReporter, createMetricsHandle, createNoopMetricsHandle, createSafeMetricsHandle, emitDispatcherError, emitDispatcherHandler, getFallbackTracer, observabilityContext, } from "../observability/index.js";
+import { createEscapeHatchReporter, createMetricsForFactory, createMetricsHandle, createNoopMetricsHandle, emitDispatcherError, emitDispatcherHandler, getFallbackTracer, observabilityContext, } from "../observability/index.js";
 import { buildBucketKey, buildPayloadBucketKey, normalizePayloadBucketValue, } from "../rate-limit/index.js";
 import { createTzContext, isValidIanaTimeZone } from "../time/index.js";
 import { isPlainObject } from "../utils/is-plain-object.js";
@@ -257,10 +257,14 @@ export function applyBeforeTransactionReadOnly(handlerContext) {
         ...denyTransactionBoundSurfaces(handlerContext),
         dbOutsideTransaction: undefined,
         outsideTransaction: undefined,
-        forTenant: undefined,
     };
 }
-export async function buildHandlerContext(ctx, type, user, origin, tx, afterCommitHooks, includeDeleted, transactionScope = tx ? "inTransaction" : "withoutTransaction") {
+export async function buildHandlerContext(ctx, type, user, origin, tx, afterCommitHooks, includeDeleted, transactionScope = tx ? "inTransaction" : "withoutTransaction", 
+// A query bridge has no commit sink of its own, but ctx.notify inside it must still wait for
+// the outer write's commit: the outer sink is lent to notify only, not to scheduleAfterCommit.
+outerNotifySink, 
+// beforeTransaction phase: ctx.forTenant stays available but every target db denies writes.
+readOnlyForTenant = false) {
     const { registry, appContext: context, effectiveFeatures, jobRunner, lifecycle } = ctx;
     const isSystem = registry.isHandlerSystemScoped(type);
     // The outer dispatcher receives a DbConnection from the server/stack;
@@ -358,23 +362,30 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
     const notifyInTransactionFactory = notifyFactory && tx !== undefined
         ? (notifyUser, notifyTenantId) => notifyFactory(notifyUser, notifyTenantId, notifyJobDispatcher, outsideTxSource, context._fileProviderResolver)
         : undefined;
+    const notifyAfterCommitFactory = notifyFactory
+        ? (notifyUser, notifyTenantId) => notifyFactory(notifyUser, notifyTenantId, notifyJobDispatcher, undefined, context._fileProviderResolver)
+        : undefined;
     const notify = buildNotify();
     function buildNotify() {
-        if (!notifyFactory)
+        if (!notifyAfterCommitFactory)
             return undefined;
-        const notifyAfterCommit = notifyFactory(user, user.tenantId, notifyJobDispatcher, undefined, context._fileProviderResolver);
+        const notifyAfterCommit = notifyAfterCommitFactory(user, user.tenantId);
         if (!notifyInTransactionFactory)
             return notifyAfterCommit;
         const notifyInTransaction = notifyInTransactionFactory(user, user.tenantId);
-        // A rolled-back write must leave no notification behind.
-        if (!hasLiveCommitSink)
+        // A rolled-back write must leave no notification behind. Without any commit to wait for (a
+        // post-commit context) delivery stays immediate.
+        const notifyCommitSink = hasLiveCommitSink ? bridgeSink : outerNotifySink;
+        if (notifyCommitSink === undefined)
             return notifyInTransaction;
         return createDeferringNotify({
             registry,
             tenantId: user.tenantId,
             notifyAfterCommit,
             notifyNow: notifyInTransaction,
-            scheduleAfterCommit,
+            scheduleAfterCommit: (hook) => {
+                notifyCommitSink.push(hook);
+            },
         });
     }
     // Mirror notify: only built when the config feature wired its factory.
@@ -417,7 +428,7 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
             if (targetTenantId === user.tenantId && exposedDb) {
                 // Only perCommand handlers lose forTenant writes; reservations keep their pre-transaction contract.
                 const ownTenantDb = denyDbWrites && !isPerCommand
-                    ? buildTenantScopedDb(dbSource, reqCtx?.signal)
+                    ? buildTenantScopedDb(dbSource, reqCtx?.signal, undefined, readOnlyForTenant)
                     : exposedDb;
                 return { db: ownTenantDb, streamTenantId: undefined };
             }
@@ -427,7 +438,7 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
                 });
             }
             return {
-                db: buildTenantScopedDb(dbSource, reqCtx?.signal, targetTenantId, denyDbWrites && isPerCommand),
+                db: buildTenantScopedDb(dbSource, reqCtx?.signal, targetTenantId, denyDbWrites && (isPerCommand || readOnlyForTenant)),
                 streamTenantId: targetTenantId,
             };
         }
@@ -455,16 +466,13 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
     const metrics = meter && featureName ? createMetricsHandle(meter, featureName) : createNoopMetricsHandle();
     // ctx.metricsFor(featureName) — shared/library code binds to a feature
     // name of its own choosing instead of the dispatching handler's
-    // (framework#1844). Unregistered names no-op rather than throw, see
-    // createSafeMetricsHandle.
-    const metricsFor = meter
-        ? (targetFeatureName) => createSafeMetricsHandle(meter, targetFeatureName)
-        : () => createNoopMetricsHandle();
+    // (framework#1844). Unregistered names no-op rather than throw.
+    const metricsFor = createMetricsForFactory(meter);
     // A failed inner write has already appended its event and projections when a later
     // step (e.g. an inTransaction hook) fails, and the outer handler may swallow the
     // failure result. The savepoint makes the failure undo exactly the inner write; the
     // inner afterCommit hooks only reach the outer sink if it succeeded.
-    const executeNestedWriteInSavepoint = async (asUser, targetType, payload) => {
+    const runNestedWriteInSavepoint = async (asUser, targetType, payload) => {
         if (registry.getWriteHandler(targetType)?.transaction === "perCommand") {
             return writeFailure(perCommandNestedDenied(targetType));
         }
@@ -488,6 +496,15 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
             throw e;
         }
     };
+    // Savepoints on one connection are not serialized by the driver: two parallel nested writes would
+    // interleave their statements and a ROLLBACK TO of the first would also discard the second's rows.
+    // Writes nested one level deeper run on their own savepoint handle and therefore their own chain.
+    let nestedWriteChain = Promise.resolve();
+    const executeNestedWriteInSavepoint = (asUser, targetType, payload) => {
+        const run = nestedWriteChain.then(() => runNestedWriteInSavepoint(asUser, targetType, payload));
+        nestedWriteChain = run.catch(() => undefined);
+        return run;
+    };
     // Without an open transaction (post-commit hooks, stream/query handlers, perCommand handlers) a bare
     // executeWrite would auto-commit event append, projections and inTransaction hooks separately and its
     // afterCommit hooks would land in a sink nobody flushes. A batch-of-one gives the write its own
@@ -498,7 +515,7 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
     const identitySwitchAudit = { reason: identitySwitchGrantReason, report: reportEscapeHatch };
     const identitySwitch = createGatedIdentitySwitch(`handler "${type}"`, user, hasIdentitySwitchGrant, {
         // Inherits the caller's origin, so switching to SYSTEM cannot shed an anonymous root.
-        queryAs: (asUser, targetType, payload) => executeQuery(ctx, targetType, payload, asUser, origin, tx), // @wrapper-known semantic-alias
+        queryAs: (asUser, targetType, payload) => executeQuery(ctx, targetType, payload, asUser, origin, tx, hasLiveCommitSink ? bridgeSink : outerNotifySink), // @wrapper-known semantic-alias
         writeAs: writeAsUser,
     }, identitySwitchAudit);
     // Lazy — creates the reader (which fails closed on SYSTEM_TENANT_ID) only
@@ -542,7 +559,7 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
         return projTable === undefined || hasTenantColumn(projTable);
     });
     const bridge = {
-        query: (targetType, payload) => executeQuery(ctx, targetType, payload, user, origin, tx), // @wrapper-known semantic-alias
+        query: (targetType, payload) => executeQuery(ctx, targetType, payload, user, origin, tx, hasLiveCommitSink ? bridgeSink : outerNotifySink), // @wrapper-known semantic-alias
         queryAs: identitySwitch.queryAs,
         write: (targetType, payload) => writeAsUser(user, targetType, payload),
         writeAs: identitySwitch.writeAs,
@@ -597,16 +614,9 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
                     message: `ctx.fetchForWriting("${args.aggregateId}") requires a database connection — none is configured.`,
                 });
             }
-            // Stream-version authoritative (same policy as CRUD executor + Block 0).
-            // A single SELECT MAX(version) is cheaper than loading the full stream
-            // when the caller just wants to append — but most callers also want
-            // the events (business-rule checks), so fetch both in parallel.
-            const [storedEvents, fetchedVersion] = await Promise.all([
-                loadAggregate(dbSource, args.aggregateId, user.tenantId, {
-                    aggregateType: args.aggregateType,
-                }),
-                getStreamVersion(dbSource, args.aggregateId, user.tenantId),
-            ]);
+            // Stream-version authoritative (same policy as CRUD executor + Block 0), read together
+            // with the events so the pinned version covers exactly what the handler's rules saw.
+            const { events: storedEvents, streamVersion: fetchedVersion } = await loadAggregateForWriting(dbSource, args.aggregateId, user.tenantId, { aggregateType: args.aggregateType });
             const events = await upcastStoredEvents(storedEvents, registry.getEventUpcasters(), {
                 db: dbSource,
                 tenantId: user.tenantId,
@@ -831,11 +841,12 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
     // able to compute bucket keys.
     const { _rateLimitPayloadDigest: payloadDigest, 
     // Bound to this call's tx: an outer context's factory must not leak into a tx-less one.
-    _notifyInTransactionFactory: _omitOuterNotifyInTransactionFactory, ...contextForHandler } = context;
+    _notifyInTransactionFactory: _omitOuterNotifyInTransactionFactory, _notifyAfterCommitFactory: _omitOuterNotifyAfterCommitFactory, ...contextForHandler } = context;
     const handlerContext = {
         ...contextForHandler,
         ...(payloadDigest && { rateLimitDigest: createHandlerBoundDigest(payloadDigest, type) }),
         ...(notifyInTransactionFactory && { _notifyInTransactionFactory: notifyInTransactionFactory }),
+        ...(notifyAfterCommitFactory && { _notifyAfterCommitFactory: notifyAfterCommitFactory }),
         registry,
         db: exposedDb,
         dbOutsideTransaction,

package/dist/pipeline/dispatch-stream.js

@@ -2,7 +2,7 @@ import { accessInvalidationCredentialFor } from "../api/sse-broker.js";
 import { scheduleTokenExpiry } from "../api/token-expiry-timer.js";
 import { hasAccess } from "../engine/access.js";
 import { tenantOverrideDenied } from "../engine/cross-tenant.js";
-import { AccessDeniedError, memberResolutionReadOnlyDenied, NotFoundError, validationErrorFromZod, } from "../errors/index.js";
+import { AccessDeniedError, memberResolutionReadOnlyDenied, NotFoundError, UnauthenticatedError, 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";
@@ -69,10 +69,16 @@ async function* executeStreamInner(ctx, type, payload, user, origin, options) {
                 abandonedForInvalidation = true;
                 void nextPull.catch(() => { });
                 void iterator.return?.(undefined)?.then(undefined, () => { });
+                // An expired token is a lapsed session (401, so clients show the
+                // session-end hint); revocation is a permission change (403).
+                if (outcome.reason === "expired") {
+                    throw new UnauthenticatedError({
+                        message: `token expired mid-stream for ${type}`,
+                        details: { handler: type, reason: outcome.reason },
+                    });
+                }
                 throw new AccessDeniedError({
-                    message: outcome.reason === "expired"
-                        ? `token expired mid-stream for ${type}`
-                        : `access revoked mid-stream for ${type}`,
+                    message: `access revoked mid-stream for ${type}`,
                     details: { handler: type },
                 });
             }

package/dist/pipeline/dispatcher.js

@@ -1,6 +1,7 @@
 import { runWithWriteOrigin } from "../api/request-context.js";
 import { TENANT_MEMBERSHIPS_QUERY } from "../engine/extension-names.js";
 import { InternalError, reraiseAsKumikoError } from "../errors/index.js";
+import { withEscapeHatchAuditScopeStream } from "../observability/escape-hatch-report.js";
 import { createEscapeHatchReportWindow, getFallbackMeter, getFallbackTracer, registerStandardMetrics, withEscapeHatchAuditScope, } from "../observability/index.js";
 import { CACHE_SYNC_TOPICS, isTenantConfigSyncMessage } from "../redis/cache-sync-topics.js";
 import { INTERACTIVE_SIGN_IN_POLICY, resolveActiveMembershipFn } from "./active-membership.js";
@@ -114,7 +115,8 @@ export function createDispatcher(registry, context, options = {}) {
         },
         stream: (typeOrRef, payload, user, options) => {
             const type = resolveType(typeOrRef);
-            return executeStream(ctx, type, payload, user, rootWriteOrigin(registry, type, user), options);
+            const origin = rootWriteOrigin(registry, type, user);
+            return withEscapeHatchAuditScopeStream(() => executeStream(ctx, type, payload, user, origin, options));
         },
         async command(typeOrRef, payload, user) {
             const type = resolveType(typeOrRef);

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

@@ -1,4 +1,4 @@
-import type { PgClient } from "../db/connection.js";
+import type { PgListenClient } from "../db/connection.js";
 import type { AppContext } from "../engine/types/index.js";
 import { type StoredEvent } from "../event-store/index.js";
 import { type Meter, type Tracer } from "../observability/index.js";
@@ -46,7 +46,7 @@ export type EventDispatcherOptions = {
     readonly tracer?: Tracer;
     readonly meter?: Meter;
     readonly instanceId?: string;
-    readonly pgClient?: PgClient;
+    readonly pgClient?: PgListenClient;
 };
 export declare function createEventDispatcher(options: EventDispatcherOptions): EventDispatcher;
 export type { ConsumerProgress, ConsumerRecoveryState } from "./event-dispatcher-admin.js";

package/dist/pipeline/event-dispatcher.js

@@ -114,7 +114,7 @@ export function createEventDispatcher(options) {
     // to EVENTS_PUBSUB_CHANNEL; cleared by .stop(). The timer remains active
     // even with LISTEN attached — it's a cheap safety net against missed
     // NOTIFYs (subscription drop, crash mid-commit).
-    let pgUnlisten = null;
+    let pgSubscription = null;
     // Bounds how many consumer turns hold a DB transaction at once. Each turn's
     // db.begin() checks out one pool connection, plus any writes the handler
     // itself makes via context.db — the app db pool defaults to postgres-js's
@@ -498,15 +498,16 @@ export function createEventDispatcher(options) {
             // succeeds (onlisten callback). It drops to 0 on the initial connect
             // failure, on stop() and when the idle pre-check detects a DB outage.
             // An outage shorter than one poll tick is not detected; the gauge then
-            // stays at 1 until postgres.js's delayed re-LISTEN lands.
+            // stays at 1 until the driver's delayed re-LISTEN lands.
             emitEventDispatcherListenConnected(meter, false);
             if (options.pgClient) {
                 try {
                     const sub = await options.pgClient.listen(EVENTS_PUBSUB_CHANNEL, runBackgroundPass, () => {
-                        // Fires on initial connect and again when postgres.js's own
+                        // Fires on initial connect and again when the driver's own
                         // re-LISTEN lands after a drop; during an outage that re-LISTEN
-                        // waits in its connection backoff (measured 10-30s after the DB
-                        // returns), polling covers delivery meanwhile. Never unlisten()
+                        // waits in its connection backoff (postgres-js: measured 10-30s
+                        // after the DB returns, Bun.SQL: up to 32s), polling covers
+                        // delivery meanwhile. Never unlisten()
                         // + listen() by hand: that leaves duplicate listeners.
                         // ponytail: no own LISTEN reconnect, the backoff gap is polled;
                         // add a dedicated LISTEN connection if prod wires a pgClient
@@ -514,7 +515,7 @@ export function createEventDispatcher(options) {
                         listenSubscribed = true;
                         emitEventDispatcherListenConnected(meter, true);
                     });
-                    pgUnlisten = sub.unlisten;
+                    pgSubscription = sub;
                 }
                 catch (e) {
                     emitEventDispatcherListenConnected(meter, false);
@@ -532,12 +533,13 @@ export function createEventDispatcher(options) {
                 clearInterval(timer);
                 timer = null;
             }
-            if (pgUnlisten) {
-                await pgUnlisten().catch(() => {
+            if (pgSubscription) {
+                // Called on the subscription: Bun.SQL's unlisten is a prototype method.
+                await pgSubscription.unlisten().catch(() => {
                     // skip: unlisten failure only matters during shutdown — the
                     // subscription is being torn down anyway.
                 });
-                pgUnlisten = null;
+                pgSubscription = null;
                 listenSubscribed = false;
                 emitEventDispatcherListenConnected(meter, false);
             }

package/dist/pipeline/event-retention.d.ts

@@ -6,6 +6,7 @@ export type PruneEventsOptions = {
     readonly aggregateTypes: readonly string[];
     readonly aggregateIds?: readonly string[];
     readonly dryRun?: boolean;
+    readonly batchSize?: number;
 };
 export type PruneEventsResult = {
     readonly deletedCount: number;

package/dist/pipeline/event-retention.js

@@ -34,6 +34,10 @@ export async function pruneEvents(db, options) {
     if (options.aggregateIds !== undefined && options.aggregateIds.length === 0) {
         throw new Error("pruneEvents: aggregateIds must be non-empty when set.");
     }
+    if (options.batchSize !== undefined &&
+        (!Number.isInteger(options.batchSize) || options.batchSize < 1)) {
+        throw new Error("pruneEvents: batchSize must be a positive integer.");
+    }
     const aggregateTypes = options.aggregateTypes;
     const aggregateIds = options.aggregateIds;
     const dryRun = options.dryRun === true;
@@ -56,7 +60,9 @@ export async function pruneEvents(db, options) {
             aggregateType: [...aggregateTypes],
             ...(aggregateIds ? { aggregateId: [...aggregateIds] } : {}),
             createdAt: { lt: cutoff },
-        });
+        }, options.batchSize === undefined
+            ? undefined
+            : { orderBy: { col: "id", direction: "asc" }, limit: options.batchSize });
         if (candidates.length === 0) {
             return { deletedCount: 0, cutoff, aggregateTypes, dryRun };
         }

package/dist/pipeline/index.d.ts

@@ -31,6 +31,8 @@ export type { LifecycleHooks, SystemHookDef, SystemHooks } from "./lifecycle-pip
 export { createLifecycleHooks } from "./lifecycle-pipeline.js";
 export type { MspRebuildDeps } from "./msp-rebuild.js";
 export { rebuildMultiStreamProjection } from "./msp-rebuild.js";
+export type { MultiStreamApplyContext, MultiStreamApplyContextDeps, } from "./multi-stream-apply-context.js";
+export { createMultiStreamApplyContext } from "./multi-stream-apply-context.js";
 export { assertNotifyTargetsOwnTenant, createDeferringNotify } from "./notify-scope.js";
 export type { ProjectionProgress, RebuildResult } from "./projection-rebuild.js";
 export { getAllProjectionProgress, getProjectionState, listProjectionsWithState, rebuildProjection, } from "./projection-rebuild.js";

package/dist/pipeline/index.js

@@ -16,6 +16,7 @@ export { createIdempotencyGuard } from "./idempotency.js";
 export { assertInstructionFieldWriteAllowed, assertIrreversibleOperationAllowed, isIrreversibleEntityVerb, } from "./irreversible-operation-gate.js";
 export { createLifecycleHooks } from "./lifecycle-pipeline.js";
 export { rebuildMultiStreamProjection } from "./msp-rebuild.js";
+export { createMultiStreamApplyContext } from "./multi-stream-apply-context.js";
 export { assertNotifyTargetsOwnTenant, createDeferringNotify } from "./notify-scope.js";
 export { getAllProjectionProgress, getProjectionState, listProjectionsWithState, rebuildProjection, } from "./projection-rebuild.js";
 export { createProjectionStateTable, ProjectionStatuses, projectionStateTable, } from "./projection-state.js";

package/dist/pipeline/multi-stream-apply-context.d.ts

@@ -14,5 +14,6 @@ export type MultiStreamApplyContextDeps = {
     readonly files?: FileContext;
     readonly derivatives?: DerivativesContext;
     readonly secrets?: SecretsContext;
+    readonly jobs?: MultiStreamApplyContext["jobs"];
 };
 export declare function createMultiStreamApplyContext(deps: MultiStreamApplyContextDeps): MultiStreamApplyContext;

package/dist/pipeline/multi-stream-apply-context.js

@@ -7,6 +7,7 @@ export function createMultiStreamApplyContext(deps) {
         ...(deps.files ? { files: deps.files } : {}),
         ...(deps.derivatives ? { derivatives: deps.derivatives } : {}),
         ...(deps.secrets ? { secrets: deps.secrets } : {}),
+        ...(deps.jobs ? { jobs: deps.jobs } : {}),
         appendEvent: (async (args) => {
             await appendDomainEventCore({
                 registry: deps.registry,

package/dist/pipeline/notify-scope.js

@@ -23,8 +23,10 @@ export function createDeferringNotify(deps) {
             assertNotificationVariables(registry, notificationType, options.data);
         if (options.immediate === true)
             return notifyNow(notificationType, options);
+        // The hook runs after the handler returned; a caller reusing `data` meanwhile must not change what is sent.
+        const optionsAtCallTime = structuredClone(options);
         scheduleAfterCommit(async () => {
-            await notifyAfterCommit(notificationType, options);
+            await notifyAfterCommit(notificationType, optionsAtCallTime);
         });
         return { kind: "deferred" };
     }

package/dist/pipeline/pre-transaction-reservations.js

@@ -73,7 +73,8 @@ export async function reserveBeforeTransaction(ctx, commands, user, inheritedOri
             }
             let prepared;
             if (handler.beforeTransaction) {
-                const phase = await handler.beforeTransaction(event, applyBeforeTransactionReadOnly(handlerContext));
+                const phaseContext = await buildHandlerContext(ctx, command.type, user, origin, undefined, undefined, undefined, undefined, undefined, true);
+                const phase = await handler.beforeTransaction(event, applyBeforeTransactionReadOnly(phaseContext));
                 if (!phase.isSuccess) {
                     await releaseAll(ctx, releases);
                     return { isSuccess: false, error: phase.error, failedIndex: index };

package/dist/schema-cli.js

@@ -439,8 +439,19 @@ export async function runSchemaCli(argv, appCwd, out, options = {}) {
                 await reportLeftoverDroppedTables(db, migrationsDir, out);
                 return pending === 0 ? 0 : 1;
             }
+            catch (e) {
+                // Message only, never dbUrl: it can carry the password.
+                out.err(`  ✗ schema status failed: ${e instanceof Error ? e.message : String(e)}`);
+                out.err('  Check that DATABASE_URL is reachable and the database exists (the scaffold\'s docker-compose creates "app").');
+                return 1;
+            }
             finally {
-                await close();
+                try {
+                    await close();
+                }
+                catch {
+                    // The connection already failed and was reported above; a failing close must not throw again.
+                }
             }
         }
         default: {

package/dist/stack/db.d.ts

@@ -1,9 +1,9 @@
-import type { DbConnection } from "@cosmicdrift/kumiko-types/db-connection";
+import type { DbConnection, PgListenClient } from "@cosmicdrift/kumiko-types/db-connection";
 declare function requireEnv(name: string): string;
 export type TestDb = {
     db: DbConnection;
     outsideTransactionDb: DbConnection;
-    client: unknown;
+    client: PgListenClient;
     dbName: string;
     cleanup: () => Promise<void>;
 };

package/dist/stack/test-stack.js

@@ -275,7 +275,8 @@ export async function setupTestStack(options) {
             (appContext.redis === undefined || options.rateLimitNowMs !== undefined);
         const rateLimitFallback = needsOwnRateLimitResolver
             ? createRateLimitResolver({
-                redis: testRedis.redis,
+                // An app-supplied redis keeps buckets and app redis on the same instance.
+                redis: appContext.redis ?? testRedis.redis,
                 ...(options.rateLimitNowMs ? { nowMs: options.rateLimitNowMs } : {}),
             })
             : undefined;

package/dist/testing/index.d.ts

@@ -22,3 +22,4 @@ export { sharedItemEntity, sharedItemTable, sharedUserEntity, sharedUserTable, s
 export { sleep } from "./utils.js";
 export { waitFor } from "./wait-for.js";
 export { withoutAmbientTemporal } from "./without-ambient-temporal.js";
+export { zipWithEntries } from "./zip-fixture.js";

package/dist/testing/index.js

@@ -30,3 +30,4 @@ export { sharedItemEntity, sharedItemTable, sharedUserEntity, sharedUserTable, s
 export { sleep } from "./utils.js";
 export { waitFor } from "./wait-for.js";
 export { withoutAmbientTemporal } from "./without-ambient-temporal.js";
+export { zipWithEntries } from "./zip-fixture.js";

package/dist/testing/multipart-helper.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Serializes a FormData instance to multipart/form-data bytes.
+ *
+ * Returns the encoded body and the Content-Type header value (including the
+ * generated boundary). Pass both directly to app.request or fetch.
+ */
 export declare function buildMultipartBody(fd: FormData): Promise<{
     body: BodyInit;
     contentType: string;

package/dist/testing/multipart-helper.js

@@ -1,3 +1,4 @@
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 // Workarounds for Bun v1.3.x bun:test limitations with multipart/form-data.
 //
 // Two bugs combine to break file upload tests in bun:test:
@@ -19,7 +20,6 @@
  * Returns the encoded body and the Content-Type header value (including the
  * generated boundary). Pass both directly to app.request or fetch.
  */
-import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 export async function buildMultipartBody(fd) {
     const boundary = `KumikoBnd${Date.now()}${Math.random().toString(36).slice(2, 8)}`;
     const enc = new TextEncoder();

package/dist/testing/zip-fixture.d.ts

@@ -0,0 +1 @@
+export declare function zipWithEntries(...entryNames: readonly string[]): Uint8Array;

package/dist/testing/zip-fixture.js

@@ -0,0 +1,33 @@
+const LOCAL_HEADER_FIXED_LENGTH = 30;
+const CENTRAL_HEADER_FIXED_LENGTH = 46;
+const EOCD_LENGTH = 22;
+// Minimal stored ZIP (no compression, zero CRC): enough structure for readers that
+// walk the central directory. Not for extraction.
+export function zipWithEntries(...entryNames) {
+    const encoder = new TextEncoder();
+    const names = entryNames.map((name) => encoder.encode(name));
+    const localSize = names.reduce((sum, name) => sum + LOCAL_HEADER_FIXED_LENGTH + name.length, 0);
+    const centralSize = names.reduce((sum, name) => sum + CENTRAL_HEADER_FIXED_LENGTH + name.length, 0);
+    const bytes = new Uint8Array(localSize + centralSize + EOCD_LENGTH);
+    const view = new DataView(bytes.buffer);
+    let localOffset = 0;
+    let centralOffset = localSize;
+    for (const name of names) {
+        view.setUint32(localOffset, 0x04034b50, true);
+        view.setUint16(localOffset + 26, name.length, true);
+        bytes.set(name, localOffset + LOCAL_HEADER_FIXED_LENGTH);
+        view.setUint32(centralOffset, 0x02014b50, true);
+        view.setUint16(centralOffset + 28, name.length, true);
+        view.setUint32(centralOffset + 42, localOffset, true);
+        bytes.set(name, centralOffset + CENTRAL_HEADER_FIXED_LENGTH);
+        localOffset += LOCAL_HEADER_FIXED_LENGTH + name.length;
+        centralOffset += CENTRAL_HEADER_FIXED_LENGTH + name.length;
+    }
+    const eocdOffset = localSize + centralSize;
+    view.setUint32(eocdOffset, 0x06054b50, true);
+    view.setUint16(eocdOffset + 8, names.length, true);
+    view.setUint16(eocdOffset + 10, names.length, true);
+    view.setUint32(eocdOffset + 12, centralSize, true);
+    view.setUint32(eocdOffset + 16, localSize, true);
+    return bytes;
+}

package/dist/ui-types/card-column-roles.js

@@ -18,8 +18,10 @@ export function cardFileDisplayKind(type, renderer) {
 // boot validator so the validator counts exactly what the card would draw.
 // The first image column is the card's leading preview, neither title nor meta.
 export function cardColumnRoles(columns) {
-    const image = columns.find((col) => col.fileDisplay?.kind === "image");
-    const textColumns = columns.filter((col) => col !== image);
+    const isImage = (col) => col.fileDisplay?.kind === "image";
+    const image = columns.find((col) => isImage(col) && col.hideOnNarrow !== true);
+    // A narrow-hidden image must not turn into the title just because it is not the preview.
+    const textColumns = columns.filter((col) => col !== image && !(isImage(col) && col.hideOnNarrow === true));
     const title = textColumns.find((col) => col.highlighted === true) ?? textColumns[0];
     const status = textColumns.find((col) => col !== title && col.type === "select" && col.renderer === undefined);
     const meta = textColumns.filter((col) => col !== title && col !== status && col.hideOnNarrow !== true);

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

@@ -4,7 +4,7 @@ export { computeDerivedCellValue, roundDerivedCellValue } from "../engine/embedd
 export type { ParsedRefTarget } from "../engine/parse-ref-target.js";
 export { parseRefTarget } from "../engine/parse-ref-target.js";
 export type { FieldsOrGroupsSection, UnavailableSelectOption } from "../engine/screen-helpers.js";
-export { availableSelectOptions, evalFieldCondition, explicitListScreenId, findUnavailableSelectOptions, isExtensionEditSection, isFieldsEditSection, isFormatSpec, isRecordLocked, isWriteFormEditSection, normalizeEditField, normalizeListColumn, resolveNavParentScreen, sectionFieldSpecs, } from "../engine/screen-helpers.js";
+export { availableSelectOptions, evalFieldCondition, explicitListScreenId, findUnavailableSelectOptions, isExtensionEditSection, isFieldsEditSection, isFormatSpec, isRecordLocked, isUnchangedValue, isWriteFormEditSection, normalizeEditField, normalizeListColumn, resolveNavParentScreen, sectionFieldSpecs, } from "../engine/screen-helpers.js";
 export type { BooleanFieldDef, DateFieldDef, EmbeddedDerivedCellDef, EntityDefinition, FieldDefinition, FileFieldDef, FilesFieldDef, ImageFieldDef, ImagesFieldDef, NumberFieldDef, OptionsQueryPayload, OptionsQueryPayloadValue, SelectFieldDef, SelectOptionTone, TextFieldDef, } from "../engine/types/fields.js";
 export type { AccessRule, OpenToAllAccessRule, OpenToAllDeclaration, OpenToAllPersonalData, RoleAccessPersonalData, RoleAccessRule, } from "../engine/types/handlers.js";
 export { isOpenToAllGranted, isUiAccessGranted } from "../engine/types/handlers.js";

package/dist/ui-types/index.js

@@ -22,7 +22,7 @@
 export { NO_WIDGET_FIELD_TYPES } from "@cosmicdrift/kumiko-types/fields";
 export { computeDerivedCellValue, roundDerivedCellValue } from "../engine/embedded-derived.js";
 export { parseRefTarget } from "../engine/parse-ref-target.js";
-export { availableSelectOptions, evalFieldCondition, explicitListScreenId, findUnavailableSelectOptions, isExtensionEditSection, isFieldsEditSection, isFormatSpec, isRecordLocked, isWriteFormEditSection, normalizeEditField, normalizeListColumn, resolveNavParentScreen, sectionFieldSpecs, } from "../engine/screen-helpers.js";
+export { availableSelectOptions, evalFieldCondition, explicitListScreenId, findUnavailableSelectOptions, isExtensionEditSection, isFieldsEditSection, isFormatSpec, isRecordLocked, isUnchangedValue, isWriteFormEditSection, normalizeEditField, normalizeListColumn, resolveNavParentScreen, sectionFieldSpecs, } from "../engine/screen-helpers.js";
 export { isOpenToAllGranted, isUiAccessGranted } from "../engine/types/handlers.js";
 export { metricField, relatedListGroupHeaderLabel, relatedListGroupKey, } from "../engine/types/screen.js";
 export { ACTION_FORM_ENTITY, handlerFieldLabelKey, handlerTitleKey, PROJECTION_DETAIL_ENTITY, WRITE_FORM_SECTION_ENTITY, } from "../i18n/required-surface-keys.js";