@sensigo/realm-testing 0.22.0 → 0.24.0

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export { InMemoryStore } from './store/in-memory-store.js';
+export { perRunArtifactStoreContract } from './store/per-run-artifact-store-contract.js';
+export type { ArtifactStoreLaw, ArtifactStoreContractCase, PerRunArtifactStoreContractAdapter, } from './store/per-run-artifact-store-contract.js';
 export { loadFixtureFromFile, loadFixtureFromString, loadFixturesFromDir, } from './fixtures/fixture-loader.js';
 export type { TestFixture, MockOperations } from './fixtures/fixture-loader.js';
 export { MockServiceRecorder } from './mocks/mock-service.js';
@@ -13,5 +15,5 @@ export { runFixtureTests } from './runner/test-runner.js';
 export type { TestResult, RunFixtureTestsOptions } from './runner/test-runner.js';
 export { startGitHubMockServer } from './servers/github-mock-server.js';
 export type { GitHubMockServerHandle } from './servers/github-mock-server.js';
-export declare const VERSION = "0.22.0";
+export declare const VERSION = "0.24.0";
 //# 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":"AAGA,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAG3D,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,8BAA8B,CAAC;AACtC,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAGhF,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,YAAY,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAG3D,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACjE,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAGxD,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,YAAY,EAAE,UAAU,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAGlF,OAAO,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAC;AACxE,YAAY,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAE9E,eAAO,MAAM,OAAO,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,2BAA2B,EAAE,MAAM,4CAA4C,CAAC;AACzF,YAAY,EACV,gBAAgB,EAChB,yBAAyB,EACzB,kCAAkC,GACnC,MAAM,4CAA4C,CAAC;AAGpD,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,8BAA8B,CAAC;AACtC,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAGhF,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,YAAY,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAG3D,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACjE,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAGxD,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,YAAY,EAAE,UAAU,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AAGlF,OAAO,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAC;AACxE,YAAY,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAE9E,eAAO,MAAM,OAAO,WAAW,CAAC"}

package/dist/index.js

@@ -1,6 +1,7 @@
 // @sensigo/realm-testing — testing utilities for Realm workflows
 // Store
 export { InMemoryStore } from './store/in-memory-store.js';
+export { perRunArtifactStoreContract } from './store/per-run-artifact-store-contract.js';
 // Fixtures
 export { loadFixtureFromFile, loadFixtureFromString, loadFixturesFromDir, } from './fixtures/fixture-loader.js';
 // Mocks
@@ -17,5 +18,5 @@ export { testAdapter } from './helpers/test-adapter.js';
 export { runFixtureTests } from './runner/test-runner.js';
 // Servers
 export { startGitHubMockServer } from './servers/github-mock-server.js';
-export const VERSION = '0.22.0';
+export const VERSION = '0.24.0';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,iEAAiE;AAEjE,QAAQ;AACR,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAE3D,WAAW;AACX,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,8BAA8B,CAAC;AAGtC,QAAQ;AACR,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAE9D,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE3D,aAAa;AACb,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,0BAA0B,CAAC;AAElC,oBAAoB;AACpB,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACjE,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAExD,SAAS;AACT,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAG1D,UAAU;AACV,OAAO,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAC;AAGxE,MAAM,CAAC,MAAM,OAAO,GAAG,QAAQ,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,iEAAiE;AAEjE,QAAQ;AACR,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,2BAA2B,EAAE,MAAM,4CAA4C,CAAC;AAOzF,WAAW;AACX,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,8BAA8B,CAAC;AAGtC,QAAQ;AACR,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAE9D,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE3D,aAAa;AACb,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,0BAA0B,CAAC;AAElC,oBAAoB;AACpB,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACjE,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAExD,SAAS;AACT,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAG1D,UAAU;AACV,OAAO,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAC;AAGxE,MAAM,CAAC,MAAM,OAAO,GAAG,QAAQ,CAAC"}

package/dist/store/per-run-artifact-store-contract.d.ts

