@rulvar/core 1.10.0 → 1.12.0

package/dist/index.d.ts

@@ -5104,6 +5104,7 @@ declare class ExternalRegistry {
   private readonly waiters;
   private readonly keysByScope;
   private activity;
+  private closedFlag;
   private quiesceListener?;
   private quiesceScheduled;
   private readonly emitEvent?;
@@ -5126,6 +5127,22 @@ declare class ExternalRegistry {
   pending(): PendingExternal[];
   /** The synthesized resolveExternal key of an approval suspension. */
   static approvalKey(entryRef: number): string;
+  /**
+  * The resolveExternal key a journaled suspension answers to: externals
+  * carry the workflow-chosen key in the payload; approvals and Flavor B
+  * decisions synthesize `approval:<seq>`. Undefined for anything that
+  * is not a suspended entry.
+  */
+  static suspensionKeyOf(entry: JournalEntry): string | undefined;
+  /**
+  * Settling the run closes this execution segment permanently: every
+  * parked waiter is detached, so a resolution arriving after
+  * handle.result settled appends durably through the fold and wakes
+  * NOTHING; exactly one subsequent engine.resume owns the continuation.
+  * Idempotent. (Suspension ownership rule; v1.10 deep E2E review.)
+  */
+  close(): void;
+  get closed(): boolean;
   private scheduleQuiesceCheck;
   /**
   * ctx.awaitExternal: journal (or re-match) the suspended entry and park
@@ -5181,9 +5198,25 @@ declare class ExternalRegistry {
   /**
   * RunHandle.resolveExternal: the live path validates BEFORE append and
   * throws InvalidResolutionError without journaling; a winning attempt
-  * settles the waiting promise in place.
+  * settles the waiting promise in place. Without an open waiter the
+  * attempt goes through the journal fold instead: a repeated resolution
+  * is the documented journaled no-op ('already_resolved'), and once the
+  * segment settled the resolution appends durably WITHOUT waking the
+  * closed body (exactly one engine.resume owns the continuation).
   */
   resolveExternal(key: string, value: Json): Promise<ResolutionOutcome>;
+  /** The shared live-path payload validation (throws, journals nothing). */
+  private validatePayload;
+  /**
+  * Resolution without a live waiter, over the journal fold. Three cases:
+  * a key no suspension ever carried throws InvalidResolutionError; a key
+  * whose suspensions are all closed submits through the arbiter and
+  * returns the journaled no-op ('already_resolved' or
+  * 'target_abandoned', durability.md contract); an OPEN suspension is
+  * resolvable this way only once the segment settled (closed registry),
+  * with the exact live-path validation and no wake.
+  */
+  private resolveDetached;
 }
 //#endregion
 //#region src/engine/ctx.d.ts
@@ -5963,6 +5996,12 @@ declare class InMemoryTranscriptStore implements TranscriptStore {
 //#region src/stores/jsonl.d.ts
 declare class JsonlFileStore implements JournalStore {
   private readonly dir;
+  /**
+  * The stored tail seq per run, lazily initialized from the file on the
+  * first append this instance performs (obligation A5). Per instance by
+  * design: cross-process writers are the lease seam's job.
+  */
+  private readonly lastSeq;
   constructor(options: {
     dir: string;
   });

package/dist/index.js

@@ -5626,6 +5626,7 @@ var ExternalRegistry = class ExternalRegistry {
 	waiters = /* @__PURE__ */ new Map();
 	keysByScope = /* @__PURE__ */ new Set();
 	activity = 0;
+	closedFlag = false;
 	quiesceListener;
 	quiesceScheduled = false;
 	emitEvent;
@@ -5697,6 +5698,34 @@ var ExternalRegistry = class ExternalRegistry {
 	static approvalKey(entryRef) {
 		return `approval:${entryRef}`;
 	}
+	/**
+	* The resolveExternal key a journaled suspension answers to: externals
+	* carry the workflow-chosen key in the payload; approvals and Flavor B
+	* decisions synthesize `approval:<seq>`. Undefined for anything that
+	* is not a suspended entry.
+	*/
+	static suspensionKeyOf(entry) {
+		if (entry.status !== "suspended") return;
+		if (entry.kind === "external") {
+			const key = entry.value?.key;
+			return typeof key === "string" ? key : void 0;
+		}
+		if (entry.kind === "approval") return ExternalRegistry.approvalKey(entry.seq);
+	}
+	/**
+	* Settling the run closes this execution segment permanently: every
+	* parked waiter is detached, so a resolution arriving after
+	* handle.result settled appends durably through the fold and wakes
+	* NOTHING; exactly one subsequent engine.resume owns the continuation.
+	* Idempotent. (Suspension ownership rule; v1.10 deep E2E review.)
+	*/
+	close() {
+		this.closedFlag = true;
+		this.waiters.clear();
+	}
+	get closed() {
+		return this.closedFlag;
+	}
 	scheduleQuiesceCheck() {
 		if (this.quiesceScheduled) return;
 		this.quiesceScheduled = true;
@@ -5885,7 +5914,7 @@ var ExternalRegistry = class ExternalRegistry {
 			const waiter = this.waiters.get(entryRef);
 			if (waiter !== void 0) {
 				this.waiters.delete(entryRef);
-				waiter.resolve(attempt.value);
+				if (!this.closedFlag) waiter.resolve(attempt.value);
 			}
 		}
 		return outcome;
@@ -5893,37 +5922,76 @@ var ExternalRegistry = class ExternalRegistry {
 	/**
 	* RunHandle.resolveExternal: the live path validates BEFORE append and
 	* throws InvalidResolutionError without journaling; a winning attempt
-	* settles the waiting promise in place.
+	* settles the waiting promise in place. Without an open waiter the
+	* attempt goes through the journal fold instead: a repeated resolution
+	* is the documented journaled no-op ('already_resolved'), and once the
+	* segment settled the resolution appends durably WITHOUT waking the
+	* closed body (exactly one engine.resume owns the continuation).
 	*/
 	async resolveExternal(key, value) {
 		const waiter = [...this.waiters.values()].find((candidate) => candidate.key === key);
-		if (waiter === void 0) throw new InvalidResolutionError(`no open awaitExternal suspension with key '${key}' in this run`);
-		if (waiter.kind === "approval") {
+		if (waiter === void 0) return this.resolveDetached(key, value);
+		await this.validatePayload(waiter.kind, key, value, waiter.schemaSpec);
+		const outcome = await this.replayer.resolveSuspended(waiter.entryRef, {
+			by: "external",
+			value
+		});
+		this.emitResolutionOutcome(waiter.entryRef, "external", outcome);
+		if (outcome.applied) {
+			this.waiters.delete(waiter.entryRef);
+			if (!this.closedFlag) waiter.resolve(value);
+		}
+		return outcome;
+	}
+	/** The shared live-path payload validation (throws, journals nothing). */
+	async validatePayload(kind, key, value, schemaSpec) {
+		if (kind === "approval") {
 			const decision = value?.decision;
 			if (decision !== "allow" && decision !== "deny") throw new InvalidResolutionError(`approval '${key}' resolves with { decision: 'allow' | 'deny', reason? }`);
 		}
-		if (waiter.kind === "decision") {
-			const kind = value?.kind;
-			if (kind !== "retry" && kind !== "decompose" && kind !== "cancel" && kind !== "accept") throw new InvalidResolutionError(`escalation '${key}' resolves with an EscalationDecision ({ kind: 'retry' | 'decompose' | 'cancel' | 'accept', ... })`);
+		if (kind === "decision") {
+			const decisionKind = value?.kind;
+			if (decisionKind !== "retry" && decisionKind !== "decompose" && decisionKind !== "cancel" && decisionKind !== "accept") throw new InvalidResolutionError(`escalation '${key}' resolves with an EscalationDecision ({ kind: 'retry' | 'decompose' | 'cancel' | 'accept', ... })`);
 		}
-		if (waiter.schemaSpec !== void 0) {
-			const validation = await validateSchemaSpec(waiter.schemaSpec, value);
+		if (schemaSpec !== void 0) {
+			const validation = await validateSchemaSpec(schemaSpec, value);
 			if (!validation.valid) throw new InvalidResolutionError(`resolution for '${key}' does not validate against the pinned schema: ` + validation.issues.map((issue) => issue.message).join("; "), { data: { issues: validation.issues.map((issue) => issue.message) } });
 		}
-		const outcome = await this.replayer.resolveSuspended(waiter.entryRef, {
+	}
+	/**
+	* Resolution without a live waiter, over the journal fold. Three cases:
+	* a key no suspension ever carried throws InvalidResolutionError; a key
+	* whose suspensions are all closed submits through the arbiter and
+	* returns the journaled no-op ('already_resolved' or
+	* 'target_abandoned', durability.md contract); an OPEN suspension is
+	* resolvable this way only once the segment settled (closed registry),
+	* with the exact live-path validation and no wake.
+	*/
+	async resolveDetached(key, value) {
+		const candidates = this.replayer.snapshot().filter((entry) => ExternalRegistry.suspensionKeyOf(entry) === key);
+		const open = candidates.find((entry) => this.replayer.suspensionState(entry.seq).state === "suspended");
+		if (open === void 0 && candidates.length === 0) throw new InvalidResolutionError(`no open awaitExternal suspension with key '${key}' in this run`);
+		if (open !== void 0 && !this.closedFlag) throw new InvalidResolutionError(`no open awaitExternal suspension with key '${key}' in this run`);
+		const target = open ?? candidates[candidates.length - 1];
+		await this.validatePayload(target.kind === "approval" ? target.deadlineAt === void 0 ? "approval" : "decision" : "external", key, value, target.value?.schema);
+		const outcome = await this.replayer.resolveSuspended(target.seq, {
 			by: "external",
 			value
 		});
-		this.emitResolutionOutcome(waiter.entryRef, "external", outcome);
-		if (outcome.applied) {
-			this.waiters.delete(waiter.entryRef);
-			waiter.resolve(value);
-		}
+		this.emitResolutionOutcome(target.seq, "external", outcome);
 		return outcome;
 	}
 };
 //#endregion
 //#region src/stores/inmemory.ts
+/**
+* InMemoryStore (M1-T04): the default journal store. Process-local, so
+* nothing survives a process exit and cross-process resume is
+* impossible (same-process resume of a kept instance works); the store
+* warns loudly exactly once per instance unless constructed with
+* `quiet: true` (the deliberate choice of a test tier).
+* An in-memory TranscriptStore ships alongside for the same default.
+*/
 function deepCopy(value) {
 	return JSON.parse(JSON.stringify(value));
 }
@@ -5937,6 +6005,8 @@ var InMemoryStore = class {
 	append(runId, e) {
 		this.warnOnce();
 		const entries = this.runs.get(runId) ?? [];
+		const tail = entries[entries.length - 1];
+		if (tail !== void 0 && Number.isFinite(e.seq) && Number.isFinite(tail.seq) && e.seq <= tail.seq) return Promise.reject(new JournalOrderViolation(`InMemoryStore: append of seq ${e.seq} to run '${runId}' is not after the stored tail seq ${tail.seq}; a concurrent writer raced this journal from a stale tail`));
 		entries.push(deepCopy(e));
 		this.runs.set(runId, entries);
 		return Promise.resolve();
@@ -6023,6 +6093,12 @@ function safeName(runId) {
 }
 var JsonlFileStore = class {
 	dir;
+	/**
+	* The stored tail seq per run, lazily initialized from the file on the
+	* first append this instance performs (obligation A5). Per instance by
+	* design: cross-process writers are the lease seam's job.
+	*/
+	lastSeq = /* @__PURE__ */ new Map();
 	constructor(options) {
 		this.dir = options.dir;
 		mkdirSync(this.dir, { recursive: true });
@@ -6034,7 +6110,16 @@ var JsonlFileStore = class {
 		return join(this.dir, `${safeName(runId)}${META_SUFFIX}`);
 	}
 	async append(runId, e) {
+		let tail = this.lastSeq.get(runId);
+		if (tail === void 0) {
+			const existing = await this.load(runId);
+			const last = existing[existing.length - 1];
+			tail = last !== void 0 && Number.isFinite(last.seq) ? last.seq : Number.NEGATIVE_INFINITY;
+			this.lastSeq.set(runId, tail);
+		}
+		if (Number.isFinite(e.seq) && e.seq <= tail) throw new JournalOrderViolation(`JsonlFileStore: append of seq ${e.seq} to run '${runId}' is not after the stored tail seq ${tail}; a concurrent writer raced this journal from a stale tail`);
 		appendFileSync(this.journalPath(runId), `${JSON.stringify(e)}\n`, "utf8");
+		if (Number.isFinite(e.seq)) this.lastSeq.set(runId, e.seq);
 	}
 	async load(runId) {
 		let raw;
@@ -6091,6 +6176,7 @@ var JsonlFileStore = class {
 	async delete(runId) {
 		rmSync(this.journalPath(runId), { force: true });
 		rmSync(this.metaPath(runId), { force: true });
+		this.lastSeq.delete(runId);
 	}
 };
 const TRANSCRIPT_SUFFIX = ".bin";
@@ -12557,6 +12643,7 @@ function createEngine(options) {
 		return priceUsdOf(pricing, usage);
 	};
 	const providerLimiter = new KeyedLimiter(options.concurrency?.perProvider);
+	const activeSegments = /* @__PURE__ */ new Set();
 	function run(wf, args, opts, resumeCtx) {
 		if (wf.kind !== "workflow" && wf.kind !== "compiled-workflow") throw new ConfigError("engine.run accepts in-process Workflow values or compileScript CompiledWorkflow values");
 		const compiled = wf.kind === "compiled-workflow" ? wf : void 0;
@@ -12701,6 +12788,8 @@ function createEngine(options) {
 			workflowHash: compiled === void 0 ? hashWorkflowBody(wf) : hashWorkflowSource(compiled.source),
 			...compiled === void 0 ? {} : { workflowSourceRef: workflowSourceRef(runId) }
 		});
+		if (activeSegments.has(runId)) throw new ConfigError(`run '${runId}' already has a live execution segment in this engine; await its settled result before starting another one (exactly one segment owns a run; https://docs.rulvar.com/guide/durability#resolving-a-settled-run)`);
+		activeSegments.add(runId);
 		const result = (async () => {
 			let status = "ok";
 			let value;
@@ -12741,8 +12830,9 @@ function createEngine(options) {
 				}))]);
 				if (raced.kind === "suspended") {
 					bodyPromise.catch(() => void 0);
+					external.close();
 					status = "suspended";
-					pending = raced.open;
+					pending = raced.open.filter((item) => replayer.suspensionState(item.entryRef).state === "suspended");
 					for (const item of pending) bus.emit({
 						type: "external:waiting",
 						key: item.key,
@@ -12764,7 +12854,7 @@ function createEngine(options) {
 				value = void 0;
 				if (thrown instanceof BudgetExhaustedError || budget.exhausted) {
 					status = "exhausted";
-					wireError = thrown instanceof RulvarError ? thrown.toWire() : void 0;
+					wireError = thrown instanceof AgentCallError ? agentResultWire(thrown.result, thrown.message) : thrown instanceof RulvarError ? thrown.toWire() : void 0;
 				} else if (controller.signal.aborted) {
 					status = "cancelled";
 					wireError = {
@@ -12782,6 +12872,7 @@ function createEngine(options) {
 				}
 			} finally {
 				if (deadlineTimer !== void 0) clearTimeout(deadlineTimer);
+				external.close();
 				await replayer.flush().catch(() => void 0);
 			}
 			const ledger = replayer.ledger();
@@ -12807,7 +12898,9 @@ function createEngine(options) {
 			});
 			return outcome;
 		})();
-		result.catch(() => void 0);
+		result.catch(() => void 0).finally(() => {
+			activeSegments.delete(runId);
+		});
 		return {
 			runId,
 			result,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/core",
-  "version": "1.10.0",
+  "version": "1.12.0",
   "description": "Rulvar core: L0 contracts, journal kernel, ctx primitives, agent runtime, model router, tool system, dynamic orchestrator, InMemory and JSONL stores, event stream.",
   "type": "module",
   "license": "Apache-2.0",