ravenflow 0.2.0 → 0.3.1

package/dist/index.js

@@ -4,10 +4,32 @@ var pino = require('pino');
 var bullmq = require('bullmq');
 var zod = require('zod');
 var mongodb = require('mongodb');
+var crypto = require('crypto');
+var os = require('os');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
+function _interopNamespace(e) {
+  if (e && e.__esModule) return e;
+  var n = Object.create(null);
+  if (e) {
+    Object.keys(e).forEach(function (k) {
+      if (k !== 'default') {
+        var d = Object.getOwnPropertyDescriptor(e, k);
+        Object.defineProperty(n, k, d.get ? d : {
+          enumerable: true,
+          get: function () { return e[k]; }
+        });
+      }
+    });
+  }
+  n.default = e;
+  return Object.freeze(n);
+}
+
 var pino__default = /*#__PURE__*/_interopDefault(pino);
+var crypto__namespace = /*#__PURE__*/_interopNamespace(crypto);
+var os__namespace = /*#__PURE__*/_interopNamespace(os);
 
 var __defProp = Object.defineProperty;
 var __export = (target, all) => {
@@ -88,11 +110,13 @@ async function closeQueues(queues) {
 }
 
 // src/processors/token-bucket-job.processor/constants.ts
-var TOKEN_BUCKET_PROCESS_SUFFIX = ":process";
+var TOKEN_BUCKET_CONSUME_SUFFIX = ":consume";
 var INTERVAL_MS = {
+  second: 1e3,
   minute: 6e4,
   hour: 36e5,
-  day: 864e5
+  day: 864e5,
+  week: 6048e5
 };
 
 // src/processors/constants.ts
@@ -178,9 +202,7 @@ function defineStatefulEtlJob(config) {
 zod.z.object({
   _id: zod.z.string(),
   accumulatedCredit: zod.z.number(),
-  lastTickAt: zod.z.date(),
-  windowDispatched: zod.z.number().int().nonnegative(),
-  windowResetAt: zod.z.date()
+  lastTickAt: zod.z.date()
 });
 function defineTokenBucketJob(config) {
   return { ...config, type: "token-bucket" };
@@ -296,18 +318,6 @@ async function dispatchSubJob(queue, queueEvents, name, data, options) {
   });
   return await job.waitUntilFinished(queueEvents);
 }
-async function dispatchSubJobsFireAndForget(queue, name, items, options) {
-  return queue.addBulk(
-    items.map((data) => ({
-      name,
-      data,
-      opts: {
-        attempts: options?.attempts,
-        backoff: options?.backoff
-      }
-    }))
-  );
-}
 
 // src/processors/etl-context.ts
 var EtlContext = class {
@@ -630,6 +640,7 @@ async function markResuming(runId) {
 // src/mongo/token-bucket.repo.ts
 var token_bucket_repo_exports = {};
 __export(token_bucket_repo_exports, {
+  ensureIndexes: () => ensureIndexes,
   getOrCreateState: () => getOrCreateState,
   updateState: () => updateState
 });
@@ -637,35 +648,33 @@ var COLLECTION = "token_bucket_state";
 function collection2() {
   return getDb().collection(collectionName(COLLECTION));
 }
-async function getOrCreateState(jobName, now, windowResetAt) {
+async function getOrCreateState(jobName, now) {
   const result = await collection2().findOneAndUpdate(
     { _id: jobName },
     {
       $setOnInsert: {
         _id: jobName,
         accumulatedCredit: 0,
-        lastTickAt: now,
-        windowDispatched: 0,
-        windowResetAt
+        lastTickAt: now
       }
     },
     { upsert: true, returnDocument: "after" }
   );
   return result;
 }
-async function updateState(jobName, accumulatedCredit, lastTickAt, windowDispatched, windowResetAt) {
+async function updateState(jobName, accumulatedCredit, lastTickAt) {
   await collection2().updateOne(
     { _id: jobName },
     {
       $set: {
         accumulatedCredit,
-        lastTickAt,
-        windowDispatched,
-        windowResetAt
+        lastTickAt
       }
     }
   );
 }
+async function ensureIndexes() {
+}
 
 // src/processors/stateful-etl-job.processor/constants.ts
 var DEFAULT_STALL_TIMEOUT_MS = 3e5;
@@ -791,128 +800,52 @@ async function ensureNotAlreadyRunning(jobName) {
   }
 }
 
-// src/processors/token-bucket-job.processor/active-hours.ts
-function isWithinActiveHours(config, now) {
-  if (!config.activeHours) return true;
-  const { start, end, timezone } = config.activeHours;
-  const hour = getHourInTimezone(now, timezone);
-  if (start <= end) {
-    return hour >= start && hour < end;
-  }
-  return hour >= start || hour < end;
-}
-function getActiveWindowMs(config) {
-  if (!config.activeHours) {
-    return getFullIntervalMs(config.rate.interval);
-  }
-  const { start, end } = config.activeHours;
-  let hours;
-  if (start <= end) {
-    hours = end - start;
-  } else {
-    hours = 24 - start + end;
-  }
-  if (hours <= 0) hours = 24;
-  if (config.rate.interval === "day") {
-    return hours * 36e5;
-  }
-  return getFullIntervalMs(config.rate.interval);
-}
-function getFullIntervalMs(interval) {
-  switch (interval) {
-    case "minute":
-      return 6e4;
-    case "hour":
-      return 36e5;
-    case "day":
-      return 864e5;
-  }
-}
-function getHourInTimezone(date, timezone) {
-  if (!timezone) return date.getUTCHours();
-  const formatted = new Intl.DateTimeFormat("en-US", {
-    hour: "numeric",
-    hour12: false,
-    timeZone: timezone
-  }).format(date);
-  return parseInt(formatted, 10);
-}
-
-// src/processors/token-bucket-job.processor/budget.ts
-function calculateBudget(state, config, now) {
-  const nowMs = now.getTime();
-  const windowResetMs = state.windowResetAt.getTime();
-  let windowDispatched = state.windowDispatched;
-  let windowResetAt = state.windowResetAt;
-  if (nowMs >= windowResetMs) {
-    windowDispatched = 0;
-    windowResetAt = computeNextWindowReset(now, config.rate.interval);
-  }
-  const elapsedMs = nowMs - state.lastTickAt.getTime();
-  if (elapsedMs <= 0) {
-    return { budget: 0, newCredit: state.accumulatedCredit, newWindowDispatched: windowDispatched, newWindowResetAt: windowResetAt };
-  }
-  const activeWindowMs = getActiveWindowMs(config);
-  const msPerItem = activeWindowMs / config.rate.amount;
-  const earnedCredit = elapsedMs / msPerItem;
-  let credit = state.accumulatedCredit + earnedCredit;
-  const maxPerBeat = config.maxPerBeat ?? computeDefaultMaxPerBeat(config);
-  credit = Math.min(credit, maxPerBeat);
-  const remaining = Math.max(0, config.rate.amount - windowDispatched);
-  const budget = Math.min(Math.floor(credit), remaining);
-  return {
-    budget,
-    newCredit: credit - budget,
-    newWindowDispatched: windowDispatched + budget,
-    newWindowResetAt: windowResetAt
-  };
-}
-function computeDefaultMaxPerBeat(config) {
-  return Math.max(1, Math.ceil(config.rate.amount / 10));
-}
-function computeNextWindowReset(now, interval) {
-  return new Date(now.getTime() + INTERVAL_MS[interval]);
+// src/processors/token-bucket-job.processor/compute-credit.ts
+function computeCredit(input) {
+  const { now, rate, lastTickAt, accumulatedCredit, maxCarryOver, budget } = input;
+  const elapsedMs = Math.max(0, now.getTime() - lastTickAt.getTime());
+  const tickCredit = rate ? rate.amount * elapsedMs / INTERVAL_MS[rate.interval] : 0;
+  const totalCredit = accumulatedCredit + tickCredit;
+  const cappedCredit = rate ? Math.min(totalCredit, tickCredit * (1 + maxCarryOver / 100)) : totalCredit;
+  const availableCredit = budget !== void 0 ? Math.min(cappedCredit, budget) : cappedCredit;
+  const tokens = Math.floor(availableCredit);
+  const newCredit = cappedCredit - tokens;
+  return { tokens, newCredit };
 }
 
-// src/processors/token-bucket-job.processor/process.ts
+// src/processors/token-bucket-job.processor/index.ts
 async function processTokenBucketJob(job, config, queues) {
   const logger2 = getLogger();
-  const jobName = job.name;
-  const now = /* @__PURE__ */ new Date();
-  if (!isWithinActiveHours(config, now)) {
-    logger2.debug({ jobName }, "[token-bucket] outside active hours, skipping");
-    return { dispatched: 0 };
-  }
-  const initialWindowReset = new Date(now.getTime() + INTERVAL_MS[config.rate.interval]);
-  const state = await token_bucket_repo_exports.getOrCreateState(jobName, now, initialWindowReset);
-  const { budget, newCredit, newWindowDispatched, newWindowResetAt } = calculateBudget(state, config, now);
-  if (budget <= 0) {
-    await token_bucket_repo_exports.updateState(jobName, newCredit, now, newWindowDispatched, newWindowResetAt);
-    logger2.debug({ jobName, credit: newCredit }, "[token-bucket] no budget, skipping");
-    return { dispatched: 0 };
-  }
-  const items = await config.getItems(budget);
-  if (items.length === 0) {
-    await token_bucket_repo_exports.updateState(jobName, newCredit, now, newWindowDispatched, newWindowResetAt);
-    logger2.debug({ jobName }, "[token-bucket] no items to dispatch");
-    return { dispatched: 0 };
-  }
-  const queueData = queues[config.queue];
-  if (!queueData) {
-    throw new Error(`[token-bucket] queue "${config.queue}" not found`);
-  }
-  const subJobOptions = config.steps?.process ? { attempts: config.steps.process.attempts, backoff: config.steps.process.backoff } : void 0;
-  const subJobName = `${jobName}${TOKEN_BUCKET_PROCESS_SUFFIX}`;
-  await dispatchSubJobsFireAndForget(queueData.queue, subJobName, items, subJobOptions);
-  const actualDispatched = items.length;
-  const adjustedCredit = Math.max(0, newCredit - Math.max(0, budget - actualDispatched));
-  const adjustedWindowDispatched = newWindowDispatched - (budget - actualDispatched);
-  await token_bucket_repo_exports.updateState(jobName, adjustedCredit, now, adjustedWindowDispatched, newWindowResetAt);
-  logger2.info(
-    { jobName, dispatched: actualDispatched, credit: adjustedCredit, windowDispatched: adjustedWindowDispatched },
-    "[token-bucket] dispatched items"
-  );
-  return { dispatched: actualDispatched };
+  const tickStartedAt = /* @__PURE__ */ new Date();
+  const state = await token_bucket_repo_exports.getOrCreateState(job.name, tickStartedAt);
+  const budget = config.getBudget ? await config.getBudget() : void 0;
+  const { tokens, newCredit } = computeCredit({
+    now: tickStartedAt,
+    rate: config.rate,
+    lastTickAt: state.lastTickAt,
+    accumulatedCredit: state.accumulatedCredit,
+    maxCarryOver: config.maxCarryOver ?? 100,
+    budget
+  });
+  if (tokens === 0) {
+    await token_bucket_repo_exports.updateState(job.name, newCredit, tickStartedAt);
+    logger2.debug({ jobName: job.name, newCredit }, "[token-bucket] zero tokens, skipping consume");
+    return;
+  }
+  try {
+    const queueData = queues[config.queue];
+    const consumeJob = await queueData.queue.add(
+      `${job.name}${TOKEN_BUCKET_CONSUME_SUFFIX}`,
+      tokens
+    );
+    const result = await consumeJob.waitUntilFinished(queueData.events, config.consumeTimeout);
+    const consumed = typeof result === "number" ? result : tokens;
+    const finalCredit = newCredit + (tokens - consumed);
+    await token_bucket_repo_exports.updateState(job.name, finalCredit, tickStartedAt);
+    logger2.info({ jobName: job.name, tokens, consumed, finalCredit }, "[token-bucket] tick complete");
+  } catch (error) {
+    logger2.warn({ jobName: job.name, error: String(error) }, "[token-bucket] consume failed, skipping state update");
+  }
 }
 
 // src/app/job-registry.ts
@@ -940,7 +873,7 @@ var ALL_SUFFIXES = [
   ETL_EXTRACT_SUFFIX,
   ETL_TRANSFORM_SUFFIX,
   ETL_LOAD_SUFFIX,
-  TOKEN_BUCKET_PROCESS_SUFFIX
+  TOKEN_BUCKET_CONSUME_SUFFIX
 ];
 function resolveJobName(name, jobConfigs) {
   for (const suffix of ALL_SUFFIXES) {
@@ -980,8 +913,8 @@ async function processJob(job, jobConfigs, queues, defaultQueue) {
       }
     }
     if (jobConfig.type === "token-bucket") {
-      if (suffix === TOKEN_BUCKET_PROCESS_SUFFIX) {
-        return await jobConfig.process(job.data);
+      if (suffix === TOKEN_BUCKET_CONSUME_SUFFIX) {
+        return await jobConfig.consume(job.data);
       }
     }
     throw new Error(`Unexpected sub-job suffix "${suffix}" for ${baseName} (type: ${jobConfig.type})`);
@@ -1082,11 +1015,27 @@ function printWorkerBanner(config) {
 }
 
 // src/app/worker-manager.ts
-function createWorker(queueName, connection, concurrency, processJob2) {
+var METRICS_TIME = {
+  ONE_MINUTE: 1,
+  FIVE_MINUTES: 5,
+  FIFTEEN_MINUTES: 15,
+  THIRTY_MINUTES: 30,
+  ONE_HOUR: 60,
+  ONE_DAY: 1440,
+  ONE_WEEK: 10080,
+  TWO_WEEKS: 20160,
+  ONE_MONTH: 80640
+};
+var DEFAULT_WORKER_METRICS = Object.freeze({
+  maxDataPoints: METRICS_TIME.ONE_WEEK
+});
+function createWorker(queueName, connection, concurrency, processJob2, workerOpts) {
   const worker = new bullmq.Worker(queueName, processJob2, {
+    ...workerOpts,
     connection,
     autorun: false,
-    concurrency
+    concurrency,
+    metrics: DEFAULT_WORKER_METRICS
   });
   return worker;
 }
@@ -1289,6 +1238,7 @@ var StallWatcher = class {
     for (const [jobName, config] of Object.entries(jobConfigs)) {
       if (config.type === "stateful-etl") {
         this.statefulEtlConfigs.set(jobName, {
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any -- generic erasure at runtime; typed config-walker deferred per Story 1.8 AC #15
           config,
           queue: config.queue ?? defaultQueue
         });
@@ -1329,7 +1279,1355 @@ var StallWatcher = class {
   }
 };
 
+// src/mongo/repositories/_base.ts
+var Repository = class {
+  constructor(db2, rawCollectionName) {
+    this.collection = db2.collection(collectionName(rawCollectionName));
+  }
+  async init() {
+    for (const idx of this.indexes()) {
+      await this.collection.createIndex(idx.keys, idx.options);
+    }
+  }
+};
+
+// src/mongo/repositories/workers.repo.ts
+var COLLECTION2 = "workers";
+var WorkersRepo = class extends Repository {
+  constructor(db2) {
+    super(db2, COLLECTION2);
+  }
+  indexes() {
+    return [
+      {
+        keys: { workerId: 1 },
+        options: { unique: true, name: "workerId_unique" }
+      },
+      {
+        keys: { lastHeartbeatAt: 1 },
+        options: { name: "lastHeartbeatAt_asc" }
+      }
+    ];
+  }
+  async registerWorker(input) {
+    this.validateRegisterInput(input);
+    const filter = { workerId: input.workerId };
+    const update = {
+      $currentDate: {
+        lastHeartbeatAt: true,
+        updatedAt: true
+      },
+      $setOnInsert: {
+        workerId: input.workerId,
+        hostname: input.hostname,
+        pid: input.pid,
+        queues: input.queues,
+        startedAt: input.startedAt,
+        createdAt: /* @__PURE__ */ new Date()
+      }
+    };
+    await this.collection.updateOne(filter, update, { upsert: true });
+  }
+  async updateHeartbeat(workerId) {
+    if (typeof workerId !== "string" || workerId.length === 0) {
+      throw new Error("WorkersRepo.updateHeartbeat: workerId must be a non-empty string");
+    }
+    const filter = { workerId };
+    const update = {
+      $currentDate: { lastHeartbeatAt: true, updatedAt: true }
+    };
+    const result = await this.collection.updateOne(filter, update);
+    if (result.matchedCount === 0) {
+      getLogger().warn(
+        { workerId },
+        "[workers-repo] heartbeat on missing worker record \u2014 ignoring"
+      );
+    }
+  }
+  /**
+   * Appends or replaces a queue entry on the worker's record.
+   *
+   * Single-writer invariant: this method is NOT atomic under concurrent writers to the
+   * SAME `workerId`. WorkerRegistry is a process-local singleton, and `workerId` is
+   * unique per process by contract (default: `<hostname>:<pid>:<uuid>`). Sharing a
+   * stable `workerId` across processes violates AC #6 and will race last-writer-wins.
+   */
+  async addQueue(input) {
+    if (typeof input.workerId !== "string" || input.workerId.length === 0) {
+      throw new Error("WorkersRepo.addQueue: workerId must be a non-empty string");
+    }
+    this.validateQueueEntry(input.queue, "WorkersRepo.addQueue");
+    const existingFilter = { workerId: input.workerId };
+    const existing = await this.collection.findOne(existingFilter);
+    if (existing === null) {
+      throw new Error(
+        `WorkersRepo.addQueue: worker not found for workerId=${input.workerId}`
+      );
+    }
+    const existingQueues = existing.queues ?? [];
+    const matchIndex = existingQueues.findIndex((q) => q.name === input.queue.name);
+    const newQueues = matchIndex === -1 ? [...existingQueues, input.queue] : existingQueues.map((q, i) => i === matchIndex ? input.queue : q);
+    const update = {
+      $set: { queues: newQueues },
+      $currentDate: { updatedAt: true }
+    };
+    await this.collection.updateOne(existingFilter, update);
+  }
+  async deregisterWorker(workerId) {
+    if (typeof workerId !== "string" || workerId.length === 0) {
+      throw new Error("WorkersRepo.deregisterWorker: workerId must be a non-empty string");
+    }
+    const filter = { workerId };
+    await this.collection.deleteOne(filter);
+  }
+  async findAlive(maxHeartbeatAgeMs) {
+    this.validateMaxHeartbeatAgeMs(maxHeartbeatAgeMs, "WorkersRepo.findAlive");
+    const threshold = new Date(Date.now() - maxHeartbeatAgeMs);
+    const filter = { lastHeartbeatAt: { $gte: threshold } };
+    return await this.collection.find(filter).sort({ lastHeartbeatAt: -1 }).toArray();
+  }
+  async cleanupStale(maxHeartbeatAgeMs) {
+    this.validateMaxHeartbeatAgeMs(maxHeartbeatAgeMs, "WorkersRepo.cleanupStale");
+    const threshold = new Date(Date.now() - maxHeartbeatAgeMs);
+    const filter = { lastHeartbeatAt: { $lt: threshold } };
+    const result = await this.collection.deleteMany(filter);
+    return result.deletedCount ?? 0;
+  }
+  validateRegisterInput(input) {
+    if (typeof input.workerId !== "string" || input.workerId.length === 0) {
+      throw new Error("WorkersRepo.registerWorker: workerId must be a non-empty string");
+    }
+    if (typeof input.hostname !== "string" || input.hostname.length === 0) {
+      throw new Error("WorkersRepo.registerWorker: hostname must be a non-empty string");
+    }
+    if (!Number.isInteger(input.pid) || input.pid < 0) {
+      throw new Error("WorkersRepo.registerWorker: pid must be a non-negative integer");
+    }
+    if (!Array.isArray(input.queues) || input.queues.length === 0) {
+      throw new Error("WorkersRepo.registerWorker: queues must be a non-empty array");
+    }
+    for (const q of input.queues) {
+      this.validateQueueEntry(q, "WorkersRepo.registerWorker");
+    }
+    if (!(input.startedAt instanceof Date) || Number.isNaN(input.startedAt.getTime())) {
+      throw new Error("WorkersRepo.registerWorker: startedAt must be a valid Date");
+    }
+  }
+  validateQueueEntry(q, ctx) {
+    if (q === null || typeof q !== "object") {
+      throw new Error(`${ctx}: queue entry must be an object`);
+    }
+    if (typeof q.name !== "string" || q.name.length === 0) {
+      throw new Error(`${ctx}: queue.name must be a non-empty string`);
+    }
+    if (!Number.isInteger(q.concurrency) || q.concurrency <= 0) {
+      throw new Error(`${ctx}: queue.concurrency must be a positive integer`);
+    }
+  }
+  validateMaxHeartbeatAgeMs(value, ctx) {
+    const MAX_AGE_MS = 30 * 24 * 60 * 60 * 1e3;
+    if (!Number.isInteger(value) || value <= 0 || value > MAX_AGE_MS) {
+      throw new Error(
+        `${ctx}: maxHeartbeatAgeMs must be a positive integer <= ${MAX_AGE_MS}`
+      );
+    }
+  }
+};
+
+// src/mongo/repositories/_types.ts
+function asBulkUpdateOp(op) {
+  return op;
+}
+function asBulkInsertOp(op) {
+  return op;
+}
+
+// src/mongo/repositories/bucket-utils.ts
+function computeBucketStart(ts, granularity) {
+  const result = new Date(ts);
+  if (granularity === "hour") {
+    result.setUTCMinutes(0, 0, 0);
+  } else {
+    result.setUTCHours(0, 0, 0, 0);
+  }
+  return result;
+}
+
+// src/mongo/mongo-error.ts
+var MONGO_DUPLICATE_KEY_CODE = 11e3;
+function isDuplicateKeyError(err) {
+  if (typeof err !== "object" || err === null) return false;
+  return err.code === MONGO_DUPLICATE_KEY_CODE;
+}
+
+// src/mongo/repositories/types.ts
+var JOB_STATS_TTL_SECONDS = 90 * 24 * 60 * 60;
+var JOB_ERRORS_MESSAGE_MAX_CHARS = 2e3;
+var JOB_ERRORS_STACK_MAX_CHARS = 8e3;
+var JOB_ERRORS_MAX_TOP_LIMIT = 1e3;
+var JOB_FAILURES_INPUT_MAX_CHARS = 1e5;
+var JOB_FAILURES_MESSAGE_MAX_CHARS = 2e3;
+var JOB_FAILURES_STACK_MAX_CHARS = 8e3;
+var JOB_FAILURES_LOGS_MAX_CHARS = 5e5;
+var JOB_FAILURES_MAX_LIST_LIMIT = 1e3;
+var JOB_FAILURES_TTL_SECONDS = 7 * 24 * 60 * 60;
+var WORKERS_DEFAULT_HEARTBEAT_INTERVAL_MS = 3e4;
+var WORKERS_MIN_HEARTBEAT_INTERVAL_MS = 1e3;
+var JOB_CONFIGS_DEFAULT_ENABLED = true;
+
+// src/mongo/repositories/job-stats.repo.ts
+var COLLECTION3 = "job_stats";
+var GRANULARITIES = ["hour", "day"];
+var MAX_GET_STATS_RESULTS = 1e4;
+var JobStatsRepo = class extends Repository {
+  constructor(db2) {
+    super(db2, COLLECTION3);
+  }
+  indexes() {
+    return [
+      {
+        keys: { jobType: 1, bucketStart: 1, granularity: 1 },
+        options: { unique: true, name: "jobType_bucketStart_granularity_unique" }
+      },
+      // NOTE (TTL migration): MongoDB's `createIndex` is a no-op when an index with the same
+      // key spec already exists — even if `expireAfterSeconds` differs. Changing
+      // `JOB_STATS_TTL_SECONDS` will NOT propagate to a running deployment; apply a `collMod`
+      // (or drop-and-recreate this index) manually at deploy time.
+      {
+        keys: { bucketStart: 1 },
+        options: {
+          expireAfterSeconds: JOB_STATS_TTL_SECONDS,
+          name: "bucketStart_ttl"
+        }
+      }
+    ];
+  }
+  /**
+   * Builds the bulk write operations for a stats increment WITHOUT executing them.
+   * Returns TWO ops — one for the hour bucket, one for the day bucket — matching
+   * `incrementStats`'s direct-call shape bit-for-bit. Intended to be pushed through
+   * a `BatchWriter` by the event-hooks layer (Story 1.7). Throws synchronously on
+   * invalid `durationMs`; otherwise no side effects.
+   *
+   * NOTE: `now` is captured at builder invocation time, NOT at BatchWriter flush
+   * time — `createdAt`, `updatedAt`, and `bucketStart` all reflect the event's
+   * wall-clock, not the flush wall-clock. Aggregations are therefore correctly
+   * attributed to the hour/day the event occurred, even if the batch flush is
+   * delayed by the buffer timer.
+   */
+  toIncrementStatsOps(jobType, input) {
+    this.validateDurationMs(input.durationMs, "toIncrementStatsOps");
+    const now = /* @__PURE__ */ new Date();
+    return GRANULARITIES.map((g) => this.buildBucketOp(jobType, g, now, input));
+  }
+  async incrementStats(jobType, input) {
+    this.validateDurationMs(input.durationMs, "incrementStats");
+    const now = /* @__PURE__ */ new Date();
+    const results = await Promise.allSettled(
+      GRANULARITIES.map((g) => this.upsertBucket(jobType, g, now, input))
+    );
+    const failures = results.map((r, i) => ({ result: r, granularity: GRANULARITIES[i] })).filter(
+      (x) => x.result.status === "rejected"
+    );
+    if (failures.length === 0) return;
+    const logger2 = getLogger();
+    for (const { result, granularity } of failures) {
+      logger2.error(
+        { jobType, granularity, err: result.reason },
+        "JobStatsRepo.incrementStats: bucket upsert failed"
+      );
+    }
+    if (failures.length === results.length) {
+      throw failures[0].result.reason;
+    }
+  }
+  async getStats(jobType, fromDate, toDate, granularity) {
+    if (fromDate > toDate) {
+      throw new Error(
+        `JobStatsRepo.getStats: fromDate (${fromDate.toISOString()}) must be <= toDate (${toDate.toISOString()})`
+      );
+    }
+    const filter = {
+      jobType,
+      granularity,
+      bucketStart: { $gte: fromDate, $lte: toDate }
+    };
+    return await this.collection.find(filter).sort({ bucketStart: 1 }).limit(MAX_GET_STATS_RESULTS).toArray();
+  }
+  /**
+   * Fetches every stats document in the given range + granularity, across ALL
+   * jobTypes. Intended for dashboard views that need a cross-jobType overview
+   * (e.g., "7-day health per job type") without a prior enumeration step.
+   *
+   * Result order: `bucketStart` ascending, then `jobType` ascending. Caller is
+   * responsible for grouping by jobType client-side if desired.
+   *
+   * Applies the same `MAX_GET_STATS_RESULTS` cap as `getStats` — a single query
+   * across all jobTypes × buckets × granularity is bounded, but the cap keeps
+   * the method safe under accidental wide-range queries.
+   */
+  async getStatsAllJobTypes(fromDate, toDate, granularity) {
+    if (fromDate > toDate) {
+      throw new Error(
+        `JobStatsRepo.getStatsAllJobTypes: fromDate (${fromDate.toISOString()}) must be <= toDate (${toDate.toISOString()})`
+      );
+    }
+    const filter = {
+      granularity,
+      bucketStart: { $gte: fromDate, $lte: toDate }
+    };
+    return await this.collection.find(filter).sort({ bucketStart: 1, jobType: 1 }).limit(MAX_GET_STATS_RESULTS).toArray();
+  }
+  async upsertBucket(jobType, granularity, now, input) {
+    const { filter, update } = this.buildBucketPayload(jobType, granularity, now, input);
+    try {
+      await this.collection.updateOne(filter, update, { upsert: true });
+    } catch (err) {
+      if (isDuplicateKeyError(err)) {
+        await this.collection.updateOne(filter, update, { upsert: true });
+        return;
+      }
+      throw err;
+    }
+  }
+  buildBucketOp(jobType, granularity, now, input) {
+    const { filter, update } = this.buildBucketPayload(jobType, granularity, now, input);
+    return asBulkUpdateOp({
+      updateOne: { filter, update, upsert: true }
+    });
+  }
+  buildBucketPayload(jobType, granularity, now, input) {
+    const bucketStart = computeBucketStart(now, granularity);
+    const filter = { jobType, bucketStart, granularity };
+    const update = {
+      $inc: {
+        count: 1,
+        success: input.success ? 1 : 0,
+        failed: input.success ? 0 : 1,
+        totalDurationMs: input.durationMs ?? 0
+      },
+      $setOnInsert: {
+        jobType,
+        bucketStart,
+        granularity,
+        createdAt: now
+      },
+      $set: {
+        updatedAt: now
+      }
+    };
+    return { filter, update };
+  }
+  validateDurationMs(durationMs, methodName) {
+    if (durationMs === void 0) return;
+    if (!Number.isFinite(durationMs) || durationMs < 0) {
+      throw new Error(
+        `JobStatsRepo.${methodName}: durationMs must be a finite non-negative number (got ${durationMs})`
+      );
+    }
+  }
+};
+var SIGNATURE_LENGTH = 16;
+var STACK_TOP_FRAMES = 5;
+var ISO_TIMESTAMP_REGEX = /\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z?/g;
+var UUID_REGEX = /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/gi;
+var HEX_ADDRESS_REGEX = /\b0x[0-9a-f]+\b/gi;
+var LONG_DIGIT_RUN_REGEX = /\b\d{5,}\b/g;
+var STACK_FRAME_PREFIX = "    at ";
+var STACK_LINE_COL_SUFFIX_REGEX = /:\d+:\d+(\)?)$/;
+function normalizeMessage(msg) {
+  return msg.replace(ISO_TIMESTAMP_REGEX, "<ts>").replace(UUID_REGEX, "<uuid>").replace(HEX_ADDRESS_REGEX, "<hex>").replace(LONG_DIGIT_RUN_REGEX, "<n>");
+}
+function normalizeStack(stack) {
+  const frames = [];
+  for (const rawLine of stack.split("\n")) {
+    if (!rawLine.startsWith(STACK_FRAME_PREFIX)) continue;
+    const slashed = rawLine.replace(/\\/g, "/");
+    const stripped = slashed.replace(STACK_LINE_COL_SUFFIX_REGEX, "$1");
+    frames.push(stripped);
+    if (frames.length === STACK_TOP_FRAMES) break;
+  }
+  return frames.join("\n");
+}
+function errorSignature(err) {
+  let combined;
+  if (err instanceof Error) {
+    const name = err.name ?? "Error";
+    const message = normalizeMessage(err.message ?? "");
+    const stack = err.stack ? normalizeStack(err.stack) : "";
+    combined = `${name}
+${message}
+${stack}`;
+  } else {
+    combined = normalizeMessage(String(err));
+  }
+  return crypto.createHash("sha256").update(combined).digest("hex").slice(0, SIGNATURE_LENGTH);
+}
+
+// src/monitoring/error-extraction.ts
+var DEFAULT_MAX_CAUSE_DEPTH = 5;
+var NAME_MAX_CHARS = 64;
+var CHAIN_SEPARATOR = "\nCaused by: ";
+function truncate(value, max) {
+  return value.length <= max ? value : value.slice(0, max);
+}
+function safeGet(getter, fallback) {
+  try {
+    return getter();
+  } catch {
+    return fallback;
+  }
+}
+function isErrorLike(value) {
+  if (typeof value !== "object" || value === null) return false;
+  return safeGet(() => "message" in value, false);
+}
+function normalizeEntry(value, messageMaxChars) {
+  const entryMax = Math.max(1, Math.floor(messageMaxChars / 2));
+  if (isErrorLike(value)) {
+    const rawMessage = safeGet(() => value.message, void 0);
+    const rawName = safeGet(() => value.name, void 0);
+    const message = truncate(
+      typeof rawMessage === "string" ? rawMessage : safeGet(() => String(rawMessage), ""),
+      entryMax
+    );
+    const name = truncate(typeof rawName === "string" ? rawName : "Error", NAME_MAX_CHARS);
+    return { message, name };
+  }
+  return {
+    message: truncate(safeGet(() => String(value), ""), entryMax),
+    name: "NonError"
+  };
+}
+function walkCauseChain(top, maxDepth, messageMaxChars) {
+  const chain = [];
+  const seen = /* @__PURE__ */ new WeakSet();
+  if (typeof top === "object" && top !== null) seen.add(top);
+  let current = safeGet(() => top.cause, void 0);
+  let truncated = false;
+  while (current !== void 0 && current !== null) {
+    if (chain.length >= maxDepth) {
+      truncated = true;
+      break;
+    }
+    if (typeof current === "object" && current !== null) {
+      if (seen.has(current)) {
+        truncated = true;
+        break;
+      }
+      seen.add(current);
+    }
+    chain.push(normalizeEntry(current, messageMaxChars));
+    const hasCause = typeof current === "object" && current !== null && safeGet(() => "cause" in current, false);
+    if (hasCause) {
+      current = safeGet(() => current.cause, void 0);
+    } else {
+      break;
+    }
+  }
+  return { chain, truncated };
+}
+function extractMessageAndStack(err, options) {
+  const { messageMaxChars, stackMaxChars } = options;
+  const rawMaxDepth = options.maxCauseDepth ?? DEFAULT_MAX_CAUSE_DEPTH;
+  const maxCauseDepth = Number.isFinite(rawMaxDepth) && rawMaxDepth >= 1 ? Math.floor(rawMaxDepth) : DEFAULT_MAX_CAUSE_DEPTH;
+  if (!(err instanceof Error)) {
+    return {
+      message: truncate(safeGet(() => String(err), ""), messageMaxChars),
+      stack: "",
+      causeChain: []
+    };
+  }
+  const topMessage = safeGet(() => {
+    const m = err.message;
+    return typeof m === "string" ? m : String(m ?? "");
+  }, "");
+  const topStack = safeGet(() => {
+    const s = err.stack;
+    return typeof s === "string" ? s : String(s ?? "");
+  }, "");
+  const { chain, truncated } = walkCauseChain(
+    err,
+    maxCauseDepth,
+    messageMaxChars
+  );
+  if (truncated) {
+    getLogger().warn(
+      { topMessage: truncate(topMessage, 120) },
+      "extractMessageAndStack: maxCauseDepth reached, truncating cause chain."
+    );
+  }
+  let joinedMessage = topMessage;
+  for (const entry of chain) {
+    joinedMessage += `${CHAIN_SEPARATOR}${entry.message}`;
+  }
+  return {
+    message: truncate(joinedMessage, messageMaxChars),
+    stack: truncate(topStack, stackMaxChars),
+    causeChain: chain
+  };
+}
+
+// src/mongo/repositories/job-errors.repo.ts
+var COLLECTION4 = "job_errors";
+var JobErrorsRepo = class extends Repository {
+  constructor(db2) {
+    super(db2, COLLECTION4);
+  }
+  indexes() {
+    return [
+      {
+        keys: { signature: 1 },
+        options: { unique: true, name: "signature_unique" }
+      },
+      {
+        keys: { lastSeenAt: -1 },
+        options: { name: "lastSeenAt_desc" }
+      },
+      {
+        keys: { jobType: 1, count: -1 },
+        options: { name: "jobType_count_desc" }
+      },
+      {
+        keys: { count: -1 },
+        options: { name: "count_desc" }
+      }
+    ];
+  }
+  /**
+   * Records one occurrence of an error, deduplicated by its stable signature.
+   *
+   * Invariant: `jobType` is set **only on insert** (`$setOnInsert`). Once a signature
+   * is first observed under jobType A, subsequent occurrences under jobType B do NOT
+   * overwrite the stored value. The signature is the identity of the error; a signature
+   * appearing across multiple job types indicates shared infrastructure failure (e.g.
+   * ECONNRESET from the shared DB) and is worth surfacing on the first-observed job.
+   */
+  async recordOccurrence(input) {
+    const { filter, update } = this.buildRecordOccurrencePayload(input);
+    try {
+      await this.collection.updateOne(filter, update, { upsert: true });
+    } catch (err) {
+      if (isDuplicateKeyError(err)) {
+        await this.collection.updateOne(filter, update, { upsert: true });
+        return;
+      }
+      throw err;
+    }
+  }
+  /**
+   * Builds the bulk write operation for `recordOccurrence` WITHOUT executing it.
+   * Returns a single upsert op matching the direct-call shape bit-for-bit.
+   *
+   * NOTE: `now` is captured at builder invocation time, NOT at BatchWriter flush
+   * time — firstSeenAt / lastSeenAt reflect the event's wall-clock, not the
+   * flush wall-clock. This preserves the semantic that these timestamps track
+   * the error's occurrence, not the observability pipeline's delay.
+   */
+  toRecordOccurrenceOp(input) {
+    const { filter, update } = this.buildRecordOccurrencePayload(input);
+    return asBulkUpdateOp({
+      updateOne: { filter, update, upsert: true }
+    });
+  }
+  buildRecordOccurrencePayload(input) {
+    const signature = errorSignature(input.error);
+    const { message, stack, causeChain } = extractMessageAndStack(input.error, {
+      messageMaxChars: JOB_ERRORS_MESSAGE_MAX_CHARS,
+      stackMaxChars: JOB_ERRORS_STACK_MAX_CHARS
+    });
+    const now = /* @__PURE__ */ new Date();
+    const filter = { signature };
+    const update = {
+      $inc: { count: 1 },
+      $setOnInsert: {
+        signature,
+        jobType: input.jobType,
+        message,
+        stack,
+        firstSeenAt: now,
+        createdAt: now,
+        ...causeChain.length > 0 ? { causeChain } : {}
+      },
+      $set: {
+        lastSeenAt: now,
+        updatedAt: now
+      }
+    };
+    return { filter, update };
+  }
+  async topErrors(options) {
+    if (!(options.limit > 0) || options.limit > JOB_ERRORS_MAX_TOP_LIMIT) {
+      throw new Error(
+        `JobErrorsRepo.topErrors: limit must be in (0, ${JOB_ERRORS_MAX_TOP_LIMIT}]`
+      );
+    }
+    const filter = {
+      ...options.jobType !== void 0 ? { jobType: options.jobType } : {},
+      ...options.since !== void 0 ? { lastSeenAt: { $gte: options.since } } : {}
+    };
+    return await this.collection.find(filter).sort({ count: -1 }).limit(options.limit).toArray();
+  }
+};
+
+// src/mongo/repositories/job-failures.repo.ts
+var COLLECTION5 = "job_failures";
+var DEFAULT_LIST_LIMIT = 50;
+var JobFailuresRepo = class extends Repository {
+  constructor(db2) {
+    super(db2, COLLECTION5);
+  }
+  indexes() {
+    return [
+      {
+        keys: { jobId: 1, failedAt: -1 },
+        options: { name: "jobId_failedAt_desc" }
+      },
+      {
+        keys: { jobType: 1, failedAt: -1 },
+        options: { name: "jobType_failedAt_desc" }
+      },
+      // NOTE (TTL migration): MongoDB's `createIndex` is a no-op when an index with the same
+      // key spec already exists — even if `expireAfterSeconds` differs. Changing
+      // `JOB_FAILURES_TTL_SECONDS` will NOT propagate to a running deployment; apply a `collMod`
+      // (or drop-and-recreate this index) manually at deploy time.
+      {
+        keys: { failedAt: 1 },
+        options: {
+          expireAfterSeconds: JOB_FAILURES_TTL_SECONDS,
+          name: "failedAt_ttl"
+        }
+      }
+    ];
+  }
+  async recordFailure(input) {
+    const doc = this.buildFailureDoc(input);
+    await this.collection.insertOne(doc);
+  }
+  /**
+   * Builds the bulk write operation for `recordFailure` WITHOUT executing it.
+   * Returns a single insertOne op matching the direct-call document shape
+   * bit-for-bit. Intended for the event-hooks layer (Story 1.7) to push through
+   * a `BatchWriter`. Throws synchronously on invalid input using the same error
+   * messages as `recordFailure`.
+   */
+  toRecordFailureOp(input) {
+    const doc = this.buildFailureDoc(input);
+    const op = { insertOne: { document: doc } };
+    return asBulkInsertOp(op);
+  }
+  buildFailureDoc(input) {
+    this.validateFailureInput(input);
+    const serializedInput = this.serializeInputValue(input.input).slice(
+      0,
+      JOB_FAILURES_INPUT_MAX_CHARS
+    );
+    const { message, stack, causeChain } = extractMessageAndStack(input.error, {
+      messageMaxChars: JOB_FAILURES_MESSAGE_MAX_CHARS,
+      stackMaxChars: JOB_FAILURES_STACK_MAX_CHARS
+    });
+    const logs = this.capLogs(input.logs);
+    const doc = {
+      jobId: input.jobId,
+      jobType: input.jobType,
+      input: serializedInput,
+      errorMessage: message,
+      errorStack: stack,
+      logs,
+      failedAt: input.failedAt,
+      createdAt: /* @__PURE__ */ new Date()
+    };
+    if (causeChain.length > 0) {
+      doc.causeChain = causeChain;
+    }
+    return doc;
+  }
+  validateFailureInput(input) {
+    if (typeof input.jobId !== "string" || input.jobId.trim().length === 0) {
+      throw new Error("JobFailuresRepo.recordFailure: jobId must be a non-empty string");
+    }
+    if (typeof input.jobType !== "string" || input.jobType.trim().length === 0) {
+      throw new Error("JobFailuresRepo.recordFailure: jobType must be a non-empty string");
+    }
+    if (!(input.failedAt instanceof Date) || Number.isNaN(input.failedAt.getTime())) {
+      throw new Error("JobFailuresRepo.recordFailure: failedAt must be a valid Date");
+    }
+  }
+  async listFailures(options) {
+    if (options.limit !== void 0) {
+      if (!Number.isInteger(options.limit) || options.limit <= 0 || options.limit > JOB_FAILURES_MAX_LIST_LIMIT) {
+        throw new Error(
+          `JobFailuresRepo.listFailures: limit must be an integer in (0, ${JOB_FAILURES_MAX_LIST_LIMIT}]`
+        );
+      }
+    }
+    if (options.skip !== void 0) {
+      if (!Number.isInteger(options.skip) || options.skip < 0) {
+        throw new Error(
+          "JobFailuresRepo.listFailures: skip must be a non-negative integer"
+        );
+      }
+    }
+    const fromDate = options.fromDate ?? void 0;
+    const toDate = options.toDate ?? void 0;
+    if (fromDate !== void 0 && (!(fromDate instanceof Date) || Number.isNaN(fromDate.getTime()))) {
+      throw new Error("JobFailuresRepo.listFailures: fromDate must be a valid Date");
+    }
+    if (toDate !== void 0 && (!(toDate instanceof Date) || Number.isNaN(toDate.getTime()))) {
+      throw new Error("JobFailuresRepo.listFailures: toDate must be a valid Date");
+    }
+    if (fromDate !== void 0 && toDate !== void 0 && fromDate.getTime() > toDate.getTime()) {
+      throw new Error("JobFailuresRepo.listFailures: fromDate must be <= toDate");
+    }
+    const skip = options.skip ?? 0;
+    const limit = options.limit ?? DEFAULT_LIST_LIMIT;
+    const filter = {};
+    if (options.jobType !== void 0) {
+      filter.jobType = options.jobType;
+    }
+    if (fromDate !== void 0 || toDate !== void 0) {
+      const range = {};
+      if (fromDate !== void 0) range.$gte = fromDate;
+      if (toDate !== void 0) range.$lte = toDate;
+      filter.failedAt = range;
+    }
+    const [items, total] = await Promise.all([
+      this.collection.find(filter).sort({ failedAt: -1 }).skip(skip).limit(limit).toArray(),
+      this.collection.countDocuments(filter)
+    ]);
+    return { items, total };
+  }
+  async getFailure(jobId) {
+    if (typeof jobId !== "string" || jobId.trim().length === 0) {
+      throw new Error("JobFailuresRepo.getFailure: jobId must be a non-empty string");
+    }
+    const filter = { jobId };
+    return await this.collection.findOne(filter, { sort: { failedAt: -1 } });
+  }
+  serializeInputValue(input) {
+    if (input === void 0) return "undefined";
+    try {
+      const result = JSON.stringify(input, (_key, value) => {
+        if (value instanceof Map) return { __type: "Map", entries: Array.from(value.entries()) };
+        if (value instanceof Set) return { __type: "Set", values: Array.from(value.values()) };
+        return value;
+      });
+      if (result === void 0) return "undefined";
+      return result;
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return `[input serialization failed: ${msg}]`;
+    }
+  }
+  capLogs(logs) {
+    if (logs === void 0) return "";
+    if (logs.length <= JOB_FAILURES_LOGS_MAX_CHARS) return logs;
+    const originalLen = logs.length;
+    let tailLen = JOB_FAILURES_LOGS_MAX_CHARS;
+    let marker = "";
+    for (let i = 0; i < 3; i++) {
+      marker = `[truncated \u2014 showing last ${tailLen} of ${originalLen} chars]
+`;
+      if (marker.length >= JOB_FAILURES_LOGS_MAX_CHARS) {
+        return marker.slice(0, JOB_FAILURES_LOGS_MAX_CHARS);
+      }
+      tailLen = JOB_FAILURES_LOGS_MAX_CHARS - marker.length;
+    }
+    return marker + logs.slice(-tailLen);
+  }
+};
+
+// src/mongo/repositories/job-configs.repo.ts
+var COLLECTION6 = "job_configs";
+var JobConfigsRepo = class extends Repository {
+  constructor(db2) {
+    super(db2, COLLECTION6);
+  }
+  indexes() {
+    return [
+      {
+        keys: { jobType: 1 },
+        options: { unique: true, name: "jobType_unique" }
+      }
+    ];
+  }
+  async getConfig(jobType) {
+    this.validateJobType(jobType, "JobConfigsRepo.getConfig");
+    const filter = { jobType };
+    const doc = await this.collection.findOne(filter);
+    if (!doc) {
+      return {
+        jobType,
+        enabled: JOB_CONFIGS_DEFAULT_ENABLED,
+        metadata: {}
+      };
+    }
+    return {
+      jobType: doc.jobType,
+      enabled: doc.enabled,
+      metadata: doc.metadata
+    };
+  }
+  async setEnabled(jobType, enabled) {
+    this.validateJobType(jobType, "JobConfigsRepo.setEnabled");
+    if (typeof enabled !== "boolean") {
+      throw new Error("JobConfigsRepo.setEnabled: enabled must be a boolean");
+    }
+    const filter = { jobType };
+    const update = {
+      $set: { enabled },
+      $setOnInsert: {
+        jobType,
+        metadata: {},
+        createdAt: /* @__PURE__ */ new Date()
+      },
+      $currentDate: { updatedAt: true }
+    };
+    const result = await this.collection.updateOne(filter, update, { upsert: true });
+    if (result.matchedCount === 0 && (result.upsertedCount ?? 0) === 0) {
+      throw new Error(
+        `JobConfigsRepo.setEnabled: updateOne acknowledged no write for jobType=${jobType}`
+      );
+    }
+  }
+  async listAll() {
+    return await this.collection.find({}).sort({ jobType: 1 }).toArray();
+  }
+  async isEnabled(jobType) {
+    this.validateJobType(jobType, "JobConfigsRepo.isEnabled");
+    const filter = { jobType };
+    const doc = await this.collection.findOne(filter, {
+      projection: { enabled: 1, _id: 0 }
+    });
+    if (!doc) {
+      return JOB_CONFIGS_DEFAULT_ENABLED;
+    }
+    return doc.enabled;
+  }
+  /**
+   * Idempotent bulk upsert of every registered jobType + its metadata
+   * projection (Story 5.1 D5.1-a). Called once per `RavenflowApp` instance
+   * inside `initializeMonitoring()`.
+   *
+   * Semantics:
+   *   - `$setOnInsert { enabled: true, createdAt }` — the enabled flag is
+   *     set to the default ONLY on initial insert. An operator-toggled
+   *     `enabled: false` is NEVER overwritten by a subsequent boot.
+   *   - `$set { metadata }` — metadata is always refreshed from code config
+   *     (code is source of truth for non-user-writable fields).
+   *   - `$currentDate { updatedAt }` — timestamp bumps every call.
+   *
+   * Metadata projection (narrow + stable — see D5.1-h):
+   *   - `type`: jobConfig.type (always present in the discriminated union).
+   *   - `queue`: jobConfig.queue ?? null (null = inherits defaultQueue).
+   *   - `cron`: jobConfig.cron if present (token-bucket only today), else null.
+   *
+   * Additional type-specific fields (token-bucket's `rate`, distributed-etl's
+   * `steps`) are NOT extracted — BSON can't serialize the function references
+   * they contain, and the dashboard surface consumes only `type`/`queue`/`cron`
+   * in V1. Future stories can widen this projection without a schema change.
+   *
+   * Failure mode: `bulkWrite` is the only I/O. Empty input short-circuits
+   * because the driver rejects empty ops arrays.
+   */
+  async ensureEntries(jobs) {
+    if (jobs === null || typeof jobs !== "object") return;
+    const entries = Object.entries(jobs);
+    if (entries.length === 0) return;
+    for (const [jobType] of entries) {
+      this.validateJobType(jobType, "JobConfigsRepo.ensureEntries");
+    }
+    const ops = entries.map(
+      ([jobType, cfg]) => {
+        const cron = "cron" in cfg && typeof cfg.cron === "string" && cfg.cron.length > 0 ? cfg.cron : null;
+        const metadata = {
+          type: cfg.type,
+          queue: cfg.queue ?? null,
+          cron
+        };
+        const update = {
+          $setOnInsert: {
+            jobType,
+            enabled: JOB_CONFIGS_DEFAULT_ENABLED,
+            createdAt: /* @__PURE__ */ new Date()
+          },
+          $set: { metadata },
+          $currentDate: { updatedAt: true }
+        };
+        return asBulkUpdateOp({
+          updateOne: {
+            filter: { jobType },
+            update,
+            upsert: true
+          }
+        });
+      }
+    );
+    await this.collection.bulkWrite(ops, { ordered: false });
+  }
+  validateJobType(jobType, ctx) {
+    if (typeof jobType !== "string" || jobType.trim().length === 0) {
+      throw new Error(`${ctx}: jobType must be a non-empty string`);
+    }
+    if (jobType.includes(".") || jobType.includes("$")) {
+      throw new Error(
+        `${ctx}: jobType cannot contain '.' or '$' (Mongo-reserved characters)`
+      );
+    }
+  }
+};
+var WorkerRegistry = class _WorkerRegistry {
+  constructor(repo, options = {}) {
+    this.timer = null;
+    this.started = false;
+    this.registered = false;
+    _WorkerRegistry.validateHeartbeatInterval(options.heartbeatIntervalMs);
+    this.repo = repo;
+    this.heartbeatIntervalMs = options.heartbeatIntervalMs ?? WORKERS_DEFAULT_HEARTBEAT_INTERVAL_MS;
+    this.hostname = options.hostnameProvider ? options.hostnameProvider() : os__namespace.hostname();
+    this.pid = options.pidProvider ? options.pidProvider() : process.pid;
+    this._workerId = options.workerIdProvider ? options.workerIdProvider() : `${this.hostname}:${this.pid}:${crypto__namespace.randomUUID()}`;
+    this.clock = options.clock ?? (() => /* @__PURE__ */ new Date());
+    this.startedAt = this.clock();
+  }
+  get workerId() {
+    return this._workerId;
+  }
+  async registerQueue(queue) {
+    _WorkerRegistry.validateQueueEntry(queue);
+    if (!this.registered) {
+      await this.repo.registerWorker({
+        workerId: this._workerId,
+        hostname: this.hostname,
+        pid: this.pid,
+        queues: [queue],
+        startedAt: this.startedAt
+      });
+      this.registered = true;
+      return;
+    }
+    await this.repo.addQueue({
+      workerId: this._workerId,
+      queue
+    });
+  }
+  async start() {
+    if (this.started) return;
+    if (!this.registered) {
+      throw new Error(
+        "WorkerRegistry.start: call registerQueue at least once before start"
+      );
+    }
+    this.timer = setInterval(() => {
+      void this.doHeartbeat();
+    }, this.heartbeatIntervalMs);
+    this.timer.unref();
+    this.started = true;
+  }
+  async stop() {
+    if (this.timer !== null) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    this.started = false;
+    if (!this.registered) return;
+    try {
+      await this.repo.deregisterWorker(this._workerId);
+    } catch (err) {
+      getLogger().warn(
+        { err, workerId: this._workerId },
+        "[worker-registry] deregister failed on stop"
+      );
+    }
+    this.registered = false;
+  }
+  async doHeartbeat() {
+    try {
+      await this.repo.updateHeartbeat(this._workerId);
+    } catch (err) {
+      getLogger().warn(
+        { err, workerId: this._workerId },
+        "[worker-registry] heartbeat failed \u2014 will retry next tick"
+      );
+    }
+  }
+  static validateHeartbeatInterval(value) {
+    if (value == null) return;
+    const MAX_HEARTBEAT_INTERVAL_MS = 24 * 60 * 60 * 1e3;
+    if (!Number.isInteger(value) || value < WORKERS_MIN_HEARTBEAT_INTERVAL_MS || value > MAX_HEARTBEAT_INTERVAL_MS) {
+      throw new Error(
+        `[ravenflow] WorkerRegistry heartbeatIntervalMs must be an integer in [${WORKERS_MIN_HEARTBEAT_INTERVAL_MS}, ${MAX_HEARTBEAT_INTERVAL_MS}], got ${value}`
+      );
+    }
+  }
+  static validateQueueEntry(q) {
+    if (q === null || typeof q !== "object") {
+      throw new Error("WorkerRegistry.registerQueue: queue must be an object");
+    }
+    if (typeof q.name !== "string" || q.name.length === 0) {
+      throw new Error(
+        "WorkerRegistry.registerQueue: queue.name must be a non-empty string"
+      );
+    }
+    if (!Number.isInteger(q.concurrency) || q.concurrency <= 0) {
+      throw new Error(
+        "WorkerRegistry.registerQueue: queue.concurrency must be a positive integer"
+      );
+    }
+  }
+};
+
+// src/monitoring/batch-writer.types.ts
+var DEFAULT_FLUSH_INTERVAL_MS = 3e4;
+var MIN_BUFFER_SIZE = 1e3;
+var MAX_BUFFER_SIZE = 5e3;
+var HARD_CAP_MULTIPLIER = 10;
+var DRAIN_RETRY_BACKOFFS_MS = [0, 1e3, 2e3, 4e3];
+
+// src/monitoring/batch-writer.ts
+var BatchWriter = class {
+  constructor(collection3, config) {
+    this.buffer = [];
+    this.timer = null;
+    this.flushing = null;
+    this.drained = false;
+    this.validateConfig(config);
+    this.collection = collection3;
+    this.maxBufferSize = config.maxBufferSize;
+    this.hardCapSize = config.maxBufferSize * HARD_CAP_MULTIPLIER;
+    this.flushIntervalMs = config.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS;
+    this.startTimer();
+  }
+  push(operation) {
+    if (this.drained) {
+      getLogger().warn(
+        "[batch-writer] push called after drain \u2014 operation ignored"
+      );
+      return;
+    }
+    this.buffer.push(operation);
+    this.enforceHardCap();
+    if (this.buffer.length >= this.maxBufferSize) {
+      this.resetTimer();
+      void this.flush();
+    }
+  }
+  async drain() {
+    this.drained = true;
+    this.stopTimer();
+    if (this.flushing) await this.flushing;
+    for (const backoffMs of DRAIN_RETRY_BACKOFFS_MS) {
+      if (this.buffer.length === 0) return;
+      if (backoffMs > 0) {
+        await new Promise((resolve2) => setTimeout(resolve2, backoffMs));
+      }
+      await this.flush();
+    }
+    if (this.buffer.length > 0) {
+      getLogger().error(
+        { unflushed: this.buffer.length },
+        "[batch-writer] drain exhausted retries \u2014 operations lost"
+      );
+    }
+  }
+  async flush() {
+    if (this.flushing) return this.flushing;
+    if (this.buffer.length === 0) return;
+    this.flushing = this.doFlush();
+    try {
+      await this.flushing;
+    } finally {
+      this.flushing = null;
+    }
+  }
+  async doFlush() {
+    while (this.buffer.length > 0) {
+      const snapshot = this.buffer;
+      this.buffer = [];
+      try {
+        await this.collection.bulkWrite(snapshot, {
+          ordered: false,
+          maxTimeMS: this.flushIntervalMs
+        });
+      } catch (err) {
+        if (err instanceof mongodb.MongoBulkWriteError && Array.isArray(err.writeErrors) && err.writeErrors.length > 0) {
+          getLogger().warn(
+            {
+              failed: err.writeErrors.length,
+              total: snapshot.length
+            },
+            "[batch-writer] bulkWrite partial failure \u2014 dropping failed ops (likely persistent errors)"
+          );
+          continue;
+        }
+        this.buffer = [...snapshot, ...this.buffer];
+        this.enforceHardCap();
+        getLogger().warn(
+          { err, count: snapshot.length },
+          "[batch-writer] flush failed \u2014 will retry on next tick or threshold"
+        );
+        return;
+      }
+    }
+  }
+  enforceHardCap() {
+    if (this.buffer.length <= this.hardCapSize) return;
+    const dropCount = this.buffer.length - this.hardCapSize;
+    this.buffer.splice(0, dropCount);
+    getLogger().warn(
+      { dropCount, hardCapSize: this.hardCapSize },
+      "[batch-writer] hard cap exceeded \u2014 dropped oldest operations"
+    );
+  }
+  startTimer() {
+    this.timer = setInterval(() => {
+      void this.flush();
+    }, this.flushIntervalMs);
+    this.timer.unref();
+  }
+  stopTimer() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+  resetTimer() {
+    this.stopTimer();
+    this.startTimer();
+  }
+  validateConfig(config) {
+    if (!Number.isInteger(config.maxBufferSize) || config.maxBufferSize < MIN_BUFFER_SIZE || config.maxBufferSize > MAX_BUFFER_SIZE) {
+      throw new Error(
+        `[ravenflow] BatchWriter maxBufferSize must be an integer in [${MIN_BUFFER_SIZE}, ${MAX_BUFFER_SIZE}], got ${config.maxBufferSize}`
+      );
+    }
+    if (config.flushIntervalMs !== void 0) {
+      if (!Number.isInteger(config.flushIntervalMs) || config.flushIntervalMs <= 0) {
+        throw new Error(
+          `[ravenflow] BatchWriter flushIntervalMs must be a positive integer, got ${config.flushIntervalMs}`
+        );
+      }
+    }
+  }
+};
+
+// src/monitoring/log-capture.ts
+async function captureJobLogs(queue, jobId, maxChars) {
+  if (typeof jobId !== "string" || jobId.length === 0) {
+    throw new Error("captureJobLogs: jobId must be a non-empty string");
+  }
+  if (!Number.isInteger(maxChars) || maxChars <= 0) {
+    throw new Error(
+      `captureJobLogs: maxChars must be a positive integer, got ${maxChars}`
+    );
+  }
+  let logs;
+  try {
+    const result = await queue.getJobLogs(jobId, 0, -1, true);
+    logs = result.logs;
+  } catch (err) {
+    getLogger().warn(
+      { err, jobId },
+      "[log-capture] failed to fetch job logs \u2014 returning empty string"
+    );
+    return "";
+  }
+  const joined = logs.join("\n");
+  if (joined.length <= maxChars) return joined;
+  const originalLen = joined.length;
+  let tailLen = maxChars;
+  let marker = "";
+  for (let i = 0; i < 3; i++) {
+    marker = `[truncated \u2014 showing last ${tailLen} of ${originalLen} chars]
+`;
+    if (marker.length >= maxChars) {
+      return marker.slice(0, maxChars);
+    }
+    tailLen = maxChars - marker.length;
+  }
+  return marker + joined.slice(-tailLen);
+}
+
+// src/monitoring/event-hooks.ts
+function attachEventHooks(worker, options) {
+  worker.on("completed", (job) => {
+    void handleCompleted(job, options);
+  });
+  worker.on("failed", (job, error) => {
+    void handleFailed(job, error, options);
+  });
+}
+async function handleCompleted(job, options) {
+  try {
+    const jobType = resolveTopLevelJobType(job, options.jobConfigs);
+    if (jobType === null) return;
+    const durationMs = computeDurationMs(job);
+    const ops = options.jobStatsRepo.toIncrementStatsOps(jobType, {
+      success: true,
+      durationMs
+    });
+    for (const op of ops) {
+      options.jobStatsBatchWriter.push(op);
+    }
+  } catch (err) {
+    getLogger().warn(
+      { err, jobId: job?.id, path: "stats" },
+      "[event-hooks] completed handler failed"
+    );
+  }
+}
+async function handleFailed(job, error, options) {
+  if (job === void 0) {
+    getLogger().warn(
+      { message: error?.message },
+      "[event-hooks] failed event fired without a job \u2014 skipping"
+    );
+    return;
+  }
+  if (job.id === void 0 || job.id === null) {
+    getLogger().warn(
+      { jobName: job.name },
+      "[event-hooks] failed event fired without a job.id \u2014 skipping"
+    );
+    return;
+  }
+  try {
+    const jobType = resolveTopLevelJobType(job, options.jobConfigs);
+    if (jobType === null) return;
+    const durationMs = computeDurationMs(job);
+    const failedAt = typeof job.finishedOn === "number" && Number.isFinite(job.finishedOn) ? new Date(job.finishedOn) : /* @__PURE__ */ new Date();
+    const jobId = String(job.id);
+    const logsMaxChars = options.logsMaxChars ?? JOB_FAILURES_LOGS_MAX_CHARS;
+    try {
+      const ops = options.jobStatsRepo.toIncrementStatsOps(jobType, {
+        success: false,
+        durationMs
+      });
+      for (const op of ops) {
+        options.jobStatsBatchWriter.push(op);
+      }
+    } catch (err) {
+      getLogger().warn(
+        { err, jobId, path: "stats" },
+        "[event-hooks] failed handler: stats write failed"
+      );
+    }
+    try {
+      const op = options.jobErrorsRepo.toRecordOccurrenceOp({
+        jobType,
+        error
+      });
+      options.jobErrorsBatchWriter.push(op);
+    } catch (err) {
+      getLogger().warn(
+        { err, jobId, path: "errors" },
+        "[event-hooks] failed handler: errors write failed"
+      );
+    }
+    let logs = "";
+    try {
+      logs = await captureJobLogs(options.queue, jobId, logsMaxChars);
+    } catch (err) {
+      getLogger().warn(
+        { err, jobId, path: "failures" },
+        "[event-hooks] failed handler: log capture failed \u2014 recording failure with empty logs"
+      );
+    }
+    try {
+      const op = options.jobFailuresRepo.toRecordFailureOp({
+        jobId,
+        jobType,
+        input: job.data,
+        error,
+        failedAt,
+        logs
+      });
+      options.jobFailuresBatchWriter.push(op);
+    } catch (err) {
+      getLogger().warn(
+        { err, jobId, path: "failures" },
+        "[event-hooks] failed handler: failures write failed"
+      );
+    }
+  } catch (err) {
+    getLogger().warn(
+      { err, jobId: job.id, path: "unknown" },
+      "[event-hooks] failed handler failed"
+    );
+  }
+}
+function computeDurationMs(job) {
+  const processedOn = job.processedOn;
+  const finishedOn = job.finishedOn;
+  if (typeof processedOn !== "number" || !Number.isFinite(processedOn)) return void 0;
+  if (typeof finishedOn !== "number" || !Number.isFinite(finishedOn)) return void 0;
+  const delta = finishedOn - processedOn;
+  if (delta < 0) return void 0;
+  return delta;
+}
+function resolveTopLevelJobType(job, jobConfigs) {
+  const { baseName, suffix } = resolveJobName(job.name, jobConfigs);
+  if (suffix !== null) return null;
+  if (!Object.prototype.hasOwnProperty.call(jobConfigs, baseName)) {
+    getLogger().debug(
+      { jobName: job.name, jobId: job.id },
+      "[event-hooks] skipping event for unknown jobType"
+    );
+    return null;
+  }
+  return baseName;
+}
+var DISABLED_JOB_DEFER_DELAY_MS = 6e4;
+async function safeEnsureEntriesAtBoot(jobConfigsRepo, jobs) {
+  try {
+    await jobConfigsRepo.ensureEntries(jobs);
+  } catch (err) {
+    getLogger().error(
+      { err },
+      "[app] job_configs ensureEntries failed at boot \u2014 dashboard may show a stale job-type list"
+    );
+  }
+}
+async function deferIfDisabled(job, jobConfigs, jobConfigsRepo, token) {
+  if (typeof job.name !== "string" || job.name.length === 0) return;
+  if (jobConfigs === null || typeof jobConfigs !== "object") return;
+  if (token === void 0) {
+    getLogger().warn(
+      { jobId: job.id, jobName: job.name },
+      "[app] deferIfDisabled invoked with undefined token \u2014 moveToDelayed may fail under lock contention"
+    );
+  }
+  const { baseName } = resolveJobName(job.name, jobConfigs);
+  if (!baseName) {
+    getLogger().warn(
+      { jobId: job.id, jobName: job.name },
+      "[app] deferIfDisabled: resolveJobName returned empty baseName \u2014 skipping gate"
+    );
+    return;
+  }
+  const enabled = await jobConfigsRepo.isEnabled(baseName);
+  if (enabled) return;
+  const prev = job.progress;
+  const prevCount = typeof prev === "object" && prev !== null && !Array.isArray(prev) ? prev.disabledDeferCount : void 0;
+  const nextCount = typeof prevCount === "number" && Number.isFinite(prevCount) ? prevCount + 1 : 1;
+  await job.moveToDelayed(Date.now() + DISABLED_JOB_DEFER_DELAY_MS, token);
+  try {
+    await job.updateProgress({ disabledDeferCount: nextCount });
+  } catch (err) {
+    getLogger().warn(
+      { err, jobType: baseName, jobId: job.id },
+      "[app] deferIfDisabled: updateProgress failed post-defer \u2014 counter may lag by one"
+    );
+  }
+  getLogger().info(
+    { jobType: baseName, jobId: job.id, disabledDeferCount: nextCount },
+    "[app] job deferred: disabled"
+  );
+  throw new bullmq.DelayedError();
+}
+
 // src/app/app.ts
+var DEFAULT_MONITORING_BATCH_BUFFER = MIN_BUFFER_SIZE;
 var MONGO_REQUIRED_TYPES = /* @__PURE__ */ new Set(["stateful-etl", "token-bucket"]);
 function resolveMongoUri(mongo) {
   if (!mongo) return null;
@@ -1348,9 +2646,39 @@ function validateConfig(config, mongoUri) {
         `"${jobName}" (${jc.type}) requires a mongo connection. Pass { mongo: "mongodb://..." } to createRavenflowApp().`
       );
     }
-    if (jc.type === "token-bucket" && !jc.cron) {
+    if (jc.type === "token-bucket" && !jc.cron?.trim()) {
       errors.push(`"${jobName}" (token-bucket) requires a cron schedule.`);
     }
+    if (jc.type === "token-bucket" && !jc.rate && !jc.getBudget) {
+      errors.push(
+        `"${jobName}" (token-bucket) requires at least one of "rate" or "getBudget".`
+      );
+    }
+    if (jc.type === "token-bucket" && jc.rate) {
+      const validIntervals = /* @__PURE__ */ new Set(["second", "minute", "hour", "day", "week"]);
+      if (!validIntervals.has(jc.rate.interval)) {
+        errors.push(
+          `"${jobName}" (token-bucket) has invalid rate interval "${jc.rate.interval}". Must be one of: second, minute, hour, day, week.`
+        );
+      }
+      if (jc.rate.amount <= 0) {
+        errors.push(
+          `"${jobName}" (token-bucket) rate.amount must be a positive number.`
+        );
+      }
+    }
+    if (jc.type === "token-bucket") {
+      if (jc.maxCarryOver !== void 0 && jc.maxCarryOver < 0) {
+        errors.push(
+          `"${jobName}" (token-bucket) maxCarryOver must be >= 0.`
+        );
+      }
+      if (jc.consumeTimeout !== void 0 && jc.consumeTimeout <= 0) {
+        errors.push(
+          `"${jobName}" (token-bucket) consumeTimeout must be a positive number.`
+        );
+      }
+    }
     if ("steps" in jc && jc.steps) {
       for (const [stepName, stepConfig] of Object.entries(jc.steps)) {
         if (stepConfig?.queue && stepConfig.queue !== config.defaultQueue) {
@@ -1379,6 +2707,16 @@ var RavenflowApp = class {
     this.defaultConcurrency = 5;
     this.workers = [];
     this.stallWatcher = null;
+    this.workersRepo = null;
+    this.workerRegistry = null;
+    this.jobStatsRepo = null;
+    this.jobErrorsRepo = null;
+    this.jobFailuresRepo = null;
+    this.jobConfigsRepo = null;
+    this.jobStatsBatchWriter = null;
+    this.jobErrorsBatchWriter = null;
+    this.jobFailuresBatchWriter = null;
+    this.monitoringInitPromise = null;
     this.redisConnection = options.redis;
     this.config = config;
     this.mongoUri = resolveMongoUri(options.mongo);
@@ -1388,16 +2726,52 @@ var RavenflowApp = class {
     const { jobsProxy, jobConfigs } = initJobs(config, this.queues);
     this.jobs = jobsProxy;
     this.jobConfigs = jobConfigs;
+    this.monitoringOptions = {
+      enabled: this.mongoUri !== null && options.monitoring?.enabled !== false,
+      heartbeatIntervalMs: options.monitoring?.heartbeatIntervalMs,
+      batchWriter: {
+        maxBufferSize: options.monitoring?.batchWriter?.maxBufferSize ?? DEFAULT_MONITORING_BATCH_BUFFER,
+        flushIntervalMs: options.monitoring?.batchWriter?.flushIntervalMs
+      }
+    };
+    if (options.monitoring?.enabled === true && this.mongoUri === null) {
+      getLogger().warn(
+        {},
+        "[ravenflow] monitoring.enabled=true was requested but no mongo connection is configured \u2014 monitoring is disabled"
+      );
+    }
   }
   async startWorker(queueName, options) {
     if (this.mongoUri) {
       await connectMongo(this.mongoUri);
+      await token_bucket_repo_exports.ensureIndexes();
     }
     const queueData = this.queues[queueName];
     if (!queueData) {
       throw new Error(`Queue ${queueName} not found in config.`);
     }
     const concurrency = options?.concurrency ?? this.defaultConcurrency;
+    if (this.mongoUri && this.monitoringOptions.enabled) {
+      if (!this.workerRegistry) {
+        if (!this.monitoringInitPromise) {
+          this.monitoringInitPromise = this.initializeMonitoring(queueName, concurrency);
+        }
+        try {
+          await this.monitoringInitPromise;
+        } catch {
+        }
+      }
+      if (this.workerRegistry) {
+        try {
+          await this.workerRegistry.registerQueue({ name: queueName, concurrency });
+        } catch (err) {
+          getLogger().error(
+            { err },
+            "[app] worker registry registerQueue failed \u2014 will retry on next startWorker call"
+          );
+        }
+      }
+    }
     printBanner(
       queueName,
       concurrency,
@@ -1421,7 +2795,16 @@ var RavenflowApp = class {
       queueName,
       this.redisConnection,
       concurrency,
-      async (job) => {
+      async (job, token) => {
+        const configsRepo = this.jobConfigsRepo;
+        if (configsRepo) {
+          await deferIfDisabled(
+            job,
+            this.jobConfigs,
+            configsRepo,
+            token
+          );
+        }
         if (this.stallWatcher?.canProcess(job.name)) {
           return this.stallWatcher.process(job);
         }
@@ -1431,10 +2814,100 @@ var RavenflowApp = class {
     setupWorkerEvents(worker, queueName);
     this.workers.push(worker);
     worker.run();
+    if (this.monitoringOptions.enabled && this.jobStatsRepo && this.jobErrorsRepo && this.jobFailuresRepo && this.jobStatsBatchWriter && this.jobErrorsBatchWriter && this.jobFailuresBatchWriter) {
+      attachEventHooks(worker, {
+        queue: queueData.queue,
+        jobConfigs: this.jobConfigs,
+        jobStatsRepo: this.jobStatsRepo,
+        jobErrorsRepo: this.jobErrorsRepo,
+        jobFailuresRepo: this.jobFailuresRepo,
+        jobStatsBatchWriter: this.jobStatsBatchWriter,
+        jobErrorsBatchWriter: this.jobErrorsBatchWriter,
+        jobFailuresBatchWriter: this.jobFailuresBatchWriter
+      });
+    }
     if (this.stallWatcher) {
       await this.stallWatcher.start();
     }
   }
+  async initializeMonitoring(queueName, concurrency) {
+    let registry = null;
+    let statsBatchWriter = null;
+    let errorsBatchWriter = null;
+    let failuresBatchWriter = null;
+    try {
+      const db2 = getDb();
+      const workersRepo = new WorkersRepo(db2);
+      const statsRepo = new JobStatsRepo(db2);
+      const errorsRepo = new JobErrorsRepo(db2);
+      const failuresRepo = new JobFailuresRepo(db2);
+      const configsRepo = new JobConfigsRepo(db2);
+      await Promise.all([
+        workersRepo.init(),
+        statsRepo.init(),
+        errorsRepo.init(),
+        failuresRepo.init(),
+        configsRepo.init()
+      ]);
+      await safeEnsureEntriesAtBoot(
+        configsRepo,
+        this.config.jobs
+      );
+      registry = new WorkerRegistry(workersRepo, {
+        heartbeatIntervalMs: this.monitoringOptions.heartbeatIntervalMs
+      });
+      await registry.registerQueue({ name: queueName, concurrency });
+      await registry.start();
+      statsBatchWriter = new BatchWriter(
+        statsRepo.collection,
+        this.monitoringOptions.batchWriter
+      );
+      errorsBatchWriter = new BatchWriter(
+        errorsRepo.collection,
+        this.monitoringOptions.batchWriter
+      );
+      failuresBatchWriter = new BatchWriter(
+        failuresRepo.collection,
+        this.monitoringOptions.batchWriter
+      );
+      this.workersRepo = workersRepo;
+      this.workerRegistry = registry;
+      this.jobStatsRepo = statsRepo;
+      this.jobErrorsRepo = errorsRepo;
+      this.jobFailuresRepo = failuresRepo;
+      this.jobConfigsRepo = configsRepo;
+      this.jobStatsBatchWriter = statsBatchWriter;
+      this.jobErrorsBatchWriter = errorsBatchWriter;
+      this.jobFailuresBatchWriter = failuresBatchWriter;
+    } catch (err) {
+      getLogger().error(
+        { err },
+        "[app] monitoring setup failed \u2014 continuing without observability writes"
+      );
+      if (registry) {
+        await registry.stop().catch(() => {
+        });
+      }
+      const drainables = [statsBatchWriter, errorsBatchWriter, failuresBatchWriter].filter(
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- heterogeneous BatchWriter union; typed narrowing deferred per Story 1.8 AC #14
+        (bw) => bw !== null
+      );
+      if (drainables.length > 0) {
+        await Promise.allSettled(drainables.map((bw) => bw.drain()));
+      }
+      this.workerRegistry = null;
+      this.workersRepo = null;
+      this.jobStatsRepo = null;
+      this.jobErrorsRepo = null;
+      this.jobFailuresRepo = null;
+      this.jobConfigsRepo = null;
+      this.jobStatsBatchWriter = null;
+      this.jobErrorsBatchWriter = null;
+      this.jobFailuresBatchWriter = null;
+    } finally {
+      this.monitoringInitPromise = null;
+    }
+  }
   async close() {
     const logger2 = getLogger();
     logger2.info("Shutting down...");
@@ -1442,7 +2915,28 @@ var RavenflowApp = class {
       await this.stallWatcher.stop();
       this.stallWatcher = null;
     }
+    if (this.workerRegistry) {
+      await this.workerRegistry.stop();
+      this.workerRegistry = null;
+      this.workersRepo = null;
+    }
     await closeWorkers(this.workers);
+    const drainables = [
+      this.jobStatsBatchWriter,
+      this.jobErrorsBatchWriter,
+      this.jobFailuresBatchWriter
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- heterogeneous BatchWriter union; typed narrowing deferred per Story 1.8 AC #14
+    ].filter((bw) => bw !== null);
+    if (drainables.length > 0) {
+      await Promise.allSettled(drainables.map((bw) => bw.drain()));
+    }
+    this.jobStatsBatchWriter = null;
+    this.jobErrorsBatchWriter = null;
+    this.jobFailuresBatchWriter = null;
+    this.jobStatsRepo = null;
+    this.jobErrorsRepo = null;
+    this.jobFailuresRepo = null;
+    this.jobConfigsRepo = null;
     await closeQueues(this.queues);
     await closeMongo();
     logger2.info("Shutdown complete.");
@@ -1454,14 +2948,34 @@ function createRavenflowApp(config, options) {
   return new RavenflowApp(config, options);
 }
 
+exports.BatchWriter = BatchWriter;
+exports.DEFAULT_WORKER_METRICS = DEFAULT_WORKER_METRICS;
+exports.DISABLED_JOB_DEFER_DELAY_MS = DISABLED_JOB_DEFER_DELAY_MS;
+exports.JOB_FAILURES_INPUT_MAX_CHARS = JOB_FAILURES_INPUT_MAX_CHARS;
+exports.JOB_FAILURES_LOGS_MAX_CHARS = JOB_FAILURES_LOGS_MAX_CHARS;
+exports.JOB_FAILURES_MESSAGE_MAX_CHARS = JOB_FAILURES_MESSAGE_MAX_CHARS;
+exports.JOB_FAILURES_STACK_MAX_CHARS = JOB_FAILURES_STACK_MAX_CHARS;
+exports.JobConfigsRepo = JobConfigsRepo;
+exports.JobErrorsRepo = JobErrorsRepo;
+exports.JobFailuresRepo = JobFailuresRepo;
+exports.JobStatsRepo = JobStatsRepo;
+exports.METRICS_TIME = METRICS_TIME;
 exports.RavenflowApp = RavenflowApp;
+exports.Repository = Repository;
+exports.WorkerRegistry = WorkerRegistry;
+exports.WorkersRepo = WorkersRepo;
+exports.attachEventHooks = attachEventHooks;
+exports.captureJobLogs = captureJobLogs;
+exports.computeBucketStart = computeBucketStart;
 exports.createRavenflowApp = createRavenflowApp;
+exports.deferIfDisabled = deferIfDisabled;
 exports.defineConfig = defineConfig;
 exports.defineDistributedEtlJob = defineDistributedEtlJob;
 exports.defineMemoryEtlJob = defineMemoryEtlJob;
 exports.defineSimpleJob = defineSimpleJob;
 exports.defineStatefulEtlJob = defineStatefulEtlJob;
 exports.defineTokenBucketJob = defineTokenBucketJob;
+exports.errorSignature = errorSignature;
 exports.getLogger = getLogger;
 exports.initLogger = initLogger;
 //# sourceMappingURL=index.js.map