@@ -0,0 +1,35 @@
+import { type PerRunArtifactStore } from '@sensigo/realm';
+/** One of the four laws every `PerRunArtifactStore` implementation must satisfy (issue #183). */
+export type ArtifactStoreLaw = 'L1_ABSENCE_RESOLVES' | 'L2_IDEMPOTENT' | 'L3_FAILURE_REJECTS' | 'L4_TYPED_REJECTION';
+/**
+ * A single, framework-agnostic contract case. `run()` throws (rejects) on failure — any test
+ * framework's `await run()` (rejecting fails the test) or `expect(run()).resolves...` /
+ * `expect(run()).rejects...` maps directly onto this.
+ */
+export interface ArtifactStoreContractCase {
+    law: ArtifactStoreLaw;
+    name: string;
+    run: () => Promise<void>;
+}
+/** Adapter a calling test file supplies to parameterize the contract against one concrete store. */
+export interface PerRunArtifactStoreContractAdapter {
+    /** The store under test. */
+    store: PerRunArtifactStore;
+    /**
+     * A runId guaranteed to have at least one real, present artifact this store owns, seeded
+     * BEFORE the case runs. L2 (idempotent) and L3/L4 (failure) all act on this runId.
+     */
+    runIdWithArtifact: string;
+    /** A runId guaranteed to own NO artifact at all (never seeded). Used by L1. */
+    runIdAbsent: string;
+    /**
+     * Makes the artifact(s) for `runIdWithArtifact` genuinely unreachable (a non-ENOENT failure) —
+     * e.g. replace the target file with a directory, or mock the underlying I/O call to reject.
+     * Called immediately before L3/L4 exercise the store. The calling test file is responsible for
+     * ensuring this actually produces a hard failure on its platform — see the module doc above for
+     * why `chmod 0o500` is disqualified.
+     */
+    injectFailure: (runId: string) => void | Promise<void>;
+}
+export declare function perRunArtifactStoreContract(adapter: PerRunArtifactStoreContractAdapter): ArtifactStoreContractCase[];
+//# sourceMappingURL=per-run-artifact-store-contract.d.ts.map

package/dist/store/per-run-artifact-store-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"per-run-artifact-store-contract.d.ts","sourceRoot":"","sources":["../../src/store/per-run-artifact-store-contract.ts"],"names":[],"mappings":"AA+BA,OAAO,EAAiB,KAAK,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAEzE,iGAAiG;AACjG,MAAM,MAAM,gBAAgB,GACxB,qBAAqB,GACrB,eAAe,GACf,oBAAoB,GACpB,oBAAoB,CAAC;AAEzB;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC,GAAG,EAAE,gBAAgB,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED,oGAAoG;AACpG,MAAM,WAAW,kCAAkC;IACjD,4BAA4B;IAC5B,KAAK,EAAE,mBAAmB,CAAC;IAC3B;;;OAGG;IACH,iBAAiB,EAAE,MAAM,CAAC;IAC1B,+EAA+E;IAC/E,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxD;AAED,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,kCAAkC,GAC1C,yBAAyB,EAAE,CA8D7B"}

package/dist/store/per-run-artifact-store-contract.js

