looply-cli 0.0.0-stage → 0.2.0

package/dist/exemption-store.js

@@ -0,0 +1,266 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExemptionStore = void 0;
+exports.grantKey = grantKey;
+exports.offerableFor = offerableFor;
+exports.grantsFromServer = grantsFromServer;
+/** Built, not typed: a literal NUL in source is an invisible control character,
+ *  and `source-hygiene.spec.ts` refuses those for exactly this reason. */
+const NUL = String.fromCharCode(0);
+/**
+ * A grant's identity, for a model that has no id of its own.
+ *
+ * 🔴 EXPIRY IS PART OF IT. Two grants for the same item and path with different
+ * expiries are two separate acts of permission — somebody granting the same door
+ * again tomorrow is not re-using yesterday's grant, and keying without the
+ * expiry would silently treat the new one as already spent.
+ *
+ * A NUL separator, so a path containing the separator cannot forge another
+ * grant's key; paths cannot contain NUL on any filesystem this runs on.
+ */
+function grantKey(e) {
+    return [e.itemId, e.path, e.expiresAt].join(NUL);
+}
+class ExemptionStore {
+    stateDir;
+    fs;
+    migrate;
+    /** Distinguishes two writes from ONE process; the pid distinguishes processes. */
+    static writes = 0;
+    spent = {};
+    readable = true;
+    /**
+     * ⚠️ `migrate` RUNS BEFORE ANY READ, AND ITS REFUSAL IS AN UNREADABLE STORE.
+     *
+     * The ledger's home moved out of the repository (see `rails-home.ts`), and a
+     * move is the one moment when "I could not see the old records" and "there
+     * were no old records" look identical. This store's entire safety argument is
+     * that they must never look identical: an unreadable ledger answers `isSpent`
+     * true for everything, because treating a corrupt ledger as "nothing spent"
+     * re-opens every door the machine has already used.
+     *
+     * So a migration that cannot prove what was spent fails the store closed,
+     * exactly as an unparseable `exemptions.json` does. Omitted, there is no
+     * migration and nothing changes — which is what every existing test relies on.
+     */
+    constructor(stateDir, fs, migrate) {
+        this.stateDir = stateDir;
+        this.fs = fs;
+        this.migrate = migrate;
+    }
+    get path() {
+        return `${this.stateDir}/exemptions.json`;
+    }
+    /**
+     * Where spends are written now: APPEND-ONLY, one JSON object per line.
+     *
+     * 🔴 THE WHOLE-MAP REWRITE BECAME A RAILS BYPASS THE MOMENT THIS LEDGER WAS
+     * SHARED. `record` used to serialise the entire `spent` map from the snapshot
+     * loaded at `open()` and rename it over the file. That was sound while one run
+     * owned one checkout. Phase 1 moved this file to the PROJECT state directory —
+     * so that a single-use grant could not be spent once per workspace — and made
+     * two runs concurrent in the same change. Two runs spending two DIFFERENT
+     * grants then each wrote a map that did not contain the other's spend, and the
+     * loser's spend was erased: a single-use grant over a railed path, spendable
+     * again. The scope fix had turned into a lost-update bug, which is precisely
+     * what the recon warned would happen if the format were left alone.
+     *
+     * An append never loses a concurrent write. `exemptions.json` is still READ,
+     * so a machine that has spent grants before this change keeps them, and it is
+     * never written again — that is the whole migration.
+     */
+    get spendLogPath() {
+        return `${this.stateDir}/exemptions.spent.jsonl`;
+    }
+    /**
+     * Read what is on disk.
+     *
+     * 🔴 AN UNREADABLE FILE FAILS CLOSED, WHICH IS THE OPPOSITE OF `CursorStore`.
+     *
+     * There it is safe to replay too much, so a corrupt cursor is treated as no
+     * cursor. Here the equivalent — treating a corrupt file as "nothing spent" —
+     * would re-open every door this machine has already used. So an unreadable
+     * store stops handing out grants entirely: `isSpent` answers true for
+     * everything, and every rail stays shut. Deny is the default the whole rails
+     * design rests on.
+     */
+    async open() {
+        if (this.migrate !== undefined) {
+            const moved = await this.migrate();
+            if (!moved.ok) {
+                this.readable = false;
+                return 'unreadable';
+            }
+        }
+        let text;
+        try {
+            text = await this.fs.readFile(this.path);
+        }
+        catch {
+            this.readable = false;
+            return 'unreadable';
+        }
+        // NO legacy file is the ORDINARY case now, and it is not the end of `open`:
+        // the append-only spend log below is where every spend since this store
+        // stopped rewriting a map lives. Returning 'ok' here — which the first
+        // version of this change did — meant a machine with no `exemptions.json`
+        // saw no spends at all, and every single-use grant read as unspent.
+        if (text === null)
+            return this.readSpendLog();
+        try {
+            const parsed = JSON.parse(text);
+            const spent = parsed?.spent;
+            if (typeof spent !== 'object' || spent === null) {
+                this.readable = false;
+                return 'unreadable';
+            }
+            for (const [key, round] of Object.entries(spent)) {
+                if (typeof round === 'number' && Number.isInteger(round))
+                    this.spent[key] = round;
+            }
+            return this.readSpendLog();
+        }
+        catch {
+            this.readable = false;
+            return 'unreadable';
+        }
+    }
+    /**
+     * Fold the append-only spend log over whatever the legacy file held.
+     *
+     * ⚠️ FAILS CLOSED LIKE ITS SIBLING. A log that exists and cannot be read is a
+     * log whose spends cannot be seen, and a store that cannot see a spend would
+     * re-open a door somebody already used. A MALFORMED LINE is different and is
+     * skipped: an append can be torn by a crash mid-write, and discarding every
+     * spend on the strength of one truncated last line would be the same
+     * fail-open by another route.
+     */
+    async readSpendLog() {
+        let text;
+        try {
+            text = await this.fs.readFile(this.spendLogPath);
+        }
+        catch {
+            this.readable = false;
+            return 'unreadable';
+        }
+        if (text === null)
+            return 'ok';
+        for (const line of text.split('\n')) {
+            if (line.trim() === '')
+                continue;
+            try {
+                const row = JSON.parse(line);
+                if (typeof row.key === 'string' && typeof row.round === 'number' && Number.isInteger(row.round)) {
+                    this.spent[row.key] = row.round;
+                }
+            }
+            catch {
+                // A torn final line, almost certainly. Skip it; the rest still count.
+            }
+        }
+        return 'ok';
+    }
+    /** True when this grant must not be handed to another round. Fails closed. */
+    isSpent(e) {
+        if (!this.readable)
+            return true;
+        return grantKey(e) in this.spent;
+    }
+    /**
+     * Record a grant as spent.
+     *
+     * ⚠️ IDEMPOTENT, AND THE FIRST ROUND WINS. A retry that spends the same grant
+     * again must not rewrite the round number: the round recorded is the one that
+     * actually used the door, and overwriting it would make the trailer and this
+     * file disagree about which commit opened it.
+     *
+     * A store that could not be read refuses to write. Writing a fresh file over
+     * one that failed to parse would discard every spend it contained.
+     */
+    async record(e) {
+        if (!this.readable)
+            return;
+        const key = grantKey(e);
+        if (key in this.spent)
+            return;
+        if (e.usedInRound === null)
+            return;
+        this.spent[key] = e.usedInRound;
+        await this.fs.mkdir(this.stateDir);
+        /**
+         * ONE LINE, APPENDED. No read, no map, no rename — see `spendLogPath`.
+         *
+         * ⚠️ AND NOTHING REWRITES `exemptions.json` EVER AGAIN. Leaving it alone is
+         * what makes the migration a non-event: a machine with spends recorded the
+         * old way keeps them, because `open` still reads it.
+         */
+        await this.fs.appendFile(this.spendLogPath, `${JSON.stringify({ key, round: e.usedInRound })}\n`);
+    }
+    /** What this machine has spent, for a report or a test. */
+    all() {
+        return { ...this.spent };
+    }
+}
+exports.ExemptionStore = ExemptionStore;
+/**
+ * The grants a round may be offered for one item.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * 🔴 THE `!isSpent` HERE IS NOT A DUPLICATE OF THE ONE IN `grantsFromServer`.
+ *
+ * That one runs ONCE, when the run starts. This one runs every time the gate
+ * asks, which is once per item per ROUND — and between two rounds of the same
+ * run a grant can be spent.
+ *
+ * Without it the wiring reproduced exactly the failure `RoundRunner` refuses to
+ * allow: its constructor rejects a grant source with no spend sink because that
+ * is "one grant reopening the same rail every round until it expires". Wiring
+ * both halves satisfied that check STRUCTURALLY while defeating it in fact —
+ * the sink recorded the spend and the source, a plain array captured before the
+ * first round, kept offering the same grant to every round after it. One grant,
+ * one round, was true only across runs and false within one.
+ *
+ * ⚠️ IT READS THE STORE'S IN-MEMORY STATE, WHICH IS WHAT MAKES IT WORK. `record`
+ * assigns `spent[key]` before it awaits the write, so the very next round sees
+ * the spend whether or not the file has landed. A store that cannot be read
+ * answers true for everything and every rail stays shut.
+ *
+ * ⚠️ WHAT IT DOES NOT DO: notice a grant made DURING a run. The source is
+ * fetched once at start, so a person who grants a rail while a run is going
+ * opens it for the NEXT run, not this one. That is a closed door rather than an
+ * open one, so it is recorded here instead of being engineered away with a
+ * mid-run refetch nothing asked for.
+ */
+function offerableFor(grants, itemId, isSpent) {
+    return grants.filter((e) => e.itemId === itemId && !isSpent(e));
+}
+/**
+ * Server rows → the grants a round may be offered.
+ *
+ * 🔴 THREE FILTERS, AND EACH ONE IS LOAD-BEARING.
+ *
+ *   - `decision === 'granted'` — a REFUSAL is recorded in the same table, and
+ *     handing one to a gate would open the door a person explicitly shut.
+ *   - a real `expiresAt` — the model treats a grant with no expiry as no grant;
+ *     `listGranted` already excludes both, and asking again means a source that
+ *     widened cannot widen the rails silently.
+ *   - not already spent on this machine — one grant, one round.
+ *
+ * ⚠️ IT DOES NOT JUDGE THE PATH, AND MUST NOT. Whether a grant opens the file
+ * actually being written is decided at the interlock by `isExemptionValid`,
+ * which is the only place that sees it. Pre-filtering here would be a second
+ * opinion about the same question, free to disagree.
+ */
+function grantsFromServer(rows, isSpent, fromGrant) {
+    return rows
+        .filter((r) => r.decision === 'granted' && typeof r.expiresAt === 'string')
+        .map((r) => fromGrant({
+        itemId: r.itemId,
+        path: r.path,
+        expiresAt: r.expiresAt,
+        actor: r.actor,
+    }))
+        .filter((e) => !isSpent(e));
+}
+//# sourceMappingURL=exemption-store.js.map

