@abloatai/ablo 0.18.0 → 0.20.0

package/dist/coordination/trace.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Claim log — the easy way to SEE agents colliding.
+ *
+ * The engine emits the claim lifecycle (`acquired → queued → granted → lost /
+ * rejected / expired`) and the notify-instead-of-abort stale-write collision
+ * through two seams: human `logger` lines (visible with `new Ablo({ debug: true })`)
+ * and structured `observability.captureClaim` / `captureConflict` calls.
+ *
+ * This is the third, evals-shaped path: hand a {@link ClaimLog} to
+ * `Ablo({ observability })`, run your scenario, then read back an ordered list
+ * you can print for eyeballing or `collisions()` for assertions.
+ */
+import type { SyncObservabilityProvider, ClaimEvent, ConflictEvent } from '../interfaces/index.js';
+/** A claim state change as one quiet, greppable line. */
+export declare function formatClaim(e: ClaimEvent): string;
+/** A notify-instead-of-abort stale write as one readable line. */
+export declare function formatConflict(e: ConflictEvent): string;
+/** 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 seams 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 full {@link SyncObservabilityProvider} (every method it does not
+ * care about is an inert no-op), so it drops straight into the `observability`
+ * slot with no adapter.
+ */
+export declare class ClaimLog implements SyncObservabilityProvider {
+    private readonly max;
+    private rows;
+    private seq;
+    private readonly listeners;
+    /** Cap the buffer so a long-running session can't grow unbounded. */
+    constructor(max?: number);
+    captureClaim(claim: ClaimEvent): void;
+    captureConflict(conflict: ConflictEvent): void;
+    /**
+     * 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);
+    /** The full ordered list. Stable reference until the next event lands. */
+    get entries(): readonly ClaimLogEntry[];
+    /** Only the collisions: rejected/lost claims + stale writes. */
+    collisions(): readonly ClaimLogEntry[];
+    /** Drop everything — useful between scenarios in one process. */
+    clear(): void;
+    /** Printable: one event per line, collisions marked. */
+    toString(): string;
+    private add;
+    private notify;
+    setContext(): void;
+    setConnectionState(): void;
+    breadcrumb(): void;
+    captureRollback(): void;
+    captureTransactionFailure(): void;
+    captureBootstrapFailure(): void;
+    captureReconciliation(): void;
+    captureDeltaRetryExhausted(): void;
+    captureWebSocketError(): void;
+    captureOfflineFlushFailure(): void;
+    captureSelfHealing(): void;
+    captureCommitZeroSyncId(): void;
+    startSpan<T>(_name: string, _op: string, fn: () => T): T;
+    startSpanAsync<T>(_name: string, _op: string, fn: () => Promise<T>): Promise<T>;
+}

package/dist/coordination/trace.js

