@abloatai/ablo 0.34.1 → 0.35.0

package/dist/{schema → transaction/schema}/schema.js

@@ -63,6 +63,7 @@ export const RESERVED_SESSION_SETTINGS = [
     'app.current_sandbox_id',
     'app.current_participant_id',
     'app.current_participant_kind',
+    'app.current_user_id',
 ];
 /**
  * Base fields every synced model gets automatically.
@@ -159,10 +160,10 @@ export function defineSchema(models, options) {
     // them at every call site.
     //
     // Defaults:
-    //   typename      ← schema key (e.g. `slideLayer` → `'slideLayer'`)
+    //   typename      ← schema key (e.g. `block` → `'block'`)
     //   persist.store ← typename (only resolved when `persist` was provided)
     //
-    // A consumer that passes `typename: 'SlideLayer'` explicitly (common when
+    // A consumer that passes `typename: 'Block'` explicitly (common when
     // the wire shape uses PascalCase while the schema key is camelCase) keeps
     // that value — the fallback only fires when the field is unset.
     //
@@ -266,7 +267,7 @@ function validateSyncGroupSchema(models) {
     for (const [name, def] of Object.entries(models)) {
         // Shape-validate the `scope` declaration via the shared Zod schema.
         if (def.scope !== undefined && !scopeSchema.safeParse(def.scope).success) {
-            throw new AbloValidationError(`Model "${name}": scope kind "${String(def.scope)}" must be a lowercase identifier (e.g. 'dataroom').`, { code: 'schema_scope_kind_invalid', param: `${name}.scope` });
+            throw new AbloValidationError(`Model "${name}": scope kind "${String(def.scope)}" must be a lowercase identifier (e.g. 'workspace').`, { code: 'schema_scope_kind_invalid', param: `${name}.scope` });
         }
         if (!def.grants)
             continue;

package/dist/{schema → transaction/schema}/tenancy.d.ts

@@ -26,7 +26,7 @@ import { z } from 'zod';
 export declare const DEFAULT_ORG_COLUMN = "organization_id";
 /**
  * Scopes a table's rows through a parent table, for rows that carry no tenancy
- * column of their own (for example, slide layers scoped through their slide, deck,
+ * column of their own (for example, blocks scoped through their section, report,
  * and organization). This is the canonical `parent` payload; authors write the
  * friendlier {@link PolicyInput} `{ by: 'parent', fk, parent }` form, which
  * {@link resolvePolicy} normalizes into this.

package/dist/{schema → transaction/schema}/tenancy.js

@@ -26,7 +26,7 @@ import { z } from 'zod';
 export const DEFAULT_ORG_COLUMN = 'organization_id';
 /**
  * Scopes a table's rows through a parent table, for rows that carry no tenancy
- * column of their own (for example, slide layers scoped through their slide, deck,
+ * column of their own (for example, blocks scoped through their section, report,
  * and organization). This is the canonical `parent` payload; authors write the
  * friendlier {@link PolicyInput} `{ by: 'parent', fk, parent }` form, which
  * {@link resolvePolicy} normalizes into this.
@@ -90,9 +90,9 @@ export const policyInputSchema = z
     by: z.enum(['column', 'parent', 'none', 'source']),
     /** `by: 'column'` — override the physical tenancy column name. Default {@link DEFAULT_ORG_COLUMN}. */
     column: z.string().min(1).optional(),
-    /** `by: 'parent'` — column on this table that points at the parent (for example, `'slideId'`). */
+    /** `by: 'parent'` — column on this table that points at the parent (for example, `'sectionId'`). */
     fk: z.string().min(1).optional(),
-    /** `by: 'parent'` — parent table name (e.g. `'slides'`). */
+    /** `by: 'parent'` — parent table name (e.g. `'sections'`). */
     parent: z.string().min(1).optional(),
     /** `by: 'parent'` — column on the parent that `fk` references. Default `'id'`. */
     parentKey: z.string().min(1).optional(),
