looply-cli 0.0.0-stage → 0.2.0

package/dist/autonomy-store.d.ts

@@ -0,0 +1,327 @@
+import { type GoalAutonomyState } from '@looply/core';
+import { type LedgerFs } from './ledger-store';
+/**
+ * WHAT THIS MACHINE HAS SPENT OF A GRANT.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * THE COUNT IS NOT A NUMBER IN A FILE. IT IS A PILE OF RECEIPTS.
+ *
+ * 6D1R-C. Spending used to be read-then-write on `startsConsumed`: read 3,
+ * add one, write 4. Two daemons for one project are possible -- nothing takes
+ * a lock at daemon startup, which was verified rather than assumed -- and two
+ * of them reading 3 both write 4. One Start's worth of budget, two Starts
+ * issued, and the file afterwards is perfectly well-formed and says 4. There
+ * is no later moment at which anything could notice.
+ *
+ * So an ordinal is now RESERVED rather than counted: one file per Start,
+ * created with O_EXCL, which the operating system will hand to exactly one
+ * caller. The loser of that race gets EEXIST, moves to the next ordinal and
+ * takes that one instead. Both callers end up with a distinct Start and the
+ * total spent is still the number of files, which nobody can lose an update
+ * to because nobody ever updates anything.
+ *
+ * `startsConsumed` is DERIVED from the receipts. Storing it as well would
+ * recreate the same defect one indirection down: two sources for one fact,
+ * disagreeing the first time a write was lost.
+ *
+ * At most one Start at a time is a separate invariant, and the RUN LEASE is
+ * what holds it -- also O_EXCL, also structural. The check here is a cheap
+ * early refusal, not the guard. Two daemons that both reserve an ordinal
+ * produce one run and one refusal, and the refused one has spent a Start,
+ * which is the direction this file always errs in.
+ *
+ * The server owns AUTHORIZATION — who may pursue which goal at which version,
+ * with what ceiling, until when. This owns EXECUTION PROGRESS: how many bounded
+ * Starts have actually been spent here, and which one is in flight.
+ *
+ * One fact, one writer. A `startsConsumed` column on the server would be a
+ * counter written from both sides, and the two would disagree the first time a
+ * machine spent a Start while offline.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * WHY NOT ANY EXISTING FILE
+ *
+ * `queue.json` — two processes write it without holding the run lease
+ * (`scan-cmd`, `verify-cmd`), each rewriting the whole list from a map filled at
+ * open. A stale writer would revert a budget, and reverting a budget REFILLS it.
+ *
+ * `goals.json` — the format is `{ schema, goals }` and nothing else survives a
+ * write. Not a race: a field that is not a goal is erased by the file's shape,
+ * on every write, from two processes.
+ *
+ * `control.json` — consumed unconditionally at the start of every run, on the
+ * reasoning that "starting a run is itself the human saying go". Right for a
+ * pause; fatal for a grant, which must outlive the runs it authorizes.
+ *
+ * The command row — deliberately time-boxed to the one-hour redelivery window,
+ * precisely so that an old command cannot be reinterpreted as a standing
+ * permission.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * FAILS CLOSED, WHICH IS THE WHOLE POINT
+ *
+ * A missing or unreadable file does NOT mean "nothing has been spent". It means
+ * this machine cannot say what it has spent, and a budget it cannot account for
+ * is a budget it may not draw on. Every other store here discards a corrupt
+ * file and carries on, because every other store holds a cache of something
+ * recoverable. This one holds the only record of what was already permitted and
+ * used, so the same policy would silently refill the budget on any corruption —
+ * turning a damaged file into unlimited Starts.
+ */
+/**
+ * Bumped only when the on-disk shape changes incompatibly. Read, not decorative.
+ *
+ * 2 dropped `startsConsumed` and `inFlight` from the file, because both are now
+ * derived from receipts. A schema-1 file is REFUSED rather than migrated: its
+ * count is a number this build has no receipts for, and inventing receipts to
+ * match it would be inventing the very evidence the receipts exist to be.
+ */
+export declare const AUTONOMY_STORE_SCHEMA = 2;
+/**
+ * The TERMS of a grant, as this machine holds them. No count.
+ *
+ * Everything here was stamped by the server and is immutable for the life of
+ * the grant, except `state`, which is where this machine records that the
+ * pursuit came to rest.
+ */
+export interface AutonomyProgress {
+    controllerId: string;
+    goalId: string;
+    /** The version this grant is for. A grant never follows a goal to a new one. */
+    goalVersion: number;
+    /** The ceiling the SERVER stamped. Copied here so an offline machine still has a bound. */
+    maxStarts: number;
+    /** ISO. The absolute end, whatever is left of the count. */
+    expiresAt: string;
+    /** What this machine believes the grant has come to. The server is told separately. */
+    state: GoalAutonomyState;
+    /**
+     * When the server was successfully told how this pursuit ended. ISO.
+     *
+     * The ONE fact here that is not derivable from anything else, and it is
+     * recorded only because of that. Everything else about a grant's progress
+     * comes from immutable receipts and marks; "we got through to the server"
+     * comes from nowhere but the moment it happened.
+     *
+     * Without it a finished pursuit has no way to know it is finished with, so
+     * every tick would re-ask the server about every grant that ever ended, for
+     * as long as the machine lived — and those requests would compete with the
+     * live grants for the one turn a tick gives out.
+     */
+    projectedAt?: string;
+}
+/** What the receipts add up to. Derived on every read; never stored. */
+export interface AutonomySpend {
+    /** The ordinals this machine holds a reservation for, ascending. */
+    reserved: readonly number[];
+    /** Its length. Named because that is the whole point of the file layout. */
+    startsConsumed: number;
+    /**
+     * Reserved ordinals with no ending marked, LOWEST FIRST.
+     *
+     * This replaced a single `inFlight` and the change is not cosmetic. That
+     * field claimed two things it could not know, and both were wrong:
+     *
+     *   IT NAMED THE HIGHEST such ordinal, because it was assigned in a loop with
+     *   no break. Two daemons racing a reservation take ordinals 1 and 2, and the
+     *   field then reported only 2 — so marking "the in-flight Start" over
+     *   finished 2 and left 1 unresolved for ever, silently spending a Start on
+     *   nothing and then refusing every later one against a Start that had never
+     *   run.
+     *
+     *   IT CALLED A RESERVATION A FLIGHT. An ordinal can be reserved by a process
+     *   that dies before it launches anything: budget spent, nothing running, no
+     *   runId, no attempt. Reporting that as in flight means waiting for a run
+     *   that does not exist, and a controller waiting on it would wait for ever.
+     *
+     * A reserved ordinal with nothing yet attempted is RESUMABLE, not in flight.
+     * Whether anything is actually executing is a question about attempt claims
+     * and start marks — see start-attempts.ts — and this file deliberately does
+     * not pretend to answer it.
+     */
+    unfinished: readonly number[];
+    /** The run each unfinished ordinal produced, where one is on record. */
+    runs: Readonly<Record<number, string>>;
+}
+/**
+ * The filesystem this store needs.
+ *
+ * `createExclusive` is not a convenience: it is the entire concurrency
+ * argument. A store handed a double that quietly overwrites has no budget.
+ */
+export interface AutonomyFs extends LedgerFs {
+    /** Create only if absent. MUST reject with an `EEXIST` error when it is not. */
+    createExclusive(path: string, data: string): Promise<void>;
+}
+/** The real one: ledger reads and writes, plus the lease file's exclusive create. */
+export declare const nodeAutonomyFs: AutonomyFs;
+export type AutonomyRead = {
+    ok: true;
+    progress: AutonomyProgress[];
+}
+/**
+ * Could not be read, or could not be trusted.
+ *
+ * NOT an empty list. The caller must treat this as "I cannot account for this
+ * budget", never as "nothing has been spent".
+ */
+ | {
+    ok: false;
+    because: string;
+    /**
+     * WHETHER THE BYTES ARE ACCUSED OF ANYTHING.
+     *
+     * Absent means damaged: something was read and could not be trusted.
+     * True means nothing was read at all, and a caller that can wait should.
+     *
+     * Every other reader in this file already had this distinction - claims,
+     * launches, spendOf all got it - and the one read that a PERSON is
+     * waiting on did not. `adopt` throws on a failed read and the command
+     * handler refuses durably on any throw, so a file lock lasting a
+     * millisecond permanently refused a grant somebody had just authorized.
+     */
+    transient?: boolean;
+};
+/**
+ * The deterministic identity of one bounded Start within one grant.
+ *
+ * Two daemons can run for one project — nothing takes a lock at daemon startup,
+ * verified rather than assumed — so "the next Start" must be a name both would
+ * compute identically, not a fresh id each invents. Ordinal N of controller C is
+ * one Start no matter how many processes decide it is due.
+ */
+/**
+ * IS THIS RECEIPT A CAPABILITY, OR JUST A FILE THAT PARSES?
+ *
+ * The receipts ARE the Start budget. Nothing else counts them, and `spendOf`
+ * derives everything a person's evening is bounded by from the ones it finds on
+ * disk. So a receipt cannot be believed merely because JSON.parse succeeded and
+ * a number looked numeric — a certification pass fed it an empty file, the text
+ * `not json at all`, and a body naming ordinal 77 of another controller, and
+ * all three were counted as valid reservations.
+ *
+ * Every receipt carries exactly three facts, and each of them must agree with
+ * where the file is sitting:
+ *
+ *   ordinal       the file's own name says which Start this is
+ *   controllerId  the directory says whose grant it belongs to
+ *   startId       derived, never minted — `autonomyStartId(controllerId, ordinal)`
+ *
+ * A CONTRADICTION IS CORRUPTION, and neither side wins. If the path says
+ * controller C ordinal 3 and the body says controller D ordinal 2, believing
+ * the path would let a receipt be moved between grants by renaming it, and
+ * believing the body would let one be forged by writing it. There is no third
+ * option that is safe, so both are refused.
+ *
+ * NOTHING IS DUPLICATED HERE. The receipt is not given a goal id, a goal
+ * version or a generation, because it needs none of them: `controllerId` IS the
+ * generation — the server mints a new row with a new id for every act of
+ * permission, precisely so a fresh grant never inherits a spent one's identity
+ * — and the grant's own terms are held immutable by `adopt`, which refuses a
+ * known controller whose goal, version, ceiling or expiry has moved. Copying a
+ * receipt from C1 into C2's directory changes the controllerId it must match,
+ * and is caught here.
+ */
+export declare function receiptTrouble(text: string, controllerId: string, ordinal: number, maxStarts: number): string | null;
+export declare function autonomyStartId(controllerId: string, ordinal: number): string;
+export declare class AutonomyStore {
+    private readonly stateDir;
+    private readonly fs;
+    private loaded;
+    /** Distinguishes two writes from ONE process; the pid distinguishes processes. */
+    private static writes;
+    constructor(stateDir: string, fs: AutonomyFs);
+    private get path();
+    /** One directory per grant. The controllerId is opaque and never reused. */
+    private receiptDir;
+    /**
+     * The reservation for one ordinal. Zero-padded so the names sort as numbers
+     * for anybody who ever lists the directory by eye.
+     */
+    private receiptPath;
+    /**
+     * Read the file, refusing to guess.
+     *
+     * ABSENT is `ok` with nothing in it — a machine that has never been granted
+     * autonomy has spent nothing, and that is a true statement rather than an
+     * assumption. UNREADABLE, malformed, wrong-schema and wrong-shape are all
+     * `ok: false`, because in every one of those cases a grant may exist whose
+     * spending this file was the only record of.
+     */
+    read(): Promise<AutonomyRead>;
+    /**
+     * Spend one Start, BEFORE it is issued, and say which one it is.
+     *
+     * The direction is the safety argument. Consuming first means a crash between
+     * the write and the spawn COSTS a Start — one of eight, and the goal is no
+     * worse off. Consuming after would mean a crash between the spawn and the
+     * write GRANTS one, and a machine that crashes reliably at that point has an
+     * unbounded budget.
+     *
+     * Refuses rather than throws when the record cannot be read, when the grant is
+     * unknown, when it has ended, when it has expired, or when the ceiling is
+     * reached. Every one of those is "no Start today", not an error to be caught
+     * and ignored.
+     */
+    consumeStart(controllerId: string, now: number): Promise<{
+        ok: true;
+        ordinal: number;
+        startId: string;
+    } | {
+        ok: false;
+        because: string;
+    }>;
+    /**
+     * Record which run a Start produced, so its ending can be watched for.
+     *
+     * Immutable like the reservation. A second call naming the SAME run is the
+     * redelivery this whole system is built to tolerate; a second call naming a
+     * different one is two runs claiming one Start, and it is refused rather
+     * than allowed to overwrite the first answer.
+     */
+    noteRun(controllerId: string, ordinal: number, runId: string): Promise<void>;
+    /** The Start is over, however it ended. The count is NOT given back. */
+    clearInFlight(controllerId: string): Promise<void>;
+    /** Mark one Start over by ordinal. Idempotent: it is already over. */
+    finishStart(controllerId: string, ordinal: number): Promise<void>;
+    /** The terms of one grant, or why they cannot be answered for. */
+    termsOf(controllerId: string): Promise<{
+        ok: true;
+        grant: AutonomyProgress;
+    } | {
+        ok: false;
+        because: string;
+    }>;
+    /**
+     * Count the receipts.
+     *
+     * Probed ordinal by ordinal rather than listed, because a ceiling of eight
+     * makes eight reads cheaper than adding a directory-listing capability to
+     * every filesystem double in the tree -- and a probe cannot be fooled by a
+     * stray file the way a listing can.
+     */
+    spendOf(controllerId: string, maxStarts: number): Promise<{
+        ok: true;
+        spend: AutonomySpend;
+    } | {
+        ok: false;
+        transient: boolean;
+        because: string;
+    }>;
+    /** Adopt a grant the server issued. Re-adopting the same one keeps what was spent. */
+    adopt(grant: Omit<AutonomyProgress, 'startsConsumed' | 'state'>): Promise<void>;
+    /**
+     * Note that the server has been told how this pursuit ended.
+     *
+     * Separate from `settle` on purpose: one is what this machine concluded, the
+     * other is that somebody else now knows. A crash between them must leave the
+     * conclusion standing and the telling still owed.
+     */
+    markProjected(controllerId: string, at: string): Promise<void>;
+    /** Record where this grant came to rest. Terminal states spend nothing further. */
+    settle(controllerId: string, state: GoalAutonomyState): Promise<void>;
+    /** What this machine last read. Empty before a successful `read`. */
+    all(): AutonomyProgress[];
+    private write;
+}
+//# sourceMappingURL=autonomy-store.d.ts.map

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

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