@@ -0,0 +1,147 @@
+/**
+ * Claim log — the easy way to SEE agents colliding.
+ *
+ * The engine emits the claim lifecycle (`acquired → queued → granted → lost /
+ * rejected / expired`) and the notify-instead-of-abort stale-write collision
+ * through two seams: human `logger` lines (visible with `new Ablo({ debug: true })`)
+ * and structured `observability.captureClaim` / `captureConflict` calls.
+ *
+ * This is the third, evals-shaped path: hand a {@link ClaimLog} to
+ * `Ablo({ observability })`, run your scenario, then read back an ordered list
+ * you can print for eyeballing or `collisions()` for assertions.
+ */
+// ─────────────────────────────────────────────
+// Formatters — one readable line per event. Shared by the WS logger seam and
+// the log so console output and log output never drift.
+// ─────────────────────────────────────────────
+/** A claim state change as one quiet, greppable line. */
+export function formatClaim(e) {
+    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}]` : '';
+    const actor = e.actor
+        ? `${e.actor}${e.participantKind ? ` (${e.participantKind})` : ''}`
+        : '';
+    // `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}`
+        : '';
+    const why = e.reason ? `: ${e.reason}` : '';
+    return `claim ${e.phase}: ${target}${scope}${pos}${by}${why}`;
+}
+/** A notify-instead-of-abort stale write as one readable line. */
+export function formatConflict(e) {
+    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}` : ''}`;
+}
+/**
+ * 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 full {@link SyncObservabilityProvider} (every method it does not
+ * care about is an inert no-op), so it drops straight into the `observability`
+ * slot with no adapter.
+ */
+export class ClaimLog {
+    max;
+    // 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.
+    rows = [];
+    seq = 0;
+    listeners = new Set();
+    /** Cap the buffer so a long-running session can't grow unbounded. */
+    constructor(max = 1_000) {
+        this.max = max;
+    }
+    // —— the two seams we record ——
+    captureClaim(claim) {
+        this.add({
+            line: formatClaim(claim),
+            collision: claim.phase === 'rejected' || claim.phase === 'lost',
+            claim,
+        });
+    }
+    captureConflict(conflict) {
+        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>;
+     * ```
+     */
+    onChange = (listener) => {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    };
+    // —— inspection ——
+    /** The full ordered list. Stable reference until the next event lands. */
+    get entries() {
+        return this.rows;
+    }
+    /** Only the collisions: rejected/lost claims + stale writes. */
+    collisions() {
+        return this.rows.filter((e) => e.collision);
+    }
+    /** Drop everything — useful between scenarios in one process. */
+    clear() {
+        this.rows = [];
+        this.seq = 0;
+        this.notify();
+    }
+    /** Printable: one event per line, collisions marked. */
+    toString() {
+        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');
+    }
+    add(entry) {
+        const next = [...this.rows, { seq: this.seq++, ...entry }];
+        this.rows = next.length > this.max ? next.slice(next.length - this.max) : next;
+        this.notify();
+    }
+    notify() {
+        for (const listener of this.listeners)
+            listener();
+    }
+    // —— inert provider surface (this log only cares about claims) ——
+    setContext() { }
+    setConnectionState() { }
+    breadcrumb() { }
+    captureRollback() { }
+    captureTransactionFailure() { }
+    captureBootstrapFailure() { }
+    captureReconciliation() { }
+    captureDeltaRetryExhausted() { }
+    captureWebSocketError() { }
+    captureOfflineFlushFailure() { }
+    captureSelfHealing() { }
+    captureCommitZeroSyncId() { }
+    startSpan(_name, _op, fn) {
+        return fn();
+    }
+    startSpanAsync(_name, _op, fn) {
+        return fn();
+    }
+}

package/dist/errorCodes.d.ts