@@ -138,7 +138,10 @@ export const policyInputSchema = z
         });
     }
 });
-const _policyInputAssignable = true;
+const _policyInputAssignable = [
+    true,
+    true,
+];
 void _policyInputAssignable;
 /**
  * Normalizes the authoring {@link PolicyInput} into the canonical {@link Tenancy}.

package/dist/transaction/transactionLayer.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The transaction layer's seam — the surface the sync engine (and any other
+ * caller) sits on. ADR 0013's thesis as an interface: the layer defines,
+ * orders, settles, and authorizes changes; it holds no materialised state.
+ *
+ * `observe()` is the whole seam in one method. The sync engine is `observe()`
+ * piped into a materializer — deltas → local store → IndexedDB → reactive
+ * re-render — plus local optimistic mutations reconciled against `commit()` /
+ * `settled()`. Everything reactive is downstream of that method; the
+ * transaction layer never calls up into it.
+ *
+ * `participant` stays the WHO (user | agent | system), never the name of this.
+ * The taught verbs map onto the seam directly: `create`/`update`/`delete` are
+ * operations inside a `commit()` payload; `claim` is `claim()`; `track` rides
+ * the commit payload's `track` field (a durable premise is a zero-operation
+ * commit). Presence (`join`) is deliberately absent: it is live observation
+ * over a socket, and it joins the seam when its core carrier type exists —
+ * see docs/plans/transaction-core-language.md, Tier 3.
+ *
+ * This is the contract, not a runtime: nothing in this package implements it
+ * yet. The first explicit implementation (a headless client, a test harness)
+ * gains a compile-time conformance pin against this interface.
+ */
+import type { CommitMessage } from './wire/frames.js';
+import type { CommitReceiptWire } from './wire/commit.js';
+import type { Delta, HeldClaim, ClaimTarget, ClaimLeaseOptions } from './types/streams.js';
+import type { ModelData } from './types/modelData.js';
+import type { ModelScope } from './types/index.js';
+/**
+ * A commit's durable acceptance — `{ status: 'queued' }` with the correlation
+ * the settlement feed later confirms. The wire layer names this
+ * {@link CommitReceiptWire}; the seam names it plainly.
+ */
+export type CommitReceipt = CommitReceiptWire;
+/**
+ * The seam's read grammar for {@link TransactionLayer.list} — filter, order,
+ * and page through settled rows. Mirrors the taught list options
+ * (`where` / `orderBy` / `limit` / `offset` / `state`) without binding the
+ * seam to the client's local-read machinery.
+ */
+export interface ListQuery {
+    /** Equality filter on field values. */
+    where?: ModelData;
+    /** Sort order, field → direction. */
+    orderBy?: Record<string, 'asc' | 'desc'>;
+    limit?: number;
+    offset?: number;
+    /** Lifecycle filter; defaults to `'live'`. */
+    state?: `${ModelScope}`;
+}
+/**
+ * The transaction layer. Reads return settled state, point-in-time — never a
+ * reactive subscription. A write is an intent submitted through `commit()`;
+ * durable acceptance is the receipt (`queued`), and `settled()` resolves when
+ * the sync log has appended it (`confirmed`).
+ */
+export interface TransactionLayer {
+    /** Authentication: mint or renew the short-lived credential (`ek_`). */
+    ready(): Promise<void>;
+    /** Read one settled row by id, or `null` when absent. */
+    get(model: string, id: string): Promise<ModelData | null>;
+    /** Read settled rows matching a {@link ListQuery}. */
+    list(model: string, query?: ListQuery): Promise<ModelData[]>;
+    /**
+     * Submit a batch of operations — with its idempotent `clientTxId`, its
+     * `reads` premise, and any durable `track` registrations — and receive
+     * durable acceptance.
+     */
+    commit(payload: CommitMessage['payload']): Promise<CommitReceipt>;
+    /** Resolve when the receipt's operations have appended to the sync log. */
+    settled(receipt: CommitReceipt): Promise<void>;
+    /**
+     * Take a FIFO lease with a fence token on a target; release through the
+     * handle (`await using` disposes it).
+     */
+    claim(target: ClaimTarget, options?: ClaimLeaseOptions): Promise<HeldClaim>;
+    /**
+     * The authoritative change feed, scoped to one or more sync groups —
+     * omitted, everything the credential can see.
+     */
+    observe(scope?: string | readonly string[]): AsyncIterable<Delta>;
+}

