@byollm/relay 0.1.0-alpha.9 → 0.1.0-alpha.91

package/dist/store-contract.d.ts

@@ -0,0 +1,77 @@
+import { R as RoutingStore } from './store-BNhCedHZ.js';
+import '@byollm/protocol';
+
+/**
+ * The routing store's behaviour, written once and run against every
+ * implementation — cloud_008 finding 54.
+ *
+ * There were two copies. This package tested `RelayState`; `byollm-cloud`
+ * tested `ValkeyRoutingStore` with a file that opened by explaining it was
+ * "written once and parameterised… a second copy of the scenario is a second
+ * place for two implementations to quietly diverge" — and was itself the
+ * second copy. It had drifted to sixteen cases against the eighteen in the
+ * ledger, which is exactly the divergence the sentence predicted, happening
+ * to the sentence.
+ *
+ * So the contract lives here, in the package that declares `RoutingStore`,
+ * and both repositories import it. A store that cannot pass this is not a
+ * routing store, whatever it implements.
+ *
+ * ## Why this ships in the published package
+ *
+ * Because the implementation that matters most is in another repository. A
+ * contract only the author can run is a description; one a third party runs
+ * against their own implementation is a contract. `@byollm/relay/store-contract`
+ * is a subpath export so nothing that imports the relay itself pulls in a
+ * test framework.
+ *
+ * ## What this cannot prove
+ *
+ * `CLAIM_ATOMIC` is a MUST and every case here would pass against a store
+ * that read, decided and wrote in three steps — in one process there is
+ * nothing to interleave. Concurrency belongs with the implementation that
+ * has a network in it, and `byollm-cloud`'s suite runs it against Valkey with
+ * many connections. Named here so the omission is a decision rather than an
+ * oversight.
+ */
+/** The control-plane site id these cases route under. */
+declare const CONTRACT_SITE = "site_store";
+interface StoreContractOptions {
+    /**
+     * A fresh, empty store, and how to dispose of it.
+     *
+     * Arrow-typed rather than a method, because the caller passes these
+     * around: a method signature lets `this` travel with the call, and a
+     * factory read off an options object is exactly where that goes wrong.
+     */
+    readonly make: () => Promise<{
+        store: RoutingStore;
+        done: () => Promise<void>;
+    }>;
+    /**
+     * Whether this store writes stubs as bytes and reads them back.
+     *
+     * An in-process store holds typed objects and cannot hold a stub it cannot
+     * parse; a serialising one can, because what it wrote may have been written
+     * by a previous version. The case that covers it is skipped rather than
+     * hidden — a reader should know which half of this contract each store is
+     * proving (cloud_008 §2.1a).
+     */
+    readonly serialising?: boolean;
+    /**
+     * Move this store's clock, for the cases that are about time — B187.
+     *
+     * Optional, and the cases that need it skip without it, on the same
+     * reasoning `serialising` is written down: a reader should know which half
+     * of this contract each store is proving. A store that cannot be advanced
+     * is not broken, it is untested here — and the sticky re-offer is exactly
+     * the rule a second implementation would get wrong quietly.
+     */
+    readonly advance?: (store: RoutingStore, ms: number) => Promise<void>;
+    /** Write a stub's raw bytes, bypassing serialisation. */
+    readonly writeRawStub?: (store: RoutingStore, id: string, raw: string) => Promise<void>;
+}
+/** Run the contract. Call inside a suite; it declares its own `describe`. */
+declare function describeStoreContract(name: string, options: StoreContractOptions): void;
+
+export { CONTRACT_SITE, type StoreContractOptions, describeStoreContract };