package/dist/exemption-store.js.map

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

package/dist/explicit-start-gate.d.ts

@@ -0,0 +1,96 @@
+import { type ApprovalGate } from '@looply/core';
+import type { ApprovalResumes } from './approval-resumes';
+import type { GovernedApprovals } from './governed-approvals';
+import { type LeaseState } from './run-lease';
+/**
+ * WHAT AN EXPLICIT START IS ALLOWED TO CARRY, AND WHETHER IT MAY HAPPEN AT ALL.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * THIS EXISTS AS A MODULE BECAUSE IT USED TO BE A CLOSURE, AND THE CLOSURE HID A
+ * PERMANENT WEDGE
+ *
+ * `daemon-cmd.ts` built this inline over five captured values, so it had no
+ * export and no test seam. Every other property of the Start path had one; this
+ * one was reachable only by running a daemon. What it hid:
+ *
+ *   `refusesExplicitStart` deliberately ADMITS `claimed`, `executing` and
+ *   `result-pending` — it says so in as many words, because refusing them
+ *   "would strand authority that was legitimately taken ... something has to be
+ *   allowed to go and look". The closure then handed the run an approval id in
+ *   ONE arm, `approved`, and dropped the other three to an ordinary Start. So
+ *   the gate admitted the Start, nothing looked, `run-cmd` killed the run on its
+ *   own re-read of the same gate, and the approval stayed `claimed` for ever —
+ *   which meant every later Start did the same thing again.
+ *
+ * The behavioural half of the rule now lives in `governedStartApproval`, and
+ * this module is what makes the WIRING testable: the collaborators injected
+ * rather than captured, so a spec can hand it a gate in any state and read what
+ * a Start would be given.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * WHAT IT DECIDES, IN ORDER
+ *
+ * 1. A gate that refuses is a refusal, and `terminal` decides whether the phone
+ *    may offer the command again. Only "nobody could tell" is worth retrying.
+ * 2. An approval the Start must carry is reserved, so the claim key is durable
+ *    before the run exists — and a lost reservation means opposite things
+ *    depending on what the SERVER already recorded.
+ * 3. A denial is claimed, and losing that race is NOT a refusal: the winner has
+ *    the answer, and this Start carries on as an ordinary one.
+ *
+ * Resolving WHICH pursuit is being started is the daemon's, and stays there.
+ */
+export interface ExplicitStartDecision {
+    /** Why not, when not. `terminal` decides whether the phone may offer it again. */
+    readonly refuse?: {
+        readonly reason: string;
+        readonly terminal: boolean;
+    };
+    readonly resumedFromApprovalId?: string;
+    /**
+     * The approved action this Start has just been given the right to carry out.
+     *
+     * Never alongside `resumedFromApprovalId`: a Start either picks up an answer
+     * or carries one out, and both at once would be a run acting on a refusal and
+     * an approval in the same breath.
+     */
+    readonly governedApprovalId?: string;
+}
+/** Just enough of each collaborator to decide. Injected so a spec can drive it. */
+export interface ExplicitStartDeps {
+    readonly governed: Pick<GovernedApprovals, 'reserve' | 'takeOver'>;
+    readonly resumes: Pick<ApprovalResumes, 'claim'>;
+    /**
+     * IS ANYTHING STILL CARRYING WORK ON THIS TREE?
+     *
+     * The run lease, read durably. This is the question a stale reservation turns
+     * on, and the lease already answers it in exactly the right four ways —
+     * `active` is a process that is running, `dead` is one that is gone,
+     * `ambiguous` fails closed, and `free` is nobody. Reusing it means this is not
+     * a second, weaker notion of liveness sitting beside the real one.
+     */
+    readonly carrier: () => Promise<LeaseState>;
+    readonly log: (line: string) => void;
+}
+/**
+ * 🔴 IT TAKES A GATE, NOT A WAY TO READ ONE, AND THAT IS AN ARCHITECTURAL RULE
+ * RATHER THAN A CONVENIENCE.
+ *
+ * The first version of this module took a gate READER plus the two identifiers
+ * that name a pursuit, and `apps/app/src/goal-wiring.spec.ts` failed it
+ * immediately: that vocabulary is confined to an allow-list of files across the
+ * whole tree, and this is not one of them. Widening the list would have been the
+ * easy answer and the wrong one — **this decision does not need to know what a
+ * pursuit IS.** It needs a gate and a Start. Reading the gate stays in the
+ * daemon, which is allowed that vocabulary because it is the thing holding one.
+ *
+ * ⚠️ Note the guardrail scans RAW LINES, comments included, so even naming those
+ * identifiers in this paragraph failed it a second time. That is coarse, and it
+ * is the safe direction: a confinement rule that reasoned about which mentions
+ * were "only prose" would be a rule with an exemption in it.
+ *
+ * The seam is not weakened by it: every arm, every reservation outcome and the
+ * takeover are all still driven from here.
+ */
+export declare function decideExplicitStart(deps: ExplicitStartDeps, gate: ApprovalGate, requestId: string): Promise<ExplicitStartDecision>;
+//# sourceMappingURL=explicit-start-gate.d.ts.map

