@rulvar/core 1.59.2 → 1.59.4

package/dist/index.d.ts

@@ -2652,6 +2652,7 @@ declare class Replayer {
   private readonly runId;
   private readonly store;
   private readonly lease?;
+  private readonly leaseOf?;
   private readonly now;
   private readonly priceUsd?;
   private readonly onWarn?;
@@ -2683,6 +2684,14 @@ declare class Replayer {
     * is asserted instead of fenced (the embedded default).
     */
     lease?: Lease;
+    /**
+    * Late-bound lease lookup (P0.2): consulted at EVERY append,
+    * winning over the static `lease` when it returns one. The engine
+    * passes its segment-lease holder here, because the
+    * engine-acquired genesis lease exists only after the ownership
+    * boot, which runs after this constructor.
+    */
+    leaseOf?: () => Lease | undefined;
   });
   /**
   * Forward-matches one live call against the prior journal. Fresh
@@ -4094,8 +4103,14 @@ interface ToolRuntime {
   * toolset holds any non-inprocess tool; the ctx layer mints the tool
   * span and idempotency key and wires the provider. A throw becomes the
   * call's error tool result exactly like an inprocess execute throw.
+  *
+  * `ordinal` is the call's 1-based position in this agent invocation's
+  * tool loop (checkpoint-stable across suspension and crash resume); the
+  * ctx layer folds it with the agent entry's seq into the idempotency
+  * key, so two separate calls with identical arguments do not collide
+  * while an at-least-once retry of one call keeps its key (P0.4).
   */
