looply-cli 0.0.0-stage → 0.2.0

package/dist/ledger-replay.d.ts

@@ -0,0 +1,115 @@
+import { type AnyEvent } from '@looply/core';
+import type { LedgerFs } from './ledger-store';
+/**
+ * Sending the server what a previous process never managed to.
+ *
+ * The ledger on disk is the record; the server is a mirror that may lag. Until
+ * now the lag could be permanent: acknowledged heads lived in memory, so a run
+ * that exited with events still buffered — or one that was killed — left them
+ * on disk with nothing that would ever look at them again. `looply report` had
+ * the whole run and the phone had a hole in it.
+ *
+ * Replay closes that by doing the obvious thing: read the ledger, skip what a
+ * durable cursor proves the server holds, and hand the rest to the uploader in
+ * its normal order. Nothing here mints ids, renumbers, or rewrites an event —
+ * a replayed event is byte-for-byte the original, which is what lets ingest
+ * recognise it by `(runId, seq)` and answer "duplicate" instead of storing it
+ * twice. That idempotency is why replaying too much is safe and replaying too
+ * little is not.
+ */
+export interface ReplaySink {
+    enqueue(event: AnyEvent): void;
+    durableHead(runId: string): number;
+}
+export interface ReplayResult {
+    /** Events handed to the uploader. */
+    replayed: number;
+    /** Events the cursor showed were already held. */
+    skipped: number;
+    /** Ledger lines too damaged to parse. Reported, never fatal. */
+    damaged: number;
+    /**
+     * Ledger lines that ARE events, naming a kind this build has no name for.
+     *
+     * Not damaged, and counted apart from M8-12: the uploader cannot send what it
+     * cannot type, but there is nothing torn and nothing to repair — the line was
+     * written by a newer looply.
+     */
+    fromNewerBuild: number;
+}
+/**
+ * How many events to hand over in one pass.
+ *
+ * A machine that was offline all night can have a very long ledger, and the
+ * uploader's buffer sheds the oldest when it overflows — so pouring the whole
+ * backlog in at once would drop the beginning of the very history we are trying
+ * to restore. Bounded per pass, the daemon simply replays again on its next
+ * tick until there is nothing left.
+ */
+export declare const DEFAULT_REPLAY_LIMIT = 1000;
+export declare function replayLedger(stateDir: string, fs: LedgerFs, sink: ReplaySink, limit?: number): Promise<ReplayResult>;
+/**
+ * A replay the daemon can afford to ask for on every tick.
+ *
+ * `replayLedger` reads and parses the whole ledger. That is the right thing to
+ * do when there is something to send and pure waste when there is not — and on
+ * an idle machine there never is. Measured on this machine: roughly 11 ms and
+ * 2.3 MiB per pass at ten thousand events, 204 ms and 46 MiB at two hundred
+ * thousand. Every five seconds, for ever, because `events.jsonl` is append-only
+ * and nothing rotates it.
+ *
+ * So the pass is skipped when the ledger cannot possibly hold anything new.
+ * `LedgerStore.append` is its only writer and it only ever appends, which makes
+ * the byte count a signal that changes exactly when the contents do — and a
+ * stat costs about 25 microseconds against the read's tens of milliseconds.
+ *
+ * Two conditions do the load-bearing work, and both are easy to get wrong:
+ *
+ * The size is taken **before** the read, not after. A size read afterwards
+ * could include an event appended while we were parsing, and remembering it
+ * would skip that event for ever. Taken first, the read is guaranteed to have
+ * covered at least those bytes, so the worst this can cause is one redundant
+ * pass.
+ *
+ * The guard is armed only by a pass that replayed **nothing**. A pass that
+ * stopped at the limit, or one whose events the uploader later shed, has work
+ * outstanding that the file's size says nothing about — and skipping the next
+ * pass would strand exactly the tail this mechanism exists to recover.
+ *
+ * This is what the daemon's old `replayDone` should have been: a re-armable
+ * memo of the size at which the file was last proved covered, rather than a
+ * terminal state. That flag memoised "covered" against nothing, so nothing
+ * could ever invalidate it.
+ */
+export declare function makeLedgerReplay(stateDir: string, fs: LedgerFs, limit?: number): (sink: ReplaySink) => Promise<ReplayResult>;
+/**
+ * EVERY LEDGER THE MACHINE HOLDS (M5-6).
+ *
+ * The replay above reads ONE file — the project's ledger. A placed run writes
+ * its ledger in its own checkout (M4), and the reaper keeps a died run's
+ * records under `retired/` (M4-4); until now those reached the server by
+ * nobody, and the measurement said so on every such ledger. This replays each
+ * place the caller lists — the same list `looply goal` reads — through the
+ * same sink and the same per-run cursor: a run lives on one ledger, so a
+ * cursor per run is a cursor per ledger, and nothing is sent twice.
+ *
+ * Re-listed on every pass, so a checkout provisioned or retired an hour into
+ * the night is picked up. One `makeLedgerReplay` per directory, memoised, so
+ * each file keeps its own byte-size latch; a place that vanishes drops its
+ * memo. The pass limit is SHARED: what one ledger sends is what the next may
+ * still send, so one busy ledger cannot pour the uploader's buffer full and
+ * shed the others' history. A ledger whose read throws is skipped for the pass
+ * and named once — the others still ship — and asked again next pass; it can
+ * never be the reason another ledger's events are missed.
+ */
+export interface LedgerPlaceToReplay {
+    /** The state directory the ledger sits in. */
+    readonly dir: string;
+    /** How to name it in a log line. */
+    readonly label: string;
+}
+export declare function makeLedgersReplay(places: () => readonly LedgerPlaceToReplay[], fs: LedgerFs, opts?: {
+    limit?: number;
+    log?: (line: string) => void;
+}): (sink: ReplaySink) => Promise<ReplayResult>;
+//# sourceMappingURL=ledger-replay.d.ts.map