package/dist/transaction/transactionLayer.js

@@ -0,0 +1,24 @@
+/**
+ * The transaction layer's seam — the surface the sync engine (and any other
+ * caller) sits on. ADR 0013's thesis as an interface: the layer defines,
+ * orders, settles, and authorizes changes; it holds no materialised state.
+ *
+ * `observe()` is the whole seam in one method. The sync engine is `observe()`
+ * piped into a materializer — deltas → local store → IndexedDB → reactive
+ * re-render — plus local optimistic mutations reconciled against `commit()` /
+ * `settled()`. Everything reactive is downstream of that method; the
+ * transaction layer never calls up into it.
+ *
+ * `participant` stays the WHO (user | agent | system), never the name of this.
+ * The taught verbs map onto the seam directly: `create`/`update`/`delete` are
+ * operations inside a `commit()` payload; `claim` is `claim()`; `track` rides
+ * the commit payload's `track` field (a durable premise is a zero-operation
+ * commit). Presence (`join`) is deliberately absent: it is live observation
+ * over a socket, and it joins the seam when its core carrier type exists —
+ * see docs/plans/transaction-core-language.md, Tier 3.
+ *
+ * This is the contract, not a runtime: nothing in this package implements it
+ * yet. The first explicit implementation (a headless client, a test harness)
+ * gains a compile-time conformance pin against this interface.
+ */
+export {};

package/dist/{transactions → transaction/transactions/settlement}/commitEnvelope.d.ts

@@ -91,12 +91,11 @@ export declare const durableCommitEnvelopeSchema: z.ZodObject<{
     }, z.core.$strip>>;
     sourceMutationIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
     commitOptions: z.ZodDefault<z.ZodObject<{
-        causedByTaskId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         reads: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
             model: z.ZodString;
             id: z.ZodString;
             readAt: z.ZodNumber;
-            fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            fields: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
             onStale: z.ZodOptional<z.ZodEnum<{
                 reject: "reject";
                 overwrite: "overwrite";
@@ -137,8 +136,8 @@ export declare function commitEnvelopeRecordId(idempotencyKey: string): string;
 /** Constructs validated member metadata when an in-memory batch is formed. */
 export declare function createCommitEnvelopeMember(value: z.input<typeof commitEnvelopeMemberSchema>): CommitEnvelopeMember;
 /**
- * Freezes the exact JSON request that will be persisted and sent. The JSON
- * round-trip deliberately applies the same Date/undefined semantics as the
- * WebSocket transport before the request fingerprint becomes durable.
+ * Freezes the exact JSON request that will be persisted and sent. The shared
+ * snapshot contract makes framework proxies plain and rejects values that
+ * would be lost or corrupted by JSON serialization.
  */
 export declare function createDurableCommitEnvelope(value: Omit<z.input<typeof durableCommitEnvelopeSchema>, 'id' | 'type' | 'storageVersion' | 'timestamp'>): DurableCommitEnvelope;

package/dist/{transactions → transaction/transactions/settlement}/commitEnvelope.js

@@ -7,10 +7,11 @@
  * operations, and the source mutations it supersedes.
  */
 import { z } from 'zod';
-import { readDependencySchema, trackDependencySchema } from '../coordination/schema.js';
-import { commitOperationSchema } from '../wire/frames.js';
-import { correlationIdSchema } from '../wire/commit.js';
+import { readDependencySchema, trackDependencySchema } from '../../coordination/schema.js';
+import { wireCommitOperationSchema } from '../../wire/frames.js';
+import { correlationIdSchema } from '../../wire/commit.js';
 import { idempotencyKeySchema } from './idempotencyKey.js';
+import { snapshotJsonValue } from '../../utils/json.js';
 export const COMMIT_ENVELOPE_VERSION = 1;
 export const COMMIT_ENVELOPE_RECORD_PREFIX = 'commit-envelope:';
 /** One transaction's position in a commit; this is not the envelope itself. */
@@ -24,7 +25,7 @@ export const commitEnvelopeMemberSchema = z
 })
     .refine(({ operationIndex, operationCount }) => operationIndex < operationCount, { message: 'operationIndex must be smaller than operationCount' });
 /** One operation stored exactly as the current commit transport sends it. */
