@abloatai/ablo 0.27.0 → 0.29.0

package/dist/transactions/commitEnvelope.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Runtime contracts for retry-safe commits.
+ *
+ * `commitEnvelopeMemberSchema` is the compact pointer stored on an in-memory
+ * transaction. `durableCommitEnvelopeSchema` is the actual outbox record: one
+ * atomic IndexedDB value containing the stable request key, exact ordered wire
+ * operations, and the source mutations it supersedes.
+ */
+import { z } from 'zod';
+export declare const COMMIT_ENVELOPE_VERSION: 1;
+export declare const COMMIT_ENVELOPE_RECORD_PREFIX = "commit-envelope:";
+/** One transaction's position in a commit; this is not the envelope itself. */
+export declare const commitEnvelopeMemberSchema: 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>;
+export type CommitEnvelopeMember = z.infer<typeof commitEnvelopeMemberSchema>;
+/** One operation stored exactly as the current commit transport sends it. */
+export declare const durableCommitOperationSchema: 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>;
+export type DurableCommitOperation = z.infer<typeof durableCommitOperationSchema>;
+export type DurableCommitOperationInput = z.input<typeof durableCommitOperationSchema>;
+export declare const commitOutboxScopeSchema: z.ZodObject<{
+    organizationId: z.ZodString;
+    participantId: z.ZodString;
+    namespace: z.ZodString;
+}, z.core.$strict>;
+export type CommitOutboxScope = z.infer<typeof commitOutboxScopeSchema>;
+/**
+ * One crash-durable logical commit. Keeping every operation in one record makes
+ * membership and order atomic: recovery can observe the old record or the new
+ * record, never half an envelope.
+ */
+export declare const durableCommitEnvelopeSchema: 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>;
+export type DurableCommitEnvelope = z.infer<typeof durableCommitEnvelopeSchema>;
+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.
+ */
+export declare function createDurableCommitEnvelope(value: Omit<z.input<typeof durableCommitEnvelopeSchema>, 'id' | 'type' | 'storageVersion' | 'timestamp'>): DurableCommitEnvelope;

package/dist/transactions/commitEnvelope.js

@@ -0,0 +1,139 @@
+/**
+ * Runtime contracts for retry-safe commits.
+ *
+ * `commitEnvelopeMemberSchema` is the compact pointer stored on an in-memory
+ * transaction. `durableCommitEnvelopeSchema` is the actual outbox record: one
+ * atomic IndexedDB value containing the stable request key, exact ordered wire
+ * operations, and the source mutations it supersedes.
+ */
+import { z } from 'zod';
+import { readDependencySchema } from '../coordination/schema.js';
+import { commitOperationSchema } from '../wire/frames.js';
+import { idempotencyKeySchema } from './idempotencyKey.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. */
+export const commitEnvelopeMemberSchema = z
+    .strictObject({
+    idempotencyKey: idempotencyKeySchema,
+    operationIndex: z.number().int().nonnegative(),
+    operationCount: z.number().int().positive(),
+    sealedAt: z.number().int().nonnegative().optional(),
+    sequence: z.number().int().nonnegative().optional(),
+})
+    .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
+    .pick({
+    type: true,
+    model: true,
+    id: true,
+    input: true,
+    transactionId: true,
+    readAt: true,
+    onStale: true,
+})
+    .extend({
+    model: z.string().min(1),
+    id: z.string().min(1),
+    input: z.record(z.string(), z.unknown()).optional(),
+    transactionId: z.string().min(1).optional(),
+    options: z
+        .strictObject({
+        idempotencyKey: z.string().min(1).max(255).nullable().optional(),
+        label: z.string().min(1).max(255).optional(),
+    })
+        .optional(),
+});
+const durableCommitOptionsSchema = z.strictObject({
+    causedByTaskId: z.string().min(1).nullable().optional(),
+    reads: z.array(readDependencySchema).nullable().optional(),
+});
+export const commitOutboxScopeSchema = z.strictObject({
+    organizationId: z.string().min(1),
+    participantId: z.string().min(1),
+    namespace: z.string().min(1),
+});
+/**
+ * One crash-durable logical commit. Keeping every operation in one record makes
+ * membership and order atomic: recovery can observe the old record or the new
+ * record, never half an envelope.
+ */
+export const durableCommitEnvelopeSchema = z
+    .strictObject({
+    id: z.string().startsWith(COMMIT_ENVELOPE_RECORD_PREFIX),
+    type: z.literal('commit_envelope'),
+    storageVersion: z.literal(COMMIT_ENVELOPE_VERSION),
+    origin: z.enum(['model_batch', 'atomic_commit']),
+    idempotencyKey: idempotencyKeySchema,
+    operations: z.array(durableCommitOperationSchema).min(1).max(500),
+    // Bookkeeping cardinality is independent of the 500 wire-operation cap:
+    // hundreds of same-row offline patches may coalesce into one operation.
+    sourceMutationIds: z.array(z.string().min(1)).default([]),
+    commitOptions: durableCommitOptionsSchema.default({}),
+    scope: commitOutboxScopeSchema.optional(),
+    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) => {
+    if (envelope.id !== commitEnvelopeRecordId(envelope.idempotencyKey)) {
+        context.addIssue({
+            code: 'custom',
+            path: ['id'],
+            message: 'Envelope record id must be derived from its idempotency key',
+        });
+    }
+    if (new Set(envelope.sourceMutationIds).size !== envelope.sourceMutationIds.length) {
+        context.addIssue({
+            code: 'custom',
+            path: ['sourceMutationIds'],
+            message: 'Source mutation ids must be unique',
+        });
+    }
+    if (envelope.origin === 'model_batch') {
+        const transactionIds = envelope.operations.map((operation) => operation.transactionId);
+        if (transactionIds.some((id) => typeof id !== 'string' || id.length === 0)) {
+            context.addIssue({
+                code: 'custom',
+                path: ['operations'],
+                message: 'Every model-batch operation must carry a transactionId',
+            });
+        }
+        else if (new Set(transactionIds).size !== transactionIds.length) {
+            context.addIssue({
+                code: 'custom',
+                path: ['operations'],
+                message: 'Model-batch transactionIds must be unique',
+            });
+        }
+    }
+});
+export function commitEnvelopeRecordId(idempotencyKey) {
+    return `${COMMIT_ENVELOPE_RECORD_PREFIX}${idempotencyKey}`;
+}
+/** Constructs validated member metadata when an in-memory batch is formed. */
+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.
+ */
+export function createDurableCommitEnvelope(value) {
+    const candidate = {
+        ...value,
+        id: commitEnvelopeRecordId(value.idempotencyKey),
+        type: 'commit_envelope',
+        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));
+}

