@abloatai/ablo 0.27.0 → 0.29.0

package/dist/transactions/httpCommitEnvelope.js

@@ -0,0 +1,181 @@
+/** 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 { 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:';
+/** Stay one hour inside the server's 24-hour idempotency retention window. */
+export const HTTP_COMMIT_REPLAY_WINDOW_MS = 23 * 60 * 60 * 1000;
+const HTTP_COMMIT_SCOPE_ID_NAMESPACE = '043e8f73-86fc-5f62-af46-935d68fca729';
+const commitPathSchema = z.literal('/v1/commits');
+const modelCollectionPathSchema = z.string().regex(/^\/v1\/models\/[^/]+$/);
+const modelEntityPathSchema = z.string().regex(/^\/v1\/models\/[^/]+\/[^/]+$/);
+function hasSafeModelPathSegments(path) {
+    if (!path.startsWith('/v1/models/'))
+        return true;
+    try {
+        return path
+            .slice('/v1/models/'.length)
+            .split('/')
+            .every((segment) => {
+            const decoded = decodeURIComponent(segment);
+            return (decoded.length > 0 &&
+                decoded !== '.' &&
+                decoded !== '..' &&
+                !decoded.includes('/') &&
+                !decoded.includes('\\'));
+        });
+    }
+    catch {
+        return false;
+    }
+}
+/** Apply normal JSON semantics 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));
+}
+export const durableHttpCommitEnvelopeSchema = z
+    .strictObject({
+    id: z.string().startsWith(HTTP_COMMIT_ENVELOPE_PREFIX),
+    type: z.literal('http_commit_envelope'),
+    storageVersion: z.literal(HTTP_COMMIT_ENVELOPE_VERSION),
+    idempotencyKey: idempotencyKeySchema,
+    /**
+     * The wire contract used when this exact request was sealed. Entries from
+     * before protocol versioning omitted the field and are v1 by definition.
+     */
+    protocolVersion: z.number().int().positive().default(1),
+    request: z.strictObject({
+        method: z.enum(['POST', 'PATCH', 'DELETE']),
+        path: z.string().startsWith('/'),
+        body: z.string().refine((body) => {
+            try {
+                JSON.parse(body);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }, 'HTTP commit body must be valid JSON'),
+    }),
+    scopeNamespace: z.string().min(1),
+    createdAt: z.number().int().nonnegative(),
+    sealedAt: z.number().int().nonnegative(),
+    /** Monotonic within one client; disambiguates writes sealed in the same ms. */
+    sequence: z.number().int().nonnegative().optional(),
+    timestamp: z.number().int().nonnegative(),
+})
+    .superRefine((envelope, context) => {
+    const legacyId = httpCommitEnvelopeRecordId(envelope.idempotencyKey);
+    const scopedId = httpCommitEnvelopeRecordId(envelope.idempotencyKey, envelope.scopeNamespace);
+    if (envelope.id !== legacyId && envelope.id !== scopedId) {
+        context.addIssue({
+            code: 'custom',
+            path: ['id'],
+            message: 'HTTP envelope id must be derived from its idempotency key',
+        });
+    }
+    if (envelope.sealedAt < envelope.createdAt) {
+        context.addIssue({
+            code: 'custom',
+            path: ['sealedAt'],
+            message: 'HTTP envelope cannot be sealed before it is created',
+        });
+    }
+    const { method, path } = envelope.request;
+    const allowedPath = method === 'POST'
+        ? commitPathSchema.safeParse(path).success ||
+            modelCollectionPathSchema.safeParse(path).success
+        : modelEntityPathSchema.safeParse(path).success;
+    if (!allowedPath || !hasSafeModelPathSegments(path)) {
+        context.addIssue({
+            code: 'custom',
+            path: ['request', 'path'],
+            message: 'HTTP outbox records may target only commit or model-mutation routes',
+        });
+        return;
+    }
+    let body;
+    try {
+        body = JSON.parse(envelope.request.body);
+    }
+    catch {
+        return; // The field-level JSON refinement reports this.
+    }
+    if (typeof body !== 'object' || body === null || Array.isArray(body)) {
+        context.addIssue({
+            code: 'custom',
+            path: ['request', 'body'],
+            message: 'HTTP commit body must be a JSON object',
+        });
+        return;
+    }
+    const record = body;
+    // `envelope.idempotencyKey` is replayed as the `Idempotency-Key` header.
+    // Older sealed bodies may also carry `idempotencyKey`/`clientTxId`; accept
+    // and replay them byte-for-byte, but current requests do not duplicate the
+    // key in JSON.
+    if (path === '/v1/commits') {
+        if (!Array.isArray(record.operations) || record.operations.length === 0) {
+            context.addIssue({
+                code: 'custom',
+                path: ['request', 'body'],
+                message: 'Commit-route body must carry operations',
+            });
+        }
+    }
+    else if (method === 'POST' && typeof record.id !== 'string') {
+        context.addIssue({
+            code: 'custom',
+            path: ['request', 'body', 'id'],
+            message: 'Model-create body must carry its entity id',
+        });
+    }
+    else if (method === 'PATCH' &&
+        (typeof record.data !== 'object' || record.data === null || Array.isArray(record.data))) {
+        context.addIssue({
+            code: 'custom',
+            path: ['request', 'body', 'data'],
+            message: 'Model-update body must carry a JSON object patch',
+        });
+    }
+});
+export function httpCommitEnvelopeRecordId(idempotencyKey, scopeNamespace) {
+    if (!scopeNamespace) {
+        return `${HTTP_COMMIT_ENVELOPE_PREFIX}${idempotencyKey}`;
+    }
+    const scopeId = uuidv5(scopeNamespace, HTTP_COMMIT_SCOPE_ID_NAMESPACE);
+    return `${HTTP_COMMIT_ENVELOPE_PREFIX}${scopeId}:${idempotencyKey}`;
+}
+export function createDurableHttpCommitEnvelope(input) {
+    const now = Date.now();
+    const createdAt = input.createdAt ?? now;
+    const sealedAt = input.sealedAt ?? now;
+    const body = canonicalHttpCommitBody(input.request.body);
+    return durableHttpCommitEnvelopeSchema.parse({
+        id: httpCommitEnvelopeRecordId(input.idempotencyKey, input.scopeNamespace),
+        type: 'http_commit_envelope',
+        storageVersion: HTTP_COMMIT_ENVELOPE_VERSION,
+        idempotencyKey: input.idempotencyKey,
+        protocolVersion: PROTOCOL_VERSION,
+        request: {
+            method: input.request.method,
+            path: input.request.path,
+            body,
+        },
+        scopeNamespace: input.scopeNamespace,
+        createdAt,
+        sealedAt,
+        ...(input.sequence !== undefined ? { sequence: input.sequence } : {}),
+        timestamp: sealedAt,
+    });
+}
+export function isHttpCommitReplayExpired(envelope, now = Date.now()) {
+    return now - envelope.sealedAt >= HTTP_COMMIT_REPLAY_WINDOW_MS;
+}

