@aragon-agent/cli 0.6.44 → 0.6.45

package/dist/governance/store/run-store.js

@@ -0,0 +1,644 @@
+/**
+ * RunStore - the single writer of `<root>/<runId>/` (governance-mode section 12.1).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * RESPONSIBILITIES AND WHY THEY ARE ONE CLASS. Every write funnels through ONE FIFO mutex
+ * so that two concurrent engine paths (a submission landing while a stage-end checkpoint
+ * is being written) can never interleave their bytes or their sequence numbers.
+ * Cross-process exclusion is a separate mechanism (`run.lock`, see `run-lock.ts`).
+ *
+ * TRUTH VS CHECKPOINT. `events.jsonl` is the truth (append + fsync, one JSON row per
+ * line); `run.json` and `ledger.json` are atomic-replace checkpoints. `load()` compares
+ * the checkpoint `seq` values with the log tail and reports `needsReplay`; the actual
+ * fold of events into state is supplied by the engine as a callback, which keeps this
+ * file free of any dependency on `rules/ledger.ts` (I-G2 stays the ledger's business).
+ * Checkpoint writers must therefore stamp the CURRENT tail seq, otherwise `needsReplay`
+ * is true forever.
+ *
+ * SEQUENCES ARE ASSIGNED HERE, not by callers: the store caches the tail per run, so a
+ * caller can never reuse or skip a number. A row dropped by compaction consumes no seq,
+ * which keeps the checkpoint-vs-tail comparison honest.
+ *
+ * The root directory is a constructor argument (`getGovernanceDir()` lives in
+ * `config/app-paths.ts`); nothing here reads the environment.
+ */
+import { join, resolve } from 'node:path';
+import { GOV_LIMITS, GOV_SCHEMA_VERSION, RUN_ID_PATTERN } from '../limits.js';
+import { appendLineFsync, atomicWriteFile, ensureDir, nodeGovFs, } from './atomic.js';
+import { EVENTS_KEPT_AFTER_CAP, parseEventsText, serializeEvent } from './events-log.js';
+import { acquireLock, defaultIsPidAlive, isLockLive, readLock, refreshLock, removeLock, } from './run-lock.js';
+import { buildScoreboard } from './scoreboard-export.js';
+const DAY_MS = 86_400_000;
+const TERMINAL = new Set(['closed', 'abandoned']);
+/** Programmer-facing store failures (the engine turns them into tool text). */
+export class GovStoreError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'GovStoreError';
+    }
+}
+/** FIFO async mutex. Never call `run` from inside a `run` callback (self-deadlock). */
+class FifoMutex {
+    tail = Promise.resolve();
+    run(fn) {
+        const result = this.tail.then(fn);
+        this.tail = result.then(() => undefined, () => undefined);
+        return result;
+    }
+}
+/** Relative path inside a run folder: no absolute paths, no `..`, no NUL. */
+function safeRelative(rel) {
+    const unified = rel.replace(/\\/g, '/');
+    const bad = unified === '' ||
+        unified.includes('\0') ||
+        unified.startsWith('/') ||
+        /^[a-zA-Z]:/.test(unified) ||
+        unified.split('/').some((segment) => segment === '..' || segment === '');
+    if (bad)
+        throw new GovStoreError('BAD_PATH', `unsafe relative path: ${JSON.stringify(rel)}`);
+    return unified;
+}
+function normalizeCwd(cwd, platform) {
+    const unified = resolve(cwd).replace(/\\/g, '/').replace(/\/+$/, '');
+    return platform === 'win32' ? unified.toLowerCase() : unified;
+}
+export class RunStore {
+    root;
+    fs;
+    platform;
+    now;
+    newId;
+    pid;
+    isPidAlive;
+    heartbeatMs;
+    sleep;
+    onLockLost;
+    mutex = new FifoMutex();
+    caches = new Map();
+    heartbeats = new Map();
+    heldLocks = new Set();
+    constructor(options) {
+        this.root = options.root;
+        this.fs = options.fs ?? nodeGovFs;
+        this.platform = options.platform ?? process.platform;
+        this.now = options.now ?? Date.now;
+        this.newId = options.newId ?? defaultSuffix;
+        this.pid = options.pid ?? process.pid;
+        this.isPidAlive = options.isPidAlive ?? defaultIsPidAlive;
+        this.heartbeatMs = options.heartbeatMs ?? GOV_LIMITS.lockHeartbeatMs;
+        this.sleep = options.sleep;
+        this.onLockLost = options.onLockLost;
+    }
+    // -------------------------------------------------------------------------
+    // Paths and ids
+    // -------------------------------------------------------------------------
+    /** Validates the id first: a run id is the only caller-influenced path segment. */
+    runDir(runId) {
+        if (!RUN_ID_PATTERN.test(runId)) {
+            throw new GovStoreError('BAD_RUN_ID', `invalid run id: ${JSON.stringify(runId)}`);
+        }
+        return join(this.root, runId);
+    }
+    runFile(runId, rel) {
+        return join(this.runDir(runId), ...safeRelative(rel).split('/'));
+    }
+    /** "g" + base36(timeMs) + 3 random [a-z0-9]; retried until the folder is unused. */
+    async allocateRunId() {
+        for (let attempt = 0; attempt < 8; attempt++) {
+            const candidate = `g${this.now().toString(36)}${this.newId()}`;
+            if (!RUN_ID_PATTERN.test(candidate))
+                continue;
+            const taken = await this.fs.stat(join(this.root, candidate)).then(() => true, () => false);
+            if (!taken)
+                return candidate;
+        }
+        throw new GovStoreError('EXISTS', 'could not allocate a free run id');
+    }
+    // -------------------------------------------------------------------------
+    // Run creation and checkpoints
+    // -------------------------------------------------------------------------
+    /** Create the folder, `spec.md` (verbatim) and the first `run.json`; index the run. */
+    async createRun(input) {
+        const { state, spec } = input;
+        const dir = this.runDir(state.runId);
+        await this.mutex.run(async () => {
+            const exists = await this.fs.stat(join(dir, 'run.json')).then(() => true, () => false);
+            if (exists)
+                throw new GovStoreError('EXISTS', `run ${state.runId} already exists`);
+            await ensureDir(join(dir, 'artifacts'), this.fs);
+            await this.atomic(join(dir, 'spec.md'), spec);
+            await this.atomic(join(dir, 'run.json'), JSON.stringify(state, null, 2));
+            this.caches.set(state.runId, this.freshCache(state.seq));
+            await this.appendIndexUnlocked(state);
+        });
+    }
+    /**
+     * Atomic replace of `run.json`; appends an index row when the status changed OR, for a
+     * caller that supplies one, when the digest did. `index.jsonl` is append-only and
+     * `listRuns` keeps the newest row per run, so appending IS the update. A caller without a
+     * digest behaves byte-for-byte as before.
+     */
+    async writeRun(state, digest) {
+        const dir = this.runDir(state.runId);
+        await this.mutex.run(async () => {
+            const cache = await this.ensureCache(state.runId);
+            this.assertWritable(state.runId, cache);
+            await this.atomic(join(dir, 'run.json'), JSON.stringify(state, null, 2));
+            const digestChanged = digest !== undefined && JSON.stringify(digest) !== cache.indexedDigest;
+            if (cache.indexedStatus !== state.status || digestChanged) {
+                await this.appendIndexUnlocked(state, digest);
+            }
+        });
+    }
+    /** Atomic replace of `ledger.json`. The caller stamps `ledger.seq`. */
+    async writeLedger(runId, ledger) {
+        const dir = this.runDir(runId);
+        await this.mutex.run(async () => {
+            this.assertWritable(runId, await this.ensureCache(runId));
+            await this.atomic(join(dir, 'ledger.json'), JSON.stringify(ledger, null, 2));
+        });
+    }
+    /** One-way `token_ledger.py` v2.0 projection. Never read back. */
+    async exportScoreboard(runId, ledger) {
+        const dir = this.runDir(runId);
+        await this.mutex.run(async () => {
+            const text = JSON.stringify(buildScoreboard(ledger, this.now()), null, 2);
+            await this.atomic(join(dir, 'scoreboard.json'), text);
+        });
+    }
+    // -------------------------------------------------------------------------
+    // Events (the truth)
+    // -------------------------------------------------------------------------
+    /**
+     * Append one event and fsync. Returns the stored row, or `null` when compaction
+     * dropped it (past the byte cap only audit-only types are dropped).
+     */
+    async appendEvent(runId, input) {
+        this.runDir(runId);
+        return this.mutex.run(async () => {
+            const cache = await this.ensureCache(runId);
+            this.assertWritable(runId, cache);
+            const overCap = cache.eventsBytes >= GOV_LIMITS.eventsFileBytes;
+            if (overCap && !cache.compacted)
+                await this.writeCompactionMarker(runId, cache, input);
+            if (overCap && !EVENTS_KEPT_AFTER_CAP.has(input.type)) {
+                cache.droppedRows += 1;
+                return null;
+            }
+            return this.writeEventRow(runId, cache, input);
+        });
+    }
+    async writeCompactionMarker(runId, cache, trigger) {
+        cache.compacted = true;
+        await this.writeEventRow(runId, cache, {
+            type: 'compacted',
+            actor: 'engine',
+            payload: {
+                reason: 'events.jsonl passed its byte budget; audit-only rows are dropped from here',
+                limitBytes: GOV_LIMITS.eventsFileBytes,
+                keptTypes: [...EVENTS_KEPT_AFTER_CAP],
+                firstTriggerType: trigger.type,
+            },
+        });
+    }
+    async writeEventRow(runId, cache, input) {
+        const row = {
+            seq: input.seq ?? cache.lastSeq + 1,
+            at: input.at ?? this.now(),
+            type: input.type,
+            actor: input.actor,
+            payload: input.payload,
+        };
+        const line = serializeEvent(row);
+        await appendLineFsync(this.runFile(runId, 'events.jsonl'), line, {
+            fs: this.fs,
+            leadingNewline: cache.tornTail,
+        });
+        cache.lastSeq = Math.max(cache.lastSeq, row.seq);
+        cache.tornTail = false;
+        cache.eventsBytes += Buffer.byteLength(line) + 1;
+        return row;
+    }
+    /** Rows with `seq > afterSeq`, in file order. Missing file reads as empty. */
+    async readEvents(runId, afterSeq = 0) {
+        const parsed = await this.parseEvents(runId);
+        return parsed.events.filter((event) => event.seq > afterSeq);
+    }
+    /** How many rows compaction dropped in this process (the marker row says why). */
+    droppedEventCount(runId) {
+        return this.caches.get(runId)?.droppedRows ?? 0;
+    }
+    async parseEvents(runId) {
+        const text = await this.fs.readFile(this.runFile(runId, 'events.jsonl')).catch(() => '');
+        return { ...parseEventsText(text), bytes: Buffer.byteLength(text) };
+    }
+    // -------------------------------------------------------------------------
+    // Load / replay
+    // -------------------------------------------------------------------------
+    /** Read both checkpoints and the log tail; optionally repair via `options.replay`. */
+    async load(runId, options = {}) {
+        this.runDir(runId);
+        const problems = [];
+        const parsed = await this.parseEvents(runId);
+        let run = await this.readCheckpoint(runId, 'run.json', problems);
+        let ledger = await this.readCheckpoint(runId, 'ledger.json', problems);
+        const readOnly = this.isNewerSchema(run) || this.isNewerSchema(ledger);
+        const cache = await this.ensureCache(runId);
+        cache.readOnly = readOnly;
+        if (run)
+            cache.indexedStatus = cache.indexedStatus ?? run.status;
+        if (parsed.tornTail)
+            problems.push('events.jsonl ends with a torn row (crash during append)');
+        if (parsed.badLines > 0) {
+            problems.push(`events.jsonl: ${parsed.badLines} unreadable row(s) skipped`);
+        }
+        const eventsUnreadable = parsed.bytes > 0 && parsed.events.length === 0;
+        const needsReplay = this.checkpointsBehind(run, ledger, parsed.lastSeq);
+        let replayed = false;
+        if (needsReplay && options.replay && !readOnly && !eventsUnreadable) {
+            const out = options.replay({ run, ledger, events: parsed.events, tailSeq: parsed.lastSeq });
+            if (out.run !== undefined)
+                run = out.run;
+            if (out.ledger !== undefined)
+                ledger = out.ledger;
+            await this.writeRepaired(runId, { run, ledger });
+            replayed = true;
+        }
+        return {
+            run,
+            ledger,
+            tailSeq: parsed.lastSeq,
+            needsReplay: needsReplay && !replayed,
+            replayed,
+            readOnly,
+            eventsUnreadable,
+            problems,
+        };
+    }
+    isNewerSchema(value) {
+        return value !== null && value.schemaVersion > GOV_SCHEMA_VERSION;
+    }
+    checkpointsBehind(run, ledger, tailSeq) {
+        if (run === null || ledger === null)
+            return tailSeq > 0 || run === null;
+        return run.seq < tailSeq || ledger.seq < tailSeq;
+    }
+    async readCheckpoint(runId, name, problems) {
+        let text;
+        try {
+            text = await this.fs.readFile(this.runFile(runId, name));
+        }
+        catch {
+            return null;
+        }
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            problems.push(`${name} is corrupt (unparseable); it will be rebuilt from events.jsonl`);
+            return null;
+        }
+    }
+    async writeRepaired(runId, repaired) {
+        if (repaired.run)
+            await this.writeRun(repaired.run);
+        if (repaired.ledger)
+            await this.writeLedger(runId, repaired.ledger);
+    }
+    // -------------------------------------------------------------------------
+    // Lock
+    // -------------------------------------------------------------------------
+    lockDeps() {
+        return {
+            fs: this.fs,
+            now: this.now,
+            pid: this.pid,
+            isPidAlive: this.isPidAlive,
+            staleMs: GOV_LIMITS.lockStaleMs,
+        };
+    }
+    /** Take `run.lock` (stale locks are taken over). Refusal text names the holder pid. */
+    async acquireLock(runId) {
+        // No mkdir: locking a run whose folder does not exist is a caller bug (ENOENT), and
+        // creating the folder here would conjure an empty run directory.
+        const result = await acquireLock(this.runFile(runId, 'run.lock'), this.lockDeps());
+        if (result.ok)
+            this.heldLocks.add(runId);
+        return result;
+    }
+    /** Start the unref'd heartbeat timer; idempotent. */
+    startHeartbeat(runId) {
+        if (this.heartbeats.has(runId))
+            return;
+        const timer = setInterval(() => {
+            void this.heartbeatOnce(runId);
+        }, this.heartbeatMs);
+        timer.unref();
+        this.heartbeats.set(runId, timer);
+    }
+    stopHeartbeat(runId) {
+        const timer = this.heartbeats.get(runId);
+        if (timer)
+            clearInterval(timer);
+        this.heartbeats.delete(runId);
+    }
+    /** One heartbeat tick (public so tests need no fake timers). False = lock lost. */
+    async heartbeatOnce(runId) {
+        let alive = false;
+        try {
+            alive = await refreshLock(this.runFile(runId, 'run.lock'), this.lockDeps());
+        }
+        catch {
+            return true;
+        }
+        if (!alive) {
+            this.stopHeartbeat(runId);
+            this.heldLocks.delete(runId);
+            this.onLockLost?.(runId);
+        }
+        return alive;
+    }
+    async releaseLock(runId) {
+        this.stopHeartbeat(runId);
+        this.heldLocks.delete(runId);
+        await removeLock(this.runFile(runId, 'run.lock'), this.lockDeps());
+    }
+    /** Stop every timer and release every lock this process holds. Safe to call twice. */
+    async dispose() {
+        for (const runId of [...this.heartbeats.keys()])
+            this.stopHeartbeat(runId);
+        for (const runId of [...this.heldLocks])
+            await this.releaseLock(runId);
+    }
+    async isRunLocked(runId) {
+        const info = await readLock(this.runFile(runId, 'run.lock'), this.fs);
+        return isLockLive(info, this.lockDeps()) || (info !== null && info.pid === this.pid);
+    }
+    // -------------------------------------------------------------------------
+    // Run files and artifacts
+    // -------------------------------------------------------------------------
+    /** Atomic write of a projection (`board.md`, `reports/phase-1.md`). Not budgeted. */
+    async writeRunFile(runId, rel, text) {
+        const path = this.runFile(runId, rel);
+        await this.mutex.run(async () => {
+            this.assertWritable(runId, await this.ensureCache(runId));
+            await this.atomic(path, text);
+        });
+    }
+    async readRunFile(runId, rel) {
+        return this.fs.readFile(this.runFile(runId, rel)).catch(() => null);
+    }
+    async listRunDir(runId, rel) {
+        const dir = rel === '' ? this.runDir(runId) : this.runFile(runId, rel);
+        const names = await this.fs.readdir(dir).catch(() => []);
+        const entries = [];
+        for (const name of names.sort()) {
+            const stat = await this.fs.stat(join(dir, name)).catch(() => null);
+            if (stat)
+                entries.push({ name, isDirectory: stat.isDirectory(), size: stat.size });
+        }
+        return entries;
+    }
+    /**
+     * Write under `artifacts/`, enforcing the per-run byte budget. The budget is a refusal
+     * (never a silent drop): the caller reports `NOT ACCEPTED: run storage budget exhausted`
+     * and the engine escalates the run.
+     */
+    async writeArtifactFile(runId, rel, text) {
+        const path = this.runFile(runId, `artifacts/${safeRelative(rel)}`);
+        return this.mutex.run(async () => {
+            const cache = await this.ensureCache(runId);
+            this.assertWritable(runId, cache);
+            const used = cache.artifactBytes ?? (await this.measureArtifacts(runId));
+            const bytes = Buffer.byteLength(text);
+            const previous = await this.fs.stat(path).then((s) => s.size, () => 0);
+            const total = used - previous + bytes;
+            if (total > GOV_LIMITS.artifactBytesPerRun) {
+                cache.artifactBytes = used;
+                return {
+                    ok: false,
+                    exhausted: true,
+                    message: 'NOT ACCEPTED: run storage budget exhausted',
+                };
+            }
+            await this.atomic(path, text);
+            cache.artifactBytes = total;
+            return { ok: true, bytes, totalBytes: total };
+        });
+    }
+    async measureArtifacts(runId) {
+        const walk = async (dir) => {
+            let sum = 0;
+            for (const name of await this.fs.readdir(dir).catch(() => [])) {
+                const stat = await this.fs.stat(join(dir, name)).catch(() => null);
+                if (!stat)
+                    continue;
+                sum += stat.isDirectory() ? await walk(join(dir, name)) : stat.size;
+            }
+            return sum;
+        };
+        return walk(this.runFile(runId, 'artifacts'));
+    }
+    // -------------------------------------------------------------------------
+    // Index, listing, pruning
+    // -------------------------------------------------------------------------
+    get indexPath() {
+        return join(this.root, 'index.jsonl');
+    }
+    async appendIndexUnlocked(state, digest) {
+        const entry = {
+            runId: state.runId,
+            cwd: state.cwd,
+            ...(state.sessionId ? { sessionId: state.sessionId } : {}),
+            goal: state.goal,
+            status: state.status,
+            createdAt: state.createdAt,
+            updatedAt: state.updatedAt,
+            ...(digest !== undefined ? { digest } : {}),
+        };
+        await appendLineFsync(this.indexPath, JSON.stringify(entry), { fs: this.fs });
+        const cache = this.caches.get(state.runId);
+        if (cache) {
+            cache.indexedStatus = state.status;
+            cache.indexedDigest = digest === undefined ? null : JSON.stringify(digest);
+        }
+    }
+    async readIndexUnlocked() {
+        const text = await this.fs.readFile(this.indexPath).catch(() => '');
+        const latest = new Map();
+        for (const line of text.split('\n')) {
+            if (line.trim() === '')
+                continue;
+            try {
+                const row = JSON.parse(line);
+                if (typeof row.runId === 'string' && RUN_ID_PATTERN.test(row.runId)) {
+                    const digest = parseRunDigest(row.digest);
+                    // A hand-edited or damaged digest is dropped, never trusted: the row still lists.
+                    const { digest: _raw, ...rest } = row;
+                    latest.set(row.runId, digest === undefined ? rest : { ...rest, digest });
+                }
+            }
+            catch {
+                // A torn index row is skipped; the run folder is still on disk.
+            }
+        }
+        return [...latest.values()];
+    }
+    /** Latest row per run, newest first. */
+    async listRuns() {
+        const rows = await this.readIndexUnlocked();
+        return rows.sort((a, b) => b.updatedAt - a.updatedAt);
+    }
+    /**
+     * Newest run of ANY status for `cwd` whose folder still exists. `/gov report` uses this
+     * rather than `latestResumable`: the report people ask for most is the one of the run
+     * that just closed, and a closed run is by definition not resumable.
+     */
+    async latestForCwd(cwd) {
+        const wanted = normalizeCwd(cwd, this.platform);
+        for (const row of await this.listRuns()) {
+            if (normalizeCwd(row.cwd, this.platform) !== wanted)
+                continue;
+            const present = await this.fs.stat(this.runDir(row.runId)).then(() => true, () => false);
+            if (present)
+                return row;
+        }
+        return null;
+    }
+    /** Newest unfinished run for `cwd` whose folder still exists. */
+    async latestResumable(cwd) {
+        const wanted = normalizeCwd(cwd, this.platform);
+        for (const row of await this.listRuns()) {
+            if (TERMINAL.has(row.status))
+                continue;
+            if (normalizeCwd(row.cwd, this.platform) !== wanted)
+                continue;
+            const present = await this.fs.stat(this.runDir(row.runId)).then(() => true, () => false);
+            if (present)
+                return row;
+        }
+        return null;
+    }
+    /**
+     * Delete closed / abandoned runs older than the retention window. Best effort and
+     * bounded (`pruneMaxPerPass`); a locked run is never touched. Never throws.
+     */
+    async pruneOld() {
+        const result = { pruned: [], skippedLocked: [], failed: [] };
+        try {
+            await this.mutex.run(() => this.pruneUnlocked(result));
+        }
+        catch {
+            // Pruning is housekeeping: a failure here must never reach the user.
+        }
+        return result;
+    }
+    async pruneUnlocked(result) {
+        const cutoff = this.now() - GOV_LIMITS.retentionDays * DAY_MS;
+        const rows = await this.readIndexUnlocked();
+        const candidates = rows
+            .filter((row) => TERMINAL.has(row.status) && row.updatedAt < cutoff)
+            .sort((a, b) => a.updatedAt - b.updatedAt)
+            .slice(0, GOV_LIMITS.pruneMaxPerPass);
+        for (const row of candidates) {
+            if (await this.isRunLocked(row.runId)) {
+                result.skippedLocked.push(row.runId);
+                continue;
+            }
+            try {
+                await this.fs.rm(this.runDir(row.runId), { recursive: true, force: true });
+                this.caches.delete(row.runId);
+                result.pruned.push(row.runId);
+            }
+            catch {
+                result.failed.push(row.runId);
+            }
+        }
+        if (result.pruned.length === 0)
+            return;
+        const gone = new Set(result.pruned);
+        const kept = rows.filter((row) => !gone.has(row.runId));
+        const text = kept.map((row) => JSON.stringify(row)).join('\n');
+        await this.atomic(this.indexPath, text === '' ? '' : `${text}\n`);
+    }
+    // -------------------------------------------------------------------------
+    // Internals
+    // -------------------------------------------------------------------------
+    atomic(path, data) {
+        return atomicWriteFile(path, data, {
+            fs: this.fs,
+            platform: this.platform,
+            ...(this.sleep ? { sleep: this.sleep } : {}),
+        });
+    }
+    freshCache(lastSeq) {
+        return {
+            lastSeq,
+            eventsBytes: 0,
+            tornTail: false,
+            compacted: false,
+            droppedRows: 0,
+            artifactBytes: null,
+            readOnly: false,
+            indexedStatus: null,
+            indexedDigest: null,
+        };
+    }
+    assertWritable(runId, cache) {
+        if (cache.readOnly) {
+            throw new GovStoreError('READ_ONLY', `run ${runId} was written by a newer CLI version and is read-only here`);
+        }
+    }
+    /** Lazily derive the tail seq / byte count from disk, once per run per process. */
+    async ensureCache(runId) {
+        const known = this.caches.get(runId);
+        if (known)
+            return known;
+        const parsed = await this.parseEvents(runId);
+        const existing = this.caches.get(runId);
+        if (existing)
+            return existing;
+        const cache = this.freshCache(parsed.lastSeq);
+        cache.eventsBytes = parsed.bytes;
+        cache.tornTail = parsed.tornTail;
+        cache.compacted = parsed.hasCompacted;
+        this.caches.set(runId, cache);
+        return cache;
+    }
+}
+function finiteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}
+/** Validate an index row's digest field; anything malformed reads as "no digest". */
+export function parseRunDigest(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return undefined;
+    const d = raw;
+    const health = d.health === null ? null : d.health;
+    const costUsd = d.costUsd === null ? null : d.costUsd;
+    const ok = finiteNumber(d.phase) && finiteNumber(d.phaseCount) && finiteNumber(d.agents) &&
+        finiteNumber(d.tokens) && finiteNumber(d.dispatches) && finiteNumber(d.eliminations) &&
+        (health === null || finiteNumber(health)) && (costUsd === null || finiteNumber(costUsd));
+    if (!ok)
+        return undefined;
+    return {
+        phase: d.phase,
+        phaseCount: d.phaseCount,
+        agents: d.agents,
+        health: health,
+        tokens: d.tokens,
+        costUsd: costUsd,
+        dispatches: d.dispatches,
+        eliminations: d.eliminations,
+    };
+}
+function defaultSuffix() {
+    const alphabet = 'abcdefghijklmnopqrstuvwxyz0123456789';
+    let out = '';
+    for (let i = 0; i < 3; i++)
+        out += alphabet[Math.floor(Math.random() * alphabet.length)];
+    return out;
+}