package/dist/ledger-replay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger-replay.d.ts","sourceRoot":"","sources":["../src/ledger-replay.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,KAAK,QAAQ,EAAE,MAAM,cAAc,CAAC;AACrE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,WAAW,UAAU;IACzB,OAAO,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC/B,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;CACpC;AAED,MAAM,WAAW,YAAY;IAC3B,qCAAqC;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,kDAAkD;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,OAAQ,CAAC;AAE1C,wBAAsB,YAAY,CAChC,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,QAAQ,EACZ,IAAI,EAAE,UAAU,EAChB,KAAK,SAAuB,GAC3B,OAAO,CAAC,YAAY,CAAC,CAoCvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,QAAQ,EACZ,KAAK,SAAuB,GAC3B,CAAC,IAAI,EAAE,UAAU,KAAK,OAAO,CAAC,YAAY,CAAC,CA4B7C;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,mBAAmB;IAClC,8CAA8C;IAC9C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,oCAAoC;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,SAAS,mBAAmB,EAAE,EAC5C,EAAE,EAAE,QAAQ,EACZ,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CAAO,GAC1D,CAAC,IAAI,EAAE,UAAU,KAAK,OAAO,CAAC,YAAY,CAAC,CAmC7C"}

package/dist/ledger-replay.js

