@nanobpm/agentic 0.1.0 → 0.4.0

package/src/session/events.ts

@@ -0,0 +1,347 @@
+/**
+ * The canonical `SessionEvent` model — ADR 0062, slice 1 (the shared contract).
+ *
+ * This is **Nano's own** agent-session event model: the single schema every
+ * harness dialect (ACP, stream-json, a native normalizer, …) normalizes *into*.
+ * We never adopt an external harness schema as ours — those are ingestion
+ * details owned by the later slices; this union is the stable interface they all
+ * target.
+ *
+ * ## The causal chain
+ *
+ * A session is an append-only log of events. Two orthogonal orderings make the
+ * log both replayable and mergeable:
+ *
+ *  - a **monotonic, gap-free `offset`** assigned by the authoritative log on
+ *    append (see {@link AppendedSessionEvent}); it is the resume coordinate —
+ *    `restore` hands back everything up to a checkpoint offset.
+ *  - a **causal `parentId`** the producer stamps: the id of the event this one
+ *    logically follows (`null` for the first event of a session). Offset gives a
+ *    total order for replay; `parentId` records the *causal* edge, which survives
+ *    a compaction that rewrites offsets.
+ *
+ * The producer owns identity (`id`) and causality (`parentId`); the log owns
+ * ordering (`offset`) and fencing (`incarnation`). Keeping those responsibilities
+ * split is what lets a resumed incarnation continue the same causal chain at a
+ * fresh offset without the producer knowing the log's internal cursor.
+ */
+
+/** Discriminates a {@link SessionEvent}. One member per row in the union below. */
+export type SessionEventType =
+  | "system"
+  | "user"
+  | "assistant"
+  | "reasoning"
+  | "tool-call"
+  | "tool-result"
+  | "compaction"
+  | "usage"
+  | "turn-start"
+  | "turn-end";
+
+/** The set of valid event types, for a runtime membership check at the DB boundary. */
+export const SESSION_EVENT_TYPES: readonly SessionEventType[] = [
+  "system",
+  "user",
+  "assistant",
+  "reasoning",
+  "tool-call",
+  "tool-result",
+  "compaction",
+  "usage",
+  "turn-start",
+  "turn-end",
+];
+
+/**
+ * The fields every event carries regardless of type. `offset` is deliberately
+ * absent — the producer does not assign it; the authoritative log does, yielding
+ * an {@link AppendedSessionEvent}.
+ */
+export interface SessionEventEnvelope {
+  /** Producer-assigned unique id for this event (the causal-chain node id). */
+  readonly id: string;
+  /** The id of the causal predecessor, or `null` for the first event of a session. */
+  readonly parentId: string | null;
+}
+
+/** A system/instruction message (the harness/system prompt turn). */
+export interface SystemMessageEvent extends SessionEventEnvelope {
+  readonly type: "system";
+  readonly text: string;
+}
+
+/** A user message. */
+export interface UserMessageEvent extends SessionEventEnvelope {
+  readonly type: "user";
+  readonly text: string;
+}
+
+/** An assistant (model) message — the visible answer text. */
+export interface AssistantMessageEvent extends SessionEventEnvelope {
+  readonly type: "assistant";
+  readonly text: string;
+}
+
+/**
+ * Assistant reasoning (chain-of-thought / thinking) for a turn.
+ *
+ * `text` is the human-readable reasoning summary when the provider exposes one.
+ * `providerContinuation` is an **opaque provider reasoning-continuation blob**:
+ * some providers (e.g. encrypted reasoning tokens) return a handle that must be
+ * fed back verbatim to continue reasoning across a resume. Nano never parses,
+ * validates, or transforms it — it stores and replays it as an opaque string so
+ * a re-leased incarnation can resume the model's reasoning exactly.
+ */
+export interface ReasoningEvent extends SessionEventEnvelope {
+  readonly type: "reasoning";
+  readonly text?: string;
+  readonly providerContinuation?: string;
+}
+
+/** A tool/function call the assistant requested. */
+export interface ToolCallEvent extends SessionEventEnvelope {
+  readonly type: "tool-call";
+  /** Correlates this call with its {@link ToolResultEvent}. */
+  readonly callId: string;
+  readonly name: string;
+  /** The call arguments, as an opaque JSON-serialisable value. */
+  readonly args: unknown;
+}
+
+/** The result of a previously-emitted {@link ToolCallEvent}. */
+export interface ToolResultEvent extends SessionEventEnvelope {
+  readonly type: "tool-result";
+  /** Matches the originating {@link ToolCallEvent.callId}. */
+  readonly callId: string;
+  /** `false` when the tool failed; the failure detail lives in `result`. */
+  readonly ok: boolean;
+  /** The tool output, as an opaque JSON-serialisable value. */
+  readonly result: unknown;
+}
+
+/**
+ * A compaction or truncation boundary: the events in the (inclusive-exclusive)
+ * offset range `[replacesFrom, replacesTo)` were summarised/dropped to bound
+ * context growth. `summary` is the replacement text (present for compaction,
+ * typically absent for a hard truncation). The original events keep their
+ * offsets in the authoritative log; this marker records that a *replay* should
+ * fold that range into the summary rather than replaying it verbatim.
+ */
+export interface CompactionEvent extends SessionEventEnvelope {
+  readonly type: "compaction";
+  readonly reason: "compaction" | "truncation";
+  readonly replacesFrom: number;
+  readonly replacesTo: number;
+  readonly summary?: string;
+}
+
+/** A usage/accounting record for a turn (token counts, etc.). */
+export interface UsageEvent extends SessionEventEnvelope {
+  readonly type: "usage";
+  readonly inputTokens: number;
+  readonly outputTokens: number;
+  /** Optional provider model identifier the usage is attributed to. */
+  readonly model?: string;
+}
+
+/** The start of a turn (a request/response cycle). `turn` is a monotonic index. */
+export interface TurnStartEvent extends SessionEventEnvelope {
+  readonly type: "turn-start";
+  readonly turn: number;
+}
+
+/** The end of a turn matching a prior {@link TurnStartEvent}. */
+export interface TurnEndEvent extends SessionEventEnvelope {
+  readonly type: "turn-end";
+  readonly turn: number;
+}
+
+/**
+ * The canonical session event — a discriminated union over {@link SessionEventType}.
+ * Every harness dialect normalises into exactly this shape.
+ */
+export type SessionEvent =
+  | SystemMessageEvent
+  | UserMessageEvent
+  | AssistantMessageEvent
+  | ReasoningEvent
+  | ToolCallEvent
+  | ToolResultEvent
+  | CompactionEvent
+  | UsageEvent
+  | TurnStartEvent
+  | TurnEndEvent;
+
+/**
+ * A {@link SessionEvent} after the authoritative log has appended it: the same
+ * event plus the log-assigned `offset` (its monotonic resume coordinate) and the
+ * `incarnation` (the generation of the writer that produced it — the fencing
+ * stamp). This is what {@link restore} replays as the mind seed.
+ */
+export type AppendedSessionEvent = SessionEvent & {
+  readonly offset: number;
+  readonly incarnation: number;
+};
+
+/** Raised when a value read back from storage is not a well-formed session event. */
+export class SessionEventShapeError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "SessionEventShapeError";
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function reqString(obj: Record<string, unknown>, field: string): string {
+  const v = obj[field];
+  if (typeof v !== "string") {
+    throw new SessionEventShapeError(`session event field "${field}" must be a string, got ${typeof v}`);
+  }
+  return v;
+}
+
+function optString(obj: Record<string, unknown>, field: string): string | undefined {
+  const v = obj[field];
+  if (v === undefined) return undefined;
+  if (typeof v !== "string") {
+    throw new SessionEventShapeError(`session event field "${field}" must be a string when present, got ${typeof v}`);
+  }
+  return v;
+}
+
+function reqNonNegInt(obj: Record<string, unknown>, field: string): number {
+  const v = obj[field];
+  if (typeof v !== "number" || !Number.isSafeInteger(v) || v < 0) {
+    throw new SessionEventShapeError(
+      `session event field "${field}" must be a non-negative safe integer, got ${String(v)}`,
+    );
+  }
+  return v;
+}
+
+function reqBool(obj: Record<string, unknown>, field: string): boolean {
+  const v = obj[field];
+  if (typeof v !== "boolean") {
+    throw new SessionEventShapeError(`session event field "${field}" must be a boolean, got ${typeof v}`);
+  }
+  return v;
+}
+
+function parentId(obj: Record<string, unknown>): string | null {
+  const v = obj.parentId;
+  if (v === null) return null;
+  if (typeof v === "string") return v;
+  throw new SessionEventShapeError(`session event "parentId" must be a string or null, got ${typeof v}`);
+}
+
+/**
+ * Coerce a required opaque payload (a tool-call `args` / tool-result `result`) to
+ * a JSON-serialisable value. These fields are documented as opaque *JSON-
+ * serialisable* values, but a dialect can legitimately omit them (e.g. a tool
+ * call with no arguments surfaces as `obj.arguments ?? obj.args === undefined`).
+ * `undefined` is not JSON-serialisable — `JSON.stringify` drops the key — so an
+ * un-normalised `undefined` would persist an event that no longer round-trips to
+ * the same shape on replay. We normalise the absence to the canonical JSON "no
+ * value" (`null`) here, at the single boundary every dialect flows through, so
+ * they all get the same replay-stable guarantee (derivation over duplication).
+ */
+function opaquePayload(value: unknown): unknown {
+  return value === undefined ? null : value;
+}
+
+/**
+ * Parse and validate an untyped value (e.g. `JSON.parse` of a stored row) into a
+ * {@link SessionEvent}, reconstructing the exact union member for its `type`.
+ * Throws {@link SessionEventShapeError} on any malformed field. This is the
+ * single trusted boundary between untyped storage and the typed union — it never
+ * uses an `as`-cast to fabricate a shape (see AGENTS.md), it *builds* one field
+ * by field, so a corrupt row fails loudly instead of masquerading as valid.
+ */
+export function parseSessionEvent(value: unknown): SessionEvent {
+  if (!isRecord(value)) {
+    throw new SessionEventShapeError(`session event must be an object, got ${typeof value}`);
+  }
+  const id = reqString(value, "id");
+  const parent = parentId(value);
+  const type = value.type;
+  switch (type) {
+    case "system":
+      return { type, id, parentId: parent, text: reqString(value, "text") };
+    case "user":
+      return { type, id, parentId: parent, text: reqString(value, "text") };
+    case "assistant":
+      return { type, id, parentId: parent, text: reqString(value, "text") };
+    case "reasoning": {
+      const event: ReasoningEvent = { type, id, parentId: parent };
+      const text = optString(value, "text");
+      const cont = optString(value, "providerContinuation");
+      return {
+        ...event,
+        ...(text !== undefined ? { text } : {}),
+        ...(cont !== undefined ? { providerContinuation: cont } : {}),
+      };
+    }
+    case "tool-call":
+      return {
+        type,
+        id,
+        parentId: parent,
+        callId: reqString(value, "callId"),
+        name: reqString(value, "name"),
+        args: opaquePayload(value.args),
+      };
+    case "tool-result":
+      return {
+        type,
+        id,
+        parentId: parent,
+        callId: reqString(value, "callId"),
+        ok: reqBool(value, "ok"),
+        result: opaquePayload(value.result),
+      };
+    case "compaction": {
+      const reason = value.reason;
+      if (reason !== "compaction" && reason !== "truncation") {
+        throw new SessionEventShapeError(`compaction "reason" must be "compaction" or "truncation", got ${String(reason)}`);
+      }
+      const summary = optString(value, "summary");
+      const replacesFrom = reqNonNegInt(value, "replacesFrom");
+      const replacesTo = reqNonNegInt(value, "replacesTo");
+      if (replacesTo < replacesFrom) {
+        throw new SessionEventShapeError(
+          `compaction "replacesTo" (${replacesTo}) must be >= "replacesFrom" (${replacesFrom})`,
+        );
+      }
+      return {
+        type,
+        id,
+        parentId: parent,
+        reason,
+        replacesFrom,
+        replacesTo,
+        ...(summary !== undefined ? { summary } : {}),
+      };
+    }
+    case "usage": {
+      const model = optString(value, "model");
+      return {
+        type,
+        id,
+        parentId: parent,
+        inputTokens: reqNonNegInt(value, "inputTokens"),
+        outputTokens: reqNonNegInt(value, "outputTokens"),
+        ...(model !== undefined ? { model } : {}),
+      };
+    }
+    case "turn-start":
+      return { type, id, parentId: parent, turn: reqNonNegInt(value, "turn") };
+    case "turn-end":
+      return { type, id, parentId: parent, turn: reqNonNegInt(value, "turn") };
+    default:
+      throw new SessionEventShapeError(`unknown session event type: ${JSON.stringify(type)}`);
+  }
+}

