looply-cli 0.0.0-stage → 0.3.0

package/dist/goal-runs.d.ts

@@ -0,0 +1,82 @@
+import { type AnyEvent, type RoundReport } from '@looply/core';
+import { type RunRegistry } from './workspace';
+/**
+ * EACH RUN OF A GOAL, FROM THE LEDGERS THIS MACHINE HOLDS (M5-4).
+ *
+ * A run writes its ledger where it ran: the project's own `.looply/state` for
+ * a run started in the main checkout, and a placed run's workspace for one the
+ * machine provisioned (M4). Nothing on the machine ever read those ledgers BY
+ * GOAL — `looply report` folds one file, and the goal view (M5-3) said "each
+ * round's account is in the run's own ledger". This file finds the ledgers,
+ * folds each run of one goal with the very fold `looply report` and the
+ * phone's run report use (core `runReport`), and names the runs whose ledger
+ * is no longer here.
+ *
+ * READ-ONLY, like the view it serves: it lists directories and reads files,
+ * and the spec pins that it does nothing else. It walks exactly two places —
+ * the project state and this project's checkouts under
+ * `~/.looply/workspaces` — never the rest of the disk.
+ *
+ * The fold is not re-implemented: a run's events are handed to `runReport`
+ * with the ledger's item events (titles), so the rounds, outcomes, totals and
+ * the implementer's note — M2-4's `touched:` account first — are the same
+ * text a person sees in `looply report`.
+ */
+export interface LedgerPlace {
+    /** The `events.jsonl` file. */
+    readonly path: string;
+    /** The state directory it sits in — what a `LedgerStore` or a replay is built on. */
+    readonly dir: string;
+    /** `retired`: the records the reaper moved to `<project state>/retired/<run>/` when it removed a died run's checkout (M4-4). */
+    readonly where: 'project' | 'workspace' | 'retired';
+    /** `project`, the checkout's path, or the retired records' path. */
+    readonly label: string;
+}
+/**
+ * The ledgers this machine holds for a project: the project's own, the records
+ * the reaper kept when it retired a died run's checkout, each registered run's,
+ * and every checkout under the project's workspaces root — de-duplicated by
+ * real path, so a registered run in a listed checkout is one ledger, not two.
+ * A path that does not exist is not a ledger.
+ */
+export declare function ledgersOn(projectStateDir: string, registry: RunRegistry, cwd: string, home?: string): LedgerPlace[];
+export interface LedgerRead {
+    readonly place: LedgerPlace;
+    readonly events: readonly AnyEvent[];
+    /** Lines that were not events — counted, never guessed at. */
+    readonly badLines: number;
+    /** Set when the file could not be read at all; `events` is then empty. */
+    readonly unreadable?: string;
+}
+export declare function readLedgers(places: readonly LedgerPlace[]): LedgerRead[];
+export interface GoalRun {
+    readonly runId: string;
+    readonly branch: string;
+    readonly startedAt: string;
+    readonly goalVersion: number | null;
+    readonly where: LedgerPlace['where'];
+    readonly label: string;
+    /** `null`: no `run.ended` on the ledger — still going, or the ledger was cut. */
+    readonly stopReason: string | null;
+    readonly rounds: readonly RoundReport[];
+    readonly totals: {
+        readonly rounds: number;
+        readonly committed: number;
+        readonly discarded: number;
+        readonly abandoned: number;
+    };
+}
+/**
+ * Every run of one goal across the ledgers read, oldest first. A run is its
+ * `run.started` naming the goal; its rounds are folded from its own events
+ * plus the ledger's item events (which carry the titles), by `runReport`.
+ */
+export declare function runsOf(ledgers: readonly LedgerRead[], goalId: string): GoalRun[];
+export interface RetiredRun {
+    readonly runId: string;
+    readonly branch: string;
+    readonly workspace: string;
+}
+/** Registered runs whose ledger is not on this machine any more — a stated absence each, never a guess at what they did. */
+export declare function retiredRunsOf(registry: RunRegistry): RetiredRun[];
+//# sourceMappingURL=goal-runs.d.ts.map