-  executeExternal?: (def: ToolDef, args: Json) => Promise<unknown>;
+  executeExternal?: (def: ToolDef, args: Json, ordinal: number) => Promise<unknown>;
 }
 /** One serving target of a phase: the primary or a failover fallback. */
 interface PhaseTarget {
@@ -5676,6 +5691,25 @@ interface CreateEngineOptions {
   security?: {
     argsHashSalt?: string;
   };
+  /**
+  * The genesis ownership protocol (P0.2): over a journal store with
+  * the lease capability, a run or resume segment that was NOT handed
+  * a lease acquires its own before its first durable mutation, renews
+  * it at ttl/3 exactly like a queue worker, and releases it at
+  * settle. Fresh start, in-process resume, and worker takeover then
+  * share ONE owner/lease contract: at most one live driver per run
+  * across processes, a second driver's acquire rejects with the typed
+  * LeaseHeldError before any write or provider dispatch, and a
+  * crashed owner's lease expires after the store ttl so a worker
+  * sweep recovers the run. Default 'auto'. 'none' restores the
+  * pre-1.59.4 behavior (no engine-acquired leases) for hosts that
+  * coordinate ownership entirely outside the engine; a lease passed
+  * via RunOptions.lease or ResumeOptions.lease always wins over both
+  * modes (the caller owns acquire, renew, and release). Stores
+  * without the lease capability are unaffected: the embedded
+  * single-process default keeps the single-writer precondition.
+  */
+  ownership?: "auto" | "none";
 }
 interface RunOptions {
   /** Explicit id; otherwise the engine mints a ULID. */
@@ -5707,6 +5741,19 @@ interface RunOptions {
   tags?: string[];
   /** Host-initiated cancellation. */
   signal?: AbortSignal;
+  /**
+  * A lease the caller already holds for this run (the genesis side of
+  * the ResumeOptions.lease contract): the engine carries it on EVERY
+  * durable mutation of the fresh segment (every journal append, every
+  * putMeta, every transcript blob write) and never acquires, renews,
+  * or releases it itself; lifecycle stays with the caller. Passing it
+  * disables the engine's own ownership acquisition for this run
+  * regardless of the `ownership` mode. Hosts that admit runs through
+  * an external queue acquire the lease at admission time and hand it
+  * here, so admission and the first dispatch are covered by ONE
+  * fencing epoch.
+  */
+  lease?: Lease;
 }
 /** Resume-time hit/miss/orphan accounting. */
 interface ResumePreview extends ResumeReport {
@@ -7328,8 +7375,12 @@ interface RunInternals {
   * worktree patches) exactly as the Replayer threads it into every
   * journal append, so a store declaring fencedWrites refuses a
   * superseded segment's blob overwrites (fenced run state RFC, F2).
+  * The engine binds this as a live getter over its segment-lease
+  * holder (P0.2), so the union with undefined is explicit: before
+  * the ownership boot (and on non-leasable stores) it reads
+  * undefined.
   */
-  lease?: Lease;
+  lease?: Lease | undefined;
   adapters: ReadonlyMap<string, ProviderAdapter>;
   defaults: {
     routing?: Partial<Record<InvocationRole, ModelSpec>>;

package/dist/index.js

@@ -420,6 +420,7 @@ function wrapJournalStore(inner, hook) {
 		wrapped.acquire = (runId, owner) => inner.acquire(runId, owner);
 		wrapped.renew = (l) => inner.renew(l);
 		wrapped.release = (l) => inner.release(l);
+		if (typeof leasable.leaseTtlMs === "number") wrapped.leaseTtlMs = leasable.leaseTtlMs;
 	}
 	if (typeof inner.getMeta === "function") wrapped.getMeta = (runId) => inner.getMeta(runId);
 	return wrapped;
@@ -6779,6 +6780,7 @@ var Replayer = class {
 	runId;
 	store;
 	lease;
+	leaseOf;
 	now;
 	priceUsd;
 	onWarn;
@@ -6796,6 +6798,7 @@ var Replayer = class {
 		this.runId = options.runId;
 		this.store = options.store;
 		if (options.lease !== void 0) this.lease = options.lease;
+		if (options.leaseOf !== void 0) this.leaseOf = options.leaseOf;
 		this.now = options.now ?? realNow;
 		if (options.priceUsd !== void 0) this.priceUsd = options.priceUsd;
 		if (options.onWarn !== void 0) this.onWarn = options.onWarn;
@@ -7083,7 +7086,7 @@ var Replayer = class {
 		} });
 		const shapeIssues = validateEntryShape(entry);
 		if (shapeIssues.length > 0) throw new ConfigError(`journal entry shape violation (kind '${entry.kind}'): ` + shapeIssues.map((i) => i.message).join("; "));
-		await this.store.append(this.runId, entry, this.lease);
+		await this.store.append(this.runId, entry, this.leaseOf?.() ?? this.lease);
 		this.entries.push(entry);
 		if (entry.status === "suspended") this.foldInternal.registerSuspended(entry);
 		else if (entry.kind !== "resolution" && entry.kind !== "abandon") this.foldInternal.registerEntry(entry);
@@ -10402,7 +10405,7 @@ async function executeToolCall(options) {
 	try {
 		let value;
 		if (def.executor === "inprocess") value = await def.execute(validation.value, runtime.contextFor(call.name));
-		else if (runtime.executeExternal !== void 0) value = await runtime.executeExternal(def, validation.value);
+		else if (runtime.executeExternal !== void 0) value = await runtime.executeExternal(def, validation.value, options.ordinal);
 		else return finish({ error: `tool '${call.name}' declares executor '${def.executor}' but no executor is registered` }, "error");
 		const serialized = toJournalValue(value === void 0 ? null : value, `tool '${call.name}'`);
 		options.retryCounts.delete(call.name);
@@ -10829,6 +10832,7 @@ async function runAgent(options) {
 				runtime,
 				retryCounts: modelRetryCounts,
 				maxModelRetries: options.modelRetryAttempts ?? 2,
+				ordinal: toolCallsUsed,
 				...events === void 0 ? {} : { events },
 				...gateAudit === void 0 ? {} : { audit: gateAudit },
 				now
@@ -13170,15 +13174,30 @@ function setLongTimeout(onDue, dueAtMs, now = Date.now) {
 */
 /**
 * Derives the idempotency key for one isolated tool dispatch. The key is
-* a pure function of the run, the tool name, and the JCS-canonical
-* arguments, so the same logical call always yields the same key
-* (byte-identical reruns dedupe) and distinct calls never collide. The
-* key never enters run identity; it exists only for the provider's own
-* side-effect deduplication.
+* a pure function of the run, the LOGICAL INVOCATION (the seq of the
+* containing agent's journal entry plus that call's ordinal within the
+* agent's tool loop), the tool name, and the JCS-canonical arguments.
+*
+* The logical-invocation component is what makes the key both stable and
+* distinguishing (v1.59.x review P0.4): the agent-entry seq and the
+* per-agent tool-call ordinal are journal- and checkpoint-stable, so a
+* crash-and-resume re-dispatch of the SAME logical call (the at-least-
+* once window between execution and the turn checkpoint) reuses the same
+* dispatch entry and the restored ordinal, and therefore the same key;
+* while two SEPARATE calls in one run, even with byte-identical
+* arguments, occupy different ordinals and never collide. Without it two
+* intended effects sharing arguments would fold into one under external
+* deduplication.
+*
+* The key never enters run identity (it is absent from every content key
+* and toolset hash); it exists only for the provider's own side-effect
+* deduplication.
 */
-function deriveExecIdempotencyKey(runId, tool, args) {
+function deriveExecIdempotencyKey(runId, agentSeq, ordinal, tool, args) {
 	const canonical = jcsSerialize({
 		runId,
+		agentSeq,
+		ordinal,
 		tool,
 		args
 	});
@@ -13980,7 +13999,8 @@ function createCtx(internals, rootWorkflow) {
 			};
 			if (internals.executors !== void 0) {
 				const executors = internals.executors;
-				toolRuntime.executeExternal = async (def, args) => {
+				const agentSeq = running.seq;
+				toolRuntime.executeExternal = async (def, args, ordinal) => {
 					const tag = def.executor;
 					const provider = executors[tag];
 					if (provider === void 0) throw new ConfigError(`no executor registered for '${def.executor}'; register one via createEngine({ executors }) (https://docs.rulvar.com/guide/isolated-executor)`);
@@ -13994,7 +14014,7 @@ function createCtx(internals, rootWorkflow) {
 							runId: internals.runId,
 							spanId: toolSpanId,
 							agentType,
-							idempotencyKey: deriveExecIdempotencyKey(internals.runId, def.name, args),
+							idempotencyKey: deriveExecIdempotencyKey(internals.runId, agentSeq, ordinal, def.name, args),
 							signal: toolSignal,
 							log: (level, msg, data) => internals.events.emit(data === void 0 ? {
 								type: "log",
@@ -17102,6 +17122,28 @@ function hashRunOutput(value) {
 		return;
 	}
 }
+/**
+* Engine ownership identity: a process-local counter, not Math.random()
+* (the queue worker's identity convention): owner strings need
+* uniqueness within the store, and the dev-mode bare-randomness guard
+* stays armed while any run is live.
+*/
+let engineOrdinal = 0;
+function engineIdentity() {
+	engineOrdinal += 1;
+	return `rulvar-engine:${process.pid}:${engineOrdinal}`;
+}
+/** Lease capability guard, mirroring createWorker's detection. */
+function leaseCapable(store) {
+	const candidate = store;
+	return typeof candidate.acquire === "function" && typeof candidate.renew === "function" && typeof candidate.release === "function";
+}
+/**
+* The renew-cadence fallback when a leasable store exposes no
+* leaseTtlMs: the Appendix A interim reference ttl the shipped stores
+* default to (60000 ms).
+*/
+const ENGINE_DEFAULT_LEASE_TTL_MS = 6e4;
 function createEngine(options) {
 	const adapters = buildAdapterRegistry(options.adapters);
 	const rawJournal = options.stores?.journal ?? new InMemoryStore();
@@ -17111,6 +17153,17 @@ function createEngine(options) {
 	const maskEvents = options.redaction?.maskEvents ?? true;
 	const eventMasker = options.redaction?.patterns === void 0 ? void 0 : compileSecretMasker(options.redaction.patterns, "createEngine redaction.patterns");
 	const defaults = options.defaults ?? {};
+	const ownership = options.ownership ?? "auto";
+	if (ownership !== "auto" && ownership !== "none") throw new ConfigError(`createEngine ownership must be 'auto' or 'none'; got '${String(ownership)}'`);
+	const engineOwner = engineIdentity();
+	let ownershipRenewMs = Math.max(1, Math.floor(ENGINE_DEFAULT_LEASE_TTL_MS / 3));
+	if (ownership === "auto" && leaseCapable(journal)) {
+		const storeTtlMs = journal.leaseTtlMs;
+		if (storeTtlMs !== void 0) {
+			if (!Number.isInteger(storeTtlMs) || storeTtlMs < 1 || storeTtlMs > 2147483647) throw new ConfigError(`the journal store's leaseTtlMs capability must report an integer between 1 and 2147483647 ms for the engine's ownership renew cadence; got ${String(storeTtlMs)}`);
+			ownershipRenewMs = Math.max(1, Math.floor(storeTtlMs / 3));
+		}
+	}
 	if (defaults.retry !== void 0) validateRetryPolicy(defaults.retry, "createEngine defaults.retry");
 	if (options.concurrency?.perRun !== void 0) requirePositiveInteger(options.concurrency.perRun, "createEngine concurrency.perRun");
 	for (const [adapterId, cap] of Object.entries(options.concurrency?.perProvider ?? {})) requirePositiveInteger(cap, `createEngine concurrency.perProvider['${adapterId}']`);
@@ -17165,6 +17218,10 @@ function createEngine(options) {
 		if (compiled !== void 0 && options.runners?.sandbox === void 0) throw new ConfigError("running a CompiledWorkflow requires a sandbox runner: pass createEngine({ runners: { sandbox: new WorkerSandboxRunner() } }) from @rulvar/planner ");
 		const runId = resumeCtx?.runId ?? opts?.runId ?? mintRunId();
 		assertSafeRunId(runId, "engine.run");
+		const suppliedLease = resumeCtx?.lease ?? opts?.lease;
+		if (suppliedLease !== void 0 && suppliedLease.runId !== runId) throw new ConfigError(`the supplied lease is for run '${suppliedLease.runId}', not '${runId}'; a lease fences exactly the run it was acquired for`);
+		const segmentLease = {};
+		if (suppliedLease !== void 0) segmentLease.current = suppliedLease;
 		const registry = buildDeriverRegistry(options.extraDerivers);
 		const segmentsBefore = resumeCtx?.segmentsBefore ?? 0;
 		const telemetryBase = segmentsBefore * EVENT_SEGMENT_STRIDE;
@@ -17201,7 +17258,7 @@ function createEngine(options) {
 			}, rootSpanId),
 			keyRing: registryKeyRing(registry),
 			...resumeCtx === void 0 ? {} : { priorEntries: resumeCtx.priorEntries },
-			...resumeCtx?.lease === void 0 ? {} : { lease: resumeCtx.lease },
+			leaseOf: () => segmentLease.current,
 			strict: resumeCtx?.strict ?? false
 		});
 		for (const seqToInvalidate of invalidated) replayer.invalidate(seqToInvalidate);
@@ -17296,7 +17353,9 @@ function createEngine(options) {
 			external,
 			mintTranscriptRef: () => `${runId}/t${transcriptCounter++}`,
 			now: realNow,
-			...resumeCtx?.lease === void 0 ? {} : { lease: resumeCtx.lease }
+			get lease() {
+				return segmentLease.current;
+			}
 		};
 		const argsBinding = {};
 		if (resumeCtx === void 0) {
@@ -17324,15 +17383,60 @@ function createEngine(options) {
 			workflowName: wf.name,
 			workflowHash: compiled === void 0 ? hashWorkflowBody(wf) : hashWorkflowSource(compiled.source),
 			...compiled === void 0 ? {} : { workflowSourceRef: workflowSourceRef(runId) }
-		}, resumeCtx?.lease);
+		}, segmentLease.current);
 		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);
+		let ownershipTeardown = () => Promise.resolve();
 		const result = (async () => {
+			let ownedLease;
+			let renewTimer;
+			const settleOwnership = async () => {
+				if (renewTimer !== void 0) {
+					clearInterval(renewTimer);
+					renewTimer = void 0;
+				}
+				const held = ownedLease;
+				ownedLease = void 0;
+				if (held !== void 0) {
+					segmentLease.current = void 0;
+					try {
+						await journal.release(held);
+					} catch {}
+				}
+			};
+			ownershipTeardown = settleOwnership;
+			if (ownership === "auto" && segmentLease.current === void 0 && resumeCtx?.strict !== true && leaseCapable(journal)) {
+				let acquired;
+				try {
+					acquired = await journal.acquire(runId, engineOwner);
+				} catch (thrown) {
+					if (deadlineTimer !== void 0) deadlineTimer.cancel();
+					external.close();
+					bus.end();
+					throw thrown;
+				}
+				ownedLease = acquired;
+				segmentLease.current = acquired;
+				renewTimer = setInterval(() => {
+					journal.renew(acquired).catch(() => {
+						bus.emit({
+							type: "log",
+							level: "warn",
+							msg: `run '${runId}' ownership lost: the lease could not be renewed and its fencing epoch may be superseded`
+						}, rootSpanId);
+						requestCancel("run ownership lost: lease fencing epoch superseded");
+						if (renewTimer !== void 0) {
+							clearInterval(renewTimer);
+							renewTimer = void 0;
+						}
+					});
+				}, ownershipRenewMs);
+			}
 			let status = "ok";
 			let value;
 			let wireError;
 			let pending = [];
-			if (compiled !== void 0 && resumeCtx?.strict !== true) await transcripts.put(workflowSourceRef(runId), new TextEncoder().encode(compiled.source), resumeCtx?.lease);
+			if (compiled !== void 0 && resumeCtx?.strict !== true) await transcripts.put(workflowSourceRef(runId), new TextEncoder().encode(compiled.source), segmentLease.current);
 			await putMeta("running");
 			bus.emit({
 				type: "run:start",
@@ -17459,9 +17563,11 @@ function createEngine(options) {
 				...replayer.resumeReport(),
 				invalidResolutions: replayer.fold.invalidResolutions()
 			});
+			await settleOwnership();
 			return outcome;
 		})();
 		result.catch(() => void 0).finally(() => {
+			ownershipTeardown();
 			activeSegments.delete(runId);
 		});
 		return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/core",
-  "version": "1.59.2",
+  "version": "1.59.4",
   "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",