@@ -0,0 +1,96 @@
+// per-run-artifact-store-contract.ts — framework-agnostic Test Compatibility Kit (TCK) for
+// PerRunArtifactStore implementations (issue #183).
+//
+// Pure case descriptors, NOT describe/it/expect: importing vitest here would make it a runtime
+// dependency of this published package (this module ships in @sensigo/realm-testing's dist,
+// alongside runFixtureTests and the other framework-agnostic helpers in this package). Each
+// calling test file (one per concrete store) supplies an adapter and wires the returned
+// descriptors into ITS OWN test framework.
+//
+// Fault injection is an OPAQUE, adapter-supplied `injectFailure` callback — never a prescribed
+// mechanism. In particular, do NOT use `chmod 0o500` as an injector: it is a no-op on Windows and
+// silently ineffective when the test process runs as root (common in CI containers) — either way
+// L3 would pass VACUOUSLY (the "failure" never actually happens, so `deleteAllForRun` resolves
+// exactly as it should for a genuine success, and the law reports green for the wrong reason). A
+// robust injector replaces the target with a directory (works on every platform, any uid — you
+// cannot `unlink`/`readFile` a directory as if it were a file, regardless of permissions) or, for
+// a store with no filesystem at all (e.g. a future Postgres-backed store), mocks the underlying
+// I/O call to reject.
+//
+// Usage (see json-file-store.test.ts / failed-attempt-store.test.ts / json-trace-buffer-store.test.ts
+// for the real wiring): construct a FRESH adapter per law you exercise — `deleteAllForRun` is
+// destructive (L2 deletes the seeded artifact) and `injectFailure` mutates on-disk state, so
+// reusing one adapter/store instance across multiple laws in sequence is not safe.
+//
+//   const cases = perRunArtifactStoreContract(makeAdapter());
+//   for (const c of cases) {
+//     it(`${c.law}: ${c.name}`, async () => {
+//       const freshCases = perRunArtifactStoreContract(makeAdapter()); // fresh per law
+//       await freshCases.find((x) => x.law === c.law)!.run();
+//     });
+//   }
+import { WorkflowError } from '@sensigo/realm';
+export function perRunArtifactStoreContract(adapter) {
+    return [
+        {
+            law: 'L1_ABSENCE_RESOLVES',
+            name: 'deleteAllForRun resolves (never rejects) for a run that owns no artifact',
+            run: async () => {
+                await adapter.store.deleteAllForRun(adapter.runIdAbsent);
+            },
+        },
+        {
+            law: 'L2_IDEMPOTENT',
+            name: 'deleteAllForRun is idempotent — a second call after a successful delete still resolves',
+            run: async () => {
+                await adapter.store.deleteAllForRun(adapter.runIdWithArtifact);
+                await adapter.store.deleteAllForRun(adapter.runIdWithArtifact); // already gone — still resolves
+            },
+        },
+        {
+            law: 'L3_FAILURE_REJECTS',
+            name: 'deleteAllForRun rejects when the artifact exists but is genuinely unreachable (non-ENOENT)',
+            run: async () => {
+                await adapter.injectFailure(adapter.runIdWithArtifact);
+                let threw = false;
+                try {
+                    await adapter.store.deleteAllForRun(adapter.runIdWithArtifact);
+                }
+                catch {
+                    threw = true;
+                }
+                if (!threw) {
+                    throw new Error('deleteAllForRun resolved despite an injected non-ENOENT failure — the store ' +
+                        'reported success for an artifact it could not actually delete (issue #183).');
+                }
+            },
+        },
+        {
+            law: 'L4_TYPED_REJECTION',
+            name: 'the L3 rejection is a WorkflowError carrying a code and details.failures',
+            run: async () => {
+                await adapter.injectFailure(adapter.runIdWithArtifact);
+                let caught;
+                try {
+                    await adapter.store.deleteAllForRun(adapter.runIdWithArtifact);
+                    throw new Error('expected deleteAllForRun to reject, but it resolved');
+                }
+                catch (err) {
+                    caught = err;
+                }
+                if (!(caught instanceof WorkflowError)) {
+                    const kind = caught instanceof Error ? caught.constructor.name : typeof caught;
+                    throw new Error(`expected a WorkflowError rejection, got: ${kind}`);
+                }
+                if (typeof caught.code !== 'string' || caught.code.length === 0) {
+                    throw new Error('WorkflowError.code is missing or empty');
+                }
+                const failures = caught.details?.failures;
+                if (!Array.isArray(failures) || failures.length === 0) {
+                    throw new Error('WorkflowError.details.failures is missing, empty, or not an array');
+                }
+            },
+        },
+    ];
+}
+//# sourceMappingURL=per-run-artifact-store-contract.js.map

package/dist/store/per-run-artifact-store-contract.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sensigo/realm-testing",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "publishConfig": {
     "access": "public"
   },
@@ -38,7 +38,7 @@
     "lint": "eslint src"
   },
   "dependencies": {
-    "@sensigo/realm": "^0.22.0",
+    "@sensigo/realm": "^0.24.0",
     "js-yaml": "^4.2.0"
   },
   "devDependencies": {