@abloatai/ablo 0.27.0 → 0.28.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>;
+/** The legacy mutation operation shape sent by the current commit transport. */
+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 { idempotencyKeySchema } from '../commit/contract.js';
+import { readDependencySchema } from '../coordination/schema.js';
+import { commitOperationSchema } from '../wire/frames.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' });
+/** The legacy mutation operation shape sent by the current commit transport. */
+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 { Database } from '../Database.js';
+import type { DurableCommitEnvelope } from './commitEnvelope.js';
+import type { DurableHttpCommitEnvelope } from './httpCommitEnvelope.js';
+export type CommitOutboxRecord = DurableCommitEnvelope | DurableHttpCommitEnvelope;
+export interface CommitOutboxStore {
+    /**
+     * Atomically reserve an envelope and consume the staged records it owns.
+     * Implementations must be scoped to one logical participant + server plane,
+     * reject same-id/different-request seals, and let only one envelope claim a
+     * staged record.
+     */
+    seal(envelope: CommitOutboxRecord, consumedRecordIds: readonly string[]): Promise<void>;
+    /** Load unacknowledged records. Implementations may return untrusted data. */
+    list(): Promise<readonly unknown[]>;
+    /** Remove one definitively settled envelope. */
+    remove(envelopeRecordId: string): Promise<void>;
+}
+/** Strict IndexedDB adapter backed by Database's `__transactions` store. */
+export declare class DatabaseCommitOutboxStore implements CommitOutboxStore {
+    private readonly database;
+    constructor(database: Database);
+    seal(envelope: CommitOutboxRecord, 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/httpCommitEnvelope.d.ts

@@ -0,0 +1,43 @@
+/** 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">;
+    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;

package/dist/transactions/httpCommitEnvelope.js

@@ -0,0 +1,179 @@
+/** 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';
+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,
+    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;
+    if (record.idempotencyKey !== envelope.idempotencyKey) {
+        context.addIssue({
+            code: 'custom',
+            path: ['request', 'body', 'idempotencyKey'],
+            message: 'HTTP body idempotency key must match its envelope',
+        });
+    }
+    if (path === '/v1/commits') {
+        if (record.clientTxId !== envelope.idempotencyKey ||
+            !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',
+            });
+        }
+    }
+    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,
+        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;
+}