@godspeedai/cognate-runtime-bun 0.5.0 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@godspeedai/cognate-runtime-bun",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Bun reference runtime: composes kernel, durable store, runs, continuations, commitments, artifacts, and cognition behind RuntimeService.",
   "type": "module",
   "license": "Apache-2.0",
@@ -22,18 +22,18 @@
     ".": "./src/index.ts"
   },
   "dependencies": {
-    "@godspeedai/cognate-artifacts": "^0.5.0",
-    "@godspeedai/cognate-capabilities": "^0.5.0",
-    "@godspeedai/cognate-cognitive-api": "^0.5.0",
-    "@godspeedai/cognate-continuations": "^0.5.0",
-    "@godspeedai/cognate-events": "^0.5.0",
-    "@godspeedai/cognate-kernel-api": "^0.5.0",
-    "@godspeedai/cognate-kernel-cordis": "^0.5.0",
-    "@godspeedai/cognate-projections": "^0.5.0",
-    "@godspeedai/cognate-runtime-api": "^0.5.0",
-    "@godspeedai/cognate-store-memory": "^0.5.0",
-    "@godspeedai/cognate-store-postgres": "^0.5.0",
-    "@godspeedai/cognate-store-sqlite": "^0.5.0"
+    "@godspeedai/cognate-artifacts": "^0.6.1",
+    "@godspeedai/cognate-capabilities": "^0.6.1",
+    "@godspeedai/cognate-cognitive-api": "^0.6.1",
+    "@godspeedai/cognate-continuations": "^0.6.1",
+    "@godspeedai/cognate-events": "^0.6.1",
+    "@godspeedai/cognate-kernel-api": "^0.6.1",
+    "@godspeedai/cognate-kernel-cordis": "^0.6.1",
+    "@godspeedai/cognate-projections": "^0.6.1",
+    "@godspeedai/cognate-runtime-api": "^0.6.1",
+    "@godspeedai/cognate-store-memory": "^0.6.1",
+    "@godspeedai/cognate-store-postgres": "^0.6.1",
+    "@godspeedai/cognate-store-sqlite": "^0.6.1"
   },
   "devDependencies": {
     "@godspeedai/cognate-cognitive-memory": "workspace:*"

package/src/executor.ts

@@ -1,7 +1,7 @@
 // Durable run execution by deterministic replay (ADR-0011, spec §11, §12).
 // Each execution re-reads the run stream, re-enters the agent from the top, and answers every
 // RunContext call that already has a recorded result from the stream instead of repeating it.
-import { ConcurrencyError, fingerprint, IdempotencyMismatchError, type Json, type NewEvent, type StoredEvent } from "@godspeedai/cognate-events";
+import { ConcurrencyError, fingerprint, IdempotencyMismatchError, type Json, type NewEvent, StaleRunOwnerError, type StoredEvent } from "@godspeedai/cognate-events";
 import type { Principal, SemanticRef } from "@godspeedai/cognate-kernel-api";
 import { applyStateUpdate, type ArtifactInput, ContinuationClosedError, FrontendCapabilityError, foldState, InvocationFailedError, type RemoteCapabilityOffer, type RunContext, StatePatchError, type WaitSpec } from "@godspeedai/cognate-runtime-api";
 import type { Core, RecallResultJson } from "./core.ts";
@@ -14,7 +14,17 @@ class Halt {
 
 export type ExecutionResult = "done" | "retry";
 
-export async function executeOnce(core: Core, runId: string): Promise<ExecutionResult> {
+/** The fenced run-write ownership a worker holds for one execution pass
+ * (docs/contracts/run-write-ownership.md). The credential fences every run-scoped append; renew
+ * refreshes the lease and reports whether ownership was lost. */
+export interface RunExecutionOwnership {
+  readonly ownerId: string;
+  readonly generation: number;
+  readonly ambiguousSteps: "reexecute" | "wait";
+  readonly renew: () => Promise<boolean>;
+}
+
+export async function executeOnce(core: Core, runId: string, ownership?: RunExecutionOwnership): Promise<ExecutionResult> {
   // Register before the first store await so cancellation and shutdown can reach this attempt
   // while its initial snapshot is being read.
   const controller = new AbortController();
@@ -23,14 +33,14 @@ export async function executeOnce(core: Core, runId: string): Promise<ExecutionR
   if (core.shutdownSignal.aborted) stopForShutdown();
   else core.shutdownSignal.addEventListener("abort", stopForShutdown, { once: true });
   try {
-    return await executeRegistered(core, runId, controller);
+    return await executeRegistered(core, runId, controller, ownership);
   } finally {
     core.shutdownSignal.removeEventListener("abort", stopForShutdown);
     if (core.controllers.get(runId) === controller) core.controllers.delete(runId);
   }
 }
 
-async function executeRegistered(core: Core, runId: string, controller: AbortController): Promise<ExecutionResult> {
+async function executeRegistered(core: Core, runId: string, controller: AbortController, ownership?: RunExecutionOwnership): Promise<ExecutionResult> {
   const streamId = runStream(runId);
   const events = await core.store.readStream(streamId);
   if (controller.signal.aborted) return "done";
@@ -81,13 +91,23 @@ async function executeRegistered(core: Core, runId: string, controller: AbortCon
       try {
         // Pre-assign the id so hooks can derive intents that commit atomically with the event (spec §13.1).
         const pending = { ...envelope, eventId: crypto.randomUUID(), streamId, recordedAt: envelope.occurredAt };
-        const outcome = await core.store.commit({ appends: [{ streamId, expectedVersion: version, events: [{ ...envelope, eventId: pending.eventId }] }], outbox: core.outboxFor(pending) });
+        const outcome = await core.store.commit({
+          appends: [{
+            streamId,
+            expectedVersion: version,
+            events: [{ ...envelope, eventId: pending.eventId }],
+            ...(ownership ? { runOwnership: { runId, ownerId: ownership.ownerId, generation: ownership.generation } } : {}),
+          }],
+          outbox: core.outboxFor(pending),
+        });
         const stored = outcome.events[0]!;
         version += 1;
         lastEventId = stored.eventId;
         return stored;
       } catch (error) {
         if (error instanceof ConcurrencyError) halt(true);
+        // Ownership was reclaimed or released: this worker is stale and must never retry the pass.
+        if (error instanceof StaleRunOwnerError) halt(false);
         throw error;
       }
     });
@@ -149,17 +169,49 @@ async function executeRegistered(core: Core, runId: string, controller: AbortCon
       // recorded event) but are a distinct event type, so the completion check must name it explicitly.
       let done = find(stepId, "run.invocation");
       if (!done) {
+        // Refresh the ownership lease before any external effect: a lost lease must be discovered
+        // before dispatch, not after (docs/contracts/run-write-ownership.md).
+        if (ownership && !(await ownership.renew())) halt(false);
+        const priorProgress = (recorded.get(stepId) ?? []).filter((e) => e.eventType === "run.invocation.progress");
+        // A previous owner's generation started this invocation and never recorded its outcome.
+        // Under `ambiguousSteps: "wait"` the recovering owner does not re-perform the effect: it
+        // records the ambiguity and waits for explicit reconciliation.
+        if (ownership && ownership.ambiguousSteps === "wait") {
+          const priorGenerations = priorProgress
+            .map((e) => field<number>(meta(e), "ownerGeneration"))
+            .filter((generation): generation is number => typeof generation === "number" && generation < ownership.generation);
+          if (priorGenerations.length > 0) {
+            const priorGeneration = Math.max(...priorGenerations);
+            const ambiguousStepId = `${stepId}:ambiguous`;
+            if (!find(ambiguousStepId, "run.invocation.ambiguous")) {
+              await append({ eventType: "run.invocation.ambiguous", payload: { capability, priorGeneration }, metadata: { stepId: ambiguousStepId, capability, priorGeneration } });
+            }
+            const resolution = await context.waitFor(`ambiguous:${stepId}`, {
+              type: "ambiguous-invocation",
+              condition: { kind: "ambiguous_invocation", capability, priorGeneration },
+              payload: { capability, stepId, priorGeneration },
+            });
+            const reconciled = (resolution ?? null) as { readonly result?: Json; readonly failure?: { readonly kind: string; readonly message?: string } } | null;
+            if (reconciled?.failure) throw new InvocationFailedError(capability, reconciled.failure);
+            return reconciled?.result ?? null;
+          }
+        }
         // A crash between a progress call and the final run.invocation event leaves partial progress
         // recorded for this stepId with no completion; re-executing calls the handler again under a
         // fresh attempt number so consumers can discard the earlier partial attempt.
-        const priorAttempts = (recorded.get(stepId) ?? [])
-          .filter((e) => e.eventType === "run.invocation.progress")
-          .map((e) => field<number>(meta(e), "attempt") ?? 0);
+        const priorAttempts = priorProgress.map((e) => field<number>(meta(e), "attempt") ?? 0);
         const attempt = priorAttempts.length ? Math.max(...priorAttempts) + 1 : 0;
         let seq = 0;
         const progress = async (payload: Json): Promise<void> => {
           guard();
-          await append({ eventType: "run.invocation.progress", payload: toJson(payload), metadata: { stepId, capability, attempt, seq: seq++ } });
+          await append({
+            eventType: "run.invocation.progress",
+            payload: toJson(payload),
+            metadata: {
+              stepId, capability, attempt, seq: seq++,
+              ...(ownership ? { ownerGeneration: ownership.generation } : {}),
+            },
+          });
         };
         const call = (approval?: { readonly approvalId: string }) =>
           core.invoker.invoke({
@@ -358,12 +410,14 @@ async function executeRegistered(core: Core, runId: string, controller: AbortCon
                   payload: toJson(update),
                   metadata: { scope: "thread", threadId: view.correlationId, source: "agent", actor: context.actor.id, stepId: `shared-state.update:${id}` },
                 }],
+                ...(ownership ? { runOwnership: { runId, ownerId: ownership.ownerId, generation: ownership.generation } } : {}),
               }],
               result: { state, version: events.length + 1 },
             });
             return outcome.result as { readonly state: Json; readonly version: number };
           } catch (error) {
             if (error instanceof ConcurrencyError) continue;
+            if (error instanceof StaleRunOwnerError) halt(false);
             if (error instanceof IdempotencyMismatchError) throw new Error(`thread state update ${id} was replayed with different input`);
             throw error;
           }

package/src/index.ts

@@ -67,6 +67,9 @@ export interface RuntimeOptions {
   /** Background work loop interval (run execution, resume delivery, expiry). Default 10 ms. */
   readonly tickMs?: number;
   /** Explicit single-process execution admission; defaults to serial compatibility. */
+  readonly execution?: {
+    readonly maxConcurrentRuns?: number;
+    /** Required above capacity one. Returning [] explicitly declares independent eligibility.
   readonly execution?: {
     readonly maxConcurrentRuns?: number;
     /** Required above capacity one. Returning [] explicitly declares independent eligibility.
@@ -74,6 +77,19 @@ export interface RuntimeOptions {
      * from authoritative application metadata. Its signal is aborted when the run is cancelled or the runtime closes.
      * Runs sharing a key serialize in this process; this is not distributed ownership or OS isolation. */
     readonly resourceKeys?: (run: RunView, signal?: AbortSignal) => readonly string[] | Promise<readonly string[]>;
+    /** Fenced run-write ownership tuning (docs/contracts/run-write-ownership.md). Claims happen
+     * automatically whenever the store implements the extension; SQLite/memory stay legacy. */
+    readonly runOwnership?: {
+      /** Stable worker identity for claims; defaults to a per-runtime random id. */
+      readonly ownerId?: string;
+      /** Lease duration in milliseconds; default 30_000. Expiry is reclaim eligibility, not
+       * ownership loss — a matching generation stays writable until someone reclaims. */
+      readonly leaseMs?: number;
+      /** What a recovering owner does with a previous generation's started-but-unrecorded
+       * invocation: "reexecute" (historical behavior, default) or "wait" — record an ambiguity
+       * and require explicit reconciliation before the external effect may repeat. */
+      readonly ambiguousSteps?: "reexecute" | "wait";
+    };
   };
   readonly system?: Principal;
 }

package/src/runtime.ts

@@ -2,7 +2,7 @@
 import { randomUUID } from "node:crypto";
 import { ArtifactService } from "@godspeedai/cognate-artifacts";
 import { ContinuationService } from "@godspeedai/cognate-continuations";
-import { type DurableStore, type Json, NotFoundError, OutboxDispatcher } from "@godspeedai/cognate-events";
+import { type DurableStore, type Json, NotFoundError, OutboxDispatcher, RunOwnershipHeldError } from "@godspeedai/cognate-events";
 import { createCordisKernel } from "@godspeedai/cognate-kernel-cordis";
 import type { Principal } from "@godspeedai/cognate-kernel-api";
 import type { RunView } from "@godspeedai/cognate-runtime-api";
@@ -11,7 +11,7 @@ import { openPostgresStore, resolvePg0Url } from "@godspeedai/cognate-store-post
 import { openSqliteStore } from "@godspeedai/cognate-store-sqlite";
 import { COGNITION_PROJECTION, cognitionProjection, recallFor } from "./cognition.ts";
 import type { Core } from "./core.ts";
-import { executeOnce } from "./executor.ts";
+import { executeOnce, type RunExecutionOwnership } from "./executor.ts";
 import { ExecutionSlots } from "./execution-slots.ts";
 import { foldRun, isTerminal, RESUME_HANDLER, RUN_EXECUTE_TOPIC, RUNS, runStream } from "./fold.ts";
 import type { Runtime, RuntimeOptions } from "./index.ts";
@@ -35,6 +35,10 @@ export async function startRuntime(options: RuntimeOptions): Promise<Runtime> {
     }
   }
   const slots=new ExecutionSlots(capacity);
+  // Fenced run-write ownership worker identity (docs/contracts/run-write-ownership.md). Per
+  // runtime instance: a restarted process reclaims with a fresh generation.
+  const ownerId=options.execution?.runOwnership?.ownerId ?? `worker-${crypto.randomUUID()}`;
+  const leaseMs=options.execution?.runOwnership?.leaseMs ?? 30_000;
   // Recovery can enqueue many runs at once. Bound authoritative eligibility lookups with the
   // same primitive/capacity so metadata resolution cannot fan out without limit.
   const eligibilitySlots = new ExecutionSlots(capacity);
@@ -163,7 +167,42 @@ export async function startRuntime(options: RuntimeOptions): Promise<Runtime> {
       if (!release) return;
       try{
         if (closed) return;
-        for (let attempt = 0; attempt < 5 && !closed; attempt++) if ((await executeOnce(core, runId)) === "done") return;
+        // Fenced run-write ownership (docs/contracts/run-write-ownership.md): claim before
+        // executing. A held lease means another live worker is executing this run — back off;
+        // its completion, suspension or death releases the run for a later pass to reclaim.
+        let ownership: RunExecutionOwnership | undefined;
+        if (store.claimRunOwnership) {
+          try {
+            const lease = await store.claimRunOwnership({ runId, ownerId, now: Date.now(), leaseMs });
+            ownership = {
+              ownerId,
+              generation: lease.generation,
+              ambiguousSteps: options.execution?.runOwnership?.ambiguousSteps ?? "reexecute",
+              renew: () => store.renewRunOwnership!({ runId, ownerId, generation: lease.generation, now: Date.now(), leaseMs }).then((ok) => ok === true),
+            };
+          } catch (error) {
+            if (error instanceof RunOwnershipHeldError) {
+              // Another live worker owns this run. Its lease expiry is reclaim eligibility, so
+              // re-arm this run for recovery once that lease can have lapsed; the durable
+              // intent machinery re-dispatches it on a later pass. Without this, a held-lease
+              // back-off would consume the only recovery trigger and strand the run.
+              const retryAt = error.lease.expiresAt - Date.now() + 250;
+              setTimeout(() => {
+                if (closed) return;
+                pending.add(runId);
+                kick();
+              }, Math.max(250, retryAt));
+              return;
+            }
+            throw error;
+          }
+        }
+        try{
+          for (let attempt = 0; attempt < 5 && !closed; attempt++) if ((await executeOnce(core, runId, ownership)) === "done") return;
+        }finally{
+          // Best-effort release: a reclaimed or already-released row simply refuses.
+          if (ownership) await store.releaseRunOwnership!({ runId, ownerId, generation: ownership.generation }).catch(() => {});
+        }
       }finally{release();}
     });
     const tracked = next.finally(() => {