package/dist/explicit-start-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explicit-start-gate.d.ts","sourceRoot":"","sources":["../src/explicit-start-gate.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,YAAY,EAClB,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAiB,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,MAAM,WAAW,qBAAqB;IACpC,kFAAkF;IAClF,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,CAAC;IAC1E,QAAQ,CAAC,qBAAqB,CAAC,EAAE,MAAM,CAAC;IACxC;;;;;;OAMG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CACtC;AAED,mFAAmF;AACnF,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,iBAAiB,EAAE,SAAS,GAAG,UAAU,CAAC,CAAC;IACnE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;IACjD;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,UAAU,CAAC,CAAC;IAC5C,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACtC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,iBAAiB,EACvB,IAAI,EAAE,YAAY,EAClB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,qBAAqB,CAAC,CA4EhC"}

package/dist/explicit-start-gate.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decideExplicitStart = decideExplicitStart;
+const core_1 = require("@looply/core");
+const run_lease_1 = require("./run-lease");
+/**
+ * 🔴 IT TAKES A GATE, NOT A WAY TO READ ONE, AND THAT IS AN ARCHITECTURAL RULE
+ * RATHER THAN A CONVENIENCE.
+ *
+ * The first version of this module took a gate READER plus the two identifiers
+ * that name a pursuit, and `apps/app/src/goal-wiring.spec.ts` failed it
+ * immediately: that vocabulary is confined to an allow-list of files across the
+ * whole tree, and this is not one of them. Widening the list would have been the
+ * easy answer and the wrong one — **this decision does not need to know what a
+ * pursuit IS.** It needs a gate and a Start. Reading the gate stays in the
+ * daemon, which is allowed that vocabulary because it is the thing holding one.
+ *
+ * ⚠️ Note the guardrail scans RAW LINES, comments included, so even naming those
+ * identifiers in this paragraph failed it a second time. That is coarse, and it
+ * is the safe direction: a confinement rule that reasoned about which mentions
+ * were "only prose" would be a rule with an exemption in it.
+ *
+ * The seam is not weakened by it: every arm, every reservation outcome and the
+ * takeover are all still driven from here.
+ */
+async function decideExplicitStart(deps, gate, requestId) {
+    if ((0, core_1.refusesExplicitStart)(gate)) {
+        return {
+            refuse: {
+                reason: (0, core_1.approvalHold)(gate) ?? 'this pursuit is waiting on a person',
+                // Definite answers are terminal: the person taps Start again when they
+                // have decided, and offering the same command back every three seconds
+                // for an hour would be noise rather than resilience. Only "nobody could
+                // tell" is worth retrying.
+                terminal: gate.kind !== 'unknown',
+            },
+        };
+    }
+    /**
+     * WHICH APPROVAL THIS START CARRIES.
+     *
+     * `governedStartApproval` owns the rule, and it is stated there as an
+     * equality over every arm rather than as a list here — because a list here is
+     * exactly what drifted out of step with `refusesExplicitStart`.
+     *
+     * The reservation is taken BEFORE the run exists, because that is where two
+     * Starts race, and because the claim key derives from it and has to survive
+     * the process that made it.
+     */
+    const approvalId = (0, core_1.governedStartApproval)(gate);
+    if (approvalId !== null) {
+        const held = await deps.governed.reserve(approvalId, requestId);
+        if (held.ok)
+            return { governedApprovalId: approvalId };
+        /**
+         * A RESERVATION IS ALREADY THERE, AND THE QUESTION IS WHETHER ANYTHING IS
+         * STILL CARRYING IT — not which arm the gate is in.
+         *
+         * The first version of this asked the arm: it took a stale record over only
+         * for the three where the server had recorded a claim, and left `approved`
+         * on the one-shot rule with the comment "it is retryable, because the winner
+         * may yet fail to produce a run". That was exactly backwards. If the winner
+         * fails to produce a run, the approval stays `approved` for ever, the gate
+         * never becomes one of the other arms, the takeover is never reachable, and
+         * every later Start is refused non-terminally and redelivered for ever —
+         * the same permanent wedge this module was written to remove, surviving in
+         * the one arm it did not touch.
+         */
+        if (held.held === null) {
+            // Present and UNREADABLE is never taken over: it may name the key an
+            // in-flight claim is using, and nothing here can tell that from a corrupt
+            // file. `takeOver` refuses this too; asked here so the reason is the one
+            // the reader gets.
+            return { refuse: { reason: held.because, terminal: false } };
+        }
+        const lease = await deps.carrier();
+        if (lease.kind !== 'free' && lease.kind !== 'dead') {
+            /**
+             * Something holds the tree, or nobody can tell. Refuse, and RETRYABLY:
+             * the holder may finish, and `ambiguous` may become decidable. Taking the
+             * record over here is what would kill a live, correctly authorised run —
+             * its prehook re-reads the reservation and refuses when the name is no
+             * longer its own.
+             */
+            return { refuse: { reason: (0, run_lease_1.describeLease)(lease), terminal: false } };
+        }
+        const taken = await deps.governed.takeOver(approvalId, requestId);
+        if (!taken.ok)
+            return { refuse: { reason: taken.because, terminal: false } };
+        deps.log(`daemon  : taking over an unfinished action on approval ${approvalId}`);
+        return { governedApprovalId: approvalId };
+    }
+    if (gate.kind !== 'resume-required')
+        return {};
+    /**
+     * A DENIAL TO CARRY BACK, and losing this race is deliberately NOT a refusal.
+     * The other Start has the answer and is about to hold the working tree; this
+     * one carries on as an ordinary Start and meets the lease like any other.
+     */
+    const claim = await deps.resumes.claim(gate.approvalId, requestId);
+    return claim.ok ? { resumedFromApprovalId: gate.approvalId } : {};
+}
+//# sourceMappingURL=explicit-start-gate.js.map