package/dist/transactions/commitOutboxStore.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Narrow persistence port for crash-durable commit envelopes.
+ *
+ * Browser clients use {@link DatabaseCommitOutboxStore}. Agent/Node hosts can
+ * inject a workflow-, SQLite-, or filesystem-backed implementation without
+ * coupling TransactionQueue to the browser database/cache implementation.
+ */
+import type { DurableWriteStore, PendingWrite } from './durableWriteStore.js';
+/** @deprecated Use {@link PendingWrite}. */
+export type CommitOutboxRecord = PendingWrite;
+/** @deprecated Use {@link DurableWriteStore}. */
+export type CommitOutboxStore = DurableWriteStore;
+/**
+ * The exact subset of the browser `Database` that {@link DatabaseCommitOutboxStore}
+ * drives. Typing the adapter to this narrow port instead of importing the
+ * concrete `Database` class keeps the outbox store off the
+ * `Database → DatabaseManager → ModelRegistry → BaseSyncedStore` import cycle;
+ * the real `Database` still satisfies it structurally, so callers are unchanged.
+ */
+export interface CommitOutboxDatabase {
+    sealTransactionRecord(record: PendingWrite, consumedRecordIds: readonly string[]): Promise<unknown>;
+    getPersistedTransactions(): Promise<readonly unknown[]>;
+    removeTransaction(id: string): Promise<void>;
+}
+/** Strict IndexedDB adapter backed by Database's `__transactions` store. */
+export declare class DatabaseCommitOutboxStore implements DurableWriteStore {
+    private readonly database;
+    constructor(database: CommitOutboxDatabase);
+    seal(envelope: PendingWrite, consumedRecordIds: readonly string[]): Promise<void>;
+    list(): Promise<readonly unknown[]>;
+    remove(envelopeRecordId: string): Promise<void>;
+}

package/dist/transactions/commitOutboxStore.js

