faberun 0.3.0

package/src/campaign/index.mjs

@@ -0,0 +1,300 @@
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+} from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { join, resolve } from "node:path";
+import { writeJsonAtomic } from "../run/store.mjs";
+import { requireId, requirePacketHash, requireString, requireTimestamp } from "../contract/assert.mjs";
+import { promoteRun } from "../repo/integrate.mjs";
+import { CAMPAIGN_FILE, GOAL_TEXT_BYTES, PROJECTION_FILE, campaignDir, campaignsDir } from "./layout.mjs";
+import { readCampaign } from "./record.mjs";
+import { appendJournal, normalizeText, readJournalForDedupe } from "./journal.mjs";
+import { readProjectionState } from "./projection.mjs";
+import { handoffFromState, materializeHandoff } from "./handoff.mjs";
+
+/** @typedef {Record<string, unknown>} JsonObject */
+/** @typedef {{path: string, digest: string}} CampaignContract */
+/** @typedef {{runId: string, contractPath?: string, branch: string, sha: string, previousSha: string|null, at: string}} PromotionRecord */
+/** @typedef {{code: string, message: string, at: string, contractPath?: string, contractId?: string, runId?: string, node?: string|null, status?: string|null, resume?: string}} CampaignAttention */
+/** @typedef {{id: string, goal: string, status: "active"|"closed", linkedRunIds: string[], contracts: CampaignContract[], landBranch: string, promotions: PromotionRecord[], attention?: CampaignAttention, createdAt: string, updatedAt: string, closedAt?: string}} Campaign */
+/** @typedef {{type: string, eventId: string, at: string, sessionId?: string, text?: string, tool?: string, transcript?: string|null, transcriptUnavailable?: boolean, format?: string|null, cursor?: string|null, decisionId?: string, supersedes?: string, runId?: string, questionId?: string, campaignId?: string, nodeId?: string|null, phase?: string, checkpointsDone?: number, checkpointsTotal?: number, runtime?: string|null, state?: string, lastProgressAt?: string, attention?: string|null}} JournalEntry */
+/** @typedef {{updatedAt: string|null, decisions: Record<string, JournalEntry>, questions: Record<string, JournalEntry>, constraints: JournalEntry[], intents: JournalEntry[], outcomes: JournalEntry[], sessions: JournalEntry[], next: JournalEntry|null, evicted: Record<string, number>}} Projection */
+/** @typedef {{cursor: number, byte: number, size: number, projection: Projection}} ProjectionRecord */
+/** @typedef {{id: string, exists: boolean, total: number, summary: string, attention: {id: string, status: string, note: string}[], unreadable: string|null}} RunSummary */
+/** @typedef {{campaign: Campaign, updatedAt: string, linkedRuns: RunSummary[], activeDecisions: JournalEntry[], constraints: JournalEntry[], intents: JournalEntry[], outcomes: JournalEntry[], nextEntry: JournalEntry|null, questions: JournalEntry[], sessions: JournalEntry[], totals: {decisions: number, constraints: number, intents: number, outcomes: number, questions: number, sessions: number}, evicted: Record<string, number>}} Handoff */
+
+/**
+ * @param {string} runsDir
+ * @param {{campaignId: string, goal: unknown, at?: string, contracts?: CampaignContract[], landBranch?: string}} options
+ * @returns {{path: string, campaign: Campaign}}
+ */
+export function initializeCampaign(runsDir, { campaignId, goal, at = new Date().toISOString(), contracts = [], landBranch = undefined }) {
+  requireId(campaignId, "campaignId");
+  requireTimestamp(at, "at");
+  const path = campaignDir(runsDir, campaignId);
+  if (existsSync(path)) throw new Error(`campaign already exists: ${path}`);
+  mkdirSync(path, { recursive: true });
+  const validatedContracts = contracts.map((entry, index) => {
+    requireString(entry.path, `contracts[${index}].path`);
+    requirePacketHash(entry.digest, `contracts[${index}].digest`);
+    return { path: entry.path, digest: entry.digest };
+  });
+  const branch = landBranch ?? `campaign/${campaignId}`;
+  requireString(branch, "landBranch");
+  /** @type {Campaign} */
+  const campaign = {
+    id: campaignId,
+    goal: normalizeText(goal, "goal", GOAL_TEXT_BYTES),
+    status: "active",
+    linkedRunIds: [],
+    contracts: validatedContracts,
+    landBranch: branch,
+    promotions: [],
+    createdAt: at,
+    updatedAt: at,
+  };
+  writeJsonAtomic(join(path, CAMPAIGN_FILE), campaign);
+  appendJournal(path, { type: "campaign.initialized", at, eventId: randomUUID() });
+  return { path, campaign };
+}
+
+/**
+ * @param {string} runsDir
+ * @returns {{campaigns: {path: string, campaign: Campaign}[], corrupt: {id: string, path: string, error: Error}[]}}
+ */
+export function discoverCampaigns(runsDir) {
+  const root = campaignsDir(runsDir);
+  if (!existsSync(root)) return { campaigns: [], corrupt: [] };
+  /** @type {{path: string, campaign: Campaign}[]} */
+  const campaigns = [];
+  /** @type {{id: string, path: string, error: Error}[]} */
+  const corrupt = [];
+  for (const name of readdirSync(root, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort()) {
+    const path = join(root, name);
+    if (!existsSync(join(path, CAMPAIGN_FILE))) {
+      corrupt.push({ id: name, path, error: new Error(`campaign.json missing in ${path}`) });
+      continue;
+    }
+    try {
+      campaigns.push({ path, campaign: readCampaign(path) });
+    } catch (error) {
+      corrupt.push({ id: name, path, error: error instanceof Error ? error : new Error(String(error)) });
+    }
+  }
+  return { campaigns, corrupt };
+}
+
+/**
+ * @param {string} runsDir
+ * @param {string|null|undefined} [campaignId]
+ * @returns {{path: string, campaign: Campaign}}
+ */
+export function resolveCampaign(runsDir, campaignId) {
+  if (campaignId !== undefined && campaignId !== null) {
+    requireId(campaignId, "campaignId");
+    const path = campaignDir(runsDir, campaignId);
+    return { path, campaign: readCampaign(path) };
+  }
+  const { campaigns, corrupt } = discoverCampaigns(runsDir);
+  if (corrupt.length) {
+    throw new Error(`corrupt campaign entries: ${corrupt.map((entry) => entry.id).join(", ")}`);
+  }
+  const active = campaigns.filter((entry) => entry.campaign.status === "active");
+  if (!active.length) {
+    if (campaigns.length) {
+      throw new Error(`no active campaign under ${campaignsDir(runsDir)}; all campaigns are closed`);
+    }
+    throw new Error(`no campaign found under ${campaignsDir(runsDir)}; initialize one with: runner.mjs campaign init`);
+  }
+  if (active.length > 1) {
+    const ids = active.map((entry) => entry.campaign.id).join(", ");
+    throw new Error(`multiple campaigns found (${ids}); choose one by id`);
+  }
+  return active[0];
+}
+
+/**
+ * @param {string} campaignPath
+ * @param {{at?: string, eventId?: string}} options
+ * @returns {{path: string, campaign: Campaign}}
+ */
+export function closeCampaign(campaignPath, { at = new Date().toISOString(), eventId = randomUUID() } = {}) {
+  requireTimestamp(at, "at");
+  const campaign = readCampaign(campaignPath);
+  if (campaign.status === "closed") throw new Error(`campaign already closed: ${campaign.id}`);
+  if (!readJournalForDedupe(campaignPath).some((entry) => entry.type === "retrospective")) {
+    throw new Error(`campaign ${campaign.id} has no recorded retrospective; record one with note --kind retrospective before close`);
+  }
+  const closed = /** @type {Campaign} */ ({ ...campaign, status: "closed", closedAt: at, updatedAt: at });
+  writeJsonAtomic(join(campaignPath, CAMPAIGN_FILE), closed);
+  appendJournal(campaignPath, { type: "campaign.closed", at, eventId });
+  return { path: campaignPath, campaign: closed };
+}
+
+/**
+ * @param {string} campaignPath
+ * @param {string} runId
+ * @param {string} at
+ * @returns {Campaign}
+ */
+export function registerRun(campaignPath, runId, at = new Date().toISOString()) {
+  requireId(runId, "runId");
+  requireTimestamp(at, "at");
+  const campaign = readCampaign(campaignPath);
+  if (campaign.status === "closed") throw new Error(`campaign is closed: ${campaign.id}`);
+  if (campaign.linkedRunIds.includes(runId)) {
+    campaign.updatedAt = at;
+    writeJsonAtomic(join(campaignPath, CAMPAIGN_FILE), campaign);
+    return campaign;
+  }
+  campaign.linkedRunIds.push(runId);
+  campaign.updatedAt = at;
+  writeJsonAtomic(join(campaignPath, CAMPAIGN_FILE), campaign);
+  appendJournal(campaignPath, { type: "run.registered", at, eventId: randomUUID(), runId });
+  return campaign;
+}
+
+/**
+ * The digest of a contract's authored bytes: the raw file, before validation
+ * canonicalizes or resolves anything. This is what a manifest entry records,
+ * so tampering between authoring and launch is detectable without validating
+ * the contract early (validation is deferred because a readFile may name a
+ * file a predecessor has not created yet).
+ *
+ * @param {string} contractPath
+ * @returns {string}
+ */
+export function authoredContractDigest(contractPath) {
+  return createHash("sha256").update(readFileSync(contractPath)).digest("hex");
+}
+
+/**
+ * Refuse a manifest entry whose file no longer matches the bytes it recorded.
+ * The chain calls this at launch, before it validates N+1 against the landing
+ * branch.
+ *
+ * @param {CampaignContract} entry
+ * @returns {void}
+ */
+export function assertContractManifestIntact(entry) {
+  requireString(entry.path, "contract path");
+  requirePacketHash(entry.digest, "contract digest");
+  const actual = authoredContractDigest(entry.path);
+  if (actual !== entry.digest) {
+    throw Object.assign(
+      new Error(`contract ${entry.path} changed after it was authored; refusing to launch bytes the manifest did not record`),
+      { code: "contract_authored_bytes_changed" },
+    );
+  }
+}
+
+/**
+ * Persist one promotion in the campaign record. Idempotent by run id and the
+ * sha it landed: a re-invocation after a crash between the branch move and
+ * this write repairs the record without adding a second promotion.
+ *
+ * @param {string} campaignPath
+ * @param {PromotionRecord} entry
+ * @returns {PromotionRecord}
+ */
+export function recordPromotion(campaignPath, entry) {
+  requireId(entry.runId, "promotion.runId");
+  requireString(entry.branch, "promotion.branch");
+  requireString(entry.sha, "promotion.sha");
+  requireTimestamp(entry.at, "promotion.at");
+  const campaign = readCampaign(campaignPath);
+  const existing = campaign.promotions.find((record) => record.runId === entry.runId && record.sha === entry.sha);
+  if (existing) return existing;
+  campaign.promotions.push(entry);
+  campaign.updatedAt = entry.at;
+  writeJsonAtomic(join(campaignPath, CAMPAIGN_FILE), campaign);
+  return entry;
+}
+
+/**
+ * Record a durable attention entry on the campaign and keep it active. The
+ * chain parks here when a contract's run did not succeed, when a contract no
+ * longer validates, or when two digests disagree; the message names the
+ * contract, the node and the status whenever they exist.
+ *
+ * @param {string} campaignPath
+ * @param {CampaignAttention} attention
+ * @returns {Campaign}
+ */
+export function parkCampaign(campaignPath, attention) {
+  requireString(attention.code, "campaign.attention.code");
+  requireString(attention.message, "campaign.attention.message");
+  requireTimestamp(attention.at, "campaign.attention.at");
+  const campaign = readCampaign(campaignPath);
+  const parked = /** @type {Campaign} */ ({ ...campaign, attention, updatedAt: attention.at });
+  writeJsonAtomic(join(campaignPath, CAMPAIGN_FILE), parked);
+  return parked;
+}
+
+/**
+ * Promote a run onto the campaign's landing branch and record it. The branch
+ * name comes from the campaign record, never from the caller, so a campaign
+ * cannot be promoted somewhere its manifest does not name.
+ *
+ * @param {{campaignPath: string, repo: string, runId: string, runHead?: string|null, baseSha?: string|null, finalVerificationPassed: boolean, allowMain?: boolean, contractPath?: string}} args
+ * @returns {import("../repo/integrate.mjs").PromoteRecord}
+ */
+export function promoteRunInCampaign({ campaignPath, repo, runId, runHead, baseSha, finalVerificationPassed, allowMain = false, contractPath }) {
+  const campaign = readCampaign(campaignPath);
+  if (campaign.status === "closed") throw new Error(`campaign is closed: ${campaign.id}`);
+  return promoteRun({
+    repo,
+    runId,
+    landBranch: campaign.landBranch,
+    runHead,
+    baseSha,
+    finalVerificationPassed,
+    allowMain,
+    onPromoted: (record) => {
+      recordPromotion(campaignPath, {
+        runId: record.runId,
+        ...(contractPath === undefined ? {} : { contractPath }),
+        branch: record.branch,
+        sha: record.sha,
+        previousSha: record.previousSha,
+        at: record.at,
+      });
+    },
+  });
+}
+
+/**
+ * @param {string} campaignPath
+ * @param {string} runsDir
+ * @returns {string}
+ */
+export function renderHandoff(campaignPath, runsDir) {
+  const campaign = readCampaign(campaignPath);
+  const { state, cursor, byte, size, changed } = readProjectionState(campaignPath, campaign);
+  const handoff = handoffFromState(campaign, state, runsDir);
+  const text = materializeHandoff(campaignPath, handoff);
+  if (changed) writeJsonAtomic(join(campaignPath, PROJECTION_FILE), { cursor, byte, size, projection: state });
+  return text;
+}
+
+/**
+ * @param {string} runDir
+ * @returns {string|null}
+ */
+export function renderRunHandoff(runDir) {
+  const contractPath = join(runDir, "contract.json");
+  if (!existsSync(contractPath)) return null;
+  const contract = /** @type {JsonObject} */ (JSON.parse(readFileSync(contractPath, "utf8")));
+  if (!contract.campaignId) return null;
+  const runsDir = resolve(runDir, "..");
+  const path = campaignDir(runsDir, /** @type {string} */ (contract.campaignId));
+  if (!existsSync(join(path, CAMPAIGN_FILE))) return null;
+  return renderHandoff(path, runsDir);
+}
+

package/src/campaign/journal.mjs

@@ -0,0 +1,347 @@
+/**
+ * The campaign journal: an append-only log of material events, and the cursor
+ * machinery that lets a session read only what it has not seen.
+ *
+ * Append-only is the point. A campaign is the durable memory across sessions and
+ * across agents, so the journal is never rewritten -- `watchJournal` and
+ * `acknowledgeJournalEvent` move a per-session cursor over it instead, keyed by
+ * the journal's own `eventId` so two sessions cannot consume each other's place.
+ */
+import { JOURNAL_FILE, JOURNAL_TEXT_BYTES, JOURNAL_WATCH_CURSOR_DIR, JOURNAL_WATCH_CURSOR_SCHEMA_VERSION } from "./layout.mjs";
+import { boundedText, collapseLines } from "../util.mjs";
+import { campaignIdOf } from "./record.mjs";
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join } from "node:path";
+import { requireText, requireTimestamp } from "../contract/assert.mjs";
+import { writeJsonAtomic } from "../run/store.mjs";
+
+/** @typedef {import("./index.mjs").JournalEntry} JournalEntry */
+/** @typedef {import("../notify/index.mjs").JsonObject} JsonObject */
+
+const JOURNAL_TYPES = new Set([
+  "campaign.initialized",
+  "campaign.closed",
+  "campaign.unparked",
+  "run.registered",
+  "session.attached",
+  "intent",
+  "decision",
+  "supersede",
+  "constraint",
+  "outcome",
+  "next",
+  "open-question",
+  "question.resolved",
+  "retrospective",
+  "liveness",
+]);
+const SESSION_REQUIRED_TYPES = new Set([
+  "session.attached",
+  "intent",
+  "decision",
+  "supersede",
+  "constraint",
+  "outcome",
+  "next",
+  "open-question",
+  "question.resolved",
+  "retrospective",
+]);
+const ENTRY_SHAPES = {
+  "campaign.initialized": ["at", "type", "eventId"],
+  "campaign.closed": ["at", "type", "eventId"],
+  "campaign.unparked": ["at", "type", "eventId", "code", "runId"],
+  "run.registered": ["at", "type", "eventId", "runId"],
+  "session.attached": ["at", "type", "eventId", "sessionId", "tool", "transcript", "transcriptUnavailable", "format", "cursor"],
+  intent: ["at", "type", "eventId", "sessionId", "text"],
+  decision: ["at", "type", "eventId", "sessionId", "decisionId", "text"],
+  supersede: ["at", "type", "eventId", "sessionId", "supersedes", "text"],
+  constraint: ["at", "type", "eventId", "sessionId", "text"],
+  outcome: ["at", "type", "eventId", "sessionId", "text", "runId"],
+  next: ["at", "type", "eventId", "sessionId", "text"],
+  "open-question": ["at", "type", "eventId", "sessionId", "questionId", "text"],
+  "question.resolved": ["at", "type", "eventId", "sessionId", "questionId", "text"],
+  retrospective: ["at", "type", "eventId", "sessionId", "text"],
+  liveness: ["at", "type", "eventId", "campaignId", "runId", "nodeId", "phase", "checkpointsDone", "checkpointsTotal", "runtime", "state", "lastProgressAt", "attention"],
+};
+/**
+ * Fields a liveness fact carried before the budget ceiling was removed. A
+ * historical journal (like the live campaign's own) still has lines shaped
+ * like the pre-diet fact, so a read path drops them instead of rejecting the
+ * whole file; nothing writes them any more.
+ */
+const LEGACY_LIVENESS_FIELDS = ["weightedUsed", "weightedCap"];
+/**
+ * @param {JournalEntry} entry
+ * @returns {JournalEntry}
+ */
+export function withoutLegacyLivenessFields(entry) {
+  if (entry.type !== "liveness") return entry;
+  const cleaned = /** @type {JournalEntry} */ ({ ...entry });
+  for (const field of LEGACY_LIVENESS_FIELDS) delete /** @type {JsonObject} */ (cleaned)[field];
+  return cleaned;
+}
+/**
+ * @param {string} campaignPath
+ * @param {unknown} entry
+ * @returns {{entry: JournalEntry, deduplicated: boolean}}
+ */
+export function appendJournal(campaignPath, entry) {
+  validateJournalEntry(entry);
+  const normalized = normalizeEntry(/** @type {JournalEntry} */ (entry));
+  const journalPath = join(campaignPath, JOURNAL_FILE);
+  if (existsSync(journalPath)) {
+    for (const existing of readJournalForDedupe(campaignPath)) {
+      if (existing.eventId === normalized.eventId) return { entry: existing, deduplicated: true };
+    }
+  }
+  const descriptor = openSync(journalPath, "a");
+  try {
+    writeFileSync(descriptor, `${JSON.stringify(normalized)}\n`);
+    fsyncSync(descriptor);
+  } finally {
+    closeSync(descriptor);
+  }
+  return { entry: normalized, deduplicated: false };
+}
+/**
+ * @param {string} campaignPath
+ * @returns {JournalEntry[]}
+ */
+export function readJournalForDedupe(campaignPath) {
+  const path = join(campaignPath, JOURNAL_FILE);
+  if (!existsSync(path)) return [];
+  /** @type {JournalEntry[]} */
+  const entries = [];
+  for (const line of readFileSync(path, "utf8").split(/\r?\n/u)) {
+    if (!line.trim()) continue;
+    try {
+      entries.push(/** @type {JournalEntry} */ (JSON.parse(line)));
+    } catch {
+      // A corrupt prior line cannot match an event id; appends must not be
+      // blocked by it because the journal is the authoritative audit source.
+    }
+  }
+  return entries;
+}
+/**
+ * Incremental read of the campaign journal for a session sync/watch, keyed by
+ * the journal's own `eventId`. Legacy `liveness` entries (the old heartbeat
+ * mechanism used to append them; nothing does any more) are filtered out: they carry no
+ * narrative a session needs to catch up on. Exactly one of `since` (a
+ * stateless event id) or `cursor` (a durable per-watcher position) is
+ * accepted; `cursor` advances atomically after the unseen list is built
+ * unless `readOnly` is set, so a repeated read-only call returns no events.
+ *
+ * @param {string} campaignPath
+ * @param {{since?: string, cursor?: string, readOnly?: boolean}} [options]
+ * @returns {{campaignId: string, cursor: {cursorId: string, at: string, eventId: string}|null, events: JournalEntry[]}}
+ */
+export function watchJournal(campaignPath, options = {}) {
+  if ((options.since !== undefined) === (options.cursor !== undefined)) {
+    throw new TypeError("watch requires exactly one of --since or --cursor");
+  }
+  const entries = readJournal(campaignPath)
+    .filter((entry) => entry.type !== "liveness")
+    .sort(compareJournalPositions);
+  let cursorId = null;
+  /** @type {{at: string, eventId: string}} */
+  let position;
+  if (options.since !== undefined) {
+    const since = String(options.since);
+    const entry = entries.find((candidate) => candidate.eventId === since);
+    if (!entry) throw new TypeError("--since event ID is not retained in the journal");
+    position = { at: entry.at, eventId: entry.eventId };
+  } else {
+    cursorId = String(options.cursor);
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u.test(cursorId)) throw new TypeError("--cursor must be a safe identifier");
+    position = readJournalCursor(campaignPath, cursorId);
+  }
+  const events = entries.filter((entry) => compareJournalPositions(entry, position) > 0);
+  if (cursorId !== null && !options.readOnly && events.length > 0) {
+    const last = events[events.length - 1];
+    position = { at: last.at, eventId: last.eventId };
+    writeJournalCursor(campaignPath, { cursorId, ...position });
+  }
+  return { campaignId: campaignIdOf(campaignPath), cursor: cursorId === null ? null : { cursorId, ...position }, events };
+}
+/**
+ * Acknowledge one retained journal event by atomically advancing a durable
+ * per-session cursor to it. `ack` is the only cursor writer: `watchJournal`
+ * only advances when explicitly told to (never in read-only mode). Cursor
+ * movement never regresses.
+ *
+ * @param {string} campaignPath
+ * @param {string} cursorId
+ * @param {string} eventId
+ * @returns {{cursorId: string, at: string, eventId: string}}
+ */
+export function acknowledgeJournalEvent(campaignPath, cursorId, eventId) {
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u.test(cursorId)) throw new TypeError("--cursor must be a safe identifier");
+  if (typeof eventId !== "string" || !eventId.trim()) throw new TypeError("--event-id requires a value");
+  const current = readJournalCursor(campaignPath, cursorId);
+  const found = readJournal(campaignPath).find((candidate) => candidate.eventId === eventId);
+  let position;
+  if (found) {
+    position = { at: found.at, eventId: found.eventId };
+  } else if (current.eventId !== "" && current.eventId === eventId) {
+    position = current;
+  } else {
+    throw new TypeError("--event-id is not retained in the journal");
+  }
+  if (current.eventId !== "" && compareJournalPositions(position, current) <= 0) position = current;
+  if (current.eventId === "" || compareJournalPositions(position, current) > 0) {
+    writeJournalCursor(campaignPath, { cursorId, ...position });
+  }
+  return { cursorId, ...position };
+}
+/** @param {{at: string, eventId: string}} left @param {{at: string, eventId: string}} right @returns {number} */
+function compareJournalPositions(left, right) {
+  if (left.at !== right.at) return left.at < right.at ? -1 : 1;
+  return left.eventId < right.eventId ? -1 : left.eventId > right.eventId ? 1 : 0;
+}
+/** @param {string} campaignPath @param {string} cursorId @returns {{at: string, eventId: string}} */
+function readJournalCursor(campaignPath, cursorId) {
+  const path = join(campaignPath, JOURNAL_WATCH_CURSOR_DIR, `${cursorId}.json`);
+  if (!existsSync(path)) return { at: "", eventId: "" };
+  const record = /** @type {JsonObject} */ (JSON.parse(readFileSync(path, "utf8")));
+  requireText(record.at, "journal watch cursor.at");
+  if (typeof record.eventId !== "string") throw new TypeError("journal watch cursor.eventId must be a string");
+  return { at: String(record.at), eventId: record.eventId };
+}
+/** @param {string} campaignPath @param {{cursorId: string, at: string, eventId: string}} position */
+function writeJournalCursor(campaignPath, position) {
+  const path = join(campaignPath, JOURNAL_WATCH_CURSOR_DIR, `${position.cursorId}.json`);
+  mkdirSync(dirname(path), { recursive: true });
+  writeJsonAtomic(path, { schemaVersion: JOURNAL_WATCH_CURSOR_SCHEMA_VERSION, ...position, updatedAt: new Date().toISOString() });
+}
+/**
+ * @param {string} campaignPath
+ * @returns {JournalEntry[]}
+ */
+export function readJournal(campaignPath) {
+  const path = join(campaignPath, JOURNAL_FILE);
+  if (!existsSync(path)) return [];
+  const text = readFileSync(path, "utf8");
+  const lines = text.split(/\r?\n/u);
+  /** @type {JournalEntry[]} */
+  const entries = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+    if (!line.trim()) continue;
+    if (index === lines.length - 1 && !text.endsWith("\n")) {
+      // The newline is written atomically with the entry, so an unterminated
+      // final line is never a committed entry; skip it regardless of whether
+      // its bytes happen to parse.
+      continue;
+    }
+    try {
+      const entry = withoutLegacyLivenessFields(/** @type {JournalEntry} */ (JSON.parse(line)));
+      validateJournalEntry(entry);
+      entries.push(entry);
+    } catch (error) {
+      throw new Error(`journal line ${index + 1} is invalid: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  return entries;
+}
+/**
+ * @param {unknown} entry
+ */
+export function validateJournalEntry(entry) {
+  if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+    throw new TypeError("journal entry must be an object");
+  }
+  const record = /** @type {JsonObject} */ (entry);
+  const type = /** @type {keyof typeof ENTRY_SHAPES} */ (record.type);
+  if (!JOURNAL_TYPES.has(type)) {
+    throw new TypeError(`journal entry type must be one of ${[...JOURNAL_TYPES].join(", ")}`);
+  }
+  const allowed = ENTRY_SHAPES[type];
+  for (const key of Object.keys(record)) {
+    if (!allowed.includes(key)) throw new TypeError(`journal entry ${type} has unexpected field ${key}`);
+  }
+  requireTimestamp(record.at, "entry.at");
+  requireText(record.eventId, "entry.eventId");
+  if (SESSION_REQUIRED_TYPES.has(type)) {
+    requireText(record.sessionId, "entry.sessionId");
+  }
+  // "liveness" is a legacy type: the old heartbeat mechanism used to append it and nothing
+  // writes it any more, but a durable journal may still carry old entries and
+  // reading them must not throw. The shared allowed-field check above already
+  // rejects an unexpected key; no deeper shape validation is needed for a type
+  // nothing produces.
+  if (type === "liveness") return;
+  if (type === "session.attached") return validateSessionEntry(record);
+  if (type === "run.registered") {
+    requireText(record.runId, "entry.runId");
+    return;
+  }
+  if (type === "campaign.initialized" || type === "campaign.closed") return;
+  if (type === "campaign.unparked") {
+    requireText(record.code, "entry.code");
+    // `runId` is optional, exactly as `outcome` treats it, but the unpark
+    // writer records an explicit null when the parked attention named no run.
+    if (record.runId !== null && record.runId !== undefined) requireText(record.runId, "entry.runId");
+    return;
+  }
+  requireText(record.text, "entry.text");
+  if (type === "decision") requireText(record.decisionId, "entry.decisionId");
+  if (type === "supersede") requireText(record.supersedes, "entry.supersedes");
+  if (type === "open-question" || type === "question.resolved") {
+    requireText(record.questionId, "entry.questionId");
+  }
+  if (type === "outcome" && record.runId !== undefined) requireText(record.runId, "entry.runId");
+}
+/**
+ * @param {JsonObject} entry
+ */
+function validateSessionEntry(entry) {
+  requireText(entry.tool, "session.tool");
+  requireText(entry.sessionId, "session.sessionId");
+  if (typeof entry.transcriptUnavailable !== "boolean") {
+    throw new TypeError("session.transcriptUnavailable must be a boolean");
+  }
+  if (entry.transcriptUnavailable) {
+    if (entry.transcript !== null) throw new TypeError("unavailable session must not include a transcript path");
+    if (entry.format !== null) throw new TypeError("unavailable session must not include a transcript format");
+  } else {
+    if (typeof entry.transcript !== "string" || !isAbsolute(entry.transcript)) {
+      throw new TypeError("session.transcript must be an absolute path when available");
+    }
+    if (typeof entry.format !== "string" || !entry.format.trim()) {
+      throw new TypeError("session.format must be a non-empty string when a transcript is available");
+    }
+  }
+  if (entry.cursor !== null && entry.cursor !== undefined && (typeof entry.cursor !== "string" || !entry.cursor.trim())) {
+    throw new TypeError("session.cursor must be null, omitted, or a non-empty string");
+  }
+}
+/**
+ * @param {JournalEntry} entry
+ * @returns {JournalEntry}
+ */
+function normalizeEntry(entry) {
+  /** @type {Record<string, unknown>} */
+  const normalized = {};
+  for (const [key, value] of Object.entries(entry)) {
+    if (typeof value === "string") {
+      normalized[key] = key === "text" ? normalizeText(value, "entry.text") : collapseLines(value);
+    } else {
+      normalized[key] = value;
+    }
+  }
+  return /** @type {JournalEntry} */ (normalized);
+}
+/**
+ * @param {unknown} value
+ * @param {string} label
+ * @param {number} maxBytes
+ * @returns {string}
+ */
+export function normalizeText(value, label, maxBytes = JOURNAL_TEXT_BYTES) {
+  requireText(value, label);
+  const collapsed = collapseLines(value);
+  if (!collapsed) throw new TypeError(`${label} must not be blank`);
+  return boundedText(collapsed, maxBytes);
+}