package/dist/explicit-start-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explicit-start-gate.js","sourceRoot":"","sources":["../src/explicit-start-gate.ts"],"names":[],"mappings":";;AAoGA,kDAgFC;AApLD,uCAKsB;AAGtB,2CAA6D;AAwE7D;;;;;;;;;;;;;;;;;;;GAmBG;AACI,KAAK,UAAU,mBAAmB,CACvC,IAAuB,EACvB,IAAkB,EAClB,SAAiB;IAEjB,IAAI,IAAA,2BAAoB,EAAC,IAAI,CAAC,EAAE,CAAC;QAC/B,OAAO;YACL,MAAM,EAAE;gBACN,MAAM,EAAE,IAAA,mBAAY,EAAC,IAAI,CAAC,IAAI,qCAAqC;gBACnE,uEAAuE;gBACvE,uEAAuE;gBACvE,wEAAwE;gBACxE,2BAA2B;gBAC3B,QAAQ,EAAE,IAAI,CAAC,IAAI,KAAK,SAAS;aAClC;SACF,CAAC;IACJ,CAAC;IAED;;;;;;;;;;OAUG;IACH,MAAM,UAAU,GAAG,IAAA,4BAAqB,EAAC,IAAI,CAAC,CAAC;IAC/C,IAAI,UAAU,KAAK,IAAI,EAAE,CAAC;QACxB,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;QAChE,IAAI,IAAI,CAAC,EAAE;YAAE,OAAO,EAAE,kBAAkB,EAAE,UAAU,EAAE,CAAC;QAEvD;;;;;;;;;;;;;WAaG;QACH,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;YACvB,qEAAqE;YACrE,0EAA0E;YAC1E,yEAAyE;YACzE,mBAAmB;YACnB,OAAO,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE,CAAC;QAC/D,CAAC;QACD,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;QACnC,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YACnD;;;;;;eAMG;YACH,OAAO,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,IAAA,yBAAa,EAAC,KAAK,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE,CAAC;QACvE,CAAC;QACD,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;QAClE,IAAI,CAAC,KAAK,CAAC,EAAE;YAAE,OAAO,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE,CAAC;QAC7E,IAAI,CAAC,GAAG,CAAC,0DAA0D,UAAU,EAAE,CAAC,CAAC;QACjF,OAAO,EAAE,kBAAkB,EAAE,UAAU,EAAE,CAAC;IAC5C,CAAC;IAED,IAAI,IAAI,CAAC,IAAI,KAAK,iBAAiB;QAAE,OAAO,EAAE,CAAC;IAC/C;;;;OAIG;IACH,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;IACnE,OAAO,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,qBAAqB,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AACpE,CAAC"}

