okengine 0.7.0 → 0.8.0

package/src/elements/clock/chaos-child.ts

@@ -4,48 +4,55 @@
  * Args:
  *   tick-loop <storePath> <instanceId> <fireLogPath> <leaseMs> [every]
  *   hold-lease <storePath> <instanceId> <markerPath> <leaseMs>
+ *   tick-loop-pg <databaseUrl> <instanceId> <fireLogPath> <leaseMs> [every]
+ *   hold-lease-pg <databaseUrl> <instanceId> <markerPath> <leaseMs>
  *   durable-mid-step <journalPath> <markerPath> <runIdPath>
+ *   journal-pg-start <databaseUrl> <instanceId> <stepLogPath> <markerPath> <leaseMs> <blockMs>
+ *   journal-pg-resume <databaseUrl> <instanceId> <stepLogPath> <donePath> <leaseMs>
+ *   journal-pg-park <databaseUrl> <instanceId> <stepLogPath> <parkedPath> <wakeMs>
+ *   journal-pg-claim <databaseUrl> <instanceId> <stepLogPath> <leaseMs>
  *
  * Modes:
- *   tick-loop         — reconcile + tick until this instance fires once, append fire log
- *   hold-lease        — acquire lease, write marker, hang (parent SIGKILLs)
- *   durable-mid-step  — journal step 1, write marker + runId, hang (parent SIGKILLs)
+ *   tick-loop / tick-loop-pg   — reconcile + tick until this instance fires once
+ *   hold-lease / hold-lease-pg — acquire lease, write marker, hang (parent SIGKILLs)
+ *   durable-mid-step           — journal step 1, write marker + runId, hang
+ *   journal-pg-start           — boot oke() app, start durable run over HTTP, hang (parent SIGKILLs)
+ *   journal-pg-resume          — boot oke() app; orphan sweep resumes the dead run; exit when done
+ *   journal-pg-park            — boot oke() app, park a durable sleep over HTTP, exit
+ *   journal-pg-claim           — boot oke() app; race claimDueSleep; exit 0 on own execution
  */
 
 import { join } from "node:path";
 
-import { flow } from "../../kernel/flow.ts";
+import { createPostgresCronStore } from "../../drivers/clock-postgres.ts";
+import { oke, type OkeApp } from "../../kernel/app.ts";
+import { flow, type AnyFlowDef } from "../../kernel/flow.ts";
 import { createFileJournalStore } from "../../kernel/journal.ts";
+import { on } from "../../kernel/on.ts";
+import { http } from "../../kernel/triggers.ts";
 import { clock } from "./declare.ts";
 import { runDurable } from "./durable.ts";
-import { createFileCronStore } from "./reconcile.ts";
+import { createFileCronStore, type CronStore } from "./reconcile.ts";
 import { createClockRuntime } from "./runtime.ts";
 
 const mode = process.argv[2];
 
 if (!mode) {
-  console.error("usage: chaos-child <tick-loop|hold-lease|durable-mid-step> …");
+  console.error(
+    "usage: chaos-child <tick-loop|hold-lease|tick-loop-pg|hold-lease-pg|durable-mid-step> …",
+  );
   process.exit(2);
 }
 
 const CRON_NAME = "chaos-job";
 
