@aldus-runtime/file-store 0.2.0-next.6 → 0.2.0-next.60

package/dist/errors.d.ts

@@ -37,6 +37,12 @@ export declare const FileStoreErrorCodes: {
     readonly LOCK_TIMEOUT: "ALDUS_LOCK_TIMEOUT";
     /** A lock was released or renewed by something that no longer holds it. */
     readonly LOCK_LOST: "ALDUS_LOCK_LOST";
+    /** A reservation transition does not satisfy its schema (ADR-0044). */
+    readonly RESERVATION_TRANSITION_INVALID: "ALDUS_RESERVATION_TRANSITION_INVALID";
+    /** One transition id was reused for a different fact (ADR-0044). */
+    readonly RESERVATION_TRANSITION_CONFLICT: "ALDUS_RESERVATION_TRANSITION_CONFLICT";
+    /** A reservation stream has a gap, which no correct writer can produce (ADR-0044). */
+    readonly RESERVATION_STREAM_CORRUPT: "ALDUS_RESERVATION_STREAM_CORRUPT";
     /**
      * A lock was re-acquired inside a scope that already holds it.
      *

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAAE,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAErE,4CAA4C;AAC5C,eAAO,MAAM,mBAAmB;IAC9B,8EAA8E;aAC9E,mBAAmB,EAAE,2BAA2B;IAChD,0DAA0D;aAC1D,gBAAgB,EAAE,wBAAwB;IAC1C,wDAAwD;aACxD,gBAAgB,EAAE,wBAAwB;IAC1C;;;;;OAKG;aACH,iBAAiB,EAAE,yBAAyB;IAC5C;;;;;OAKG;aACH,mBAAmB,EAAE,2BAA2B;IAChD,8DAA8D;aAC9D,qBAAqB,EAAE,6BAA6B;IACpD,uEAAuE;aACvE,eAAe,EAAE,uBAAuB;IACxC,iEAAiE;aACjE,YAAY,EAAE,oBAAoB;IAClC,2EAA2E;aAC3E,SAAS,EAAE,iBAAiB;IAC5B;;;;;;;OAOG;aACH,cAAc,EAAE,sBAAsB;IACtC,yFAAyF;aACzF,wBAAwB,EAAE,gCAAgC;CAClD,CAAC;AAEX,+BAA+B;AAC/B,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,OAAO,mBAAmB,CAAC,CAAC;AAEhG,8DAA8D;AAC9D,wBAAgB,cAAc,CAC5B,IAAI,EAAE,kBAAkB,EACxB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE;IAAE,QAAQ,EAAE,aAAa,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAC3F,UAAU,CAEZ"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAAE,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAErE,4CAA4C;AAC5C,eAAO,MAAM,mBAAmB;IAC9B,8EAA8E;aAC9E,mBAAmB,EAAE,2BAA2B;IAChD,0DAA0D;aAC1D,gBAAgB,EAAE,wBAAwB;IAC1C,wDAAwD;aACxD,gBAAgB,EAAE,wBAAwB;IAC1C;;;;;OAKG;aACH,iBAAiB,EAAE,yBAAyB;IAC5C;;;;;OAKG;aACH,mBAAmB,EAAE,2BAA2B;IAChD,8DAA8D;aAC9D,qBAAqB,EAAE,6BAA6B;IACpD,uEAAuE;aACvE,eAAe,EAAE,uBAAuB;IACxC,iEAAiE;aACjE,YAAY,EAAE,oBAAoB;IAClC,2EAA2E;aAC3E,SAAS,EAAE,iBAAiB;IAC5B,uEAAuE;aACvE,8BAA8B,EAAE,sCAAsC;IACtE,oEAAoE;aACpE,+BAA+B,EAAE,uCAAuC;IACxE,sFAAsF;aACtF,0BAA0B,EAAE,kCAAkC;IAC9D;;;;;;;OAOG;aACH,cAAc,EAAE,sBAAsB;IACtC,yFAAyF;aACzF,wBAAwB,EAAE,gCAAgC;CAClD,CAAC;AAEX,+BAA+B;AAC/B,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,OAAO,mBAAmB,CAAC,CAAC;AAEhG,8DAA8D;AAC9D,wBAAgB,cAAc,CAC5B,IAAI,EAAE,kBAAkB,EACxB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE;IAAE,QAAQ,EAAE,aAAa,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAC3F,UAAU,CAEZ"}

package/dist/errors.js

@@ -37,6 +37,12 @@ export const FileStoreErrorCodes = {
     LOCK_TIMEOUT: "ALDUS_LOCK_TIMEOUT",
     /** A lock was released or renewed by something that no longer holds it. */
     LOCK_LOST: "ALDUS_LOCK_LOST",
+    /** A reservation transition does not satisfy its schema (ADR-0044). */
+    RESERVATION_TRANSITION_INVALID: "ALDUS_RESERVATION_TRANSITION_INVALID",
+    /** One transition id was reused for a different fact (ADR-0044). */
+    RESERVATION_TRANSITION_CONFLICT: "ALDUS_RESERVATION_TRANSITION_CONFLICT",
+    /** A reservation stream has a gap, which no correct writer can produce (ADR-0044). */
+    RESERVATION_STREAM_CORRUPT: "ALDUS_RESERVATION_STREAM_CORRUPT",
     /**
      * A lock was re-acquired inside a scope that already holds it.
      *

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAAsB,MAAM,qBAAqB,CAAC;AAErE,4CAA4C;AAC5C,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,8EAA8E;IAC9E,mBAAmB,EAAE,2BAA2B;IAChD,0DAA0D;IAC1D,gBAAgB,EAAE,wBAAwB;IAC1C,wDAAwD;IACxD,gBAAgB,EAAE,wBAAwB;IAC1C;;;;;OAKG;IACH,iBAAiB,EAAE,yBAAyB;IAC5C;;;;;OAKG;IACH,mBAAmB,EAAE,2BAA2B;IAChD,8DAA8D;IAC9D,qBAAqB,EAAE,6BAA6B;IACpD,uEAAuE;IACvE,eAAe,EAAE,uBAAuB;IACxC,iEAAiE;IACjE,YAAY,EAAE,oBAAoB;IAClC,2EAA2E;IAC3E,SAAS,EAAE,iBAAiB;IAC5B;;;;;;;OAOG;IACH,cAAc,EAAE,sBAAsB;IACtC,yFAAyF;IACzF,wBAAwB,EAAE,gCAAgC;CAClD,CAAC;AAKX,8DAA8D;AAC9D,MAAM,UAAU,cAAc,CAC5B,IAAwB,EACxB,OAAe,EACf,OAA4F;IAE5F,OAAO,IAAI,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;AAChD,CAAC"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAAsB,MAAM,qBAAqB,CAAC;AAErE,4CAA4C;AAC5C,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,8EAA8E;IAC9E,mBAAmB,EAAE,2BAA2B;IAChD,0DAA0D;IAC1D,gBAAgB,EAAE,wBAAwB;IAC1C,wDAAwD;IACxD,gBAAgB,EAAE,wBAAwB;IAC1C;;;;;OAKG;IACH,iBAAiB,EAAE,yBAAyB;IAC5C;;;;;OAKG;IACH,mBAAmB,EAAE,2BAA2B;IAChD,8DAA8D;IAC9D,qBAAqB,EAAE,6BAA6B;IACpD,uEAAuE;IACvE,eAAe,EAAE,uBAAuB;IACxC,iEAAiE;IACjE,YAAY,EAAE,oBAAoB;IAClC,2EAA2E;IAC3E,SAAS,EAAE,iBAAiB;IAC5B,uEAAuE;IACvE,8BAA8B,EAAE,sCAAsC;IACtE,oEAAoE;IACpE,+BAA+B,EAAE,uCAAuC;IACxE,sFAAsF;IACtF,0BAA0B,EAAE,kCAAkC;IAC9D;;;;;;;OAOG;IACH,cAAc,EAAE,sBAAsB;IACtC,yFAAyF;IACzF,wBAAwB,EAAE,gCAAgC;CAClD,CAAC;AAKX,8DAA8D;AAC9D,MAAM,UAAU,cAAc,CAC5B,IAAwB,EACxB,OAAe,EACf,OAA4F;IAE5F,OAAO,IAAI,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;AAChD,CAAC"}

package/dist/index.d.ts

@@ -25,4 +25,5 @@ export { DEFAULT_LOCK_RETRY_MS, DEFAULT_LOCK_TIMEOUT_MS, DEFAULT_LOCK_TTL_MS, Fi
 export type { EpisodeStore, EventReadOptions, EventReadResult, EventStore, RunCollectionName, RunCollectionTypes, RunStore, } from "./ports.js";
 export { FileEpisodeStore, FileEventStore, FileRunStore, RUN_COLLECTION_SCHEMAS, nextSequenceOf, } from "./stores.js";
 export { FileWorkspace, initWorkspace, openWorkspace, type OpenWorkspaceOptions, } from "./workspace.js";
+export { FileSpendReservationStore, type CompareAndAppendResult, type FileSpendReservationStoreOptions, type GrantReservationStream, type SpendReservationStore, } from "./reservation-store.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,UAAU,EACV,SAAS,EACT,mBAAmB,EACnB,eAAe,EACf,eAAe,EACf,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,GACxB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAE7F,OAAO,EACL,aAAa,EACb,aAAa,EACb,eAAe,EACf,YAAY,EACZ,aAAa,EACb,KAAK,cAAc,GACpB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAE3F,OAAO,EACL,cAAc,EACd,aAAa,EACb,UAAU,EACV,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,GAC1B,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,SAAS,EACT,eAAe,EACf,eAAe,EACf,KAAK,WAAW,GACjB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,qBAAqB,EACrB,uBAAuB,EACvB,mBAAmB,EACnB,eAAe,EACf,KAAK,cAAc,EACnB,KAAK,sBAAsB,EAC3B,KAAK,KAAK,EACV,KAAK,WAAW,GACjB,MAAM,WAAW,CAAC;AAEnB,YAAY,EACV,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,UAAU,EACV,iBAAiB,EACjB,kBAAkB,EAClB,QAAQ,GACT,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,sBAAsB,EACtB,cAAc,GACf,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,aAAa,EACb,aAAa,EACb,aAAa,EACb,KAAK,oBAAoB,GAC1B,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,UAAU,EACV,SAAS,EACT,mBAAmB,EACnB,eAAe,EACf,eAAe,EACf,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,GACxB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAE7F,OAAO,EACL,aAAa,EACb,aAAa,EACb,eAAe,EACf,YAAY,EACZ,aAAa,EACb,KAAK,cAAc,GACpB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAE3F,OAAO,EACL,cAAc,EACd,aAAa,EACb,UAAU,EACV,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,GAC1B,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,SAAS,EACT,eAAe,EACf,eAAe,EACf,KAAK,WAAW,GACjB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,qBAAqB,EACrB,uBAAuB,EACvB,mBAAmB,EACnB,eAAe,EACf,KAAK,cAAc,EACnB,KAAK,sBAAsB,EAC3B,KAAK,KAAK,EACV,KAAK,WAAW,GACjB,MAAM,WAAW,CAAC;AAEnB,YAAY,EACV,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,UAAU,EACV,iBAAiB,EACjB,kBAAkB,EAClB,QAAQ,GACT,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,sBAAsB,EACtB,cAAc,GACf,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,aAAa,EACb,aAAa,EACb,aAAa,EACb,KAAK,oBAAoB,GAC1B,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,yBAAyB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,gCAAgC,EACrC,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,GAC3B,MAAM,wBAAwB,CAAC"}

package/dist/index.js

@@ -24,4 +24,5 @@ export { ALDUS_DIRECTORY, EPISODE_LOCK_RESOURCE, RUN_FILES, WorkspaceLayout, run
 export { DEFAULT_LOCK_RETRY_MS, DEFAULT_LOCK_TIMEOUT_MS, DEFAULT_LOCK_TTL_MS, FileLockManager, } from "./lock.js";
 export { FileEpisodeStore, FileEventStore, FileRunStore, RUN_COLLECTION_SCHEMAS, nextSequenceOf, } from "./stores.js";
 export { FileWorkspace, initWorkspace, openWorkspace, } from "./workspace.js";
+export { FileSpendReservationStore, } from "./reservation-store.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,UAAU,EACV,SAAS,EACT,mBAAmB,EACnB,eAAe,EACf,eAAe,GAGhB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAyB,MAAM,kBAAkB,CAAC;AAE7F,OAAO,EACL,aAAa,EACb,aAAa,EACb,eAAe,EACf,YAAY,EACZ,aAAa,GAEd,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAA2B,MAAM,aAAa,CAAC;AAE3F,OAAO,EACL,cAAc,EACd,aAAa,EACb,UAAU,GAGX,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,SAAS,EACT,eAAe,EACf,eAAe,GAEhB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,qBAAqB,EACrB,uBAAuB,EACvB,mBAAmB,EACnB,eAAe,GAKhB,MAAM,WAAW,CAAC;AAYnB,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,sBAAsB,EACtB,cAAc,GACf,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,aAAa,EACb,aAAa,EACb,aAAa,GAEd,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,UAAU,EACV,SAAS,EACT,mBAAmB,EACnB,eAAe,EACf,eAAe,GAGhB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAyB,MAAM,kBAAkB,CAAC;AAE7F,OAAO,EACL,aAAa,EACb,aAAa,EACb,eAAe,EACf,YAAY,EACZ,aAAa,GAEd,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAA2B,MAAM,aAAa,CAAC;AAE3F,OAAO,EACL,cAAc,EACd,aAAa,EACb,UAAU,GAGX,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,SAAS,EACT,eAAe,EACf,eAAe,GAEhB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,qBAAqB,EACrB,uBAAuB,EACvB,mBAAmB,EACnB,eAAe,GAKhB,MAAM,WAAW,CAAC;AAYnB,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,sBAAsB,EACtB,cAAc,GACf,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,aAAa,EACb,aAAa,EACb,aAAa,GAEd,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,yBAAyB,GAK1B,MAAM,wBAAwB,CAAC"}

package/dist/reservation-store.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Durable storage for spend reservation transitions (ADR-0044; #155 step 2).
+ *
+ * The store owns **durability**: schema validation, transition-identity uniqueness,
+ * expected-revision atomicity, the durable commit. It does not own the reservation lifecycle —
+ * a store that knew the state machine would be a store making policy, and `SpendService` owns that.
+ *
+ * ## Why there is no `append()`
+ *
+ * An unconditional append beside a conditional one is an unsafe API a future caller reaches for,
+ * so the unsafe path is unrepresentable rather than discouraged.
+ *
+ * ## Why the lease is not the safety property
+ *
+ * `LockManager` **detects** lease loss; it does not fence. `withLock` reports `LOCK_LOST` after the
+ * body has run, so a holder that lost its lease can still write in the interval before it finds
+ * out. A revision comparison followed by an ordinary write is therefore still check-then-act: two
+ * writers can both pass the check at revision N, and a replacing write lets the slower one destroy
+ * the faster one's committed transition.
+ *
+ * The linearization point is `link()`, which refuses to replace an existing target. One commit file
+ * **is** one revision, so exactly one writer can create a given name.
+ */
+import { type SpendReservation, type SpendReservationTransition } from "@aldus-runtime/core";
+import type { LockManager } from "./lock.js";
+/** A grant's committed history, and the revision a writer must expect to still be current. */
+export interface GrantReservationStream {
+    grantId: string;
+    /**
+     * Number of **commits**, not of transitions.
+     *
+     * One commit may carry several transitions — a reconciliation must land atomically with the
+     * settlement it justifies. Defining this as `transitions.length` would make the revision depend
+     * on batch shapes, so two writers proposing different batches could compute the same expected
+     * revision from different histories.
+     */
+    revision: number;
+    /** Every transition, flattened across commits, in commit order. For reduction. */
+    transitions: readonly SpendReservationTransition[];
+}
+/** @see SpendReservationStore.compareAndAppend */
+export type CompareAndAppendResult = 
+/** This call created a new durable fact. */
+{
+    kind: "appended";
+    revision: number;
+}
+/** These exact transitions were already committed, by an earlier attempt of this same call. */
+ | {
+    kind: "already_present";
+    revision: number;
+}
+/** Another commit won the successor of the expected revision. Re-read and recompute. */
+ | {
+    kind: "conflict";
+    currentRevision: number;
+};
+/** Durable transition storage with atomic conditional commit (ADR-0044). */
+export interface SpendReservationStore {
+    readGrant(grantId: string): Promise<GrantReservationStream>;
+    /**
+     * Commit iff the stream is still at `expectedRevision`.
+     *
+     * Decision order, so a retry is deterministic:
+     *
+     * 1. every supplied identity present with byte-identical contents → `already_present`;
+     * 2. any supplied identity present with different contents → refuse;
+     * 3. `expectedRevision` stale → `conflict`;
+     * 4. otherwise attempt the conditional commit.
+     *
+     * Rule 1 outranks rule 3 so a caller that committed and lost the response terminates instead of
+     * looping to rediscover its own success.
+     */
+    compareAndAppend(input: {
+        grantId: string;
+        expectedRevision: number;
+        transitions: readonly SpendReservationTransition[];
+    }): Promise<CompareAndAppendResult>;
+    get(reservationId: string): Promise<SpendReservation | undefined>;
+    listByRun(runId: string): Promise<readonly SpendReservation[]>;
+}
+/** Wiring for {@link FileSpendReservationStore}. */
+export interface FileSpendReservationStoreOptions {
+    root: string;
+    /** Reduces contention. **Not** the correctness mechanism — see the module docstring. */
+    locks?: LockManager;
+}
+export declare class FileSpendReservationStore implements SpendReservationStore {
+    #private;
+    constructor(options: FileSpendReservationStoreOptions);
+    readGrant(grantId: string): Promise<GrantReservationStream>;
+    compareAndAppend(input: {
+        grantId: string;
+        expectedRevision: number;
+        transitions: readonly SpendReservationTransition[];
+    }): Promise<CompareAndAppendResult>;
+    get(reservationId: string): Promise<SpendReservation | undefined>;
+    listByRun(runId: string): Promise<readonly SpendReservation[]>;
+    /**
+     * Where this store looks. Exposed so a refusal can name the path it searched: "no reservation
+     * here" and "I could not look" read identically to an operator otherwise (§19.2).
+     */
+    get root(): string;
+}
+//# sourceMappingURL=reservation-store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reservation-store.d.ts","sourceRoot":"","sources":["../src/reservation-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAKH,OAAO,EAGL,KAAK,gBAAgB,EACrB,KAAK,0BAA0B,EAChC,MAAM,qBAAqB,CAAC;AAG7B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C,8FAA8F;AAC9F,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;;OAOG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,WAAW,EAAE,SAAS,0BAA0B,EAAE,CAAC;CACpD;AAED,kDAAkD;AAClD,MAAM,MAAM,sBAAsB;AAChC,4CAA4C;AAC1C;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE;AACxC,+FAA+F;GAC7F;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE;AAC/C,wFAAwF;GACtF;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,eAAe,EAAE,MAAM,CAAA;CAAE,CAAC;AAElD,4EAA4E;AAC5E,MAAM,WAAW,qBAAqB;IACpC,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAC5D;;;;;;;;;;;;OAYG;IACH,gBAAgB,CAAC,KAAK,EAAE;QACtB,OAAO,EAAE,MAAM,CAAC;QAChB,gBAAgB,EAAE,MAAM,CAAC;QACzB,WAAW,EAAE,SAAS,0BAA0B,EAAE,CAAC;KACpD,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;IACpC,GAAG,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAAC;IAClE,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,gBAAgB,EAAE,CAAC,CAAC;CAChE;AAQD,oDAAoD;AACpD,MAAM,WAAW,gCAAgC;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,wFAAwF;IACxF,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB;AAOD,qBAAa,yBAA0B,YAAW,qBAAqB;;IAIrE,YAAY,OAAO,EAAE,gCAAgC,EAGpD;IAEK,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAOhE;IAEK,gBAAgB,CAAC,KAAK,EAAE;QAC5B,OAAO,EAAE,MAAM,CAAC;QAChB,gBAAgB,EAAE,MAAM,CAAC;QACzB,WAAW,EAAE,SAAS,0BAA0B,EAAE,CAAC;KACpD,GAAG,OAAO,CAAC,sBAAsB,CAAC,CA0ClC;IAEK,GAAG,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAYtE;IAEK,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,gBAAgB,EAAE,CAAC,CAanE;IAuFD;;;OAGG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;CAgEF"}

package/dist/reservation-store.js

@@ -0,0 +1,249 @@
+/**
+ * Durable storage for spend reservation transitions (ADR-0044; #155 step 2).
+ *
+ * The store owns **durability**: schema validation, transition-identity uniqueness,
+ * expected-revision atomicity, the durable commit. It does not own the reservation lifecycle —
+ * a store that knew the state machine would be a store making policy, and `SpendService` owns that.
+ *
+ * ## Why there is no `append()`
+ *
+ * An unconditional append beside a conditional one is an unsafe API a future caller reaches for,
+ * so the unsafe path is unrepresentable rather than discouraged.
+ *
+ * ## Why the lease is not the safety property
+ *
+ * `LockManager` **detects** lease loss; it does not fence. `withLock` reports `LOCK_LOST` after the
+ * body has run, so a holder that lost its lease can still write in the interval before it finds
+ * out. A revision comparison followed by an ordinary write is therefore still check-then-act: two
+ * writers can both pass the check at revision N, and a replacing write lets the slower one destroy
+ * the faster one's committed transition.
+ *
+ * The linearization point is `link()`, which refuses to replace an existing target. One commit file
+ * **is** one revision, so exactly one writer can create a given name.
+ */
+import { link, mkdir, open, readdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { spendReservationTransitionSchema, reduceReservations, } from "@aldus-runtime/core";
+import { FileStoreErrorCodes, fileStoreError } from "./errors.js";
+// The store has no retry policy on purpose. A conflict is returned, not absorbed: the caller's
+// availability answer was computed against a stream that no longer exists, and only the caller can
+// recompute it. A store that retried internally would hide that from the caller — the same reason
+// ADR-0044 rejects a callback transaction.
+export class FileSpendReservationStore {
+    #root;
+    #locks;
+    constructor(options) {
+        this.#root = options.root;
+        this.#locks = options.locks;
+    }
+    async readGrant(grantId) {
+        const commits = await this.#readCommits(grantId);
+        return {
+            grantId,
+            revision: commits.length,
+            transitions: commits.flatMap((commit) => commit.transitions),
+        };
+    }
+    async compareAndAppend(input) {
+        for (const transition of input.transitions) {
+            const parsed = spendReservationTransitionSchema.safeParse(transition);
+            if (!parsed.success) {
+                throw fileStoreError(FileStoreErrorCodes.RESERVATION_TRANSITION_INVALID, "A reservation transition does not satisfy its schema, so it must not become durable.", {
+                    category: "validation",
+                    retryable: false,
+                    details: { grantId: input.grantId, issue: parsed.error.issues[0]?.path.join(".") },
+                });
+            }
+        }
+        const commit = async () => {
+            const commits = await this.#readCommits(input.grantId);
+            const identity = this.#checkIdentities(commits, input.transitions, input.grantId);
+            if (identity !== undefined)
+                return identity;
+            if (commits.length !== input.expectedRevision) {
+                return { kind: "conflict", currentRevision: commits.length };
+            }
+            return this.#install(input.grantId, commits.length + 1, [...input.transitions]);
+        };
+        // The lease reduces contention and nothing more: `#install` is safe without it, because
+        // `link()` refuses to replace a winner. If the lease is lost, the commit's own identity is
+        // what answers whether it landed — see `#install`.
+        const locks = this.#locks;
+        if (locks === undefined)
+            return commit();
+        try {
+            return await locks.withLock(`spend-reservation:${input.grantId}`, commit);
+        }
+        catch (error) {
+            // `LOCK_LOST` after a successful commit is not a failure: the commit is immutable and ours.
+            if (error.code === FileStoreErrorCodes.LOCK_LOST) {
+                const commits = await this.#readCommits(input.grantId);
+                const identity = this.#checkIdentities(commits, input.transitions, input.grantId);
+                if (identity !== undefined)
+                    return identity;
+            }
+            throw error;
+        }
+    }
+    async get(reservationId) {
+        // An index would be a hint, and a hint cannot establish absence: a syntactically valid but
+        // stale index is missing the newest reservation, and nothing about it looks damaged. So a miss
+        // scans the canonical streams rather than returning `undefined` (ADR-0044).
+        for (const grantId of await this.#grantIds()) {
+            const stream = await this.readGrant(grantId);
+            const found = reduceReservations(stream.transitions).find((reservation) => reservation.reservationId === reservationId);
+            if (found !== undefined)
+                return found;
+        }
+        return undefined;
+    }
+    async listByRun(runId) {
+        // Scans for the same reason: completeness is a claim about everything, and an index is a claim
+        // about what it happened to record.
+        const found = [];
+        for (const grantId of await this.#grantIds()) {
+            const stream = await this.readGrant(grantId);
+            found.push(...reduceReservations(stream.transitions).filter((reservation) => reservation.runId === runId));
+        }
+        return found;
+    }
+    /** Rule 1 and rule 2 of the decision order. */
+    #checkIdentities(commits, proposed, grantId) {
+        const present = new Map();
+        for (const commit of commits) {
+            for (const transition of commit.transitions)
+                present.set(transition.transitionId, transition);
+        }
+        let allPresent = proposed.length > 0;
+        for (const transition of proposed) {
+            const existing = present.get(transition.transitionId);
+            if (existing === undefined) {
+                allPresent = false;
+                continue;
+            }
+            if (JSON.stringify(existing) !== JSON.stringify(transition)) {
+                throw fileStoreError(FileStoreErrorCodes.RESERVATION_TRANSITION_CONFLICT, `Transition "${transition.transitionId}" already exists with different contents. Two ` +
+                    "different facts under one identity cannot both be true, so this is refused rather " +
+                    "than resolved (ADR-0044).", {
+                    category: "conflict",
+                    retryable: false,
+                    details: { grantId, transitionId: transition.transitionId },
+                });
+            }
+        }
+        return allPresent ? { kind: "already_present", revision: commits.length } : undefined;
+    }
+    /**
+     * The linearization point, and the durability step after it.
+     *
+     * `link()` wins the revision; the directory `fsync` is what permits acknowledging it. Between the
+     * two the writer has won and cannot prove it survived a power loss, so the commit is not
+     * reported as appended — the caller retries with the same stable identities and rule 1 resolves
+     * it either way.
+     */
+    async #install(grantId, revision, transitions) {
+        const dir = join(this.#root, grantId, "commits");
+        await mkdir(dir, { recursive: true });
+        const final = join(dir, `${String(revision).padStart(6, "0")}.json`);
+        const temp = `${final}.${Math.random().toString(36).slice(2)}.tmp`;
+        const payload = { revision, transitions };
+        // Complete before visible: a partial file that *exists* would block the true winner from this
+        // revision forever, which is why this is not `open(final, "wx")` and a direct write.
+        await writeFile(temp, JSON.stringify(payload), "utf8");
+        await this.#fsync(temp);
+        try {
+            await link(temp, final);
+        }
+        catch (error) {
+            await unlink(temp).catch(() => undefined);
+            if (error.code === "EEXIST") {
+                const commits = await this.#readCommits(grantId);
+                return { kind: "conflict", currentRevision: commits.length };
+            }
+            throw error;
+        }
+        await unlink(temp).catch(() => undefined);
+        // Durability, separate from linearization. Only after this may the commit be acknowledged.
+        await this.#fsync(dir);
+        return { kind: "appended", revision };
+    }
+    async #fsync(path) {
+        const handle = await open(path, "r").catch(() => undefined);
+        if (handle === undefined)
+            return;
+        try {
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    /**
+     * Where this store looks. Exposed so a refusal can name the path it searched: "no reservation
+     * here" and "I could not look" read identically to an operator otherwise (§19.2).
+     */
+    get root() {
+        return this.#root;
+    }
+    async #grantIds() {
+        try {
+            return (await readdir(this.#root, { withFileTypes: true }))
+                .filter((entry) => entry.isDirectory())
+                .map((entry) => entry.name);
+        }
+        catch (error) {
+            // A root that does not exist yet is a workspace that has reserved nothing — an ordinary
+            // empty answer. Anything else is the instrument failing to look: a permission error, a file
+            // where the directory should be, a root pointed at a composition's idea of the layout rather
+            // than this one's. Swallowing those returned `[]`, and `[]` is indistinguishable from a
+            // truthful "no reservations" — so `costs` reported an empty ledger for a workspace holding
+            // real money and `settle` answered "holds no reservation", both stating a fact about the
+            // world when the instrument had never reached it.
+            //
+            // The distinction is the point: an empty answer must come from an empty store, never from a
+            // failure to read one.
+            if (error.code === "ENOENT")
+                return [];
+            throw error;
+        }
+    }
+    async #readCommits(grantId) {
+        const dir = join(this.#root, grantId, "commits");
+        let names;
+        try {
+            names = (await readdir(dir)).filter((name) => name.endsWith(".json")).sort();
+        }
+        catch (error) {
+            // The same distinction `#grantIds` makes, one level down, where it was still missing.
+            // A grant directory that does not exist is a grant that has committed nothing — an ordinary
+            // empty answer. A permission error, a file where the directory should be, an I/O failure:
+            // those are the instrument failing to look, and returning `[]` for them made a grant holding
+            // a live reservation read as "nothing reserved" to `costs`, to `settle`, and to every caller
+            // that asks what authorization is committed.
+            //
+            // An empty answer must come from an empty store, never from a failure to read one.
+            if (error.code === "ENOENT")
+                return [];
+            throw error;
+        }
+        const commits = [];
+        for (const [index, name] of names.entries()) {
+            const parsed = JSON.parse(await readFile(join(dir, name), "utf8"));
+            // A gap is not producible by a correct writer — a commit may only claim N+1 having read N as
+            // current — so a gap is corruption. Refusing beats reducing a shorter stream and reporting a
+            // smaller balance as though it were the answer.
+            if (parsed.revision !== index + 1) {
+                throw fileStoreError(FileStoreErrorCodes.RESERVATION_STREAM_CORRUPT, `The reservation stream for grant "${grantId}" is missing revision ${index + 1}. A gap ` +
+                    "cannot be produced by a correct writer, so this stream is not projected: a shorter " +
+                    "history would understate committed authorization.", {
+                    category: "conflict",
+                    retryable: false,
+                    details: { grantId, expectedRevision: index + 1, found: parsed.revision },
+                });
+            }
+            commits.push(parsed);
+        }
+        return commits;
+    }
+}
+//# sourceMappingURL=reservation-store.js.map

package/dist/reservation-store.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aldus-runtime/file-store",
-  "version": "0.2.0-next.6",
+  "version": "0.2.0-next.60",
   "type": "module",
   "description": "Aldus File Store — file-backed Episode, Run, and Event stores with atomic writes and crash recovery.",
   "license": "Apache-2.0",
@@ -33,10 +33,10 @@
     "typecheck:test": "tsc -p tsconfig.test.json"
   },
   "dependencies": {
-    "@aldus-runtime/core": "0.2.0-next.6"
+    "@aldus-runtime/core": "0.2.0-next.60"
   },
   "devDependencies": {
-    "@aldus-runtime/testkit": "0.2.0-next.6",
+    "@aldus-runtime/testkit": "0.2.0-next.60",
     "@types/node": "^26.2.0",
     "typescript": "^7.0.2",
     "vitest": "^4.1.10"

package/src/errors.ts

@@ -39,6 +39,12 @@ export const FileStoreErrorCodes = {
   LOCK_TIMEOUT: "ALDUS_LOCK_TIMEOUT",
   /** A lock was released or renewed by something that no longer holds it. */
   LOCK_LOST: "ALDUS_LOCK_LOST",
+  /** A reservation transition does not satisfy its schema (ADR-0044). */
+  RESERVATION_TRANSITION_INVALID: "ALDUS_RESERVATION_TRANSITION_INVALID",
+  /** One transition id was reused for a different fact (ADR-0044). */
+  RESERVATION_TRANSITION_CONFLICT: "ALDUS_RESERVATION_TRANSITION_CONFLICT",
+  /** A reservation stream has a gap, which no correct writer can produce (ADR-0044). */
+  RESERVATION_STREAM_CORRUPT: "ALDUS_RESERVATION_STREAM_CORRUPT",
   /**
    * A lock was re-acquired inside a scope that already holds it.
    *

package/src/index.ts

@@ -94,3 +94,11 @@ export {
   openWorkspace,
   type OpenWorkspaceOptions,
 } from "./workspace.js";
+
+export {
+  FileSpendReservationStore,
+  type CompareAndAppendResult,
+  type FileSpendReservationStoreOptions,
+  type GrantReservationStream,
+  type SpendReservationStore,
+} from "./reservation-store.js";

package/src/reservation-store.ts

@@ -0,0 +1,356 @@
+/**
+ * Durable storage for spend reservation transitions (ADR-0044; #155 step 2).
+ *
+ * The store owns **durability**: schema validation, transition-identity uniqueness,
+ * expected-revision atomicity, the durable commit. It does not own the reservation lifecycle —
+ * a store that knew the state machine would be a store making policy, and `SpendService` owns that.
+ *
+ * ## Why there is no `append()`
+ *
+ * An unconditional append beside a conditional one is an unsafe API a future caller reaches for,
+ * so the unsafe path is unrepresentable rather than discouraged.
+ *
+ * ## Why the lease is not the safety property
+ *
+ * `LockManager` **detects** lease loss; it does not fence. `withLock` reports `LOCK_LOST` after the
+ * body has run, so a holder that lost its lease can still write in the interval before it finds
+ * out. A revision comparison followed by an ordinary write is therefore still check-then-act: two
+ * writers can both pass the check at revision N, and a replacing write lets the slower one destroy
+ * the faster one's committed transition.
+ *
+ * The linearization point is `link()`, which refuses to replace an existing target. One commit file
+ * **is** one revision, so exactly one writer can create a given name.
+ */
+
+import { link, mkdir, open, readdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import {
+  spendReservationTransitionSchema,
+  reduceReservations,
+  type SpendReservation,
+  type SpendReservationTransition,
+} from "@aldus-runtime/core";
+
+import { FileStoreErrorCodes, fileStoreError } from "./errors.js";
+import type { LockManager } from "./lock.js";
+
+/** A grant's committed history, and the revision a writer must expect to still be current. */
+export interface GrantReservationStream {
+  grantId: string;
+  /**
+   * Number of **commits**, not of transitions.
+   *
+   * One commit may carry several transitions — a reconciliation must land atomically with the
+   * settlement it justifies. Defining this as `transitions.length` would make the revision depend
+   * on batch shapes, so two writers proposing different batches could compute the same expected
+   * revision from different histories.
+   */
+  revision: number;
+  /** Every transition, flattened across commits, in commit order. For reduction. */
+  transitions: readonly SpendReservationTransition[];
+}
+
+/** @see SpendReservationStore.compareAndAppend */
+export type CompareAndAppendResult =
+  /** This call created a new durable fact. */
+  | { kind: "appended"; revision: number }
+  /** These exact transitions were already committed, by an earlier attempt of this same call. */
+  | { kind: "already_present"; revision: number }
+  /** Another commit won the successor of the expected revision. Re-read and recompute. */
+  | { kind: "conflict"; currentRevision: number };
+
+/** Durable transition storage with atomic conditional commit (ADR-0044). */
+export interface SpendReservationStore {
+  readGrant(grantId: string): Promise<GrantReservationStream>;
+  /**
+   * Commit iff the stream is still at `expectedRevision`.
+   *
+   * Decision order, so a retry is deterministic:
+   *
+   * 1. every supplied identity present with byte-identical contents → `already_present`;
+   * 2. any supplied identity present with different contents → refuse;
+   * 3. `expectedRevision` stale → `conflict`;
+   * 4. otherwise attempt the conditional commit.
+   *
+   * Rule 1 outranks rule 3 so a caller that committed and lost the response terminates instead of
+   * looping to rediscover its own success.
+   */
+  compareAndAppend(input: {
+    grantId: string;
+    expectedRevision: number;
+    transitions: readonly SpendReservationTransition[];
+  }): Promise<CompareAndAppendResult>;
+  get(reservationId: string): Promise<SpendReservation | undefined>;
+  listByRun(runId: string): Promise<readonly SpendReservation[]>;
+}
+
+/** One committed batch, as stored. */
+interface CommitFile {
+  revision: number;
+  transitions: SpendReservationTransition[];
+}
+
+/** Wiring for {@link FileSpendReservationStore}. */
+export interface FileSpendReservationStoreOptions {
+  root: string;
+  /** Reduces contention. **Not** the correctness mechanism — see the module docstring. */
+  locks?: LockManager;
+}
+
+// The store has no retry policy on purpose. A conflict is returned, not absorbed: the caller's
+// availability answer was computed against a stream that no longer exists, and only the caller can
+// recompute it. A store that retried internally would hide that from the caller — the same reason
+// ADR-0044 rejects a callback transaction.
+
+export class FileSpendReservationStore implements SpendReservationStore {
+  readonly #root: string;
+  readonly #locks: LockManager | undefined;
+
+  constructor(options: FileSpendReservationStoreOptions) {
+    this.#root = options.root;
+    this.#locks = options.locks;
+  }
+
+  async readGrant(grantId: string): Promise<GrantReservationStream> {
+    const commits = await this.#readCommits(grantId);
+    return {
+      grantId,
+      revision: commits.length,
+      transitions: commits.flatMap((commit) => commit.transitions),
+    };
+  }
+
+  async compareAndAppend(input: {
+    grantId: string;
+    expectedRevision: number;
+    transitions: readonly SpendReservationTransition[];
+  }): Promise<CompareAndAppendResult> {
+    for (const transition of input.transitions) {
+      const parsed = spendReservationTransitionSchema.safeParse(transition);
+      if (!parsed.success) {
+        throw fileStoreError(
+          FileStoreErrorCodes.RESERVATION_TRANSITION_INVALID,
+          "A reservation transition does not satisfy its schema, so it must not become durable.",
+          {
+            category: "validation",
+            retryable: false,
+            details: { grantId: input.grantId, issue: parsed.error.issues[0]?.path.join(".") },
+          },
+        );
+      }
+    }
+
+    const commit = async (): Promise<CompareAndAppendResult> => {
+      const commits = await this.#readCommits(input.grantId);
+      const identity = this.#checkIdentities(commits, input.transitions, input.grantId);
+      if (identity !== undefined) return identity;
+      if (commits.length !== input.expectedRevision) {
+        return { kind: "conflict", currentRevision: commits.length };
+      }
+      return this.#install(input.grantId, commits.length + 1, [...input.transitions]);
+    };
+
+    // The lease reduces contention and nothing more: `#install` is safe without it, because
+    // `link()` refuses to replace a winner. If the lease is lost, the commit's own identity is
+    // what answers whether it landed — see `#install`.
+    const locks = this.#locks;
+    if (locks === undefined) return commit();
+    try {
+      return await locks.withLock(`spend-reservation:${input.grantId}`, commit);
+    } catch (error) {
+      // `LOCK_LOST` after a successful commit is not a failure: the commit is immutable and ours.
+      if ((error as { code?: string }).code === FileStoreErrorCodes.LOCK_LOST) {
+        const commits = await this.#readCommits(input.grantId);
+        const identity = this.#checkIdentities(commits, input.transitions, input.grantId);
+        if (identity !== undefined) return identity;
+      }
+      throw error;
+    }
+  }
+
+  async get(reservationId: string): Promise<SpendReservation | undefined> {
+    // An index would be a hint, and a hint cannot establish absence: a syntactically valid but
+    // stale index is missing the newest reservation, and nothing about it looks damaged. So a miss
+    // scans the canonical streams rather than returning `undefined` (ADR-0044).
+    for (const grantId of await this.#grantIds()) {
+      const stream = await this.readGrant(grantId);
+      const found = reduceReservations(stream.transitions).find(
+        (reservation) => reservation.reservationId === reservationId,
+      );
+      if (found !== undefined) return found;
+    }
+    return undefined;
+  }
+
+  async listByRun(runId: string): Promise<readonly SpendReservation[]> {
+    // Scans for the same reason: completeness is a claim about everything, and an index is a claim
+    // about what it happened to record.
+    const found: SpendReservation[] = [];
+    for (const grantId of await this.#grantIds()) {
+      const stream = await this.readGrant(grantId);
+      found.push(
+        ...reduceReservations(stream.transitions).filter(
+          (reservation) => reservation.runId === runId,
+        ),
+      );
+    }
+    return found;
+  }
+
+  /** Rule 1 and rule 2 of the decision order. */
+  #checkIdentities(
+    commits: readonly CommitFile[],
+    proposed: readonly SpendReservationTransition[],
+    grantId: string,
+  ): CompareAndAppendResult | undefined {
+    const present = new Map<string, SpendReservationTransition>();
+    for (const commit of commits) {
+      for (const transition of commit.transitions) present.set(transition.transitionId, transition);
+    }
+
+    let allPresent = proposed.length > 0;
+    for (const transition of proposed) {
+      const existing = present.get(transition.transitionId);
+      if (existing === undefined) {
+        allPresent = false;
+        continue;
+      }
+      if (JSON.stringify(existing) !== JSON.stringify(transition)) {
+        throw fileStoreError(
+          FileStoreErrorCodes.RESERVATION_TRANSITION_CONFLICT,
+          `Transition "${transition.transitionId}" already exists with different contents. Two ` +
+            "different facts under one identity cannot both be true, so this is refused rather " +
+            "than resolved (ADR-0044).",
+          {
+            category: "conflict",
+            retryable: false,
+            details: { grantId, transitionId: transition.transitionId },
+          },
+        );
+      }
+    }
+    return allPresent ? { kind: "already_present", revision: commits.length } : undefined;
+  }
+
+  /**
+   * The linearization point, and the durability step after it.
+   *
+   * `link()` wins the revision; the directory `fsync` is what permits acknowledging it. Between the
+   * two the writer has won and cannot prove it survived a power loss, so the commit is not
+   * reported as appended — the caller retries with the same stable identities and rule 1 resolves
+   * it either way.
+   */
+  async #install(
+    grantId: string,
+    revision: number,
+    transitions: SpendReservationTransition[],
+  ): Promise<CompareAndAppendResult> {
+    const dir = join(this.#root, grantId, "commits");
+    await mkdir(dir, { recursive: true });
+    const final = join(dir, `${String(revision).padStart(6, "0")}.json`);
+    const temp = `${final}.${Math.random().toString(36).slice(2)}.tmp`;
+
+    const payload: CommitFile = { revision, transitions };
+    // Complete before visible: a partial file that *exists* would block the true winner from this
+    // revision forever, which is why this is not `open(final, "wx")` and a direct write.
+    await writeFile(temp, JSON.stringify(payload), "utf8");
+    await this.#fsync(temp);
+
+    try {
+      await link(temp, final);
+    } catch (error) {
+      await unlink(temp).catch(() => undefined);
+      if ((error as NodeJS.ErrnoException).code === "EEXIST") {
+        const commits = await this.#readCommits(grantId);
+        return { kind: "conflict", currentRevision: commits.length };
+      }
+      throw error;
+    }
+    await unlink(temp).catch(() => undefined);
+    // Durability, separate from linearization. Only after this may the commit be acknowledged.
+    await this.#fsync(dir);
+    return { kind: "appended", revision };
+  }
+
+  async #fsync(path: string): Promise<void> {
+    const handle = await open(path, "r").catch(() => undefined);
+    if (handle === undefined) return;
+    try {
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+  }
+
+  /**
+   * Where this store looks. Exposed so a refusal can name the path it searched: "no reservation
+   * here" and "I could not look" read identically to an operator otherwise (§19.2).
+   */
+  get root(): string {
+    return this.#root;
+  }
+
+  async #grantIds(): Promise<string[]> {
+    try {
+      return (await readdir(this.#root, { withFileTypes: true }))
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name);
+    } catch (error) {
+      // A root that does not exist yet is a workspace that has reserved nothing — an ordinary
+      // empty answer. Anything else is the instrument failing to look: a permission error, a file
+      // where the directory should be, a root pointed at a composition's idea of the layout rather
+      // than this one's. Swallowing those returned `[]`, and `[]` is indistinguishable from a
+      // truthful "no reservations" — so `costs` reported an empty ledger for a workspace holding
+      // real money and `settle` answered "holds no reservation", both stating a fact about the
+      // world when the instrument had never reached it.
+      //
+      // The distinction is the point: an empty answer must come from an empty store, never from a
+      // failure to read one.
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+      throw error;
+    }
+  }
+
+  async #readCommits(grantId: string): Promise<CommitFile[]> {
+    const dir = join(this.#root, grantId, "commits");
+    let names: string[];
+    try {
+      names = (await readdir(dir)).filter((name) => name.endsWith(".json")).sort();
+    } catch (error) {
+      // The same distinction `#grantIds` makes, one level down, where it was still missing.
+      // A grant directory that does not exist is a grant that has committed nothing — an ordinary
+      // empty answer. A permission error, a file where the directory should be, an I/O failure:
+      // those are the instrument failing to look, and returning `[]` for them made a grant holding
+      // a live reservation read as "nothing reserved" to `costs`, to `settle`, and to every caller
+      // that asks what authorization is committed.
+      //
+      // An empty answer must come from an empty store, never from a failure to read one.
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+      throw error;
+    }
+
+    const commits: CommitFile[] = [];
+    for (const [index, name] of names.entries()) {
+      const parsed = JSON.parse(await readFile(join(dir, name), "utf8")) as CommitFile;
+      // A gap is not producible by a correct writer — a commit may only claim N+1 having read N as
+      // current — so a gap is corruption. Refusing beats reducing a shorter stream and reporting a
+      // smaller balance as though it were the answer.
+      if (parsed.revision !== index + 1) {
+        throw fileStoreError(
+          FileStoreErrorCodes.RESERVATION_STREAM_CORRUPT,
+          `The reservation stream for grant "${grantId}" is missing revision ${index + 1}. A gap ` +
+            "cannot be produced by a correct writer, so this stream is not projected: a shorter " +
+            "history would understate committed authorization.",
+          {
+            category: "conflict",
+            retryable: false,
+            details: { grantId, expectedRevision: index + 1, found: parsed.revision },
+          },
+        );
+      }
+      commits.push(parsed);
+    }
+    return commits;
+  }
+}