package/dist/fs-trouble.d.ts

@@ -0,0 +1,70 @@
+/**
+ * WHY A FILE COULD NOT BE READ, WHEN THE ANSWER CHANGES WHAT HAPPENS.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * Two failures wear the same clothes and mean opposite things.
+ *
+ * A file whose CONTENTS cannot be trusted is durable damage. Retrying reads the
+ * same bytes and reaches the same conclusion, so a machine that kept trying
+ * would spin until the grant expired without ever telling anybody. That has to
+ * stop and ask a person.
+ *
+ * A file that could not be OPENED THIS INSTANT is weather. On Windows it is
+ * ordinary: an antivirus scanner, the search indexer, a backup agent or another
+ * process holding a handle produces EPERM or EBUSY for a few milliseconds and
+ * then stops. Nothing is wrong with the data. A machine that treated it as
+ * damage would end somebody's night over a file lock that cleared before they
+ * read the message.
+ *
+ * A certification pass reproduced exactly that: one transient read, and a
+ * pursuit irreversibly terminated as `human_required`.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * ENOENT IS NOT HERE, deliberately.
+ *
+ * The filesystem contract these stores are written against resolves a missing
+ * file to `null` rather than throwing (see `nodeLedgerFs.readFile`), because
+ * absence is usually legal — the first receipt of a request, a grant nothing has
+ * been spent against yet. Where absence is NOT legal, the store that knows the
+ * history says so itself: a hole among receipts is a contradiction, and that
+ * judgement belongs to the store, not to an errno.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * UNKNOWN IS NOT TRANSIENT.
+ *
+ * Anything not on the list below is reported as unknown, and callers treat
+ * unknown the same way they treat transient — hold, do not conclude — because
+ * the alternative is inventing durable corruption out of an errno nobody
+ * recognised. What it must never do is silently widen: a list that swallowed
+ * every error would make the corrupt path unreachable, and the corrupt path is
+ * the one that protects the budget.
+ */
+export type FsTrouble = 
+/** Could not read it now. The bytes are not accused of anything. */
+{
+    kind: 'transient';
+    code: string;
+    because: string;
+}
+/** An error nobody here recognises. Treated as "not now", never as damage. */
+ | {
+    kind: 'unknown';
+    code: string;
+    because: string;
+};
+/**
+ * Classify a thrown read error.
+ *
+ * Never decides that contents are corrupt — it has not seen any contents. That
+ * judgement belongs to whoever parsed them.
+ */
+export declare function classifyFsError(e: unknown, what: string): FsTrouble;
+/**
+ * Whether this trouble should make a caller wait rather than conclude.
+ *
+ * Both arms today, and the function exists so that the decision has one home
+ * instead of being re-derived at each call site — which is how the two would
+ * eventually come to disagree.
+ */
+export declare function shouldWaitFor(t: FsTrouble): boolean;
+//# sourceMappingURL=fs-trouble.d.ts.map

