@stateledger/memory 0.0.1-experimental.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Enow Divine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# @stateledger/memory
+
+> In-memory adapter for [stateledger](https://github.com/enowdivine/stateledger).
+> Use it for tests, hello-world demos, and prototyping — **not production**.
+> State is lost on process exit.
+
+> ⚠️ **Placeholder release.** This `experimental` tag exists alongside the
+> rest of the `@stateledger/*` scope while the API stabilizes. The first
+> real release will publish to the `latest` tag.
+
+---
+
+## Install
+
+```
+pnpm add @stateledger/core @stateledger/memory
+```
+
+## Use
+
+```ts
+import { defineMachine } from "@stateledger/core";
+import { InMemoryAdapter } from "@stateledger/memory";
+
+const PaymentMachine = defineMachine({
+  name: "payment",
+  states: ["pending", "authorized", "captured", "settled"],
+  initialState: "pending",
+  transitions: [
+    { from: "pending",    to: "authorized" },
+    { from: "authorized", to: "captured" },
+    { from: "captured",   to: "settled" },
+  ],
+} as const);
+
+const adapter = new InMemoryAdapter();
+const machine = PaymentMachine.for("payment-1", { adapter });
+
+await machine.transitionTo("pending");      // bootstrap
+await machine.transitionTo("authorized");
+await machine.transitionTo("captured");
+
+console.log(await machine.history());
+// [
+//   { fromState: null,         toState: "pending",    sortKey: 1, ... },
+//   { fromState: "pending",    toState: "authorized", sortKey: 2, ... },
+//   { fromState: "authorized", toState: "captured",   sortKey: 3, ... },
+// ]
+```
+
+## When to use this
+
+- **Unit tests** in user code. Spin up a fresh adapter per test, no DB setup.
+- **Hello-world demos** in documentation or tutorials.
+- **Prototyping** an API design before wiring up real persistence.
+
+## When NOT to use it
+
+- Anything where you'd be sad if a server restart wiped the state.
+
+For production, use [`@stateledger/prisma`](https://www.npmjs.com/package/@stateledger/prisma)
+(coming soon) or another persistent adapter.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,112 @@
+'use strict';
+
+var core = require('@stateledger/core');
+
+// src/in-memory-adapter.ts
+var KeyedMutex = class {
+  queues = /* @__PURE__ */ new Map();
+  async acquire(key) {
+    let release;
+    const next = new Promise((resolve) => {
+      release = resolve;
+    });
+    const prev = this.queues.get(key) ?? Promise.resolve();
+    this.queues.set(
+      key,
+      prev.then(() => next)
+    );
+    await prev;
+    return () => {
+      if (this.queues.get(key) === prev.then(() => next)) {
+        this.queues.delete(key);
+      }
+      release();
+    };
+  }
+};
+var InMemoryAdapter = class {
+  rows = [];
+  nextId = 1;
+  locks = new KeyedMutex();
+  // ── transaction lifecycle ──────────────────────────────────
+  async withTransaction(fn) {
+    const tx = {
+      id: `tx-${this.nextId++}`,
+      pendingAppends: [],
+      pendingPatches: /* @__PURE__ */ new Map(),
+      heldLocks: /* @__PURE__ */ new Set()
+    };
+    const releases = [];
+    tx._releases = releases;
+    try {
+      const result = await fn(tx);
+      for (const [rowId, patch] of tx.pendingPatches) {
+        const idx = this.rows.findIndex((r) => r.id === rowId);
+        if (idx >= 0) this.rows[idx] = { ...this.rows[idx], ...patch };
+      }
+      this.rows.push(...tx.pendingAppends);
+      return result;
+    } finally {
+      for (const release of releases) release();
+    }
+  }
+  // ── locking ────────────────────────────────────────────────
+  async acquireLock(tx, machine, subjectId) {
+    const key = `${machine}::${subjectId}`;
+    if (tx.heldLocks.has(key)) return;
+    const release = await this.locks.acquire(key);
+    tx.heldLocks.add(key);
+    tx._releases.push(release);
+  }
+  // ── reads ──────────────────────────────────────────────────
+  async readCurrent(tx, machine, subjectId) {
+    const all = this.snapshot(tx, machine, subjectId);
+    const current = all.find((r) => r.mostRecent);
+    return current ? { ...current } : null;
+  }
+  async readHistory(tx, machine, subjectId) {
+    return this.snapshot(tx, machine, subjectId).slice().sort((a, b) => a.sortKey - b.sortKey).map((r) => ({ ...r }));
+  }
+  /**
+   * Merge committed rows + this tx's pending appends/patches into a single
+   * view. Reads inside a tx see their own pending writes.
+   */
+  snapshot(tx, machine, subjectId) {
+    const committed = this.rows.filter(
+      (r) => r.machine === machine && r.subjectId === subjectId
+    );
+    if (!tx) return committed;
+    const patched = committed.map((r) => {
+      const patch = tx.pendingPatches.get(r.id);
+      return patch ? { ...r, ...patch } : r;
+    });
+    const pending = tx.pendingAppends.filter(
+      (r) => r.machine === machine && r.subjectId === subjectId
+    );
+    return [...patched, ...pending];
+  }
+  // ── writes ─────────────────────────────────────────────────
+  async appendTransition(tx, row) {
+    try {
+      const previousCurrent = await this.readCurrent(tx, row.machine, row.subjectId) ?? null;
+      if (previousCurrent) {
+        tx.pendingPatches.set(previousCurrent.id, { mostRecent: false });
+      }
+      const inserted = {
+        ...row,
+        id: `txn-${this.nextId++}`,
+        createdAt: /* @__PURE__ */ new Date()
+      };
+      tx.pendingAppends.push(inserted);
+      return { ...inserted };
+    } catch (err) {
+      throw new core.AdapterError("in-memory append failed", { cause: err });
+    }
+  }
+  async updateSubjectState(_tx, _hint, _newState) {
+  }
+};
+
+exports.InMemoryAdapter = InMemoryAdapter;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/in-memory-adapter.ts"],"names":["AdapterError"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * In-memory adapter for stateledger.\n *\n * Backed by a plain `Map`. Used by the core test suite to validate the\n * contract test pack itself and as a teaching fixture for adapter authors.\n *\n * Implements `Adapter<InMemoryTx>` with pessimistic semantics:\n *   - acquireLock uses a per-`(machine, subjectId)` promise queue so two\n *     concurrent transactions cannot hold the lock at once.\n *   - appendTransition flips the prior mostRecent inside the same\n *     transactional buffer.\n *   - withTransaction commits the buffer on success, discards on throw.\n *\n * Not thread-safe in any meaningful sense; this is a teaching adapter, not\n * a production store.\n */\n\nimport type {\n  Adapter,\n  NewTransitionRow,\n  SubjectStateHint,\n  TransitionRow,\n} from \"@stateledger/core\";\nimport { AdapterError } from \"@stateledger/core\";\n\ntype StoredRow = TransitionRow;\n\n/** Opaque transaction handle. The adapter knows how to use it; users don't. */\nexport type InMemoryTx = {\n  readonly id: string;\n  /** Pending inserts staged inside this tx — applied to the store on commit. */\n  pendingAppends: StoredRow[];\n  /** Per-row patches (e.g. flipping mostRecent) staged inside this tx. */\n  pendingPatches: Map<string, Partial<StoredRow>>;\n  /** Locks held by this tx, released on commit/rollback. */\n  heldLocks: Set<string>;\n};\n\n/** A simple FIFO mutex per key, used to serialize lock acquisition. */\nclass KeyedMutex {\n  private queues = new Map<string, Promise<void>>();\n\n  async acquire(key: string): Promise<() => void> {\n    let release!: () => void;\n    const next = new Promise<void>((resolve) => {\n      release = resolve;\n    });\n    const prev = this.queues.get(key) ?? Promise.resolve();\n    this.queues.set(\n      key,\n      prev.then(() => next),\n    );\n    await prev;\n    return () => {\n      // If we're the tail, clean the entry so the map doesn't grow forever.\n      if (this.queues.get(key) === prev.then(() => next)) {\n        this.queues.delete(key);\n      }\n      release();\n    };\n  }\n}\n\nexport class InMemoryAdapter implements Adapter<InMemoryTx> {\n  private rows: StoredRow[] = [];\n  private nextId = 1;\n  private locks = new KeyedMutex();\n\n  // ── transaction lifecycle ──────────────────────────────────\n\n  async withTransaction<R>(fn: (tx: InMemoryTx) => Promise<R>): Promise<R> {\n    const tx: InMemoryTx = {\n      id: `tx-${this.nextId++}`,\n      pendingAppends: [],\n      pendingPatches: new Map(),\n      heldLocks: new Set(),\n    };\n\n    const releases: Array<() => void> = [];\n    // The InMemoryTx tracks its own held locks via heldLocks; we also keep\n    // a parallel array of release callbacks so we can free them on\n    // commit/rollback without re-querying the mutex.\n    (tx as InMemoryTx & { _releases: Array<() => void> })._releases = releases;\n\n    // On success: apply pending writes atomically.\n    // On throw: pending buffer is dropped — that's the rollback.\n    try {\n      const result = await fn(tx);\n      for (const [rowId, patch] of tx.pendingPatches) {\n        const idx = this.rows.findIndex((r) => r.id === rowId);\n        if (idx >= 0) this.rows[idx] = { ...this.rows[idx]!, ...patch } as StoredRow;\n      }\n      this.rows.push(...tx.pendingAppends);\n      return result;\n    } finally {\n      for (const release of releases) release();\n    }\n  }\n\n  // ── locking ────────────────────────────────────────────────\n\n  async acquireLock(tx: InMemoryTx, machine: string, subjectId: string): Promise<void> {\n    const key = `${machine}::${subjectId}`;\n    if (tx.heldLocks.has(key)) return; // re-entrant within same tx\n    const release = await this.locks.acquire(key);\n    tx.heldLocks.add(key);\n    (tx as InMemoryTx & { _releases: Array<() => void> })._releases.push(release);\n  }\n\n  // ── reads ──────────────────────────────────────────────────\n\n  async readCurrent(\n    tx: InMemoryTx | null,\n    machine: string,\n    subjectId: string,\n  ): Promise<TransitionRow | null> {\n    const all = this.snapshot(tx, machine, subjectId);\n    const current = all.find((r) => r.mostRecent);\n    return current ? { ...current } : null;\n  }\n\n  async readHistory(\n    tx: InMemoryTx | null,\n    machine: string,\n    subjectId: string,\n  ): Promise<TransitionRow[]> {\n    return this.snapshot(tx, machine, subjectId)\n      .slice()\n      .sort((a, b) => a.sortKey - b.sortKey)\n      .map((r) => ({ ...r }));\n  }\n\n  /**\n   * Merge committed rows + this tx's pending appends/patches into a single\n   * view. Reads inside a tx see their own pending writes.\n   */\n  private snapshot(\n    tx: InMemoryTx | null,\n    machine: string,\n    subjectId: string,\n  ): StoredRow[] {\n    const committed = this.rows.filter(\n      (r) => r.machine === machine && r.subjectId === subjectId,\n    );\n    if (!tx) return committed;\n\n    const patched = committed.map((r) => {\n      const patch = tx.pendingPatches.get(r.id);\n      return patch ? ({ ...r, ...patch } as StoredRow) : r;\n    });\n    const pending = tx.pendingAppends.filter(\n      (r) => r.machine === machine && r.subjectId === subjectId,\n    );\n    return [...patched, ...pending];\n  }\n\n  // ── writes ─────────────────────────────────────────────────\n\n  async appendTransition(tx: InMemoryTx, row: NewTransitionRow): Promise<TransitionRow> {\n    try {\n      // Flip the previous mostRecent (in the tx's pending buffer, not committed yet).\n      const previousCurrent = (await this.readCurrent(tx, row.machine, row.subjectId)) ?? null;\n      if (previousCurrent) {\n        tx.pendingPatches.set(previousCurrent.id, { mostRecent: false });\n      }\n\n      const inserted: StoredRow = {\n        ...row,\n        id: `txn-${this.nextId++}`,\n        createdAt: new Date(),\n      };\n      tx.pendingAppends.push(inserted);\n      return { ...inserted };\n    } catch (err) {\n      throw new AdapterError(\"in-memory append failed\", { cause: err });\n    }\n  }\n\n  async updateSubjectState(\n    _tx: InMemoryTx,\n    _hint: SubjectStateHint,\n    _newState: string,\n  ): Promise<void> {\n    // Optional method — the in-memory adapter has no subject row to update.\n  }\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,48 @@
+import { Adapter, TransitionRow, NewTransitionRow, SubjectStateHint } from '@stateledger/core';
+
+/**
+ * In-memory adapter for stateledger.
+ *
+ * Backed by a plain `Map`. Used by the core test suite to validate the
+ * contract test pack itself and as a teaching fixture for adapter authors.
+ *
+ * Implements `Adapter<InMemoryTx>` with pessimistic semantics:
+ *   - acquireLock uses a per-`(machine, subjectId)` promise queue so two
+ *     concurrent transactions cannot hold the lock at once.
+ *   - appendTransition flips the prior mostRecent inside the same
+ *     transactional buffer.
+ *   - withTransaction commits the buffer on success, discards on throw.
+ *
+ * Not thread-safe in any meaningful sense; this is a teaching adapter, not
+ * a production store.
+ */
+
+type StoredRow = TransitionRow;
+/** Opaque transaction handle. The adapter knows how to use it; users don't. */
+type InMemoryTx = {
+    readonly id: string;
+    /** Pending inserts staged inside this tx — applied to the store on commit. */
+    pendingAppends: StoredRow[];
+    /** Per-row patches (e.g. flipping mostRecent) staged inside this tx. */
+    pendingPatches: Map<string, Partial<StoredRow>>;
+    /** Locks held by this tx, released on commit/rollback. */
+    heldLocks: Set<string>;
+};
+declare class InMemoryAdapter implements Adapter<InMemoryTx> {
+    private rows;
+    private nextId;
+    private locks;
+    withTransaction<R>(fn: (tx: InMemoryTx) => Promise<R>): Promise<R>;
+    acquireLock(tx: InMemoryTx, machine: string, subjectId: string): Promise<void>;
+    readCurrent(tx: InMemoryTx | null, machine: string, subjectId: string): Promise<TransitionRow | null>;
+    readHistory(tx: InMemoryTx | null, machine: string, subjectId: string): Promise<TransitionRow[]>;
+    /**
+     * Merge committed rows + this tx's pending appends/patches into a single
+     * view. Reads inside a tx see their own pending writes.
+     */
+    private snapshot;
+    appendTransition(tx: InMemoryTx, row: NewTransitionRow): Promise<TransitionRow>;
+    updateSubjectState(_tx: InMemoryTx, _hint: SubjectStateHint, _newState: string): Promise<void>;
+}
+
+export { InMemoryAdapter, type InMemoryTx };

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+import { Adapter, TransitionRow, NewTransitionRow, SubjectStateHint } from '@stateledger/core';
+
+/**
+ * In-memory adapter for stateledger.
+ *
+ * Backed by a plain `Map`. Used by the core test suite to validate the
+ * contract test pack itself and as a teaching fixture for adapter authors.
+ *
+ * Implements `Adapter<InMemoryTx>` with pessimistic semantics:
+ *   - acquireLock uses a per-`(machine, subjectId)` promise queue so two
+ *     concurrent transactions cannot hold the lock at once.
+ *   - appendTransition flips the prior mostRecent inside the same
+ *     transactional buffer.
+ *   - withTransaction commits the buffer on success, discards on throw.
+ *
+ * Not thread-safe in any meaningful sense; this is a teaching adapter, not
+ * a production store.
+ */
+
+type StoredRow = TransitionRow;
+/** Opaque transaction handle. The adapter knows how to use it; users don't. */
+type InMemoryTx = {
+    readonly id: string;
+    /** Pending inserts staged inside this tx — applied to the store on commit. */
+    pendingAppends: StoredRow[];
+    /** Per-row patches (e.g. flipping mostRecent) staged inside this tx. */
+    pendingPatches: Map<string, Partial<StoredRow>>;
+    /** Locks held by this tx, released on commit/rollback. */
+    heldLocks: Set<string>;
+};
+declare class InMemoryAdapter implements Adapter<InMemoryTx> {
+    private rows;
+    private nextId;
+    private locks;
+    withTransaction<R>(fn: (tx: InMemoryTx) => Promise<R>): Promise<R>;
+    acquireLock(tx: InMemoryTx, machine: string, subjectId: string): Promise<void>;
+    readCurrent(tx: InMemoryTx | null, machine: string, subjectId: string): Promise<TransitionRow | null>;
+    readHistory(tx: InMemoryTx | null, machine: string, subjectId: string): Promise<TransitionRow[]>;
+    /**
+     * Merge committed rows + this tx's pending appends/patches into a single
+     * view. Reads inside a tx see their own pending writes.
+     */
+    private snapshot;
+    appendTransition(tx: InMemoryTx, row: NewTransitionRow): Promise<TransitionRow>;
+    updateSubjectState(_tx: InMemoryTx, _hint: SubjectStateHint, _newState: string): Promise<void>;
+}
+
+export { InMemoryAdapter, type InMemoryTx };

package/dist/index.js

@@ -0,0 +1,110 @@
+import { AdapterError } from '@stateledger/core';
+
+// src/in-memory-adapter.ts
+var KeyedMutex = class {
+  queues = /* @__PURE__ */ new Map();
+  async acquire(key) {
+    let release;
+    const next = new Promise((resolve) => {
+      release = resolve;
+    });
+    const prev = this.queues.get(key) ?? Promise.resolve();
+    this.queues.set(
+      key,
+      prev.then(() => next)
+    );
+    await prev;
+    return () => {
+      if (this.queues.get(key) === prev.then(() => next)) {
+        this.queues.delete(key);
+      }
+      release();
+    };
+  }
+};
+var InMemoryAdapter = class {
+  rows = [];
+  nextId = 1;
+  locks = new KeyedMutex();
+  // ── transaction lifecycle ──────────────────────────────────
+  async withTransaction(fn) {
+    const tx = {
+      id: `tx-${this.nextId++}`,
+      pendingAppends: [],
+      pendingPatches: /* @__PURE__ */ new Map(),
+      heldLocks: /* @__PURE__ */ new Set()
+    };
+    const releases = [];
+    tx._releases = releases;
+    try {
+      const result = await fn(tx);
+      for (const [rowId, patch] of tx.pendingPatches) {
+        const idx = this.rows.findIndex((r) => r.id === rowId);
+        if (idx >= 0) this.rows[idx] = { ...this.rows[idx], ...patch };
+      }
+      this.rows.push(...tx.pendingAppends);
+      return result;
+    } finally {
+      for (const release of releases) release();
+    }
+  }
+  // ── locking ────────────────────────────────────────────────
+  async acquireLock(tx, machine, subjectId) {
+    const key = `${machine}::${subjectId}`;
+    if (tx.heldLocks.has(key)) return;
+    const release = await this.locks.acquire(key);
+    tx.heldLocks.add(key);
+    tx._releases.push(release);
+  }
+  // ── reads ──────────────────────────────────────────────────
+  async readCurrent(tx, machine, subjectId) {
+    const all = this.snapshot(tx, machine, subjectId);
+    const current = all.find((r) => r.mostRecent);
+    return current ? { ...current } : null;
+  }
+  async readHistory(tx, machine, subjectId) {
+    return this.snapshot(tx, machine, subjectId).slice().sort((a, b) => a.sortKey - b.sortKey).map((r) => ({ ...r }));
+  }
+  /**
+   * Merge committed rows + this tx's pending appends/patches into a single
+   * view. Reads inside a tx see their own pending writes.
+   */
+  snapshot(tx, machine, subjectId) {
+    const committed = this.rows.filter(
+      (r) => r.machine === machine && r.subjectId === subjectId
+    );
+    if (!tx) return committed;
+    const patched = committed.map((r) => {
+      const patch = tx.pendingPatches.get(r.id);
+      return patch ? { ...r, ...patch } : r;
+    });
+    const pending = tx.pendingAppends.filter(
+      (r) => r.machine === machine && r.subjectId === subjectId
+    );
+    return [...patched, ...pending];
+  }
+  // ── writes ─────────────────────────────────────────────────
+  async appendTransition(tx, row) {
+    try {
+      const previousCurrent = await this.readCurrent(tx, row.machine, row.subjectId) ?? null;
+      if (previousCurrent) {
+        tx.pendingPatches.set(previousCurrent.id, { mostRecent: false });
+      }
+      const inserted = {
+        ...row,
+        id: `txn-${this.nextId++}`,
+        createdAt: /* @__PURE__ */ new Date()
+      };
+      tx.pendingAppends.push(inserted);
+      return { ...inserted };
+    } catch (err) {
+      throw new AdapterError("in-memory append failed", { cause: err });
+    }
+  }
+  async updateSubjectState(_tx, _hint, _newState) {
+  }
+};
+
+export { InMemoryAdapter };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/in-memory-adapter.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * In-memory adapter for stateledger.\n *\n * Backed by a plain `Map`. Used by the core test suite to validate the\n * contract test pack itself and as a teaching fixture for adapter authors.\n *\n * Implements `Adapter<InMemoryTx>` with pessimistic semantics:\n *   - acquireLock uses a per-`(machine, subjectId)` promise queue so two\n *     concurrent transactions cannot hold the lock at once.\n *   - appendTransition flips the prior mostRecent inside the same\n *     transactional buffer.\n *   - withTransaction commits the buffer on success, discards on throw.\n *\n * Not thread-safe in any meaningful sense; this is a teaching adapter, not\n * a production store.\n */\n\nimport type {\n  Adapter,\n  NewTransitionRow,\n  SubjectStateHint,\n  TransitionRow,\n} from \"@stateledger/core\";\nimport { AdapterError } from \"@stateledger/core\";\n\ntype StoredRow = TransitionRow;\n\n/** Opaque transaction handle. The adapter knows how to use it; users don't. */\nexport type InMemoryTx = {\n  readonly id: string;\n  /** Pending inserts staged inside this tx — applied to the store on commit. */\n  pendingAppends: StoredRow[];\n  /** Per-row patches (e.g. flipping mostRecent) staged inside this tx. */\n  pendingPatches: Map<string, Partial<StoredRow>>;\n  /** Locks held by this tx, released on commit/rollback. */\n  heldLocks: Set<string>;\n};\n\n/** A simple FIFO mutex per key, used to serialize lock acquisition. */\nclass KeyedMutex {\n  private queues = new Map<string, Promise<void>>();\n\n  async acquire(key: string): Promise<() => void> {\n    let release!: () => void;\n    const next = new Promise<void>((resolve) => {\n      release = resolve;\n    });\n    const prev = this.queues.get(key) ?? Promise.resolve();\n    this.queues.set(\n      key,\n      prev.then(() => next),\n    );\n    await prev;\n    return () => {\n      // If we're the tail, clean the entry so the map doesn't grow forever.\n      if (this.queues.get(key) === prev.then(() => next)) {\n        this.queues.delete(key);\n      }\n      release();\n    };\n  }\n}\n\nexport class InMemoryAdapter implements Adapter<InMemoryTx> {\n  private rows: StoredRow[] = [];\n  private nextId = 1;\n  private locks = new KeyedMutex();\n\n  // ── transaction lifecycle ──────────────────────────────────\n\n  async withTransaction<R>(fn: (tx: InMemoryTx) => Promise<R>): Promise<R> {\n    const tx: InMemoryTx = {\n      id: `tx-${this.nextId++}`,\n      pendingAppends: [],\n      pendingPatches: new Map(),\n      heldLocks: new Set(),\n    };\n\n    const releases: Array<() => void> = [];\n    // The InMemoryTx tracks its own held locks via heldLocks; we also keep\n    // a parallel array of release callbacks so we can free them on\n    // commit/rollback without re-querying the mutex.\n    (tx as InMemoryTx & { _releases: Array<() => void> })._releases = releases;\n\n    // On success: apply pending writes atomically.\n    // On throw: pending buffer is dropped — that's the rollback.\n    try {\n      const result = await fn(tx);\n      for (const [rowId, patch] of tx.pendingPatches) {\n        const idx = this.rows.findIndex((r) => r.id === rowId);\n        if (idx >= 0) this.rows[idx] = { ...this.rows[idx]!, ...patch } as StoredRow;\n      }\n      this.rows.push(...tx.pendingAppends);\n      return result;\n    } finally {\n      for (const release of releases) release();\n    }\n  }\n\n  // ── locking ────────────────────────────────────────────────\n\n  async acquireLock(tx: InMemoryTx, machine: string, subjectId: string): Promise<void> {\n    const key = `${machine}::${subjectId}`;\n    if (tx.heldLocks.has(key)) return; // re-entrant within same tx\n    const release = await this.locks.acquire(key);\n    tx.heldLocks.add(key);\n    (tx as InMemoryTx & { _releases: Array<() => void> })._releases.push(release);\n  }\n\n  // ── reads ──────────────────────────────────────────────────\n\n  async readCurrent(\n    tx: InMemoryTx | null,\n    machine: string,\n    subjectId: string,\n  ): Promise<TransitionRow | null> {\n    const all = this.snapshot(tx, machine, subjectId);\n    const current = all.find((r) => r.mostRecent);\n    return current ? { ...current } : null;\n  }\n\n  async readHistory(\n    tx: InMemoryTx | null,\n    machine: string,\n    subjectId: string,\n  ): Promise<TransitionRow[]> {\n    return this.snapshot(tx, machine, subjectId)\n      .slice()\n      .sort((a, b) => a.sortKey - b.sortKey)\n      .map((r) => ({ ...r }));\n  }\n\n  /**\n   * Merge committed rows + this tx's pending appends/patches into a single\n   * view. Reads inside a tx see their own pending writes.\n   */\n  private snapshot(\n    tx: InMemoryTx | null,\n    machine: string,\n    subjectId: string,\n  ): StoredRow[] {\n    const committed = this.rows.filter(\n      (r) => r.machine === machine && r.subjectId === subjectId,\n    );\n    if (!tx) return committed;\n\n    const patched = committed.map((r) => {\n      const patch = tx.pendingPatches.get(r.id);\n      return patch ? ({ ...r, ...patch } as StoredRow) : r;\n    });\n    const pending = tx.pendingAppends.filter(\n      (r) => r.machine === machine && r.subjectId === subjectId,\n    );\n    return [...patched, ...pending];\n  }\n\n  // ── writes ─────────────────────────────────────────────────\n\n  async appendTransition(tx: InMemoryTx, row: NewTransitionRow): Promise<TransitionRow> {\n    try {\n      // Flip the previous mostRecent (in the tx's pending buffer, not committed yet).\n      const previousCurrent = (await this.readCurrent(tx, row.machine, row.subjectId)) ?? null;\n      if (previousCurrent) {\n        tx.pendingPatches.set(previousCurrent.id, { mostRecent: false });\n      }\n\n      const inserted: StoredRow = {\n        ...row,\n        id: `txn-${this.nextId++}`,\n        createdAt: new Date(),\n      };\n      tx.pendingAppends.push(inserted);\n      return { ...inserted };\n    } catch (err) {\n      throw new AdapterError(\"in-memory append failed\", { cause: err });\n    }\n  }\n\n  async updateSubjectState(\n    _tx: InMemoryTx,\n    _hint: SubjectStateHint,\n    _newState: string,\n  ): Promise<void> {\n    // Optional method — the in-memory adapter has no subject row to update.\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@stateledger/memory",
+  "version": "0.0.1-experimental.0",
+  "description": "In-memory adapter for stateledger — for tests, hello-world demos, and prototyping.",
+  "license": "MIT",
+  "author": "Enow Divine",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/enowdivine/stateledger.git",
+    "directory": "packages/memory"
+  },
+  "homepage": "https://github.com/enowdivine/stateledger#readme",
+  "bugs": {
+    "url": "https://github.com/enowdivine/stateledger/issues"
+  },
+  "keywords": [
+    "state-machine",
+    "in-memory",
+    "stateledger",
+    "testing",
+    "fixture"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@stateledger/core": "0.0.1-experimental.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}