atris 3.70.0 → 3.71.1

package/lib/campaign-schema.js

@@ -0,0 +1,196 @@
+// Campaign schema: the struct, event types, and actions shared by every
+// surface (CLI, backend, desktop, web, terrace). Pure, no I/O.
+//
+// The fold rules that turn events into state live in
+// test/fixtures/campaign/README.md, which is the cross-surface contract.
+// Spec: atris/features/campaign/idea.md.
+
+'use strict';
+
+// idea.md "Events" list, plus two the spec's actions need but never named:
+// add_budget writes budget_added, veto writes mission_vetoed, and judge_set
+// changes the judge (found running real campaigns: a judge is not forever).
+const EVENT_TYPES = Object.freeze([
+  'campaign_started', 'seat_filled', 'bet_set', 'attached',
+  'mission_proposed', 'mission_claimed', 'mission_started', 'step', 'kept', 'reverted', 'mission_ended',
+  'mission_vetoed',
+  'judge_ran', 'ask_opened', 'ask_answered',
+  'budget_reserved', 'budget_released', 'budget_added',
+  'paused', 'resumed', 'stopped', 'home_moved', 'done',
+  'judge_set',
+]);
+
+const ACTIONS = Object.freeze([
+  'start', 'pause', 'resume', 'answer_ask', 'change_bet', 'add_budget', 'fill_seat', 'veto', 'stop',
+]);
+
+const CONFIDENCE = Object.freeze(['open', 'leaning', 'stronger', 'answered']);
+
+const STATES = Object.freeze([
+  'running', 'needs_you', 'resting', 'queued', 'done', 'out_of_budget', 'paused',
+]);
+
+const STOP_REASONS = Object.freeze(['judge_passed', 'stopped', 'done_by_human', 'budget_spent']);
+
+const MISSION_OUTCOMES = Object.freeze(['kept', 'reverted', 'failed']);
+
+// What a person or agent writes. Everything else is folded from events.
+const CAMPAIGN_FIELDS = Object.freeze({
+  title: { required: true, type: 'string' },
+  judge: { required: true, type: 'string' },
+  budget: { required: true, type: 'number' },
+  owner: { required: false, type: 'string' },
+  seats: { required: false, type: 'array' },
+  bet: { required: false, type: 'string' },
+  standing: { required: false, type: 'boolean' },
+  parent: { required: false, type: 'string' },
+});
+
+const CAMPAIGN_ID = /^cmp-[a-z0-9][a-z0-9-]{0,63}$/;
+const EVENT_ID = /^[\x21-\x7e]{1,128}$/;
+const ORIGIN = /^[A-Za-z0-9._:-]{1,64}$/;
+// RFC 3339 with a zone: no surface may read a timestamp in its own timezone.
+const TIMESTAMP = /^(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2}:\d{2})(?:\.(\d{1,9}))?(Z|[+-]\d{2}:\d{2})$/;
+
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function nonEmpty(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function positiveNumber(value) {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0;
+}
+
+function nonNegativeNumber(value) {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+}
+
+// A seat is "member" (role comes from the member's own job) or { member, role }.
+function seatErrors(seats) {
+  if (!Array.isArray(seats)) return ['seats_not_list'];
+  const errors = [];
+  for (const seat of seats) {
+    if (nonEmpty(seat)) continue;
+    if (isObject(seat) && nonEmpty(seat.member) && (seat.role === undefined || seat.role === null || nonEmpty(seat.role))) continue;
+    errors.push('bad_seat');
+  }
+  return errors;
+}
+
+// record: the hand-written struct. options.lookup(id) returns another
+// campaign record (or null) so the one-level nesting rule can be checked.
+function validateCampaign(record, options = {}) {
+  const errors = [];
+  if (!isObject(record)) return { ok: false, errors: ['not_object'] };
+  for (const key of Object.keys(record)) {
+    if (!Object.prototype.hasOwnProperty.call(CAMPAIGN_FIELDS, key)) errors.push(`unknown_field:${key}`);
+  }
+  if (!nonEmpty(record.title)) errors.push('missing_title');
+  if (!nonEmpty(record.judge)) errors.push('missing_judge');
+  if (!positiveNumber(record.budget)) errors.push('bad_budget');
+  if (record.owner !== undefined && !nonEmpty(record.owner)) errors.push('bad_owner');
+  if (record.bet !== undefined && !nonEmpty(record.bet)) errors.push('bad_bet');
+  if (record.standing !== undefined && typeof record.standing !== 'boolean') errors.push('bad_standing');
+  if (record.seats !== undefined) errors.push(...seatErrors(record.seats));
+  if (record.parent !== undefined) {
+    if (!nonEmpty(record.parent)) {
+      errors.push('bad_parent');
+    } else if (typeof options.lookup === 'function') {
+      const parent = options.lookup(record.parent);
+      if (!parent) errors.push('unknown_parent');
+      else if (parent.parent) errors.push('nested_parent');
+    }
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+// Fields each event type must carry in its data.
+const EVENT_DATA_RULES = Object.freeze({
+  campaign_started: (d) => [
+    nonEmpty(d.title) ? null : 'missing_title',
+    nonEmpty(d.judge) ? null : 'missing_judge',
+    positiveNumber(d.budget) ? null : 'bad_budget',
+    d.seats === undefined ? null : (seatErrors(d.seats)[0] || null),
+    d.standing === undefined || typeof d.standing === 'boolean' ? null : 'bad_standing',
+  ],
+  seat_filled: (d) => [nonEmpty(d.member) ? null : 'missing_member', nonEmpty(d.role) ? null : 'missing_role'],
+  bet_set: (d) => [nonEmpty(d.bet) ? null : 'missing_bet'],
+  judge_set: (d) => [nonEmpty(d.judge) ? null : 'missing_judge'],
+  attached: (d) => [nonEmpty(d.parent_id) ? null : 'missing_parent_id'],
+  mission_proposed: (d) => [nonEmpty(d.mission_id) ? null : 'missing_mission_id'],
+  mission_claimed: (d) => [
+    nonEmpty(d.mission_id) ? null : 'missing_mission_id',
+    nonEmpty(d.claim_key) ? null : 'missing_claim_key',
+  ],
+  mission_started: (d) => [
+    nonEmpty(d.mission_id) ? null : 'missing_mission_id',
+    nonEmpty(d.member) ? null : 'missing_member',
+  ],
+  step: (d) => [nonEmpty(d.mission_id) ? null : 'missing_mission_id'],
+  kept: (d) => [nonEmpty(d.mission_id) ? null : 'missing_mission_id'],
+  reverted: (d) => [nonEmpty(d.mission_id) ? null : 'missing_mission_id'],
+  // Every mission reports its cost (idea.md review rule 1).
+  mission_ended: (d) => [
+    nonEmpty(d.mission_id) ? null : 'missing_mission_id',
+    MISSION_OUTCOMES.includes(d.outcome) ? null : 'bad_outcome',
+    nonNegativeNumber(d.cost_usd) ? null : 'missing_cost',
+  ],
+  mission_vetoed: (d) => [nonEmpty(d.mission_id) ? null : 'missing_mission_id'],
+  judge_ran: (d) => [
+    typeof d.passed === 'boolean' ? null : 'missing_passed',
+    d.reading === undefined || (typeof d.reading === 'number' && Number.isFinite(d.reading)) ? null : 'bad_reading',
+    d.confidence === undefined || ['open', 'leaning', 'stronger'].includes(d.confidence) ? null : 'bad_confidence',
+  ],
+  ask_opened: (d) => [nonEmpty(d.ask_id) ? null : 'missing_ask_id', nonEmpty(d.question) ? null : 'missing_question'],
+  ask_answered: (d) => [nonEmpty(d.ask_id) ? null : 'missing_ask_id', nonEmpty(d.answer) ? null : 'missing_answer'],
+  budget_reserved: (d) => [
+    nonEmpty(d.mission_id) ? null : 'missing_mission_id',
+    positiveNumber(d.amount_usd) ? null : 'bad_amount',
+  ],
+  budget_released: (d) => [nonEmpty(d.mission_id) ? null : 'missing_mission_id'],
+  budget_added: (d) => [positiveNumber(d.amount_usd) ? null : 'bad_amount'],
+  paused: () => [],
+  resumed: () => [],
+  stopped: () => [],
+  home_moved: (d) => [nonEmpty(d.to) ? null : 'missing_to'],
+  done: () => [],
+});
+
+function validateEvent(event) {
+  if (!isObject(event)) return { ok: false, errors: ['not_object'] };
+  const errors = [];
+  if (typeof event.id !== 'string' || !EVENT_ID.test(event.id)) errors.push('bad_id');
+  if (typeof event.campaign_id !== 'string' || !CAMPAIGN_ID.test(event.campaign_id)) errors.push('bad_campaign_id');
+  if (!EVENT_TYPES.includes(event.type)) errors.push('unknown_type');
+  if (typeof event.at !== 'string' || !TIMESTAMP.test(event.at) || Number.isNaN(Date.parse(event.at))) errors.push('bad_at');
+  if (typeof event.origin !== 'string' || !ORIGIN.test(event.origin)) errors.push('bad_origin');
+  if (!Number.isInteger(event.seq) || event.seq < 1) errors.push('bad_seq');
+  if (!nonEmpty(event.actor)) errors.push('missing_actor');
+  if (!isObject(event.data)) errors.push('bad_data');
+  if (errors.length === 0) {
+    for (const code of EVENT_DATA_RULES[event.type](event.data)) if (code) errors.push(code);
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+function isHumanActor(actor) {
+  return typeof actor === 'string' && actor.startsWith('human:');
+}
+
+module.exports = {
+  ACTIONS,
+  CAMPAIGN_FIELDS,
+  CAMPAIGN_ID,
+  CONFIDENCE,
+  EVENT_TYPES,
+  TIMESTAMP,
+  MISSION_OUTCOMES,
+  STATES,
+  STOP_REASONS,
+  isHumanActor,
+  validateCampaign,
+  validateEvent,
+};

package/lib/campaign-store.js

@@ -0,0 +1,380 @@
+// Campaign store: append-only events behind one small interface, with a
+// SQLite adapter (one file per workspace) and an in-memory adapter for tests.
+//
+// Built so Campaign does not inherit the mission ledger's problems
+// (atris/features/campaign/build.md Phase -1): every append is one
+// transaction, events carry a unique id plus a per-origin sequence, writers
+// can demand an expected version, and a corrupt row fails closed.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+// task-db installs the narrow node:sqlite warning filter and owns the shared
+// busy retry; load it before node:sqlite so the filter is in place.
+const { withBusyRetry } = require('./task-db');
+const { DatabaseSync } = require('node:sqlite');
+const { mainCheckoutRoot } = require('./engine-registry');
+const { validateEvent } = require('./campaign-schema');
+const { fold } = require('./campaign-core');
+
+// Any event naming a mission ties that mission to its campaign.
+function missionIdOf(event) {
+  return event.data && typeof event.data.mission_id === 'string' && event.data.mission_id ? event.data.mission_id : null;
+}
+
+function storeError(code, message) {
+  const error = new Error(message || code);
+  error.code = code;
+  return error;
+}
+
+// The checkout holding root, so a call from a subfolder finds the same store.
+function checkoutRoot(root) {
+  let dir = path.resolve(root);
+  for (;;) {
+    if (fs.existsSync(path.join(dir, '.git'))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return path.resolve(root);
+    dir = parent;
+  }
+}
+
+function campaignDbPath(root = process.cwd()) {
+  if (process.env.ATRIS_CAMPAIGN_DB) return process.env.ATRIS_CAMPAIGN_DB;
+  const checkout = checkoutRoot(root);
+  const home = mainCheckoutRoot(checkout) || checkout;
+  return path.join(home, '.atris', 'state', 'atris.db');
+}
+
+// Files a campaign owns (like a copied judge script) live beside the store.
+function campaignFolder(campaignId, root = process.cwd()) {
+  return path.join(path.dirname(campaignDbPath(root)), 'campaigns', campaignId);
+}
+
+function newCampaignId(title = '') {
+  const slug = String(title).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 24).replace(/-+$/, '');
+  const suffix = crypto.randomBytes(2).toString('hex');
+  return slug ? `cmp-${slug}-${suffix}` : `cmp-${suffix}`;
+}
+
+function newOrigin() {
+  return `c-${crypto.randomBytes(4).toString('hex')}`;
+}
+
+// Fill the fields the store owns, then validate the whole event.
+function completeEvent(input, origin, seq, now) {
+  const event = {
+    id: input.id || `evt-${crypto.randomUUID()}`,
+    campaign_id: input.campaign_id,
+    type: input.type,
+    at: input.at || now(),
+    origin,
+    seq,
+    actor: input.actor,
+    data: input.data || {},
+  };
+  const check = validateEvent(event);
+  if (!check.ok) throw storeError('invalid_event', `invalid ${input.type || 'event'}: ${check.errors.join(', ')}`);
+  return event;
+}
+
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS meta (
+  key TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS campaigns (
+  id TEXT PRIMARY KEY,
+  created_at TEXT NOT NULL,
+  origin TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS events (
+  pos INTEGER PRIMARY KEY AUTOINCREMENT,
+  id TEXT NOT NULL UNIQUE,
+  campaign_id TEXT NOT NULL,
+  origin TEXT NOT NULL,
+  seq INTEGER NOT NULL,
+  type TEXT NOT NULL,
+  at TEXT NOT NULL,
+  actor TEXT NOT NULL,
+  data TEXT NOT NULL,
+  UNIQUE (origin, seq)
+);
+CREATE INDEX IF NOT EXISTS events_by_campaign ON events (campaign_id, pos);
+CREATE TABLE IF NOT EXISTS missions (
+  mission_id TEXT PRIMARY KEY,
+  campaign_id TEXT NOT NULL
+);
+`;
+
+function createSqliteStore(dbPath, options = {}) {
+  const now = options.now || (() => new Date().toISOString());
+  fs.mkdirSync(path.dirname(dbPath), { recursive: true });
+  let readOnly = false;
+  let db;
+  try {
+    fs.accessSync(fs.existsSync(dbPath) ? dbPath : path.dirname(dbPath), fs.constants.W_OK);
+    db = new DatabaseSync(dbPath);
+    withBusyRetry(() => db.exec('PRAGMA journal_mode = WAL'));
+    db.exec('PRAGMA busy_timeout = 30000');
+    withBusyRetry(() => db.exec(SCHEMA));
+    withBusyRetry(() => db.exec('PRAGMA user_version = 1'));
+  } catch (error) {
+    // A store someone can only read still shows its campaigns; writes say why they cannot.
+    if (!fs.existsSync(dbPath)) throw error;
+    if (db) try { db.close(); } catch {}
+    db = new DatabaseSync(dbPath, { readOnly: true });
+    readOnly = true;
+  }
+
+  const tx = (fn) => {
+    if (readOnly) throw storeError('read_only', `the campaign store at ${dbPath} is read-only`);
+    withBusyRetry(() => db.exec('BEGIN IMMEDIATE'));
+    try {
+      const result = fn();
+      db.exec('COMMIT');
+      return result;
+    } catch (error) {
+      try { db.exec('ROLLBACK'); } catch {}
+      throw error;
+    }
+  };
+
+  const origin = readOnly ? ((db.prepare("SELECT value FROM meta WHERE key = 'origin'").get() || {}).value || 'read-only') : tx(() => {
+    const row = db.prepare("SELECT value FROM meta WHERE key = 'origin'").get();
+    if (row) return row.value;
+    const value = options.origin || newOrigin();
+    db.prepare("INSERT INTO meta (key, value) VALUES ('origin', ?)").run(value);
+    return value;
+  });
+
+  const linkMission = (event) => {
+    const missionId = missionIdOf(event);
+    if (!missionId) return;
+    const row = db.prepare('SELECT campaign_id FROM missions WHERE mission_id = ?').get(missionId);
+    if (row && row.campaign_id !== event.campaign_id) {
+      throw storeError('mission_in_other_campaign', `mission ${missionId} already belongs to ${row.campaign_id}`);
+    }
+    if (!row) db.prepare('INSERT INTO missions (mission_id, campaign_id) VALUES (?, ?)').run(missionId, event.campaign_id);
+  };
+
+  const insert = (event) => {
+    db.prepare('INSERT INTO events (id, campaign_id, origin, seq, type, at, actor, data) VALUES (?, ?, ?, ?, ?, ?, ?, ?)')
+      .run(event.id, event.campaign_id, event.origin, event.seq, event.type, event.at, event.actor, JSON.stringify(event.data));
+  };
+
+  const count = (campaignId) => db.prepare('SELECT COUNT(*) AS n FROM events WHERE campaign_id = ?').get(campaignId).n;
+
+  const readEvents = (campaignId) => db.prepare('SELECT * FROM events WHERE campaign_id = ? ORDER BY pos').all(campaignId).map((row) => {
+    let data;
+    try {
+      data = JSON.parse(row.data);
+    } catch {
+      throw storeError('corrupt_event', `event ${row.id} in ${campaignId} has unreadable data`);
+    }
+    return {
+      id: row.id, campaign_id: row.campaign_id, type: row.type, at: row.at,
+      origin: row.origin, seq: row.seq, actor: row.actor, data,
+    };
+  });
+
+  return {
+    kind: 'sqlite',
+    path: dbPath,
+    origin,
+    readOnly,
+
+    // Write a new event from this computer. options.expectedVersion is the
+    // event count the writer last read; a mismatch refuses the write.
+    append(input, appendOptions = {}) {
+      return tx(() => {
+        const campaignId = input.campaign_id;
+        if (appendOptions.expectedVersion !== undefined && count(campaignId) !== appendOptions.expectedVersion) {
+          throw storeError('version_conflict', `campaign ${campaignId} changed since version ${appendOptions.expectedVersion}`);
+        }
+        const exists = db.prepare('SELECT 1 FROM campaigns WHERE id = ?').get(campaignId);
+        if (input.type === 'campaign_started' && exists) throw storeError('campaign_exists', `campaign ${campaignId} already started`);
+        if (input.type !== 'campaign_started' && !exists) throw storeError('unknown_campaign', `no campaign ${campaignId}`);
+        // A check that must see the campaign as it is at the moment of the
+        // write, such as a budget reservation, runs inside this transaction.
+        if (appendOptions.check) appendOptions.check(fold(readEvents(campaignId)));
+        const last = db.prepare('SELECT MAX(seq) AS seq FROM events WHERE origin = ?').get(origin).seq || 0;
+        const event = completeEvent(input, origin, last + 1, now);
+        if (input.type === 'campaign_started') {
+          db.prepare('INSERT INTO campaigns (id, created_at, origin) VALUES (?, ?, ?)').run(campaignId, event.at, origin);
+        }
+        linkMission(event);
+        insert(event);
+        return event;
+      });
+    },
+
+    // Take an event written elsewhere (sync). Returns false for one already
+    // held; a different event claiming the same origin and seq is refused.
+    ingest(event) {
+      const check = validateEvent(event);
+      if (!check.ok) throw storeError('invalid_event', `invalid ${event && event.type}: ${check.errors.join(', ')}`);
+      return tx(() => {
+        if (db.prepare('SELECT 1 FROM events WHERE id = ?').get(event.id)) return false;
+        const clash = db.prepare('SELECT id FROM events WHERE origin = ? AND seq = ?').get(event.origin, event.seq);
+        if (clash) throw storeError('seq_conflict', `origin ${event.origin} seq ${event.seq} is already ${clash.id}`);
+        if (event.type === 'campaign_started') {
+          db.prepare('INSERT OR IGNORE INTO campaigns (id, created_at, origin) VALUES (?, ?, ?)').run(event.campaign_id, event.at, event.origin);
+        }
+        linkMission(event);
+        insert(event);
+        return true;
+      });
+    },
+
+    read: readEvents,
+
+    version: count,
+
+    campaignIds() {
+      return db.prepare('SELECT id FROM campaigns ORDER BY created_at, id').all().map((row) => row.id);
+    },
+
+    campaignForMission(missionId) {
+      const row = db.prepare('SELECT campaign_id FROM missions WHERE mission_id = ?').get(missionId);
+      return row ? row.campaign_id : null;
+    },
+
+    // Small notes the store keeps beside the events, such as a campaign's
+    // cloud link and the last cloud seq pulled (lib/campaign-sync.js).
+    getMeta(key) {
+      const row = db.prepare('SELECT value FROM meta WHERE key = ?').get(key);
+      return row ? row.value : null;
+    },
+
+    setMeta(key, value) {
+      tx(() => db.prepare('INSERT INTO meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value').run(key, String(value)));
+    },
+
+    close() {
+      db.close();
+    },
+  };
+}
+
+function createMemoryStore(options = {}) {
+  const now = options.now || (() => new Date().toISOString());
+  const origin = options.origin || newOrigin();
+  const events = [];
+  const campaigns = new Map();
+  const missions = new Map();
+  const seqByOrigin = new Map();
+  const meta = new Map();
+
+  const clone = (value) => JSON.parse(JSON.stringify(value));
+  const count = (campaignId) => events.filter((e) => e.campaign_id === campaignId).length;
+  const checkMission = (event) => {
+    const missionId = missionIdOf(event);
+    if (!missionId) return;
+    const owner = missions.get(missionId);
+    if (owner && owner !== event.campaign_id) {
+      throw storeError('mission_in_other_campaign', `mission ${missionId} already belongs to ${owner}`);
+    }
+  };
+  const commit = (event) => {
+    const missionId = missionIdOf(event);
+    if (missionId && !missions.has(missionId)) missions.set(missionId, event.campaign_id);
+    seqByOrigin.set(event.origin, Math.max(seqByOrigin.get(event.origin) || 0, event.seq));
+    events.push(clone(event));
+  };
+
+  return {
+    kind: 'memory',
+    path: null,
+    origin,
+    append(input, appendOptions = {}) {
+      const campaignId = input.campaign_id;
+      if (appendOptions.expectedVersion !== undefined && count(campaignId) !== appendOptions.expectedVersion) {
+        throw storeError('version_conflict', `campaign ${campaignId} changed since version ${appendOptions.expectedVersion}`);
+      }
+      if (input.type === 'campaign_started' && campaigns.has(campaignId)) throw storeError('campaign_exists', `campaign ${campaignId} already started`);
+      if (input.type !== 'campaign_started' && !campaigns.has(campaignId)) throw storeError('unknown_campaign', `no campaign ${campaignId}`);
+      if (appendOptions.check) appendOptions.check(fold(events.filter((e) => e.campaign_id === campaignId)));
+      const event = completeEvent(input, origin, (seqByOrigin.get(origin) || 0) + 1, now);
+      checkMission(event);
+      if (input.type === 'campaign_started') campaigns.set(campaignId, event.at);
+      commit(event);
+      return clone(event);
+    },
+    ingest(event) {
+      const check = validateEvent(event);
+      if (!check.ok) throw storeError('invalid_event', `invalid ${event && event.type}: ${check.errors.join(', ')}`);
+      if (events.some((e) => e.id === event.id)) return false;
+      const clash = events.find((e) => e.origin === event.origin && e.seq === event.seq);
+      if (clash) throw storeError('seq_conflict', `origin ${event.origin} seq ${event.seq} is already ${clash.id}`);
+      checkMission(event);
+      if (event.type === 'campaign_started' && !campaigns.has(event.campaign_id)) campaigns.set(event.campaign_id, event.at);
+      commit(event);
+      return true;
+    },
+    read(campaignId) {
+      return events.filter((e) => e.campaign_id === campaignId).map(clone);
+    },
+    version: count,
+    campaignIds() {
+      return [...campaigns.entries()].sort((a, b) => (a[1] === b[1] ? (a[0] < b[0] ? -1 : 1) : (a[1] < b[1] ? -1 : 1))).map(([id]) => id);
+    },
+    campaignForMission(missionId) {
+      return missions.get(missionId) || null;
+    },
+    getMeta(key) {
+      return meta.has(key) ? meta.get(key) : null;
+    },
+    setMeta(key, value) {
+      meta.set(key, String(value));
+    },
+    close() {},
+  };
+}
+
+const openStores = new Map();
+
+function openCampaignStore(root = process.cwd()) {
+  const dbPath = campaignDbPath(root);
+  if (!openStores.has(dbPath)) openStores.set(dbPath, createSqliteStore(dbPath));
+  return openStores.get(dbPath);
+}
+
+function closeCampaignStores() {
+  for (const store of openStores.values()) store.close();
+  openStores.clear();
+}
+
+function getCampaign(storeOrRoot, campaignId) {
+  const store = typeof storeOrRoot === 'string' ? openCampaignStore(storeOrRoot) : storeOrRoot;
+  const events = store.read(campaignId);
+  if (events.length === 0) return null;
+  return fold(events);
+}
+
+// One unreadable campaign never hides the others: it comes back as { id, error }.
+function listCampaigns(storeOrRoot) {
+  const store = typeof storeOrRoot === 'string' ? openCampaignStore(storeOrRoot) : storeOrRoot;
+  return store.campaignIds().map((id) => {
+    try {
+      const view = fold(store.read(id));
+      return view.error ? { id, error: view.error } : view;
+    } catch (error) {
+      return { id, error: error.code || error.message };
+    }
+  });
+}
+
+module.exports = {
+  campaignDbPath,
+  campaignFolder,
+  closeCampaignStores,
+  createMemoryStore,
+  createSqliteStore,
+  getCampaign,
+  listCampaigns,
+  newCampaignId,
+  openCampaignStore,
+};