package/dist/fs-trouble.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-trouble.d.ts","sourceRoot":"","sources":["../src/fs-trouble.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAuBH,MAAM,MAAM,SAAS;AACnB,oEAAoE;AAClE;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE;AACtD,8EAA8E;GAC5E;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,CAenE;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,SAAS,GAAG,OAAO,CAEnD"}

package/dist/fs-trouble.js

@@ -0,0 +1,98 @@
+"use strict";
+/**
+ * WHY A FILE COULD NOT BE READ, WHEN THE ANSWER CHANGES WHAT HAPPENS.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * Two failures wear the same clothes and mean opposite things.
+ *
+ * A file whose CONTENTS cannot be trusted is durable damage. Retrying reads the
+ * same bytes and reaches the same conclusion, so a machine that kept trying
+ * would spin until the grant expired without ever telling anybody. That has to
+ * stop and ask a person.
+ *
+ * A file that could not be OPENED THIS INSTANT is weather. On Windows it is
+ * ordinary: an antivirus scanner, the search indexer, a backup agent or another
+ * process holding a handle produces EPERM or EBUSY for a few milliseconds and
+ * then stops. Nothing is wrong with the data. A machine that treated it as
+ * damage would end somebody's night over a file lock that cleared before they
+ * read the message.
+ *
+ * A certification pass reproduced exactly that: one transient read, and a
+ * pursuit irreversibly terminated as `human_required`.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * ENOENT IS NOT HERE, deliberately.
+ *
+ * The filesystem contract these stores are written against resolves a missing
+ * file to `null` rather than throwing (see `nodeLedgerFs.readFile`), because
+ * absence is usually legal — the first receipt of a request, a grant nothing has
+ * been spent against yet. Where absence is NOT legal, the store that knows the
+ * history says so itself: a hole among receipts is a contradiction, and that
+ * judgement belongs to the store, not to an errno.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * UNKNOWN IS NOT TRANSIENT.
+ *
+ * Anything not on the list below is reported as unknown, and callers treat
+ * unknown the same way they treat transient — hold, do not conclude — because
+ * the alternative is inventing durable corruption out of an errno nobody
+ * recognised. What it must never do is silently widen: a list that swallowed
+ * every error would make the corrupt path unreachable, and the corrupt path is
+ * the one that protects the budget.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyFsError = classifyFsError;
+exports.shouldWaitFor = shouldWaitFor;
+/**
+ * Codes that mean "not this instant", on the platforms looply runs on.
+ *
+ * EPERM and EACCES are what Windows reports for a sharing violation, which is
+ * the case that actually bit. EBUSY is the same thing under another name. The
+ * descriptor-exhaustion pair (EMFILE/ENFILE) and the non-blocking pair
+ * (EAGAIN/EWOULDBLOCK) are here for the same reason: they describe the machine
+ * being busy, never the bytes being wrong.
+ */
+const TRANSIENT = new Set([
+    'EPERM',
+    'EACCES',
+    'EBUSY',
+    'EMFILE',
+    'ENFILE',
+    'EAGAIN',
+    'EWOULDBLOCK',
+    'ETXTBSY',
+    'ETIMEDOUT',
+]);
+/**
+ * Classify a thrown read error.
+ *
+ * Never decides that contents are corrupt — it has not seen any contents. That
+ * judgement belongs to whoever parsed them.
+ */
+function classifyFsError(e, what) {
+    const code = e?.code ?? '';
+    const detail = e?.message ?? String(e);
+    if (TRANSIENT.has(code)) {
+        return {
+            kind: 'transient',
+            code,
+            because: `${what} could not be read just now (${code}) — something else is holding it`,
+        };
+    }
+    return {
+        kind: 'unknown',
+        code,
+        because: `${what} could not be read (${detail})`,
+    };
+}
+/**
+ * Whether this trouble should make a caller wait rather than conclude.
+ *
+ * Both arms today, and the function exists so that the decision has one home
+ * instead of being re-derived at each call site — which is how the two would
+ * eventually come to disagree.
+ */
+function shouldWaitFor(t) {
+    return t.kind === 'transient' || t.kind === 'unknown';
+}
+//# sourceMappingURL=fs-trouble.js.map