@@ -0,0 +1,155 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_REPLAY_LIMIT = void 0;
+exports.replayLedger = replayLedger;
+exports.makeLedgerReplay = makeLedgerReplay;
+exports.makeLedgersReplay = makeLedgersReplay;
+const core_1 = require("@looply/core");
+/**
+ * How many events to hand over in one pass.
+ *
+ * A machine that was offline all night can have a very long ledger, and the
+ * uploader's buffer sheds the oldest when it overflows — so pouring the whole
+ * backlog in at once would drop the beginning of the very history we are trying
+ * to restore. Bounded per pass, the daemon simply replays again on its next
+ * tick until there is nothing left.
+ */
+exports.DEFAULT_REPLAY_LIMIT = 1_000;
+async function replayLedger(stateDir, fs, sink, limit = exports.DEFAULT_REPLAY_LIMIT) {
+    // A ledger that cannot be read is not an empty ledger, and this used to
+    // return "nothing to replay" for both. That was survivable while the caller
+    // treated every quiet pass alike; it is not now, because `makeLedgerReplay`
+    // remembers the size at which a pass found nothing left to send. A read that
+    // failed — a lock, an exhausted fd table, a scanner holding the file open on
+    // Windows — would arm that memo against a file it never looked at, and the
+    // tail would then be skipped until something appended to it. So the failure
+    // is raised: the daemon catches it, says so once, and asks again next tick.
+    //
+    // `readFile` resolving to null is a different thing entirely — there is no
+    // ledger yet — and stays a quiet, armable zero.
+    const text = await fs.readFile(`${stateDir}/events.jsonl`);
+    if (text === null || text.length === 0)
+        return { replayed: 0, skipped: 0, damaged: 0, fromNewerBuild: 0 };
+    // Damage-tolerant, exactly as the ledger's own reader is: a process killed
+    // mid-append leaves a partial final line, and losing every durable event
+    // before it because the last one is short would be absurd.
+    const { events, badLines, fromNewerBuild } = (0, core_1.parseLines)(text);
+    let replayed = 0;
+    let skipped = 0;
+    // Ordered so the uploader receives a run's events in seq order and the
+    // durable head can advance one at a time rather than stalling on a gap it
+    // only appears to have.
+    for (const e of (0, core_1.sortEvents)(events)) {
+        if (e.seq <= sink.durableHead(e.runId)) {
+            skipped += 1;
+            continue;
+        }
+        if (replayed >= limit)
+            break;
+        sink.enqueue(e);
+        replayed += 1;
+    }
+    return { replayed, skipped, damaged: badLines.length, fromNewerBuild: fromNewerBuild.length };
+}
+/**
+ * A replay the daemon can afford to ask for on every tick.
+ *
+ * `replayLedger` reads and parses the whole ledger. That is the right thing to
+ * do when there is something to send and pure waste when there is not — and on
+ * an idle machine there never is. Measured on this machine: roughly 11 ms and
+ * 2.3 MiB per pass at ten thousand events, 204 ms and 46 MiB at two hundred
+ * thousand. Every five seconds, for ever, because `events.jsonl` is append-only
+ * and nothing rotates it.
+ *
+ * So the pass is skipped when the ledger cannot possibly hold anything new.
+ * `LedgerStore.append` is its only writer and it only ever appends, which makes
+ * the byte count a signal that changes exactly when the contents do — and a
+ * stat costs about 25 microseconds against the read's tens of milliseconds.
+ *
+ * Two conditions do the load-bearing work, and both are easy to get wrong:
+ *
+ * The size is taken **before** the read, not after. A size read afterwards
+ * could include an event appended while we were parsing, and remembering it
+ * would skip that event for ever. Taken first, the read is guaranteed to have
+ * covered at least those bytes, so the worst this can cause is one redundant
+ * pass.
+ *
+ * The guard is armed only by a pass that replayed **nothing**. A pass that
+ * stopped at the limit, or one whose events the uploader later shed, has work
+ * outstanding that the file's size says nothing about — and skipping the next
+ * pass would strand exactly the tail this mechanism exists to recover.
+ *
+ * This is what the daemon's old `replayDone` should have been: a re-armable
+ * memo of the size at which the file was last proved covered, rather than a
+ * terminal state. That flag memoised "covered" against nothing, so nothing
+ * could ever invalidate it.
+ */
+function makeLedgerReplay(stateDir, fs, limit = exports.DEFAULT_REPLAY_LIMIT) {
+    const path = `${stateDir}/events.jsonl`;
+    /** Bytes as of the last pass that proved the file fully covered; null re-reads. */
+    let coveredAtBytes = null;
+    // The limit may be handed in per pass (M5-6): when many ledgers share one
+    // pass, what one has already sent is what the next may still send.
+    return async (sink, passLimit = limit) => {
+        // A filesystem that cannot answer gets the full read every time: the guard
+        // is an optimisation and must never be the reason an event is missed.
+        const before = fs.size ? await fs.size(path).catch(() => null) : null;
+        if (before !== null && before === coveredAtBytes) {
+            return { replayed: 0, skipped: 0, damaged: 0, fromNewerBuild: 0 };
+        }
+        let r;
+        try {
+            r = await replayLedger(stateDir, fs, sink, passLimit);
+        }
+        catch (e) {
+            // Disarm before rethrowing. A pass that failed proved nothing about the
+            // file, and leaving a stale `coveredAtBytes` armed would let the *next*
+            // pass skip on a size this one never verified.
+            coveredAtBytes = null;
+            throw e;
+        }
+        coveredAtBytes = r.replayed === 0 ? before : null;
+        return r;
+    };
+}
+function makeLedgersReplay(places, fs, opts = {}) {
+    const limit = opts.limit ?? exports.DEFAULT_REPLAY_LIMIT;
+    const log = opts.log ?? (() => { });
+    const replays = new Map();
+    const named = new Set();
+    return async (sink) => {
+        const total = { replayed: 0, skipped: 0, damaged: 0, fromNewerBuild: 0 };
+        const listed = places();
+        const current = new Set(listed.map((p) => p.dir));
+        for (const dir of [...replays.keys()])
+            if (!current.has(dir))
+                replays.delete(dir);
+        let remaining = limit;
+        for (const place of listed) {
+            if (remaining <= 0)
+                break;
+            let replay = replays.get(place.dir);
+            if (replay === undefined) {
+                replay = makeLedgerReplay(place.dir, fs, limit);
+                replays.set(place.dir, replay);
+            }
+            try {
+                const r = await replay(sink, remaining);
+                total.replayed += r.replayed;
+                total.skipped += r.skipped;
+                total.damaged += r.damaged;
+                total.fromNewerBuild += r.fromNewerBuild;
+                remaining -= r.replayed;
+                named.delete(place.dir);
+            }
+            catch (e) {
+                if (!named.has(place.dir)) {
+                    named.add(place.dir);
+                    log(`daemon  : could not read the ledger at ${place.label} — ${e.message}; the others still ship, and it is asked again next pass`);
+                }
+            }
+        }
+        return total;
+    };
+}
+//# sourceMappingURL=ledger-replay.js.map

