@classytic/repo-core 0.29.0 → 0.30.0

package/CHANGELOG.md

@@ -4,6 +4,33 @@ All notable changes to `@classytic/repo-core` are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.30.0] - 2026-10-06
+
+### Added — command streams and a shared catalog in `./sync`
+
+- **`CommandStreamStore`**: the server side of a command-sync protocol. It records one verdict per
+  sequence number (carrying the command's `fingerprint`) and a per-stream watermark bound to a
+  tenant, all in the transaction of the command's effects. `createMemoryCommandStreamStore` is
+  the reference implementation; mongokit ships the durable one.
+- **Resolutions and aliases** on the same contract:
+  - outcome `resolved`;
+  - a refused verdict keeps its `body` and `dependsOn`;
+  - `resolution` attribution;
+  - `record` replaces;
+  - `blockedOn(commandId)`;
+  - `alias` / `aliasOf`: tenant-scoped, and one local id names one record.
+- **`runCommandStreamStoreConformance`** (`./testing`): eight cases. One of them is serialisation:
+  twenty concurrent advances of one stream must reach 20.
+- **`runChangeLogStoreConformance`** (`./testing`): eleven cases. These include commit order: an
+  entry that commits after a reader's checkpoint must still reach that reader.
+- **`ChangesSinceOptions.sharedScopes`**: company-wide scopes (a catalog) that every tenant reads,
+  whatever tenant their entries carry.
+
+### Removed
+
+- `PushMutation`, `PushVerdict`, `PushVerdictStatus`. Nothing consumed them; command streams
+  replace them.
+
 ## [0.29.0] - 2026-09-23
 
 ### ⚠ Changed — ONE list-query grammar, held to by every parser (`./query-parser`)

package/dist/sync/index.d.mts

@@ -1,39 +1,24 @@
 //#region src/sync/index.d.ts
 /**
- * Change-log / cursor contract — the data-sync spine for offline-first and
- * incremental replication (`arc-sync`-style capability packages, POS offline,
- * bulk delta export, cross-service read models).
+ * The sync contracts kits implement and a sync engine (`@classytic/arc-sync`) consumes:
  *
- * Synthesized from the proven protocols, taking the best of each:
+ *   - `ChangeLogStore` — the server's change FEED: append-only, commit-ordered, tombstones for
+ *     deletes, opaque cursors a client resumes from.
+ *   - `CommandStreamStore` — per-client COMMAND STREAMS: one recorded verdict per sequence number,
+ *     committed in the transaction of the command's effects.
  *
- *   - CouchDB `_changes`      → append-only feed, TOMBSTONES for deletes,
- *                               client checkpoints
- *   - Drive/Graph delta APIs  → OPAQUE server-issued cursors (`deltaLink` /
- *                               `startPageToken`) — clients never parse them
- *   - Mongo change streams    → resumable, ordered, per-scope feeds
- *   - Replicache push/pull    → client mutation ids for idempotent PUSH,
- *                               server-authoritative conflict verdicts
+ * Contracts only; `MemoryChangeLogStore` / `createMemoryCommandStreamStore` are the references,
+ * and `@classytic/repo-core/testing` holds the conformance suites every durable store passes.
  *
- * CONTRACT ONLY — storage-agnostic (repo-core is the cross-kit contract home,
- * like DataAdapter/EventTransport/IdempotencyStore). `MemoryChangeLogStore` is
- * the reference impl. Durable stores + capture plugins live in the KITS
- * (mongokit/prismakit/sqlitekit repository plugins); the HTTP surface
- * (`/sync/pull`, `/sync/push`) is an arc module; arc re-exports this contract
- * at `@classytic/arc/sync`. repo-core is source of truth.
+ * ## Feed semantics (stores MUST honor)
  *
- * ## Required semantics (stores MUST honor)
- *
- * 1. **Cursors are opaque, totally ordered per store.** Clients echo them
- *    verbatim. A cursor from one store/scope-set is meaningless elsewhere.
- * 2. **`append` is ordered and atomic with the business write** when a
- *    `session` is provided (same transaction — the outbox discipline).
- * 3. **Deletes are tombstones**, never gaps. A client at cursor C must be able
- *    to converge by applying every entry after C — including deletions.
- * 4. **`since` is exclusive** of the given cursor and returns entries in
- *    cursor order. `hasMore: true` means call again with the new cursor.
- * 5. **Compaction (`prune`) may drop superseded intermediate versions but
- *    NEVER the latest state or an un-consumed tombstone horizon** — a store
- *    advertises its horizon so clients older than it do a full resync.
+ * 1. **Cursors are opaque, totally ordered per store, in COMMIT order.** A reader must never
+ *    checkpoint past an entry that commits later.
+ * 2. **`append` joins the caller's transaction** when given a `session`.
+ * 3. **Deletes are tombstones**, never gaps.
+ * 4. **`since` is exclusive** of the cursor and returns entries in cursor order.
+ * 5. **`prune` keeps the latest state and advertises its horizon**; an older cursor gets
+ *    `CursorExpiredError` and resyncs.
  */
 /** What happened to a document. Field-level patches are deliberately out of
  *  scope — version-checked upserts + server authority beat CRDT complexity
@@ -47,7 +32,7 @@ interface ChangeEntry<TDoc = unknown> {
   readonly op: ChangeOp;
   /**
    * Monotonic per-document version — the optimistic-concurrency token.
-   * Conflict rule: a push carrying `baseVersion < current` is a conflict.
+   * A client ignores an entry not newer than the version it holds.
    */
   readonly version: number;
   /** Full document snapshot for `upsert`; absent for `delete` (tombstone). */
@@ -66,6 +51,11 @@ interface ChangesSinceOptions {
   readonly scopes?: readonly string[];
   /** Tenant partition — REQUIRED by multi-tenant stores. */
   readonly tenantId?: string;
+  /**
+   * Scopes every tenant reads whatever their entries' tenant (company-wide resources: the catalog
+   * every branch sells from). Only meaningful with `tenantId`; still narrowed by `scopes`.
+   */
+  readonly sharedScopes?: readonly string[];
 }
 interface ChangesPage<TDoc = unknown> {
   readonly changes: readonly ChangeEntry<TDoc>[];
@@ -74,29 +64,6 @@ interface ChangesPage<TDoc = unknown> {
   /** True → more entries exist; pull again immediately. */
   readonly hasMore: boolean;
 }
-interface PushMutation<TDoc = unknown> {
-  readonly scope: string;
-  readonly docId: string;
-  readonly op: ChangeOp;
-  /** Version the client last saw — the optimistic-concurrency precondition. */
-  readonly baseVersion?: number;
-  readonly doc?: TDoc;
-  /**
-   * Client-unique id (`<clientId>:<seq>`) — replays of the same id MUST be
-   * acknowledged as already-applied, never re-executed (at-least-once safe).
-   */
-  readonly mutationId: string;
-}
-type PushVerdictStatus = 'applied' | 'already_applied' | 'conflict' | 'rejected';
-interface PushVerdict<TDoc = unknown> {
-  readonly mutationId: string;
-  readonly status: PushVerdictStatus;
-  /** Authoritative post-push version (also on conflict: the WINNING version). */
-  readonly version?: number;
-  /** Authoritative doc on conflict so the client can rebase (server wins). */
-  readonly current?: TDoc;
-  readonly reason?: string;
-}
 interface ChangeLogAppendOptions {
   /** DB session/transaction handle — append atomically with the business write. */
   readonly session?: unknown;
@@ -127,5 +94,73 @@ declare class MemoryChangeLogStore<TDoc = unknown> implements ChangeLogStore<TDo
   since(cursor: string, options?: ChangesSinceOptions): Promise<ChangesPage<TDoc>>;
   latestCursor(): Promise<string>;
 }
+/** `resolved`: a refused command settled afterwards by a recorded resolution. */
+type CommandOutcome = 'applied' | 'rejected' | 'blocked' | 'resolved';
+/** The one outcome recorded for one command — and for its `seq` on its stream. */
+interface CommandVerdictRecord {
+  readonly commandId: string;
+  readonly stream: string;
+  readonly seq: number;
+  readonly outcome: CommandOutcome;
+  /** Why it was rejected or blocked — a stable code. */
+  readonly code?: string;
+  /** `fingerprintRequest` of the command: a retry with other bytes under the same id is a fault. */
+  readonly fingerprint: string;
+  /** The command's bytes, kept while it is refused — a resolution re-evaluates them unchanged. */
+  readonly body?: string;
+  /** What a `blocked` command waits on — how a resolution finds the dependants to re-evaluate. */
+  readonly dependsOn?: readonly string[];
+  /** On a `resolved` verdict: the decision that settled it, and who made it. */
+  readonly resolution?: {
+    readonly action: string;
+    readonly by: string;
+    readonly at: string;
+  };
+}
+/** A device-minted id the server resolved to one of its own records (a matched customer, a merged shift). */
+interface CommandAliasRecord {
+  readonly tenantId: string;
+  readonly localId: string;
+  readonly serverId: string;
+}
+interface CommandStreamRecord {
+  /** The tenant the stream was bound to by its first command. */
+  readonly tenantId: string;
+  /** Highest seq with a recorded verdict; every seq up to it has one. */
+  readonly processed: number;
+}
+/** One store transaction. Pass `session` to the feed's `append` and to every domain write. */
+interface CommandStreamTx {
+  readonly session?: unknown;
+}
+/**
+ * Per-client command streams. Every method but `transaction` runs inside one; the transaction
+ * commits stream, verdict, feed entries and the domain's writes together, or none of them.
+ */
+interface CommandStreamStore<TTx extends CommandStreamTx = CommandStreamTx> {
+  /** The feed the domain's writes are captured into — verdicts are appended to it too. */
+  readonly changes: ChangeLogStore;
+  /**
+   * Commit when `work` returns, discard everything when it throws. Two transactions moving one
+   * stream must SERIALISE (a retried write conflict, a lock): neither may commit on a stale read.
+   */
+  transaction<T>(work: (tx: TTx) => Promise<T>): Promise<T>;
+  stream(tx: TTx, id: string): Promise<CommandStreamRecord | null>;
+  /** Move `from` → `to`, creating the stream (bound to `tenantId`) at `from === 0`. False when not at `from`. */
+  advance(tx: TTx, id: string, tenantId: string, from: number, to: number): Promise<boolean>;
+  verdict(tx: TTx, commandId: string): Promise<CommandVerdictRecord | null>;
+  /** Record a verdict, replacing the command's earlier one (a resolution settles a refusal). */
+  record(tx: TTx, verdict: CommandVerdictRecord): Promise<void>;
+  /** The `blocked` verdicts waiting on `commandId`, in seq order. */
+  blockedOn(tx: TTx, commandId: string): Promise<CommandVerdictRecord[]>;
+  /** Record that `localId` names `serverId` in this tenant. One alias per local id. */
+  alias(tx: TTx, alias: CommandAliasRecord): Promise<void>;
+  aliasOf(tx: TTx, tenantId: string, localId: string): Promise<string | null>;
+}
+/**
+ * The reference `CommandStreamStore`: transactions run one at a time over a copy of the state, and
+ * the feed entries appended with their `session` reach `changes` only on commit.
+ */
+declare function createMemoryCommandStreamStore(feed?: ChangeLogStore): CommandStreamStore;
 //#endregion
-export { ChangeEntry, ChangeLogAppendOptions, ChangeLogStore, ChangeOp, ChangesPage, ChangesSinceOptions, CursorExpiredError, MemoryChangeLogStore, PushMutation, PushVerdict, PushVerdictStatus };
+export { ChangeEntry, ChangeLogAppendOptions, ChangeLogStore, ChangeOp, ChangesPage, ChangesSinceOptions, CommandAliasRecord, CommandOutcome, CommandStreamRecord, CommandStreamStore, CommandStreamTx, CommandVerdictRecord, CursorExpiredError, MemoryChangeLogStore, createMemoryCommandStreamStore };

package/dist/testing/change-log-conformance.d.mts

@@ -0,0 +1,21 @@
+import { ChangeLogStore } from "../sync/index.mjs";
+//#region src/testing/change-log-conformance.d.ts
+interface ChangeLogConformanceHarness {
+  /** A store over an EMPTY backend, per scenario. */
+  createStore(): ChangeLogStore | Promise<ChangeLogStore>;
+  /**
+   * Run `work` in a transaction on the store's backend and commit it, or abort when it throws.
+   * Omit for a store with no transactions (the memory reference); the atomicity cases then skip.
+   */
+  transaction?<T>(work: (session: unknown) => Promise<T>): Promise<T>;
+}
+/** The contract's cases, runner-agnostic — each `run` throws on failure. */
+declare function changeLogStoreCases(harness: ChangeLogConformanceHarness): {
+  readonly name: string;
+  readonly run: () => Promise<void>;
+  readonly needsTransaction?: boolean;
+}[];
+/** The contract as a vitest suite. */
+declare function runChangeLogStoreConformance(harness: ChangeLogConformanceHarness): void;
+//#endregion
+export { ChangeLogConformanceHarness, changeLogStoreCases, runChangeLogStoreConformance };

package/dist/testing/change-log-conformance.mjs

@@ -0,0 +1,204 @@
+import { describe, it } from "vitest";
+//#region src/testing/change-log-conformance.ts
+/**
+* `runChangeLogStoreConformance` — the contract every `ChangeLogStore` passes. A kit runs it against
+* its real backend; passing it is what "implements the store" means.
+*
+*     describe('mongokit/sync conformance', () => {
+*       runChangeLogStoreConformance({ createStore: () => createMongoChangeLogStore(...), transaction });
+*     });
+*
+* The case that matters is the checkpoint one: a store whose cursors can commit OUT of order loses
+* an entry for every client that read between them — it passes everything else and drops data.
+*/
+let n = 0;
+const upsert = (over = {}) => {
+	n += 1;
+	return {
+		scope: "order",
+		docId: `doc-${n}`,
+		op: "upsert",
+		version: 1,
+		doc: { n },
+		tenantId: "branch-a",
+		...over
+	};
+};
+function check(condition, message) {
+	if (!condition) throw new Error(`[ChangeLogStore contract] ${message}`);
+}
+/** Every entry after `cursor`, page by page — what a client converges by. */
+async function drain(store, cursor, options = {}) {
+	const out = [];
+	let at = cursor;
+	for (let guard = 0; guard < 1e4; guard++) {
+		const page = await store.since(at, options);
+		out.push(...page.changes);
+		at = page.cursor;
+		if (!page.hasMore) return {
+			entries: out,
+			cursor: at
+		};
+	}
+	throw new Error("[ChangeLogStore contract] since() never reported hasMore: false");
+}
+/** The contract's cases, runner-agnostic — each `run` throws on failure. */
+function changeLogStoreCases(harness) {
+	const transact = (work) => {
+		if (!harness.transaction) throw new Error("[ChangeLogStore contract] this case needs transaction()");
+		return harness.transaction(work);
+	};
+	return [
+		["an empty store has no entries and an empty head cursor", async (store) => {
+			check(await store.latestCursor() === "", "latestCursor of an empty store must be \"\"");
+			const page = await store.since("");
+			check(page.changes.length === 0 && !page.hasMore, "since(\"\") of an empty store must be empty");
+		}],
+		["append assigns a cursor and a capture time, and round-trips the rest", async (store) => {
+			const entry = upsert({ doc: {
+				name: "Mug",
+				price: 450
+			} });
+			const saved = await store.append(entry);
+			check(typeof saved.cursor === "string" && saved.cursor.length > 0, "append must assign a cursor");
+			check(saved.at instanceof Date, "append must assign `at` as a Date");
+			const [read] = (await store.since("")).changes;
+			check(read && read.docId === entry.docId && read.scope === entry.scope && read.op === "upsert", "since must return the entry");
+			check(read.version === 1 && read.tenantId === "branch-a", "version and tenantId must round-trip");
+			check(JSON.stringify(read.doc) === JSON.stringify(entry.doc), "the doc snapshot must round-trip");
+			check(read.cursor === saved.cursor, "since must return the cursor append assigned");
+		}],
+		["since is exclusive and returns entries in append order", async (store) => {
+			const a = await store.append(upsert());
+			const b = await store.append(upsert());
+			const c = await store.append(upsert());
+			check((await drain(store, a.cursor)).entries.map((e) => e.cursor).join() === [b.cursor, c.cursor].join(), "since(a) must be [b, c], in order");
+		}],
+		["paging with a small limit delivers every entry exactly once", async (store) => {
+			for (let i = 0; i < 7; i++) await store.append(upsert());
+			const { entries } = await drain(store, "", { limit: 3 });
+			check(entries.length === 7, `paging must deliver all 7 entries, got ${entries.length}`);
+			check(new Set(entries.map((e) => e.cursor)).size === 7, "no entry may be delivered twice");
+		}],
+		["a delete is a tombstone with no doc", async (store) => {
+			await store.append({
+				scope: "order",
+				docId: "gone",
+				op: "delete",
+				version: 2,
+				tenantId: "branch-a"
+			});
+			const [tomb] = (await store.since("")).changes;
+			check(tomb?.op === "delete" && tomb.docId === "gone" && tomb.doc === void 0, "a delete must come back as a tombstone without a doc");
+		}],
+		["a tenant (branch) sees only its own entries", async (store) => {
+			await store.append(upsert({ tenantId: "branch-a" }));
+			await store.append(upsert({ tenantId: "branch-b" }));
+			await store.append(upsert({ tenantId: "branch-a" }));
+			const a = await drain(store, "", { tenantId: "branch-a" });
+			const b = await drain(store, "", { tenantId: "branch-b" });
+			check(a.entries.length === 2 && a.entries.every((e) => e.tenantId === "branch-a"), "branch-a must see its 2 entries only");
+			check(b.entries.length === 1 && b.entries[0]?.tenantId === "branch-b", "branch-b must see its 1 entry only");
+		}],
+		["a shared scope reaches every tenant; its other scopes stay partitioned", async (store) => {
+			const { tenantId: _, ...companyWide } = upsert({ scope: "product" });
+			await store.append(companyWide);
+			await store.append(upsert({
+				scope: "product",
+				tenantId: "branch-b"
+			}));
+			await store.append(upsert({
+				scope: "order",
+				tenantId: "branch-b"
+			}));
+			await store.append(upsert({
+				scope: "order",
+				tenantId: "branch-a"
+			}));
+			const { entries } = await drain(store, "", {
+				tenantId: "branch-a",
+				sharedScopes: ["product"]
+			});
+			check(entries.map((e) => e.scope).join() === "product,product,order", "branch-a must read every product and only its own order");
+			const narrowed = await drain(store, "", {
+				tenantId: "branch-a",
+				sharedScopes: ["product"],
+				scopes: ["order"]
+			});
+			check(narrowed.entries.length === 1 && narrowed.entries[0]?.tenantId === "branch-a", "scopes must still narrow a shared scope away");
+		}],
+		["scopes narrow the feed to the resources a client syncs", async (store) => {
+			await store.append(upsert({ scope: "order" }));
+			await store.append(upsert({ scope: "product" }));
+			await store.append(upsert({ scope: "shift" }));
+			const { entries } = await drain(store, "", { scopes: ["order", "shift"] });
+			check(entries.map((e) => e.scope).join() === "order,shift", "scopes must select order and shift, in order");
+		}],
+		["latestCursor is a checkpoint after which the filtered feed is empty", async (store) => {
+			await store.append(upsert({ tenantId: "branch-a" }));
+			await store.append(upsert({ tenantId: "branch-b" }));
+			const head = await store.latestCursor({ tenantId: "branch-a" });
+			check((await store.since(head, { tenantId: "branch-a" })).changes.length === 0, "nothing for branch-a after its head");
+			const later = await store.append(upsert({ tenantId: "branch-a" }));
+			const next = await store.since(head, { tenantId: "branch-a" });
+			check(next.changes.length === 1 && next.changes[0]?.cursor === later.cursor, "a later entry must follow the head");
+		}],
+		["concurrent appends get distinct cursors and none is lost", async (store) => {
+			const saved = await Promise.all(Array.from({ length: 25 }, () => store.append(upsert())));
+			check(new Set(saved.map((e) => e.cursor)).size === 25, "every concurrent append must get its own cursor");
+			const { entries } = await drain(store, "", { limit: 10 });
+			check(entries.length === 25, `all 25 must be delivered, got ${entries.length}`);
+		}],
+		[
+			"an entry appended in an aborted transaction never appears",
+			async (store) => {
+				await transact(async (session) => {
+					await store.append(upsert({ docId: "rolled-back" }), { session });
+					throw new Error("abort");
+				}).catch(() => void 0);
+				await store.append(upsert({ docId: "kept" }), {});
+				const { entries } = await drain(store, "");
+				check(!entries.some((e) => e.docId === "rolled-back"), "an aborted append must not be in the feed");
+				check(entries.some((e) => e.docId === "kept"), "a committed append must be in the feed");
+			},
+			true
+		],
+		[
+			"an entry committed after a client checkpointed is still delivered after that checkpoint",
+			async (store) => {
+				let releaseA;
+				const aMayCommit = new Promise((resolve) => releaseA = resolve);
+				let aAppended;
+				const aHasAppended = new Promise((resolve) => aAppended = resolve);
+				const a = transact(async (session) => {
+					await store.append(upsert({ docId: "slow" }), { session });
+					aAppended();
+					await aMayCommit;
+				});
+				await aHasAppended;
+				const b = store.append(upsert({ docId: "fast" }));
+				const bCommittedFirst = await Promise.race([b.then(() => true), new Promise((r) => setTimeout(() => r(false), 300))]);
+				const checkpoint = bCommittedFirst ? (await drain(store, "")).cursor : "";
+				releaseA();
+				await Promise.all([a, b]);
+				const all = (await drain(store, "")).entries.map((e) => e.docId);
+				check(all.includes("slow") && all.includes("fast"), "both entries must be in the feed");
+				if (bCommittedFirst) check((await drain(store, checkpoint)).entries.map((e) => e.docId).includes("slow"), "an entry committed after a checkpoint was lost to the client that took it");
+			},
+			true
+		]
+	].map(([name, body, needsTransaction]) => ({
+		name,
+		needsTransaction: needsTransaction === true,
+		run: async () => body(await harness.createStore())
+	}));
+}
+/** The contract as a vitest suite. */
+function runChangeLogStoreConformance(harness) {
+	describe("ChangeLogStore conformance", () => {
+		for (const c of changeLogStoreCases(harness)) if (c.needsTransaction && !harness.transaction) it.skip(`${c.name} (no transactions)`, c.run);
+		else it(c.name, c.run, 3e4);
+	});
+}
+//#endregion
+export { changeLogStoreCases, runChangeLogStoreConformance };

package/dist/testing/command-stream-conformance.d.mts

@@ -0,0 +1,15 @@
+import { CommandStreamStore } from "../sync/index.mjs";
+//#region src/testing/command-stream-conformance.d.ts
+interface CommandStreamConformanceHarness {
+  /** A store over an EMPTY backend, per scenario. */
+  createStore(): CommandStreamStore | Promise<CommandStreamStore>;
+}
+/** The contract's cases, runner-agnostic — each `run` throws on failure. */
+declare function commandStreamStoreCases(harness: CommandStreamConformanceHarness): {
+  readonly name: string;
+  readonly run: () => Promise<void>;
+}[];
+/** The contract as a vitest suite. */
+declare function runCommandStreamStoreConformance(harness: CommandStreamConformanceHarness): void;
+//#endregion
+export { CommandStreamConformanceHarness, commandStreamStoreCases, runCommandStreamStoreConformance };

package/dist/testing/command-stream-conformance.mjs

@@ -0,0 +1,163 @@
+import { describe, it } from "vitest";
+//#region src/testing/command-stream-conformance.ts
+/**
+* `runCommandStreamStoreConformance` — the contract every `CommandStreamStore` passes, run against
+* its real backend. The serialisation case is the one that matters: a store whose transactions can
+* both commit on a stale read gives two commands the same seq, and passes everything else.
+*/
+function check(condition, message) {
+	if (!condition) throw new Error(`[CommandStreamStore contract] ${message}`);
+}
+const verdict = (over = {}) => ({
+	commandId: "c1",
+	stream: "s1",
+	seq: 1,
+	outcome: "applied",
+	fingerprint: "f1",
+	...over
+});
+/** The contract's cases, runner-agnostic — each `run` throws on failure. */
+function commandStreamStoreCases(harness) {
+	return [
+		["an unknown stream and command read as null", async (store) => {
+			await store.transaction(async (tx) => {
+				check(await store.stream(tx, "s1") === null, "an unknown stream must be null");
+				check(await store.verdict(tx, "c1") === null, "an unknown verdict must be null");
+			});
+		}],
+		["advance creates the stream bound to its tenant, then moves only from where it stands", async (store) => {
+			await store.transaction(async (tx) => {
+				check(await store.advance(tx, "s1", "branch-a", 0, 1), "advance 0 → 1 must create the stream");
+				check(!await store.advance(tx, "s1", "branch-a", 0, 1), "advance from a stale position must be false");
+				check(await store.advance(tx, "s1", "branch-b", 1, 2), "advance 1 → 2 must succeed");
+			});
+			const stream = await store.transaction((tx) => store.stream(tx, "s1"));
+			check(stream?.processed === 2, "the watermark must be 2");
+			check(stream.tenantId === "branch-a", "the stream stays bound to its FIRST tenant");
+		}],
+		["a verdict round-trips, with its code and fingerprint", async (store) => {
+			await store.transaction((tx) => store.record(tx, verdict({
+				outcome: "rejected",
+				code: "pos.closed"
+			})));
+			await store.transaction((tx) => store.record(tx, verdict({
+				commandId: "c2",
+				seq: 2
+			})));
+			const [rejected, applied] = await store.transaction(async (tx) => [await store.verdict(tx, "c1"), await store.verdict(tx, "c2")]);
+			check(rejected?.outcome === "rejected" && rejected.code === "pos.closed" && rejected.fingerprint === "f1", "the rejected verdict must round-trip");
+			check(applied?.outcome === "applied" && applied.code === void 0 && applied.seq === 2, "an applied verdict has no code");
+		}],
+		["a later record replaces a verdict — how a resolution settles a refusal", async (store) => {
+			await store.transaction((tx) => store.record(tx, verdict({
+				outcome: "rejected",
+				code: "x",
+				body: "{\"id\":\"c1\"}"
+			})));
+			await store.transaction((tx) => store.record(tx, verdict({ outcome: "resolved" })));
+			const settled = await store.transaction((tx) => store.verdict(tx, "c1"));
+			check(settled?.outcome === "resolved" && settled.code === void 0, "the second record must replace the first");
+			check(settled.body === void 0, "a replaced verdict keeps nothing of the first");
+		}],
+		["blockedOn finds the blocked verdicts waiting on a command, in seq order", async (store) => {
+			await store.transaction(async (tx) => {
+				await store.record(tx, verdict({
+					commandId: "c3",
+					seq: 3,
+					outcome: "blocked",
+					dependsOn: ["c1"],
+					body: "{}"
+				}));
+				await store.record(tx, verdict({
+					commandId: "c2",
+					seq: 2,
+					outcome: "blocked",
+					dependsOn: ["c1"],
+					body: "{}"
+				}));
+				await store.record(tx, verdict({
+					commandId: "c4",
+					seq: 4,
+					outcome: "blocked",
+					dependsOn: ["c9"],
+					body: "{}"
+				}));
+				await store.record(tx, verdict({
+					commandId: "c5",
+					seq: 5,
+					outcome: "applied",
+					dependsOn: ["c1"]
+				}));
+			});
+			const waiting = await store.transaction((tx) => store.blockedOn(tx, "c1"));
+			check(waiting.map((v) => v.commandId).join() === "c2,c3", `expected c2,c3 — got ${waiting.map((v) => v.commandId).join()}`);
+			check(waiting[0]?.body === "{}" && waiting[0].dependsOn?.[0] === "c1", "a blocked verdict keeps its body and what it waits on");
+		}],
+		["an alias resolves in its own tenant only, and a local id names one record", async (store) => {
+			await store.transaction((tx) => store.alias(tx, {
+				tenantId: "branch-a",
+				localId: "cust-local",
+				serverId: "cust-1"
+			}));
+			const [own, other] = await store.transaction(async (tx) => [await store.aliasOf(tx, "branch-a", "cust-local"), await store.aliasOf(tx, "branch-b", "cust-local")]);
+			check(own === "cust-1" && other === null, "an alias is tenant-scoped");
+			await store.transaction((tx) => store.alias(tx, {
+				tenantId: "branch-a",
+				localId: "cust-local",
+				serverId: "cust-1"
+			}));
+			let refused = false;
+			await store.transaction((tx) => store.alias(tx, {
+				tenantId: "branch-a",
+				localId: "cust-local",
+				serverId: "cust-2"
+			})).catch(() => refused = true);
+			check(refused, "a local id already naming one record must not be re-pointed");
+		}],
+		["a transaction that throws leaves no stream, verdict or feed entry", async (store) => {
+			await store.transaction(async (tx) => {
+				await store.advance(tx, "s1", "branch-a", 0, 1);
+				await store.record(tx, verdict());
+				await store.alias(tx, {
+					tenantId: "branch-a",
+					localId: "cust-local",
+					serverId: "cust-1"
+				});
+				await store.changes.append({
+					scope: "order",
+					docId: "o1",
+					op: "upsert",
+					version: 1,
+					doc: {},
+					tenantId: "branch-a"
+				}, { session: tx.session });
+				throw new Error("abort");
+			}).catch(() => void 0);
+			await store.transaction(async (tx) => {
+				check(await store.stream(tx, "s1") === null, "an aborted advance must not persist");
+				check(await store.verdict(tx, "c1") === null, "an aborted verdict must not persist");
+				check(await store.aliasOf(tx, "branch-a", "cust-local") === null, "an aborted alias must not persist");
+			});
+			check((await store.changes.since("")).changes.length === 0, "an aborted feed entry must not persist");
+		}],
+		["transactions moving one stream serialise: twenty concurrent advances reach 20", async (store) => {
+			await Promise.all(Array.from({ length: 20 }, () => store.transaction(async (tx) => {
+				const at = (await store.stream(tx, "s1"))?.processed ?? 0;
+				check(await store.advance(tx, "s1", "branch-a", at, at + 1), "a serialised advance must find the stream where it read it");
+			})));
+			const stream = await store.transaction((tx) => store.stream(tx, "s1"));
+			check(stream?.processed === 20, `twenty advances must reach 20, got ${stream?.processed}`);
+		}]
+	].map(([name, body]) => ({
+		name,
+		run: async () => body(await harness.createStore())
+	}));
+}
+/** The contract as a vitest suite. */
+function runCommandStreamStoreConformance(harness) {
+	describe("CommandStreamStore conformance", () => {
+		for (const c of commandStreamStoreCases(harness)) it(c.name, c.run, 6e4);
+	});
+}
+//#endregion
+export { commandStreamStoreCases, runCommandStreamStoreConformance };

package/dist/testing/index.d.mts

@@ -1,4 +1,6 @@
 import { AggregateOpsSupport } from "../repository/capabilities.mjs";
+import { ChangeLogConformanceHarness, changeLogStoreCases, runChangeLogStoreConformance } from "./change-log-conformance.mjs";
+import { CommandStreamConformanceHarness, commandStreamStoreCases, runCommandStreamStoreConformance } from "./command-stream-conformance.mjs";
 import { ConformanceContext, ConformanceDoc, ConformanceFeatures, ConformanceHarness } from "./types.mjs";
 import { runStandardRepoConformance } from "./conformance.mjs";
 import { IdempotencyConformanceHarness, idempotencyStoreCases, runIdempotencyStoreConformance } from "./idempotency-conformance.mjs";
@@ -6,4 +8,4 @@ import { LockConformanceHarness, runLockAdapterConformance } from "./lock-confor
 import { PurgeConformanceContext, PurgeConformanceHarness, runPurgeConformance } from "./purge-conformance.mjs";
 import { QUERY_GRAMMAR_DOCS, QUERY_GRAMMAR_FILTER_CASES, QUERY_GRAMMAR_PAGING_CASES, QUERY_GRAMMAR_REFUSED, QueryGrammarCaseOptions, QueryGrammarConformanceOptions, QueryGrammarHarness, QueryGrammarParsed, runQueryGrammarConformance } from "./query-grammar-conformance.mjs";
 import { UsageConformanceHarness, runUsageStoreContract } from "./usage-conformance.mjs";
-export { type AggregateOpsSupport, type ConformanceContext, type ConformanceDoc, type ConformanceFeatures, type ConformanceHarness, type IdempotencyConformanceHarness, type LockConformanceHarness, type PurgeConformanceContext, type PurgeConformanceHarness, QUERY_GRAMMAR_DOCS, QUERY_GRAMMAR_FILTER_CASES, QUERY_GRAMMAR_PAGING_CASES, QUERY_GRAMMAR_REFUSED, type QueryGrammarCaseOptions, type QueryGrammarConformanceOptions, type QueryGrammarHarness, type QueryGrammarParsed, type UsageConformanceHarness, idempotencyStoreCases, runIdempotencyStoreConformance, runLockAdapterConformance, runPurgeConformance, runQueryGrammarConformance, runStandardRepoConformance, runUsageStoreContract };
+export { type AggregateOpsSupport, type ChangeLogConformanceHarness, type CommandStreamConformanceHarness, type ConformanceContext, type ConformanceDoc, type ConformanceFeatures, type ConformanceHarness, type IdempotencyConformanceHarness, type LockConformanceHarness, type PurgeConformanceContext, type PurgeConformanceHarness, QUERY_GRAMMAR_DOCS, QUERY_GRAMMAR_FILTER_CASES, QUERY_GRAMMAR_PAGING_CASES, QUERY_GRAMMAR_REFUSED, type QueryGrammarCaseOptions, type QueryGrammarConformanceOptions, type QueryGrammarHarness, type QueryGrammarParsed, type UsageConformanceHarness, changeLogStoreCases, commandStreamStoreCases, idempotencyStoreCases, runChangeLogStoreConformance, runCommandStreamStoreConformance, runIdempotencyStoreConformance, runLockAdapterConformance, runPurgeConformance, runQueryGrammarConformance, runStandardRepoConformance, runUsageStoreContract };

package/dist/testing/index.mjs

@@ -1,7 +1,9 @@
+import { changeLogStoreCases, runChangeLogStoreConformance } from "./change-log-conformance.mjs";
+import { commandStreamStoreCases, runCommandStreamStoreConformance } from "./command-stream-conformance.mjs";
 import { runStandardRepoConformance } from "./conformance.mjs";
 import { idempotencyStoreCases, runIdempotencyStoreConformance } from "./idempotency-conformance.mjs";
 import { runLockAdapterConformance } from "./lock-conformance.mjs";
 import { runPurgeConformance } from "./purge-conformance.mjs";
 import { QUERY_GRAMMAR_DOCS, QUERY_GRAMMAR_FILTER_CASES, QUERY_GRAMMAR_PAGING_CASES, QUERY_GRAMMAR_REFUSED, runQueryGrammarConformance } from "./query-grammar-conformance.mjs";
 import { runUsageStoreContract } from "./usage-conformance.mjs";
-export { QUERY_GRAMMAR_DOCS, QUERY_GRAMMAR_FILTER_CASES, QUERY_GRAMMAR_PAGING_CASES, QUERY_GRAMMAR_REFUSED, idempotencyStoreCases, runIdempotencyStoreConformance, runLockAdapterConformance, runPurgeConformance, runQueryGrammarConformance, runStandardRepoConformance, runUsageStoreContract };
+export { QUERY_GRAMMAR_DOCS, QUERY_GRAMMAR_FILTER_CASES, QUERY_GRAMMAR_PAGING_CASES, QUERY_GRAMMAR_REFUSED, changeLogStoreCases, commandStreamStoreCases, idempotencyStoreCases, runChangeLogStoreConformance, runCommandStreamStoreConformance, runIdempotencyStoreConformance, runLockAdapterConformance, runPurgeConformance, runQueryGrammarConformance, runStandardRepoConformance, runUsageStoreContract };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/repo-core",
-  "version": "0.29.0",
+  "version": "0.30.0",
   "description": "Driver-agnostic repository primitives: hooks, Filter IR, operations, pagination, cache contract. Foundation for mongokit, sqlitekit, pgkit, and prismakit. Lean by design \u2014 no plugins ship here; each kit owns its own.",
   "type": "module",
   "sideEffects": false,