package/dist/goal-runs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"goal-runs.d.ts","sourceRoot":"","sources":["../src/goal-runs.ts"],"names":[],"mappings":"AAGA,OAAO,EAAyB,KAAK,QAAQ,EAAE,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAEtF,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,MAAM,WAAW,WAAW;IAC1B,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,qFAAqF;IACrF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,gIAAgI;IAChI,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,WAAW,GAAG,SAAS,CAAC;IACpD,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,eAAe,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,MAAkB,GAAG,WAAW,EAAE,CA2C9H;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,SAAS,QAAQ,EAAE,CAAC;IACrC,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,0EAA0E;IAC1E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,GAAG,UAAU,EAAE,CAWxE;AAED,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,iFAAiF;IACjF,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,CAAC;IACxC,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CAClI;AAED;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,EAAE,CAsBhF;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,4HAA4H;AAC5H,wBAAgB,aAAa,CAAC,QAAQ,EAAE,WAAW,GAAG,UAAU,EAAE,CAMjE"}

package/dist/goal-runs.js

@@ -0,0 +1,120 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ledgersOn = ledgersOn;
+exports.readLedgers = readLedgers;
+exports.runsOf = runsOf;
+exports.retiredRunsOf = retiredRunsOf;
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const core_1 = require("@looply/core");
+const git_driver_1 = require("./git-driver");
+const workspace_1 = require("./workspace");
+/**
+ * The ledgers this machine holds for a project: the project's own, the records
+ * the reaper kept when it retired a died run's checkout, each registered run's,
+ * and every checkout under the project's workspaces root — de-duplicated by
+ * real path, so a registered run in a listed checkout is one ledger, not two.
+ * A path that does not exist is not a ledger.
+ */
+function ledgersOn(projectStateDir, registry, cwd, home = (0, node_os_1.homedir)()) {
+    const seen = new Set();
+    const out = [];
+    const add = (dir, where, label) => {
+        const path = (0, node_path_1.join)(dir, 'events.jsonl');
+        if (!(0, node_fs_1.existsSync)(path))
+            return;
+        let key;
+        try {
+            key = (0, node_fs_1.realpathSync)(path).toLowerCase();
+        }
+        catch {
+            key = path.toLowerCase();
+        }
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        out.push({ path, dir, where, label });
+    };
+    add(projectStateDir, 'project', 'project');
+    let kept;
+    try {
+        kept = (0, node_fs_1.readdirSync)((0, node_path_1.join)(projectStateDir, 'retired'));
+    }
+    catch {
+        kept = [];
+    }
+    for (const name of [...kept].sort()) {
+        const dir = (0, node_path_1.join)(projectStateDir, 'retired', name);
+        add(dir, 'retired', dir);
+    }
+    for (const live of registry.list()) {
+        if (!('record' in live))
+            continue;
+        add(live.record.stateDir, 'workspace', live.record.workspace);
+    }
+    const root = (0, workspace_1.workspacesRoot)(cwd, home);
+    let names;
+    try {
+        names = (0, node_fs_1.readdirSync)(root);
+    }
+    catch {
+        names = [];
+    }
+    for (const name of [...names].sort()) {
+        const checkout = (0, node_path_1.join)(root, name);
+        add((0, node_path_1.join)(checkout, git_driver_1.STATE_DIR, 'state'), 'workspace', checkout);
+    }
+    return out;
+}
+function readLedgers(places) {
+    return places.map((place) => {
+        let text;
+        try {
+            text = (0, node_fs_1.readFileSync)(place.path, 'utf8');
+        }
+        catch (e) {
+            return { place, events: [], badLines: 0, unreadable: e.message };
+        }
+        const parsed = (0, core_1.parseLines)(text);
+        return { place, events: parsed.events, badLines: parsed.badLines.length };
+    });
+}
+/**
+ * Every run of one goal across the ledgers read, oldest first. A run is its
+ * `run.started` naming the goal; its rounds are folded from its own events
+ * plus the ledger's item events (which carry the titles), by `runReport`.
+ */
+function runsOf(ledgers, goalId) {
+    const out = [];
+    for (const { place, events } of ledgers) {
+        for (const e of events) {
+            if (e.kind !== 'run.started' || e.data.goalId !== goalId)
+                continue;
+            const id = e.data.runId;
+            const own = events.filter((x) => x.runId === id || x.kind === 'item.created' || x.kind === 'item.verified');
+            const report = (0, core_1.runReport)(own);
+            out.push({
+                runId: id,
+                branch: e.data.branch,
+                startedAt: e.ts,
+                goalVersion: e.data.goalVersion ?? null,
+                where: place.where,
+                label: place.label,
+                stopReason: report.live ? null : report.stopReason,
+                rounds: report.rounds,
+                totals: report.totals,
+            });
+        }
+    }
+    return out.sort((a, b) => a.startedAt.localeCompare(b.startedAt) || a.runId.localeCompare(b.runId));
+}
+/** Registered runs whose ledger is not on this machine any more — a stated absence each, never a guess at what they did. */
+function retiredRunsOf(registry) {
+    return registry
+        .list()
+        .flatMap((l) => ('record' in l ? [l.record] : []))
+        .filter((r) => !(0, node_fs_1.existsSync)((0, node_path_1.join)(r.stateDir, 'events.jsonl')))
+        .map((r) => ({ runId: r.runId, branch: r.branch, workspace: r.workspace }));
+}
+//# sourceMappingURL=goal-runs.js.map

