@rulvar/store-conformance 1.68.0 → 1.70.0

package/README.md

@@ -2,9 +2,13 @@
 
 The executable conformance kit for Rulvar store adapters: append
 atomicity, total per-run order, read-your-writes, payload opacity, lease
-fencing, and golden fold-state fixtures. If you implement a custom
-store, this suite is the contract your implementation must pass. Exports
-`journalStoreConformance`, `leasableStoreConformance`, and
+fencing, golden fold-state fixtures, the adversarial multi-process soak,
+and the engine-level kill-point suite (a child process SIGKILLed around
+each durable write, resumed from another process, with the documented
+re-pay counts asserted). If you implement a custom store, this suite is
+the contract your implementation must pass. Exports
+`journalStoreConformance`, `leasableStoreConformance`,
+`runMultiProcessSoak`, `killPointConformance`, and
 `registerConformance`.
 
 Part of [Rulvar](https://rulvar.com), an embeddable TypeScript engine

package/dist/index.d.ts

@@ -278,6 +278,195 @@ declare function verifySoakHistory(fixture: FencedTranscriptsFixture, events: re
 */
 declare function runMultiProcessSoak(options: MultiProcessSoakOptions): Promise<MultiProcessSoakResult>;
 //#endregion
+//#region src/kill-points.d.ts
+/** The five durable writes a scenario kills around. */
+type KillPointName = "running" | "ok-terminal" | "limit-terminal" | "settle" | "meta";
+/** `before` = the write is lost; `after` = everything past it is lost. */
+type KillPointPhase = "before" | "after";
+/** The two scripted runs: two plain steps, or one tool-capped agent. */
+type KillPointWorkflowKind = "happy" | "limit";
+/** The pinned recovery semantics a scenario asserts. */
+interface KillPointExpectation {
+  /** Provider calls the child paid before dying. */
+  childCalls: number;
+  /** Tool executions the child performed before dying. */
+  childToolExecutions: number;
+  /** Provider calls the resume pays (the bracket's documented re-pay). */
+  resumeCalls: number;
+  /** Tool executions during the resume. */
+  resumeToolExecutions: number;
+  /** `agent` terminals with status `limit` in the final journal. */
+  limitTerminals: number;
+  /** The workflow value after recovery. */
+  value: unknown;
+}
+interface KillPointScenario {
+  /** Stable scenario id (`<workflow>-<point>-<phase>`). */
+  id: string;
+  workflow: KillPointWorkflowKind;
+  point: KillPointName;
+  phase: KillPointPhase;
+  /** Which matching write dies (1-based; step two of the happy run is 2). */
+  occurrence: number;
+  expected: KillPointExpectation;
+}
+/**
+* The full table: both brackets of all five write points. The expected
+* counts ARE the engine's documented recovery semantics; a count moving
+* here means the durability contract moved and the change must be
+* deliberate.
+*/
+declare const KILL_POINT_SCENARIOS: readonly KillPointScenario[];
+/**
+* The per-scenario contract, serialized as JSON into the
+* `RULVAR_KILL_POINT_CONFIG` environment variable of the spawned worker.
+*/
+interface KillPointWorkerConfig {
+  /** Store location the writer script constructs its store over. */
+  storePath: string;
+  /** The run both processes drive; the referee resumes this id. */
+  runId: string;
+  /** Lease ttl the writer's store MUST be constructed with. */
+  ttlMs: number;
+  /** JSONL report file the worker appends its events to. */
+  reportPath: string;
+  /** Which {@link KILL_POINT_SCENARIOS} entry this worker executes. */
+  scenarioId: string;
+}
+/** One JSONL line of a worker's report file. */
+type KillPointEvent = {
+  t: "call";
+  prompt: string;
+} | {
+  t: "tool";
+  target: string;
+} | {
+  t: "kill";
+  point: KillPointName;
+  phase: KillPointPhase;
+  site: "append" | "putMeta";
+  kind?: string;
+  status?: string;
+  seq?: number;
+} | {
+  t: "ran-to-completion";
+  status: string;
+} | {
+  t: "fatal";
+  message: string;
+};
+/** Reads the worker contract a referee serialized into the child env. */
+declare function killPointWorkerConfigFromEnv(env?: Record<string, string | undefined>): KillPointWorkerConfig;
+/** Parses one report file, tolerating a torn trailing line. */
+declare function parseKillPointReport(path: string): KillPointEvent[];
+/** Consumer hooks for {@link runKillPointWorker}. */
+interface KillPointWorkerHooks {
+  /**
+  * The death itself; default SIGKILLs the current process and never
+  * returns. In-process protocol tests inject a throwing hook instead,
+  * which surfaces through the engine as a store failure.
+  */
+  kill?: () => void;
+}
+/**
+* The worker protocol: run it in a spawned process against the
+* consumer-constructed store pair. Wraps the journal so the configured
+* write kills the process (`before` = ahead of the write, `after` =
+* once it is durable), appends every observation to the report file
+* first (the appends are synchronous, so the report survives the
+* SIGKILL), and reports `ran-to-completion` when the kill point is
+* never reached, which the referee treats as a violation.
+*/
+declare function runKillPointWorker(fixture: FencedTranscriptsFixture, config: KillPointWorkerConfig, hooks?: KillPointWorkerHooks): Promise<void>;
+/** What a green scenario returns (the observed recovery). */
+interface KillPointObservation {
+  scenario: KillPointScenario;
+  childCalls: number;
+  childToolExecutions: number;
+  resumeCalls: number;
+  resumeToolExecutions: number;
+  /** `kind:status` per final journal entry, in seq order. */
+  journal: string[];
+  metaStatus: string | undefined;
+}
+interface KillPointScenarioOptions {
+  /**
+  * Absolute path of the consumer's writer script. It must construct
+  * the store over `killPointWorkerConfigFromEnv()` and call
+  * {@link runKillPointWorker}.
+  */
+  writerScript: string;
+  /** Scratch directory for the report file. */
+  dir: string;
+  /** The scenario to execute, by table entry or id. */
+  scenario: KillPointScenario | string;
+  /** Store location handed to the worker config; default `join(dir, 'kp.db')`. */
+  storePath?: string;
+  /**
+  * The WORKER'S lease ttl; default 300 ms. The referee waits it out
+  * after the kill, so keep it short. It binds only the killed owner:
+  * the referee's own store (the `openStore` fixture) should keep its
+  * GENEROUS default ttl, so a scheduler stall under a loaded test
+  * runner cannot expire the resume's lease mid-scenario (a lost lease
+  * cancels the run by contract, and the fence then swallows its
+  * settle, which reads as a recovery violation when it is really a
+  * harness self-inflicted takeover).
+  */
+  ttlMs?: number;
+  /**
+  * Opens the referee's own fixture over the SAME store location for
+  * the resume and the final state verification.
+  */
+  openStore: () => Promise<FencedTranscriptsFixture> | FencedTranscriptsFixture;
+  /** Closes what {@link KillPointScenarioOptions.openStore} opened. */
+  closeStore?: (fixture: FencedTranscriptsFixture) => void | Promise<void>;
+  /** Extra environment for the worker process. */
+  env?: Record<string, string>;
+  /** Extra `node` arguments placed before the writer script. */
+  execArgv?: string[];
+  /** Ceiling on lease-held resume retries; default 15000 ms. */
+  resumeDeadlineMs?: number;
+}
+/**
+* Spawns the worker, asserts it died AT the configured write by
+* SIGKILL, waits out the dead owner's lease, resumes the run over the
+* referee's own store instance, and asserts the scenario's pinned
+* recovery semantics. Throws one Error naming every violation.
+*/
+declare function runKillPointScenario(options: KillPointScenarioOptions): Promise<KillPointObservation>;
+/** Per-scenario isolation a consumer's `prepare` hands the suite. */
+interface KillPointTarget {
+  /** Store location for this scenario (worker config + referee). */
+  storePath?: string;
+  /** Extra environment for the worker process. */
+  env?: Record<string, string>;
+  openStore: KillPointScenarioOptions["openStore"];
+  closeStore?: KillPointScenarioOptions["closeStore"];
+  /** Runs after the scenario, pass or fail (drop the schema, etc). */
+  cleanup?: () => void | Promise<void>;
+}
+interface KillPointConformanceOptions {
+  /** Absolute path of the consumer's writer script. */
+  writerScript: string;
+  /** Scratch directory for report files. */
+  dir: string;
+  /** Fresh isolation per scenario: store location and referee opener. */
+  prepare: (scenario: KillPointScenario) => Promise<KillPointTarget> | KillPointTarget;
+  /** The worker's lease ttl (see {@link KillPointScenarioOptions.ttlMs}); default 300 ms. */
+  ttlMs?: number;
+  /** Extra `node` arguments placed before the writer script. */
+  execArgv?: string[];
+  /** Ceiling on lease-held resume retries; default 15000 ms. */
+  resumeDeadlineMs?: number;
+}
+/**
+* The whole {@link KILL_POINT_SCENARIOS} table as a conformance suite:
+* one check per scenario, each over the fresh isolation `prepare`
+* returns. Register it with a test API whose `it` allows at least
+* thirty seconds per case (spawn, run, die, lease lapse, resume).
+*/
+declare function killPointConformance(options: KillPointConformanceOptions): ConformanceSuite;
+//#endregion
 //#region src/fixtures/golden-fold.d.ts
 /**
 * seq 0  agent spawn (running; abandoned by seq 6)
@@ -302,4 +491,4 @@ declare function foldStateSha256(entries: readonly JournalEntry[]): string;
 /** The reference hash; computed once from the kernel fold and frozen. */
 declare const GOLDEN_FOLD_STATE_SHA256 = "81e6ccff549fb3e6c1de4d34ba65b912162eba6f66403b5d5f23a3e1ec69243c";
 //#endregion
-export { type ConformanceCheck, type ConformanceSuite, DEFAULT_SOAK_QUORUM, type FencedTranscriptsFixture, GOLDEN_FOLD_JOURNAL, GOLDEN_FOLD_STATE_SHA256, type MultiProcessSoakOptions, type MultiProcessSoakResult, type SoakAcceptSurface, type SoakActivity, type SoakEvent, type SoakProbeSurface, type SoakQuorum, type SoakWriterConfig, type SoakWriterHooks, type StoreFactory, type TestRegistrar, countSoakActivity, fencedTranscriptsConformance, fencedWritesConformance, foldStateSha256, journalStoreConformance, leasableStoreConformance, makeSuite, materializeFoldState, parseSoakReport, registerConformance, runMultiProcessSoak, runSoakWriter, soakWriterConfigFromEnv, stableStringify, verifySoakHistory };
+export { type ConformanceCheck, type ConformanceSuite, DEFAULT_SOAK_QUORUM, type FencedTranscriptsFixture, GOLDEN_FOLD_JOURNAL, GOLDEN_FOLD_STATE_SHA256, KILL_POINT_SCENARIOS, type KillPointConformanceOptions, type KillPointEvent, type KillPointExpectation, type KillPointName, type KillPointObservation, type KillPointPhase, type KillPointScenario, type KillPointScenarioOptions, type KillPointTarget, type KillPointWorkerConfig, type KillPointWorkerHooks, type KillPointWorkflowKind, type MultiProcessSoakOptions, type MultiProcessSoakResult, type SoakAcceptSurface, type SoakActivity, type SoakEvent, type SoakProbeSurface, type SoakQuorum, type SoakWriterConfig, type SoakWriterHooks, type StoreFactory, type TestRegistrar, countSoakActivity, fencedTranscriptsConformance, fencedWritesConformance, foldStateSha256, journalStoreConformance, killPointConformance, killPointWorkerConfigFromEnv, leasableStoreConformance, makeSuite, materializeFoldState, parseKillPointReport, parseSoakReport, registerConformance, runKillPointScenario, runKillPointWorker, runMultiProcessSoak, runSoakWriter, soakWriterConfigFromEnv, stableStringify, verifySoakHistory };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { JournalOrderViolation, LeaseHeldError, Replayer, ResolutionFold, agentScope, buildDeriverRegistry, deriveContentKey, dispositionHook } from "@rulvar/core";
+import { JournalOrderViolation, LeaseHeldError, Replayer, ResolutionFold, agentScope, buildDeriverRegistry, createCanonicalIdMinter, createEngine, defineWorkflow, deriveContentKey, dispositionHook, tool } from "@rulvar/core";
 import { createHash } from "node:crypto";
 import { spawn } from "node:child_process";
 import { appendFileSync, existsSync, readFileSync, writeFileSync } from "node:fs";
@@ -631,7 +631,7 @@ function leaseEntry(seq) {
 		startedAt: (/* @__PURE__ */ new Date(17e11 + seq * 1e3)).toISOString()
 	};
 }
-function sleep$1(ms) {
+function sleep$2(ms) {
 	return new Promise((resolve) => setTimeout(resolve, ms));
 }
 async function mustReject(operation) {
@@ -713,13 +713,13 @@ function leasableStoreConformance(mk, options) {
 			const cadence = Math.floor(ttlMs / 3);
 			const deadline = Date.now() + Math.ceil(ttlMs * 1.5);
 			while (Date.now() < deadline) {
-				await sleep$1(cadence);
+				await sleep$2(cadence);
 				await store.renew(held);
 				ensure(await mustReject(() => store.acquire(RUN$2, "owner-b")) instanceof LeaseHeldError, "lease-ttl-and-renew-cadence", "a lease renewed at ttl/3 must stay held past the original ttl");
 			}
 			await store.release(held);
 			const abandoned = await store.acquire("expiring-run", "owner-a");
-			await sleep$1(Math.ceil(ttlMs * 1.2));
+			await sleep$2(Math.ceil(ttlMs * 1.2));
 			ensure((await store.acquire("expiring-run", "owner-b")).epoch > abandoned.epoch, "lease-ttl-and-renew-cadence", "reclaiming an expired lease must advance the fencing epoch");
 		}
 	});
@@ -1039,7 +1039,7 @@ function soakWriterConfigFromEnv(env = process.env) {
 	if (raw === void 0) throw new Error(`store-conformance multi-process-soak: the writer expects its config in ${SOAK_CONFIG_ENV}`);
 	return JSON.parse(raw);
 }
-const wallClock = Date.now.bind(globalThis);
+const wallClock$1 = Date.now.bind(globalThis);
 /** Deterministic PRNG (mulberry32): the soak never uses Math.random. */
 function prng(seed) {
 	let a = seed >>> 0;
@@ -1051,7 +1051,7 @@ function prng(seed) {
 		return ((t ^ t >>> 14) >>> 0) / 4294967296;
 	};
 }
-const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const sleep$1 = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 function soakEntry(seq, nonce) {
 	return {
 		hashVersion: 2,
@@ -1115,7 +1115,7 @@ async function runSoakWriter(fixture, config, hooks = {}) {
 					w: config.writer,
 					surface
 				});
-				await sleep(1 + Math.floor(rnd() * 3));
+				await sleep$1(1 + Math.floor(rnd() * 3));
 				continue;
 			}
 			log({
@@ -1236,7 +1236,7 @@ async function runSoakWriter(fixture, config, hooks = {}) {
 			lease = await journal.acquire(config.runId, owner);
 		} catch (thrown) {
 			if (thrown instanceof LeaseHeldError || retryable(thrown)) {
-				await sleep(3 + Math.floor(rnd() * 12));
+				await sleep$1(3 + Math.floor(rnd() * 12));
 				return;
 			}
 			log({
@@ -1410,7 +1410,7 @@ async function runSoakWriter(fixture, config, hooks = {}) {
 				w: config.writer,
 				epoch
 			});
-			await sleep(Math.ceil(config.ttlMs * 1.4));
+			await sleep$1(Math.ceil(config.ttlMs * 1.4));
 			await staleSweep(lease);
 			return;
 		}
@@ -1629,28 +1629,28 @@ async function runMultiProcessSoak(options) {
 			stderrOf: () => stderr
 		};
 	});
-	const startedAt = wallClock();
+	const startedAt = wallClock$1();
 	let capped = false;
 	for (;;) {
-		await sleep(100);
+		await sleep$1(100);
 		if (quorumMet(countSoakActivity(reportPaths.flatMap((path) => parseSoakReport(path))), quorum)) break;
-		if (wallClock() - startedAt > capMs) {
+		if (wallClock$1() - startedAt > capMs) {
 			capped = true;
 			break;
 		}
 	}
 	writeFileSync(stopPath, "");
-	const exitDeadline = wallClock() + 3e4;
+	const exitDeadline = wallClock$1() + 3e4;
 	const codes = await Promise.all(children.map(async ({ child, exit }) => {
-		const timeout = Math.max(1, exitDeadline - wallClock());
-		const code = await Promise.race([exit, sleep(timeout).then(() => "hung")]);
+		const timeout = Math.max(1, exitDeadline - wallClock$1());
+		const code = await Promise.race([exit, sleep$1(timeout).then(() => "hung")]);
 		if (code === "hung") {
 			child.kill("SIGKILL");
 			return "hung";
 		}
 		return code;
 	}));
-	const stormMs = wallClock() - startedAt;
+	const stormMs = wallClock$1() - startedAt;
 	const events = reportPaths.flatMap((path) => parseSoakReport(path));
 	const activity = countSoakActivity(events);
 	const violations = [];
@@ -1674,4 +1674,619 @@ async function runMultiProcessSoak(options) {
 	};
 }
 //#endregion
-export { DEFAULT_SOAK_QUORUM, GOLDEN_FOLD_JOURNAL, GOLDEN_FOLD_STATE_SHA256, countSoakActivity, fencedTranscriptsConformance, fencedWritesConformance, foldStateSha256, journalStoreConformance, leasableStoreConformance, makeSuite, materializeFoldState, parseSoakReport, registerConformance, runMultiProcessSoak, runSoakWriter, soakWriterConfigFromEnv, stableStringify, verifySoakHistory };
+//#region src/kill-points.ts
+/**
+* Engine-level kill-point conformance (the 1.65.0 experiment review,
+* P1.10): a real OS child process drives a scripted engine run over the
+* consumer-constructed store and SIGKILLs ITSELF around one durable
+* write, then the referee resumes the run from a fresh process image
+* over its own store instance and asserts the engine's documented
+* recovery semantics against real death, not a simulated throw.
+*
+* The five write points and their brackets (before = the write is lost,
+* after = the write is durable and everything past it is lost):
+* - `running`: the two-phase dispatch entry appended BEFORE the
+*   provider call (the "request" write). Either bracket costs nothing
+*   extra: the step re-runs once on resume.
+* - `ok-terminal`: the terminal entry carrying the response and its
+*   usage. The `before` bracket is THE at-least-once window: the
+*   provider was paid and the acknowledgement died, so resume pays the
+*   step a second time. The `after` bracket replays it for free.
+* - `limit-terminal`: the `maxToolCalls`-expiry terminal. `before`
+*   resumes as a dangling redispatch RESTORED from the last transcript
+*   boundary (one completed tool turn = one checkpoint), so the re-pay
+*   is exactly the turns since that boundary, not the whole agent;
+*   `after` leaves an UNSTAMPED limit terminal in a never-settled run,
+*   which is the documented second chance: resume re-runs the agent
+*   live in full.
+* - `settle`: the run_settle decision. Both brackets resume as a pure
+*   replay (zero provider calls); a lost settle is re-appended by the
+*   resume segment (the settlement third guard arm), a durable one is
+*   never duplicated.
+* - `meta`: the RunMeta projection, ordered strictly AFTER the settle.
+*   `before` is the repairable meta-behind residue and the resume heals
+*   it; `after` is a fully consistent run whose resume changes nothing.
+*
+* Every scenario additionally asserts: death by SIGKILL (a worker that
+* runs to completion means the kill point was never reached, which is a
+* violation, never a pass), exactly ONE ok run_settle in the final
+* journal, meta `ok`, contiguous journal seqs, and the exact workflow
+* value after recovery.
+*
+* Three pieces, split like the multi-process soak so the child side
+* stays a few consumer lines:
+* - {@link runKillPointWorker} is the child protocol: the consumer's
+*   writer script constructs the store over
+*   `killPointWorkerConfigFromEnv()` and hands it over; the protocol
+*   wraps the journal, runs the scripted workflow, and dies at the
+*   configured write.
+* - {@link runKillPointScenario} is the referee: spawns the writer,
+*   waits out the killed owner's lease ttl, resumes over its own store
+*   instance, and throws one Error naming every violation.
+* - {@link killPointConformance} registers the whole
+*   {@link KILL_POINT_SCENARIOS} table as a {@link ConformanceSuite}.
+*/
+const HAPPY_VALUE = {
+	one: "alpha",
+	two: "beta"
+};
+const LIMIT_VALUE = { agentStatus: "limit" };
+/**
+* The full table: both brackets of all five write points. The expected
+* counts ARE the engine's documented recovery semantics; a count moving
+* here means the durability contract moved and the change must be
+* deliberate.
+*/
+const KILL_POINT_SCENARIOS = [
+	{
+		id: "happy-running-before",
+		workflow: "happy",
+		point: "running",
+		phase: "before",
+		occurrence: 2,
+		expected: {
+			childCalls: 1,
+			childToolExecutions: 0,
+			resumeCalls: 1,
+			resumeToolExecutions: 0,
+			limitTerminals: 0,
+			value: HAPPY_VALUE
+		}
+	},
+	{
+		id: "happy-running-after",
+		workflow: "happy",
+		point: "running",
+		phase: "after",
+		occurrence: 2,
+		expected: {
+			childCalls: 1,
+			childToolExecutions: 0,
+			resumeCalls: 1,
+			resumeToolExecutions: 0,
+			limitTerminals: 0,
+			value: HAPPY_VALUE
+		}
+	},
+	{
+		id: "happy-ok-terminal-before",
+		workflow: "happy",
+		point: "ok-terminal",
+		phase: "before",
+		occurrence: 2,
+		expected: {
+			childCalls: 2,
+			childToolExecutions: 0,
+			resumeCalls: 1,
+			resumeToolExecutions: 0,
+			limitTerminals: 0,
+			value: HAPPY_VALUE
+		}
+	},
+	{
+		id: "happy-ok-terminal-after",
+		workflow: "happy",
+		point: "ok-terminal",
+		phase: "after",
+		occurrence: 2,
+		expected: {
+			childCalls: 2,
+			childToolExecutions: 0,
+			resumeCalls: 0,
+			resumeToolExecutions: 0,
+			limitTerminals: 0,
+			value: HAPPY_VALUE
+		}
+	},
+	{
+		id: "happy-settle-before",
+		workflow: "happy",
+		point: "settle",
+		phase: "before",
+		occurrence: 1,
+		expected: {
+			childCalls: 2,
+			childToolExecutions: 0,
+			resumeCalls: 0,
+			resumeToolExecutions: 0,
+			limitTerminals: 0,
+			value: HAPPY_VALUE
+		}
+	},
+	{
+		id: "happy-settle-after",
+		workflow: "happy",
+		point: "settle",
+		phase: "after",
+		occurrence: 1,
+		expected: {
+			childCalls: 2,
+			childToolExecutions: 0,
+			resumeCalls: 0,
+			resumeToolExecutions: 0,
+			limitTerminals: 0,
+			value: HAPPY_VALUE
+		}
+	},
+	{
+		id: "happy-meta-before",
+		workflow: "happy",
+		point: "meta",
+		phase: "before",
+		occurrence: 1,
+		expected: {
+			childCalls: 2,
+			childToolExecutions: 0,
+			resumeCalls: 0,
+			resumeToolExecutions: 0,
+			limitTerminals: 0,
+			value: HAPPY_VALUE
+		}
+	},
+	{
+		id: "happy-meta-after",
+		workflow: "happy",
+		point: "meta",
+		phase: "after",
+		occurrence: 1,
+		expected: {
+			childCalls: 2,
+			childToolExecutions: 0,
+			resumeCalls: 0,
+			resumeToolExecutions: 0,
+			limitTerminals: 0,
+			value: HAPPY_VALUE
+		}
+	},
+	{
+		id: "limit-limit-terminal-before",
+		workflow: "limit",
+		point: "limit-terminal",
+		phase: "before",
+		occurrence: 1,
+		expected: {
+			childCalls: 3,
+			childToolExecutions: 2,
+			resumeCalls: 1,
+			resumeToolExecutions: 0,
+			limitTerminals: 1,
+			value: LIMIT_VALUE
+		}
+	},
+	{
+		id: "limit-limit-terminal-after",
+		workflow: "limit",
+		point: "limit-terminal",
+		phase: "after",
+		occurrence: 1,
+		expected: {
+			childCalls: 3,
+			childToolExecutions: 2,
+			resumeCalls: 3,
+			resumeToolExecutions: 2,
+			limitTerminals: 2,
+			value: LIMIT_VALUE
+		}
+	}
+];
+const KILL_POINT_CONFIG_ENV = "RULVAR_KILL_POINT_CONFIG";
+/** Reads the worker contract a referee serialized into the child env. */
+function killPointWorkerConfigFromEnv(env = process.env) {
+	const raw = env[KILL_POINT_CONFIG_ENV];
+	if (raw === void 0) throw new Error(`store-conformance kill-points: the worker expects its config in ${KILL_POINT_CONFIG_ENV}`);
+	return JSON.parse(raw);
+}
+/** Parses one report file, tolerating a torn trailing line. */
+function parseKillPointReport(path) {
+	if (!existsSync(path)) return [];
+	const events = [];
+	for (const line of readFileSync(path, "utf8").split("\n")) {
+		if (line.trim() === "") continue;
+		try {
+			events.push(JSON.parse(line));
+		} catch {}
+	}
+	return events;
+}
+const KILL_POINT_CAPS = {
+	structuredOutput: "native",
+	supportsTemperature: false,
+	supportsParallelTools: true,
+	reasoningEfforts: [
+		"low",
+		"medium",
+		"high"
+	],
+	contextWindow: 2e5,
+	maxOutputTokens: 4096
+};
+function lastUserText(req) {
+	for (let i = req.messages.length - 1; i >= 0; i -= 1) {
+		const msg = req.messages[i];
+		if (msg?.role !== "user") continue;
+		return msg.parts.filter((part) => part.type === "text").map((part) => part.text).join("\n");
+	}
+	return "";
+}
+/**
+* The scripted model: `step one`/`step two` answer with fixed texts;
+* every other prompt is the limit script, whose model NEVER stops
+* asking for the probe tool, so the executed-call cap is what ends it.
+*/
+function makeKillPointAdapter(onCall) {
+	const mintId = createCanonicalIdMinter();
+	let limitTurn = 0;
+	return {
+		id: "kp",
+		caps: () => KILL_POINT_CAPS,
+		async *stream(req) {
+			const prompt = lastUserText(req);
+			onCall(prompt);
+			const usage = {
+				inputTokens: Math.max(1, Math.ceil(prompt.length / 4)),
+				outputTokens: 4,
+				cacheReadTokens: 0,
+				cacheWriteTokens: 0
+			};
+			if (prompt.includes("step one")) {
+				yield {
+					type: "text-delta",
+					text: "alpha"
+				};
+				yield {
+					type: "finish",
+					finish: { reason: "stop" },
+					usage
+				};
+				return;
+			}
+			if (prompt.includes("step two")) {
+				yield {
+					type: "text-delta",
+					text: "beta"
+				};
+				yield {
+					type: "finish",
+					finish: { reason: "stop" },
+					usage
+				};
+				return;
+			}
+			limitTurn += 1;
+			const id = mintId();
+			yield {
+				type: "tool-call-start",
+				id,
+				name: "probe"
+			};
+			yield {
+				type: "tool-call-end",
+				id,
+				args: { target: `t${String(limitTurn)}` }
+			};
+			yield {
+				type: "finish",
+				finish: { reason: "tool-calls" },
+				usage
+			};
+		}
+	};
+}
+/** Both processes run the SAME workflow; resume replays through it. */
+function makeKillPointWorkflow(kind, onTool) {
+	if (kind === "limit") {
+		const probe = tool({
+			name: "probe",
+			description: "reads one evidence source",
+			parameters: {
+				type: "object",
+				properties: { target: { type: "string" } },
+				required: ["target"],
+				additionalProperties: false
+			},
+			execute: (input) => {
+				const target = input.target;
+				onTool(target);
+				return Promise.resolve(`evidence ${target}`);
+			}
+		});
+		return defineWorkflow({ name: "kp-limit" }, async (ctx) => {
+			return { agentStatus: (await ctx.agent("probe until the cap", {
+				tools: [probe],
+				limits: {
+					maxTurns: 4,
+					maxToolCalls: 2
+				},
+				result: "full"
+			})).status };
+		});
+	}
+	return defineWorkflow({ name: "kp-happy" }, async (ctx) => {
+		return {
+			one: await ctx.agent("step one"),
+			two: await ctx.agent("step two")
+		};
+	});
+}
+function isRunSettle(entry) {
+	return entry.kind === "decision" && entry.value?.decisionType === "run_settle";
+}
+/**
+* The worker protocol: run it in a spawned process against the
+* consumer-constructed store pair. Wraps the journal so the configured
+* write kills the process (`before` = ahead of the write, `after` =
+* once it is durable), appends every observation to the report file
+* first (the appends are synchronous, so the report survives the
+* SIGKILL), and reports `ran-to-completion` when the kill point is
+* never reached, which the referee treats as a violation.
+*/
+async function runKillPointWorker(fixture, config, hooks = {}) {
+	const scenario = KILL_POINT_SCENARIOS.find((s) => s.id === config.scenarioId);
+	if (scenario === void 0) throw new Error(`store-conformance kill-points: unknown scenario '${config.scenarioId}'`);
+	const log = (event) => {
+		appendFileSync(config.reportPath, `${JSON.stringify(event)}\n`);
+	};
+	const die = hooks.kill ?? (() => {
+		process.kill(process.pid, "SIGKILL");
+	});
+	const counters = { hits: 0 };
+	const matches = (entry) => {
+		if (scenario.point === "running") return entry.kind === "agent" && entry.status === "running";
+		if (scenario.point === "ok-terminal") return entry.kind === "agent" && entry.ref !== void 0 && entry.status === "ok";
+		if (scenario.point === "limit-terminal") return entry.kind === "agent" && entry.ref !== void 0 && entry.status === "limit";
+		if (scenario.point === "settle") return isRunSettle(entry);
+		return false;
+	};
+	const kill = (site, extra) => {
+		log({
+			t: "kill",
+			point: scenario.point,
+			phase: scenario.phase,
+			site,
+			...extra
+		});
+		die();
+	};
+	const journal = new Proxy(fixture.journal, { get(target, prop, receiver) {
+		if (prop === "append") return async (runId, entry, lease) => {
+			let hit = false;
+			if (matches(entry)) {
+				counters.hits += 1;
+				hit = counters.hits === scenario.occurrence;
+			}
+			const detail = {
+				kind: entry.kind,
+				status: entry.status,
+				seq: entry.seq
+			};
+			if (hit && scenario.phase === "before") kill("append", detail);
+			const out = await target.append(runId, entry, lease);
+			if (hit && scenario.phase === "after") kill("append", detail);
+			return out;
+		};
+		if (prop === "putMeta") return async (meta, lease) => {
+			const hit = scenario.point === "meta" && meta.status !== "running";
+			if (hit && scenario.phase === "before") kill("putMeta", { status: meta.status });
+			const out = await target.putMeta(meta, lease);
+			if (hit && scenario.phase === "after") kill("putMeta", { status: meta.status });
+			return out;
+		};
+		const value = Reflect.get(target, prop, receiver);
+		return typeof value === "function" ? value.bind(target) : value;
+	} });
+	const adapter = makeKillPointAdapter((prompt) => {
+		log({
+			t: "call",
+			prompt
+		});
+	});
+	const workflow = makeKillPointWorkflow(scenario.workflow, (target) => {
+		log({
+			t: "tool",
+			target
+		});
+	});
+	const engine = createEngine({
+		adapters: [adapter],
+		stores: {
+			journal,
+			transcripts: fixture.transcripts
+		},
+		defaults: { routing: { loop: "kp:kp-model" } }
+	});
+	try {
+		log({
+			t: "ran-to-completion",
+			status: (await engine.run(workflow, void 0, { runId: config.runId }).result).status
+		});
+	} catch (thrown) {
+		log({
+			t: "fatal",
+			message: String(thrown)
+		});
+		throw thrown;
+	}
+}
+const wallClock = Date.now.bind(globalThis);
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+* Spawns the worker, asserts it died AT the configured write by
+* SIGKILL, waits out the dead owner's lease, resumes the run over the
+* referee's own store instance, and asserts the scenario's pinned
+* recovery semantics. Throws one Error naming every violation.
+*/
+async function runKillPointScenario(options) {
+	const scenario = typeof options.scenario === "string" ? KILL_POINT_SCENARIOS.find((s) => s.id === options.scenario) : options.scenario;
+	if (scenario === void 0) {
+		const named = typeof options.scenario === "string" ? options.scenario : options.scenario.id;
+		throw new Error(`store-conformance kill-points: unknown scenario '${named}'`);
+	}
+	const ttlMs = options.ttlMs ?? 300;
+	const storePath = options.storePath ?? join(options.dir, "kp.db");
+	const reportPath = join(options.dir, `kill-report-${scenario.id}.jsonl`);
+	const runId = `kp-${scenario.id}`;
+	const config = {
+		storePath,
+		runId,
+		ttlMs,
+		reportPath,
+		scenarioId: scenario.id
+	};
+	const child = spawn(process.execPath, [...options.execArgv ?? [], options.writerScript], {
+		env: {
+			...process.env,
+			...options.env,
+			[KILL_POINT_CONFIG_ENV]: JSON.stringify(config)
+		},
+		stdio: [
+			"ignore",
+			"ignore",
+			"pipe"
+		]
+	});
+	let stderr = "";
+	child.stderr.on("data", (chunk) => {
+		stderr += String(chunk);
+	});
+	const exitPromise = new Promise((resolve) => {
+		child.on("exit", (code, signal) => resolve({
+			code,
+			signal
+		}));
+	});
+	const exit = await Promise.race([exitPromise, sleep(3e4).then(() => "hung")]);
+	if (exit === "hung") {
+		child.kill("SIGKILL");
+		throw new Error(`store-conformance kill-points ${scenario.id}: the worker did not exit within 30 s`);
+	}
+	const violations = [];
+	const events = parseKillPointReport(reportPath);
+	const childCalls = events.filter((e) => e.t === "call").length;
+	const childTools = events.filter((e) => e.t === "tool").length;
+	const kills = events.filter((e) => e.t === "kill");
+	const completed = events.find((e) => e.t === "ran-to-completion");
+	const fatal = events.find((e) => e.t === "fatal");
+	if (exit.signal !== "SIGKILL") violations.push(`the worker must die by SIGKILL at the configured write; exit code ${String(exit.code)}, signal ${String(exit.signal)}` + (completed === void 0 ? "" : " (it ran to completion: the kill point was never reached)") + (fatal === void 0 ? "" : ` (fatal: ${fatal.message})`) + (stderr === "" ? "" : `; stderr: ${stderr.slice(0, 2e3)}`));
+	if (kills.length !== 1) violations.push(`expected exactly one kill event, saw ${String(kills.length)}`);
+	else {
+		const kill = kills[0];
+		if (kill.point !== scenario.point || kill.phase !== scenario.phase) violations.push(`the kill event names ${kill.point}/${kill.phase}, the scenario is ${scenario.point}/${scenario.phase}`);
+	}
+	if (childCalls !== scenario.expected.childCalls) violations.push(`the child paid ${String(childCalls)} provider calls before dying, expected ` + String(scenario.expected.childCalls));
+	if (childTools !== scenario.expected.childToolExecutions) violations.push(`the child executed ${String(childTools)} tools before dying, expected ` + String(scenario.expected.childToolExecutions));
+	await sleep(ttlMs * 2);
+	let resumeCalls = 0;
+	let resumeTools = 0;
+	const fixture = await options.openStore();
+	try {
+		const adapter = makeKillPointAdapter(() => {
+			resumeCalls += 1;
+		});
+		const workflow = makeKillPointWorkflow(scenario.workflow, () => {
+			resumeTools += 1;
+		});
+		const engine = createEngine({
+			adapters: [adapter],
+			stores: {
+				journal: fixture.journal,
+				transcripts: fixture.transcripts
+			},
+			defaults: { routing: { loop: "kp:kp-model" } }
+		});
+		const deadline = wallClock() + (options.resumeDeadlineMs ?? 15e3);
+		let resumed;
+		for (;;) try {
+			resumed = await engine.resume(runId, workflow).result;
+			break;
+		} catch (thrown) {
+			if (thrown instanceof LeaseHeldError && wallClock() < deadline) {
+				await sleep(Math.max(50, Math.ceil(ttlMs / 3)));
+				continue;
+			}
+			violations.push(`the resume rejected: ${String(thrown)}`);
+			break;
+		}
+		if (resumed !== void 0) {
+			if (resumed.status !== "ok") violations.push(`the resume settled '${resumed.status}', expected 'ok'`);
+			if (stableStringify(resumed.value) !== stableStringify(scenario.expected.value)) violations.push(`the recovered value is ${stableStringify(resumed.value)}, expected ` + stableStringify(scenario.expected.value));
+			if (resumeCalls !== scenario.expected.resumeCalls) violations.push(`the resume paid ${String(resumeCalls)} provider calls, the bracket documents ` + String(scenario.expected.resumeCalls));
+			if (resumeTools !== scenario.expected.resumeToolExecutions) violations.push(`the resume executed ${String(resumeTools)} tools, the bracket documents ` + String(scenario.expected.resumeToolExecutions));
+		}
+		const entries = await fixture.journal.load(runId);
+		const firstSeq = entries[0]?.seq ?? 0;
+		if (!entries.every((entry, i) => entry.seq === firstSeq + i)) violations.push(`journal seqs are not contiguous: ${entries.map((e) => String(e.seq)).join(", ")}`);
+		const settles = entries.filter((entry) => isRunSettle(entry));
+		if (settles.length !== 1) violations.push(`expected exactly one run_settle, the journal holds ${String(settles.length)}`);
+		const lastSettle = settles.at(-1)?.value;
+		if (lastSettle?.runStatus !== "ok") violations.push(`the run settle records '${String(lastSettle?.runStatus)}', expected 'ok'`);
+		const limitTerminals = entries.filter((entry) => entry.kind === "agent" && entry.ref !== void 0 && entry.status === "limit").length;
+		if (limitTerminals !== scenario.expected.limitTerminals) violations.push(`the journal holds ${String(limitTerminals)} limit terminals, expected ` + String(scenario.expected.limitTerminals));
+		const meta = await fixture.journal.getMeta?.(runId);
+		if (meta?.status !== "ok") violations.push(`meta records '${String(meta?.status)}', expected 'ok' after recovery`);
+		if (violations.length > 0) throw new Error(`store-conformance kill-points ${scenario.id}: ${String(violations.length)} violation(s)\n - ` + violations.join("\n - "));
+		return {
+			scenario,
+			childCalls,
+			childToolExecutions: childTools,
+			resumeCalls,
+			resumeToolExecutions: resumeTools,
+			journal: entries.map((entry) => `${entry.kind}:${entry.status}`),
+			metaStatus: meta?.status
+		};
+	} finally {
+		await options.closeStore?.(fixture);
+	}
+}
+/**
+* The whole {@link KILL_POINT_SCENARIOS} table as a conformance suite:
+* one check per scenario, each over the fresh isolation `prepare`
+* returns. Register it with a test API whose `it` allows at least
+* thirty seconds per case (spawn, run, die, lease lapse, resume).
+*/
+function killPointConformance(options) {
+	return makeSuite("kill-point conformance (engine recovery under real process death)", KILL_POINT_SCENARIOS.map((scenario) => ({
+		id: `kp-${scenario.id}`,
+		title: `a SIGKILL ${scenario.phase} the ${scenario.point} write recovers on resume (${String(scenario.expected.resumeCalls)} re-paid call(s))`,
+		run: async () => {
+			const target = await options.prepare(scenario);
+			try {
+				await runKillPointScenario({
+					writerScript: options.writerScript,
+					dir: options.dir,
+					scenario,
+					openStore: target.openStore,
+					...target.storePath === void 0 ? {} : { storePath: target.storePath },
+					...target.env === void 0 ? {} : { env: target.env },
+					...target.closeStore === void 0 ? {} : { closeStore: target.closeStore },
+					...options.ttlMs === void 0 ? {} : { ttlMs: options.ttlMs },
+					...options.execArgv === void 0 ? {} : { execArgv: options.execArgv },
+					...options.resumeDeadlineMs === void 0 ? {} : { resumeDeadlineMs: options.resumeDeadlineMs }
+				});
+			} finally {
+				await target.cleanup?.();
+			}
+		}
+	})));
+}
+//#endregion
+export { DEFAULT_SOAK_QUORUM, GOLDEN_FOLD_JOURNAL, GOLDEN_FOLD_STATE_SHA256, KILL_POINT_SCENARIOS, countSoakActivity, fencedTranscriptsConformance, fencedWritesConformance, foldStateSha256, journalStoreConformance, killPointConformance, killPointWorkerConfigFromEnv, leasableStoreConformance, makeSuite, materializeFoldState, parseKillPointReport, parseSoakReport, registerConformance, runKillPointScenario, runKillPointWorker, runMultiProcessSoak, runSoakWriter, soakWriterConfigFromEnv, stableStringify, verifySoakHistory };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/store-conformance",
-  "version": "1.68.0",
+  "version": "1.70.0",
   "description": "Rulvar executable store conformance kit (DEF-4).",
   "type": "module",
   "license": "Apache-2.0",
@@ -22,7 +22,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@rulvar/core": "1.68.0"
+    "@rulvar/core": "1.70.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.0",