package/dist/ledger-replay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger-replay.js","sourceRoot":"","sources":["../src/ledger-replay.ts"],"names":[],"mappings":"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"}

package/dist/ledger-store.d.ts

@@ -0,0 +1,68 @@
+import { type AnyEvent, type EventKind, type LooplyEvent, type Status } from '@looply/core';
+/**
+ * The ledger writer — the only code that puts events on disk.
+ *
+ * Two files, two contracts. `events.jsonl` is append-only and is the truth;
+ * `status.json` is a projection rebuilt from it, rewritten via temp-then-rename
+ * so a concurrent reader (the `status` command, the daemon's poller) never sees
+ * half a file. All filesystem calls come through {@link LedgerFs}, so every
+ * behaviour here is testable without touching disk.
+ */
+export interface LedgerFs {
+    /** Resolves to null when the file does not exist. */
+    readFile(path: string): Promise<string | null>;
+    appendFile(path: string, data: string): Promise<void>;
+    writeFile(path: string, data: string): Promise<void>;
+    rename(from: string, to: string): Promise<void>;
+    /** Recursive; succeeds when the directory already exists. */
+    mkdir(path: string): Promise<void>;
+    /**
+     * The file's size in bytes, or null when it does not exist.
+     *
+     * Optional, because it buys speed and not correctness: a store that cannot
+     * answer simply pays for the whole read every time. `makeLedgerReplay` uses
+     * it to skip a pass over a ledger that cannot have grown — see the note on
+     * `append` below, which is what makes a byte count a sound signal here.
+     */
+    size?(path: string): Promise<number | null>;
+}
+/** An event as the caller hands it over: everything but `seq`, which the store owns. */
+export type AnyEventInput = {
+    [K in EventKind]: Omit<LooplyEvent<K>, 'seq'>;
+}[EventKind];
+export declare class LedgerStore {
+    private readonly stateDir;
+    private readonly fs;
+    /** Distinguishes two writes from ONE process; the pid distinguishes processes. */
+    private static writes;
+    private readonly nextSeq;
+    private status;
+    private opened;
+    constructor(stateDir: string, fs: LedgerFs);
+    private get eventsPath();
+    private get statusPath();
+    /**
+     * Replay whatever is on disk. Damaged lines are skipped, not fatal: a truncated
+     * final line is the normal consequence of a process dying mid-append, and the
+     * next seq must continue from the last line that survived.
+     */
+    open(): Promise<Status>;
+    /**
+     * Assign the next per-run seq, append the line, then rewrite the projection.
+     * Ledger first, projection second: if the process dies between the two, reopen
+     * rebuilds `status.json` from events — the other order cannot recover.
+     *
+     * ⚠️ This is the only writer of `events.jsonl` in the repository, and it only
+     * ever appends. `makeLedgerReplay` depends on that: it skips a pass when the
+     * file's byte count has not changed. Rotation, compaction or any in-place
+     * rewrite would make that guard unsound in the dangerous direction — a
+     * rewrite preserving the byte count would be invisible to it.
+     */
+    append(input: AnyEventInput): Promise<AnyEvent>;
+    /** The in-memory projection; identical to what `status.json` holds after each append. */
+    currentStatus(): Status;
+    private writeStatus;
+}
+/** The real filesystem, shaped to the injected interface. */
+export declare const nodeLedgerFs: LedgerFs;
+//# sourceMappingURL=ledger-store.d.ts.map

