@godspeedai/cognate-runtime-bun 0.2.0 → 0.4.0

package/README.md

@@ -124,12 +124,14 @@ kept current automatically), `cognition` (index completed runs and recall them v
 
 ## Limitations
 
-- **One process, one writer.** All runs live in the process that opened the store; executions
-  within a tick run sequentially, so a slow agent delays others. To scale out, split runtimes per
-  store file.
+- **One runtime execution owner per store.** PostgreSQL supports multiple durable-store writers;
+  that does not establish distributed run ownership. Run execution defaults to serial. Opt-in
+  `execution.maxConcurrentRuns` admits bounded independent runs in one process and requires a
+  trusted `execution.resourceKeys` eligibility policy above one. Shared resource keys serialize;
+  callers must canonicalize aliases. Do not start competing runtimes against the same runnable work.
 - **Steps are at-least-once.** A step that was in flight during a crash re-executes after restart.
-  Keep steps idempotent, and put irreversible external calls behind a `ctx.waitFor` continuation so
-  they happen once, resolved deliberately.
+  Keep steps idempotent, and use native commitment receipts and explicit reconciliation for external
+  actions. A continuation or permission gate alone does not establish exactly-once physical effects.
 - **Polling, not pushing, inside the process.** Background work (run execution, resume delivery,
   continuation expiry) runs on a loop every `tickMs`.
 - **Erasure has copies.** `runtime.erase` removes an event's payload from the log, derived views,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@godspeedai/cognate-runtime-bun",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "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.2.0",
-    "@godspeedai/cognate-capabilities": "^0.2.0",
-    "@godspeedai/cognate-cognitive-api": "^0.2.0",
-    "@godspeedai/cognate-continuations": "^0.2.0",
-    "@godspeedai/cognate-events": "^0.2.0",
-    "@godspeedai/cognate-kernel-api": "^0.2.0",
-    "@godspeedai/cognate-kernel-cordis": "^0.2.0",
-    "@godspeedai/cognate-projections": "^0.2.0",
-    "@godspeedai/cognate-runtime-api": "^0.2.0",
-    "@godspeedai/cognate-store-memory": "^0.2.0",
-    "@godspeedai/cognate-store-postgres": "^0.2.0",
-    "@godspeedai/cognate-store-sqlite": "^0.2.0"
+    "@godspeedai/cognate-artifacts": "^0.4.0",
+    "@godspeedai/cognate-capabilities": "^0.4.0",
+    "@godspeedai/cognate-cognitive-api": "^0.4.0",
+    "@godspeedai/cognate-continuations": "^0.4.0",
+    "@godspeedai/cognate-events": "^0.4.0",
+    "@godspeedai/cognate-kernel-api": "^0.4.0",
+    "@godspeedai/cognate-kernel-cordis": "^0.4.0",
+    "@godspeedai/cognate-projections": "^0.4.0",
+    "@godspeedai/cognate-runtime-api": "^0.4.0",
+    "@godspeedai/cognate-store-memory": "^0.4.0",
+    "@godspeedai/cognate-store-postgres": "^0.4.0",
+    "@godspeedai/cognate-store-sqlite": "^0.4.0"
   },
   "devDependencies": {
     "@godspeedai/cognate-cognitive-memory": "workspace:*"

package/src/execution-slots.ts

@@ -0,0 +1,37 @@
+/** Admission inside the native executor, shared by start/recovery/resume paths. This is a
+ * process-local limit and resource exclusion, not durable ownership of an execution. */
+export class ExecutionSlots {
+  private active = 0;
+  private readonly held = new Set<string>();
+  private readonly waiting: {keys: readonly string[]; resolve: (release: () => void) => void}[] = [];
+  constructor(readonly capacity: number) {}
+
+  acquire(raw: readonly string[]): Promise<() => void> {
+    if (!Array.isArray(raw) || raw.length > 100 || raw.some(key=>typeof key!=="string" || !key || key.length>500)) {
+      return Promise.reject(new Error("execution.resourceKeys must return at most 100 nonempty resource identities"));
+    }
+    return new Promise(resolve=>{
+      this.waiting.push({keys:[...new Set(raw)].sort(),resolve});
+      this.pump();
+    });
+  }
+  private pump(): void {
+    const earlier=new Set<string>();
+    for(let i=0;i<this.waiting.length && this.active<this.capacity;){
+      const item=this.waiting[i]!;
+      if(item.keys.some(key=>this.held.has(key) || earlier.has(key))){
+        for(const key of item.keys)earlier.add(key);
+        i++;continue;
+      }
+      this.waiting.splice(i,1);this.active++;
+      for(const key of item.keys)this.held.add(key);
+      let released=false;
+      item.resolve(()=>{
+        if(released)return;
+        released=true;this.active--;
+        for(const key of item.keys)this.held.delete(key);
+        this.pump();
+      });
+    }
+  }
+}

package/src/index.ts

@@ -2,7 +2,7 @@ import type { CognitiveIndex, Embedder, IndexDocument } from "@godspeedai/cognat
 import type { DurableStore, Json, NewEvent, OutboxIntent, StoredEvent } from "@godspeedai/cognate-events";
 import type { Component, Kernel, Policy, Principal } from "@godspeedai/cognate-kernel-api";
 import type { Projection } from "@godspeedai/cognate-projections";
-import type { AgentDefinition, Caller, RuntimeService } from "@godspeedai/cognate-runtime-api";
+import type { AgentDefinition, Caller, RuntimeService, RunView } from "@godspeedai/cognate-runtime-api";
 import type { GovernanceOptions } from "./governed-operation.ts";
 import { startRuntime } from "./runtime.ts";
 
@@ -66,6 +66,14 @@ export interface RuntimeOptions {
   readonly outboxFor?: (event: PendingEvent) => readonly OutboxIntent[];
   /** 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.
+     * Trusted resource identities derived from frozen run inputs, never model-granted authority.
+     * Runs sharing a key serialize in this process; this is not a distributed lock or OS isolation. */
+    readonly resourceKeys?: (run: RunView) => readonly string[];
+  };
   readonly system?: Principal;
 }
 

