OpenPanel is an open-source web and product analytics platform, an open-source alternative to Mixpanel with optional self-hosting.
ralph(M9-001): jobs.registry: all 7 queues + envelope on for producers + compat hooks proven
ralph896d368d7567
diff --git a/apps/api/e2e/README.md b/apps/api/e2e/README.mdindex 2464532d1..8b4f40333 100644--- a/apps/api/e2e/README.md+++ b/apps/api/e2e/README.md@@ -318,3 +318,24 @@ consumer code paths in a way expected to cost throughput — `M8-006`'scorrectness checkpoint (`0f8d956a`) already proved the ported path behavesidentically to the one BENCH-001 measured; this run's job was only to attach anumber to it.++## `legacy-job-proof.sh` — the P9 jobs cutover proof (M9-001)++Independent of the session harnesses and of `pnpm dev`: it needs only Redis.++```bash+bash apps/api/e2e/legacy-job-proof.sh+```++Writes one **V1-shaped** job per queue straight into Redis (V1's exact+`Queue.add(name, data)`, dumping the stored bytes to show there is no+`{payload, meta}` envelope on them), then starts the V2 workers over the real+`jobs.registry` and asserts every one is resolved through its `compat` hook to+the right V2 job name and payload — plus the other direction, a producer-+enqueued envelope whose `requestId` reaches the handler's logger.++It runs on a `-m9001proof` queue-key namespace so it cannot touch the shared+dev Redis's live queues, and it refuses to start if the event/group buffers are+non-empty (the real `flushEvents` handler it runs would drain them). The+un-namespaced keys' byte-identity is pinned separately by+`packages/core/src/jobs/naming.test.ts`.diff --git a/apps/api/e2e/legacy-job-proof.sh b/apps/api/e2e/legacy-job-proof.shnew file mode 100755index 000000000..31ad1bb37--- /dev/null+++ b/apps/api/e2e/legacy-job-proof.sh@@ -0,0 +1,18 @@+#!/usr/bin/env bash+# M9-001 acceptance proof (playbook rule 1: a runtime claim gets a runnable+# proof). Loads the repo .env for REDIS_URL, then runs the proof under Bun.+#+# bash apps/api/e2e/legacy-job-proof.sh+set -u++REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"+cd "$REPO_ROOT" || exit 1++if [ -f .env ]; then+ set -a+ # shellcheck disable=SC1091+ . ./.env+ set +a+fi++exec bun run apps/api/e2e/legacy-job-proof.tsdiff --git a/apps/api/e2e/legacy-job-proof.ts b/apps/api/e2e/legacy-job-proof.tsnew file mode 100644index 000000000..f52ecbbd2--- /dev/null+++ b/apps/api/e2e/legacy-job-proof.ts@@ -0,0 +1,513 @@+/**+ * M9-001 acceptance proof: a LEGACY-shaped job already sitting in Redis is+ * still picked up and run by the V2 worker, with no drain and no rename+ * (ADR-005). Plus the other direction — a job the V2 producer enqueues+ * carries the `{payload, meta}` envelope and its `requestId` reaches the+ * handler's logger (ADR-018 R1).+ *+ * What is real here: the registry (`queues`), every `compat` hook, every job+ * payload schema, `resolveJob`, BullMQ, and Redis. The legacy jobs are put in+ * Redis by `Queue.add(name, data)` with V1's exact data — byte-for-byte the+ * call `packages/queue`'s producers make — before any worker starts, so they+ * are genuinely waiting on the list when the worker connects.+ *+ * Two deliberate narrowings, both stated in the output:+ *+ * 1. It runs on a `-m9001proof` queue-key namespace, not on the shared dev+ * Redis's live `cron`/`sessions`/… keys, so it can neither consume nor be+ * confused by whatever the golden harness left there. Only the key string+ * differs; the un-namespaced keys' byte-identity is pinned separately by+ * `packages/core/src/jobs/naming.test.ts`.+ * 2. `cron` runs its REAL handlers over the REAL boot buffers. The other six+ * queues' handlers reach `ctx.services`, which needs the db/ch clients+ * `AppDeps` does not carry until M9-002/M9-003, so for those six the+ * handler body is a recorder — everything up to and including the handler+ * lookup is the real thing.+ *+ * Run: `bash apps/api/e2e/legacy-job-proof.sh`+ */++process.env.TZ = 'UTC';++import {+ type AnyJob,+ type AppDeps,+ createBuffers,+ createProducers,+ type QueueDefinition,+ type Queues,+ queueKey,+ queues,+ startWorkers,+} from '@openpanel/core';+import { produceIncomingEvent } from '@openpanel/queue';+import { Redis } from '@openpanel/redis';+import pino from 'pino';++/** Isolates the proof from the shared dev Redis — see the header. */+const NAMESPACE = 'm9001proof';+const REDIS_URL = process.env.REDIS_URL || 'redis://127.0.0.1:6379';+const JOB_WAIT_TIMEOUT_MS = 20_000;+const JOB_POLL_INTERVAL_MS = 100;+const REAL_HANDLER_QUEUE = 'cron';++type QueueKey = keyof Queues;++interface LegacyCase {+ queue: QueueKey;+ /** The BullMQ job name V1 put on the wire. */+ wireName: string;+ /** V1's job data, verbatim (packages/queue/src/queues.ts). */+ data: unknown;+ /** The V2 job the compat hook must resolve it to. */+ expectJob: string;+ expectPayload: unknown;+}++// One per queue. Every `data` below is a V1 payload type from+// packages/queue/src/queues.ts; `undefined` fields are omitted because JSON+// drops them, which is exactly what is in Redis today.+const LEGACY_CASES: LegacyCase[] = [+ {+ queue: 'cron',+ wireName: 'flushEvents',+ data: { type: 'flushEvents' },+ expectJob: 'flushEvents',+ expectPayload: null,+ },+ {+ queue: 'sessions',+ wireName: 'session',+ data: {+ type: 'createSessionEnd',+ payload: { projectId: 'proj_m9001', deviceId: 'dev_m9001' },+ snapshot: {+ id: 'ses_m9001',+ project_id: 'proj_m9001',+ device_id: 'dev_m9001',+ ended_at: '2026-09-05 00:00:00',+ },+ },+ expectJob: 'session',+ expectPayload: {+ event: { projectId: 'proj_m9001', deviceId: 'dev_m9001' },+ snapshot: {+ id: 'ses_m9001',+ project_id: 'proj_m9001',+ device_id: 'dev_m9001',+ ended_at: '2026-09-05 00:00:00',+ },+ },+ },+ {+ queue: 'notification',+ wireName: 'sendNotification',+ data: {+ type: 'sendNotification',+ payload: {+ notification: {+ projectId: 'proj_m9001',+ title: 'legacy',+ message: 'still processed',+ },+ },+ },+ expectJob: 'sendNotification',+ expectPayload: {+ notification: {+ projectId: 'proj_m9001',+ title: 'legacy',+ message: 'still processed',+ },+ },+ },+ {+ queue: 'import',+ wireName: 'import',+ data: { type: 'import', payload: { importId: 'imp_m9001' } },+ expectJob: 'import',+ expectPayload: { importId: 'imp_m9001' },+ },+ {+ queue: 'insights',+ wireName: 'insightsProject',+ data: {+ type: 'insightsProject',+ payload: { projectId: 'proj_m9001', date: '2026-09-05' },+ },+ expectJob: 'insightsProject',+ expectPayload: { projectId: 'proj_m9001', date: '2026-09-05' },+ },+ {+ queue: 'gsc',+ wireName: 'gscProjectBackfill',+ data: {+ type: 'gscProjectBackfill',+ payload: { projectId: 'proj_m9001' },+ },+ expectJob: 'gscProjectBackfill',+ expectPayload: { projectId: 'proj_m9001' },+ },+ {+ // The one V1 payload with no discriminant at all — a bare `{cohortId}`,+ // which must NOT be mistaken for an envelope.+ queue: 'cohortCompute',+ wireName: 'cohortCompute',+ data: { cohortId: 'coh_m9001' },+ expectJob: 'cohortCompute',+ expectPayload: { cohortId: 'coh_m9001' },+ },+];++interface HandlerRun {+ queue: string;+ job: string;+ payload: unknown;+ requestId: string;+}++const runs: HandlerRun[] = [];+const logLines: string[] = [];+let failures = 0;++function pass(message: string) {+ process.stdout.write(`PASS: ${message}\n`);+}++function fail(message: string) {+ failures += 1;+ process.stdout.write(`FAIL: ${message}\n`);+}++function check(condition: boolean, message: string) {+ if (condition) {+ pass(message);+ } else {+ fail(message);+ }+}++/** Both records every line and lets it out, so the run is readable live. */+const logger = pino(+ { name: 'legacy-job-proof', level: 'debug' },+ {+ write: (line: string) => {+ logLines.push(line.trimEnd());+ process.stdout.write(line);+ },+ }+);++/**+ * The six queues whose real handlers need `ctx.services`. Only the handler+ * body is replaced: the queue's `compat` hook, `defaults`, `worker` settings+ * and every job's payload schema are the registry's own.+ */+function recordingCopy(definition: QueueDefinition): QueueDefinition {+ const jobs = Object.fromEntries(+ Object.entries(definition.jobs).map(([name, job]) => [+ name,+ {+ ...(job as AnyJob),+ queue: definition.name,+ name,+ handler: (async (args: {+ payload: unknown;+ ctx: { requestId: string };+ }) => {+ runs.push({+ queue: definition.name,+ job: name,+ payload: args.payload,+ requestId: args.ctx.requestId,+ });+ }) as AnyJob['handler'],+ },+ ])+ ) as QueueDefinition['jobs'];++ return { ...definition, jobs };+}++/**+ * Structurally identical to `queues` — same keys, same queue names, same+ * schemas — so the typed producer surface survives the cast.+ */+function proofRegistry(): Queues {+ return Object.fromEntries(+ Object.entries(queues).map(([key, definition]) => [+ key,+ key === REAL_HANDLER_QUEUE+ ? (definition as QueueDefinition)+ : recordingCopy(definition as QueueDefinition),+ ])+ ) as unknown as Queues;+}++function delay(ms: number): Promise<void> {+ return new Promise((resolve) => setTimeout(resolve, ms));+}++async function main() {+ const connections: Redis[] = [];+ const newConnection = () => {+ // BullMQ requires `maxRetriesPerRequest: null`; V1's `getRedisQueue` sets+ // the same three options.+ const client = new Redis(REDIS_URL, {+ maxRetriesPerRequest: null,+ enableReadyCheck: false,+ enableOfflineQueue: true,+ });+ client.on('error', (error) =>+ logger.error({ err: error }, 'proof redis error')+ );+ connections.push(client);+ return client;+ };++ const producerConnection = newConnection();+ const registry = proofRegistry();++ const producers = createProducers(registry, {+ connection: producerConnection,+ namespace: NAMESPACE,+ logger,+ });++ const buffers = createBuffers({+ createLogger: (name) => logger.child({ name }),+ isCronPaused: async () => false,+ });++ const deps: AppDeps = {+ db: undefined,+ ch: undefined,+ redis: undefined,+ clients: undefined,+ buffers,+ producers,+ produceIncomingEvent,+ logger,+ config: { selfHosted: false },+ };++ process.stdout.write(+ '\n--- keys ------------------------------------------------------\n' ++ `production key for 'cron' : ${queueKey('cron')}\n` ++ `key this proof runs on : ${queueKey('cron', { namespace: NAMESPACE })}\n`+ );++ // Never drain a buffer somebody else filled: the real `flushEvents` /+ // `flushGroups` handlers below write to ClickHouse if their list is+ // non-empty, and the buffers' Redis keys are fixed names on the shared+ // client — a namespace cannot isolate them.+ const buffered =+ (await buffers.event.getBufferSize()) ++ (await buffers.group.getBufferSize());+ if (buffered !== 0) {+ process.stdout.write(+ `\nABORT: the shared event/group buffers hold ${buffered} rows; running the real flush handlers would drain them. Refusing.\n`+ );+ await producers.close();+ for (const client of connections) {+ client.disconnect();+ }+ process.exit(1);+ }++ const queueByName = new Map(+ producers.bullQueues.map((queue) => [queue.name, queue])+ );+ const bullFor = (key: QueueKey) => {+ const queue = queueByName.get(queueKey(key, { namespace: NAMESPACE }));+ if (!queue) {+ throw new Error(`no bull queue for '${key}'`);+ }+ return queue;+ };++ // --- 1. Put the legacy jobs in Redis, before any worker exists -----------++ process.stdout.write(+ '\n--- legacy jobs written to Redis (raw stored bytes) -----------\n'+ );++ const enqueued: { legacyCase: LegacyCase; jobId: string }[] = [];+ for (const legacyCase of LEGACY_CASES) {+ const bull = bullFor(legacyCase.queue);+ const job = await bull.add(legacyCase.wireName, legacyCase.data as object);+ if (!job.id) {+ throw new Error(`no job id for ${legacyCase.queue}`);+ }+ enqueued.push({ legacyCase, jobId: job.id });++ const stored = await producerConnection.hget(+ `bull:${bull.name}:${job.id}`,+ 'data'+ );+ process.stdout.write(+ `${legacyCase.queue.padEnd(14)} name=${legacyCase.wireName.padEnd(19)} data=${stored}\n`+ );+ check(+ stored !== null && !stored.includes('"meta"'),+ `${legacyCase.queue}: stored bytes carry no envelope (V1 shape)`+ );+ }++ // --- 2. One envelope job, from the V2 producer, for the round trip -------++ const requestId = 'm9001proof-req';+ const envelopeJobId = await producers+ .scope({ requestId })+ .cron.flushGroups.add(null);+ const envelopeStored = await producerConnection.hget(+ `bull:${bullFor('cron').name}:${envelopeJobId}`,+ 'data'+ );+ process.stdout.write(+ '\n--- envelope job written by the V2 producer -------------------\n' ++ `cron name=flushGroups data=${envelopeStored}\n`+ );+ check(+ envelopeStored === `{"payload":null,"meta":{"requestId":"${requestId}"}}`,+ 'producer stores {payload, meta} with the scoped requestId'+ );++ // --- 3. Now start the workers -------------------------------------------++ process.stdout.write(+ '\n--- worker log ------------------------------------------------\n'+ );++ const workers = startWorkers({+ definitions: registry,+ deps,+ createConnection: () => newConnection(),+ namespace: NAMESPACE,+ onTerminalFailure: (failure) =>+ fail(+ `${failure.queue}/${failure.job} failed terminally: ${failure.error.message}`+ ),+ });++ /**+ * `sessions` carries `removeOnComplete: true`, so a completed job is gone+ * from Redis rather than marked finished — the job was already added, so a+ * disappearance is a completion. A terminal failure would leave the job in+ * the failed set (and fire `onTerminalFailure`), not delete it.+ */+ const waitForCompletion = async (key: QueueKey, jobId: string) => {+ const bull = bullFor(key);+ const deadline = Date.now() + JOB_WAIT_TIMEOUT_MS;+ while (Date.now() < deadline) {+ const job = await bull.getJob(jobId);+ if (!job) {+ return 'completed and removed';+ }+ if (job.finishedOn) {+ return await job.getState();+ }+ await delay(JOB_POLL_INTERVAL_MS);+ }+ return null;+ };++ for (const { legacyCase, jobId } of enqueued) {+ const state = await waitForCompletion(legacyCase.queue, jobId);+ check(+ state === 'completed' || state === 'completed and removed',+ `${legacyCase.queue}: legacy job ${jobId} was processed by the new worker (${state})`+ );+ }+ const envelopeState = await waitForCompletion('cron', envelopeJobId);+ check(+ envelopeState === 'completed' || envelopeState === 'completed and removed',+ `cron: envelope job ${envelopeJobId} was processed by the new worker (${envelopeState})`+ );++ // --- 4. Assertions on what the worker actually resolved ------------------++ process.stdout.write(+ '\n--- what the compat hooks resolved ----------------------------\n'+ );++ for (const legacyCase of LEGACY_CASES) {+ if (legacyCase.queue === REAL_HANDLER_QUEUE) {+ continue;+ }+ const run = runs.find(+ (candidate) =>+ candidate.queue === legacyCase.queue &&+ candidate.job === legacyCase.expectJob+ );+ process.stdout.write(+ `${legacyCase.queue.padEnd(14)} ${JSON.stringify(legacyCase.data)}\n` ++ `${''.padEnd(14)} -> job=${run?.job} payload=${JSON.stringify(run?.payload)}\n`+ );+ check(+ run !== undefined &&+ JSON.stringify(run.payload) ===+ JSON.stringify(legacyCase.expectPayload),+ `${legacyCase.queue}: resolved to '${legacyCase.expectJob}' with V1's payload`+ );+ }++ const startedLegacy = logLines.filter(+ (line) => line.includes('"job started"') && line.includes('"legacy":true')+ );+ check(+ startedLegacy.length === LEGACY_CASES.length,+ `worker logged 'job started' with legacy:true for all ${LEGACY_CASES.length} legacy jobs (got ${startedLegacy.length})`+ );++ const realFlush = logLines.find(+ (line) =>+ line.includes('"job completed"') &&+ line.includes('"job":"flushEvents"') &&+ line.includes('"legacy":true')+ );+ check(+ realFlush !== undefined,+ "cron: the REAL flushEvents handler ran to completion off V1's `{type:'flushEvents'}`"+ );++ const envelopeLine = logLines.find(+ (line) =>+ line.includes('"job completed"') &&+ line.includes('"job":"flushGroups"') &&+ line.includes(`"requestId":"${requestId}"`)+ );+ check(+ envelopeLine !== undefined,+ 'envelope job: the producer requestId reached the handler logger'+ );++ // --- 5. Clean the proof namespace up ------------------------------------++ await workers.close();+ await producers.close();++ const proofKeys = await producerConnection.keys(`bull:*-${NAMESPACE}*`);+ if (proofKeys.length > 0) {+ await producerConnection.del(...proofKeys);+ }+ process.stdout.write(`\ncleaned ${proofKeys.length} proof redis keys\n`);++ for (const client of connections) {+ client.disconnect();+ }++ process.stdout.write(+ failures === 0+ ? '\nlegacy-job-proof: all checks passed\n'+ : `\nlegacy-job-proof: ${failures} failure(s)\n`+ );+ process.exit(failures === 0 ? 0 : 1);+}++main().catch((error) => {+ process.stdout.write(+ `\nlegacy-job-proof: crashed\n${error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`+ );+ process.exit(1);+});diff --git a/apps/api/package.json b/apps/api/package.jsonindex 3af22cc73..b73aeb388 100644--- a/apps/api/package.json+++ b/apps/api/package.json@@ -10,6 +10,7 @@"test:manage": "jiti scripts/test-manage-api.ts","e2e:sessions": "LOG_LEVEL=warn dotenv -e ../../.env -- jiti e2e/session-e2e.ts","e2e:sessions:stress": "LOG_LEVEL=warn dotenv -e ../../.env -- jiti e2e/session-stress.ts",+ "e2e:legacy-jobs": "bash e2e/legacy-job-proof.sh","test": "vitest","test:run": "vitest run","typecheck": "tsc --noEmit"diff --git a/apps/api/src/config/env.ts b/apps/api/src/config/env.tsindex 46c997fe0..744ffbe6e 100644--- a/apps/api/src/config/env.ts+++ b/apps/api/src/config/env.ts@@ -2,8 +2,8 @@// per TARGET_ARCHITECTURE §7 "apps/api — three files". `packages/db` and// `packages/redis` keep reading their own env until they grow factories —// an accepted pragmatic deviation (ADR-007 §7) — so this catalogue covers-// only what `main.ts` itself reads today: TZ, ROLE, LOG_LEVEL, API_PORT and-// SELF_HOSTED.+// only what `main.ts` itself reads today: TZ, ROLE, LOG_LEVEL, API_PORT,+// SELF_HOSTED and QUEUE_CLUSTER.//// Invalid config fails boot loudly, with every issue reported at once —// never a fail-fast on the first bad var.@@ -64,6 +64,21 @@ const envSchema = z.object({.optional().default('false').transform((value) => value === TRUE_STRING),+ /**+ * Redis Cluster hash-tags every queue key (`cron` -> `{cron}`). Read here+ * because `main.ts` hands it to `createProducers`, and it decides a Redis+ * key name: set it on a deployment whose queues already exist unbraced and+ * every one of them is orphaned. V1 read it as a bare truthy check+ * (`packages/queue/src/queues.ts` `getQueueName`); a blank value is unset,+ * exactly as before.+ */+ QUEUE_CLUSTER: z.preprocess(+ blankToUndefined,+ z+ .string()+ .optional()+ .transform((value) => value !== undefined)+ ),});export type Config = z.infer<typeof envSchema>;diff --git a/apps/api/src/main.ts b/apps/api/src/main.tsindex bced7c8e8..f2a20c96d 100644--- a/apps/api/src/main.ts+++ b/apps/api/src/main.ts@@ -3,12 +3,14 @@// keeps serving the golden harness untouched until `apps/worker` is deleted// at P9.//-// This is the M3 gate boot only: db/ch/redis/clients are not wired into-// `AppDeps` yet — their types stay the `unknown` stubs `context.ts` declares-// until P3/P4 land the real clients — so only the ops surface (healthz +-// metrics) is mounted here. `dashboardRoutes`/`publicApiRoutes` land with-// their first module (see `rest.routes.ts`). The buffers ARE real from M8-001:-// `createBuffers` builds them once, here, and nowhere else.+// This is the M3 gate boot only: db/ch/clients are not wired into `AppDeps`+// yet — their types stay the `unknown` stubs `context.ts` declares until+// P3/P4 land the real clients — so only the ops surface (healthz + metrics)+// is mounted here. `dashboardRoutes`/`publicApiRoutes` land with their first+// module (see `rest.routes.ts`). The buffers ARE real from M8-001:+// `createBuffers` builds them once, here, and nowhere else. The producers are+// real from M9-001: all seven queues, envelope on, byte-identical Redis keys.+// Workers, schedulers and the ingest consumer are M9-002.process.env.TZ = 'UTC';@@ -16,12 +18,15 @@ import {type AppDeps,type BufferDeps,createBuffers,+ createProducers,opsRoutes,type QueueProducerHandle,+ queueKey,queues,registerBufferMetrics,} from '@openpanel/core';import { produceIncomingEvent } from '@openpanel/queue';+import { getRedisQueue } from '@openpanel/redis';import pino from 'pino';import { type Config, loadConfig } from './config/env';@@ -55,53 +60,45 @@ const config = loadConfigOrExit();const logger = pino({ name: 'api', level: config.LOG_LEVEL });/**- * `AppDeps.producers` needs a real `QueueProducerHandle`, but core's exports- * map (ADR-008) only publishes the type — `createProducers` is internal.- * Every registry queue's `jobs` map is still empty (no module has landed- * one, see jobs.registry.ts), so there is nothing to enqueue yet; this stub- * satisfies the type with no Redis connection. It is replaced by a real- * `createProducers` call site inside core once a module needs to enqueue.+ * All seven queues, envelope on, on the Redis keys V1 already uses — so a job+ * V1 enqueued before the cutover is read back by V2's `resolveJob` through+ * that queue's compat hook, with no drain and no rename (ADR-005).+ *+ * The connection is `packages/redis`'s dedicated queue client: a separate+ * client from cache/pub/sub with `maxRetriesPerRequest: null`, which is what+ * BullMQ requires and exactly what V1's `packages/queue` producers connect+ * through. It stays that package's singleton to close (ADR-007 §7's accepted+ * pragmatic deviation); `producers.close()` closes the queues over it.*/-function stubProducers(): QueueProducerHandle {- const emptyQueues = Object.fromEntries(- Object.keys(queues).map((name) => [name, {}])- ) as QueueProducerHandle['queues'];-- const notWired = (): never => {- throw new Error('Job producers are not wired up yet (M3 boot stub)');- };-- return {- queues: emptyQueues,- scope: () => emptyQueues,- enqueue: notWired,- remove: notWired,- bullQueues: [],- close: () => Promise.resolve(),- };+function buildProducerHandle(): QueueProducerHandle {+ return createProducers(queues, {+ connection: getRedisQueue(),+ cluster: config.QUEUE_CLUSTER,+ logger,+ });}/*** A named child of the boot logger per buffer, plus the buffers' one direct* BullMQ read — ADR-005's `bullQueues` escape hatch.* Pausing `cron` from bull-board halts ALL buffer flushing, preserved- * deliberately (docs/ANSWERS.md §3: "known!"). The M3 producer stub owns no- * queues yet, and a queue that does not exist has not been paused.+ * deliberately (docs/ANSWERS.md §3: "known!").*/function bufferDeps(producers: QueueProducerHandle): BufferDeps {+ // `bullQueues` are keyed by the Redis name, which `QUEUE_CLUSTER` braces.+ const cronKey = queueKey(CRON_QUEUE_NAME, { cluster: config.QUEUE_CLUSTER });+return {createLogger: (name) => logger.child({ name }),isCronPaused: async () => {- const cron = producers.bullQueues.find(- (queue) => queue.name === CRON_QUEUE_NAME- );+ const cron = producers.bullQueues.find((queue) => queue.name === cronKey);return cron ? await cron.isPaused() : false;},};}function buildDeps(): AppDeps {- const producers = stubProducers();+ const producers = buildProducerHandle();return {// db/ch/redis/clients are `unknown` stubs in context.ts until P3/P4 land// the real clients — reading one before its type lands is meant to be adiff --git a/packages/core/src/index.ts b/packages/core/src/index.tsindex 76ece8588..9b9c9580d 100644--- a/packages/core/src/index.ts+++ b/packages/core/src/index.ts@@ -142,6 +142,33 @@ export type {} from './context';export { createCtx, extendCtx } from './context';export { requestContext, requestLogging } from './http/context';+// The two runtime seams over the registry (ADR-005). `main.ts` builds+// producers in every role and workers only where the role consumes; both take+// the registry as data, so neither opens a connection until it is called.+export type {+ AnyJob,+ EnqueueOptions,+ QueueDefinition,+} from './jobs/define';+export type { JobEnvelope, JobMeta } from './jobs/envelope';+export { queueKey } from './jobs/naming';+export type { CreateProducersOptions } from './jobs/producers';+export { createProducers } from './jobs/producers';+export type {+ SchedulerDefinition,+ SchedulerFlags,+} from './jobs/schedulers';+export {+ CRON_SCHEDULES,+ PING_SCHEDULE,+ startSchedulers,+} from './jobs/schedulers';+export type {+ StartWorkersOptions,+ TerminalFailure,+ WorkerHandle,+} from './jobs/workers';+export { startWorkers } from './jobs/workers';export type {QueueProducerHandle,QueueProducers,@@ -277,7 +304,6 @@ export {verifyPasswordHash,verifyTotpCode,} from './modules/auth/auth.service';-export { getIsRegistrationAllowed } from './modules/auth/src/registration';// Moved from packages/db/src/services/auth-session.service.ts (M8-005) —// the Postgres-backed login session CRUD. packages/db keeps a re-export// shim (existing `@openpanel/db` importers, apps/api's app.ts).@@ -289,6 +315,7 @@ export {invalidateSession,validateSessionToken,} from './modules/auth/src/login-session';+export { getIsRegistrationAllowed } from './modules/auth/src/registration';// Dissolved from @openpanel/db's services/chart.service.ts and engine/// (M7-003) — packages/trpc's chart router, apps/api's export controller,// V1's funnel/conversion/sankey/retention/overview services and the@@ -364,12 +391,6 @@ export {rewriteProfilePropertyRefs,transformPropertyKey,} from './modules/chart/chart.service';-// Moved from packages/db/src/services/filter-where.service.ts (M8-005) — the-// sessions/profiles/events-table filter compiler, distinct from-// `getEventFiltersWhereClause` above. packages/db/src/services/-// filter-where.service.ts stays a re-export shim.-export type { FilterTableContext } from './modules/chart/src/table-filter-where';-export { buildFilterWhere } from './modules/chart/src/table-filter-where';// Dissolved from @openpanel/db's services/conversion.service.ts (M7-004) —// reached through the chart module's own dispatch and the db shim.export { getConversion } from './modules/chart/conversion.service';@@ -427,6 +448,12 @@ export {getUserFlowCore,zGetSankeyInput,} from './modules/chart/sankey.service';+// Moved from packages/db/src/services/filter-where.service.ts (M8-005) — the+// sessions/profiles/events-table filter compiler, distinct from+// `getEventFiltersWhereClause` above. packages/db/src/services/+// filter-where.service.ts stays a re-export shim.+export type { FilterTableContext } from './modules/chart/src/table-filter-where';+export { buildFilterWhere } from './modules/chart/src/table-filter-where';// Dissolved from @openpanel/db's services/clients.service.ts (M6-002) —// packages/trpc's client router, apps/api's manage controller and mcp/utils// auth call these directly, the same way V1 reaches every other dissolveddiff --git a/packages/core/src/jobs.registry.test.ts b/packages/core/src/jobs.registry.test.tsindex 482371196..e102d5a77 100644--- a/packages/core/src/jobs.registry.test.ts+++ b/packages/core/src/jobs.registry.test.ts@@ -1,4 +1,5 @@import { expect, test } from 'bun:test';+import { CRON_SCHEDULES, PING_SCHEDULE } from './jobs/schedulers';import { queues } from './jobs.registry';// V1's `defaultJobOptions`, verbatim from packages/queue/src/queues.ts.@@ -213,3 +214,31 @@ test('the notification queue carries the notification module job', () => {name: 'sendNotification',});});++// M9-001: every scheduler id must land on a cron job that exists, or the+// scheduled run resolves (legacyCompat.cron maps `type` straight onto a job+// name) and then throws `has no job named ...`.+//+// Three ids do not yet: `dataHealth`, `windDown` and `flushExports` are still+// only implemented in apps/worker/src/jobs (cron.data-health.ts,+// cron.wind-down.ts, cron.flush-exports.ts) and are ported with the rest of+// the worker at M9-003 ("every job the old worker ran is served by the merged+// app under ROLE=worker"). Pinned as a precise, exhaustive exception set so+// the gap is loud here rather than silent in production — and so M9-003 has+// to delete this list to go green.+const CRON_JOBS_NOT_YET_PORTED = ['dataHealth', 'flushExports', 'windDown'];++test('every cron scheduler id has a handler, bar the three M9-003 ports', () => {+ const declared = new Set(Object.keys(queues.cron.jobs));+ const scheduled = [...CRON_SCHEDULES, PING_SCHEDULE].map(+ (scheduler) => scheduler.id+ );++ expect(scheduled.filter((id) => !declared.has(id)).sort()).toEqual(+ CRON_JOBS_NOT_YET_PORTED+ );+ // The reverse direction: nothing is registered that nothing ever schedules.+ expect(+ [...declared].filter((name) => !scheduled.includes(name)).sort()+ ).toEqual([]);+});diff --git a/packages/core/src/jobs/producers.ts b/packages/core/src/jobs/producers.tsindex 2e65302f9..0d5c5bdb6 100644--- a/packages/core/src/jobs/producers.ts+++ b/packages/core/src/jobs/producers.ts@@ -3,6 +3,7 @@ import {type ConnectionOptions,type JobsOptions,} from 'bullmq';+import type { Logger } from '../logger';import type {AnyBoundJob,EnqueueOptions,@@ -48,6 +49,14 @@ export interface CreateProducersOptions {/** `QUEUE_CLUSTER`. Off in every deployment that exists today — see `queueKey`. */cluster?: boolean;namespace?: string;+ /**+ * Where a queue's connection errors go. BullMQ re-emits ioredis errors on+ * every `Queue`, and an `'error'` event with no listener is an uncaught+ * exception that kills the process — V1 lost the api roughly daily to idle+ * ECONNRESETs before `guardQueue` was added (packages/queue/src/queues.ts).+ * A listener is attached either way; this decides whether it says anything.+ */+ logger?: Logger;}/**@@ -59,18 +68,29 @@ export interface CreateProducersOptions {*/export function createProducers<TQueues extends QueueMap>(definitions: TQueues,- { connection, cluster, namespace }: CreateProducersOptions+ { connection, cluster, namespace, logger }: CreateProducersOptions): ProducerHandle<TQueues> {const bullQueues = new Map<string, BullQueue>();for (const definition of Object.values(definitions)) {- bullQueues.set(- definition.name,- new BullQueue(queueKey(definition.name, { cluster, namespace }), {+ const queue = new BullQueue(+ queueKey(definition.name, { cluster, namespace }),+ {connection,defaultJobOptions: toJobsOptions(definition.defaults),- })+ }+ );++ // Never omitted: the listener is what stops a reconnectable socket error+ // from taking the process down. ioredis reconnects on its own.+ queue.on('error', (error) =>+ logger?.error(+ { err: error, queue: definition.name },+ 'queue connection error'+ ));++ bullQueues.set(definition.name, queue);}const queueFor = (name: string): BullQueue => {diff --git a/packages/core/src/jobs/workers.ts b/packages/core/src/jobs/workers.tsindex 826a67617..96ecd9ac9 100644--- a/packages/core/src/jobs/workers.ts+++ b/packages/core/src/jobs/workers.ts@@ -8,6 +8,7 @@ import { REQUEST_ID_LENGTH, REQUEST_ID_LOG_FIELD } from '../logger';import { generateId } from '../shared/id';import { resolveJob } from './compat';import type { QueueDefinition, QueueMap } from './define';+import { isEnvelope } from './envelope';import { queueKey } from './naming';export interface TerminalFailure {@@ -181,5 +182,18 @@ export async function runJob(ctx: JobCtx;}) => Promise<void>;+ // `debug`, not `info`: `sessions` runs one of these per session close.+ // `legacy` is the cutover's own signal — while it is still ever true, a+ // V1-shaped job is still being replayed and the compat hooks cannot go+ // (ADR-005 risk 1).+ const legacy = !isEnvelope(job.data);+ logger.debug({ legacy }, 'job started');+ const startedAt = performance.now();+await handler({ payload, ctx });++ logger.debug(+ { legacy, durationMs: Math.round(performance.now() - startedAt) },+ 'job completed'+ );}