@@ -135,6 +135,7 @@ export declare const ERROR_CODES: {
     readonly browser_database_url_blocked: ErrorCodeSpec;
     readonly datasource_registration_failed: ErrorCodeSpec;
     readonly datasource_connection_unsupported: ErrorCodeSpec;
+    readonly datasource_direct_deprecated: ErrorCodeSpec;
     readonly capability_scope_denied: ErrorCodeSpec;
     readonly issuer_register_forbidden: ErrorCodeSpec;
     readonly capability_invalid: ErrorCodeSpec;
@@ -188,6 +189,7 @@ export declare const ERROR_CODES: {
     readonly unique_violation: ErrorCodeSpec;
     readonly check_violation: ErrorCodeSpec;
     readonly constraint_violation: ErrorCodeSpec;
+    readonly column_type_mismatch: ErrorCodeSpec;
     readonly server_execute_unknown_model: ErrorCodeSpec;
     readonly mutate_create_unknown_model: ErrorCodeSpec;
     readonly tenant_model_columns_unknown: ErrorCodeSpec;

package/dist/errorCodes.js

@@ -125,6 +125,7 @@ export const ERROR_CODES = {
     browser_database_url_blocked: client('auth', 'A database connection string must not be used from a browser context — it carries DB credentials.'),
     datasource_registration_failed: client('auth', 'Failed to register the provided databaseUrl as a datasource.'),
     datasource_connection_unsupported: wire('validation', 400, false, 'This deployment cannot register a direct (connection string) datasource — use the signed endpoint kind.'),
+    datasource_direct_deprecated: wire('validation', 410, false, 'The direct (connection string) datasource is deprecated. Register a signed Data Source endpoint instead — your app owns the write and your credentials never leave it.'),
     // ── permission / capability (403) ──────────────────────────────────
     capability_scope_denied: wire('capability', 403, false, "The connection's resolved scope does not cover the attempted action."),
     issuer_register_forbidden: wire('permission', 403, false, 'Registering a trusted issuer requires a secret (sk_) API key.'),
@@ -201,6 +202,7 @@ export const ERROR_CODES = {
     unique_violation: wire('conflict', 409, false, 'A value violates a uniqueness constraint.'),
     check_violation: wire('validation', 400, false, 'A value violates a database check constraint.'),
     constraint_violation: wire('validation', 400, false, 'A database integrity constraint was violated.'),
+    column_type_mismatch: wire('validation', 400, false, 'A structured (JSON) value was written to a column whose database type cannot hold it. Ablo adapts a json field to either a jsonb column (native) or a text column (serialized) — but a scalar column (integer, boolean, uuid, timestamp, …) cannot store a JSON object or array. Use a jsonb or text column for this field. Ablo adapts to your column; it does not alter your schema.'),
     // ── tenant / unknown model (400) ───────────────────────────────────
     server_execute_unknown_model: wire('tenant', 400, false, 'Wrote to a model the server does not know. The server keeps its own copy of the schema — run `ablo push` (or keep `ablo dev` running) to upload `ablo/schema.ts` before writing to new or changed models.'),
     mutate_create_unknown_model: wire('tenant', 400, false, 'Created a model the server does not know. Run `ablo push` (or keep `ablo dev` running) to upload `ablo/schema.ts` first — the server keeps its own copy of the schema.'),

package/dist/errors.d.ts

@@ -185,8 +185,7 @@ export interface ClaimContext {
     readonly claimId?: string;
     readonly actor?: string;
     readonly participantKind?: ParticipantKind;
-    /** Human-readable phase the holder is in (`'editing'`). Matches the public
-     *  claim surface; the wire summary carries the same value as `action`. */
+    /** Human-readable phase the holder is in (`'editing'`). */
     readonly reason?: string;
     readonly description?: string;
     readonly field?: string;

package/dist/errors.js

@@ -196,13 +196,10 @@ export class AbloStaleContextError extends AbloError {
             this.conflicts = options.conflicts;
     }
 }
-function claimAction(claim) {
+function claimReason(claim) {
     if (!claim)
         return undefined;
-    // The public `ClaimContext` exposes the phase as `reason`; the wire
-    // `WireClaimSummary` projection still carries it under `action`. Read both.
-    const c = claim;
-    return c.reason ?? c.action;
+    return claim.reason;
 }
 function claimDescription(claim) {
     if (!claim)
@@ -229,20 +226,20 @@ function secondsUntil(ms, now = Date.now()) {
 }
 export function formatClaimedErrorMessage(args) {
     const holder = claimActor(args.claim, args.heldBy);
-    const action = claimAction(args.claim);
+    const reason = claimReason(args.claim);
     const description = claimDescription(args.claim);
     const expiresIn = secondsUntil(claimExpiresAt(args.claim));
-    if (!holder && !action && !description) {
+    if (!holder && !reason && !description) {
         return args.fallback ?? `Model row is claimed: ${args.targetLabel}.`;
     }
     const actor = holder ?? 'another participant';
-    const actionPart = action ? ` (${action})` : '';
+    const reasonPart = reason ? ` (${reason})` : '';
     const descriptionPart = description ? `: ${description}` : '';
     const expiresPart = expiresIn !== undefined ? ` - expires in ${expiresIn}s` : '';
     const policyPart = args.policyReason
         ? ` Policy reason: ${args.policyReason}.`
         : '';
-    return `Claimed by ${actor}${actionPart}${descriptionPart}${expiresPart} on ${args.targetLabel}.${policyPart}`;
+    return `Claimed by ${actor}${reasonPart}${descriptionPart}${expiresPart} on ${args.targetLabel}.${policyPart}`;
 }
 /**
  * The target entity is currently claimed by another participant and the caller

package/dist/index.d.ts

@@ -52,7 +52,7 @@ export type { MutationExecutor } from './interfaces/index.js';
 export type { HttpClaimApi, InternalAbloOptions } from './client/Ablo.js';
 export { type AbloHttpClientOptions, type AbloHttpClient, type HttpModelClient, } from './client/httpClient.js';
 export { ABLO_DEFAULT_BASE_URL, ABLO_HOSTED_API_DOMAIN, ABLO_HOSTED_HTTP_BASE_URL, normalizeAbloHostedBaseUrl, } from './client/auth.js';
-export type { AbloOptions, LocalCountOptions, LocalReadOptions, ModelListScope, ServerReadOptions, ModelRetrieveParams, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, ClaimOptions, ClaimParams, ClaimLookupParams, ClaimReorderParams, ClaimHandle, ModelOperations, } from './client/Ablo.js';
+export type { AbloOptions, LocalCountOptions, LocalReadOptions, ModelListScope, ServerReadOptions, ModelRetrieveParams, ModelCreateParams, ModelUpdateParams, ModelDeleteParams, ClaimOptions, ClaimParams, ClaimLookupParams, ClaimReorderParams, Claim, ModelOperations, } from './client/Ablo.js';
 export type { AbloPersistence } from './client/persistence.js';
 import { Ablo } from './client/Ablo.js';
 export default Ablo;
@@ -72,9 +72,14 @@ export type { WriteOptionsInput } from './client/writeOptionsSchema.js';
 export type { WriteOptions, MutationOptions } from './interfaces/index.js';
 export { staleNotificationSchema, readDependencySchema } from './coordination/schema.js';
 export type { StaleNotification, ReadDependency } from './coordination/schema.js';
+export { ClaimLog, formatClaim, formatConflict } from './coordination/trace.js';
+export type { ClaimLogEntry } from './coordination/trace.js';
+export type { ClaimEvent, ConflictEvent, SyncObservabilityProvider, } from './interfaces/index.js';
+export { noopObservability } from './SyncEngineContext.js';
 export { IDBOpenTimeoutError, isStorageOpenTimeout } from './core/openIDBWithTimeout.js';
 export { PUBLIC_MODEL_VERBS, PUBLIC_LIST_OPTION_KEYS, PUBLIC_ABLO_OPTION_KEYS, } from './surface.js';
 export type { ModelVerb, ListOptionKey, AbloOptionKey } from './surface.js';
 export type { Register, DefaultSyncShape } from './types/global.js';
 export { defineMutators } from './mutators/defineMutators.js';
 export { createTransaction, type Transaction } from './mutators/Transaction.js';
+export { deepEqual, stableStringify } from './utils/json.js';

package/dist/index.js

@@ -104,6 +104,13 @@ export { writeOptionsSchema, onStaleModeSchema, assertWriteOptions, } from './cl
 // agent can self-heal rather than discard work (see coordination/schema.ts and
 // docs/coordination.md → "Notify, do not abort").
 export { staleNotificationSchema, readDependencySchema } from './coordination/schema.js';
+// Claim log — collect claim events + stale-write collisions into an ordered list
+// you can print for eyeballing or collisions() for evals assertions. Hand
+// `new ClaimLog()` to `Ablo({ observability })`.
+export { ClaimLog, formatClaim, formatConflict } from './coordination/trace.js';
+// Spread this to provide a custom `observability` that overrides only the hooks
+// you care about (e.g. captureClaim) and no-ops the rest.
+export { noopObservability } from './SyncEngineContext.js';
 // Storage-wedge detection — lets app shells render a recovery screen when the
 // IndexedDB backing store is stuck (see core/openIDBWithTimeout.ts).
 export { IDBOpenTimeoutError, isStorageOpenTimeout } from './core/openIDBWithTimeout.js';
@@ -127,3 +134,9 @@ export { defineMutators } from './mutators/defineMutators.js';
 export { createTransaction } from './mutators/Transaction.js';
 // Undo runtime is intentionally not part of the public root surface. App code
 // uses `useUndoScope` from `@abloatai/ablo/react`.
+// JSON comparison helpers. A `field.json()` value backed by a Postgres `jsonb`
+// column round-trips with reordered object keys (jsonb doesn't preserve key
+// order), so a naive `JSON.stringify(a) === JSON.stringify(b)` guard misfires
+// when an app reconciles an Ablo row against external editor state. Use these
+// (key-order-insensitive) instead. See `utils/json.ts` for the full rationale.
+export { deepEqual, stableStringify } from './utils/json.js';

package/dist/interfaces/index.d.ts

@@ -5,7 +5,7 @@
  * Consumers implement them to wire in their own logging, observability,
  * GraphQL client, session handling, and analytics.
  */
-import type { StaleNotification, ReadDependency } from '../coordination/schema.js';
+import type { StaleNotification, ReadDependency, ParticipantKind } from '../coordination/schema.js';
 export interface SyncLogger {
     debug(message: string, ...args: unknown[]): void;
     info(message: string, ...args: unknown[]): void;
@@ -15,7 +15,7 @@ export interface SyncLogger {
 /** Breadcrumb severity levels */
 export type BreadcrumbLevel = 'debug' | 'info' | 'warning' | 'error';
 /** Breadcrumb categories for sync engine lifecycle events */
-export type SyncBreadcrumbCategory = 'sync.bootstrap' | 'sync.transaction' | 'sync.websocket' | 'sync.offline' | 'sync.database' | 'sync.conflict' | 'sync.groups';
+export type SyncBreadcrumbCategory = 'sync.bootstrap' | 'sync.transaction' | 'sync.websocket' | 'sync.offline' | 'sync.database' | 'sync.conflict' | 'sync.coordination' | 'sync.groups';
 export interface RollbackDetails {
     transactionType: string;
     modelName: string;
@@ -71,6 +71,45 @@ export interface CommitZeroSyncIdDetails {
 export interface OfflineFlushFailureDetails {
     error: string;
 }
+/**
+ * One thing that happened to a claim. `phase` is the past-tense state it just
+ * entered — the trail you follow to see WHY two participants collided on a row:
+ * who asked, who waited behind whom, who was turned away, whose lease lapsed.
+ * Each phase mirrors a `claim_*` wire frame.
+ */
+export interface ClaimEvent {
+    phase: 'acquired' | 'queued' | 'granted' | 'lost' | 'rejected' | 'expired';
+    /** Server claim id, when the frame carries one. */
+    claimId?: string;
+    /** The claimed row + optional field scope. */
+    model?: string;
+    id?: string;
+    field?: string;
+    /** Participant that owns or blocks the lease (on `rejected`, the holder). */
+    actor?: string;
+    participantKind?: ParticipantKind;
+    /** FIFO position when `queued`. */
+    position?: number;
+    /** Rejection or policy reason, when the server supplied one. */
+    reason?: string;
+}
+/**
+ * A committed `onStale: 'notify'` write whose premise moved — the in-flight twin
+ * of a claim collision. The commit SUCCEEDED, but the guarded ops weren't written
+ * because the row changed since the caller's `readAt`; the engine handed back the
+ * live value so the actor can self-heal. Records WHICH rows and fields collided.
+ */
+export interface ConflictEvent {
+    /** The client idempotency key whose write was notified. */
+    clientTxId: string;
+    /** The conflicted rows + the fields that collided. */
+    rows: ReadonlyArray<{
+        model: string;
+        id: string;
+        fields: readonly string[];
+        writtenBy?: ParticipantKind;
+    }>;
+}
 /** Span attributes for performance monitoring */
 export interface SpanAttributes {
     [key: string]: string | number | boolean | undefined;
@@ -102,6 +141,10 @@ export interface SyncObservabilityProvider {
     captureOfflineFlushFailure(details: OfflineFlushFailureDetails): void;
     /** Capture self-healing event */
     captureSelfHealing(details: SelfHealingDetails): void;
+    /** 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;
     /** Capture commit returning lastSyncId: 0 */
     captureCommitZeroSyncId(details: CommitZeroSyncIdDetails): void;
     /** Wrap a synchronous function in a performance span */

package/dist/mutators/undoApply.d.ts

@@ -24,6 +24,7 @@
  */
 import type { SyncStoreContract } from '../react/context.js';
 import type { InverseOp } from './inverseOp.js';
+import { deepEqual } from '../utils/json.js';
 /**
  * How undo/redo handles a field a collaborator changed after your op:
  *   - `skip-stale` (default): leave it — your change is already superseded, so
@@ -33,8 +34,12 @@ import type { InverseOp } from './inverseOp.js';
  */
 export type UndoConflictPolicy = 'skip-stale' | 'last-writer-wins';
 export declare const DEFAULT_UNDO_CONFLICT_POLICY: UndoConflictPolicy;
-/** Structural equality for JSON-shaped values (scalars, arrays, plain objects). */
-export declare function deepEqual(a: unknown, b: unknown): boolean;
+/**
+ * Structural equality for JSON-shaped values (scalars, arrays, plain objects).
+ * Re-exported from the shared `utils/json` helper (key order is ignored) so the
+ * undo path and app authors share one implementation.
+ */
+export { deepEqual };
 /**
  * Filter the ops to apply so they don't clobber concurrent collaborator edits.
  * See the module docblock. `last-writer-wins` returns the ops unchanged.

package/dist/mutators/undoApply.js

@@ -22,42 +22,14 @@
  * With no collaborator, the live value always equals what you set, so nothing
  * is dropped — single-user undo is byte-for-byte unchanged.
  */
+import { deepEqual } from '../utils/json.js';
 export const DEFAULT_UNDO_CONFLICT_POLICY = 'skip-stale';
-/** Structural equality for JSON-shaped values (scalars, arrays, plain objects). */
-export function deepEqual(a, b) {
-    if (a === b)
-        return true;
-    if (a === null || b === null || typeof a !== 'object' || typeof b !== 'object') {
-        return false;
-    }
-    const aArr = Array.isArray(a);
-    if (aArr !== Array.isArray(b))
-        return false;
-    if (aArr) {
-        const av = a;
-        const bv = b;
-        if (av.length !== bv.length)
-            return false;
-        for (let i = 0; i < av.length; i++) {
-            if (!deepEqual(av[i], bv[i]))
-                return false;
-        }
-        return true;
-    }
-    const ao = a;
-    const bo = b;
-    const ak = Object.keys(ao);
-    const bk = Object.keys(bo);
-    if (ak.length !== bk.length)
-        return false;
-    for (const k of ak) {
-        if (!Object.prototype.hasOwnProperty.call(bo, k))
-            return false;
-        if (!deepEqual(ao[k], bo[k]))
-            return false;
-    }
-    return true;
-}
+/**
+ * Structural equality for JSON-shaped values (scalars, arrays, plain objects).
+ * Re-exported from the shared `utils/json` helper (key order is ignored) so the
+ * undo path and app authors share one implementation.
+ */
+export { deepEqual };
 /**
  * Map `id → { field: establishedValue }` from the paired ops. Only update-family
  * ops carry per-field values worth comparing.

package/dist/policy/types.d.ts

@@ -126,20 +126,28 @@ export type ConflictPolicy = (conflict: Conflict) => ConflictDecision | Promise<
  * default, not an opt-in.**
  *
  * A `claim_held` conflict resolves by the COMMITTER's kind. This default is, by
- * construction, identical to `coordination(humansOverwrite(), agentsReject())`
- * applied to every model — so a developer who wants different behaviour just
- * declares the conflict axis on that model (`humansReject()`, `humansNotify()`,
- * …) and it wins. The default and the override speak the same vocabulary; the
+ * construction, identical to `coordination(humansOverwrite())` applied to every
+ * model — so a developer who wants different behaviour just declares the conflict
+ * axis on that model (`humansReject()`, `humansNotify()`, `systemOverwrite()`, …)
+ * and it wins. The default and the override speak the same vocabulary; the
  * default is the one you get for free.
  *
  *   • `user`   → `allow`  — a human is never blocked by a claim (a claim is a
  *                           coordination hint among agents, not a lock on people)
- *   • `system` → `allow`  — automation principals at the root of a trust chain
- *                           behave like humans here (matches `mayBypassClaims`)
  *   • `agent`  → `reject` — an agent yields to a foreign claim (the no-bypass
  *                           invariant; the ONLY sanctioned agent override is the
  *                           privileged `claim.preempt` capability seam, see
  *                           {@link capabilityPreemptPolicy})
+ *   • `system` → `reject` — automation / backend (`sk_`) writers SERIALIZE
+ *                           through claims by default like agents do, so a server
+ *                           job can't silently steamroll a held row. Opt a model
+ *                           in with `systemOverwrite()` when that's wanted.
+ *
+ * Scope note: only `user` is allowed by default — that is the exact Law 7
+ * decision ("a human is never blocked"). `system` is deliberately NOT a
+ * free-bypass: `sk_` keys are full-access backend credentials, and a foundational
+ * contract (claim serialization / the retry-storm guard) depends on them
+ * respecting claims unless a model says otherwise.
  *
  * `stale_context` conflicts honor the committer's declared `onStale` intent:
  *
@@ -186,9 +194,10 @@ export interface ConflictAxis {
  * synchronous (no I/O), so it runs on either side of the schema-agnostic
  * boundary. Looks up the committer's kind and maps the declared `OnStaleMode`:
  *
- *   - undefined   → the engine default (`defaultPolicy`: Law 7 — a human/system
- *                   committer is allowed (never blocked), an agent rejects on a
- *                   `claim_held`; on a stale write, honor `onStale: 'notify'`)
+ *   - undefined   → the engine default (`defaultPolicy`: Law 7 — a human (`user`)
+ *                   committer is allowed (never blocked); `agent` and `system`
+ *                   reject on a `claim_held`; on a stale write, honor
+ *                   `onStale: 'notify'`)
  *   - `overwrite` → `allow` — the write wins / the committer is never blocked
  *   - `reject`    → `reject` — the committer yields
  *   - `notify`    → on `stale_context`: notify + hold (re-read & re-apply);

package/dist/policy/types.js

@@ -11,20 +11,28 @@
  * default, not an opt-in.**
  *
  * A `claim_held` conflict resolves by the COMMITTER's kind. This default is, by
- * construction, identical to `coordination(humansOverwrite(), agentsReject())`
- * applied to every model — so a developer who wants different behaviour just
- * declares the conflict axis on that model (`humansReject()`, `humansNotify()`,
- * …) and it wins. The default and the override speak the same vocabulary; the
+ * construction, identical to `coordination(humansOverwrite())` applied to every
+ * model — so a developer who wants different behaviour just declares the conflict
+ * axis on that model (`humansReject()`, `humansNotify()`, `systemOverwrite()`, …)
+ * and it wins. The default and the override speak the same vocabulary; the
  * default is the one you get for free.
  *
  *   • `user`   → `allow`  — a human is never blocked by a claim (a claim is a
  *                           coordination hint among agents, not a lock on people)
- *   • `system` → `allow`  — automation principals at the root of a trust chain
- *                           behave like humans here (matches `mayBypassClaims`)
  *   • `agent`  → `reject` — an agent yields to a foreign claim (the no-bypass
  *                           invariant; the ONLY sanctioned agent override is the
  *                           privileged `claim.preempt` capability seam, see
  *                           {@link capabilityPreemptPolicy})
+ *   • `system` → `reject` — automation / backend (`sk_`) writers SERIALIZE
+ *                           through claims by default like agents do, so a server
+ *                           job can't silently steamroll a held row. Opt a model
+ *                           in with `systemOverwrite()` when that's wanted.
+ *
+ * Scope note: only `user` is allowed by default — that is the exact Law 7
+ * decision ("a human is never blocked"). `system` is deliberately NOT a
+ * free-bypass: `sk_` keys are full-access backend credentials, and a foundational
+ * contract (claim serialization / the retry-storm guard) depends on them
+ * respecting claims unless a model says otherwise.
  *
  * `stale_context` conflicts honor the committer's declared `onStale` intent:
  *
@@ -41,13 +49,14 @@
 // `ConflictPolicy` everywhere it's used as a policy.
 export const defaultPolicy = ((conflict) => {
     if (conflict.kind === 'claim_held') {
-        // Law 7 universal default: principals (human / system) are never blocked;
-        // agents yield. Keeping `agent → reject` here is what makes the no-bypass
-        // invariant hold even on the registry/default resolution path (which, unlike
-        // the declared-axis path, has no separate agent-degradation guard).
-        return conflict.committer.kind === 'agent'
-            ? { action: 'reject', reason: 'claim_conflict' }
-            : { action: 'allow', note: 'principal:not-blocked' };
+        // Law 7 universal default: a human (`user`) is never blocked; agents AND
+        // system actors yield. Keeping every non-`user` kind on `reject` here is
+        // what makes the no-bypass invariant hold even on the registry/default
+        // resolution path (which, unlike the declared-axis path, has no separate
+        // agent-degradation guard).
+        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' }
@@ -73,9 +82,10 @@ export const capabilityPreemptPolicy = (conflict) => {
  * synchronous (no I/O), so it runs on either side of the schema-agnostic
  * boundary. Looks up the committer's kind and maps the declared `OnStaleMode`:
  *
- *   - undefined   → the engine default (`defaultPolicy`: Law 7 — a human/system
- *                   committer is allowed (never blocked), an agent rejects on a
- *                   `claim_held`; on a stale write, honor `onStale: 'notify'`)
+ *   - undefined   → the engine default (`defaultPolicy`: Law 7 — a human (`user`)
+ *                   committer is allowed (never blocked); `agent` and `system`
+ *                   reject on a `claim_held`; on a stale write, honor
+ *                   `onStale: 'notify'`)
  *   - `overwrite` → `allow` — the write wins / the committer is never blocked
  *   - `reject`    → `reject` — the committer yields
  *   - `notify`    → on `stale_context`: notify + hold (re-read & re-apply);