@inetafrica/open-claudia 2.14.8 → 3.0.0

package/core/jobs.js

@@ -1,99 +1,616 @@
-// Unified persistent store for scheduled work — both one-shot wakeups
-// the agent set for itself ("check back in 30 min") and recurring crons
-// (user-defined or agent-defined). Survives bot restarts.
+// Durable provider-aware store for one-shot wakeups and recurring crons.
 //
-// Entry shape:
-//   {
-//     id: "job_<ts>_<rand>",
-//     kind: "wakeup" | "cron",
-//     adapter: "<adapter-id>",       // e.g. "telegram-1" / "kazee-1"
-//     adapterType: "telegram"|"kazee",
-//     channelId: "<chat or channel id>",
-//     canonicalUserId: "telegram:<id>" or "<email>",
-//     project: "<project-name>" or null,
-//     prompt: "<text to send as if user>",
-//     label: "<short>",
-//     source: "agent" | "user",
-//     // wakeup-only
-//     fireAt: <ms epoch>,
-//     // cron-only
-//     schedule: "<5-field cron>",
-//     // session pinning (per choice a/i):
-//     sessionKey: "lastSessionId" | "cursorSessionId" | "codexSessionId" | null,
-//     sessionId: "<claude-session-id>" | null,
-//     createdAt: <ms>,
-//     lastFireAt: <ms> | null,
-//     lastFireOk: true|false|null,
-//   }
+// Runnable entries are pinned to one canonical user, channel, project,
+// provider, provider-settings snapshot, and native session lineage. Legacy
+// entries that cannot be classified safely stay in `archived` and are never
+// returned by listAll() or scheduled.
 
+"use strict";
+
+const crypto = require("crypto");
 const fs = require("fs");
 const path = require("path");
-const { JOBS_FILE } = require("./config");
+const {
+  CONFIG_DIR,
+  CRONS_FILE,
+  JOBS_FILE,
+  SESSIONS_FILE,
+  STATE_FILE,
+} = require("./config");
+const { atomicWriteFileSync } = require("./fsutil");
+const {
+  defaultMigrationSources,
+  markMigrationComponentActivated,
+  markMigrationComponentPrepared,
+  requireMigrationSnapshotForComponent,
+  sha256,
+} = require("./migration-backup");
+
+const JOBS_SCHEMA_VERSION = 2;
+const DEFAULT_MAX_ATTEMPTS = 5;
+const RUNNABLE_PROVIDERS = new Set(["claude", "codex"]);
+const PROVIDER_SETTING_KEYS = Object.freeze(["model", "effort", "budget", "permissionMode", "worktree"]);
+const LEGACY_SESSION_KEY = "sessionKey";
+const LEGACY_CRON_ARCHIVE_REASON = "Legacy cron had no saved provider/session identity and is disabled";
 
