@cosmicdrift/kumiko-testing 0.413.1 → 0.414.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,227 @@
1
+ // @runtime dev
2
+ import { createSseBroker, withFileProviderResolver } from "@cosmicdrift/kumiko-framework/api";
3
+ import { createRegistry } from "@cosmicdrift/kumiko-framework/engine";
4
+ import { createJobRunner, type JobRunner } from "@cosmicdrift/kumiko-framework/jobs";
5
+ import { createNoopProvider } from "@cosmicdrift/kumiko-framework/observability";
6
+ import { createEntityCache } from "@cosmicdrift/kumiko-framework/pipeline";
7
+ import {
8
+ type ClosableCacheSyncBus,
9
+ createLocalCacheSyncBus,
10
+ createRedisCacheSyncBus,
11
+ } from "@cosmicdrift/kumiko-framework/redis";
12
+ import { createInMemorySearchAdapter } from "@cosmicdrift/kumiko-framework/search";
13
+ import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
14
+ import type { Clock } from "@cosmicdrift/kumiko-types/tz-context";
15
+ import { createManualClock, type ManualClock } from "../helpers/manual-clock.ts";
16
+ import type { createJobFailureTracker } from "./drain-jobs.ts";
17
+ import { createEventCollector } from "./event-collector.ts";
18
+ import { queueNamePrefixForTestRedis, type TestRedis } from "./redis.ts";
19
+ import type { TestStackOptions } from "./test-stack.ts";
20
+ import type { StackStorage } from "./test-stack-storage.ts";
21
+
22
+ // Redis only where two stacks can actually disagree (avoids two extra
23
+ // Pub/Sub connections); otherwise a local bus so invalidation still works
24
+ // inside this stack. Passing it explicitly keeps buildServer from using its
25
+ // REDIS_URL default (an unnamespaced channel).
26
+ export function createStackCacheSync(
27
+ options: TestStackOptions,
28
+ testRedis: TestRedis,
29
+ ): ClosableCacheSyncBus {
30
+ return options.cacheSync || options.sharedRedisWith
31
+ ? createRedisCacheSyncBus({
32
+ redisUrl: testRedis.redisUrl,
33
+ channelPrefix: testRedis.keyPrefix,
34
+ })
35
+ : createLocalCacheSyncBus();
36
+ }
37
+
38
+ // A static `files.storageProvider` is wired as the per-tenant resolver — the
39
+ // framework test seam that doesn't require mounting config + file-foundation.
40
+ // (Bundled GDPR tests mount the real provider features instead.)
41
+ function isManualClock(value: unknown): value is ManualClock {
42
+ return (
43
+ isClock(value) &&
44
+ "set" in value &&
45
+ typeof value.set === "function" &&
46
+ "advance" in value &&
47
+ typeof value.advance === "function"
48
+ );
49
+ }
50
+
51
+ function isClock(value: unknown): value is Clock {
52
+ return (
53
+ typeof value === "object" && value !== null && "now" in value && typeof value.now === "function"
54
+ );
55
+ }
56
+
57
+ async function resolveStackFileProvider(
58
+ options: TestStackOptions,
59
+ testDb: StackStorage["testDb"],
60
+ readClock: () => unknown,
61
+ ): Promise<import("@cosmicdrift/kumiko-framework/files").FileProviderResolver | undefined> {
62
+ if (!options.files) return undefined;
63
+ const provider = options.files.storageProvider;
64
+ const { withUploadLedger } = await import("@cosmicdrift/kumiko-framework/files");
65
+ // Read per call: the clock arrives via extraContext, which is merged after this resolver is built.
66
+ const now = (): Temporal.Instant => {
67
+ const clock = readClock();
68
+ return isClock(clock) ? clock.now() : Temporal.Now.instant();
69
+ };
70
+ return withUploadLedger(() => Promise.resolve(provider), testDb.db, now);
71
+ }
72
+
73
+ function parseNow(now: NonNullable<TestStackOptions["now"]>): Temporal.Instant {
74
+ if (typeof now !== "string") return now;
75
+ try {
76
+ return Temporal.Instant.from(now);
77
+ } catch (error) {
78
+ throw new Error(
79
+ `setupTestStack: option "now" must be an ISO instant such as "2031-05-06T07:08:09Z", got "${now}"`,
80
+ { cause: error },
81
+ );
82
+ }
83
+ }
84
+
85
+ export async function buildStackServices(
86
+ options: TestStackOptions,
87
+ testDb: StackStorage["testDb"],
88
+ testRedis: TestRedis,
89
+ cacheSync: ClosableCacheSyncBus,
90
+ ) {
91
+ const searchAdapter = createInMemorySearchAdapter();
92
+ const events = createEventCollector();
93
+ const registry = createRegistry([...options.features]);
94
+
95
+ // Wire SSE broker with event collector — built early (not just before
96
+ // buildServer) because extraContext + the job context below both need it.
97
+ const sseBroker = options.sseBroker ?? createSseBroker();
98
+ sseBroker.addClient(
99
+ "tenant:00000000-0000-4000-8000-000000000001",
100
+ (event) => events.sse.push(event),
101
+ () => {},
102
+ );
103
+
104
+ const entityCache = createEntityCache(testRedis.redis, { ttlSeconds: 60 });
105
+ const extraContextClock: { current: unknown } = { current: undefined };
106
+ const fileProviderResolver = await resolveStackFileProvider(
107
+ options,
108
+ testDb,
109
+ () => extraContextClock.current,
110
+ );
111
+ const observability = options.observability ?? createNoopProvider();
112
+
113
+ // Same AppContext buildServer() gets below (db/redis/searchAdapter/
114
+ // entityCache/masterKeyProvider/fileProviderResolver/extraContext) —
115
+ // shared so the job context can't drift from the request-path context:
116
+ // a reduced `{ db, registry }` literal let jobs pass in tests while
117
+ // reaching for fields only prod's context has.
118
+ //
119
+ // effectiveFeatures deliberately stays OUT of appContext — prod never puts
120
+ // it there either (only dispatcherOptions.effectiveFeatures, consumed by
121
+ // the command-dispatcher — see buildJobRunnerWithHook in entrypoint/
122
+ // index.ts). Putting it here would reintroduce the exact test-vs-prod
123
+ // drift fixed: a job/handler reading `ctx.services.effectiveFeatures` would pass in
124
+ // tests and break in prod.
125
+ const manualClock =
126
+ options.now === undefined ? undefined : createManualClock(parseNow(options.now));
127
+ const extraContext =
128
+ typeof options.extraContext === "function"
129
+ ? options.extraContext({
130
+ registry,
131
+ // The raw pool, as in prod: request-time services keep the ambient request scope, so a tenant leak shows in tests.
132
+ db: testDb.db,
133
+ sseBroker,
134
+ redis: testRedis.redis,
135
+ })
136
+ : options.extraContext;
137
+ // The prod entrypoint resolves the mounted file-provider plugins before the job runner sees
138
+ // the context; without it a job's ctx.services.files is undefined only in tests.
139
+ const appContext = withFileProviderResolver(
140
+ registry,
141
+ {
142
+ db: testDb.db,
143
+ redis: testRedis.redis,
144
+ searchAdapter,
145
+ entityCache,
146
+ registry,
147
+ ...(options.masterKeyProvider ? { masterKeyProvider: options.masterKeyProvider } : {}),
148
+ ...(fileProviderResolver ? { _fileProviderResolver: fileProviderResolver } : {}),
149
+ ...(options.defaultLocale !== undefined && { defaultLocale: options.defaultLocale }),
150
+ ...(manualClock !== undefined && { clock: manualClock }),
151
+ ...extraContext,
152
+ },
153
+ // Same bus buildServer gets: the resolver built here is the one it reuses, so config and
154
+ // secret writes must reach its per-tenant provider cache through it.
155
+ cacheSync,
156
+ );
157
+ extraContextClock.current = extraContext?.["clock"] ?? manualClock;
158
+ const effectiveClock = isManualClock(extraContextClock.current)
159
+ ? extraContextClock.current
160
+ : undefined;
161
+ return {
162
+ searchAdapter,
163
+ events,
164
+ registry,
165
+ sseBroker,
166
+ entityCache,
167
+ observability,
168
+ appContext,
169
+ clock: effectiveClock,
170
+ };
171
+ }
172
+
173
+ export type StackServices = Awaited<ReturnType<typeof buildStackServices>>;
174
+
175
+ export type JobFailureTracker = ReturnType<typeof createJobFailureTracker>;
176
+
177
+ // Built before buildServer() so it can be merged into dispatcherOptions
178
+ // (write handlers' `ctx.services.jobRunner.dispatch(...)` and the afterCommit
179
+ // event-trigger hook both need it present at dispatcher-construction
180
+ // time, same as the prod entrypoint's buildJobRunnerWithHook). Uses the
181
+ // test-stack's own ephemeral redis — no separate `redisUrl` seam needed.
182
+ //
183
+ // context = appContext + tracer/meter, mirroring the prod entrypoint's
184
+ // `contextWithObservability(options.context, observability)`.
185
+ export function createStackJobRunner(
186
+ options: TestStackOptions,
187
+ services: StackServices,
188
+ testDb: StackStorage["testDb"],
189
+ testRedis: TestRedis,
190
+ jobFailureTracker: JobFailureTracker,
191
+ ): JobRunner | undefined {
192
+ const { registry, appContext, observability } = services;
193
+ if (!options.jobs || registry.getAllJobs().size === 0) return undefined;
194
+ const runLogger = options.jobs.runLogger?.({ registry, db: testDb.db });
195
+ return createJobRunner({
196
+ registry,
197
+ context: { ...appContext, tracer: observability.tracer, meter: observability.meter },
198
+ // The real REDIS_URL, not one rebuilt from `.options` — rebuilding it lost
199
+ // password/username/tls/path.
200
+ redisUrl: testRedis.redisUrl,
201
+ ...(options.jobs.consumerLane !== undefined && { consumerLane: options.jobs.consumerLane }),
202
+ queueNamePrefix:
203
+ options.jobs.queueNamePrefix ?? queueNamePrefixForTestRedis(testRedis.keyPrefix),
204
+ ...(options.jobs.getActiveTenantIds !== undefined && {
205
+ getActiveTenantIds: options.jobs.getActiveTenantIds,
206
+ }),
207
+ ...(runLogger?.onJobStart !== undefined && { onJobStart: runLogger.onJobStart }),
208
+ ...(runLogger?.onJobQueued !== undefined && { onJobQueued: runLogger.onJobQueued }),
209
+ ...(runLogger?.onJobDropped !== undefined && { onJobDropped: runLogger.onJobDropped }),
210
+ // Tracker fires in finally: drainJobs wakes on it, so the log row must
211
+ // be written first, and a throwing logger must not swallow the signal.
212
+ onJobComplete: async (jobName, jobId, ...rest) => {
213
+ try {
214
+ await runLogger?.onJobComplete?.(jobName, jobId, ...rest);
215
+ } finally {
216
+ jobFailureTracker.onJobComplete(jobName, jobId);
217
+ }
218
+ },
219
+ onJobFailed: async (jobName, jobId, error, ...rest) => {
220
+ try {
221
+ await runLogger?.onJobFailed?.(jobName, jobId, error, ...rest);
222
+ } finally {
223
+ jobFailureTracker.onJobFailed(jobName, jobId, error);
224
+ }
225
+ },
226
+ });
227
+ }
@@ -0,0 +1,236 @@
1
+ // @runtime dev
2
+ import { createHash } from "node:crypto";
3
+ import {
4
+ assertRowLevelSecurityBootState,
5
+ type DbConnection,
6
+ type EntityTableMeta,
7
+ knownTablesOf,
8
+ type RowLevelSecurityMode,
9
+ } from "@cosmicdrift/kumiko-framework/db";
10
+ import { validateBoot } from "@cosmicdrift/kumiko-framework/engine";
11
+ import type { FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine/types";
12
+ import {
13
+ createArchivedStreamsTable,
14
+ createEventsTable,
15
+ } from "@cosmicdrift/kumiko-framework/event-store";
16
+ import {
17
+ unsafePushTables,
18
+ validateNavBootSubset,
19
+ validateOwnershipBoot,
20
+ } from "@cosmicdrift/kumiko-framework/internal/stack-support";
21
+ import {
22
+ createTestDb,
23
+ ensureTestDbTemplate,
24
+ TEST_APPLICATION_ROLE,
25
+ TEST_DB_TEMPLATE_RUN_ENV,
26
+ testDbTemplatePrefix,
27
+ } from "./db.ts";
28
+ import { createTestRedis, type TestRedis } from "./redis.ts";
29
+ import type { TestStackOptions } from "./test-stack.ts";
30
+
31
+ type MfaTokenSecretBinder = (
32
+ masterSecret: string,
33
+ env: Readonly<Record<string, string | undefined>>,
34
+ ) => void;
35
+
36
+ // Mirrors bindMfaTokenSecretsFromFeature from bundled-features/auth-mfa,
37
+ // which this package cannot import: bundled-features is an optional peer.
38
+ function isMfaTokenSecretBinder(value: unknown): value is MfaTokenSecretBinder {
39
+ return typeof value === "function";
40
+ }
41
+
42
+ // The env is empty on purpose: test secrets derive from jwtSecret,
43
+ // independent of the host env.
44
+ function bindMfaTokenSecrets(features: readonly FeatureDefinition[], jwtSecret: string): void {
45
+ for (const { exports } of features) {
46
+ if (typeof exports !== "object" || exports === null || !("bindTokenSecrets" in exports)) {
47
+ continue;
48
+ }
49
+ const { bindTokenSecrets } = exports;
50
+ if (isMfaTokenSecretBinder(bindTokenSecrets)) bindTokenSecrets(jwtSecret, {});
51
+ }
52
+ }
53
+
54
+ // Same table list as `kumiko schema generate` (collectTableMetas) — divergence
55
+ // caused a production crash and left r.entity() tables missing.
56
+ async function collectStackTableMetas(
57
+ options: TestStackOptions,
58
+ ): Promise<readonly EntityTableMeta[]> {
59
+ const { collectTableMetas, enumerateFeatureTableSources, extractTableInfo } = await import(
60
+ "@cosmicdrift/kumiko-framework/db"
61
+ );
62
+ const metas = collectTableMetas(options.features);
63
+ if (options.entityTables !== false) return metas;
64
+ const nonEntityNames = new Set(
65
+ options.features.flatMap((f) =>
66
+ enumerateFeatureTableSources(f).map((s) => extractTableInfo(s.table).name),
67
+ ),
68
+ );
69
+ return metas.filter((m) => nonEntityNames.has(m.tableName));
70
+ }
71
+
72
+ async function pushStackSchema(
73
+ db: DbConnection,
74
+ metas: readonly EntityTableMeta[],
75
+ withFileTables: boolean,
76
+ ): Promise<void> {
77
+ // Every ES-entity writes events via createEventStoreExecutor in the
78
+ // feature's write handlers. Auto-create the events table so every
79
+ // setupTestStack call is ready for writes without needing a manual
80
+ // createEventsTable().
81
+ await createEventsTable(db);
82
+ // Archive-stream metadata — needed by ctx.events.append's archive guard and
83
+ // loadAggregate's default-skip. Idempotent, so production boot running
84
+ // the same call is fine.
85
+ await createArchivedStreamsTable(db);
86
+
87
+ // Framework state for projection rebuild/status + event-consumer cursors.
88
+ // Idempotent — production boot flows run the same calls.
89
+ const { createProjectionStateTable, createEventConsumerStateTable } = await import(
90
+ "@cosmicdrift/kumiko-framework/pipeline"
91
+ );
92
+ await createProjectionStateTable(db);
93
+ await createEventConsumerStateTable(db);
94
+
95
+ // Files support: when a provider is registered, the fileRefs table must
96
+ // exist before the first upload. Skipped when no provider — the table
97
+ // stays off tenant test DBs that never touch files.
98
+ if (withFileTables) {
99
+ const { fileRefsTable, fileUploadLedgerTable } = await import(
100
+ "@cosmicdrift/kumiko-framework/files"
101
+ );
102
+ await unsafePushTables(db, { fileRefsTable, fileUploadLedgerTable });
103
+ }
104
+
105
+ const { tableExists } = await import("@cosmicdrift/kumiko-framework/db");
106
+ const missing: Record<string, unknown> = {};
107
+ for (const meta of metas) {
108
+ if (await tableExists(db, `public.${meta.tableName}`)) continue;
109
+ missing[meta.tableName] = meta;
110
+ }
111
+ if (Object.keys(missing).length > 0) {
112
+ await unsafePushTables(db, missing);
113
+ }
114
+ }
115
+
116
+ // Only inside an integration-runner run: the framework tables above are not part
117
+ // of the fingerprint, which holds because one run never sees two framework versions.
118
+ async function resolveTestDbTemplateName(
119
+ options: TestStackOptions,
120
+ metas: readonly EntityTableMeta[],
121
+ withFileTables: boolean,
122
+ rowLevelSecurity: RowLevelSecurityMode,
123
+ ): Promise<string | undefined> {
124
+ const runId = process.env[TEST_DB_TEMPLATE_RUN_ENV];
125
+ if (runId === undefined || options.persistentDb === true || options.dbName !== undefined) {
126
+ return undefined;
127
+ }
128
+ const { renderTablesDdl } = await import("@cosmicdrift/kumiko-framework/db");
129
+ const fingerprint = createHash("sha256")
130
+ .update(
131
+ JSON.stringify({
132
+ withFileTables,
133
+ rowLevelSecurity,
134
+ role: rowLevelSecurity === "on" ? TEST_APPLICATION_ROLE : "superuser",
135
+ ddl: renderTablesDdl(metas, { rowLevelSecurity }),
136
+ }),
137
+ )
138
+ .digest("hex")
139
+ .slice(0, 16);
140
+ return `${testDbTemplatePrefix(runId)}${fingerprint}`;
141
+ }
142
+
143
+ // Best-effort and sequential: a broken cleanup must never mask the setup error the caller rethrows.
144
+ export async function runCleanupsIgnoringErrors(
145
+ cleanups: ReadonlyArray<() => Promise<void>>,
146
+ ): Promise<void> {
147
+ for (const cleanup of cleanups) {
148
+ try {
149
+ await cleanup();
150
+ } catch {
151
+ // ignore — the setup error is the one that matters
152
+ }
153
+ }
154
+ }
155
+
156
+ export async function validateStackFeatures(
157
+ options: TestStackOptions,
158
+ jwtSecret: string,
159
+ ): Promise<void> {
160
+ // Install the Temporal polyfill before feature code runs. Idempotent: the
161
+ // production server boot does the same. A no-op on runtimes with native Temporal.
162
+ const { ensureTemporalPolyfill } = await import("@cosmicdrift/kumiko-framework/time");
163
+ await ensureTemporalPolyfill();
164
+
165
+ // Ownership boot-guards (unqualified where-fragments, where-rules on the
166
+ // write path) otherwise run only in the prod boot via validateBoot, leaving
167
+ // every test stack blind to a broken access map.
168
+ // Runs after the polyfill (buildEntityTable needs it to derive the probe
169
+ // columns) and before the ephemeral DB/Redis exist, so a throw can't leak
170
+ // a database that nothing will clean up.
171
+ validateOwnershipBoot(options.features);
172
+ // Nav/workspace refs fail the prod boot too; the subset check tolerates refs into unmounted features.
173
+ validateNavBootSubset(options.features);
174
+ if (options.validateBoot === "full") validateBoot(options.features);
175
+ bindMfaTokenSecrets(options.features, jwtSecret);
176
+ }
177
+
178
+ export type StackStorage = {
179
+ readonly testDb: Awaited<ReturnType<typeof createTestDb>>;
180
+ readonly testRedis: TestRedis;
181
+ };
182
+
183
+ export async function provisionStackStorage(options: TestStackOptions): Promise<StackStorage> {
184
+ const stackTableMetas = await collectStackTableMetas(options);
185
+ const withFileTables = options.files !== undefined;
186
+ const buildStackSchema = (db: DbConnection): Promise<void> =>
187
+ pushStackSchema(db, stackTableMetas, withFileTables);
188
+ const rowLevelSecurity = options.rowLevelSecurity ?? "on";
189
+ const applicationRole = rowLevelSecurity === "on";
190
+ const templateDbName = await resolveTestDbTemplateName(
191
+ options,
192
+ stackTableMetas,
193
+ withFileTables,
194
+ rowLevelSecurity,
195
+ );
196
+ if (templateDbName !== undefined) {
197
+ await ensureTestDbTemplate(templateDbName, buildStackSchema, { applicationRole });
198
+ }
199
+
200
+ // Forward db-name/persistent-flag through to createTestDb. The
201
+ // defaults (undefined dbName, persistent:false) keep the legacy
202
+ // test contract: fresh kumiko_test_<random> DB per setup, dropped
203
+ // on cleanup.
204
+ const [testDb, testRedis] = await Promise.all([
205
+ createTestDb({
206
+ ...(options.dbName !== undefined && { dbName: options.dbName }),
207
+ ...(options.persistentDb !== undefined && { persistent: options.persistentDb }),
208
+ ...(options.dbPoolMax !== undefined && { poolMax: options.dbPoolMax }),
209
+ ...(options.outsideTransactionPoolMax !== undefined && {
210
+ outsideTransactionPoolMax: options.outsideTransactionPoolMax,
211
+ }),
212
+ ...(templateDbName !== undefined && { templateDbName }),
213
+ applicationRole,
214
+ }),
215
+ createTestRedis(
216
+ options.sharedRedisWith && { borrowKeyPrefix: options.sharedRedisWith.redis.keyPrefix },
217
+ ),
218
+ ]);
219
+
220
+ // Any throw in this DDL region must still drop the just-created ephemeral
221
+ // DB/Redis — the caller never gets the stack object back to call
222
+ // cleanup() itself (same "leaked ephemeral DB" failure class as the later
223
+ // try/catch in setupTestStack, but for setup that runs before that try starts).
224
+ try {
225
+ if (templateDbName === undefined) await buildStackSchema(testDb.db);
226
+ await assertRowLevelSecurityBootState(
227
+ testDb.db,
228
+ rowLevelSecurity,
229
+ knownTablesOf(options.features),
230
+ );
231
+ } catch (error) {
232
+ await runCleanupsIgnoringErrors([() => testDb.cleanup(), () => testRedis.cleanup()]);
233
+ throw error;
234
+ }
235
+ return { testDb, testRedis };
236
+ }
@@ -18,20 +18,24 @@ import type {
18
18
  } from "@cosmicdrift/kumiko-framework/pipeline";
19
19
  import type { ClosableCacheSyncBus } from "@cosmicdrift/kumiko-framework/redis";
20
20
  import type { SearchAdapter } from "@cosmicdrift/kumiko-framework/search";
21
+ import type { Temporal } from "@cosmicdrift/kumiko-types/temporal";
21
22
  import type { Hono } from "hono";
23
+ import type { ManualClock } from "../helpers/manual-clock.ts";
22
24
  import { createJobFailureTracker } from "./drain-jobs.ts";
23
25
  import type { EventCollector } from "./event-collector.ts";
24
26
  import type { TestRedis } from "./redis.ts";
25
27
  import type { RequestHelper } from "./request-helper.ts";
28
+ import { startStackServer } from "./test-stack-server.ts";
26
29
  import {
27
30
  buildStackServices,
28
31
  createStackCacheSync,
29
32
  createStackJobRunner,
33
+ } from "./test-stack-services.ts";
34
+ import {
30
35
  provisionStackStorage,
31
36
  runCleanupsIgnoringErrors,
32
- startStackServer,
33
37
  validateStackFeatures,
34
- } from "./test-stack-setup.ts";
38
+ } from "./test-stack-storage.ts";
35
39
 