package/dist/goal-runs.js.map

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

package/dist/goal-store.d.ts

@@ -0,0 +1,146 @@
+import { type Goal } from '@looply/core';
+import type { LedgerFs } from './ledger-store';
+/**
+ * What the server says this project's goals are — `goals.json` under the state dir.
+ *
+ * A MIRROR, not an authority. The server owns goal intent, this file is a copy,
+ * and nothing on the machine ever writes a goal back. That single fact settles
+ * most of the design questions a durable store usually raises: there is no
+ * merge, because there is no local edit; there is no conflict, because there is
+ * no second writer; and a whole-file replace is not a compromise but exactly
+ * right, because the server's answer IS the state.
+ *
+ * It is also why this is the first store here whose corrupt-file policy is
+ * DISCARD AND RE-PULL rather than a loud failure. `queue-store.ts` fails loudly
+ * because losing the queue loses curation somebody did by hand; every byte in
+ * this file costs one HTTP GET to rebuild, so killing an overnight daemon over
+ * it would be trading something valuable for something free. The policy in each
+ * store follows what its contents are worth, not a house preference.
+ *
+ * ONE WRITER: the daemon. These stores rewrite the whole file from an in-memory
+ * map, so a second writer does not race a row — it reverts the file to its own
+ * snapshot. Nothing else may call `replace`.
+ */
+/** Bumped only when the on-disk shape changes incompatibly. Read, not decorative. */
+export declare const GOAL_STORE_SCHEMA = 1;
+export interface GoalFile {
+    schema: number;
+    goals: Goal[];
+}
+/** Why a load produced nothing, so the caller can say which happened. */
+export type GoalLoad = 'ok' | 'absent' | 'discarded';
+/**
+ * What a locally-observed abandonment did to the mirror.
+ *
+ * Reported rather than swallowed so the daemon can say which happened, and so a
+ * test can tell "declined to move backwards" apart from "did nothing because it
+ * was already right".
+ */
+export type MirrorUpdate = 
+/** The row moved to abandoned at the command's version. */
+'applied'
+/** Already abandoned at that version or newer. */
+ | 'already'
+/** The mirror holds a NEWER row; left alone rather than rewound. */
+ | 'ahead'
+/** This mirror has never heard of the goal. Nothing invented. */
+ | 'absent';
+export declare class GoalStore {
+    private readonly stateDir;
+    private readonly fs;
+    /** Optional: a discarded mirror is worth saying once, not silently. */
+    private readonly log?;
+    /** Distinguishes two writes from ONE process; the pid distinguishes processes. */
+    private static writes;
+    private goals;
+    private loaded;
+    constructor(stateDir: string, fs: LedgerFs, 
+    /** Optional: a discarded mirror is worth saying once, not silently. */
+    log?: ((line: string) => void) | undefined);
+    private get path();
+    /**
+     * Read what is on disk.
+     *
+     * Anything unreadable, unparseable, wrongly shaped or of an unrecognised
+     * schema version is DISCARDED — treated as an empty mirror — and reported.
+     * Never a throw: this file is a cache of something the server can always be
+     * asked for again, and a daemon that dies over it has turned a free problem
+     * into an outage.
+     *
+     * An unknown `schema` is deliberately handled the same way. `cursor.json`
+     * declares a version field that nothing reads, so this is the first store
+     * where the field means anything; treating a future shape as corrupt lets an
+     * older build be downgraded onto a newer state dir and simply re-pull.
+     */
+    load(): Promise<GoalLoad>;
+    private readIn;
+    /**
+     * What the mirror says RIGHT NOW, without adopting it.
+     *
+     * `get()` answers from an array this process loaded once, which is correct
+     * for the hundred cheap questions a run asks of it and wrong for the one
+     * expensive question asked after several minutes have passed. An adaptive
+     * Start spends up to eight minutes inside a goal evaluation; if a person
+     * amended or abandoned the goal in that window and the daemon has since
+     * written the new mirror, comparing the frozen snapshot against a value taken
+     * from that same snapshot compares a thing to itself and can only ever agree.
+     * That is not a re-check, and an adversarial review proved it was not
+     * behaving as one.
+     *
+     * So this reads the file again, and deliberately does NOT adopt what it
+     * finds: no `this.goals`, no `this.loaded`, no write, not even the discard
+     * rewrite that `load()` performs. It is a question, not a state change, and a
+     * run holding the lease must not quietly become the mirror's second writer
+     * on its way to asking one.
+     *
+     * ONE read, so what comes back is one whole state of the file rather than
+     * fields sampled across two of them.
+     */
+    readFresh(): Promise<{
+        ok: true;
+        goals: Goal[];
+    } | {
+        ok: false;
+        because: string;
+    }>;
+    /**
+     * Take the server's answer as the new truth, whole.
+     *
+     * No merge and no diff: the argument IS the state. A goal the server no longer
+     * returns is gone from the mirror, which is what makes an abandoned goal
+     * disappear here without anything having to delete it.
+     */
+    replace(goals: readonly Goal[]): Promise<void>;
+    private write;
+    /**
+     * Record that a goal has been given up on.
+     *
+     * Written when THIS machine carries out the release the abandonment produced,
+     * so a Start still in flight for the old version cannot resolve against
+     * `active` and adopt work back into a goal nobody is pursuing. The server
+     * remains authoritative — the next pull overwrites this with the real row,
+     * which says the same thing — but the machine must not need the server to
+     * remember something it has already been told.
+     *
+     * A goal the mirror has never heard of is left alone rather than invented:
+     * an absent goal can never resolve to `bound` anyway.
+     */
+    markAbandoned(goalId: string, goalVersion: number): Promise<MirrorUpdate>;
+    private write1;
+    /** Everything the mirror holds, newest first as the server ordered it. */
+    all(): Goal[];
+    get(goalId: string): Goal | null;
+    /** Whether `load` has run. A store nobody loaded is empty for a different reason. */
+    isLoaded(): boolean;
+    size(): number;
+}
+/**
+ * Shape check for a goal off the wire or off disk.
+ *
+ * Deliberately structural and shallow, in the spirit of `isLooplyEvent`: it
+ * guards the fields the machine actually reads. A goal from a newer server with
+ * extra fields is kept — dropping it would make an older CLI go blind the day
+ * the server grows a column.
+ */
+export declare function isGoal(v: unknown): v is Goal;
+//# sourceMappingURL=goal-store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"goal-store.d.ts","sourceRoot":"","sources":["../src/goal-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,IAAI,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,qFAAqF;AACrF,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAEnC,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,IAAI,EAAE,CAAC;CACf;AAED,yEAAyE;AACzE,MAAM,MAAM,QAAQ,GAAG,IAAI,GAAG,QAAQ,GAAG,WAAW,CAAC;AAErD;;;;;;GAMG;AACH,MAAM,MAAM,YAAY;AACtB,2DAA2D;AACzD,SAAS;AACX,kDAAkD;GAChD,SAAS;AACX,oEAAoE;GAClE,OAAO;AACT,iEAAiE;GAC/D,QAAQ,CAAC;AAqCb,qBAAa,SAAS;IAQlB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,uEAAuE;IACvE,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC;IAVvB,kFAAkF;IAClF,OAAO,CAAC,MAAM,CAAC,MAAM,CAAK;IAE1B,OAAO,CAAC,KAAK,CAAc;IAC3B,OAAO,CAAC,MAAM,CAAS;gBAGJ,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,QAAQ;IAC7B,uEAAuE;IACtD,GAAG,CAAC,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,aAAA;IAG/C,OAAO,KAAK,IAAI,GAEf;IAED;;;;;;;;;;;;;OAaG;IACG,IAAI,IAAI,OAAO,CAAC,QAAQ,CAAC;YAiBjB,MAAM;IA4BpB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,SAAS,IAAI,OAAO,CAAC;QAAE,EAAE,EAAE,IAAI,CAAC;QAAC,KAAK,EAAE,IAAI,EAAE,CAAA;KAAE,GAAG;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAexF;;;;;;OAMG;IACG,OAAO,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;YAWtC,KAAK;IAenB;;;;;;;;;;;;OAYG;IACG,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;YAmCjE,MAAM;IAIpB,0EAA0E;IAC1E,GAAG,IAAI,IAAI,EAAE;IAIb,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAIhC,qFAAqF;IACrF,QAAQ,IAAI,OAAO;IAInB,IAAI,IAAI,MAAM;CAGf;AAED;;;;;;;GAOG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,IAAI,CAe5C"}

