@abloatai/transaction 0.37.0

package/src/coordination/targetConflict.ts

@@ -0,0 +1,85 @@
+import type { ClaimTargetDetails } from './locator.js';
+
+/**
+ * Whether two claims on the same entity collide — the single most consequential
+ * predicate in the claim protocol, and the one rule that decides whether a
+ * second writer is granted a lease or made to wait.
+ *
+ * It lived in two files for as long as there were two claim authorities: the
+ * Redis lease store, which is authoritative wherever Redis is wired, and the
+ * in-process presence store, which answers when it is not. Both spelled the
+ * rule out in full, byte for byte, so a change to the granularity semantics had
+ * two places to land and no way to notice when it landed in one. It is one
+ * definition here, and both authorities import it.
+ *
+ * It lives in the settlement core rather than the server because it is the rule
+ * itself, not a deployment of it: a claim authority running against a
+ * developer's own database has to answer this question exactly the same way,
+ * and a client that wants to predict a refusal before paying for the round trip
+ * reads the same predicate. Nothing about it needs a socket, a store, or a
+ * screen.
+ *
+ * Entity identity is NOT part of this comparison. Callers reach this predicate
+ * having already narrowed to a single `(organization, environment, entityType,
+ * entityId)` bucket — the lease store through its key, the presence store
+ * through its per-entity scan — so what remains to decide is only whether the
+ * two sub-targets within that entity overlap.
+ *
+ * **The bias is deliberate: when in doubt, conflict.** A false conflict costs a
+ * writer a wait. A missed conflict hands two writers the same target and loses
+ * one of their updates with no error anywhere, which is the failure this
+ * predicate exists to prevent.
+ */
+
+/**
+ * The named parts a claim covers, as one set.
+ *
+ * `field` and `fields` are the same idea at two cardinalities, so the rule
+ * reads both through here and never has to ask which one a caller used. Names
+ * are lowercased for the same reason the single-field comparison always
+ * lowercased them.
+ */
+function fieldSet(target: ClaimTargetDetails | undefined): Set<string> {
+  const named = [
+    ...(target?.field !== undefined ? [target.field] : []),
+    ...(target?.fields ?? []),
+  ];
+  return new Set(named.map((n) => n.toLowerCase()));
+}
+
+/** Whether a claim narrows below the whole entity at all. */
+function hasSubtarget(target: ClaimTargetDetails | undefined): boolean {
+  return Boolean(
+    target?.field || (target?.fields && target.fields.length > 0),
+  );
+}
+
+export function targetsConflict(
+  held: ClaimTargetDetails,
+  incoming: ClaimTargetDetails | undefined,
+): boolean {
+  // Whole-entity claims are conservative: they conflict with any narrower
+  // field claim under the same entity.
+  if (!hasSubtarget(held) || !hasSubtarget(incoming)) return true;
+
+  // Field is the floor. A claim is only as fine as the smallest thing the write
+  // path can address, and today that is a whole field: nothing writes part of a
+  // value. Sub-field targeting — a text range, a path into a document — would
+  // let two writers hold disjoint parts of the SAME field at once, which is
+  // only safe once concurrent edits to one field can be reconciled (operational
+  // transformation). We have not solved that yet, so we do not offer the finer
+  // grain: two claims on the same field conflict, full stop. When same-field
+  // concurrency is solved, sub-field targets return with real disjointness.
+  // See docs/plans/claim-granularity-field-floor.md.
+  //
+  // A claim that names no field covers every field, so it conflicts with any
+  // claim under the same entity. Two that both name fields conflict only where
+  // their sets intersect.
+  const heldFields = fieldSet(held);
+  const incomingFields = fieldSet(incoming);
+  return (
+    heldFields.size === 0 ||
+    incomingFields.size === 0 ||
+    [...heldFields].some((name) => incomingFields.has(name))
+  );
+}

package/src/coordination/trace.ts