package/dist/governance/store/scoreboard-export.d.ts

@@ -0,0 +1,53 @@
+/**
+ * One-way export of the ledger in the `token_ledger.py` v2.0 field layout
+ * (governance-mode section 12.3).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * The point is that a user can point the reference skill's scripts at
+ * `scoreboard.json` for ad-hoc analysis. It is NEVER read back: the ledger of record is
+ * `events.jsonl` (+ `ledger.json`), and a second readable copy would be a second source
+ * of truth that could drift. Python's vocabulary only knows `provisional` and
+ * `confirmed` as history statuses, so `immediate` positives (which land in `confirmed`,
+ * RV-9) are exported as `confirmed`.
+ */
+import type { LedgerState } from '../types.js';
+export declare const SCOREBOARD_VERSION = "2.0";
+interface ScoreboardHistoryRow {
+    event: string;
+    delta: number;
+    status: 'provisional' | 'confirmed';
+    balance_after: number;
+    confirmed_after: number;
+    provisional_after: number;
+    reason: string;
+    timestamp: string;
+}
+interface ScoreboardEscrowRow {
+    action: 'hold' | 'confirm' | 'clawback';
+    phase: number;
+    delta: number;
+    reason: string;
+    timestamp: string;
+}
+export interface ScoreboardAgent {
+    role: string;
+    generation: number;
+    tokens: number;
+    tokens_confirmed: number;
+    tokens_provisional: number;
+    status: 'active' | 'eliminated';
+    replaced_by: string | null;
+    history: ScoreboardHistoryRow[];
+    escrow_history: ScoreboardEscrowRow[];
+}
+export interface ScoreboardFile {
+    version: string;
+    generated_by: string;
+    generated_at: string;
+    agents: Record<string, ScoreboardAgent>;
+    phase_reports: unknown[];
+}
+/** Build the export document. Pure: `now` is injected so the output is reproducible. */
+export declare function buildScoreboard(ledger: LedgerState, now: number): ScoreboardFile;
+export {};