-function load() {
-  try {
-    const raw = JSON.parse(fs.readFileSync(JOBS_FILE, "utf-8"));
-    return Array.isArray(raw) ? raw : [];
-  } catch (e) { return []; }
+function isRecord(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
 }
 
-function save(list) {
-  fs.mkdirSync(path.dirname(JOBS_FILE), { recursive: true });
-  const tmp = `${JOBS_FILE}.tmp`;
-  fs.writeFileSync(tmp, JSON.stringify(list, null, 2));
-  fs.renameSync(tmp, JOBS_FILE);
+function nonEmpty(value) {
+  const text = value === null || value === undefined ? "" : String(value).trim();
+  return text || null;
 }
 
-function nextId(kind) {
-  return `${kind}_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+function clone(value) {
+  return value === undefined ? undefined : structuredClone(value);
+}
+
+function occurrenceId(job, options = {}) {
+  if (nonEmpty(job.occurrenceId)) return nonEmpty(job.occurrenceId);
+  const factory = options.occurrenceIdFactory || (() => (
+    typeof crypto.randomUUID === "function"
+      ? crypto.randomUUID()
+      : `${Date.now()}-${crypto.randomBytes(6).toString("hex")}`
+  ));
+  return nonEmpty(factory(job)) || `${job.id || "job"}-${Date.now()}`;
 }
 
-function add(job) {
-  const list = load();
-  const entry = { createdAt: Date.now(), lastFireAt: null, lastFireOk: null, ...job };
-  if (!entry.id) entry.id = nextId(entry.kind || "job");
-  list.push(entry);
-  save(list);
-  return entry;
+function nowMs(options = {}) {
+  const value = typeof options.now === "function" ? options.now() : Date.now();
+  const number = value instanceof Date ? value.getTime() : Number(value);
+  if (!Number.isFinite(number)) throw new TypeError("jobs clock returned an invalid time");
+  return number;
 }
 
-function remove(id) {
-  const list = load();
-  const idx = list.findIndex((j) => j.id === id);
-  if (idx < 0) return null;
-  const [removed] = list.splice(idx, 1);
-  save(list);
-  return removed;
+function legacyProvider(record) {
+  const explicit = nonEmpty(record.provider)?.toLowerCase() || null;
+  if (explicit) return explicit;
+  const key = nonEmpty(record[LEGACY_SESSION_KEY]);
+  if (key === "lastSessionId") return "claude";
+  if (key === "codexSessionId") return "codex";
+  if (key === "cursorSessionId") return "cursor";
+  return null;
 }
 
-function update(id, patch) {
-  const list = load();
-  const idx = list.findIndex((j) => j.id === id);
-  if (idx < 0) return null;
-  list[idx] = { ...list[idx], ...patch };
-  save(list);
-  return list[idx];
+function archiveLegacyJob(record, reason, options = {}) {
+  const archived = {
+    ...clone(record),
+    id: nonEmpty(record?.id) || `archived-${occurrenceId(record || {}, options)}`,
+    provider: legacyProvider(record || {}),
+    project: nonEmpty(record?.project),
+    sessionId: nonEmpty(record?.sessionId),
+    status: "archived",
+    disabled: true,
+    archiveReason: reason,
+    archivedAt: Number.isFinite(options.archivedAt) ? options.archivedAt : nowMs(options),
+  };
+  if (Object.prototype.hasOwnProperty.call(archived, LEGACY_SESSION_KEY)) {
+    archived.legacySessionPointerField = archived[LEGACY_SESSION_KEY];
+    delete archived[LEGACY_SESSION_KEY];
+  }
+  return archived;
 }
 
-function get(id) {
-  return load().find((j) => j.id === id) || null;
+function requiredLegacyContext(record, options = {}) {
+  return {
+    canonicalUserId: nonEmpty(record.canonicalUserId) || nonEmpty(options.defaultCanonicalUserId),
+    channelId: nonEmpty(record.channelId) || nonEmpty(options.defaultChannelId),
+    adapter: nonEmpty(record.adapter) || nonEmpty(options.defaultAdapter),
+    adapterType: nonEmpty(record.adapterType) || nonEmpty(options.defaultAdapterType),
+  };
 }
 
-function listForChannel(adapter, channelId) {
-  return load().filter((j) =>
-    String(j.channelId) === String(channelId) &&
-    (j.adapter === adapter || j.adapterType === adapter),
-  );
+function normalizeProviderSettings(value) {
+  if (!isRecord(value)) return {};
+  const result = {};
+  for (const key of PROVIDER_SETTING_KEYS) {
+    if (Object.prototype.hasOwnProperty.call(value, key)) result[key] = clone(value[key]);
+  }
+  return result;
 }
 
-function listAll() { return load(); }
+function normalizeRunnableJob(record, options = {}) {
+  if (!isRecord(record)) throw new TypeError("job must be an object");
+  const provider = legacyProvider(record);
+  const project = nonEmpty(record.project);
+  const context = requiredLegacyContext(record, options);
+  const id = nonEmpty(record.id);
+  const kind = nonEmpty(record.kind);
+  const prompt = nonEmpty(record.prompt);
+  if (!id || !["wakeup", "cron"].includes(kind) || !prompt) return null;
+  if (!RUNNABLE_PROVIDERS.has(provider) || !project) return null;
+  if (!context.canonicalUserId || !context.channelId || (!context.adapter && !context.adapterType)) return null;
+  if (kind === "wakeup" && !Number.isFinite(Number(record.fireAt))) return null;
+  if (kind === "cron" && !nonEmpty(record.schedule)) return null;
 
-function listByCanonicalUser(canonicalUserId) {
-  return load().filter((j) => j.canonicalUserId === canonicalUserId);
+  const createdAt = Number.isFinite(Number(record.createdAt)) ? Number(record.createdAt) : nowMs(options);
+  const attemptCount = Math.max(0, Number.parseInt(record.attemptCount || 0, 10) || 0);
+  const maxAttempts = Math.max(1, Number.parseInt(record.maxAttempts || DEFAULT_MAX_ATTEMPTS, 10) || DEFAULT_MAX_ATTEMPTS);
+  const allowedStatuses = new Set(["pending", "running", "deferred", "failed", "succeeded", "dead-letter"]);
+  const status = allowedStatuses.has(record.status) ? record.status : "pending";
+  const disabled = record.disabled === true || status === "dead-letter";
+  const normalized = {
+    ...clone(record),
+    id,
+    kind,
+    adapter: context.adapter,
+    adapterType: context.adapterType,
+    channelId: context.channelId,
+    canonicalUserId: context.canonicalUserId,
+    userId: nonEmpty(record.userId),
+    provider,
+    providerSettings: normalizeProviderSettings(record.providerSettings),
+    project,
+    projectDir: nonEmpty(record.projectDir),
+    prompt,
+    label: nonEmpty(record.label) || prompt.slice(0, 60),
+    source: nonEmpty(record.source) || "agent",
+    sessionId: nonEmpty(record.sessionId),
+    previousSessionId: nonEmpty(record.previousSessionId),
+    sessionLineage: isRecord(record.sessionLineage) ? clone(record.sessionLineage) : {},
+    originRunId: nonEmpty(record.originRunId) || nonEmpty(record.sessionLineage?.originRunId),
+    occurrenceId: occurrenceId(record, options),
+    status,
+    disabled,
+    attemptCount,
+    maxAttempts,
+    nextAttemptAt: Number.isFinite(Number(record.nextAttemptAt)) ? Number(record.nextAttemptAt) : null,
+    createdAt,
+    lastFireAt: Number.isFinite(Number(record.lastFireAt)) ? Number(record.lastFireAt) : null,
+    lastFireOk: typeof record.lastFireOk === "boolean" ? record.lastFireOk : null,
+    lastError: isRecord(record.lastError) ? clone(record.lastError) : null,
+  };
+  if (kind === "wakeup") normalized.fireAt = Number(record.fireAt);
+  else normalized.schedule = nonEmpty(record.schedule);
+  delete normalized[LEGACY_SESSION_KEY];
+  delete normalized.archiveReason;
+  delete normalized.archivedAt;
+  return normalized;
 }
 
+function migrationReason(record, options = {}) {
+  const provider = legacyProvider(record);
+  if (provider === "cursor") return "Pinned to removed provider Cursor Agent";
+  if (!provider || !RUNNABLE_PROVIDERS.has(provider)) return "Legacy provider is missing or ambiguous";
+  if (!nonEmpty(record.project)) return "Legacy job has no unambiguous project";
+  const context = requiredLegacyContext(record, options);
+  if (!context.canonicalUserId) return "Legacy job has no unambiguous canonical user";
+  if (!context.channelId || (!context.adapter && !context.adapterType)) return "Legacy job has no unambiguous channel";
+  if (!nonEmpty(record.id) || !["wakeup", "cron"].includes(nonEmpty(record.kind)) || !nonEmpty(record.prompt)) {
+    return "Legacy job shape is incomplete";
+  }
+  if (record.kind === "wakeup" && !Number.isFinite(Number(record.fireAt))) return "Legacy wakeup has no valid fire time";
+  if (record.kind === "cron" && !nonEmpty(record.schedule)) return "Legacy cron has no valid schedule";
+  return "Legacy job could not be classified safely";
+}
+
+function normalizeArchived(record, options = {}) {
+  if (!isRecord(record)) return null;
+  if (record.status === "archived" && record.disabled === true && nonEmpty(record.archiveReason)) {
+    return clone(record);
+  }
+  return archiveLegacyJob(record, migrationReason(record, options), options);
+}
+
+function migrateJobsDocument(raw, options = {}) {
+  const source = isRecord(raw) && raw.schemaVersion === JOBS_SCHEMA_VERSION
+    ? raw
+    : { jobs: Array.isArray(raw) ? raw : [], archived: [] };
+  const jobs = [];
+  const archived = [];
+
+  for (const record of Array.isArray(source.jobs) ? source.jobs : []) {
+    const normalized = normalizeRunnableJob(record, options);
+    if (normalized) jobs.push(normalized);
+    else archived.push(archiveLegacyJob(record, migrationReason(record, options), options));
+  }
+  for (const record of Array.isArray(source.archived) ? source.archived : []) {
+    const normalized = normalizeArchived(record, options);
+    if (normalized) archived.push(normalized);
+  }
+  const occupied = new Map([...jobs, ...archived].map((record) => [record.id, record]));
+  for (const cronArchive of Array.isArray(options.legacyCronArchives) ? options.legacyCronArchives : []) {
+    let normalized = normalizeArchived(cronArchive, options);
+    if (!normalized) continue;
+    const alreadyArchived = [...occupied.values()].some((record) => (
+      (normalized.legacyCronHash && record.legacyCronHash === normalized.legacyCronHash)
+      || (normalized.legacyCronSourceHash && record.legacyCronSourceHash === normalized.legacyCronSourceHash)
+    ));
+    if (alreadyArchived) continue;
+    const collision = occupied.get(normalized.id);
+    if (collision) {
+      const evidenceHash = normalized.legacyCronHash || normalized.legacyCronSourceHash;
+      normalized = {
+        ...normalized,
+        legacyId: normalized.id,
+        id: `legacy-cron-${evidenceHash.slice(0, 32)}`,
+      };
+    }
+    occupied.set(normalized.id, normalized);
+    archived.push(normalized);
+  }
+  if (options.malformedSource) {
+    archived.push({
+      id: "legacy-jobs-source",
+      provider: null,
+      project: null,
+      sessionId: null,
+      status: "archived",
+      disabled: true,
+      archiveReason: "Malformed legacy jobs source retained byte-for-byte in the verified migration snapshot",
+      archivedAt: nowMs(options),
+      sourceSnapshot: clone(options.malformedSource),
+    });
+  }
+
+  const dedupe = (records) => {
+    const result = new Map();
+    for (const record of records) result.set(nonEmpty(record.id) || occurrenceId(record, options), record);
+    return [...result.values()];
+  };
+  const result = {
+    schemaVersion: JOBS_SCHEMA_VERSION,
+    jobs: dedupe(jobs),
+    archived: dedupe(archived),
+  };
+  const legacyCronMigration = isRecord(options.legacyCronMigration)
+    ? options.legacyCronMigration
+    : source.legacyCronMigration;
+  if (isRecord(legacyCronMigration)) result.legacyCronMigration = clone(legacyCronMigration);
+  return result;
+}
+
+function migrationSources(configDir, options = {}) {
+  return options.sources || defaultMigrationSources({
+    configDir,
+    stateFile: options.stateFile || path.join(configDir, path.basename(STATE_FILE)),
+    sessionsFile: options.sessionsFile || path.join(configDir, path.basename(SESSIONS_FILE)),
+    jobsFile: options.jobsFile || path.join(configDir, path.basename(JOBS_FILE)),
+    cronsFile: options.cronsFile || path.join(configDir, path.basename(CRONS_FILE)),
+  });
+}
+
+function createJobsStore(options = {}) {
+  const jobsFile = path.resolve(options.jobsFile || JOBS_FILE);
+  const configDir = path.resolve(options.configDir || path.dirname(jobsFile) || CONFIG_DIR);
+  const sources = migrationSources(configDir, { ...options, jobsFile });
+  const defaults = isRecord(options.defaults) ? options.defaults : {};
+  const migrationOptions = () => ({
+    defaultCanonicalUserId: defaults.canonicalUserId,
+    defaultChannelId: defaults.channelId,
+    defaultAdapter: defaults.adapter,
+    defaultAdapterType: defaults.adapterType,
+    now: options.now,
+    occurrenceIdFactory: options.occurrenceIdFactory,
+  });
+
+  function readLegacyCronSource() {
+    const source = sources.find((entry) => entry.kind === "crons" && entry.path === "crons.json");
+    if (!source || !fs.existsSync(source.sourcePath)) {
+      return {
+        legacyCronMigration: {
+          path: source?.path || "crons.json",
+          present: false,
+          size: null,
+          sha256: null,
+          status: "missing",
+          recordCount: 0,
+          recordHashes: [],
+        },
+        legacyCronArchives: [],
+      };
+    }
+    const bytes = fs.readFileSync(source.sourcePath);
+    const sourceHash = sha256(bytes);
+    let records;
+    try { records = JSON.parse(bytes.toString("utf8")); }
+    catch (_) { records = null; }
+    if (!Array.isArray(records)) {
+      const archiveId = `legacy-crons-source-${sourceHash.slice(0, 16)}`;
+      return {
+        legacyCronMigration: {
+          path: source.path,
+          present: true,
+          size: bytes.length,
+          sha256: sourceHash,
+          status: "malformed-archived",
+          recordCount: 0,
+          recordHashes: [],
+          archiveId,
+        },
+        legacyCronArchives: [{
+          id: archiveId,
+          provider: null,
+          project: null,
+          sessionId: null,
+          status: "archived",
+          disabled: true,
+          archiveReason: "Malformed legacy cron source retained byte-for-byte in the verified migration snapshot",
+          archivedAt: nowMs(migrationOptions()),
+          legacyCronSourceHash: sourceHash,
+        }],
+      };
+    }
+    const recordHashes = [];
+    const legacyCronArchives = records.map((record) => {
+      const serialized = JSON.stringify(record);
+      const recordHash = sha256(serialized);
+      recordHashes.push(recordHash);
+      const valid = isRecord(record) && nonEmpty(record.schedule) && nonEmpty(record.prompt);
+      const value = isRecord(record) ? clone(record) : { legacyRecord: clone(record) };
+      return archiveLegacyJob({
+        ...value,
+        id: nonEmpty(record?.id) || `legacy-cron-${recordHash.slice(0, 16)}`,
+        kind: "cron",
+        legacyCronHash: recordHash,
+        legacyCronSource: source.path,
+      }, valid ? LEGACY_CRON_ARCHIVE_REASON : "Legacy cron record is incomplete and is disabled", migrationOptions());
+    });
+    return {
+      legacyCronMigration: {
+        path: source.path,
+        present: true,
+        size: bytes.length,
+        sha256: sourceHash,
+        status: "archived",
+        recordCount: records.length,
+        recordHashes,
+      },
+      legacyCronArchives,
+    };
+  }
+
+  function readSource() {
+    if (!fs.existsSync(jobsFile)) return { raw: [], malformedSource: null, missing: true };
+    const bytes = fs.readFileSync(jobsFile);
+    try { return { raw: JSON.parse(bytes.toString("utf8")), malformedSource: null, missing: false }; }
+    catch (_) {
+      return {
+        raw: [],
+        malformedSource: { path: "jobs.json", size: bytes.length, sha256: sha256(bytes) },
+        missing: false,
+      };
+    }
+  }
+
+  function readDocument() {
+    const source = readSource();
+    return migrateJobsDocument(source.raw, {
+      ...migrationOptions(),
+      ...readLegacyCronSource(),
+      malformedSource: source.malformedSource,
+    });
+  }
+
+  function saveDocument(document, saveOptions = {}) {
+    const source = readSource();
+    const alreadyProviderAware = isRecord(source.raw)
+      && source.raw.schemaVersion === JOBS_SCHEMA_VERSION
+      && Array.isArray(source.raw.jobs)
+      && Array.isArray(source.raw.archived);
+    const snapshot = requireMigrationSnapshotForComponent("jobs", {
+      configDir,
+      sources,
+      allowSourceMismatch: alreadyProviderAware,
+    });
+    markMigrationComponentPrepared(snapshot.snapshotDir, "jobs", {
+      configDir,
+      sources,
+      requireSourceMatch: !alreadyProviderAware,
+    });
+    const normalized = migrateJobsDocument(document, { ...migrationOptions(), ...readLegacyCronSource() });
+    atomicWriteFileSync(jobsFile, `${JSON.stringify(normalized, null, 2)}\n`, { backup: true });
+    if (typeof saveOptions.faultInjector === "function") {
+      saveOptions.faultInjector("after-jobs-write", { jobsFile, document: normalized });
+    }
+    const persisted = JSON.parse(fs.readFileSync(jobsFile, "utf8"));
+    if (persisted?.schemaVersion !== JOBS_SCHEMA_VERSION || !Array.isArray(persisted.jobs) || !Array.isArray(persisted.archived)) {
+      const error = new Error("provider-aware jobs verification failed after write");
+      error.code = "JOBS_MIGRATION_WRITE_INVALID";
+      throw error;
+    }
+    markMigrationComponentActivated(snapshot.snapshotDir, "jobs", { configDir, sources });
+    return normalized;
+  }
+
+  function ensureMigrated(saveOptions = {}) {
+    const source = readSource();
+    const document = migrateJobsDocument(source.raw, {
+      ...migrationOptions(),
+      ...readLegacyCronSource(),
+      malformedSource: source.malformedSource,
+    });
+    const alreadyProviderAware = isRecord(source.raw)
+      && source.raw.schemaVersion === JOBS_SCHEMA_VERSION
+      && Array.isArray(source.raw.jobs)
+      && Array.isArray(source.raw.archived);
+    if (alreadyProviderAware) {
+      // A crash can leave the new file durable while the journal component is
+      // still pending. Re-saving completes the prepare/verify/activate cycle.
+      return saveDocument(document, saveOptions);
+    }
+    return saveDocument(document, saveOptions);
+  }
+
+  function mutate(mutator) {
+    const document = ensureMigrated();
+    const result = mutator(document);
+    saveDocument(document);
+    return clone(result);
+  }
+
+  function listAll() {
+    return readDocument().jobs.map(clone);
+  }
+
+  function listArchived() {
+    return readDocument().archived.map(clone);
+  }
+
+  function get(id) {
+    return listAll().find((job) => job.id === id) || null;
+  }
+
+  function add(job) {
+    const candidate = normalizeRunnableJob({
+      id: nonEmpty(job?.id) || nextId(job?.kind || "job"),
+      createdAt: nowMs(options),
+      lastFireAt: null,
+      lastFireOk: null,
+      status: "pending",
+      disabled: false,
+      attemptCount: 0,
+      maxAttempts: DEFAULT_MAX_ATTEMPTS,
+      ...clone(job),
+    }, migrationOptions());
+    if (!candidate) {
+      const error = new TypeError("scheduled jobs require kind, provider, project, user, channel, prompt, and timing metadata");
+      error.code = "INVALID_SCHEDULED_JOB";
+      throw error;
+    }
+    return mutate((document) => {
+      if (document.jobs.some((entry) => entry.id === candidate.id)
+          || document.archived.some((entry) => entry.id === candidate.id)) {
+        const error = new Error(`scheduled job already exists: ${candidate.id}`);
+        error.code = "DUPLICATE_SCHEDULED_JOB";
+        throw error;
+      }
+      document.jobs.push(candidate);
+      return candidate;
+    });
+  }
+
+  function remove(id) {
+    return mutate((document) => {
+      const index = document.jobs.findIndex((job) => job.id === id);
+      if (index < 0) return null;
+      return document.jobs.splice(index, 1)[0];
+    });
+  }
+
+  function update(id, patch) {
+    return mutate((document) => {
+      const index = document.jobs.findIndex((job) => job.id === id);
+      if (index < 0) return null;
+      const next = normalizeRunnableJob({ ...document.jobs[index], ...clone(patch) }, migrationOptions());
+      if (!next) throw Object.assign(new Error(`invalid scheduled job update: ${id}`), { code: "INVALID_SCHEDULED_JOB" });
+      document.jobs[index] = next;
+      return next;
+    });
+  }
+
+  function archive(job, reason = null) {
+    return mutate((document) => {
+      const index = document.jobs.findIndex((entry) => entry.id === job.id);
+      const source = index >= 0 ? document.jobs.splice(index, 1)[0] : job;
+      const archived = archiveLegacyJob(source, reason || "Archived by scheduler", migrationOptions());
+      document.archived.push(archived);
+      return archived;
+    });
+  }
+
+  function bindOriginRunSession(originRunId, provider, project, sessionId) {
+    const run = nonEmpty(originRunId);
+    const providerId = nonEmpty(provider);
+    const projectName = nonEmpty(project);
+    const nativeSessionId = nonEmpty(sessionId);
+    if (!run || !providerId || !projectName || !nativeSessionId) return 0;
+    const pending = readDocument().jobs.some((job) => (
+      job.originRunId === run && job.provider === providerId && job.project === projectName && !job.sessionId
+    ));
+    if (!pending) return 0;
+    return mutate((document) => {
+      let count = 0;
+      for (const job of document.jobs) {
+        if (job.originRunId !== run || job.provider !== providerId || job.project !== projectName || job.sessionId) continue;
+        job.sessionId = nativeSessionId;
+        job.sessionLineage = {
+          ...(isRecord(job.sessionLineage) ? job.sessionLineage : {}),
+          originRunId: run,
+          originSessionId: nativeSessionId,
+          boundAt: nowMs(options),
+        };
+        count += 1;
+      }
+      return count;
+    });
+  }
+
+  function markArchivedAnnounced(ids) {
+    const wanted = new Set((Array.isArray(ids) ? ids : [ids]).filter(Boolean));
+    if (wanted.size === 0) return 0;
+    return mutate((document) => {
+      let count = 0;
+      for (const record of document.archived) {
+        if (!wanted.has(record.id) || record.announcedAt) continue;
+        record.announcedAt = nowMs(options);
+        count += 1;
+      }
+      return count;
+    });
+  }
+
+  function listForChannel(adapter, channelId) {
+    return listAll().filter((job) => (
+      String(job.channelId) === String(channelId)
+      && (job.adapter === adapter || job.adapterType === adapter)
+    ));
+  }
+
+  function listByCanonicalUser(canonicalUserId) {
+    return listAll().filter((job) => job.canonicalUserId === canonicalUserId);
+  }
+
+  return {
+    ensureMigrated,
+    readDocument,
+    saveDocument,
+    load: listAll,
+    save(list) {
+      const current = readDocument();
+      current.jobs = Array.isArray(list) ? list : [];
+      return saveDocument(current).jobs;
+    },
+    add,
+    remove,
+    update,
+    get,
+    archive,
+    bindOriginRunSession,
+    listAll,
+    listArchived,
+    markArchivedAnnounced,
+    listForChannel,
+    listByCanonicalUser,
+  };
+}
+
+function nextId(kind) {
+  return `${kind}_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+}
+
+const defaultStore = createJobsStore();
+
 module.exports = {
-  load, save, add, remove, update, get,
-  listAll, listForChannel, listByCanonicalUser,
+  JOBS_SCHEMA_VERSION,
+  DEFAULT_MAX_ATTEMPTS,
+  RUNNABLE_PROVIDERS,
+  migrateJobsDocument,
+  createJobsStore,
   nextId,
+  ensureMigrated: defaultStore.ensureMigrated,
+  load: defaultStore.load,
+  save: defaultStore.save,
+  add: defaultStore.add,
+  remove: defaultStore.remove,
+  update: defaultStore.update,
+  get: defaultStore.get,
+  archive: defaultStore.archive,
+  bindOriginRunSession: defaultStore.bindOriginRunSession,
+  listAll: defaultStore.listAll,
+  listArchived: defaultStore.listArchived,
+  markArchivedAnnounced: defaultStore.markArchivedAnnounced,
+  listForChannel: defaultStore.listForChannel,
+  listByCanonicalUser: defaultStore.listByCanonicalUser,
 };