@godspeedai/cognate-runtime-bun 0.1.2 → 0.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 The Cognate reference runtime for Bun: durable agent runs, human-in-the-loop continuations,
 artifacts, projections, and optional cognition, composed in-process behind a single
-`RuntimeService`. Point it at a SQLite file and your application's history survives restarts.
+`RuntimeService`. Point it at a SQLite file and your application's history survives restarts; point it at PostgreSQL (or a pg0-managed local instance) and multiple processes share the same history safely.
 
 **When to use this package:** to run agents for real — in a server, a worker, or a script. Pair it
 with [`@godspeedai/cognate-client`](https://www.npmjs.com/package/@godspeedai/cognate-client) to

package/package.json

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

package/src/index.ts

@@ -34,9 +34,20 @@ export type PendingEvent = NewEvent & { readonly eventId: string; readonly strea
 /** Outbox topic whose items represent RealityTrace observations; `inspect` reports their observation ids. */
 export const OBSERVATION_OUTBOX_TOPIC = "observation.deliver";
 
+/** Where the runtime's authoritative state lives (spec §13). SQLite stays the zero-dependency default;
+ * PostgreSQL removes the single-writer limit (multi-process runtimes share one database). */
+export type RuntimeStoreConfig =
+  /** SQLite database file path, or `":memory:"` for an in-memory SQLite database. */
+  | string
+  | { readonly store: DurableStore }
+  | { readonly sqlite: { readonly path: string } }
+  | { readonly postgres: { readonly url: string; readonly schema?: string } }
+  | { readonly postgresPg0: { readonly name?: string; readonly schema?: string; readonly bin?: string } };
+
 export interface RuntimeOptions {
-  /** SQLite file path, `":memory:"` for an in-memory SQLite database, or an explicit store. */
-  readonly store: string | { readonly store: DurableStore };
+  /** Where durable state lives: a SQLite path (default form), an explicit store, a PostgreSQL
+   * connection (`postgres`), or a pg0-managed local instance (`postgresPg0` starts it if needed). */
+  readonly store: RuntimeStoreConfig;
   /** Kernel invocation policy for capabilities (default-deny if omitted). */
   readonly policy: Policy;
   readonly actions: ActionPolicy;

package/src/runtime.ts

@@ -1,10 +1,11 @@
 // Composition root: store, kernel, continuations, artifacts, projections, cognition, and the background loop.
 import { ArtifactService } from "@godspeedai/cognate-artifacts";
 import { ContinuationService } from "@godspeedai/cognate-continuations";
-import { type DurableStore, OutboxDispatcher } from "@godspeedai/cognate-events";
+import { type DurableStore, type Json, NotFoundError, OutboxDispatcher } from "@godspeedai/cognate-events";
 import { createCordisKernel } from "@godspeedai/cognate-kernel-cordis";
 import type { Principal } from "@godspeedai/cognate-kernel-api";
 import { ProjectionRunner } from "@godspeedai/cognate-projections";
+import { openPostgresStore, resolvePg0Url } from "@godspeedai/cognate-store-postgres";
 import { openSqliteStore } from "@godspeedai/cognate-store-sqlite";
 import { COGNITION_PROJECTION, cognitionProjection, recallFor } from "./cognition.ts";
 import type { Core } from "./core.ts";
@@ -21,8 +22,23 @@ 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 ownsStore = typeof options.store === "string";
-  const store: DurableStore = typeof options.store === "string" ? openSqliteStore({ path: options.store }) : options.store.store;
+  // 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;
+  const ownsStore = typeof config === "string" || !("store" in config);
+  let store: DurableStore;
+  if (typeof config === "string") {
+    store = openSqliteStore({ path: config });
+  } else if ("store" in config) {
+    store = config.store;
+  } else if ("sqlite" in config) {
+    store = openSqliteStore({ path: config.sqlite.path });
+  } else if ("postgres" in config) {
+    store = (await openPostgresStore({ url: config.postgres.url, schema: config.postgres.schema })).store;
+  } else {
+    const url = await resolvePg0Url(config.postgresPg0);
+    store = (await openPostgresStore({ url, schema: config.postgresPg0.schema })).store;
+  }
   const system: Principal = options.system ?? { id: "system", kind: "system" };
   const governor = new Governor(options.actions, options.policy, options.governance ?? { mode: "off" });
   const invoker = new Invoker(governor);
@@ -136,6 +152,107 @@ export async function startRuntime(options: RuntimeOptions): Promise<Runtime> {
     }
   }
 
+  // ── Erasure propagation (spec §32, DEBT-014) ─────────────────────────────────────
+  // Erasing one event must also reach its derived copies: idempotency result snapshots (redacted by
+  // the store's erasePayload itself), continuation records and their transition events, run.resumed
+  // resolution copies on the run stream, and recorded run.recall results referencing the erased
+  // run's view. Every erasure is recorded as a durable job before it runs, so an interrupted
+  // propagation resumes on the next erase call or runtime start instead of being reported complete.
+  const ERASURES = "erasures";
+
+  interface ErasureJob {
+    readonly id: string;
+    readonly streamId: string | null;
+    readonly runId: string | null;
+    readonly eventType: string | null;
+    readonly reason: string;
+  }
+
+  async function propagateErasure(job: ErasureJob): Promise<void> {
+    const event = await store.getEvent(job.id);
+    if (event && !event.erasure) await store.erasePayload(job.id, job.reason, "erasure");
+    if (!job.runId) return;
+    await continuations.redactForRun(job.runId, { reason: job.reason });
+    // run.resumed events carry the resolution-input copy on the run stream itself.
+    for (const e of await store.readStream(runStream(job.runId))) {
+      if (e.eventType === "run.resumed" && !e.erasure) await store.erasePayload(e.eventId, job.reason, "erasure");
+    }
+    // A recorded run.recall whose items reference an erased run's view copies that view's source
+    // content (run.started input, run.completed output). Lineage is explicit (sourceRef), not a text
+    // guess. The closure is transitive: a recalling run's own terminal output may embed the recalled
+    // result (the agent returned it), and a third run may have recalled THAT view — so each erased
+    // terminal output makes its run a view source too. Visited runs terminate the loop.
+    if (job.eventType !== "run.started" && job.eventType !== "run.completed") return;
+    const viewSources: string[] = [job.runId];
+    const visited = new Set<string>();
+    while (viewSources.length > 0) {
+      const sourceRunId = viewSources.shift()!;
+      if (visited.has(sourceRunId)) continue;
+      visited.add(sourceRunId);
+      let afterPosition = 0;
+      for (;;) {
+        const page = await store.readAll({ afterPosition, limit: 500 });
+        if (page.length === 0) break;
+        for (const e of page) {
+          afterPosition = e.position;
+          if (e.eventType !== "run.recall" || e.erasure || !e.runId) continue;
+          const items = (e.payload as { readonly result?: { readonly items?: readonly { readonly sourceRef?: string }[] } } | null)?.result?.items;
+          if (!Array.isArray(items) || !items.some((item) => item.sourceRef === `run:${sourceRunId}`)) continue;
+          await store.erasePayload(e.eventId, job.reason, "erasure");
+          // The recalling run's terminal output may embed the recalled content; erase it and treat
+          // that run as a view source for its own recallers.
+          for (const terminal of await store.readStream(runStream(e.runId))) {
+            if ((terminal.eventType === "run.completed" || terminal.eventType === "run.failed") && !terminal.erasure) {
+              await store.erasePayload(terminal.eventId, job.reason, "erasure");
+            }
+          }
+          viewSources.push(e.runId);
+        }
+        if (page.length < 500) break;
+      }
+    }
+  }
+
+  async function completeErasureJob(job: { readonly id: string; readonly version: number; readonly value: Record<string, Json> }): Promise<void> {
+    await store.commit({
+      appends: [],
+      records: [{ collection: ERASURES, id: job.id, expectedVersion: job.version, value: { ...job.value, status: "complete", completedAt: new Date().toISOString() } }],
+    });
+  }
+
+  async function resumeErasureJobs(): Promise<void> {
+    for (const stored of await store.listRecords(ERASURES, { status: "propagating" })) {
+      const value = stored.value;
+      await propagateErasure({
+        id: stored.id,
+        streamId: (value.streamId as string | null) ?? null,
+        runId: (value.runId as string | null) ?? null,
+        eventType: (value.eventType as string | null) ?? null,
+        reason: value.reason as string,
+      });
+      await completeErasureJob(stored);
+    }
+  }
+
+  async function eraseWithPropagation(eventId: string, reason: string, actor: Principal): Promise<void> {
+    await resumeErasureJobs();
+    const target = await store.getEvent(eventId);
+    if (!target) throw new NotFoundError(`event ${eventId} not found`);
+    let job = await store.getRecord(ERASURES, eventId);
+    if (!job) {
+      await store.commit({
+        appends: [],
+        records: [{ collection: ERASURES, id: eventId, expectedVersion: 0, value: { status: "propagating", reason, actorId: actor.id, streamId: target.streamId, runId: target.runId, eventType: target.eventType, startedAt: new Date().toISOString() } }],
+      });
+      job = await store.getRecord(ERASURES, eventId);
+    }
+    if (!job) throw new Error(`erase: could not record the propagation job for ${eventId}`);
+    await propagateErasure({ id: eventId, streamId: target.streamId, runId: target.runId, eventType: target.eventType, reason });
+    await completeErasureJob(job);
+  }
+
+  await resumeErasureJobs();
+
   const timer = setInterval(kick, options.tickMs ?? 10);
   kick();
 
@@ -203,7 +320,7 @@ export async function startRuntime(options: RuntimeOptions): Promise<Runtime> {
     },
 
     async erase(eventId, reason, actor) {
-      await store.erasePayload(eventId, reason, actor.id);
+      await eraseWithPropagation(eventId, reason, actor);
     },
 
     pollApprovals,

package/src/service.ts

@@ -1,7 +1,7 @@
 // In-process RuntimeService (ADR-0011): authorization, tenancy, and typed errors over the durable core.
 import { randomUUID } from "node:crypto";
 import type { ContinuationRecord, TransitionOutcome } from "@godspeedai/cognate-continuations";
-import { ConcurrencyError, fingerprint, IdempotencyMismatchError, type Json, type StoredEvent } from "@godspeedai/cognate-events";
+import { ConcurrencyError, fingerprint, IdempotencyMismatchError, readProjectionSnapshot, type Json, type StoredEvent } from "@godspeedai/cognate-events";
 import { applyStateUpdate, type Caller, type ContinuationView, foldState, type ObservationInput, type ObservationView, type RunView, type RuntimeService, ServiceError, type ServiceErrorCode, StatePatchError } from "@godspeedai/cognate-runtime-api";
 import type { Core } from "./core.ts";
 import type { ActionName } from "./governed-operation.ts";
@@ -218,9 +218,15 @@ export function createService(core: Core, publicProjections: ReadonlySet<string>
     async readProjection(caller, request) {
       if (!publicProjections.has(request.name)) throw new ServiceError("not_found", `projection ${request.name} not found`);
       // Public projections are tenant-partitioned by key prefix `<tenant>/` (spec §32); an empty
-      // partition is [] so the caller cannot tell whether other tenants have data.
+      // partition is [] so the caller cannot tell whether other tenants have data. The checkpoint is
+      // read consistently with the rows (never ahead of them) so a client can tell whether its view
+      // covers the events it has observed (DEBT-021).
       const prefix = `${caller.tenant}/`;
-      return (await store.listProjection(request.name)).filter((e) => e.key.startsWith(prefix)).map((e) => ({ key: e.key.slice(prefix.length), value: e.value }));
+      const snapshot = await readProjectionSnapshot(store, request.name);
+      return {
+        rows: snapshot.rows.filter((e) => e.key.startsWith(prefix)).map((e) => ({ key: e.key.slice(prefix.length), value: e.value })),
+        checkpoint: snapshot.checkpoint ?? null,
+      };
     },
 
     async listRuns(caller, request) {