package/dist/fs-trouble.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-trouble.js","sourceRoot":"","sources":["../src/fs-trouble.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;;AAmCH,0CAeC;AASD,sCAEC;AA3DD;;;;;;;;GAQG;AACH,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC;IACxB,OAAO;IACP,QAAQ;IACR,OAAO;IACP,QAAQ;IACR,QAAQ;IACR,QAAQ;IACR,aAAa;IACb,SAAS;IACT,WAAW;CACZ,CAAC,CAAC;AAQH;;;;;GAKG;AACH,SAAgB,eAAe,CAAC,CAAU,EAAE,IAAY;IACtD,MAAM,IAAI,GAAI,CAAkC,EAAE,IAAI,IAAI,EAAE,CAAC;IAC7D,MAAM,MAAM,GAAI,CAAkB,EAAE,OAAO,IAAI,MAAM,CAAC,CAAC,CAAC,CAAC;IACzD,IAAI,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QACxB,OAAO;YACL,IAAI,EAAE,WAAW;YACjB,IAAI;YACJ,OAAO,EAAE,GAAG,IAAI,gCAAgC,IAAI,kCAAkC;SACvF,CAAC;IACJ,CAAC;IACD,OAAO;QACL,IAAI,EAAE,SAAS;QACf,IAAI;QACJ,OAAO,EAAE,GAAG,IAAI,uBAAuB,MAAM,GAAG;KACjD,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,aAAa,CAAC,CAAY;IACxC,OAAO,CAAC,CAAC,IAAI,KAAK,WAAW,IAAI,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC;AACxD,CAAC"}