@@ -0,0 +1,26 @@
+/**
+ * Narrow persistence port for crash-durable commit envelopes.
+ *
+ * Browser clients use {@link DatabaseCommitOutboxStore}. Agent/Node hosts can
+ * inject a workflow-, SQLite-, or filesystem-backed implementation without
+ * coupling TransactionQueue to the browser database/cache implementation.
+ */
+/** Strict IndexedDB adapter backed by Database's `__transactions` store. */
+export class DatabaseCommitOutboxStore {
+    database;
+    constructor(database) {
+        this.database = database;
+    }
+    async seal(envelope, consumedRecordIds) {
+        // This adapter deliberately has no duck-typed fallback. Reporting a
+        // successful seal after a no-op or a non-atomic save/delete handoff would
+        // authorize network dispatch without the durability this port promises.
+        await this.database.sealTransactionRecord(envelope, consumedRecordIds);
+    }
+    async list() {
+        return this.database.getPersistedTransactions();
+    }
+    async remove(envelopeRecordId) {
+        await this.database.removeTransaction(envelopeRecordId);
+    }
+}

package/dist/transactions/commitPayload.d.ts

@@ -10,6 +10,7 @@
  */
 import { MutationOperationType } from '../types/index.js';
 import type { MutationOptions, WriteOptions } from '../interfaces/index.js';
+import type { CommitEnvelopeMember } from './commitEnvelope.js';
 export interface UserContext {
     userId: string;
     organizationId: string;
@@ -55,6 +56,18 @@ export interface Transaction {
     priorityScore: number;
     writeOptions?: WriteOptions;
     batchId?: string;
+    /**
+     * Stable identity of the wire commit that currently owns this operation.
+     *
+     * A transport failure is ambiguous: the server may have committed the
+     * batch even though the acknowledgement never reached this client. Keeping
+     * this envelope on every member lets the queue replay the exact same ordered
+     * batch with the exact same idempotency key instead of accidentally
+     * re-batching its operations under a fresh key.
+     */
+    commitEnvelope?: CommitEnvelopeMember;
+    /** Pending-mutation journal entries atomically consumed by this envelope. */
+    sourceMutationIds?: string[];
     /** Completed locally without a server operation; no sync echo will arrive. */
     localOnly?: boolean;
     /** Sync-id threshold: the transaction confirms once a delta with an id at least this value arrives. */
@@ -90,6 +103,8 @@ export declare const stripModelSuffix: (modelName: string) => string;
 export declare const computePriorityScore: (type: Transaction["type"], modelName: string) => number;
 export declare const TX_TYPE_TO_MUTATION_OP: Record<Transaction['type'], MutationOperationType>;
 export declare function hasStaleWriteOptions(options?: WriteOptions): boolean;
+/** Options whose identity/audit semantics forbid merging two caller writes. */
+export declare function hasCommitCoalescingBarrier(options?: WriteOptions): boolean;
 export interface WriteOperationFields {
     readAt?: number | null;
     onStale?: 'reject' | 'overwrite' | 'notify' | null;

package/dist/transactions/commitPayload.js

@@ -107,6 +107,12 @@ export function hasStaleWriteOptions(options) {
     return (options?.readAt !== undefined ||
         options?.onStale !== undefined);
 }
+/** Options whose identity/audit semantics forbid merging two caller writes. */
+export function hasCommitCoalescingBarrier(options) {
+    return (hasStaleWriteOptions(options) ||
+        typeof options?.idempotencyKey === 'string' ||
+        typeof options?.label === 'string');
+}
 /**
  * Copies a transaction's `writeOptions` onto the wire operation. The
  * stale-context guards (`readAt` and `onStale`) sit at the operation's root,

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

@@ -0,0 +1,44 @@
+/** Crash-durable exact HTTP request used by the stateless agent client. */
+import { z } from 'zod';
+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. */
+export declare function canonicalHttpCommitBody(value: unknown): string;
+export declare const durableHttpCommitEnvelopeSchema: 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 DurableHttpCommitEnvelope = z.infer<typeof durableHttpCommitEnvelopeSchema>;
+export declare function httpCommitEnvelopeRecordId(idempotencyKey: string, scopeNamespace?: string): string;
+export declare function createDurableHttpCommitEnvelope(input: {
+    idempotencyKey: string;
+    request: {
+        method: 'POST' | 'PATCH' | 'DELETE';
+        path: string;
+        body: unknown;
+    };
+    scopeNamespace: string;
+    createdAt?: number;
+    sealedAt?: number;
+    sequence?: number;
+}): DurableHttpCommitEnvelope;
+export declare function isHttpCommitReplayExpired(envelope: Pick<DurableHttpCommitEnvelope, 'sealedAt'>, now?: number): boolean;