-export const durableCommitOperationSchema = commitOperationSchema
+export const durableCommitOperationSchema = wireCommitOperationSchema
     .pick({
     type: true,
     model: true,
@@ -48,7 +49,6 @@ export const durableCommitOperationSchema = commitOperationSchema
         .optional(),
 });
 const durableCommitOptionsSchema = z.strictObject({
-    causedByTaskId: z.string().min(1).nullable().optional(),
     reads: z.array(readDependencySchema).nullable().optional(),
     track: z.array(trackDependencySchema).nullable().optional(),
 });
@@ -145,9 +145,9 @@ export function createCommitEnvelopeMember(value) {
     return commitEnvelopeMemberSchema.parse(value);
 }
 /**
- * Freezes the exact JSON request that will be persisted and sent. The JSON
- * round-trip deliberately applies the same Date/undefined semantics as the
- * WebSocket transport before the request fingerprint becomes durable.
+ * Freezes the exact JSON request that will be persisted and sent. The shared
+ * snapshot contract makes framework proxies plain and rejects values that
+ * would be lost or corrupted by JSON serialization.
  */
 export function createDurableCommitEnvelope(value) {
     const candidate = {
@@ -157,9 +157,5 @@ export function createDurableCommitEnvelope(value) {
         storageVersion: COMMIT_ENVELOPE_VERSION,
         timestamp: value.sealedAt,
     };
-    const serialized = JSON.stringify(candidate);
-    if (serialized === undefined) {
-        throw new TypeError('Commit envelope is not JSON serializable');
-    }
-    return durableCommitEnvelopeSchema.parse(JSON.parse(serialized));
+    return durableCommitEnvelopeSchema.parse(snapshotJsonValue(candidate, '$.commitEnvelope'));
 }

package/dist/{transactions → transaction/transactions/settlement}/httpCommitEnvelope.d.ts

@@ -4,7 +4,7 @@ export declare const HTTP_COMMIT_ENVELOPE_VERSION: 1;
 export declare const HTTP_COMMIT_ENVELOPE_PREFIX = "http-commit-envelope:";
 /** Stay one hour inside the server's 24-hour idempotency retention window. */
 export declare const HTTP_COMMIT_REPLAY_WINDOW_MS: number;
-/** Apply normal JSON semantics once, then make object-key order canonical. */
+/** Snapshot the JSON contract once, then make object-key order canonical. */
 export declare function canonicalHttpCommitBody(value: unknown): string;
 export declare const durableHttpCommitEnvelopeSchema: z.ZodObject<{
     id: z.ZodString;
@@ -30,11 +30,18 @@ export declare const durableHttpCommitEnvelopeSchema: z.ZodObject<{
     timestamp: z.ZodNumber;
 }, z.core.$strict>;
 export type DurableHttpCommitEnvelope = z.infer<typeof durableHttpCommitEnvelopeSchema>;
+/**
+ * The HTTP verbs a durable commit envelope can carry, projected out of the
+ * persisted schema above. Callers that build, seal, or dispatch an envelope
+ * take this rather than restating the verbs: the envelope is a stored contract,
+ * so a verb the schema does not accept must not be constructible.
+ */
+export type DurableHttpCommitMethod = DurableHttpCommitEnvelope['request']['method'];
 export declare function httpCommitEnvelopeRecordId(idempotencyKey: string, scopeNamespace?: string): string;
 export declare function createDurableHttpCommitEnvelope(input: {
     idempotencyKey: string;
     request: {
-        method: 'POST' | 'PATCH' | 'DELETE';
+        method: DurableHttpCommitMethod;
         path: string;
         body: unknown;
     };

package/dist/{transactions → transaction/transactions/settlement}/httpCommitEnvelope.js

@@ -1,9 +1,9 @@
 /** Crash-durable exact HTTP request used by the stateless agent client. */
 import { z } from 'zod';
 import { v5 as uuidv5 } from 'uuid';
-import { stableStringify } from '../utils/json.js';
-import { correlationIdSchema } from '../wire/commit.js';
-import { PROTOCOL_VERSION } from '../wire/protocolVersion.js';
+import { snapshotJsonValue, stableStringify } from '../../utils/json.js';
+import { correlationIdSchema } from '../../wire/commit.js';
+import { PROTOCOL_VERSION } from '../../wire/protocolVersion.js';
 import { idempotencyKeySchema } from './idempotencyKey.js';
 export const HTTP_COMMIT_ENVELOPE_VERSION = 1;
 export const HTTP_COMMIT_ENVELOPE_PREFIX = 'http-commit-envelope:';
@@ -33,13 +33,9 @@ function hasSafeModelPathSegments(path) {
         return false;
     }
 }
-/** Apply normal JSON semantics once, then make object-key order canonical. */
+/** Snapshot the JSON contract once, then make object-key order canonical. */
 export function canonicalHttpCommitBody(value) {
-    const serialized = JSON.stringify(value);
-    if (serialized === undefined) {
-        throw new TypeError('HTTP commit body is not JSON serializable');
-    }
-    return stableStringify(JSON.parse(serialized));
+    return stableStringify(snapshotJsonValue(value, '$.body'));
 }
 export const durableHttpCommitEnvelopeSchema = z
     .strictObject({

package/dist/{transactions/durableWriteStore.d.ts → transaction/transactions/settlement/pendingWrite.d.ts}

@@ -1,9 +1,14 @@
 /**
- * Product-facing persistence contract for writes that must survive a process
- * restart or an ambiguous network response.
+ * The persisted shape of a write awaiting a definitive outcome.
  *
- * The engine implements this contract with a transactional outbox internally,
- * but callers should only need to think in terms of pending durable writes.
+ * Owns one authoritative union over the two durable commit envelopes — the
+ * WebSocket envelope and its HTTP counterpart — so an injected store and the
+ * engine that reads back from it agree on exactly one set of records. The
+ * envelope schemas in this directory remain authoritative for their own fields;
+ * this module only unions them.
+ *
+ * The port that persists these records is a behavior contract, not a persisted
+ * shape, so it lives outside this directory in `src/durableWrites.ts`.
  */
 import { z } from 'zod';
 /** Every write shape that Ablo may ask an injected store to persist. */
@@ -42,12 +47,11 @@ export declare const pendingWriteSchema: z.ZodUnion<readonly [z.ZodObject<{
     }, z.core.$strip>>;
     sourceMutationIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
     commitOptions: z.ZodDefault<z.ZodObject<{
-        causedByTaskId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         reads: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
             model: z.ZodString;
             id: z.ZodString;
             readAt: z.ZodNumber;
-            fields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            fields: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
             onStale: z.ZodOptional<z.ZodEnum<{
                 reject: "reject";
                 overwrite: "overwrite";
@@ -106,33 +110,3 @@ export declare const pendingWriteSchema: z.ZodUnion<readonly [z.ZodObject<{
     timestamp: z.ZodNumber;
 }, z.core.$strict>]>;
 export type PendingWrite = z.infer<typeof pendingWriteSchema>;
-/**
- * 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 declare const durableWriteStoreSchema: z.ZodCustom<DurableWriteStore, DurableWriteStore>;
-/** Options for crash-durable `create`, `update`, and `delete` calls. */
-export declare const durableWritesConfigSchema: z.ZodObject<{
-    store: z.ZodCustom<DurableWriteStore, DurableWriteStore>;
-    namespace: z.ZodOptional<z.ZodString>;
-}, z.core.$strict>;
-export type DurableWritesConfig = z.infer<typeof durableWritesConfigSchema>;

package/dist/transaction/transactions/settlement/pendingWrite.js

@@ -0,0 +1,20 @@
+/**
+ * The persisted shape of a write awaiting a definitive outcome.
+ *
+ * Owns one authoritative union over the two durable commit envelopes — the
+ * WebSocket envelope and its HTTP counterpart — so an injected store and the
+ * engine that reads back from it agree on exactly one set of records. The
+ * envelope schemas in this directory remain authoritative for their own fields;
+ * this module only unions them.
+ *
+ * The port that persists these records is a behavior contract, not a persisted
+ * shape, so it lives outside this directory in `src/durableWrites.ts`.
+ */
+import { z } from 'zod';
+import { durableCommitEnvelopeSchema } from './commitEnvelope.js';
+import { durableHttpCommitEnvelopeSchema } from './httpCommitEnvelope.js';
+/** Every write shape that Ablo may ask an injected store to persist. */
+export const pendingWriteSchema = z.union([
+    durableCommitEnvelopeSchema,
+    durableHttpCommitEnvelopeSchema,
+]);

package/dist/transaction/transport/commitFrames.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Builds the outgoing frames the sync WebSocket sends on the commit path, and
+ * provides the single place claim events are traced. These are stateless
+ * helpers that hold no socket state, so both the transport and its frame
+ * dispatch can share them.
+ */
+import type { CommitMessage } from '../wire/index.js';
+import type { CommitAck as CanonicalCommitAck } from '../wire/commit.js';
+import type { OnStaleMode, StaleNotification, ReadDependency, TrackDependency } from '../coordination/schema.js';
+import type { ClaimAcquired, ClaimGranted, ClaimQueued, ClaimLost, ClaimRejection, ClaimExpired } from '../coordination/schema.js';
+import type { Logger } from '../logger.js';
+import type { SocketObservability } from '../observability.js';
+/**
+ * The value a commit acknowledgement resolves to. `notifications` is present
+ * only when a guarded write (`onStale: 'notify'`) met a concurrent change; it
+ * carries the advisory signal that lets the writer self-heal, and the same
+ * signal also arrives on the `conflict:notified` event.
+ */
+export type CommitAck = CanonicalCommitAck;
+/**
+ * The slice of a queued client mutation the commit frame reads — a structural
+ * port, so the reactive engine's fatter `MutationOperation` satisfies it
+ * without this module importing the consumer package.
+ */
+export interface CommitFrameOperation {
+    readonly type: string;
+    readonly model: string;
+    readonly id: string;
+    readonly input?: Record<string, unknown>;
+    readonly transactionId?: string;
+    readonly readAt?: number | null;
+    readonly onStale?: OnStaleMode | null;
+    readonly fenceToken?: number | null;
+}
+/**
+ * Converts the client's list of {@link CommitFrameOperation} values into the wire
+ * {@link CommitMessage} the server accepts. This is the one place the loosely
+ * typed operation — its `type` is a string, and it carries client-only
+ * `options` the server never reads — becomes the strict wire contract. Mapping
+ * each field by hand means a change to {@link WireCommitOperation} fails to compile
+ * here; the single `as` cast narrows the validated `type` to the wire union and
+ * is the only place that loosening happens.
+ */
+export declare function buildCommitFrame(operations: readonly CommitFrameOperation[], clientTxId: string, reads?: readonly ReadDependency[] | null, track?: readonly TrackDependency[] | null): CommitMessage;
+/**
+ * Defensively validate the optional `notifications` array off a commit ack.
+ * Untrusted wire data — a malformed entry is dropped rather than throwing,
+ * so a bad notification never sinks an otherwise-successful commit.
+ */
+export declare function parseNotifications(raw: unknown): StaleNotification[] | undefined;
+/** The reporting ports a claim trace writes through — supplied by the caller
+ *  (the frame dispatch passes its session's own ports). */
+export interface ClaimTracePorts {
+    readonly logger: Logger;
+    readonly observability: SocketObservability;
+}
+/**
+ * Which frame reports each phase of a claim's life.
+ *
+ * The correspondence is real and was previously implicit: six dispatch handlers
+ * each passed their own payload alongside a phase they picked by hand, and
+ * nothing checked that the two matched. Stating it once means a caller cannot
+ * label a rejection as an acquisition.
+ *
+ * Every value is the `z.infer` of the schema the dispatcher parsed with, so no
+ * field is restated here — this maps existing types, it does not describe them.
+ */
+interface ClaimFrameByPhase {
+    acquired: ClaimAcquired;
+    granted: ClaimGranted;
+    queued: ClaimQueued;
+    lost: ClaimLost;
+    rejected: ClaimRejection;
+    expired: ClaimExpired;
+}
+/**
+ * The single place claim events are traced. Every `claim_*` frame passes
+ * through here, so a developer debugging a collision gets one consistent record
+ * — a console line and a structured capture — without each frame case
+ * re-deriving the row and holder shape.
+ *
+ * The payload arrives already validated against its frame's schema, so this
+ * reads it as the shape it is rather than re-narrowing an untyped record. That
+ * distinction is not cosmetic: while this took `Record<string, unknown>` it
+ * read `actor`, `participantKind`, and `description` off frames that carry none
+ * of them, and every one of those reads silently produced `undefined` because a
+ * string key never has to exist.
+ */
+export declare function recordClaim<P extends keyof ClaimFrameByPhase>(ports: ClaimTracePorts, phase: P, payload: ClaimFrameByPhase[P]): void;
+export {};

package/dist/transaction/transport/commitFrames.js

@@ -0,0 +1,134 @@
+/**
+ * Builds the outgoing frames the sync WebSocket sends on the commit path, and
+ * provides the single place claim events are traced. These are stateless
+ * helpers that hold no socket state, so both the transport and its frame
+ * dispatch can share them.
+ */
+import { claimEventReasonSchema, staleNotificationSchema, } from '../coordination/schema.js';
+import { formatClaim } from '../coordination/trace.js';
+import { modelTarget } from '../coordination/locator.js';
+/**
+ * Converts the client's list of {@link CommitFrameOperation} values into the wire
+ * {@link CommitMessage} the server accepts. This is the one place the loosely
+ * typed operation — its `type` is a string, and it carries client-only
+ * `options` the server never reads — becomes the strict wire contract. Mapping
+ * each field by hand means a change to {@link WireCommitOperation} fails to compile
+ * here; the single `as` cast narrows the validated `type` to the wire union and
+ * is the only place that loosening happens.
+ */
+export function buildCommitFrame(operations, clientTxId, reads, track) {
+    const payload = {
+        operations: operations.map((op) => ({
+            type: op.type,
+            model: op.model,
+            id: op.id,
+            input: op.input,
+            transactionId: op.transactionId,
+            readAt: op.readAt,
+            onStale: op.onStale,
+            fenceToken: op.fenceToken,
+        })),
+        clientTxId,
+    };
+    // The batch premise: the rows or groups the writer read before committing.
+    if (reads && reads.length > 0)
+        payload.reads = [...reads];
+    // Durable premises the writer is registering: the rows or groups it
+    // wants to keep hearing about after this commit, delivered on a future receipt.
+    if (track && track.length > 0)
+        payload.track = [...track];
+    return { type: 'commit', payload };
+}
+/**
+ * Defensively validate the optional `notifications` array off a commit ack.
+ * Untrusted wire data — a malformed entry is dropped rather than throwing,
+ * so a bad notification never sinks an otherwise-successful commit.
+ */
+export function parseNotifications(raw) {
+    if (!Array.isArray(raw) || raw.length === 0)
+        return undefined;
+    const out = [];
+    for (const entry of raw) {
+        const parsed = staleNotificationSchema.safeParse(entry);
+        if (parsed.success)
+            out.push(parsed.data);
+    }
+    return out.length > 0 ? out : undefined;
+}
+// The phases this map covers and the phases a ClaimEvent can report are the
+// same set. Adding one to either without the other stops compiling here.
+const _phaseCoverage = true;
+void _phaseCoverage;
+/**
+ * The single place claim events are traced. Every `claim_*` frame passes
+ * through here, so a developer debugging a collision gets one consistent record
+ * — a console line and a structured capture — without each frame case
+ * re-deriving the row and holder shape.
+ *
+ * The payload arrives already validated against its frame's schema, so this
+ * reads it as the shape it is rather than re-narrowing an untyped record. That
+ * distinction is not cosmetic: while this took `Record<string, unknown>` it
+ * read `actor`, `participantKind`, and `description` off frames that carry none
+ * of them, and every one of those reads silently produced `undefined` because a
+ * string key never has to exist.
+ */
+export function recordClaim(ports, phase, payload) {
+    // Widened so the members can be told apart with `in`. The parameter above
+    // stays correlated to `phase`, which is what the widening cannot undo.
+    const frame = payload;
+    const target = 'target' in frame ? frame.target : undefined;
+    // The holder rides on the rejection and queued frames, with a summary of
+    // their claim beside it. Collecting it is the whole of "name the
+    // counterparty" — the wire has carried it all along and this projection used
+    // to flatten it into one string alongside the cause.
+    const counterparty = {
+        ...('heldBy' in frame && frame.heldBy !== undefined
+            ? { actor: frame.heldBy }
+            : {}),
+        ...('heldByKind' in frame && frame.heldByKind !== undefined
+            ? { participantKind: frame.heldByKind }
+            : {}),
+        ...('heldByClaimId' in frame && frame.heldByClaimId !== undefined
+            ? { claimId: frame.heldByClaimId }
+            : {}),
+        ...('heldByExpiresAt' in frame && frame.heldByExpiresAt !== undefined
+            ? { expiresAt: frame.heldByExpiresAt }
+            : {}),
+        ...('heldByClaim' in frame && frame.heldByClaim?.description !== undefined
+            ? { description: frame.heldByClaim.description }
+            : {}),
+    };
+    // `reason` is a plain string on the wire, which is frozen, so an older server
+    // may send a word the closed set does not list. One that parses becomes the
+    // typed reason; one that does not is absent rather than passed off as prose.
+    const parsedReason = 'reason' in frame ? claimEventReasonSchema.safeParse(frame.reason) : undefined;
+    const event = {
+        phase,
+        claimId: frame.claimId,
+        ...(target ? modelTarget(target) : {}),
+        ...(target?.field !== undefined ? { field: target.field } : {}),
+        // No claim frame names an actor of its own; the only participant one
+        // carries is the holder that blocked it.
+        ...('heldBy' in frame && frame.heldBy !== undefined
+            ? { actor: frame.heldBy }
+            : {}),
+        ...('position' in frame ? { position: frame.position } : {}),
+        ...(parsedReason?.success ? { reason: parsedReason.data } : {}),
+        ...('policyReason' in frame && frame.policyReason !== undefined
+            ? { policyReason: frame.policyReason }
+            : {}),
+        ...(Object.keys(counterparty).length > 0 ? { heldBy: counterparty } : {}),
+    };
+    const message = formatClaim(event);
+    // A rejection or lost lease is the collision a developer is actively
+    // debugging → warn (shows at the default log level). The routine events
+    // (acquired/queued/granted/expired) are debug-only so they never drown the
+    // console until you opt in with `new Ablo({ debug: true })`.
+    const isCollision = phase === 'rejected' || phase === 'lost';
+    if (isCollision)
+        ports.logger.warn(message);
+    else
+        ports.logger.debug(message);
+    ports.observability.breadcrumb(message, 'sync.coordination', isCollision ? 'warning' : 'info');
+    ports.observability.captureClaim(event);
+}