36
40
  export type TestStack = {
37
41
  app: Hono;
@@ -66,6 +70,8 @@ export type TestStack = {
66
70
  // `{ db, registry }` literal — that's the drift, and it makes an
67
71
  // event-triggered job reaching for ctx.services.files die where the request path works.
68
72
  context: AppContext;
73
+ /** The effective manual clock behind `ctx.tz.now()`: `extraContext.clock` when it is one, else the clock created from `options.now`; absent when neither is manual. */
74
+ clock?: ManualClock;
69
75
  // Present whenever a system consumer (SSE, Search) or
70
76
  // r.multiStreamProjection is wired. Tests drain it via runOnce() (or the
71
77
  // drainEventConsumers helper for a named-consumer backlog) for
@@ -108,6 +114,8 @@ export type TestStackOptions = {
108
114
  * Can be a function receiving (registry, db, sseBroker) for late binding. */
109
115
  /** Boot default locale (BCP-47) merged into AppContext before extraContext. */
110
116
  defaultLocale?: string;
117
+ /** Fixed wall clock for `ctx.tz.now()`: becomes a manual clock merged into the AppContext as `clock`; an `extraContext.clock` wins. */
118
+ now?: string | Temporal.Instant;
111
119
  extraContext?:
112
120
  | Record<string, unknown>
113
121
  | ((deps: {
@@ -270,21 +278,20 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
270
278
  const enabledHooks = options.systemHooks ?? ["sse", "search"];
271
279
  await validateStackFeatures(options, jwtSecret);
272
280
  const { testDb, testRedis } = await provisionStackStorage(options);
273
- const cacheSync = createStackCacheSync(options, testRedis);
274
- const services = await buildStackServices(options, testDb, testRedis, cacheSync);
275
- // Fed to the job runner's onJobComplete/onJobFailed so drainJobs()
276
- // can tell a job's final outcome apart from an attempt that will retry —
277
- // built regardless of whether a runner ends up existing, so the returned
278
- // drainJobs() closure always has one to read.
279
- const jobFailureTracker = createJobFailureTracker();
280
- const jobRunner = createStackJobRunner(options, services, testDb, testRedis, jobFailureTracker);
281
-
282
- // From here on, any throw must stop a jobRunner that was already created
283
- // above (createJobRunner() itself opens live BullMQ Queue/lock Redis
284
- // connections, .start() adds a live worker) — otherwise a failing
285
- // buildServer()/search-config/etc. leaks that connection and the test
286
- // process hangs on exit.
281
+ // Declared before the try so the catch only cleans up what already exists:
282
+ // the extraContext/runLogger factories are caller code and can throw, and
283
+ // createJobRunner() opens live BullMQ Redis connections.
284
+ let cacheSync: ClosableCacheSyncBus | undefined;
285
+ let jobRunner: JobRunner | undefined;
287
286
  try {
287
+ cacheSync = createStackCacheSync(options, testRedis);
288
+ const services = await buildStackServices(options, testDb, testRedis, cacheSync);
289
+ // Fed to the job runner's onJobComplete/onJobFailed so drainJobs()
290
+ // can tell a job's final outcome apart from an attempt that will retry —
291
+ // built regardless of whether a runner ends up existing, so the returned
292
+ // drainJobs() closure always has one to read.
293
+ const jobFailureTracker = createJobFailureTracker();
294
+ jobRunner = createStackJobRunner(options, services, testDb, testRedis, jobFailureTracker);
288
295
  return await startStackServer({
289
296
  options,
290
297
  jwtSecret,
@@ -299,16 +306,18 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
299
306
  } catch (error) {
300
307
  // Best-effort — a broken jobRunner.stop()/cleanup() must never mask the
301
308
  // real setup failure below. testDb/testRedis are created before this
302
- // try even starts, so a throw anywhere in setup (buildServer,
303
- // search-config, ...) would otherwise leak their open pg/ioredis
304
- // sockets — the caller never gets the stack object back to call
309
+ // try even starts, so a throw anywhere in setup (extraContext,
310
+ // buildServer, search-config, ...) would otherwise leak their open
311
+ // pg/ioredis sockets — the caller never gets the stack object back to call
305
312
  // cleanup() itself, which is the same "hangs on exit" failure class
306
313
  // this function exists to prevent.
307
314
  await runCleanupsIgnoringErrors([
308
315
  async () => {
309
316
  if (jobRunner) await jobRunner.stop();
310
317
  },
311
- () => cacheSync.close(),
318
+ async () => {
319
+ if (cacheSync) await cacheSync.close();
320
+ },
312
321
  () => testDb.cleanup(),
313
322
  () => testRedis.cleanup(),
314
323
  ]);