@abloatai/transaction 0.37.0

package/src/observability.ts

@@ -0,0 +1,85 @@
+/**
+ * The observability the settlement core reports on its own behalf.
+ *
+ * Coordination outcomes — a claim changing state, a stale-write collision that
+ * notified instead of aborting — happen with no UI and no local store anywhere,
+ * so the core must be able to report them without depending on the consumer's
+ * full provider (ADR 0016).
+ *
+ * This is deliberately the narrow set the core actually calls today. Widening it
+ * later is non-breaking; the reactive engine's `ObservabilityProvider` extends
+ * this interface, so a single implementation still satisfies both.
+ */
+
+import type { ClaimEvent, ConflictEvent } from './coordination/events.js';
+
+export interface CoordinationObservability {
+  /** Capture a claim state change (acquired / queued / granted / lost / rejected / expired). */
+  captureClaim(event: ClaimEvent): void;
+
+  /** Capture a notify-instead-of-abort stale-write collision. */
+  captureConflict(event: ConflictEvent): void;
+}
+
+// ─────────────────────────────────────────────
+// Transport observability
+// ─────────────────────────────────────────────
+
+/** Breadcrumb severity levels */
+export type BreadcrumbLevel = 'debug' | 'info' | 'warning' | 'error';
+
+/** Breadcrumb categories for sync engine lifecycle events */
+export type BreadcrumbCategory =
+  | 'sync.bootstrap'
+  | 'sync.transaction'
+  | 'sync.websocket'
+  | 'sync.offline'
+  | 'sync.database'
+  | 'sync.conflict'
+  | 'sync.coordination'
+  | 'sync.groups';
+
+export interface WebSocketErrorDetails {
+  context: string;
+  error?: string;
+  code?: number;
+  reason?: string;
+}
+
+/**
+ * The observability the duplex transport reports on its own behalf: connection
+ * lifecycle breadcrumbs and socket errors. A server-side agent holding a socket
+ * for claim push has no store and no UI, so the transport must be able to
+ * report without the consumer's full provider — the same reasoning as
+ * {@link CoordinationObservability}, one layer down. The reactive engine's
+ * `ObservabilityProvider` extends this interface, so a single implementation
+ * satisfies both.
+ */
+export interface TransportObservability {
+  /** Add a breadcrumb for sync lifecycle events */
+  breadcrumb(
+    message: string,
+    category: BreadcrumbCategory,
+    level?: BreadcrumbLevel,
+    data?: Record<string, string | number | boolean | undefined>
+  ): void;
+
+  /** Capture WebSocket error */
+  captureWebSocketError(details: WebSocketErrorDetails): void;
+}
+
+/**
+ * Everything the duplex transport reports: its own lifecycle
+ * ({@link TransportObservability}) plus the coordination outcomes that ride
+ * the socket ({@link CoordinationObservability} — claim pushes and notified
+ * collisions arrive as frames, so the transport is where they surface).
+ */
+export type SocketObservability = TransportObservability & CoordinationObservability;
+
+/** The no-op default — what the transport reports through when nothing is wired. */
+export const noopSocketObservability: SocketObservability = {
+  breadcrumb() {},
+  captureWebSocketError() {},
+  captureClaim() {},
+  captureConflict() {},
+};

package/src/policy/types.ts