package/dist/transactions/idempotencyKey.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Identity shared by the durable write records.
+ *
+ * A retry must reuse the same non-empty key so the server can recognize the
+ * same logical write. This is a persistence invariant, not a second commit
+ * protocol.
+ */
+import { z } from 'zod';
+export declare const idempotencyKeySchema: z.core.$ZodBranded<z.ZodString, "IdempotencyKey", "out">;
+export type IdempotencyKey = z.output<typeof idempotencyKeySchema>;

package/dist/transactions/idempotencyKey.js

@@ -0,0 +1,9 @@
+/**
+ * Identity shared by the durable write records.
+ *
+ * A retry must reuse the same non-empty key so the server can recognize the
+ * same logical write. This is a persistence invariant, not a second commit
+ * protocol.
+ */
+import { z } from 'zod';
+export const idempotencyKeySchema = z.string().min(1).max(255).brand();

package/dist/transactions/replayValidation.d.ts

@@ -45,6 +45,14 @@ export declare const persistedTransactionSchema: z.ZodObject<{
     }, z.core.$strip>;
     createdAt: z.ZodOptional<z.ZodNumber>;
     batchId: z.ZodOptional<z.ZodString>;
+    commitEnvelope: z.ZodOptional<z.ZodObject<{
+        idempotencyKey: z.core.$ZodBranded<z.ZodString, "IdempotencyKey", "out">;
+        operationIndex: z.ZodNumber;
+        operationCount: z.ZodNumber;
+        sealedAt: z.ZodOptional<z.ZodNumber>;
+        sequence: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    sourceMutationIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
     writeOptions: z.ZodOptional<z.ZodObject<{
         readAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
         onStale: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
@@ -76,6 +84,7 @@ export declare function deserializePersistedTransaction(row: unknown): Transacti
  * queue is restored on reconnect.
  */
 export declare const persistedMutationSchema: z.ZodObject<{
+    mutationId: z.ZodOptional<z.ZodString>;
     type: z.ZodEnum<{
         update: "update";
         create: "create";
@@ -85,6 +94,7 @@ export declare const persistedMutationSchema: z.ZodObject<{
     modelData: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     modelName: z.ZodString;
     timestamp: z.ZodString;
+    capturedChanges: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     writeOptions: z.ZodOptional<z.ZodObject<{
         readAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
         onStale: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
@@ -97,3 +107,76 @@ export declare const persistedMutationSchema: z.ZodObject<{
     }, z.core.$loose>>;
 }, z.core.$loose>;
 export type PersistedQueuedMutation = z.infer<typeof persistedMutationSchema>;
+export declare const PENDING_MUTATION_RECORD_PREFIX = "pending-mutation:";
+/**
+ * Stay one hour inside the server's 24-hour idempotency retention window.
+ * A journaled write older than this can no longer be deduplicated by the
+ * server, so restore holds it for review instead of replaying it.
+ */
+export declare const PENDING_MUTATION_REPLAY_WINDOW_MS: number;
+/** Scope-less records written by the first aggregate-journal release. */
+export declare const legacyPendingMutationRecordSchema: z.ZodObject<{
+    storageVersion: z.ZodLiteral<1>;
+    id: z.ZodString;
+    type: z.ZodLiteral<"pending_mutation">;
+    mutation: z.ZodObject<{
+        type: z.ZodEnum<{
+            update: "update";
+            create: "create";
+            delete: "delete";
+            archive: "archive";
+        }>;
+        modelData: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        modelName: z.ZodString;
+        timestamp: z.ZodString;
+        capturedChanges: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        writeOptions: z.ZodOptional<z.ZodObject<{
+            readAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            onStale: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+                reject: "reject";
+                overwrite: "overwrite";
+                notify: "notify";
+            }>>>;
+            idempotencyKey: z.ZodOptional<z.ZodString>;
+            label: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>;
+        mutationId: z.ZodString;
+    }, z.core.$loose>;
+    timestamp: z.ZodNumber;
+}, z.core.$strict>;
+export declare const pendingMutationRecordSchema: z.ZodObject<{
+    storageVersion: z.ZodLiteral<2>;
+    scope: z.ZodObject<{
+        organizationId: z.ZodString;
+        participantId: z.ZodString;
+        namespace: z.ZodString;
+    }, z.core.$strict>;
+    id: z.ZodString;
+    type: z.ZodLiteral<"pending_mutation">;
+    mutation: z.ZodObject<{
+        type: z.ZodEnum<{
+            update: "update";
+            create: "create";
+            delete: "delete";
+            archive: "archive";
+        }>;
+        modelData: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        modelName: z.ZodString;
+        timestamp: z.ZodString;
+        capturedChanges: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        writeOptions: z.ZodOptional<z.ZodObject<{
+            readAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            onStale: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+                reject: "reject";
+                overwrite: "overwrite";
+                notify: "notify";
+            }>>>;
+            idempotencyKey: z.ZodOptional<z.ZodString>;
+            label: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>;
+        mutationId: z.ZodString;
+    }, z.core.$loose>;
+    timestamp: z.ZodNumber;
+}, z.core.$strict>;
+export type PendingMutationRecord = z.infer<typeof pendingMutationRecordSchema>;
+export declare function pendingMutationRecordId(mutationId: string): string;

package/dist/transactions/replayValidation.js

@@ -16,6 +16,7 @@
  */
 import { z } from 'zod';
 import { computePriorityScore, normalizeModelKey } from './commitPayload.js';
+import { commitEnvelopeMemberSchema, commitOutboxScopeSchema, } from './commitEnvelope.js';
 /** The subset of a write's options that is stored with each transaction or queued mutation. */
 const persistedWriteOptionsSchema = z
     .object({
@@ -49,12 +50,20 @@ export const persistedTransactionSchema = z
     }),
     createdAt: z.number().optional(),
     batchId: z.string().optional(),
+    commitEnvelope: commitEnvelopeMemberSchema.optional(),
+    sourceMutationIds: z.array(z.string().min(1)).optional(),
     writeOptions: persistedWriteOptionsSchema.optional(),
     localOnly: z.boolean().optional(),
 })
     .loose();
 /** The `type` values of stored rows that belong to other parts of the client and are not replayable transactions. */
-const NON_REPLAYABLE_TYPES = new Set(['queue', 'awaiting_delta']);
+const NON_REPLAYABLE_TYPES = new Set([
+    'queue',
+    'awaiting_delta',
+    'pending_mutation',
+    'commit_envelope',
+    'http_commit_envelope',
+]);
 /**
  * Reports whether a stored row is one of the non-transaction kinds, so callers
  * skip it instead of treating it as a corrupt transaction.
@@ -91,6 +100,12 @@ export function deserializePersistedTransaction(row) {
         priority: 'normal',
         priorityScore: computePriorityScore(tx.type, tx.modelName),
         ...(tx.batchId !== undefined ? { batchId: tx.batchId } : {}),
+        ...(tx.commitEnvelope !== undefined
+            ? { commitEnvelope: tx.commitEnvelope }
+            : {}),
+        ...(tx.sourceMutationIds !== undefined
+            ? { sourceMutationIds: tx.sourceMutationIds }
+            : {}),
         ...(tx.writeOptions !== undefined ? { writeOptions: tx.writeOptions } : {}),
         ...(tx.localOnly !== undefined ? { localOnly: tx.localOnly } : {}),
     };
@@ -102,10 +117,40 @@ export function deserializePersistedTransaction(row) {
  */
 export const persistedMutationSchema = z
     .object({
+    mutationId: z.string().min(1).optional(),
     type: z.enum(['create', 'update', 'delete', 'archive']),
     modelData: z.record(z.string(), z.unknown()),
     modelName: z.string().min(1),
     timestamp: z.string(),
+    capturedChanges: z.record(z.string(), z.unknown()).optional(),
     writeOptions: persistedWriteOptionsSchema.optional(),
 })
     .loose();
+export const PENDING_MUTATION_RECORD_PREFIX = 'pending-mutation:';
+/**
+ * Stay one hour inside the server's 24-hour idempotency retention window.
+ * A journaled write older than this can no longer be deduplicated by the
+ * server, so restore holds it for review instead of replaying it.
+ */
+export const PENDING_MUTATION_REPLAY_WINDOW_MS = 23 * 60 * 60 * 1000;
+const pendingMutationRecordBaseShape = {
+    id: z.string().startsWith(PENDING_MUTATION_RECORD_PREFIX),
+    type: z.literal('pending_mutation'),
+    mutation: persistedMutationSchema.extend({
+        mutationId: z.string().min(1),
+    }),
+    timestamp: z.number().int().nonnegative(),
+};
+/** Scope-less records written by the first aggregate-journal release. */
+export const legacyPendingMutationRecordSchema = z.strictObject({
+    ...pendingMutationRecordBaseShape,
+    storageVersion: z.literal(1),
+});
+export const pendingMutationRecordSchema = z.strictObject({
+    ...pendingMutationRecordBaseShape,
+    storageVersion: z.literal(2),
+    scope: commitOutboxScopeSchema,
+});
+export function pendingMutationRecordId(mutationId) {
+    return `${PENDING_MUTATION_RECORD_PREFIX}${mutationId}`;
+}

package/dist/types/global.d.ts

@@ -1,11 +1,10 @@
 /**
  * The single place where you tell the SDK about your application's types.
  *
- * You register your Schema, Presence, Claims, and UserMeta once by augmenting
- * the {@link Register} interface. From then on every SDK hook — `useAblo`,
- * `useQuery`, `useOne`, `usePresence`, `useClaim` — reads its types from that
- * registration, so you never pass a generic or a `schema` argument at a call
- * site.
+ * You register your Schema and UserMeta once by augmenting the
+ * {@link Register} interface. From then on the typed SDK surface reads its
+ * types from that registration, so you never pass a generic or a `schema`
+ * argument at a call site.
  *
  * Registration uses TypeScript module augmentation: any file in your project
  * can add an `interface Register` to a `declare module '@abloatai/ablo'`
@@ -27,8 +26,6 @@
  * declare module '@abloatai/ablo' {
  *   interface Register {
  *     Schema: typeof schema;
- *     Presence: { cursor: { x: number; y: number } | null };
- *     Claims: { editLayer: { layerId: string } };
  *     UserMeta: { id: string; email: string };
  *   }
  * }
@@ -39,18 +36,18 @@
  * {@link DefaultSyncShape} — a loose shape that keeps your code compiling
  * without typed results until you opt in.
  */
+import type { SchemaRecord } from '../schema/schema.js';
 /**
  * The fallback shapes the resolvers use when {@link Register} has not been
  * augmented. `DefaultSyncShape.Schema` is deliberately structural — it carries
- * `{ models: Record<string, unknown> }` so hooks can still check a model-key
- * argument against something, just without a typed entity shape behind it.
+ * `{ models: SchemaRecord }` so hooks can still check a model-key argument
+ * against something (and satisfy the `SchemaRecord` bound), just without a
+ * typed entity shape behind it.
  */
 export interface DefaultSyncShape {
     readonly Schema: {
-        readonly models: Record<string, unknown>;
+        readonly models: SchemaRecord;
     };
-    readonly Presence: Record<string, unknown>;
-    readonly Claims: Record<string, unknown>;
     readonly UserMeta: {
         readonly id: string;
     };
@@ -58,7 +55,7 @@ export interface DefaultSyncShape {
 /**
  * The registration interface you augment to declare your application's types.
  * Add keys inside a `declare module '@abloatai/ablo'` block — for example
- * `interface Register { Schema: ...; Presence: ...; }`. It is empty by default,
+ * `interface Register { Schema: ...; UserMeta: ...; }`. It is empty by default,
  * so any key you omit falls back to {@link DefaultSyncShape}. It is exported
  * from the package root so your augmentation merges into this declaration.
  *
@@ -77,22 +74,6 @@ export type ResolveSchema = Register extends {
 } ? S extends {
     models: Record<string, unknown>;
 } ? S : DefaultSyncShape['Schema'] : DefaultSyncShape['Schema'];
-/**
- * Your registered presence shape, or the default when none is registered.
- * `usePresence` reads it. The shape is free-form — any JSON-serializable value
- * you broadcast per session.
- */
-export type ResolvePresence = Register extends {
-    Presence: infer P;
-} ? P : DefaultSyncShape['Presence'];
-/**
- * Your registered claim vocabulary, or the default when none is registered.
- * Each key is a claim name and its value is that claim's payload.
- * `useClaim(claimName)` reads it.
- */
-export type ResolveClaims = Register extends {
-    Claims: infer I;
-} ? I : DefaultSyncShape['Claims'];
 /**
  * Your registered user-metadata shape, or the default when none is registered.
  * It carries identity information you trust from your own auth layer; the SDK

package/dist/types/global.js

@@ -1,11 +1,10 @@
 /**
  * The single place where you tell the SDK about your application's types.
  *
- * You register your Schema, Presence, Claims, and UserMeta once by augmenting
- * the {@link Register} interface. From then on every SDK hook — `useAblo`,
- * `useQuery`, `useOne`, `usePresence`, `useClaim` — reads its types from that
- * registration, so you never pass a generic or a `schema` argument at a call
- * site.
+ * You register your Schema and UserMeta once by augmenting the
+ * {@link Register} interface. From then on the typed SDK surface reads its
+ * types from that registration, so you never pass a generic or a `schema`
+ * argument at a call site.
  *
  * Registration uses TypeScript module augmentation: any file in your project
  * can add an `interface Register` to a `declare module '@abloatai/ablo'`
@@ -27,8 +26,6 @@
  * declare module '@abloatai/ablo' {
  *   interface Register {
  *     Schema: typeof schema;
- *     Presence: { cursor: { x: number; y: number } | null };
- *     Claims: { editLayer: { layerId: string } };
  *     UserMeta: { id: string; email: string };
  *   }
  * }

package/dist/types/streams.d.ts

@@ -9,8 +9,8 @@
  * layer underneath.
  */
 import type { InferModel, Schema } from '../schema/schema.js';
-import type { TargetRange, OnStaleMode, WireClaim, ClaimRejection, PresenceKind, ParticipantKind } from '../coordination/schema.js';
-export type { TargetRange, OnStaleMode, WireClaim, ClaimRejection, PresenceKind, ParticipantKind };
+import type { TargetRange, OnStaleMode, WireClaim, ClaimRejection, ClaimLost, PresenceKind, ParticipantKind } from '../coordination/schema.js';
+export type { TargetRange, OnStaleMode, WireClaim, ClaimRejection, ClaimLost, PresenceKind, ParticipantKind, };
 /**
  * Any JSON-serializable value. Used where the SDK accepts free-form metadata
  * that is stored or transported as JSON — more precise than `unknown` while
@@ -384,32 +384,6 @@ export interface ClaimStream {
      */
     [Symbol.asyncIterator](): AsyncIterableIterator<readonly Claim[]>;
 }
-/**
- * A notification that you lost a claim you were holding — distinct from
- * {@link ClaimRejection}, which is a claim the server refused to grant.
- * Delivered through `onLost`.
- */
-export interface ClaimLost {
-    /** The id of the claim you just lost. */
-    readonly claimId: string;
-    /**
-     * How you lost it. `'preempted'`: a privileged participant (one holding the
-     * `claim.preempt` capability) evicted you and took the lease — its work now
-     * supersedes yours, so re-plan against the new holder rather than blindly
-     * re-claiming. `'expired'`: your TTL lapsed without finishing — re-claim if
-     * you still need it.
-     */
-    readonly reason: 'expired' | 'preempted';
-    /** The target you no longer hold. */
-    readonly target: {
-        readonly entityType: string;
-        readonly entityId: string;
-        readonly path?: string;
-        readonly range?: TargetRange;
-        readonly field?: string;
-        readonly meta?: Record<string, unknown>;
-    };
-}
 /**
  * Every lifecycle state of a claim. `active` is the current holder — the lock
  * itself. `queued` is waiting in line behind the holder and carries a

package/dist/wire/bootstrapReason.d.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+/** Machine-readable reasons a live delta stream must resume via catch-up. */
+export declare const bootstrapReasonSchema: z.ZodEnum<{
+    too_far_behind: "too_far_behind";
+    too_many_deltas: "too_many_deltas";
+    missing_entities: "missing_entities";
+    stream_gap: "stream_gap";
+}>;
+export type BootstrapReason = z.infer<typeof bootstrapReasonSchema>;

package/dist/wire/bootstrapReason.js

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+/** Machine-readable reasons a live delta stream must resume via catch-up. */
+export const bootstrapReasonSchema = z.enum([
+    'too_far_behind',
+    'too_many_deltas',
+    'missing_entities',
+    'stream_gap',
+]);

package/dist/wire/frames.d.ts

@@ -1,9 +1,9 @@
 /**
  * The write-path message shapes for the sync protocol. These cover the frames
- * a client sends to commit work — {@link CommitMessage} (a batch of raw
- * operations) and {@link MutationMessage} (a single named mutation) — and the
- * server's {@link MutationResultMessage} acknowledgement. The same frames flow
- * over a WebSocket connection and over the HTTP commit endpoint.
+ * a client sends to commit work — {@link CommitMessage}, a batch of raw
+ * operations — and the server's {@link MutationResultMessage}
+ * acknowledgement. The same frames flow over a WebSocket connection and over
+ * the HTTP commit endpoint.
  *
  * Both the client and the server import these definitions from here, so the two
  * sides cannot drift. Each interface is paired with a Zod validator
@@ -85,25 +85,10 @@ export declare const commitOperationSchema: z.ZodObject<{
     transactionId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     bypass: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
 }, z.core.$strip>;
-/**
- * A client-to-server frame that invokes a single named mutation by name and
- * arguments, as opposed to the raw operation batch in {@link CommitMessage}.
- * The server resolves `mutatorName` against the set of mutations registered on
- * it and runs the matching one.
- */
-export interface MutationMessage {
-    type: 'mutation';
-    payload: {
-        mutatorName: string;
-        input: unknown;
-        clientTxId: string;
-    };
-}
 /**
  * A client-to-server frame that asks the server to commit a batch of operations
- * atomically. This is the raw-operation counterpart to {@link MutationMessage};
- * it carries a list of {@link CommitOperation} entries plus the batch metadata
- * below.
+ * atomically. It carries a list of {@link CommitOperation} entries plus the
+ * batch metadata below.
  */
 export interface CommitMessage {
     type: 'commit';

package/dist/wire/frames.js

@@ -1,9 +1,9 @@
 /**
  * The write-path message shapes for the sync protocol. These cover the frames
- * a client sends to commit work — {@link CommitMessage} (a batch of raw
- * operations) and {@link MutationMessage} (a single named mutation) — and the
- * server's {@link MutationResultMessage} acknowledgement. The same frames flow
- * over a WebSocket connection and over the HTTP commit endpoint.
+ * a client sends to commit work — {@link CommitMessage}, a batch of raw
+ * operations — and the server's {@link MutationResultMessage}
+ * acknowledgement. The same frames flow over a WebSocket connection and over
+ * the HTTP commit endpoint.
  *
  * Both the client and the server import these definitions from here, so the two
  * sides cannot drift. Each interface is paired with a Zod validator

package/dist/wire/index.d.ts

@@ -19,9 +19,12 @@ export { errorEnvelope, statusForType } from './errorEnvelope.js';
 export type { ErrorEnvelope } from './errorEnvelope.js';
 export { listEnvelope } from './listEnvelope.js';
 export type { ListEnvelope } from './listEnvelope.js';
-export { commitOperationSchema, commitPayloadSchema } from './frames.js';
-export { PROTOCOL_VERSION, MIN_SUPPORTED_PROTOCOL_VERSION, WS_CLOSE_PROTOCOL_VERSION, PROTOCOL_VERSION_HEADER, protocolVersionProblem, } from './protocolVersion.js';
-export type { CommitOperation, MutationMessage, CommitMessage, MutationResultMessage, } from './frames.js';
+export { bootstrapReasonSchema } from './bootstrapReason.js';
+export type { BootstrapReason } from './bootstrapReason.js';
+export { commitOperationSchema, commitPayloadSchema, } from './frames.js';
+export { PROTOCOL_VERSION, MIN_SUPPORTED_PROTOCOL_VERSION, DEFAULT_PROTOCOL_VERSION, SUPPORTED_PROTOCOL_VERSIONS, WS_CLOSE_PROTOCOL_VERSION, PROTOCOL_VERSION_HEADER, protocolVersionProblem, resolveProtocolVersion, } from './protocolVersion.js';
+export type { SupportedProtocolVersion, ProtocolVersionProblem, } from './protocolVersion.js';
+export type { CommitOperation, CommitMessage, MutationResultMessage, } from './frames.js';
 export { participantKindSchema, confirmationStateSchema, syncDeltaActionSchema, wireDeltaDataSchema, participantRefSchema, syncDeltaWireCoreSchema, clientSyncDeltaSchema, serverSyncDeltaSchema, } from './delta.js';
 export type { ParticipantKind, ConfirmationState, SyncDeltaAction, WireDeltaData, ParticipantRef, SyncDeltaWireCore, ClientSyncDelta, ServerSyncDelta, } from './delta.js';
 export { AbloError, AbloAuthenticationError, AbloPermissionError, AbloValidationError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloServerError, AbloStaleContextError, AbloClaimedError, CapabilityError, SyncSessionError, docUrlForCode, translateHttpError, errorFromWire, toAbloError, ERROR_CONTRACT_VERSION, errorCodeSpec, } from '../errors.js';

package/dist/wire/index.js

@@ -17,15 +17,16 @@
  */
 export { errorEnvelope, statusForType } from './errorEnvelope.js';
 export { listEnvelope } from './listEnvelope.js';
+export { bootstrapReasonSchema } from './bootstrapReason.js';
 // The write-path frame contract: the message shapes shared by the client and
 // the server. The runtime Zod validators sit beside the interfaces and are
 // pinned to them, and they gate every operation and payload on both commit
 // transports.
-export { commitOperationSchema, commitPayloadSchema } from './frames.js';
+export { commitOperationSchema, commitPayloadSchema, } from './frames.js';
 // Protocol versioning: the single integer the client and server compare to
 // confirm they can speak to each other, plus the WebSocket close code used to
 // reject a mismatch. See protocolVersion.ts for the changelog and deploy rules.
-export { PROTOCOL_VERSION, MIN_SUPPORTED_PROTOCOL_VERSION, WS_CLOSE_PROTOCOL_VERSION, PROTOCOL_VERSION_HEADER, protocolVersionProblem, } from './protocolVersion.js';
+export { PROTOCOL_VERSION, MIN_SUPPORTED_PROTOCOL_VERSION, DEFAULT_PROTOCOL_VERSION, SUPPORTED_PROTOCOL_VERSIONS, WS_CLOSE_PROTOCOL_VERSION, PROTOCOL_VERSION_HEADER, protocolVersionProblem, resolveProtocolVersion, } from './protocolVersion.js';
 // The read-path delta contract: the shape the server broadcasts to clients as the
 // payload of a `delta` or `sync_response` frame, together with the shared
 // participant vocabulary it carries. Both ends derive their delta type from these