-if (mode === "tick-loop") {
-  const storePath = process.argv[3];
-  const instanceId = process.argv[4];
-  const fireLogPath = process.argv[5];
-  const leaseMs = Number(process.argv[6] ?? 100);
-  // Default 1h so a second process cannot become due again within the test window
-  // after the winner sets lastRunAt (proves one fire per tick, not one per lease).
-  const every = process.argv[7] ?? "1h";
-  if (!storePath || !instanceId || !fireLogPath) {
-    console.error(
-      "usage: chaos-child tick-loop <storePath> <instanceId> <fireLogPath> <leaseMs> [every]",
-    );
-    process.exit(2);
-  }
-
-  const store = createFileCronStore(join(storePath));
+async function runTickLoop(
+  store: CronStore,
+  instanceId: string,
+  fireLogPath: string,
+  leaseMs: number,
+  every: string,
+) {
   const rt = createClockRuntime({
     instanceId,
     store,
@@ -69,17 +76,12 @@ if (mode === "tick-loop") {
   process.exit(3);
 }
 
-if (mode === "hold-lease") {
-  const storePath = process.argv[3];
-  const instanceId = process.argv[4];
-  const markerPath = process.argv[5];
-  const leaseMs = Number(process.argv[6] ?? 100);
-  if (!storePath || !instanceId || !markerPath) {
-    console.error("usage: chaos-child hold-lease <storePath> <instanceId> <markerPath> <leaseMs>");
-    process.exit(2);
-  }
-
-  const store = createFileCronStore(join(storePath));
+async function runHoldLease(
+  store: CronStore,
+  instanceId: string,
+  markerPath: string,
+  leaseMs: number,
+) {
   const rt = createClockRuntime({
     instanceId,
     store,
@@ -88,7 +90,6 @@ if (mode === "hold-lease") {
   rt.register(clock(CRON_NAME, { every: "50ms" }));
   await rt.reconcile();
 
-  // Fire once so lastRunAt + lease are set (this instance is leader).
   rt.onCron(CRON_NAME, () => {});
   const ok = await rt.runNow(CRON_NAME);
   if (!ok) {
@@ -104,12 +105,61 @@ if (mode === "hold-lease") {
       leaderLeaseUntil: row?.leaderLeaseUntil,
     }),
   );
-  // Hang while holding the lease — parent will SIGKILL.
   await Bun.sleep(60_000);
   process.exit(0);
 }
 
-if (mode === "durable-mid-step") {
+if (mode === "tick-loop") {
+  const storePath = process.argv[3];
+  const instanceId = process.argv[4];
+  const fireLogPath = process.argv[5];
+  const leaseMs = Number(process.argv[6] ?? 100);
+  const every = process.argv[7] ?? "1h";
+  if (!storePath || !instanceId || !fireLogPath) {
+    console.error(
+      "usage: chaos-child tick-loop <storePath> <instanceId> <fireLogPath> <leaseMs> [every]",
+    );
+    process.exit(2);
+  }
+  await runTickLoop(createFileCronStore(join(storePath)), instanceId, fireLogPath, leaseMs, every);
+} else if (mode === "hold-lease") {
+  const storePath = process.argv[3];
+  const instanceId = process.argv[4];
+  const markerPath = process.argv[5];
+  const leaseMs = Number(process.argv[6] ?? 100);
+  if (!storePath || !instanceId || !markerPath) {
+    console.error("usage: chaos-child hold-lease <storePath> <instanceId> <markerPath> <leaseMs>");
+    process.exit(2);
+  }
+  await runHoldLease(createFileCronStore(join(storePath)), instanceId, markerPath, leaseMs);
+} else if (mode === "tick-loop-pg") {
+  const databaseUrl = process.argv[3];
+  const instanceId = process.argv[4];
+  const fireLogPath = process.argv[5];
+  const leaseMs = Number(process.argv[6] ?? 100);
+  const every = process.argv[7] ?? "1h";
+  if (!databaseUrl || !instanceId || !fireLogPath) {
+    console.error(
+      "usage: chaos-child tick-loop-pg <databaseUrl> <instanceId> <fireLogPath> <leaseMs> [every]",
+    );
+    process.exit(2);
+  }
+  const store = await createPostgresCronStore({ url: databaseUrl });
+  await runTickLoop(store, instanceId, fireLogPath, leaseMs, every);
+} else if (mode === "hold-lease-pg") {
+  const databaseUrl = process.argv[3];
+  const instanceId = process.argv[4];
+  const markerPath = process.argv[5];
+  const leaseMs = Number(process.argv[6] ?? 100);
+  if (!databaseUrl || !instanceId || !markerPath) {
+    console.error(
+      "usage: chaos-child hold-lease-pg <databaseUrl> <instanceId> <markerPath> <leaseMs>",
+    );
+    process.exit(2);
+  }
+  const store = await createPostgresCronStore({ url: databaseUrl });
+  await runHoldLease(store, instanceId, markerPath, leaseMs);
+} else if (mode === "durable-mid-step") {
   const journalPath = process.argv[3];
   const markerPath = process.argv[4];
   const runIdPath = process.argv[5];
@@ -124,14 +174,12 @@ if (mode === "durable-mid-step") {
     durable: true,
     do: async (_input, fx) => {
       const intent = await fx.step("create-intent", async () => {
-        // Persist run id as soon as the step body runs (session already started).
         const runs = await journalStore.list();
         const run = runs[0];
         if (run) await Bun.write(runIdPath, run.id);
         await Bun.write(markerPath, "step1");
         return { id: "pi_chaos" };
       });
-      // Hang after journaling step 1 — parent SIGKILLs before confirm.
       await Bun.sleep(60_000);
       return fx.step("confirm", () => intent.id === "pi_chaos");
     },
@@ -142,9 +190,200 @@ if (mode === "durable-mid-step") {
     input: { orderId: "o-chaos" },
     journalStore,
   });
-  // Unreachable under SIGKILL.
   process.exit(0);
+} else if (mode === "journal-pg-start") {
+  const [databaseUrl, instanceId, stepLogPath, markerPath] = process.argv.slice(3);
+  const leaseMs = Number(process.argv[7] ?? 300);
+  const blockMs = Number(process.argv[8] ?? 60_000);
+  if (!databaseUrl || !instanceId || !stepLogPath || !markerPath) {
+    console.error(
+      "usage: chaos-child journal-pg-start <databaseUrl> <instanceId> <stepLogPath> <markerPath> <leaseMs> <blockMs>",
+    );
+    process.exit(2);
+  }
+  const app = await bootJournalPgApp({
+    url: databaseUrl!,
+    instanceId: instanceId!,
+    leaseMs,
+    flow: chargeFlow(instanceId!, stepLogPath!, blockMs),
+  });
+  void app.fetch(new Request("http://localhost/charge", { method: "POST", body: "{}" }));
+  // Marker once step 1 is journaled — then hang; the parent SIGKILLs mid-run.
+  const deadline = Date.now() + 15_000;
+  for (;;) {
+    const row = (await app.bootResult!.journal!.store.list())[0];
+    if (row && row.entries.length >= 1) {
+      await Bun.write(markerPath!, JSON.stringify({ runId: row.id, instanceId }));
+      break;
+    }
+    if (Date.now() > deadline) {
+      console.error("journal-pg-start: step 1 never journaled");
+      process.exit(3);
+    }
+    await Bun.sleep(10);
+  }
+  await Bun.sleep(3_600_000);
+  process.exit(0);
+} else if (mode === "journal-pg-resume") {
+  const [databaseUrl, instanceId, stepLogPath, donePath] = process.argv.slice(3);
+  const leaseMs = Number(process.argv[7] ?? 300);
+  if (!databaseUrl || !instanceId || !stepLogPath || !donePath) {
+    console.error(
+      "usage: chaos-child journal-pg-resume <databaseUrl> <instanceId> <stepLogPath> <donePath> <leaseMs>",
+    );
+    process.exit(2);
+  }
+  // No fetch — the boot orphan scan / resume sweep must discover the dead run.
+  const app = await bootJournalPgApp({
+    url: databaseUrl!,
+    instanceId: instanceId!,
+    leaseMs,
+    flow: chargeFlow(instanceId!, stepLogPath!, 0),
+  });
+  const deadline = Date.now() + 20_000;
+  for (;;) {
+    await app.resumeDurable();
+    const row = (await app.bootResult!.journal!.store.list())[0];
+    if (row?.status === "completed") {
+      await Bun.write(donePath!, JSON.stringify({ runId: row.id, completedBy: instanceId }));
+      process.exit(0);
+    }
+    if (Date.now() > deadline) {
+      console.error("journal-pg-resume: orphan never resumed");
+      process.exit(3);
+    }
+    await Bun.sleep(25);
+  }
+} else if (mode === "journal-pg-park") {
+  const [databaseUrl, instanceId, stepLogPath, parkedPath] = process.argv.slice(3);
+  const wakeMs = Number(process.argv[7] ?? 400);
+  if (!databaseUrl || !instanceId || !stepLogPath || !parkedPath) {
+    console.error(
+      "usage: chaos-child journal-pg-park <databaseUrl> <instanceId> <stepLogPath> <parkedPath> <wakeMs>",
+    );
+    process.exit(2);
+  }
+  const app = await bootJournalPgApp({
+    url: databaseUrl!,
+    instanceId: instanceId!,
+    leaseMs: 30_000,
+    flow: sleeperFlow(instanceId!, stepLogPath!, wakeMs),
+  });
+  const res = await app.fetch(
+    new Request("http://localhost/sleep", { method: "POST", body: "{}" }),
+  );
+  if (res.status !== 204) {
+    console.error(`journal-pg-park: expected 204 park, got ${res.status}`);
+    process.exit(3);
+  }
+  const row = (await app.bootResult!.journal!.store.list())[0];
+  await Bun.write(parkedPath!, JSON.stringify({ runId: row?.id, instanceId }));
+  process.exit(0);
+} else if (mode === "journal-pg-claim") {
+  const [databaseUrl, instanceId, stepLogPath] = process.argv.slice(3);
+  const leaseMs = Number(process.argv[6] ?? 300);
+  if (!databaseUrl || !instanceId || !stepLogPath) {
+    console.error(
+      "usage: chaos-child journal-pg-claim <databaseUrl> <instanceId> <stepLogPath> <leaseMs>",
+    );
+    process.exit(2);
+  }
+  const app = await bootJournalPgApp({
+    url: databaseUrl!,
+    instanceId: instanceId!,
+    leaseMs,
+    flow: sleeperFlow(instanceId!, stepLogPath!, 400),
+  });
+  const deadline = Date.now() + 15_000;
+  for (;;) {
+    await app.resumeDurable();
+    if (await logHasStep(stepLogPath!, "confirm", instanceId!)) process.exit(0);
+    const row = (await app.bootResult!.journal!.store.list())[0];
+    if (row?.status === "completed") process.exit(3); // someone else claimed it
+    if (Date.now() > deadline) process.exit(3);
+    await Bun.sleep(25);
+  }
+} else {
+  console.error(`unknown mode: ${mode}`);
+  process.exit(2);
+}
+
+/** Append one JSON line to the shared step log. */
+async function appendStepLog(
+  path: string,
+  entry: { instanceId: string; step: string; at: number },
+): Promise<void> {
+  const prev = (await Bun.file(path).exists()) ? await Bun.file(path).text() : "";
+  await Bun.write(path, `${prev}${JSON.stringify(entry)}\n`);
+}
+
+/** True when the step log holds `step` executed by `instanceId`. */
+async function logHasStep(path: string, step: string, instanceId: string): Promise<boolean> {
+  if (!(await Bun.file(path).exists())) return false;
+  const lines = (await Bun.file(path).text()).trim().split("\n").filter(Boolean);
+  return lines.some((l) => {
+    const e = JSON.parse(l) as { instanceId: string; step: string };
+    return e.step === step && e.instanceId === instanceId;
+  });
+}
+
+/** Durable charge flow: step 1 → block → step 2 (both logged). */
+function chargeFlow(instanceId: string, stepLogPath: string, blockMs: number): AnyFlowDef {
+  return flow({
+    name: "chaos.journal.charge",
+    durable: true,
+    do: async (_input, fx) => {
+      const intent = await fx.step("create-intent", async () => {
+        await appendStepLog(stepLogPath, { instanceId, step: "create-intent", at: Date.now() });
+        return { id: "pi_chaos" };
+      });
+      if (blockMs > 0) await Bun.sleep(blockMs);
+      await fx.step("mid-flight", async () => {
+        await appendStepLog(stepLogPath, { instanceId, step: "mid-flight", at: Date.now() });
+        return intent.id === "pi_chaos";
+      });
+      return { ok: true };
+    },
+  });
+}
+
+/** Durable sleeper flow: step 1 → sleep → confirm (steps logged). */
+function sleeperFlow(instanceId: string, stepLogPath: string, wakeMs: number): AnyFlowDef {
+  return flow({
+    name: "chaos.journal.sleeper",
+    durable: true,
+    do: async (_input, fx) => {
+      await fx.step("create-intent", async () => {
+        await appendStepLog(stepLogPath, { instanceId, step: "create-intent", at: Date.now() });
+        return { id: "pi_chaos" };
+      });
+      await fx.clock.sleep("verify-window", `${wakeMs}ms`);
+      await fx.step("confirm", async () => {
+        await appendStepLog(stepLogPath, { instanceId, step: "confirm", at: Date.now() });
+        return true;
+      });
+      return { ok: true };
+    },
+  });
 }
 
-console.error(`unknown mode: ${mode}`);
-process.exit(2);
+/** Boot a real `oke()` app against live postgres (drivers.journal). */
+async function bootJournalPgApp(options: {
+  readonly url: string;
+  readonly instanceId: string;
+  readonly leaseMs: number;
+  readonly flow: AnyFlowDef;
+}): Promise<OkeApp> {
+  process.env.DATABASE_URL = options.url;
+  on(http.post("/charge"), options.flow);
+  on(http.post("/sleep"), options.flow);
+  const app = oke({
+    name: `chaos-journal-${options.instanceId}`,
+    env: "test",
+    startScheduler: false,
+    gate: { unguardedHttp: "allow" },
+    config: { drivers: { journal: { test: "postgres" } } },
+  });
+  await app.boot({ instanceId: options.instanceId, journalLeaseMs: options.leaseMs });
+  return app;
+}

package/src/elements/clock/durable.ts

@@ -13,6 +13,7 @@ import {
   createJournal,
   isJournalSuspend,
   type Journal,
+  type JournalLeaseOptions,
   type JournalSession,
   type JournalStore,
 } from "../../kernel/journal.ts";
@@ -45,6 +46,11 @@ export interface RunDurableOptions {
   readonly journalStore: JournalStore;
   /** Resume an existing run id (crash recovery). */
   readonly runId?: string;
+  /**
+   * Run-level lease (SKIP LOCKED + lazy reclaim when the store supports it).
+   * Resume throws `JournalLeaseBusy` when another live instance holds the run.
+   */
+  readonly lease?: JournalLeaseOptions;
   /** Injectable clock. */
   readonly now?: () => number;
   /** Extra fx options (secrets, store runtime, …). */
@@ -63,6 +69,7 @@ export async function runDurable<O = unknown>(
   const journal: Journal = createJournal({
     store: options.journalStore,
     now,
+    ...(options.lease ? { lease: options.lease } : {}),
   });
 
   if (options.runId) {

package/src/elements/clock/reconcile.ts

@@ -52,8 +52,8 @@ export interface CronRow {
 
 /** Store surface for reconciled crons. */
 export interface CronStore {
-  /** Backing kind when known (`memory` · `file`). */
-  readonly kind?: "memory" | "file";
+  /** Backing kind when known (`memory` · `file` · `postgres`). */
+  readonly kind?: "memory" | "file" | "postgres";
   /**
    * @param name - Cron name
    */

package/src/elements/clock/runtime.ts

@@ -44,9 +44,9 @@ export interface CreateClockRuntimeOptions {
 export interface ClockRuntime {
   /**
    * Effective driver id selected at construction
-   * (`memory` · `file` · `frozen`).
+   * (`memory` · `file` · `postgres` · `frozen`).
    */
-  readonly driverId: "memory" | "file" | "frozen";
+  readonly driverId: "memory" | "file" | "postgres" | "frozen";
   /** Instance id used for leases. */
   readonly instanceId: string;
   /** Cron store the scheduler reads. */
@@ -116,7 +116,9 @@ export function createClockRuntime(options: CreateClockRuntimeOptions = {}): Clo
     ? "frozen"
     : store.kind === "file"
       ? "file"
-      : "memory";
+      : store.kind === "postgres"
+        ? "postgres"
+        : "memory";
 
   async function fire(name: string): Promise<boolean> {
     const row = await store.get(name);

package/src/elements/clock.ts

@@ -2,7 +2,7 @@
  * Clock element — time.
  *
  * Physics: cron · delay · timeout · durable sleep · TTL.
- * Drivers (protocol-named): `memory` · `postgres`.
+ * Drivers (protocol-named): `memory` · `postgres` · `file` · `frozen`.
  *
  * Durability lives on the Flow (`durable: true`); the journal records every
  * `fx` call. Crons leader-elect; schedules are reconciled into the Store at

package/src/elements/store/seed.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, test } from "bun:test";
+import { defineSeed, normalizeSeedFns, resolveSeedCategory, type SeedFn } from "./seed.ts";
+
+describe("defineSeed / resolveSeedCategory", () => {
+  test("defineSeed returns the same def", () => {
+    const fn: SeedFn = async () => {};
+    const def = defineSeed({ essential: fn, dev: [fn], prod: fn });
+    expect(def.essential).toBe(fn);
+    expect(def.dev).toEqual([fn]);
+    expect(def.prod).toBe(fn);
+  });
+
+  test("normalizeSeedFns preserves array order", () => {
+    const a: SeedFn = async () => {};
+    const b: SeedFn = async () => {};
+    expect(normalizeSeedFns([a, b])).toEqual([a, b]);
+    expect(normalizeSeedFns(a)).toEqual([a]);
+    expect(normalizeSeedFns()).toEqual([]);
+  });
+
+  test("resolveSeedCategory matches the env matrix", () => {
+    expect(resolveSeedCategory("local")).toBe("dev");
+    expect(resolveSeedCategory("docker")).toBe("dev");
+    expect(resolveSeedCategory("prod")).toBe("prod");
+    expect(resolveSeedCategory("test")).toBe(null);
+  });
+});

package/src/elements/store/seed.ts

@@ -0,0 +1,68 @@
+/**
+ * Database seed declarations — `defineSeed({ essential, dev, prod })`.
+ *
+ * Seed never runs at boot; only via `oke db seed`.
+ */
+
+import type { ConfigEnv } from "../../config/index.ts";
+import type { Fx } from "../../kernel/fx.ts";
+
+/** One seed function — receives a privileged `fx` with store access. */
+export type SeedFn = (fx: Fx) => Promise<void>;
+
+/** Single function or ordered array (array order is execution order). */
+export type SeedFns = SeedFn | readonly SeedFn[];
+
+/**
+ * Seed categories for {@link defineSeed}.
+ *
+ * - `essential` — every environment, always
+ * - `dev` — `local` or `docker` only
+ * - `prod` — `prod` only
+ */
+export interface SeedDef {
+  readonly essential?: SeedFns;
+  readonly dev?: SeedFns;
+  readonly prod?: SeedFns;
+}
+
+/** Env-selected category that runs alongside `essential` (or neither). */
+export type SeedCategory = "dev" | "prod";
+
+/**
+ * Freeze a seed declaration for `src/seed/index.ts` default export.
+ *
+ * @param def - Essential / dev / prod function bags
+ */
+export function defineSeed(def: SeedDef): SeedDef {
+  return def;
+}
+
+/**
+ * Normalize a seed key to an ordered function list.
+ *
+ * @param fns - Single function, array, or omitted
+ */
+export function normalizeSeedFns(fns?: SeedFns): SeedFn[] {
+  if (fns === undefined) return [];
+  if (typeof fns === "function") return [fns];
+  return [...fns];
+}
+
+/**
+ * Which optional category runs for `env` (single source of truth).
+ *
+ * | env    | category |
+ * | ------ | -------- |
+ * | local  | dev      |
+ * | docker | dev      |
+ * | test   | (none)   |
+ * | prod   | prod     |
+ *
+ * @param env - Resolved {@link ConfigEnv}
+ */
+export function resolveSeedCategory(env: ConfigEnv): SeedCategory | null {
+  if (env === "local" || env === "docker") return "dev";
+  if (env === "prod") return "prod";
+  return null;
+}

package/src/elements/store/sql-session.test.ts

@@ -56,6 +56,7 @@ describe("SqlStoreHandle — no relational query surface (path b)", () => {
         "findById",
         "delete",
         "exists",
+        "upsert",
         "increment",
         "raw",
         "count",
@@ -133,3 +134,41 @@ describe("SqlStoreHandle — orderBy / limit select chain", () => {
     await conn.close();
   });
 });
+
+describe("SqlStoreHandle — upsert", () => {
+  test("default inserts once then already-existed without touching the row", async () => {
+    const { handle, conn } = await openHandle();
+    const first = await handle.upsert(
+      posts,
+      { id: "welcome" },
+      { id: "welcome", title: "Hello", createdAt: 1 },
+    );
+    expect(first.status).toBe("upserted");
+
+    const second = await handle.upsert(
+      posts,
+      { id: "welcome" },
+      { id: "welcome", title: "Changed", createdAt: 2 },
+    );
+    expect(second.status).toBe("already-existed");
+
+    const row = await handle.findById(posts, "welcome");
+    expect(row).toEqual({ id: "welcome", title: "Hello", createdAt: 1 });
+    await conn.close();
+  });
+
+  test("onExisting update changes matched columns", async () => {
+    const { handle, conn } = await openHandle();
+    await handle.upsert(posts, { id: "n1" }, { id: "n1", title: "one", createdAt: 10 });
+    const updated = await handle.upsert(
+      posts,
+      { id: "n1" },
+      { id: "n1", title: "two", createdAt: 20 },
+      { onExisting: "update" },
+    );
+    expect(updated.status).toBe("changed");
+    const row = await handle.findById(posts, "n1");
+    expect(row).toEqual({ id: "n1", title: "two", createdAt: 20 });
+    await conn.close();
+  });
+});

package/src/elements/store/sql-session.ts

@@ -237,6 +237,21 @@ export interface SqlStoreHandle {
    * @param idOrWhere - Primary key string, or column equality map
    */
   exists(table: TableHandle | unknown, idOrWhere: string | WhereMap): Promise<boolean>;
+  /**
+   * Insert when no row matches `matchOn`; never touches an existing match
+   * unless `options.onExisting` is `"update"`.
+   *
+   * @param table - Table
+   * @param matchOn - Equality map or Drizzle condition identifying the row
+   * @param values - Row values for insert (and optional update)
+   * @param options - Per-call opt-in to update an existing match
+   */
+  upsert(
+    table: TableHandle | unknown,
+    matchOn: WhereMap | unknown,
+    values: SqlRow,
+    options?: { readonly onExisting?: "update" },
+  ): Promise<UpsertResult>;
   /**
    * Atomically add `by` to `column` on the PK row.
    *
@@ -276,6 +291,14 @@ export interface SqlStoreHandle {
   ensureTable(table: TableHandle): Promise<void>;
 }
 
+/** Outcome of {@link SqlStoreHandle.upsert}. */
+export type UpsertStatus = "upserted" | "changed" | "already-existed";
+
+/** Result envelope for {@link SqlStoreHandle.upsert}. */
+export interface UpsertResult {
+  readonly status: UpsertStatus;
+}
+
 /** Options for {@link SqlStoreHandle.page}. */
 export interface SqlPageOptions {
   /** Filter condition (equality map or Drizzle SQL). */
@@ -617,6 +640,38 @@ export function createSqlStoreHandle(
       return rows.length > 0;
     },
 
+    async upsert(table, matchOn, values, upsertOptions) {
+      await ensureFromMeta(table);
+      const name = resolveTableName(table);
+      const compiled = compileTableWhere(table, matchOn);
+      if (!compiled.clause) {
+        throw new Error("upsert() requires at least one matchOn predicate");
+      }
+      const found = await query(
+        `SELECT 1 AS "ok" FROM ${quoteIdent(name)} WHERE ${compiled.clause} LIMIT 1`,
+        compiled.params,
+      );
+      if (found.length === 0) {
+        const prepared = prepareInsertRow(table, values);
+        const cols = Object.keys(prepared);
+        const placeholders = cols.map(() => "?").join(", ");
+        const colList = cols.map(quoteIdent).join(", ");
+        const params = cols.map((c) => prepared[c]);
+        await exec(`INSERT INTO ${quoteIdent(name)} (${colList}) VALUES (${placeholders})`, params);
+        return { status: "upserted" as const };
+      }
+      if (upsertOptions?.onExisting !== "update") {
+        return { status: "already-existed" as const };
+      }
+      const prepared = prepareUpdateRow(table, values);
+      const setEntries = Object.entries(prepared);
+      if (setEntries.length === 0) return { status: "changed" as const };
+      const setSql = setEntries.map(([col]) => `${quoteIdent(col)} = ?`).join(", ");
+      const params = [...setEntries.map(([, v]) => v), ...compiled.params];
+      await exec(`UPDATE ${quoteIdent(name)} SET ${setSql} WHERE ${compiled.clause}`, params);
+      return { status: "changed" as const };
+    },
+
     async increment(table, idValue, column, by = 1) {
       await ensureFromMeta(table);
       const name = resolveTableName(table);