package/dist/goal-store.js

@@ -0,0 +1,294 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GoalStore = exports.GOAL_STORE_SCHEMA = void 0;
+exports.isGoal = isGoal;
+const core_1 = require("@looply/core");
+/**
+ * What the server says this project's goals are — `goals.json` under the state dir.
+ *
+ * A MIRROR, not an authority. The server owns goal intent, this file is a copy,
+ * and nothing on the machine ever writes a goal back. That single fact settles
+ * most of the design questions a durable store usually raises: there is no
+ * merge, because there is no local edit; there is no conflict, because there is
+ * no second writer; and a whole-file replace is not a compromise but exactly
+ * right, because the server's answer IS the state.
+ *
+ * It is also why this is the first store here whose corrupt-file policy is
+ * DISCARD AND RE-PULL rather than a loud failure. `queue-store.ts` fails loudly
+ * because losing the queue loses curation somebody did by hand; every byte in
+ * this file costs one HTTP GET to rebuild, so killing an overnight daemon over
+ * it would be trading something valuable for something free. The policy in each
+ * store follows what its contents are worth, not a house preference.
+ *
+ * ONE WRITER: the daemon. These stores rewrite the whole file from an in-memory
+ * map, so a second writer does not race a row — it reverts the file to its own
+ * snapshot. Nothing else may call `replace`.
+ */
+/** Bumped only when the on-disk shape changes incompatibly. Read, not decorative. */
+exports.GOAL_STORE_SCHEMA = 1;
+/**
+ * The mirror's bytes, checked. PURE, and shared by both readers.
+ *
+ * Extracted rather than duplicated because the two callers ask the same
+ * question for different reasons — one adopts the answer, one only looks — and
+ * two copies of a schema check are two copies that can disagree about what a
+ * valid mirror is.
+ */
+function parseMirror(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return { ok: false, because: 'the mirror is not readable JSON' };
+    }
+    const file = parsed;
+    if (typeof file !== 'object' || file === null || file.schema !== exports.GOAL_STORE_SCHEMA) {
+        return {
+            ok: false,
+            because: `the mirror is schema ${String(file?.schema)}, this build reads ${exports.GOAL_STORE_SCHEMA}`,
+        };
+    }
+    if (!Array.isArray(file.goals))
+        return { ok: false, because: 'the mirror has no goals array' };
+    // Row-level rather than file-level: one malformed goal from a newer server
+    // should cost that goal, not the whole mirror. Anything the shape check
+    // rejects is simply not carried forward — and the next pull replaces the
+    // file wholesale anyway.
+    const kept = file.goals.filter(isGoal);
+    return { ok: true, goals: kept, dropped: file.goals.length - kept.length };
+}
+class GoalStore {
+    stateDir;
+    fs;
+    log;
+    /** Distinguishes two writes from ONE process; the pid distinguishes processes. */
+    static writes = 0;
+    goals = [];
+    loaded = false;
+    constructor(stateDir, fs, 
+    /** Optional: a discarded mirror is worth saying once, not silently. */
+    log) {
+        this.stateDir = stateDir;
+        this.fs = fs;
+        this.log = log;
+    }
+    get path() {
+        return `${this.stateDir}/goals.json`;
+    }
+    /**
+     * Read what is on disk.
+     *
+     * Anything unreadable, unparseable, wrongly shaped or of an unrecognised
+     * schema version is DISCARDED — treated as an empty mirror — and reported.
+     * Never a throw: this file is a cache of something the server can always be
+     * asked for again, and a daemon that dies over it has turned a free problem
+     * into an outage.
+     *
+     * An unknown `schema` is deliberately handled the same way. `cursor.json`
+     * declares a version field that nothing reads, so this is the first store
+     * where the field means anything; treating a future shape as corrupt lets an
+     * older build be downgraded onto a newer state dir and simply re-pull.
+     */
+    async load() {
+        const outcome = await this.readIn();
+        // "Discard and re-pull" has to be true of the DISK, not of a field nobody
+        // reads. Leaving the bad bytes in place meant a daemon that started corrupt
+        // and stayed offline kept them for ever, and the next process re-discovered
+        // the same damage — the invariant held in memory and nowhere else.
+        if (outcome === 'discarded') {
+            try {
+                await this.write([]);
+            }
+            catch {
+                // Best-effort. A mirror that cannot be rewritten is still discarded in
+                // memory, and the next successful pull replaces it wholesale anyway.
+            }
+        }
+        return outcome;
+    }
+    async readIn() {
+        this.loaded = true;
+        let text;
+        try {
+            text = await this.fs.readFile(this.path);
+        }
+        catch (e) {
+            this.goals = [];
+            this.log?.(`goals  : could not read the mirror (${e.message}) — will re-pull`);
+            return 'discarded';
+        }
+        if (text === null) {
+            this.goals = [];
+            return 'absent';
+        }
+        const parsed = parseMirror(text);
+        if (!parsed.ok) {
+            this.goals = [];
+            this.log?.(`goals  : ${parsed.because} — discarding it and re-pulling`);
+            return 'discarded';
+        }
+        if (parsed.dropped > 0) {
+            this.log?.(`goals  : ignored ${parsed.dropped} unreadable goal(s) in the mirror`);
+        }
+        this.goals = parsed.goals;
+        return 'ok';
+    }
+    /**
+     * What the mirror says RIGHT NOW, without adopting it.
+     *
+     * `get()` answers from an array this process loaded once, which is correct
+     * for the hundred cheap questions a run asks of it and wrong for the one
+     * expensive question asked after several minutes have passed. An adaptive
+     * Start spends up to eight minutes inside a goal evaluation; if a person
+     * amended or abandoned the goal in that window and the daemon has since
+     * written the new mirror, comparing the frozen snapshot against a value taken
+     * from that same snapshot compares a thing to itself and can only ever agree.
+     * That is not a re-check, and an adversarial review proved it was not
+     * behaving as one.
+     *
+     * So this reads the file again, and deliberately does NOT adopt what it
+     * finds: no `this.goals`, no `this.loaded`, no write, not even the discard
+     * rewrite that `load()` performs. It is a question, not a state change, and a
+     * run holding the lease must not quietly become the mirror's second writer
+     * on its way to asking one.
+     *
+     * ONE read, so what comes back is one whole state of the file rather than
+     * fields sampled across two of them.
+     */
+    async readFresh() {
+        let text;
+        try {
+            text = await this.fs.readFile(this.path);
+        }
+        catch (e) {
+            return { ok: false, because: `the goal mirror could not be read (${e.message})` };
+        }
+        // Absent is NOT an empty mirror here. `load()` may treat it as one because
+        // a pull will fill it; a run asking whether its authority still stands must
+        // not read "the file is missing" as "nothing has changed".
+        if (text === null)
+            return { ok: false, because: 'there is no goal mirror on this machine' };
+        const parsed = parseMirror(text);
+        return parsed.ok ? { ok: true, goals: parsed.goals } : { ok: false, because: parsed.because };
+    }
+    /**
+     * Take the server's answer as the new truth, whole.
+     *
+     * No merge and no diff: the argument IS the state. A goal the server no longer
+     * returns is gone from the mirror, which is what makes an abandoned goal
+     * disappear here without anything having to delete it.
+     */
+    async replace(goals) {
+        const next = goals.filter(isGoal);
+        await this.write(next);
+        // Committed to memory only AFTER the durable write. The other order leaves
+        // this object ahead of the file when a write fails — the caller is told the
+        // mirror could not be written, while `all()` cheerfully returns the goals
+        // that never landed, and nothing can tell the two states apart afterwards.
+        this.goals = next;
+        this.loaded = true;
+    }
+    async write(goals) {
+        const body = { schema: exports.GOAL_STORE_SCHEMA, goals: [...goals] };
+        await this.fs.mkdir(this.stateDir);
+        // Temp-then-rename, like every other store here: a half-written mirror read
+        // by the next process is worse than no mirror, because it looks like data.
+        // The temp name is PRIVATE TO THIS WRITER. A shared `goals.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.path}.${process.pid}.${(GoalStore.writes += 1)}.tmp`;
+        await this.fs.writeFile(tmp, JSON.stringify(body, null, 2) + '\n');
+        await this.fs.rename(tmp, this.path);
+    }
+    /**
+     * Record that a goal has been given up on.
+     *
+     * Written when THIS machine carries out the release the abandonment produced,
+     * so a Start still in flight for the old version cannot resolve against
+     * `active` and adopt work back into a goal nobody is pursuing. The server
+     * remains authoritative — the next pull overwrites this with the real row,
+     * which says the same thing — but the machine must not need the server to
+     * remember something it has already been told.
+     *
+     * A goal the mirror has never heard of is left alone rather than invented:
+     * an absent goal can never resolve to `bound` anyway.
+     */
+    async markAbandoned(goalId, goalVersion) {
+        const local = this.goals.find((g) => g.id === goalId);
+        // Never invented. An absent goal cannot resolve to `bound` anyway, so
+        // there is nothing to defend against and nothing to fabricate.
+        if (!local)
+            return 'absent';
+        if (local.version > goalVersion) {
+            // The mirror is AHEAD of what this command proves. A later server row has
+            // already been pulled, and writing this one over it would move the mirror
+            // backwards — turning a server-authoritative file into a guess. The goal
+            // is abandoned either way; the newer row already says so or says something
+            // truer.
+            return 'ahead';
+        }
+        if (local.version === goalVersion) {
+            // Same row. The command proves it is abandoned; anything else here is a
+            // mirror that disagrees with the transition that produced the command.
+            if (local.state === 'abandoned')
+                return 'already';
+            await this.write1(goalId, { state: 'abandoned', version: goalVersion });
+            return 'applied';
+        }
+        // Behind. The command is durable server-generated proof that the
+        // abandonment happened AT this version, so both fields move together — the
+        // one thing that must never happen is `abandoned` stamped against an older
+        // version, which is a row no server ever wrote and which every version
+        // comparison downstream would then read wrongly.
+        //
+        // Only these two fields move. Anything else on the row stays as the last
+        // real pull left it, and the next whole-file refresh replaces all of it.
+        await this.write1(goalId, { state: 'abandoned', version: goalVersion });
+        return 'applied';
+    }
+    async write1(goalId, fields) {
+        await this.replace(this.goals.map((g) => (g.id === goalId ? { ...g, ...fields } : g)));
+    }
+    /** Everything the mirror holds, newest first as the server ordered it. */
+    all() {
+        return [...this.goals];
+    }
+    get(goalId) {
+        return this.goals.find((g) => g.id === goalId) ?? null;
+    }
+    /** Whether `load` has run. A store nobody loaded is empty for a different reason. */
+    isLoaded() {
+        return this.loaded;
+    }
+    size() {
+        return this.goals.length;
+    }
+}
+exports.GoalStore = GoalStore;
+/**
+ * Shape check for a goal off the wire or off disk.
+ *
+ * Deliberately structural and shallow, in the spirit of `isLooplyEvent`: it
+ * guards the fields the machine actually reads. A goal from a newer server with
+ * extra fields is kept — dropping it would make an older CLI go blind the day
+ * the server grows a column.
+ */
+function isGoal(v) {
+    if (typeof v !== 'object' || v === null)
+        return false;
+    const g = v;
+    return (typeof g['id'] === 'string' &&
+        typeof g['projectId'] === 'string' &&
+        typeof g['text'] === 'string' &&
+        (0, core_1.isGoalState)(g['state']) &&
+        typeof g['version'] === 'number' &&
+        Number.isInteger(g['version']) &&
+        typeof g['clientRef'] === 'string' &&
+        typeof g['createdBy'] === 'string' &&
+        typeof g['createdAt'] === 'string' &&
+        typeof g['updatedAt'] === 'string');
+}
+//# sourceMappingURL=goal-store.js.map