package/src/runtime.ts

@@ -10,6 +10,7 @@ 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 { 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";
 import { inspectCorrelation } from "./inspect.ts";
@@ -22,6 +23,25 @@ const DELIVERY = { baseMs: 50, maxMs: 5_000, maxAttempts: 10 };
 const TOPICS = [RUN_EXECUTE_TOPIC, "continuation.resume"];
 
 export async function startRuntime(options: RuntimeOptions): Promise<Runtime> {
+  const capacity=options.execution?.maxConcurrentRuns ?? 1;
+  if(!Number.isInteger(capacity) || capacity<1 || capacity>64)throw new Error("execution.maxConcurrentRuns must be an integer between 1 and 64");
+  if(capacity>1 && typeof options.execution?.resourceKeys!=="function")throw new Error("Concurrent execution requires an explicit execution.resourceKeys eligibility policy");
+  if(capacity>1 && typeof options.store!=="string" && "store" in options.store){
+    const injected=options.store.store;
+    if(typeof injected.claimOutboxLeased!=="function" || typeof injected.renewOutboxLease!=="function" || typeof injected.settleOutboxLease!=="function"){
+      throw new Error("Concurrent execution requires a store with complete fenced outbox lease support");
+    }
+  }
+  const slots=new ExecutionSlots(capacity);
+  // Run and resume topics share one pre-claim budget. ExecutionSlots separately enforces
+  // run-local/resource exclusion for every execution path, including direct recovery.
+  let admittedDeliveries = 0;
+  const deliveryAdmission = { tryAcquire(): (() => void) | undefined {
+    if (admittedDeliveries >= capacity) return undefined;
+    admittedDeliveries++;
+    let released = false;
+    return () => { if (!released) { released = true; admittedDeliveries--; } };
+  } };
   // The runtime closes only stores it opened itself; an injected store is owned by its creator.
   // (The PostgreSQL store's close() ends its pool and LISTEN connection, so one call covers both.)
   const config = options.store;
@@ -47,14 +67,24 @@ export async function startRuntime(options: RuntimeOptions): Promise<Runtime> {
   await invoker.attach(kernel, options.components ?? []);
 
   // Authorization happens in the service against `actions`; the continuation layer trusts its caller.
-  const continuations = new ContinuationService(store, { policy: { authorize: () => ({ allow: true, reason: "authorized by runtime service" }) }, delivery: DELIVERY });
+  const continuations = new ContinuationService(store, { policy: { authorize: () => ({ allow: true, reason: "authorized by runtime service" }) }, delivery: DELIVERY, deliveryConcurrency: capacity, deliveryAdmission });
 
   let closed = false;
   const chains = new Map<string, Promise<void>>();
   const pending = new Set<string>();
+  const deliveries = new Set<Promise<void>>();
+  const trackDelivery=(job:Promise<unknown>):void=>{
+    const tracked=job.then(()=>{},()=>{}).finally(()=>deliveries.delete(tracked));
+    deliveries.add(tracked);
+  };
   const execute = (runId: string): Promise<void> => {
     const next = (chains.get(runId) ?? Promise.resolve()).then(async () => {
-      for (let attempt = 0; attempt < 5 && !closed; attempt++) if ((await executeOnce(core, runId)) === "done") return;
+      const view=foldRun(runId,await store.readStream(runStream(runId)));
+      if(closed || !view || isTerminal(view))return;
+      const release=await slots.acquire(options.execution?.resourceKeys?.(view) ?? []);
+      try{
+        for (let attempt = 0; attempt < 5 && !closed; attempt++) if ((await executeOnce(core, runId)) === "done") return;
+      }finally{release();}
     });
     const tracked = next.finally(() => {
       if (chains.get(runId) === tracked) chains.delete(runId);
@@ -88,6 +118,8 @@ export async function startRuntime(options: RuntimeOptions): Promise<Runtime> {
 
   const runDispatcher = new OutboxDispatcher(store, {
     topic: RUN_EXECUTE_TOPIC,
+    concurrency: capacity,
+    admission: deliveryAdmission,
     backoff: DELIVERY,
     deliver: async (item) => {
       await execute((item.payload as { runId: string }).runId);
@@ -95,14 +127,24 @@ export async function startRuntime(options: RuntimeOptions): Promise<Runtime> {
     },
   });
 
+  let resumeFirst = false;
   async function tick(): Promise<void> {
     for (const record of await continuations.expireDue()) pending.add(record.runId);
-    await continuations.dispatchResumes();
-    await runDispatcher.drain();
-    for (const runId of [...pending]) {
-      pending.delete(runId);
-      await execute(runId);
+    // Dispatchers reserve a bounded set of slots across overlapping drains. A new runnable
+    // arrival can fill a free slot while an earlier long-running delivery is still executing.
+    // Rotate priority: even an empty topic briefly reserves capacity while its claim is
+    // in flight. A fixed first topic could otherwise starve the other at capacity one.
+    if (resumeFirst) {
+      trackDelivery(continuations.dispatchResumes());
+      trackDelivery(runDispatcher.drain());
+    } else {
+      trackDelivery(runDispatcher.drain());
+      trackDelivery(continuations.dispatchResumes());
     }
+    resumeFirst = !resumeFirst;
+    const recover=[...pending];
+    for(const runId of recover)pending.delete(runId);
+    for(const runId of recover)trackDelivery(execute(runId));
   }
 
   let ticking: Promise<void> | null = null;
@@ -290,7 +332,7 @@ export async function startRuntime(options: RuntimeOptions): Promise<Runtime> {
   }
 
   async function quiescent(): Promise<boolean> {
-    if (ticking || pending.size > 0 || chains.size > 0) return false;
+    if (ticking || pending.size > 0 || chains.size > 0 || deliveries.size>0) return false;
     const now = Date.now();
     for (const topic of TOPICS) {
       const items = await store.listOutbox({ topic, status: "pending" });
@@ -342,6 +384,7 @@ export async function startRuntime(options: RuntimeOptions): Promise<Runtime> {
       clearInterval(timer);
       if (approvalTimer) clearInterval(approvalTimer);
       await ticking;
+      await Promise.allSettled([...deliveries]);
       await Promise.allSettled([...chains.values()]);
       for (const runner of runners) await runner.stop();
       unregister();