@sensigo/realm-testing 0.25.0 → 0.27.0

package/dist/index.d.ts

@@ -1,6 +1,10 @@
 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 { runStoreFidelityContract } from './store/run-store-fidelity-contract.js';
+export type { RunStoreFidelityLaw, RunStoreFidelityContractCase, RunStoreFidelityContractAdapter, } from './store/run-store-fidelity-contract.js';
+export { fencedTraceBufferContract } from './store/fenced-trace-buffer-contract.js';
+export type { FencedTraceBufferLaw, FencedTraceBufferContractCase, FencedTraceBufferContractAdapter, } from './store/fenced-trace-buffer-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';
@@ -15,5 +19,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.25.0";
+export declare const VERSION = "0.27.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;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"}
+{"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;AACpD,OAAO,EAAE,wBAAwB,EAAE,MAAM,wCAAwC,CAAC;AAClF,YAAY,EACV,mBAAmB,EACnB,4BAA4B,EAC5B,+BAA+B,GAChC,MAAM,wCAAwC,CAAC;AAChD,OAAO,EAAE,yBAAyB,EAAE,MAAM,yCAAyC,CAAC;AACpF,YAAY,EACV,oBAAoB,EACpB,6BAA6B,EAC7B,gCAAgC,GACjC,MAAM,yCAAyC,CAAC;AAGjD,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

@@ -2,6 +2,8 @@
 // Store
 export { InMemoryStore } from './store/in-memory-store.js';
 export { perRunArtifactStoreContract } from './store/per-run-artifact-store-contract.js';
+export { runStoreFidelityContract } from './store/run-store-fidelity-contract.js';
+export { fencedTraceBufferContract } from './store/fenced-trace-buffer-contract.js';
 // Fixtures
 export { loadFixtureFromFile, loadFixtureFromString, loadFixturesFromDir, } from './fixtures/fixture-loader.js';
 // Mocks
@@ -18,5 +20,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.25.0';
+export const VERSION = '0.27.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;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"}
+{"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;AAMzF,OAAO,EAAE,wBAAwB,EAAE,MAAM,wCAAwC,CAAC;AAMlF,OAAO,EAAE,yBAAyB,EAAE,MAAM,yCAAyC,CAAC;AAOpF,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/fenced-trace-buffer-contract.d.ts

@@ -0,0 +1,87 @@
+import { type TraceBufferStore } from '@sensigo/realm';
+/**
+ * One of the laws every fenced-trio-declaring `TraceBufferStore` must satisfy. The original five
+ * (issue #207) cover the fenced trio itself; the remaining five (issue #197 PR-1) cover the
+ * optional capability-ladder rungs a trio-declaring store MAY additionally declare (`seal` and
+ * `writer_nonce_carriage`) — each of those five produces an explicit, VISIBLE documented-skip case
+ * (never a silent omission) for a store that does not declare the relevant rung, mirroring the
+ * `fenceForm: 'native-predicate'` skip precedent already established for the latch-based trio
+ * laws below.
+ */
+export type FencedTraceBufferLaw = 'STRUCTURAL' | 'FENCE_REFUSES' | 'CS_OCCUPANCY' | 'PER_KEY_INDEPENDENCE' | 'NO_SILENT_LOSS' | 'CARRIAGE_ROUND_TRIP' | 'SEAL' | 'SEAL_BUDGET' | 'PER_WRITER_BUDGET' | 'VERBATIM';
+/**
+ * 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 FencedTraceBufferContractCase {
+    law: FencedTraceBufferLaw;
+    name: string;
+    run: () => Promise<void>;
+}
+/** Adapter a calling test file supplies to parameterize the contract against one concrete store. */
+export interface FencedTraceBufferContractAdapter {
+    /** The store under test — already declaring the fenced trio (`appendFenced`/`deleteFenced`/
+     *  `deleteAllForRunFenced`). For `fenceForm: 'guard-in-cs'` stores, this instance should already
+     *  be constructed with a sufficiently generous lock-acquisition profile (see `lockProfile`
+     *  below) so a deliberately-parked guard in the latch-based laws doesn't cause a concurrent
+     *  caller's own acquisition attempt to give up before the law's observation window completes. */
+    store: TraceBufferStore;
+    /** Returns a fresh, never-before-used (runId, stepId) pair for one case — callers should treat
+     *  every returned pair as belonging to a disjoint run from every other pair this returns. */
+    makeKey: () => {
+        runId: string;
+        stepId: string;
+    };
+    /**
+     * `'guard-in-cs'`: the store enforces the fence via an in-process critical section — the guard
+     * literally runs inside the same lock/mutex the destructive effect does. `'native-predicate'`:
+     * the store enforces the fence via a transaction-scoped SQL predicate instead (e.g. a future
+     * Postgres store) — the latch-based laws (`CS_OCCUPANCY`, `PER_KEY_INDEPENDENCE`,
+     * `NO_SILENT_LOSS`) do not apply to this fence form and produce an explicit, VISIBLE
+     * documented-skip case rather than a silent omission. **A green TCK run does NOT verify race
+     * closure for a native-predicate store** — that store's own in-transaction fencing suite must
+     * (the same posture `RunStore.claimStep`'s cross-host obligation already states for
+     * `CLAIM_SINGLE_OWNER`, issue #188).
+     */
+    fenceForm: 'guard-in-cs' | 'native-predicate';
+    /** Descriptive only (present for `'guard-in-cs'` adapters): the lock-acquisition profile the
+     *  `store` instance above was actually constructed with, for the calling test file's own
+     *  documentation — the TCK itself does not need to act on this value; it exists so a wiring
+     *  test can assert (and a reader can see) that a genuinely generous profile is in use. */
+    lockProfile?: unknown;
+    /**
+     * Per-adapter byte oracle for `PER_WRITER_BUDGET` (issue #197 PR-1) — since the in-memory and fs
+     * stores compute "bytes" via genuinely different formulas (whole-array restringify vs
+     * JSONL-additive), this TCK can only assert exact ENTRY COUNTS store-agnostically; exact BYTE
+     * equality needs each adapter to supply its own oracle, computed however that concrete store's
+     * own `AppendResult.buffer_bytes`/`file_bytes` are actually derived. Optional — a store without
+     * this hook still runs every count-based `PER_WRITER_BUDGET` assertion; only the byte-exactness
+     * sub-assertion is skipped (visibly, never silently) for that adapter.
+     */
+    bytesOracle?: (runId: string, stepId: string, writerNonce: string | undefined) => Promise<{
+        count: number;
+        bytes: number;
+    }>;
+    /**
+     * fs-scoped raw on-disk byte access for `VERBATIM` (issue #197 PR-1) — reads the RAW bytes of a
+     * live WAL path and of one sealed artifact (`seq`), so the law can assert a seal moves bytes
+     * byte-for-byte (no parse/re-copy/truncation/dedup). `undefined` from either function means "no
+     * file at that path" (mirrors `readIfExists`'s absence convention). Optional — a store without
+     * this hook (e.g. the in-memory store, which has no on-disk representation at all) skips ONLY
+     * the raw-byte-exactness case; the shape-tolerant sibling case still runs unconditionally for
+     * every `seal`-declaring store.
+     */
+    rawWalAccess?: {
+        readLiveRaw: (runId: string, stepId: string) => Promise<string | undefined>;
+        readSealedRaw: (runId: string, stepId: string, seq: number) => Promise<string | undefined>;
+    };
+}
+/**
+ * Builds the contract cases for `adapter`. See each law's own doc above (the `build*Case`
+ * functions) for what it asserts. For `fenceForm: 'native-predicate'` adapters, `CS_OCCUPANCY`,
+ * `PER_KEY_INDEPENDENCE`, and `NO_SILENT_LOSS` are replaced with an explicit, VISIBLE
+ * documented-skip case each (never a silent omission) — see the adapter's own `fenceForm` doc.
+ */
+export declare function fencedTraceBufferContract(adapter: FencedTraceBufferContractAdapter): FencedTraceBufferContractCase[];
+//# sourceMappingURL=fenced-trace-buffer-contract.d.ts.map

package/dist/store/fenced-trace-buffer-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fenced-trace-buffer-contract.d.ts","sourceRoot":"","sources":["../../src/store/fenced-trace-buffer-contract.ts"],"names":[],"mappings":"AAcA,OAAO,EAGL,KAAK,gBAAgB,EAStB,MAAM,gBAAgB,CAAC;AAExB;;;;;;;;GAQG;AACH,MAAM,MAAM,oBAAoB,GAC5B,YAAY,GACZ,eAAe,GACf,cAAc,GACd,sBAAsB,GACtB,gBAAgB,GAChB,qBAAqB,GACrB,MAAM,GACN,aAAa,GACb,mBAAmB,GACnB,UAAU,CAAC;AAEf;;;;GAIG;AACH,MAAM,WAAW,6BAA6B;IAC5C,GAAG,EAAE,oBAAoB,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED,oGAAoG;AACpG,MAAM,WAAW,gCAAgC;IAC/C;;;;qGAIiG;IACjG,KAAK,EAAE,gBAAgB,CAAC;IACxB;iGAC6F;IAC7F,OAAO,EAAE,MAAM;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACjD;;;;;;;;;;OAUG;IACH,SAAS,EAAE,aAAa,GAAG,kBAAkB,CAAC;IAC9C;;;8FAG0F;IAC1F,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,CACZ,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,GAAG,SAAS,KAC5B,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAE/C;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE;QACb,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;QAC5E,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;KAC5F,CAAC;CACH;AAk1BD;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,gCAAgC,GACxC,6BAA6B,EAAE,CAuVjC"}