package/dist/ledger-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger-store.d.ts","sourceRoot":"","sources":["../src/ledger-store.ts"],"names":[],"mappings":"AACA,OAAO,EAKL,KAAK,QAAQ,EACb,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,MAAM,EACZ,MAAM,cAAc,CAAC;AAEtB;;;;;;;;GAQG;AAEH,MAAM,WAAW,QAAQ;IACvB,qDAAqD;IACrD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC/C,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,6DAA6D;IAC7D,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC;;;;;;;OAOG;IACH,IAAI,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC7C;AAED,wFAAwF;AACxF,MAAM,MAAM,aAAa,GAAG;KAAG,CAAC,IAAI,SAAS,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC;CAAE,CAAC,SAAS,CAAC,CAAC;AAEzF,qBAAa,WAAW;IASpB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,EAAE;IATrB,kFAAkF;IAClF,OAAO,CAAC,MAAM,CAAC,MAAM,CAAK;IAE1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;IACrD,OAAO,CAAC,MAAM,CAAyB;IACvC,OAAO,CAAC,MAAM,CAAS;gBAGJ,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,QAAQ;IAG/B,OAAO,KAAK,UAAU,GAErB;IAED,OAAO,KAAK,UAAU,GAErB;IAED;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;IAY7B;;;;;;;;;;OAUG;IACG,MAAM,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,QAAQ,CAAC;IAerD,yFAAyF;IACzF,aAAa,IAAI,MAAM;YAIT,WAAW;CAU1B;AAED,6DAA6D;AAC7D,eAAO,MAAM,YAAY,EAAE,QAuB1B,CAAC"}

