@yieldstar/runtime-conformance 0.0.0-stage → 0.6.1

package/README.md

@@ -1,3 +1,104 @@
-# Temporary Holding Version
+# `@yieldstar/runtime-conformance`
+
+This package contains the runnable qualification suites for YieldStar runtimes: one for store connectors, one for the execution client and one for the effect client. The normative protocol is documented in the [store connector conformance specification](https://github.com/notationlabs/yieldstar/blob/main/docs/store-connector-spec.md).
+
+Install it with the test runner and core package:
+
+```sh
+pnpm add -D @yieldstar/core @yieldstar/runtime-conformance vitest
+```
+
+Register the suite from a Vitest test file. The only required integration point is a factory that creates a clean backend and returns a `Runtime` built on it. Store wakes are observed through the runtime's `ExecutionClient`: the suite admits the executions that wait on stores, and a commit that satisfies a waiter must make that execution due, so `runtime.executions.claimDue()` returns it.
+
+```ts
+import { registerStoreClientConformance } from "@yieldstar/runtime-conformance";
+import { MyRuntime } from "./my-runtime";
+
+registerStoreClientConformance({
+  name: "my-store",
+  create() {
+    const backend = createCleanBackend();
+    return {
+      runtime: new MyRuntime(backend),
+      dispose: () => backend.close(),
+    };
+  },
+});
+```
+
+The base factory qualifies a process-local runtime. A backend that supports multiple clients should also return `createPeer`, a runtime over the same backend as another process would open; a durable backend should additionally return `restart`. These capabilities activate the shared-client race and crash-recovery suites:
+
+```ts
+create() {
+  const backend = createCleanBackend();
+  const runtime = new MyRuntime(backend);
+  return {
+    runtime,
+    createPeer: () => new MyRuntime(backend),
+    restart: async () => {
+      await runtime.close();
+      return new MyRuntime(backend.reopen());
+    },
+    dispose: () => backend.close(),
+  };
+}
+```
+
+Run the test with either supported runtime:
+
+```sh
+vitest run runtime-conformance.test.ts
+```
+
+## Execution client suite
+
+`registerExecutionClientConformance` checks a runtime's `ExecutionClient` and fenced heap writes: admission, wake merging, claims, acknowledgement and terminal outcomes; leases, renewal, release and the `running` status; the redelivery delay and `unacknowledgedDeliveryCount`; fencing of heap writes, renewals, releases and acknowledgements against a stale holder; and `start`, its idempotency by request ID, parameter validation, mismatches and the target's parent link. The suite passes a `clock` to `create`; build every runtime on it so the suite controls time, including lease expiry.
+
+The harness has three optional capabilities:
+
+- `createPeer` returns another runtime over the same backend, as a second runtime process would. The suite uses it to race two clients for one execution and to reclaim an expired lease from a different client than the one that holds it. Return it whenever several processes can share the backend; without it those cases run both sides on `runtime`, which proves less.
+- `restart` reopens the same durable backend in a new runtime. It enables the restart cases; without it they are skipped.
+- `failStartCommits` makes every new `start` on `runtime` fail after it begins writing but before it commits, and returns a function that stops the failures. It enables the case that a failed start leaves no trace; without it that case is skipped. The SQLite harness installs a temporary trigger that aborts the start-request insert.
+
+```ts
+import { registerExecutionClientConformance } from "@yieldstar/runtime-conformance";
+import { MyRuntime } from "./my-runtime";
+
+registerExecutionClientConformance({
+  name: "my-runtime",
+  create({ clock }) {
+    const backend = createCleanBackend();
+    return {
+      runtime: new MyRuntime(backend, { clock }),
+      // A separate connection, as another process would open.
+      createPeer: () => new MyRuntime(backend.connect(), { clock }),
+      restart: () => new MyRuntime(backend.reopen(), { clock }),
+      dispose: () => backend.close(),
+    };
+  },
+});
+```
+
+## Effect client suite
+
+`registerEffectClientConformance` checks a runtime's `EffectClient`: `begin` creating or reading one effect, mismatched operations and inputs, concurrent equal and different settlements and their conflict reports, `watch` registration and immediate wakes, settlement racing `watch`, waiter deletion with the step's result and its rejection for a stale holder, value encoding, and durability across a restart. Its harness takes the same `clock`, `createPeer` and `restart` as the execution client suite, plus `failEffectWatches`, which makes every `watch` on `runtime` fail before it commits and returns a function that stops the failures. Without it the case for a failed watch is skipped; the SQLite harness installs a temporary trigger that aborts the waiter insert.
+
+```ts
+import { registerEffectClientConformance } from "@yieldstar/runtime-conformance";
+
+registerEffectClientConformance({
+  name: "my-runtime",
+  create({ clock }) {
+    const backend = createCleanBackend();
+    return {
+      runtime: new MyRuntime(backend, { clock }),
+      createPeer: () => new MyRuntime(backend.connect(), { clock }),
+      restart: () => new MyRuntime(backend.reopen(), { clock }),
+      dispose: () => backend.close(),
+    };
+  },
+});
+```
+
+The suite covers the runtime adapter. The workflow-driver and delivery cases for `step.start` and `step.effect` are tested in the repository rather than here (`test/start.test.ts`, `test/effect.test.ts` and `test/effect-delivery.test.ts`). The dispatcher and worker cases, such as concurrency, releasing on a retry reply, a worker that exits without replying, and a worker whose runtime process dies, are properties of `ExecutionDispatcher` and the invoker rather than of an adapter; the repository tests them in `test/dispatcher.test.ts` and `test/worker-invoker.test.ts`.
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.

package/dist/effect.d.ts

@@ -0,0 +1,33 @@
+import { type Runtime } from "@yieldstar/core";
+export type EffectConformanceHarnessOptions = {
+    /** The suite's clock. Construct the runtime with it. */
+    clock: () => number;
+};
+/** A clean runtime under test, built on the suite's clock. */
+export type EffectConformanceHarness = {
+    runtime: Runtime;
+    /**
+     * Creates another runtime sharing the same backend, as another process
+     * would. Race cases fall back to `runtime` when it is absent.
+     */
+    createPeer?(): Runtime | Promise<Runtime>;
+    /** Opens the same durable backend in a new runtime, as after a restart. */
+    restart?(): Runtime | Promise<Runtime>;
+    /**
+     * Makes every `watch` on `runtime` fail after it begins writing but before
+     * it commits, until the returned function is called. Without it, the case
+     * for a failure before a watch commits is skipped.
+     */
+    failEffectWatches?(): (() => void | Promise<void>) | Promise<() => void | Promise<void>>;
+    dispose?(): void | Promise<void>;
+};
+export type EffectConformanceOptions = {
+    name: string;
+    create(options: EffectConformanceHarnessOptions): EffectConformanceHarness | Promise<EffectConformanceHarness>;
+};
+/**
+ * Registers the runtime-adapter suite for `EffectClient` and the wakes it
+ * requests (RFC 005).
+ */
+export declare function registerEffectClientConformance({ name, create, }: EffectConformanceOptions): void;
+//# sourceMappingURL=effect.d.ts.map

package/dist/effect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effect.d.ts","sourceRoot":"","sources":["../src/effect.ts"],"names":[],"mappings":"AAAA,OAAO,EASL,KAAK,OAAO,EACb,MAAM,iBAAiB,CAAC;AAGzB,MAAM,MAAM,+BAA+B,GAAG;IAC5C,wDAAwD;IACxD,KAAK,EAAE,MAAM,MAAM,CAAC;CACrB,CAAC;AAEF,8DAA8D;AAC9D,MAAM,MAAM,wBAAwB,GAAG;IACrC,OAAO,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,UAAU,CAAC,IAAI,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1C,2EAA2E;IAC3E,OAAO,CAAC,IAAI,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACvC;;;;OAIG;IACH,iBAAiB,CAAC,IACd,CAAC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,GAC5B,OAAO,CAAC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACxC,OAAO,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClC,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CACJ,OAAO,EAAE,+BAA+B,GACvC,wBAAwB,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAAC;CACjE,CAAC;AA8BF;;;GAGG;AACH,wBAAgB,+BAA+B,CAAC,EAC9C,IAAI,EACJ,MAAM,GACP,EAAE,wBAAwB,GAAG,IAAI,CA6rBjC"}

package/dist/execution.d.ts

@@ -0,0 +1,36 @@
+import { type Runtime } from "@yieldstar/core";
+export type ExecutionConformanceHarnessOptions = {
+    /**
+     * The suite's clock. Construct the runtime with it, so due times, lease
+     * expiry and redelivery delays are deterministic.
+     */
+    clock: () => number;
+};
+/** A clean runtime under test, built on the suite's clock. */
+export type ExecutionConformanceHarness = {
+    runtime: Runtime;
+    /**
+     * Creates another runtime sharing the same backend, as another process
+     * would. Cases that need one fall back to `runtime` when it is absent.
+     */
+    createPeer?(): Runtime | Promise<Runtime>;
+    /** Opens the same durable backend in a new runtime, as after a restart. */
+    restart?(): Runtime | Promise<Runtime>;
+    /**
+     * Makes every new start on `runtime` fail after it begins writing but before
+     * it commits, until the returned function is called. Without it, the case
+     * for a failure before a start commits is skipped.
+     */
+    failStartCommits?(): (() => void | Promise<void>) | Promise<() => void | Promise<void>>;
+    dispose?(): void | Promise<void>;
+};
+export type ExecutionConformanceOptions = {
+    name: string;
+    create(options: ExecutionConformanceHarnessOptions): ExecutionConformanceHarness | Promise<ExecutionConformanceHarness>;
+};
+/**
+ * Registers the runtime-adapter suite for `ExecutionClient` and fenced heap
+ * writes (RFC 001, RFC 002 and RFC 003).
+ */
+export declare function registerExecutionClientConformance({ name, create, }: ExecutionConformanceOptions): void;
+//# sourceMappingURL=execution.d.ts.map

package/dist/execution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution.d.ts","sourceRoot":"","sources":["../src/execution.ts"],"names":[],"mappings":"AAAA,OAAO,EASL,KAAK,OAAO,EAGb,MAAM,iBAAiB,CAAC;AAGzB,MAAM,MAAM,kCAAkC,GAAG;IAC/C;;;OAGG;IACH,KAAK,EAAE,MAAM,MAAM,CAAC;CACrB,CAAC;AAEF,8DAA8D;AAC9D,MAAM,MAAM,2BAA2B,GAAG;IACxC,OAAO,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,UAAU,CAAC,IAAI,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1C,2EAA2E;IAC3E,OAAO,CAAC,IAAI,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACvC;;;;OAIG;IACH,gBAAgB,CAAC,IAAI,CAAC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACxF,OAAO,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClC,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CACJ,OAAO,EAAE,kCAAkC,GAC1C,2BAA2B,GAAG,OAAO,CAAC,2BAA2B,CAAC,CAAC;CACvE,CAAC;AAwDF;;;GAGG;AACH,wBAAgB,kCAAkC,CAAC,EACjD,IAAI,EACJ,MAAM,GACP,EAAE,2BAA2B,GAAG,IAAI,CAg/DpC"}

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+import { type Runtime } from "@yieldstar/core";
+export { registerEffectClientConformance, type EffectConformanceHarness, type EffectConformanceHarnessOptions, type EffectConformanceOptions, } from "./effect";
+export { registerExecutionClientConformance, type ExecutionConformanceHarness, type ExecutionConformanceHarnessOptions, type ExecutionConformanceOptions, } from "./execution";
+/**
+ * A clean runtime under test. Store wakes are observed through its
+ * `ExecutionClient`: a commit that satisfies a waiter makes the waiter's
+ * execution due, so `runtime.executions.claimDue()` returns it.
+ */
+export type StoreConformanceHarness = {
+    runtime: Runtime;
+    /** Creates another runtime connected to the same backend. */
+    createPeer?(): Runtime | Promise<Runtime>;
+    /** Simulates opening the same durable backend in a new process. */
+    restart?(): Runtime | Promise<Runtime>;
+    dispose?(): void | Promise<void>;
+};
+export type StoreConformanceFactory = () => StoreConformanceHarness | Promise<StoreConformanceHarness>;
+export type StoreConformanceOptions = {
+    name: string;
+    create: StoreConformanceFactory;
+};
+/** Registers the normative YieldStar store connector qualification suite. */
+export declare function registerStoreClientConformance({ name, create, }: StoreConformanceOptions): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,OAAO,EAKb,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,+BAA+B,EAC/B,KAAK,wBAAwB,EAC7B,KAAK,+BAA+B,EACpC,KAAK,wBAAwB,GAC9B,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,kCAAkC,EAClC,KAAK,2BAA2B,EAChC,KAAK,kCAAkC,EACvC,KAAK,2BAA2B,GACjC,MAAM,aAAa,CAAC;AAErB;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,6DAA6D;IAC7D,UAAU,CAAC,IAAI,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1C,mEAAmE;IACnE,OAAO,CAAC,IAAI,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACvC,OAAO,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClC,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG,MAClC,uBAAuB,GACvB,OAAO,CAAC,uBAAuB,CAAC,CAAC;AAErC,MAAM,MAAM,uBAAuB,GAAG;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,uBAAuB,CAAC;CACjC,CAAC;AAkJF,6EAA6E;AAC7E,wBAAgB,8BAA8B,CAAC,EAC7C,IAAI,EACJ,MAAM,GACP,EAAE,uBAAuB,GAAG,IAAI,CA+9ChC"}