@@ -0,0 +1,292 @@
+/**
+ * The conflict types a policy decides on. The engine detects a conflict and
+ * hands it to your {@link ConflictPolicy}, which returns a
+ * {@link ConflictDecision}.
+ *
+ * There are two conflict shapes. A {@link StaleContextConflict} is a write
+ * whose `readAt` watermark is older than the latest delta on the target row. A
+ * {@link ClaimHeldConflict} is a participant trying to claim a target that
+ * someone else already holds. {@link Conflict} is the discriminated union of
+ * the two; switch on `kind` to narrow it.
+ */
+
+import type { z } from 'zod';
+import type { ParticipantRef } from '../types/participant.js';
+import type { CommitOperationType, OnStaleMode } from '../coordination/schema.js';
+import type { conflictAxisWireSchema } from '../wire/accountResponses.js';
+
+export type ConflictKind = 'stale_context' | 'claim_held';
+
+/** Fields shared by every conflict shape. */
+interface ConflictBase {
+  readonly committer: ParticipantRef;
+  readonly organizationId: string;
+  /** Human at the root of the committer's delegation chain (if any). */
+  readonly delegationChainRootUserId?: string | null;
+}
+
+/** The operation whose write conflicts. */
+export interface ConflictOperation {
+  readonly model: string;
+  readonly id: string;
+  readonly type: CommitOperationType;
+  readonly input?: Readonly<Record<string, unknown>>;
+}
+
+export interface StaleContextConflict extends ConflictBase {
+  readonly kind: 'stale_context';
+  readonly operation: ConflictOperation;
+  /** Watermark the committer reasoned against. */
+  readonly readAt: number;
+  /** Most recent delta id on the target. */
+  readonly observedSyncId: number;
+  /**
+   * The fields whose concurrent change triggered this conflict — the
+   * intersection of the fields the committer wrote and the columns a newer
+   * delta touched. An empty array means the conflicting delta was a
+   * whole-entity change, such as a create or delete, which conflicts with any
+   * write. A policy can use this to decide at field granularity — for example,
+   * allowing the write when the only overlap is on a cosmetic field.
+   */
+  readonly conflictingFields?: readonly string[];
+  /**
+   * The committer's declared `onStale` intent for this operation. The default
+   * policy honors it: `'notify'` holds the write and notifies, and anything
+   * else rejects. A custom policy may override this. When absent, it is treated
+   * as `'reject'`, the default for an unguarded write.
+   */
+  readonly requestedMode?: OnStaleMode;
+}
+
+export interface ClaimHeldConflict extends ConflictBase {
+  readonly kind: 'claim_held';
+  readonly heldBy: ParticipantRef;
+  readonly claimId: string;
+  readonly entityType: string;
+  readonly entityId: string;
+  /** Holder's claim expiry (ms since epoch). */
+  readonly expiresAt: number;
+  /**
+   * The capability operations granted to the committer — the allowlist carried
+   * by its key. A policy decides purely from the conflict it is given, so this
+   * is the only place it can read the committer's privileges. It lets a policy
+   * express a rule such as "preempt only if the committer holds `claim.preempt`"
+   * (see {@link capabilityPreemptPolicy}). Empty for a human session that
+   * carries no allowlist.
+   */
+  readonly committerOperations: readonly string[];
+}
+
+/**
+ * The discriminated union the policy receives. Switch on `.kind` to
+ * narrow to the variant.
+ */
+export type Conflict = StaleContextConflict | ClaimHeldConflict;
+
+/** What the policy returns. */
+export type ConflictDecision =
+  | { readonly action: 'reject'; readonly reason?: string }
+  | { readonly action: 'allow'; readonly note?: string }
+  /**
+   * Evict the current holder and grant the target to the committer. This is
+   * only meaningful for a `claim_held` conflict raised at claim time: the
+   * holder receives a `claim_lost` notification with reason `'preempted'`, and
+   * the committer takes the lease ahead of anyone already waiting in line for
+   * it. Return it only for a committer you consider higher priority — for
+   * example, a supervisor over its own sub-agents, or an identity that holds a
+   * preempt capability. At commit time there is no holder to evict, so a
+   * `preempt` decision is treated as `allow`.
+   */
+  | { readonly action: 'preempt'; readonly reason?: string }
+  /**
+   * Hold the write instead of aborting it. This is only meaningful for a
+   * `stale_context` conflict. The engine withholds the conflicting operation
+   * and returns a `StaleNotification` carrying the current value, so the actor
+   * — an agent or a human — can reconcile and re-commit. The rest of the batch
+   * still commits. It maps from `onStale: 'notify'`.
+   *
+   * The monotonic `sync_id` landing order decides who yields: the stale
+   * committer always recomputes against the newer value, an asymmetry that
+   * prevents two notifying writers from looping against each other. Retries are
+   * bounded by the client's reconciliation retry cap.
+   */
+  | { readonly action: 'notify'; readonly reason?: string };
+
+/**
+ * The function that decides a conflict. It receives a {@link Conflict} and
+ * returns a {@link ConflictDecision}, either synchronously or as a promise.
+ * Register your implementation with the engine; the example below allows a
+ * cosmetic "linter" writer and defers everything else to {@link defaultPolicy}.
+ *
+ * ```ts
+ * const policy: ConflictPolicy = (conflict) => {
+ *   if (conflict.committer.id.startsWith('linter:')) {
+ *     return { action: 'allow', note: 'cosmetic writer' };
+ *   }
+ *   return defaultPolicy(conflict);
+ * };
+ * ```
+ */
+export type ConflictPolicy = (
+  conflict: Conflict,
+) => ConflictDecision | Promise<ConflictDecision>;
+
+/**
+ * The conflict policy the engine uses when you do not supply your own. It
+ * favors people: a human is never blocked, while agents and automated writers
+ * yield to a claim someone else holds.
+ *
+ * For a `claim_held` conflict, the decision follows the committer's kind:
+ *
+ *   • `user`   → `allow`  — a human is never blocked by a claim. A claim is a
+ *                           coordination hint among agents, not a lock on
+ *                           people.
+ *   • `agent`  → `reject` — an agent yields to a claim held by someone else.
+ *                           The one sanctioned exception is the privileged
+ *                           `claim.preempt` capability; see
+ *                           {@link capabilityPreemptPolicy}.
+ *   • `system` → `reject` — automated and backend writers serialize through
+ *                           claims the same way agents do, so a server job
+ *                           cannot silently overwrite a held row. Declare the
+ *                           model's conflict axis to overwrite if you want that.
+ *
+ * Allowing only `user` by default is deliberate: a backend key is a
+ * full-access credential, and claim serialization depends on those writers
+ * respecting claims unless a model opts out.
+ *
+ * For a `stale_context` conflict, the decision honors the committer's declared
+ * `onStale` intent: `'notify'` holds the write and notifies the actor to
+ * resolve it, and anything else (including `'reject'` or an absent value)
+ * rejects. An `onStale` of `'overwrite'` never reaches a policy — it is a hard
+ * opt-out resolved before the conflict is detected.
+ *
+ * To change this behavior for a model, declare its conflict axis in the schema;
+ * a declared axis overrides this default.
+ */
+// Typed by its real synchronous shape with `satisfies`, rather than the
+// async-permissive `ConflictPolicy` alias, so synchronous callers such as
+// `interpretConflictAxis` and `capabilityPreemptPolicy` receive a plain
+// `ConflictDecision` rather than `ConflictDecision | Promise<…>`. It remains
+// assignable to `ConflictPolicy` wherever it is used as one.
+export const defaultPolicy = ((conflict: Conflict): ConflictDecision => {
+  if (conflict.kind === 'claim_held') {
+    // A human (`user`) is never blocked; agents and system actors yield.
+    // Keeping every non-`user` kind on `reject` here ensures an agent cannot
+    // bypass a claim even on this default resolution path, which — unlike the
+    // declared-axis path — has no separate agent guard of its own.
+    return conflict.committer.kind === 'user'
+      ? { action: 'allow', note: 'principal:not-blocked' }
+      : { action: 'reject', reason: 'claim_conflict' };
+  }
+  return conflict.requestedMode === 'notify'
+    ? { action: 'notify', reason: 'stale_notify_hold' }
+    : { action: 'reject', reason: 'stale_context' };
+}) satisfies ConflictPolicy;
+
+/**
+ * A ready-made policy that grants capability-gated preemption. When the
+ * committer's capability allowlist includes the `claim.preempt` operation, a
+ * `claim_held` conflict is preempted: the current holder is evicted and the
+ * committer takes the lease. Every other conflict falls back to
+ * {@link defaultPolicy}, which rejects. Register it as your conflict policy to
+ * let a privileged identity take over a held entity without writing a bespoke
+ * policy. The authorization rests on holding the capability, not on any
+ * particular identity string.
+ */
+export const capabilityPreemptPolicy: ConflictPolicy = (conflict) => {
+  if (
+    conflict.kind === 'claim_held' &&
+    conflict.committerOperations.includes('claim.preempt')
+  ) {
+    return { action: 'preempt', reason: 'capability:claim.preempt' };
+  }
+  return defaultPolicy(conflict);
+};
+
+/**
+ * A model's declared conflict disposition, keyed by the kind of committer. You
+ * set it in the model's schema, for example
+ * `conflict: { user: 'overwrite', agent: 'reject' }`, and the engine applies it
+ * at commit time. It is plain data using the same `'reject' | 'overwrite' |
+ * 'notify'` vocabulary as the write guards, so it travels through the schema
+ * registry to the server without naming any application model.
+ *
+ * Each key is the committer's participant kind, which the server derives and a
+ * client cannot forge; an omitted kind falls back to the engine default. So
+ * `{ user: 'overwrite', agent: 'reject' }` reads as "a human's write wins, an
+ * agent's write yields," and `system`, being unlisted, takes the default.
+ */
+export interface ConflictAxis {
+  /** What happens when a human (`user` session) commits into a conflict. */
+  readonly user?: OnStaleMode;
+  /** What happens when an AI `agent` commits into a conflict. */
+  readonly agent?: OnStaleMode;
+  /** What happens when a `system` / automation actor commits into a conflict. */
+  readonly system?: OnStaleMode;
+}
+
+/**
+ * The same three members reach the server as `conflictAxisWireSchema`, which is
+ * a runtime-validatable zod object rather than an interface — `wire/` is the
+ * protocol leaf and cannot import this file, so the two are stated separately
+ * and pinned to each other here, on the side of the edge that is allowed to
+ * cross. A member added to one and not the other stops compiling.
+ *
+ * The import is type-only and erases, so nothing in the policy layer pulls the
+ * wire module in at runtime.
+ */
+type _ConflictAxisMatchesWire =
+  z.infer<typeof conflictAxisWireSchema> extends ConflictAxis ? true : never;
+type _WireMatchesConflictAxis =
+  ConflictAxis extends z.infer<typeof conflictAxisWireSchema> ? true : never;
+const _conflictAxisPinned: [_ConflictAxisMatchesWire, _WireMatchesConflictAxis] = [true, true];
+void _conflictAxisPinned;
+
+/**
+ * Resolves a declared {@link ConflictAxis} into a {@link ConflictDecision} for
+ * one concrete conflict. It is pure and synchronous, doing no I/O, so it can
+ * run on either the client or the server. It reads the committer's kind from
+ * the conflict and maps the declared mode:
+ *
+ *   - undefined   → the engine default, {@link defaultPolicy}: a human is
+ *                   allowed, an agent or system committer is rejected on a
+ *                   `claim_held`, and a stale write honors `onStale: 'notify'`.
+ *   - `overwrite` → `allow`; the write wins and the committer is never blocked.
+ *   - `reject`    → `reject`; the committer yields.
+ *   - `notify`    → on a `stale_context` conflict, hold the write and notify so
+ *                   the committer re-reads and re-applies; on a `claim_held`
+ *                   conflict there is no held write to reconcile (see
+ *                   {@link ConflictDecision} `notify`), so it degrades to
+ *                   `reject` rather than silently writing to a claimed row.
+ *
+ * This is only the generic interpretation. Stronger server-side rules — such as
+ * an agent never bypassing a claim held by someone else — are enforced where
+ * the decision is applied, not here.
+ */
+export function interpretConflictAxis(
+  axis: ConflictAxis,
+  conflict: Conflict,
+): ConflictDecision {
+  const mode = axis[conflict.committer.kind];
+  if (mode === undefined) return defaultPolicy(conflict);
+  switch (mode) {
+    case 'overwrite':
+      return { action: 'allow', note: 'conflict:overwrite' };
+    case 'reject':
+      return {
+        action: 'reject',
+        reason: conflict.kind === 'claim_held' ? 'claim_conflict' : 'stale_context',
+      };
+    case 'notify':
+      return conflict.kind === 'stale_context'
+        ? { action: 'notify', reason: 'stale_notify_hold' }
+        : { action: 'reject', reason: 'claim_conflict' };
+    default: {
+      // Exhaustiveness backstop: a future `OnStaleMode` member surfaces as a
+      // localized compile error here, not a missing-return at the signature.
+      const _exhaustive: never = mode;
+      return _exhaustive;
+    }
+  }
+}
+