package/dist/ledger-store.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nodeLedgerFs = exports.LedgerStore = void 0;
+const node_fs_1 = require("node:fs");
+const core_1 = require("@looply/core");
+class LedgerStore {
+    stateDir;
+    fs;
+    /** Distinguishes two writes from ONE process; the pid distinguishes processes. */
+    static writes = 0;
+    nextSeq = new Map();
+    status = (0, core_1.emptyStatus)();
+    opened = false;
+    constructor(stateDir, fs) {
+        this.stateDir = stateDir;
+        this.fs = fs;
+    }
+    get eventsPath() {
+        return `${this.stateDir}/events.jsonl`;
+    }
+    get statusPath() {
+        return `${this.stateDir}/status.json`;
+    }
+    /**
+     * Replay whatever is on disk. Damaged lines are skipped, not fatal: a truncated
+     * final line is the normal consequence of a process dying mid-append, and the
+     * next seq must continue from the last line that survived.
+     */
+    async open() {
+        await this.fs.mkdir(this.stateDir);
+        const text = await this.fs.readFile(this.eventsPath);
+        const events = text === null ? [] : (0, core_1.parseLines)(text).events;
+        for (const e of events) {
+            if (e.seq >= (this.nextSeq.get(e.runId) ?? 0))
+                this.nextSeq.set(e.runId, e.seq + 1);
+            this.status = (0, core_1.applyEvent)(this.status, e);
+        }
+        this.opened = true;
+        return this.status;
+    }
+    /**
+     * Assign the next per-run seq, append the line, then rewrite the projection.
+     * Ledger first, projection second: if the process dies between the two, reopen
+     * rebuilds `status.json` from events — the other order cannot recover.
+     *
+     * ⚠️ This is the only writer of `events.jsonl` in the repository, and it only
+     * ever appends. `makeLedgerReplay` depends on that: it skips a pass when the
+     * file's byte count has not changed. Rotation, compaction or any in-place
+     * rewrite would make that guard unsound in the dangerous direction — a
+     * rewrite preserving the byte count would be invisible to it.
+     */
+    async append(input) {
+        if (!this.opened) {
+            // Appending before replay would restart seq at 0 and corrupt the run's
+            // `(runId, seq)` uniqueness on disk. Fail loudly instead.
+            throw new Error('ledger: append() before open() — seq would restart and collide');
+        }
+        const seq = this.nextSeq.get(input.runId) ?? 0;
+        const event = { ...input, seq };
+        await this.fs.appendFile(this.eventsPath, (0, core_1.encodeLine)(event) + '\n');
+        this.nextSeq.set(input.runId, seq + 1);
+        this.status = (0, core_1.applyEvent)(this.status, event);
+        await this.writeStatus();
+        return event;
+    }
+    /** The in-memory projection; identical to what `status.json` holds after each append. */
+    currentStatus() {
+        return this.status;
+    }
+    async writeStatus() {
+        // The temp name is PRIVATE TO THIS WRITER. A shared `status.json.tmp` is
+        // two processes writing one path: the second truncates and rewrites what
+        // the first is midway through, and then both rename it into place. The
+        // rename is atomic and the file it renames is a splice of two writes, and
+        // nothing downstream can tell.
+        const tmp = `${this.statusPath}.${process.pid}.${(LedgerStore.writes += 1)}.tmp`;
+        await this.fs.writeFile(tmp, JSON.stringify(this.status, null, 2) + '\n');
+        await this.fs.rename(tmp, this.statusPath);
+    }
+}
+exports.LedgerStore = LedgerStore;
+/** The real filesystem, shaped to the injected interface. */
+exports.nodeLedgerFs = {
+    async readFile(path) {
+        try {
+            return await node_fs_1.promises.readFile(path, 'utf8');
+        }
+        catch (e) {
+            if (e.code === 'ENOENT')
+                return null;
+            throw e;
+        }
+    },
+    appendFile: (path, data) => node_fs_1.promises.appendFile(path, data, 'utf8'),
+    writeFile: (path, data) => node_fs_1.promises.writeFile(path, data, 'utf8'),
+    rename: (from, to) => node_fs_1.promises.rename(from, to),
+    async mkdir(path) {
+        await node_fs_1.promises.mkdir(path, { recursive: true });
+    },
+    async size(path) {
+        try {
+            return (await node_fs_1.promises.stat(path)).size;
+        }
+        catch (e) {
+            if (e.code === 'ENOENT')
+                return null;
+            throw e;
+        }
+    },
+};
+//# sourceMappingURL=ledger-store.js.map

