@abloatai/ablo 0.28.0 → 0.29.0

package/dist/transactions/durableWriteStore.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Product-facing persistence contract for writes that must survive a process
+ * restart or an ambiguous network response.
+ *
+ * The engine implements this contract with a transactional outbox internally,
+ * but callers should only need to think in terms of pending durable writes.
+ */
+import { z } from 'zod';
+/** Every write shape that Ablo may ask an injected store to persist. */
+export declare const pendingWriteSchema: z.ZodUnion<readonly [z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodLiteral<"commit_envelope">;
+    storageVersion: z.ZodLiteral<1>;
+    origin: z.ZodEnum<{
+        model_batch: "model_batch";
+        atomic_commit: "atomic_commit";
+    }>;
+    idempotencyKey: z.core.$ZodBranded<z.ZodString, "IdempotencyKey", "out">;
+    operations: z.ZodArray<z.ZodObject<{
+        type: z.ZodEnum<{
+            CREATE: "CREATE";
+            UPDATE: "UPDATE";
+            DELETE: "DELETE";
+            ARCHIVE: "ARCHIVE";
+            UNARCHIVE: "UNARCHIVE";
+        }>;
+        readAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        onStale: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            reject: "reject";
+            overwrite: "overwrite";
+            notify: "notify";
+        }>>>;
+        model: z.ZodString;
+        id: z.ZodString;
+        input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        transactionId: z.ZodOptional<z.ZodString>;
+        options: z.ZodOptional<z.ZodObject<{
+            idempotencyKey: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            label: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+    }, 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>>;
+            onStale: z.ZodOptional<z.ZodEnum<{
+                reject: "reject";
+                overwrite: "overwrite";
+                notify: "notify";
+            }>>;
+        }, z.core.$strip>, z.ZodObject<{
+            group: z.ZodString;
+            readAt: z.ZodNumber;
+            onStale: z.ZodOptional<z.ZodEnum<{
+                reject: "reject";
+                overwrite: "overwrite";
+                notify: "notify";
+            }>>;
+        }, z.core.$strip>]>>>>;
+    }, z.core.$strict>>;
+    scope: z.ZodOptional<z.ZodObject<{
+        organizationId: z.ZodString;
+        participantId: z.ZodString;
+        namespace: z.ZodString;
+    }, z.core.$strict>>;
+    createdAt: z.ZodNumber;
+    sealedAt: z.ZodNumber;
+    sequence: z.ZodOptional<z.ZodNumber>;
+    timestamp: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodLiteral<"http_commit_envelope">;
+    storageVersion: z.ZodLiteral<1>;
+    idempotencyKey: z.core.$ZodBranded<z.ZodString, "IdempotencyKey", "out">;
+    protocolVersion: z.ZodDefault<z.ZodNumber>;
+    request: z.ZodObject<{
+        method: z.ZodEnum<{
+            DELETE: "DELETE";
+            POST: "POST";
+            PATCH: "PATCH";
+        }>;
+        path: z.ZodString;
+        body: z.ZodString;
+    }, z.core.$strict>;
+    scopeNamespace: z.ZodString;
+    createdAt: z.ZodNumber;
+    sealedAt: z.ZodNumber;
+    sequence: z.ZodOptional<z.ZodNumber>;
+    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.
+     */
+    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/transactions/durableWriteStore.js

@@ -0,0 +1,30 @@
+/**
+ * Product-facing persistence contract for writes that must survive a process
+ * restart or an ambiguous network response.
+ *
+ * The engine implements this contract with a transactional outbox internally,
+ * but callers should only need to think in terms of pending durable writes.
+ */
+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,
+]);
+/** Runtime validation for injected adapters, including JavaScript consumers. */
+export const durableWriteStoreSchema = z.custom((value) => {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const candidate = value;
+    return (typeof candidate.seal === 'function' &&
+        typeof candidate.list === 'function' &&
+        typeof candidate.remove === 'function');
+}, { message: 'store must implement seal(), list(), and remove()' });
+/** Options for crash-durable `create`, `update`, and `delete` calls. */
+export const durableWritesConfigSchema = z.strictObject({
+    store: durableWriteStoreSchema,
+    /** Separates deployments or workflow lanes that share an authenticated actor. */
+    namespace: z.string().trim().min(1).optional(),
+});

package/dist/transactions/httpCommitEnvelope.d.ts

@@ -11,6 +11,7 @@ export declare const durableHttpCommitEnvelopeSchema: z.ZodObject<{
     type: z.ZodLiteral<"http_commit_envelope">;
     storageVersion: z.ZodLiteral<1>;
     idempotencyKey: z.core.$ZodBranded<z.ZodString, "IdempotencyKey", "out">;
+    protocolVersion: z.ZodDefault<z.ZodNumber>;
     request: z.ZodObject<{
         method: z.ZodEnum<{
             DELETE: "DELETE";

package/dist/transactions/httpCommitEnvelope.js

@@ -1,8 +1,9 @@
 /** Crash-durable exact HTTP request used by the stateless agent client. */
 import { z } from 'zod';
 import { v5 as uuidv5 } from 'uuid';
-import { idempotencyKeySchema } from '../commit/contract.js';
 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. */
@@ -45,6 +46,11 @@ export const durableHttpCommitEnvelopeSchema = z
     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('/'),
@@ -111,21 +117,16 @@ export const durableHttpCommitEnvelopeSchema = z
         return;
     }
     const record = body;
-    if (record.idempotencyKey !== envelope.idempotencyKey) {
-        context.addIssue({
-            code: 'custom',
-            path: ['request', 'body', 'idempotencyKey'],
-            message: 'HTTP body idempotency key must match its envelope',
-        });
-    }
+    // `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 (record.clientTxId !== envelope.idempotencyKey ||
-            !Array.isArray(record.operations) ||
-            record.operations.length === 0) {
+        if (!Array.isArray(record.operations) || record.operations.length === 0) {
             context.addIssue({
                 code: 'custom',
                 path: ['request', 'body'],
-                message: 'Commit-route body must carry the same clientTxId and operations',
+                message: 'Commit-route body must carry operations',
             });
         }
     }
@@ -162,6 +163,7 @@ export function createDurableHttpCommitEnvelope(input) {
         type: 'http_commit_envelope',
         storageVersion: HTTP_COMMIT_ENVELOPE_VERSION,
         idempotencyKey: input.idempotencyKey,
+        protocolVersion: PROTOCOL_VERSION,
         request: {
             method: input.request.method,
             path: input.request.path,

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/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