package/src/resources/functionalUpdate.ts

@@ -0,0 +1,151 @@
+/**
+ * The functional update — `ablo.<model>.update(id, current => next)`.
+ *
+ * This is the surface that just works under contention. You express only your
+ * intent — given the latest row, here is the next state — and the client does
+ * the rest: it reads the fresh row and its watermark, runs your updater, writes
+ * the result as a compare-and-swap against that watermark, and on any concurrent
+ * write it re-reads, recomputes, and retries. No claim, no identity, no transport
+ * awareness, and no `stale_context` or `claim_*` error codes ever reach the
+ * caller. The write either lands or, at the extreme, throws a single
+ * {@link AbloContentionError} once the reconcile budget is spent.
+ *
+ * Correctness comes from the `readAt` watermark plus `onStale: 'reject'`
+ * (optimistic concurrency, or compare-and-swap), not from participant identity.
+ * That is why it is immune to the shared-credential silent-overwrite hazard and
+ * behaves identically on both transports: the HTTP and WebSocket clients inject
+ * the same two functions ({@link ReconcileTransport}) into the shared loop below,
+ * so the guarantee cannot drift between them — only the mechanism differs.
+ *
+ * The mental model is React's `setState(prev => next)`: pass a function of the
+ * current state and the runtime owns reconciliation.
+ */
+
+import {
+  AbloError,
+  AbloNotFoundError,
+  AbloStaleContextError,
+  AbloClaimedError,
+  AbloContentionError,
+} from '../errors.js';
+
+/**
+ * The functional form of an update: given the freshly-read row, return the
+ * fields to write. Return `null` or `undefined` to make no write — a no-op the
+ * caller chose after seeing the latest state (for example, "already done").
+ */
+export type ModelUpdater<T> = (
+  current: T,
+) => Partial<T> | null | undefined | Promise<Partial<T> | null | undefined>;
+
+/** Tuning for the functional update's internal reconcile loop. */
+export interface ContentionOptions {
+  /**
+   * Max reconcile rounds under contention before throwing
+   * {@link AbloContentionError}. Each round re-reads the latest row and re-runs
+   * your updater. Defaults to {@link DEFAULT_CONTENTION_RETRIES}.
+   */
+  readonly retries?: number;
+  /** Abort the reconcile loop (e.g. the request was cancelled). */
+  readonly signal?: AbortSignal;
+}
+
+/** Reconcile rounds before a hot row is declared permanently contended. */
+export const DEFAULT_CONTENTION_RETRIES = 16;
+
+/**
+ * Reports whether a thrown error means "another writer moved the row — re-read
+ * and retry" rather than a genuine failure to surface. These are the
+ * optimistic-concurrency signals the functional update reconciles against:
+ *   - `stale_context` — the `readAt` watermark was overtaken by a concurrent write
+ *   - `claim_lost`    — a holder preempted the write (for example a human under `humansOverwrite`)
+ *   - `claim_queued`  — a holder is actively editing the row right now
+ */
+export function isReconcilableConflict(err: unknown): boolean {
+  if (err instanceof AbloStaleContextError) return true;
+  if (err instanceof AbloClaimedError) {
+    return err.code === 'claim_lost' || err.code === 'claim_queued';
+  }
+  return false;
+}
+
+const sleep = (ms: number): Promise<void> =>
+  new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Jittered backoff so N reconcilers retrying at once don't lock-step straight
+ * back into the same collision. Bounded; grows mildly with the attempt.
+ */
+function backoffMs(attempt: number): number {
+  return 60 + attempt * 40 + Math.floor(Math.random() * 60);
+}
+
+/**
+ * The transport-specific read and write that the shared loop drives. Each client
+ * injects its own pair — the one thing that differs between the HTTP and
+ * WebSocket transports.
+ */
+export interface ReconcileTransport<T, R> {
+  readonly model: string;
+  readonly id: string;
+  /** Read the latest row and its watermark from the authoritative store. */
+  readFresh: () => Promise<{ readonly data: T | null | undefined; readonly stamp: number }>;
+  /**
+   * Write the computed patch as a compare-and-swap against `readAt`. It must
+   * throw a reconcilable conflict (`stale_context` or `claim_*`) when the
+   * watermark was overtaken — that rejection is what drives the next reconcile
+   * round.
+   */
+  writeNext: (patch: Partial<T>, readAt: number) => Promise<R>;
+}
+
+/**
+ * Run the read-fresh → compute → compare-and-swap → reconcile loop. Shared by
+ * both transports so the guarantee is provably identical. Returns the write's
+ * result, or `undefined` when the updater opted out of writing.
+ */
+export async function reconcileFunctionalUpdate<T, R>(
+  updater: ModelUpdater<T>,
+  options: ContentionOptions | undefined,
+  transport: ReconcileTransport<T, R>,
+): Promise<R | undefined> {
+  const retries = options?.retries ?? DEFAULT_CONTENTION_RETRIES;
+  let lastConflict: unknown;
+
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    if (options?.signal?.aborted) {
+      throw new AbloError(
+        `Update of ${transport.model}/${transport.id} was aborted before it landed.`,
+        { code: 'update_aborted' },
+      );
+    }
+
+    const { data, stamp } = await transport.readFresh();
+    if (data == null) {
+      throw new AbloNotFoundError(
+        `Cannot update ${transport.model}/${transport.id}: it does not exist (or is ` +
+          `outside this credential's scope).`,
+        [transport.id],
+      );
+    }
+
+    const patch = await updater(data);
+    if (patch == null) return undefined; // updater opted out after reading fresh
+
+    try {
+      return await transport.writeNext(patch, stamp);
+    } catch (err) {
+      if (!isReconcilableConflict(err)) throw err; // genuine failure — surface it
+      lastConflict = err;
+      if (attempt < retries) await sleep(backoffMs(attempt));
+    }
+  }
+
+  throw new AbloContentionError(transport.model, transport.id, retries + 1, {
+    cause: lastConflict,
+  });
+}
+
+// Re-exported so call sites import the loop and its terminal error from one
+// place; the class itself lives with the rest of the error hierarchy.
+export { AbloContentionError };