@@ -0,0 +1,173 @@
+/**
+ * A claim log — the simplest way to watch agents collide. The engine reports
+ * the claim lifecycle (`acquired → queued → granted → lost / rejected /
+ * expired`) and the notify-instead-of-abort stale write through two channels:
+ * human-readable `logger` lines (shown with `new Ablo({ debug: true })`) and
+ * structured `observability.captureClaim` / `captureConflict` calls.
+ *
+ * This is a third channel, shaped for tests and evals. Pass a {@link ClaimLog}
+ * as `Ablo({ observability })`, run your scenario, then read back an ordered
+ * list — print it to eyeball what happened, or call `collisions()` to assert on it.
+ */
+
+import type {
+  ClaimEvent,
+  ConflictEvent,
+  CoordinationObserver,
+} from './events.js';
+
+// ─────────────────────────────────────────────
+// Formatters — one readable line per event. Shared by the debug logger and
+// this log so console output and log output never drift.
+// ─────────────────────────────────────────────
+
+/** A claim state change as one quiet, greppable line. */
+export function formatClaim(e: ClaimEvent): string {
+  const target = e.model && e.id ? `${e.model}/${e.id}` : e.claimId ?? 'unknown target';
+  const scope = e.field ? `#${e.field}` : '';
+  const pos = e.position !== undefined ? ` [pos ${e.position}]` : '';
+  // The kind belongs to the counterparty, which is the only participant an
+  // event names: on an acquisition the participant is us.
+  const kind = e.heldBy?.participantKind;
+  const actor = e.actor ? `${e.actor}${kind ? ` (${kind})` : ''}` : '';
+  // `rejected`/`lost` name the blocking holder; the rest name us (or no one).
+  const by = actor
+    ? e.phase === 'rejected' || e.phase === 'lost'
+      ? ` — held by ${actor}`
+      : ` — by ${actor}`
+    : '';
+  // The cause when there is one, in the policy's own words when a policy
+  // decided; otherwise what the holder said they were doing. A line never
+  // shows both, because a claim that ended has a cause and a claim that is
+  // simply alive has only its description.
+  const why = e.reason
+    ? `: ${e.policyReason ?? e.reason}`
+    : e.description
+      ? `: ${e.description}`
+      : '';
+  return `claim ${e.phase}: ${target}${scope}${pos}${by}${why}`;
+}
+
+/** A notify-instead-of-abort stale write as one readable line. */
+export function formatConflict(e: ConflictEvent): string {
+  const rows = e.rows.map((r) => `${r.model}/${r.id}(${r.fields.join(',')})`).join(', ');
+  return `conflict: tx ${e.clientTxId} — ${e.rows.length} row(s) changed underneath${rows ? `: ${rows}` : ''}`;
+}
+
+// ─────────────────────────────────────────────
+// Log — collect → inspect / assert
+// ─────────────────────────────────────────────
+
+/** One ordered entry in a {@link ClaimLog}. */
+export interface ClaimLogEntry {
+  /** Monotonic order index — deterministic, clock-free, eval-friendly. */
+  readonly seq: number;
+  /** The same one-line text the console and breadcrumb channels emit. */
+  readonly line: string;
+  /** A collision worth flagging: a rejected/lost claim or a stale write. */
+  readonly collision: boolean;
+  readonly claim?: ClaimEvent;
+  readonly conflict?: ConflictEvent;
+}
+
+/**
+ * Collects the claim lifecycle + stale-write collisions into an ordered list.
+ *
+ * @example
+ * ```ts
+ * const log = new ClaimLog();
+ * const ablo = new Ablo({ schema, apiKey, observability: log });
+ * // …run the agents…
+ * console.log(`${log}`);                 // pretty timeline for eyeballing
+ * expect(log.collisions()).toHaveLength(0); // assert no one stepped on anyone
+ * ```
+ *
+ * Implements the transaction layer's narrow {@link CoordinationObserver}.
+ * The sync engine re-serves a compatibility subclass that fills its broader
+ * lifecycle-observability contract, so the public `Ablo({ observability })`
+ * usage remains unchanged without teaching this core class about bootstrap,
+ * IndexedDB, or WebSockets.
+ */
+export class ClaimLog implements CoordinationObserver {
+  // Immutable list: a new array reference on every change. This is what lets
+  // `useSyncExternalStore(log.onChange, () => log.entries)` detect updates —
+  // it compares snapshots by reference, so an in-place push would never render.
+  private rows: readonly ClaimLogEntry[] = [];
+  private seq = 0;
+  private readonly listeners = new Set<() => void>();
+
+  /** Cap the buffer so a long-running session can't grow unbounded. */
+  constructor(private readonly max = 1_000) {}
+
+  // —— the two channels we record ——
+
+  captureClaim(claim: ClaimEvent): void {
+    this.add({
+      line: formatClaim(claim),
+      collision: claim.phase === 'rejected' || claim.phase === 'lost',
+      claim,
+    });
+  }
+
+  captureConflict(conflict: ConflictEvent): void {
+    this.add({ line: formatConflict(conflict), collision: true, conflict });
+  }
+
+  // —— reactivity ——
+
+  /**
+   * Fire `listener` every time an event lands. Returns an unsubscribe fn. Same
+   * contract as `ablo.claims.onChange` — drop it into `useSyncExternalStore` in
+   * React or `autorun` in MobX to render a live activity feed.
+   *
+   * @example
+   * ```tsx
+   * const log = useMemo(() => new ClaimLog(), []);
+   * const entries = useSyncExternalStore(log.onChange, () => log.entries);
+   * return <ul>{entries.map((e) => <li key={e.seq}>{e.line}</li>)}</ul>;
+   * ```
+   */
+  readonly onChange = (listener: () => void): (() => void) => {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  };
+
+  // —— inspection ——
+
+  /** The full ordered list. Stable reference until the next event lands. */
+  get entries(): readonly ClaimLogEntry[] {
+    return this.rows;
+  }
+
+  /** Only the collisions: rejected/lost claims + stale writes. */
+  collisions(): readonly ClaimLogEntry[] {
+    return this.rows.filter((e) => e.collision);
+  }
+
+  /** Drop everything — useful between scenarios in one process. */
+  clear(): void {
+    this.rows = [];
+    this.seq = 0;
+    this.notify();
+  }
+
+  /** Printable: one event per line, collisions marked. */
+  toString(): string {
+    if (this.rows.length === 0) return 'claim log: (empty)';
+    const w = String(this.rows.length).length;
+    return this.rows
+      .map((e) => `${String(e.seq).padStart(w)}  ${e.collision ? '⚠ ' : '  '}${e.line}`)
+      .join('\n');
+  }
+
+  private add(entry: Omit<ClaimLogEntry, 'seq'>): void {
+    const next = [...this.rows, { seq: this.seq++, ...entry }];
+    this.rows = next.length > this.max ? next.slice(next.length - this.max) : next;
+    this.notify();
+  }
+
+  private notify(): void {
+    for (const listener of this.listeners) listener();
+  }
+
+}