package/src/session/index.ts

@@ -0,0 +1,67 @@
+/**
+ * `@nanobpm/agentic/session` — the canonical agent-session contract (ADR 0062,
+ * slice 1). The foundation the two ingestion backends (ACP, normalisers) and the
+ * nano-workforce world-restore all code against in parallel.
+ *
+ * Exports, in the order a consumer meets them:
+ *  - the canonical {@link SessionEvent} union every harness dialect normalises
+ *    into, plus {@link parseSessionEvent} (the untyped-storage boundary);
+ *  - the three-method {@link SessionAdapter} interface (emit/checkpoint/restore)
+ *    with its {@link ActivationKey}, {@link SessionCheckpoint} and
+ *    {@link SessionSeed} types;
+ *  - the {@link SessionLog} port and its two backends — the in-memory reference
+ *    ({@link InMemorySessionLog}, the stub) and the durable, authoritative
+ *    {@link SqliteSessionLog} that promotes the ADR 0056 §12 relay ring + fence;
+ *  - {@link SessionBackend} (the one adapter implementation) and the
+ *    {@link openInMemorySession} / {@link openSqliteSession} factories.
+ *
+ * The new DB schema ships as the forward-only migration
+ * `db/migrations/005_agentic_session.sql`, mirrored by {@link SESSION_SCHEMA_SQL}
+ * and kept in lockstep by a drift-guard test. Nothing here rides the Camunda-8
+ * engine — the log is app-tier (ADR 0056 boundary preserved).
+ */
+export type {
+  AppendedSessionEvent,
+  AssistantMessageEvent,
+  CompactionEvent,
+  ReasoningEvent,
+  SessionEvent,
+  SessionEventEnvelope,
+  SessionEventType,
+  SystemMessageEvent,
+  ToolCallEvent,
+  ToolResultEvent,
+  TurnEndEvent,
+  TurnStartEvent,
+  UsageEvent,
+  UserMessageEvent,
+} from "./events.ts";
+export { parseSessionEvent, SESSION_EVENT_TYPES, SessionEventShapeError } from "./events.ts";
+
+export type {
+  ActivationKey,
+  EffectEntry,
+  EffectLedger,
+  SessionAdapter,
+  SessionCheckpoint,
+  SessionSeed,
+} from "./adapter.ts";
+export { activationKeyString, StaleIncarnationError } from "./adapter.ts";
+
+export type { Clock, SessionLog, SqliteDb } from "./log.ts";
+export {
+  InMemorySessionLog,
+  SessionLogCorruptionError,
+  SqliteSessionLog,
+  systemClock,
+} from "./log.ts";
+
+export type { SessionBackendOptions } from "./backend.ts";
+export { openInMemorySession, openSqliteSession, SessionBackend } from "./backend.ts";
+
+export {
+  SESSION_CHECKPOINT_TABLE,
+  SESSION_EVENT_TABLE,
+  SESSION_LOG_TABLE,
+  SESSION_SCHEMA_SQL,
+} from "./schema.ts";