package/dist/ledger-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger-store.js","sourceRoot":"","sources":["../src/ledger-store.ts"],"names":[],"mappings":"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"}

package/dist/loop-safety-observer.d.ts

@@ -0,0 +1,132 @@
+import { type AttemptOutcome, type ExcludedReason, type ProgressVector, type SafetyObservation } from '@looply/core';
+import { type Item } from '@looply/core';
+/**
+ * TURNING WHAT A RUN LEFT BEHIND INTO WHAT IT ACHIEVED.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * WHICH FACTS ARE REAL, AND WHICH ARE DELIBERATELY NOT INVENTED
+ *
+ * The pure `ProgressVector` has room for five kinds of achievement. This
+ * producer populates the three this architecture actually establishes, and
+ * leaves two empty ON PURPOSE — an empty array here means "this codebase does
+ * not record that", not "none of it happened", and the difference matters
+ * because a reader who assumed the second would think a passing gate had been
+ * ignored.
+ *
+ *   verifiedItemIds  REAL. An item reaches `done` on the COMMIT path only, and
+ *                    the commit path is reached only after the deterministic
+ *                    gate passes (`round-runner.ts`, `state: 'done'` is written
+ *                    immediately after `git.commit`). So item state already
+ *                    carries gate success.
+ *   workRemaining    REAL. Counted from item states through the same predicate
+ *                    the run itself uses to decide whether anything is pickable.
+ *   planRevision     REAL, and CARRIED RATHER THAN COUNTED — see the pure file.
+ *
+ *   passingGates     REAL SINCE PHASE 6, and the argument for leaving it empty
+ *                    had a hole. It said: "a gate only ever passes on the way
+ *                    to `done`, so a gate that went red→green has already moved
+ *                    `verifiedItemIds`." That is true of every round the gate
+ *                    ENDS — and false of the one that matters. A round whose
+ *                    gate goes GREEN and whose PROVER then refuses is
+ *                    discarded: the deterministic checks genuinely started
+ *                    passing, nothing moved to `done`, and the observation was
+ *                    identical to the round before it. So `no_progress` counted
+ *                    real progress as none, three times in a row, and held the
+ *                    pursuit.
+ *
+ *                    ⚠️ IT IS THE STEP NAMES, NOT A COUNT. A count cannot tell
+ *                    "the same two gates passed again" from "a different two
+ *                    passed", and the second is progress while the first is not.
+ *   provenCriteria   EMPTY. No deterministic per-criterion proof exists in this
+ *                    repository yet. Inventing a number here — a percentage, a
+ *                    model's own estimate — is precisely the thing the phase
+ *                    forbids, because it would make progress claimable.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * THE BOUNDARY IS HALF THE VALUE
+ *
+ * `observationFor` returns null for anything that could not have advanced the
+ * work. A person taking ten minutes over an approval is not ten failed
+ * attempts, and a governed execution being reconciled is one authority being
+ * carried out rather than a fresh try. Counting either would hold a pursuit for
+ * somebody else's lunch break.
+ */
+/** Items belonging to one pursuit. The caller has already narrowed by goal. */
+export interface PursuitItems {
+    readonly items: readonly Item[];
+    readonly planRevision: number;
+}
+/**
+ * The achievement facts, read off the queue.
+ *
+ * `done` is the only state that means an item was actually finished — the
+ * others are all "not yet" of one kind or another, and `workLeft` is the
+ * repository's own reading of what a set of them amounts to.
+ */
+export declare function vectorFor(goalId: string, goalVersion: number, pursuit: PursuitItems, passingGates?: readonly string[]): ProgressVector;
+export interface AttemptFacts {
+    readonly goalId: string;
+    readonly goalVersion: number;
+    readonly ordinal: number;
+    readonly runId: string;
+    readonly outcome: AttemptOutcome;
+    readonly pursuit: PursuitItems;
+    /**
+     * Gate steps that passed in this attempt, by name.
+     *
+     * ⚠️ ABSENT IS "NOT RECORDED", NOT "NONE PASSED". The run-level producer
+     * cannot say — a run summarises many rounds — so it omits this and the vector
+     * is exactly what it always was.
+     */
+    readonly passingGates?: readonly string[];
+    /**
+     * Every gate step that has EVER passed in this pursuit before now.
+     *
+     * 🔴 WITHOUT THIS, ONE FLAKY GATE STEP TURNS EVERY DETECTOR OFF.
+     *
+     * `passingGates` was folded into the progress fingerprint raw, and the
+     * argument for it is right as far as it goes: a round whose gate goes green
+     * and whose prover then refuses IS progress, and recording it as none held
+     * pursuits that were moving.
+     *
+     * But `noProgress` fires only on three IDENTICAL fingerprints in a row. A
+     * gate step that flickers — a timeout, a port already in use, a slow
+     * container — changes the set every round, so the fingerprint changes every
+     * round, so three identical ones never happen. MEASURED: two round facts
+     * differing ONLY in `passingGates` produce different fingerprints, and with
+     * one flapping step a genuinely stuck pursuit is never held by ANY of the
+     * four detectors, for ever.
+     *
+     * The fix is to make the contribution MONOTONE. Progress is the set GROWING —
+     * a step passing for the first time. A step that oscillates green-red-green
+     * adds nothing the second time, so the fingerprint settles and the detectors
+     * work again.
+     *
+     * ⚠️ ABSENT IS "THIS CALLER KEEPS NO HISTORY", which reproduces the old
+     * behaviour exactly. The run-level producer omits both fields.
+     */
+    readonly gatesEverPassed?: readonly string[];
+    readonly treeFingerprint: string | null;
+    readonly failureSignature: string | null;
+    readonly actionFingerprint: string | null;
+    /**
+     * Why this attempt does not count, or null when it does.
+     *
+     * 🔴 THE CALLER NAMES THE REASON; THIS FILE DOES NOT GUESS ONE. A producer
+     * that inferred "waiting" from the absence of work would eventually infer it
+     * wrongly, and the direction it fails in decides whether a person's lunch
+     * break becomes a safety incident.
+     */
+    readonly excluded: ExcludedReason | null;
+    readonly at: string;
+}
+/**
+ * One observation, or null when this attempt is not the model's to answer for.
+ *
+ * Null is the common case in a quiet daemon and is not a failure: a tick that
+ * held, an approval nobody has answered, a recovery carrying one authority
+ * forward. None of those is an attempt that achieved nothing — they are attempts
+ * that never happened.
+ */
+export declare function observationFor(facts: AttemptFacts): SafetyObservation | null;
+//# sourceMappingURL=loop-safety-observer.d.ts.map

package/dist/loop-safety-observer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop-safety-observer.d.ts","sourceRoot":"","sources":["../src/loop-safety-observer.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACvB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAY,KAAK,IAAI,EAAE,MAAM,cAAc,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAEH,+EAA+E;AAC/E,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CACvB,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,YAAY,EACrB,YAAY,GAAE,SAAS,MAAM,EAAO,GACnC,cAAc,CAsBhB;AAOD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAC;IACzC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,iBAAiB,GAAG,IAAI,CA+B5E"}