package/src/docs/catalog.ts

@@ -0,0 +1,274 @@
+/**
+ * The catalog of documentation this package ships.
+ *
+ * One definition of *which docs exist*, read from the files themselves. Every
+ * reader — `ablo docs`, the public `/api/docs/*` routes, the MCP docs tools —
+ * resolves through here rather than keeping its own list, because a
+ * hand-maintained index of a directory is a copy that drifts the moment a page
+ * is added and nothing fails when it does. Before this module the public web
+ * allowlist had fallen 21 pages behind the corpus, including `coordination`.
+ *
+ * Title and description are DERIVED from each file's own convention: an H1,
+ * then a one-paragraph blockquote stating what the page is for. That blockquote
+ * is the description everywhere it is needed — the site frontmatter lifts the
+ * same line — so a page states its own promise exactly once, in the source that
+ * ships in the npm tarball and still reads correctly as plain markdown.
+ *
+ * The published set mirrors the tarball's `files` globs (`docs/*.md`,
+ * `docs/examples/*.md`, plus the three root files). Anything else under `docs/`
+ * — `docs/internal/**` above all — is neither shipped nor catalogued, and that
+ * exclusion is the only thing keeping internal notes off the public routes now
+ * that they read from here.
+ */
+
+import { readdir, readFile } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+
+/** Where a page sits in the corpus, and how a reader should group it. */
+export type DocKind = 'guide' | 'example' | 'package';
+
+/** One documentation page, as shipped. */
+export interface DocEntry {
+  /** Stable reference: `quickstart`, `examples/nextjs`, `agents`. */
+  readonly slug: string;
+  /** Human-readable title — the file's H1, or curated for the root files. */
+  readonly title: string;
+  /** One line stating what the page is for — the file's promise blockquote. */
+  readonly description: string;
+  readonly kind: DocKind;
+  /** Absolute path on disk. */
+  readonly path: string;
+  readonly mime: string;
+}
+
+const MARKDOWN_MIME = 'text/markdown; charset=utf-8';
+const TEXT_MIME = 'text/plain; charset=utf-8';
+
+/**
+ * The three files that document the package itself rather than a topic. They
+ * live at the package root, not under `docs/`, and none follows the H1 +
+ * blockquote convention — `llms.txt` opens with a prose paragraph and
+ * `README.md` with a banner — so their titles and descriptions are curated
+ * here, the one place that knows they are a different kind of artifact.
+ *
+ * Their slug is their filename, because the filename IS how these are referred
+ * to everywhere (`AGENTS.md` is an ecosystem convention, not a topic name) and
+ * because a bare word would collide: `docs/agents.md` is a published guide that
+ * the docs index cross-links as `agents`, and whichever of the two won that
+ * name would silently shadow the other. Friendlier spellings are aliases below.
+ */
+const PACKAGE_FILES: readonly {
+  readonly filename: string;
+  readonly title: string;
+  readonly description: string;
+  readonly mime: string;
+}[] = [
+  {
+    filename: 'AGENTS.md',
+    title: 'AGENTS.md',
+    description:
+      'The playbook a coding agent follows to install and drive Ablo without hanging on a prompt.',
+    mime: MARKDOWN_MIME,
+  },
+  {
+    filename: 'README.md',
+    title: 'README',
+    description: 'Package overview — what Ablo is and the shape of the API.',
+    mime: MARKDOWN_MIME,
+  },
+  {
+    filename: 'llms.txt',
+    title: 'llms.txt',
+    description: 'The curated single-file index of the whole API, for machine readers.',
+    mime: TEXT_MIME,
+  },
+];
+
+/**
+ * Curated redirects for references that are not a slug: the friendly spellings
+ * of the root files, plus the renames the public URLs carried before this
+ * module existed, kept so old links and any agent working from a cached page
+ * still resolve. Identity mappings are NOT listed — a slug resolves to itself
+ * by derivation, and restating the other 30 here would rebuild the
+ * hand-maintained list this module exists to delete.
+ */
+const SLUG_ALIASES: Readonly<Record<string, string>> = {
+  readme: 'README.md',
+  overview: 'README.md',
+  llms: 'llms.txt',
+  storage: 'data-sources',
+  'docs/storage.md': 'data-sources',
+};
+
+/**
+ * Read the catalog from a package root — the directory holding `docs/` and the
+ * three root files.
+ *
+ * The root is a parameter rather than resolved here because each reader knows
+ * it differently and they are genuinely different facts: the CLI resolves it
+ * against its own bundle inside `node_modules`, while the web app resolves it
+ * against the monorepo checkout. Nothing is cached; callers that serve many
+ * requests should memoize the returned array.
+ */
+export async function readDocsCatalog(packageRoot: string): Promise<DocEntry[]> {
+  const docsDir = join(packageRoot, 'docs');
+  const entries: DocEntry[] = [];
+
+  entries.push(...(await readDocsDirectory(docsDir, 'guide')));
+  entries.push(...(await readDocsDirectory(join(docsDir, 'examples'), 'example')));
+
+  for (const file of PACKAGE_FILES) {
+    const path = join(packageRoot, file.filename);
+    const body = await readFileOrNull(path);
+    if (body === null) continue;
+    entries.push({
+      slug: file.filename,
+      title: file.title,
+      description: file.description,
+      kind: 'package',
+      path,
+      mime: file.mime,
+    });
+  }
+
+  return entries.sort((a, b) => a.slug.localeCompare(b.slug));
+}
+
+/**
+ * Read one flat directory of markdown. Deliberately non-recursive: the shipped
+ * set is `docs/*.md` plus `docs/examples/*.md`, so descending would catalogue
+ * `docs/internal/**` — notes that are not in the tarball and must not reach a
+ * public route.
+ */
+async function readDocsDirectory(dir: string, kind: DocKind): Promise<DocEntry[]> {
+  let names: string[];
+  try {
+    const found = await readdir(dir, { withFileTypes: true });
+    names = found.filter((e) => e.isFile() && e.name.endsWith('.md')).map((e) => e.name);
+  } catch {
+    return [];
+  }
+
+  const entries: DocEntry[] = [];
+  for (const name of names) {
+    const path = join(dir, name);
+    const body = await readFileOrNull(path);
+    if (body === null) continue;
+    const stem = basename(name, '.md');
+    const { title, description } = parseDocHeader(body);
+    entries.push({
+      slug: kind === 'example' ? `examples/${stem}` : stem,
+      title: title ?? stem,
+      description,
+      kind,
+      path,
+      mime: MARKDOWN_MIME,
+    });
+  }
+  return entries;
+}
+
+/** The H1 a page opens with, and the blockquote paragraph that follows it. */
+const H1_LINE = /^#[ \t]+(.+?)[ \t]*$/m;
+const PROMISE_BLOCKQUOTE = /^\s*\n((?:>.*\n)+)/;
+
+/**
+ * Pull a page's title and promise line out of its markdown.
+ *
+ * The convention every page follows: an H1, then a blockquote paragraph saying
+ * what the page is for. A page missing either simply reports what it has — the
+ * catalog never invents prose.
+ */
+export function parseDocHeader(body: string): {
+  readonly title: string | null;
+  readonly description: string;
+} {
+  const heading = H1_LINE.exec(body);
+  const title = heading?.[1] ?? null;
+
+  const afterHeading = heading === null ? body : body.slice(heading.index + heading[0].length);
+  const promise = PROMISE_BLOCKQUOTE.exec(afterHeading);
+  const description =
+    promise?.[1]
+      ?.split('\n')
+      .filter(Boolean)
+      .map((line) => line.replace(/^>\s?/, ''))
+      .join(' ')
+      .trim() ?? '';
+
+  return { title, description };
+}
+
+/**
+ * Resolve a reference to a page. Accepts the slug (`coordination`), a curated
+ * alias (`storage`), or a repo-relative path (`docs/coordination.md`,
+ * `AGENTS.md`) — the three forms readers actually arrive with. Returns null
+ * rather than throwing so a caller can render its own not-found.
+ */
+export function findDoc(catalog: readonly DocEntry[], reference: string): DocEntry | null {
+  const trimmed = reference.trim();
+  if (trimmed === '') return null;
+
+  const direct = matchSlug(catalog, trimmed);
+  if (direct) return direct;
+
+  const aliased = SLUG_ALIASES[trimmed.toLowerCase()];
+  if (aliased) {
+    const target = matchSlug(catalog, aliased);
+    if (target) return target;
+  }
+
+  // Path form: `docs/coordination.md`, `docs/examples/nextjs.md`, `llms.txt`.
+  const asSlug = trimmed
+    .replace(/^\.?\//, '')
+    .replace(/^docs\//, '')
+    .replace(/\.(md|txt)$/i, '');
+  return matchSlug(catalog, asSlug);
+}
+
+function matchSlug(catalog: readonly DocEntry[], slug: string): DocEntry | null {
+  const needle = slug.toLowerCase();
+  return catalog.find((entry) => entry.slug.toLowerCase() === needle) ?? null;
+}
+
+/**
+ * Slugs closest to a miss, for a "did you mean" line. Ranks by shared prefix,
+ * then substring containment — enough to catch a typo or a half-remembered
+ * name without pulling in a distance library.
+ */
+export function suggestSlugs(
+  catalog: readonly DocEntry[],
+  reference: string,
+  limit = 3
+): string[] {
+  const needle = reference.trim().toLowerCase();
+  if (needle === '') return [];
+
+  return catalog
+    .map((entry) => {
+      const slug = entry.slug.toLowerCase();
+      let score = 0;
+      if (slug.includes(needle) || needle.includes(slug)) score += 10;
+      score += sharedPrefixLength(slug, needle);
+      return { slug: entry.slug, score };
+    })
+    .filter(({ score }) => score > 2)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, limit)
+    .map(({ slug }) => slug);
+}
+
+function sharedPrefixLength(a: string, b: string): number {
+  const max = Math.min(a.length, b.length);
+  let i = 0;
+  while (i < max && a[i] === b[i]) i += 1;
+  return i;
+}
+
+async function readFileOrNull(path: string): Promise<string | null> {
+  try {
+    return await readFile(path, 'utf8');
+  } catch {
+    return null;
+  }
+}

package/src/docs/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Programmatic access to the documentation this package ships.
+ *
+ * The docs travel in the npm tarball beside the code they describe, so a reader
+ * that resolves them through here is reading the pages for the version actually
+ * installed — not whatever the website is serving today. That is the whole
+ * point of the subpath: a published version is frozen, its docs are frozen with
+ * it, and the canonical `get` contract cannot drift behind a pinned dependency.
+ */
+
+export {
+  readDocsCatalog,
+  findDoc,
+  parseDocHeader,
+  suggestSlugs,
+  type DocEntry,
+  type DocKind,
+} from './catalog.js';

package/src/durableWrites.ts

@@ -0,0 +1,134 @@
+/**
+ * The durable-write port and the option that installs it.
+ *
+ * Owns the persistence contract behind `Ablo({ durableWrites })` — a behavior
+ * contract of methods, not a serialized shape, which is why it lives here
+ * rather than in `transactions/settlement/`. The records that cross this port
+ * are owned by `pendingWriteSchema` there; this module never redescribes them.
+ *
+ * The engine consumes the port through `commitOutboxStore`, and the HTTP client
+ * accepts the same option through `transport/httpOptions`.
+ */
+
+import { z } from 'zod';
+import { AbloValidationError } from './errors.js';
+import type { CommitOutboxScope } from './transactions/settlement/commitEnvelope.js';
+import type { PendingWrite } from './transactions/settlement/pendingWrite.js';
+
+/**
+ * Persistence port used by `Ablo({ durableWrites })`.
+ *
+ * `seal` is the durability boundary: it must atomically persist the exact write
+ * and consume the staged records that write supersedes. Resolving this promise
+ * authorizes Ablo to dispatch the request, so adapters must never report success
+ * before the data is durable.
+ */
+export interface DurableWriteStore {
+  /**
+   * Atomically reserve a pending write and consume the staged records it owns.
+   * The same id + same request is idempotent; the same id + a different request
+   * must be rejected. For a source-accepted envelope, a re-seal may add the
+   * monotonic `acceptedAt`/`correlationId` evidence and the store must preserve
+   * that upgrade atomically rather than ignoring it.
+   */
+  seal(
+    write: PendingWrite,
+    consumedRecordIds: readonly string[],
+  ): Promise<void>;
+  /** Load all unacknowledged writes. Stored data is treated as untrusted. */
+  list(): Promise<readonly unknown[]>;
+  /** Remove one write only after its outcome is definitive. */
+  remove(writeId: string): Promise<void>;
+}
+
+/** Runtime validation for injected adapters, including JavaScript consumers. */
+export const durableWriteStoreSchema = z.custom<DurableWriteStore>(
+  (value) => {
+    if (typeof value !== 'object' || value === null) return false;
+    const candidate = value as Record<string, unknown>;
+    return (
+      typeof candidate.seal === 'function' &&
+      typeof candidate.list === 'function' &&
+      typeof candidate.remove === 'function'
+    );
+  },
+  { message: 'store must implement seal(), list(), and remove()' },
+);
+
+/** Options for crash-durable `create`, `update`, and `delete` calls. */
+export const durableWritesConfigSchema = z.strictObject({
+  store: durableWriteStoreSchema,
+  /** Separates deployments or workflow lanes that share an authenticated actor. */
+  namespace: z.string().trim().min(1).optional(),
+});
+
+export type DurableWritesConfig = z.infer<typeof durableWritesConfigSchema>;
+
+interface DurableWriteOptionInput {
+  readonly durableWrites?: DurableWritesConfig;
+  /** Compatibility input for pre-`durableWrites` clients. */
+  readonly commitOutbox?: DurableWriteStore;
+  /** Compatibility input and internal child-client identity seam. */
+  readonly commitOutboxScope?: CommitOutboxScope;
+}
+
+export interface ResolvedDurableWrites {
+  readonly store?: DurableWriteStore;
+  readonly namespace?: string;
+}
+
+function invalidDurableWrites(message: string): AbloValidationError {
+  return new AbloValidationError(`Ablo: invalid \`durableWrites\` option — ${message}.`, {
+    code: 'invalid_options',
+    param: 'durableWrites',
+  });
+}
+
+/**
+ * Resolves one canonical store configuration for both HTTP and WebSocket
+ * clients. Mixed old/new configuration fails loudly so Ablo never persists to
+ * one adapter while the caller believes another adapter is authoritative.
+ */
+export function resolveDurableWrites(
+  options: DurableWriteOptionInput,
+): ResolvedDurableWrites {
+  if (options.durableWrites !== undefined && options.commitOutbox !== undefined) {
+    throw invalidDurableWrites(
+      'pass `durableWrites` or the deprecated `commitOutbox`, not both',
+    );
+  }
+
+  if (options.durableWrites !== undefined) {
+    const parsed = durableWritesConfigSchema.safeParse(options.durableWrites);
+    if (!parsed.success) {
+      throw invalidDurableWrites(
+        parsed.error.issues.map((issue) => issue.message).join('; '),
+      );
+    }
+    return {
+      store: parsed.data.store,
+      ...(parsed.data.namespace !== undefined
+        ? { namespace: parsed.data.namespace }
+        : options.commitOutboxScope?.namespace !== undefined
+          ? { namespace: options.commitOutboxScope.namespace }
+          : {}),
+    };
+  }
+
+  if (options.commitOutbox !== undefined) {
+    const parsed = durableWriteStoreSchema.safeParse(options.commitOutbox);
+    if (!parsed.success) {
+      throw invalidDurableWrites(
+        parsed.error.issues.map((issue) => issue.message).join('; '),
+      );
+    }
+    return {
+      store: parsed.data,
+      ...(options.commitOutboxScope?.namespace !== undefined
+        ? { namespace: options.commitOutboxScope.namespace }
+        : {}),
+    };
+  }
+
+  return {};
+}