package/src/session/log.test.ts

@@ -0,0 +1,215 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import type { TestContext } from "node:test";
+import type { ActivationKey } from "./adapter.ts";
+import type { SessionEvent } from "./events.ts";
+import { StaleIncarnationError } from "./adapter.ts";
+import type { SessionCheckpoint } from "./adapter.ts";
+import { InMemorySessionLog, SessionLogCorruptionError, type SqliteDb, SqliteSessionLog } from "./log.ts";
+import { SESSION_CHECKPOINT_TABLE, SESSION_EVENT_TABLE, SESSION_LOG_TABLE } from "./schema.ts";
+import { openTestDb } from "./test-db.ts";
+
+const KEY: ActivationKey = { processInstanceKey: "pik", elementId: "el" };
+
+function ev(id: string, offset: number): SessionEvent {
+  return { type: "user", id, parentId: offset === 0 ? null : `e${offset - 1}`, text: `t${offset}` };
+}
+
+function checkpoint(overrides: Partial<SessionCheckpoint> = {}): SessionCheckpoint {
+  return {
+    id: "c0",
+    offset: 0,
+    commitSha: "sha",
+    effectLedger: [],
+    incarnation: 1,
+    at: new Date(0).toISOString(),
+    ...overrides,
+  };
+}
+
+test("append rejects a gap (offset beyond next)", () => {
+  const log = new InMemorySessionLog();
+  log.lease(KEY, 1);
+  assert.throws(() => log.append(KEY, 1, 1, ev("e", 1)), RangeError);
+});
+
+test("replay honours from/to bounds", () => {
+  const log = new InMemorySessionLog();
+  log.lease(KEY, 1);
+  for (let i = 0; i < 5; i++) log.append(KEY, 1, i, ev(`e${i}`, i));
+  assert.deepEqual(log.replay(KEY, 1, 3).map((e) => e.offset), [1, 2]);
+  assert.deepEqual(log.replay(KEY, 3).map((e) => e.offset), [3, 4]);
+  assert.deepEqual(log.replay(KEY, 0).length, 5);
+});
+
+for (const make of [
+  { name: "in-memory", open: (_t: TestContext) => new InMemorySessionLog() },
+  {
+    name: "sqlite",
+    open: (t: TestContext) => {
+      const log = new SqliteSessionLog(openTestDb(t));
+      log.ensureSchema();
+      return log;
+    },
+  },
+]) {
+  test(`[${make.name}] replay rejects an invalid 'to' bound just like 'from'`, (t) => {
+    const log = make.open(t);
+    log.lease(KEY, 1);
+    for (let i = 0; i < 3; i++) log.append(KEY, 1, i, ev(`e${i}`, i));
+    assert.throws(() => log.replay(KEY, 0, -1), RangeError, "negative to");
+    assert.throws(() => log.replay(KEY, 0, 1.5), RangeError, "non-integer to");
+    assert.throws(() => log.replay(KEY, 2, 1), RangeError, "to < from");
+  });
+}
+
+test("latestCheckpoint returns the highest-offset checkpoint", () => {
+  const log = new InMemorySessionLog();
+  log.lease(KEY, 1);
+  const at = new Date(0).toISOString();
+  log.putCheckpoint(KEY, 1, { id: "c0", offset: 1, commitSha: "s0", effectLedger: [], incarnation: 1, at });
+  log.putCheckpoint(KEY, 1, { id: "c1", offset: 4, commitSha: "s1", effectLedger: [], incarnation: 1, at });
+  log.putCheckpoint(KEY, 1, { id: "c2", offset: 2, commitSha: "s2", effectLedger: [], incarnation: 1, at });
+  assert.equal(log.latestCheckpoint(KEY)?.id, "c1");
+  assert.equal(log.getCheckpoint(KEY, "c2")?.offset, 2);
+});
+
+test("[sqlite] the offset window (first/next) tracks stored events", (t) => {
+  const db = openTestDb(t);
+  const log = new SqliteSessionLog(db);
+  log.ensureSchema();
+  log.lease(KEY, 1);
+  assert.equal(log.nextOffset(KEY), 0);
+  log.append(KEY, 1, 0, ev("e0", 0));
+  log.append(KEY, 1, 1, ev("e1", 1));
+  assert.equal(log.nextOffset(KEY), 2);
+  const row = db.all<{ first_offset: number; next_offset: number }>(
+    `SELECT first_offset, next_offset FROM agentic_session_log WHERE process_instance_key = ? AND element_id = ?`,
+    [KEY.processInstanceKey, KEY.elementId],
+  )[0];
+  assert.equal(row?.first_offset, 0);
+  assert.equal(row?.next_offset, 2);
+});
+
+test("[sqlite] a durable checkpoint round-trips its effect ledger", (t) => {
+  const db = openTestDb(t);
+  const log = new SqliteSessionLog(db);
+  log.ensureSchema();
+  log.lease(KEY, 1);
+  const ledger = [{ id: "e1", kind: "push", detail: { sha: "abc" } }];
+  log.putCheckpoint(KEY, 1, {
+    id: "c0",
+    offset: 0,
+    commitSha: "sha",
+    effectLedger: ledger,
+    incarnation: 1,
+    at: new Date(0).toISOString(),
+  });
+  assert.deepEqual(log.getCheckpoint(KEY, "c0")?.effectLedger, ledger);
+});
+
+test("[sqlite] a corrupt effect ledger fails fast on read", (t) => {
+  const db = openTestDb(t);
+  const log = new SqliteSessionLog(db);
+  log.ensureSchema();
+  log.lease(KEY, 1);
+  db.run(
+    `INSERT INTO ${SESSION_CHECKPOINT_TABLE}
+       (process_instance_key, element_id, checkpoint_id, checkpoint_offset, incarnation, commit_sha, effect_ledger, created_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+    [KEY.processInstanceKey, KEY.elementId, "bad", 0, 1, "sha", '{"not":"an-array"}', new Date(0).toISOString()],
+  );
+  assert.throws(() => log.getCheckpoint(KEY, "bad"), SessionLogCorruptionError);
+});
+
+test("[sqlite] resuming into the log deletes the superseded tail rows", (t) => {
+  const db = openTestDb(t);
+  const log = new SqliteSessionLog(db);
+  log.ensureSchema();
+  log.lease(KEY, 1);
+  for (let i = 0; i < 4; i++) log.append(KEY, 1, i, ev(`e${i}`, i));
+  // Resume: rewrite from offset 2 under a newer incarnation.
+  log.lease(KEY, 2);
+  log.append(KEY, 2, 2, ev("e2b", 2));
+  const rows = db.all<{ n: number }>(
+    `SELECT COUNT(*) AS n FROM ${SESSION_EVENT_TABLE} WHERE process_instance_key = ? AND element_id = ?`,
+    [KEY.processInstanceKey, KEY.elementId],
+  )[0];
+  assert.equal(rows?.n, 3, "offsets 0,1,2 remain; the old 2 and 3 were dropped");
+  assert.equal(log.nextOffset(KEY), 3);
+});
+
+test("[sqlite] the offset window stays exact across a rewinding resume", (t) => {
+  const db = openTestDb(t);
+  const log = new SqliteSessionLog(db);
+  log.ensureSchema();
+  const window = () => {
+    const row = db.all<{ first_offset: number | null; next_offset: number }>(
+      `SELECT first_offset, next_offset FROM ${SESSION_LOG_TABLE} WHERE process_instance_key = ? AND element_id = ?`,
+      [KEY.processInstanceKey, KEY.elementId],
+    )[0];
+    return { first_offset: row?.first_offset ?? null, next_offset: row?.next_offset ?? null };
+  };
+  log.lease(KEY, 1);
+  for (let i = 0; i < 4; i++) log.append(KEY, 1, i, ev(`e${i}`, i));
+  assert.deepEqual(window(), { first_offset: 0, next_offset: 4 }, "grows to [0,4)");
+  // Resume above the floor: the tail is rewritten but the min is untouched.
+  log.lease(KEY, 2);
+  log.append(KEY, 2, 2, ev("e2b", 2));
+  assert.deepEqual(window(), { first_offset: 0, next_offset: 3 }, "min 0 kept; next follows the new tail");
+  // Resume at the floor: every prior event is dropped, so the min rewinds too.
+  log.lease(KEY, 3);
+  log.append(KEY, 3, 0, ev("e0b", 0));
+  assert.deepEqual(window(), { first_offset: 0, next_offset: 1 }, "min rewinds to the new sole event");
+});
+
+test("[sqlite] a concurrent first-lease race fences out the stale writer", (t) => {
+  // Simulate the TOCTOU window: a competing writer commits the activation row at a
+  // higher incarnation just before our INSERT lands. A plain ON CONFLICT DO NOTHING
+  // would let the stale lease proceed unfenced; #admit must reject it instead.
+  const base = openTestDb(t);
+  new SqliteSessionLog(base).ensureSchema();
+  const winner = new SqliteSessionLog(base);
+  let raced = false;
+  const racingDb: SqliteDb = {
+    exec: (sql) => base.exec(sql),
+    all: (sql, params) => base.all(sql, params),
+    run: (sql, params) => {
+      if (!raced && /^\s*INSERT\s+INTO\s+agentic_session_log\b/i.test(sql)) {
+        raced = true;
+        winner.lease(KEY, 5); // a newer incarnation grabs the lease first
+      }
+      return base.run(sql, params);
+    },
+  };
+  const stale = new SqliteSessionLog(racingDb);
+  assert.throws(() => stale.lease(KEY, 3), StaleIncarnationError);
+  assert.equal(new SqliteSessionLog(base).currentIncarnation(KEY), 5);
+});
+
+for (const make of [
+  { name: "in-memory", open: (_t: TestContext) => new InMemorySessionLog() },
+  {
+    name: "sqlite",
+    open: (t: TestContext) => {
+      const log = new SqliteSessionLog(openTestDb(t));
+      log.ensureSchema();
+      return log;
+    },
+  },
+]) {
+  test(`[${make.name}] putCheckpoint rejects a checkpoint whose incarnation differs from the lease`, (t) => {
+    const log = make.open(t);
+    log.lease(KEY, 2);
+    assert.throws(() => log.putCheckpoint(KEY, 2, checkpoint({ incarnation: 1 })), RangeError);
+  });
+
+  test(`[${make.name}] putCheckpoint is idempotent on checkpoint id (first-wins)`, (t) => {
+    const log = make.open(t);
+    log.lease(KEY, 1);
+    log.putCheckpoint(KEY, 1, checkpoint({ id: "c0", offset: 1 }));
+    log.putCheckpoint(KEY, 1, checkpoint({ id: "c0", offset: 2 }));
+    assert.equal(log.getCheckpoint(KEY, "c0")?.offset, 1, "the first write wins; a retry never duplicates");
+    assert.equal(log.latestCheckpoint(KEY)?.offset, 1);
+  });
+}