@abloatai/transaction 0.37.0

package/dist/wire/commit.js

@@ -0,0 +1,322 @@
+/**
+ * Canonical runtime contracts for commit settlement.
+ *
+ * A commit crosses several boundaries during its lifetime: the server's
+ * execution cache, the HTTP/WS receipt, and the client's acknowledgement
+ * tracker. Those boundaries intentionally have different envelopes, but they
+ * all compose the same settlement vocabulary from this module:
+ *
+ *   - `confirmed` — the authoritative change is visible at a sync watermark.
+ *   - `queued` — a connected source durably accepted the write and only its
+ *     correlated authoritative source delta (WAL for direct, endpoint event
+ *     for endpoint-only), identified by `correlationId`, may promote it.
+ *
+ * Keeping the variants discriminated here makes an impossible receipt (most
+ * importantly, `queued` without a correlation) unrepresentable at every
+ * untrusted boundary without collapsing the distinct lifecycle envelopes into
+ * one giant object.
+ */
+import { z } from 'zod';
+import { onStaleModeSchema, readDependencySchema, staleNotificationSchema, trackDependencySchema, } from '../coordination/schema.js';
+import { requiredCapabilityWireSchema } from '../errors.js';
+/** Matches the permanent source/idempotency-key ceiling. */
+export const COMMIT_CORRELATION_ID_MAX_LENGTH = 255;
+/** Opaque server-authored identity shared by a queued receipt and its authoritative source delta. */
+export const correlationIdSchema = z.string().min(1).max(COMMIT_CORRELATION_ID_MAX_LENGTH);
+export const commitStatusSchema = z.enum(['queued', 'confirmed']);
+/**
+ * The settlement states a write may block on — extracted from the reported
+ * vocabulary above, never restated beside it. `commitStatusSchema` is every
+ * state a server can report; this is the subset a caller can usefully wait for,
+ * and the two are not the same question: one describes an outcome, the other a
+ * request.
+ *
+ * `.extract` keeps the relationship mechanical in both directions. Renaming a
+ * settlement state breaks this line at build time, and adding one that nobody
+ * can block on — a commit parked for a human, say — does not become a legal
+ * `wait` merely by being added above. Both the `wait` option's runtime
+ * validator and its interface derive from here, so they cannot disagree.
+ */
+export const commitWaitSchema = commitStatusSchema.extract(['queued', 'confirmed']);
+const queuedSettlementShape = {
+    status: z.literal('queued'),
+    correlationId: correlationIdSchema,
+};
+const confirmedSettlementShape = {
+    status: z.literal('confirmed'),
+    correlationId: correlationIdSchema.optional(),
+};
+const queuedSettlementSchema = z.strictObject(queuedSettlementShape);
+const confirmedSettlementSchema = z.strictObject(confirmedSettlementShape);
+/** The one settlement discriminant shared by every commit boundary. */
+export const commitSettlementSchema = z.discriminatedUnion('status', [
+    queuedSettlementSchema,
+    confirmedSettlementSchema,
+]);
+const missingIdsSchema = z.array(z.string().min(1));
+const notificationsSchema = z.array(staleNotificationSchema);
+const successfulReceiptCommonShape = {
+    object: z.literal('commit_receipt'),
+    /** Optional convenience id used by some HTTP surfaces. */
+    id: z.string().min(1).optional(),
+    clientTxId: z.string().min(1),
+    serverTxId: z.string().min(1),
+    success: z.literal(true),
+    lastSyncId: z.number().int().nonnegative(),
+    ops: z.number().int().nonnegative(),
+    notifications: notificationsSchema.optional(),
+    missingIds: missingIdsSchema.optional(),
+};
+const queuedCommitReceiptSchema = z
+    .object({
+    ...successfulReceiptCommonShape,
+    ...queuedSettlementShape,
+})
+    .superRefine((receipt, context) => {
+    if (receipt.lastSyncId !== 0) {
+        context.addIssue({
+            code: 'custom',
+            path: ['lastSyncId'],
+            message: 'A queued source receipt cannot claim a confirmed sync watermark',
+        });
+    }
+});
+const confirmedCommitReceiptSchema = z
+    .object({
+    ...successfulReceiptCommonShape,
+    ...confirmedSettlementShape,
+})
+    .superRefine((receipt, context) => {
+    if (receipt.correlationId && receipt.lastSyncId <= 0) {
+        context.addIssue({
+            code: 'custom',
+            path: ['lastSyncId'],
+            message: 'A source-confirmed receipt requires a positive sync watermark',
+        });
+    }
+});
+/**
+ * Successful HTTP/WS receipt. This schema is deliberately strict about the
+ * settlement discriminant. Zod's default object behavior strips additive
+ * fields, which is forward compatible without allowing server-internal
+ * recovery evidence to leak through a parsed wire receipt.
+ */
+export const commitReceiptSchema = z.discriminatedUnion('status', [
+    queuedCommitReceiptSchema,
+    confirmedCommitReceiptSchema,
+]);
+/**
+ * The rejection code is deliberately not narrowed to the {@link ErrorCode}
+ * registry. A newer server may reject a commit with a code this build predates,
+ * and failing the whole receipt over an unrecognized string would turn a
+ * readable rejection into an opaque parse error. `errorCodes.ts` sanctions this
+ * single boundary cast; every code *producer* is constrained at the
+ * `AbloError` constructor instead.
+ */
+const errorCodeSchema = z.custom((value) => typeof value === 'string' && value.length > 0, { message: 'commit rejection code must be a non-empty string' });
+/** The failure arm is separate: queued/confirmed always imply `success:true`. */
+export const rejectedCommitReceiptSchema = z.object({
+    object: z.literal('commit_receipt'),
+    clientTxId: z.string(),
+    serverTxId: z.string(),
+    success: z.literal(false),
+    status: z.literal('rejected'),
+    lastSyncId: z.number().int().nonnegative().optional(),
+    ops: z.number().int().nonnegative().optional(),
+    error: z.object({
+        code: errorCodeSchema,
+        message: z.string(),
+        field: z.string().optional(),
+        requiredCapability: requiredCapabilityWireSchema.optional(),
+    }),
+});
+export const mutationResultPayloadSchema = z.union([
+    commitReceiptSchema,
+    rejectedCommitReceiptSchema,
+]);
+export const mutationResultMessageSchema = z.object({
+    type: z.literal('mutation_result'),
+    payload: mutationResultPayloadSchema,
+});
+const confirmationTransactionIdsSchema = z
+    .array(z.string().min(1))
+    .min(1)
+    .refine((ids) => new Set(ids).size === ids.length, {
+    message: 'confirmation transaction ids must be unique',
+});
+/**
+ * Server-internal execution result persisted in `mutation_log`.
+ *
+ * `status` remains optional only for pre-settlement hosted rows. At runtime an
+ * omitted value has the established meaning `confirmed`; new source-forwarded
+ * rows must use the explicit queued arm with both public correlation and exact
+ * internal storage ids.
+ */
+const rawCommitExecutionResultSchema = z
+    .strictObject({
+    lastSyncId: z.number().int().nonnegative(),
+    firstSyncId: z.number().int().nonnegative(),
+    status: commitStatusSchema.optional(),
+    correlationId: correlationIdSchema.optional(),
+    confirmationTransactionIds: confirmationTransactionIdsSchema.optional(),
+    notifications: notificationsSchema.optional(),
+    missingIds: missingIdsSchema.optional(),
+})
+    .superRefine((result, context) => {
+    const validRange = (result.firstSyncId === 0 && result.lastSyncId === 0) ||
+        (result.firstSyncId > 0 && result.firstSyncId <= result.lastSyncId);
+    if (!validRange) {
+        context.addIssue({
+            code: 'custom',
+            path: ['firstSyncId'],
+            message: 'CommitResult sync range is inconsistent',
+        });
+    }
+    if (result.status === 'queued') {
+        if (!result.correlationId) {
+            context.addIssue({
+                code: 'custom',
+                path: ['correlationId'],
+                message: 'A queued source result requires a correlationId',
+            });
+        }
+        if (!result.confirmationTransactionIds) {
+            context.addIssue({
+                code: 'custom',
+                path: ['confirmationTransactionIds'],
+                message: 'A queued source result requires durable confirmation ids',
+            });
+        }
+        if (result.firstSyncId !== 0 || result.lastSyncId !== 0) {
+            context.addIssue({
+                code: 'custom',
+                path: ['lastSyncId'],
+                message: 'A queued source result cannot claim a confirmed sync range',
+            });
+        }
+    }
+    if (result.confirmationTransactionIds && !result.correlationId) {
+        context.addIssue({
+            code: 'custom',
+            path: ['correlationId'],
+            message: 'Confirmation transaction ids require their source correlation',
+        });
+    }
+    if (result.correlationId && !result.confirmationTransactionIds) {
+        context.addIssue({
+            code: 'custom',
+            path: ['confirmationTransactionIds'],
+            message: 'A source correlation requires exact confirmation transaction ids',
+        });
+    }
+    if (result.correlationId && result.status === undefined) {
+        context.addIssue({
+            code: 'custom',
+            path: ['status'],
+            message: 'Source-correlated results require explicit settlement status',
+        });
+    }
+    if (result.status === 'confirmed' &&
+        result.correlationId &&
+        (result.firstSyncId <= 0 || result.lastSyncId <= 0)) {
+        context.addIssue({
+            code: 'custom',
+            path: ['lastSyncId'],
+            message: 'A source-confirmed result requires a durable positive sync range',
+        });
+    }
+});
+export const commitExecutionResultSchema = rawCommitExecutionResultSchema.transform((result) => ({
+    ...result,
+    status: result.status ?? 'confirmed',
+}));
+const ackCommonShape = {
+    lastSyncId: z.number().int().nonnegative(),
+    notifications: notificationsSchema.optional(),
+    missingIds: missingIdsSchema.optional(),
+};
+/** Normalized acknowledgement handed from a mutation transport to the queue. */
+export const commitAckSchema = z.discriminatedUnion('status', [
+    z
+        .strictObject({
+        ...ackCommonShape,
+        ...queuedSettlementShape,
+    })
+        .refine(({ lastSyncId }) => lastSyncId === 0, {
+        path: ['lastSyncId'],
+        message: 'A queued acknowledgement cannot claim a sync watermark',
+    }),
+    z
+        .strictObject({
+        ...ackCommonShape,
+        ...confirmedSettlementShape,
+    })
+        .refine(({ correlationId, lastSyncId }) => correlationId === undefined || lastSyncId > 0, {
+        path: ['lastSyncId'],
+        message: 'A source-confirmed acknowledgement requires a sync watermark',
+    }),
+]);
+/**
+ * The boundary an injected mutation executor returns through. It is the
+ * acknowledgement schema itself: settlement is declared, never inferred from
+ * an omission, so a transport cannot report a write as landed by staying
+ * silent about how it landed.
+ */
+export const mutationCommitResultSchema = commitAckSchema;
+/**
+ * Public SDK projection returned by `ablo.commits` and model mutations.
+ *
+ * This intentionally does not compose `commitSettlementSchema`: on the WS
+ * facade, `wait:'queued'` currently means locally sealed/enqueued, before a
+ * server has necessarily accepted the write. Renaming that public state to
+ * `enqueued` is a separate protocol change; the authoritative settlement
+ * union above is reserved for server acknowledgements.
+ */
+export const clientCommitReceiptSchema = z.strictObject({
+    id: z.string().min(1),
+    status: commitStatusSchema,
+    lastSyncId: z.number().int().nonnegative().optional(),
+    notifications: notificationsSchema.optional(),
+    missingIds: missingIdsSchema.optional(),
+});
+// ─────────────────────────────────────────────────────────────────────────
+//  The request side of the commit boundary
+// ─────────────────────────────────────────────────────────────────────────
+//
+// `POST /v1/commits` is the chokepoint every write passes through, so its
+// request shape is a boundary contract and belongs here beside the receipt it
+// answers with — not in a route handler. The published OpenAPI reference is
+// derived from these schemas rather than describing them separately, so the
+// documented surface cannot drift from the validated one.
+//
+// The server layers its own decoder-only compatibility spellings on top for
+// already-shipped clients; those are a rollout concern, not the contract.
+/** Control fields any operation in a commit may carry. */
+export const commitOperationControlShape = {
+    id: z.string().nullish(),
+    transactionId: z.string().nullish(),
+    readAt: z.number().nullish(),
+    onStale: onStaleModeSchema.nullish(),
+    fenceToken: z.number().nullish(),
+};
+/** One write inside a commit, in the canonical spelling. */
+export const commitOperationBodySchema = z.object({
+    ...commitOperationControlShape,
+    action: z.string(),
+    model: z.string(),
+    data: z.record(z.string(), z.unknown()).nullish(),
+});
+/**
+ * The `POST /v1/commits` request body.
+ *
+ * `operations` carries the writes; `track` registers durable premises.
+ * Neither is required on its own, because a body with `track` and no
+ * `operations` is how a caller starts watching a row without writing to it.
+ * Request identity travels in the `Idempotency-Key` header.
+ */
+export const commitRequestSchema = z.object({
+    operations: z.array(commitOperationBodySchema).min(1).optional(),
+    reads: z.array(readDependencySchema).nullish(),
+    track: z.array(trackDependencySchema).nullish(),
+});
+//# sourceMappingURL=commit.js.map

package/dist/wire/commit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commit.js","sourceRoot":"","sources":["../../src/wire/commit.ts"],"names":[],"mappings":"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"}

package/dist/wire/delta.d.ts

@@ -0,0 +1,251 @@
+/**
+ * The delta wire contract: the object the server broadcasts to a client as the
+ * payload of a `delta` or `sync_response` frame. Both the client SDK and the
+ * server derive their delta types from the schemas here, so the two ends share
+ * one definition and cannot drift apart. This is the delta's home in the wire
+ * layer, alongside the other protocol shapes in `wire/`.
+ *
+ * The wire delta is a projection of the stored `sync_deltas` row (the
+ * `syncDeltaRowSchema` in `../log/syncDeltaRow.ts`) and differs from it
+ * in three ways: it omits `organizationId` (the tenant-isolation predicate is
+ * never broadcast), it uses the full action vocabulary (see
+ * {@link syncDeltaActionSchema}) rather than plain create, update, and delete, and
+ * it carries attribution as nested {@link ParticipantRef}s instead of flat columns.
+ *
+ * The schemas layer a shared core plus per-side extensions:
+ *   - {@link syncDeltaWireCoreSchema} — the fields both sides agree on.
+ *   - {@link clientSyncDeltaSchema} — the core plus the fields only the client reads.
+ *   - {@link serverSyncDeltaSchema} — the core plus the audit attribution the server
+ *     adds to each broadcast, which the client ignores.
+ *
+ * The participant vocabulary the delta carries is declared once elsewhere and
+ * re-served here: the actor union lives in `types/participant.ts` and its
+ * runtime validator in `coordination/schema.ts`. Only `confirmationState` has
+ * its home in this module, since the approval stage of a committed change is
+ * delta attribution and nothing else. All three mirror Postgres enums.
+ */
+import { z } from 'zod';
+/** `participant_kind` — who a delta is attributed to. Declared in
+ *  `coordination/schema.ts`; re-exported so the wire subpath serves the
+ *  vocabulary its delta shapes carry. */
+export { participantKindSchema } from '../coordination/schema.js';
+export type { ParticipantKind } from '../types/participant.js';
+/** `confirmation_state` — the approval stage a committed change was in. */
+export declare const confirmationStateSchema: z.ZodEnum<{
+    auto: "auto";
+    previewed: "previewed";
+    approved: "approved";
+    required_human_approval: "required_human_approval";
+    auto_historical: "auto_historical";
+}>;
+export type ConfirmationState = z.infer<typeof confirmationStateSchema>;
+/**
+ * The full set of action codes a wire delta can carry — a broader vocabulary than
+ * the stored row's create, update, and delete. Each is a single character: `I`
+ * insert, `U` update, `D` delete, `A` archive, `V` revive (unarchive), `C` covering
+ * (the row just became visible to this subscriber), `G` group added, and `S` group
+ * removed.
+ */
+export declare const syncDeltaActionSchema: z.ZodEnum<{
+    I: "I";
+    U: "U";
+    D: "D";
+    A: "A";
+    V: "V";
+    C: "C";
+    G: "G";
+    S: "S";
+}>;
+export type SyncDeltaAction = z.infer<typeof syncDeltaActionSchema>;
+/**
+ * The payload carried on a wire delta: the post-mutation row as an object, a
+ * serialized string (used by the group-change frames on `G` and `S` deltas), or
+ * `null` on deletes. This is wider than the stored row's payload — which is only a
+ * row or null — because the group-change frames encode their payload as a string.
+ */
+export declare const wireDeltaDataSchema: z.ZodNullable<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodString]>>;
+export type WireDeltaData = z.infer<typeof wireDeltaDataSchema>;
+/**
+ * A participant reference as carried on a broadcast delta. The server expands the
+ * flat `actor_id` and `actor_kind` stored columns into this nested `{ kind, id }`
+ * shape. The type is the canonical {@link ParticipantRef} from
+ * `types/participant.ts`; the pin below fails to compile if this schema and the
+ * canonical shape ever drift.
+ */
+export declare const participantRefSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        user: "user";
+        agent: "agent";
+        system: "system";
+    }>;
+    id: z.ZodString;
+}, z.core.$strip>;
+export type { ParticipantRef } from '../types/participant.js';
+/**
+ * The fields the server and client agree on for a broadcast delta — the shared core
+ * both projections extend. `transactionId` is typed as the client sees it (an
+ * optional string); {@link serverSyncDeltaSchema} widens it to nullable. There is no
+ * `organizationId` here (it is never broadcast) and no attribution — those fields
+ * differ between the two sides and live in the extensions below.
+ */
+export declare const syncDeltaWireCoreSchema: z.ZodObject<{
+    id: z.ZodNumber;
+    actionType: z.ZodEnum<{
+        I: "I";
+        U: "U";
+        D: "D";
+        A: "A";
+        V: "V";
+        C: "C";
+        G: "G";
+        S: "S";
+    }>;
+    modelName: z.ZodString;
+    modelId: z.ZodString;
+    data: z.ZodNullable<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodString]>>;
+    previousData: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodString]>>>;
+    syncGroups: z.ZodArray<z.ZodString>;
+    transactionId: z.ZodOptional<z.ZodString>;
+    correlationId: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodString;
+}, z.core.$strip>;
+export type SyncDeltaWireCore = z.infer<typeof syncDeltaWireCoreSchema>;
+/**
+ * The client's view of a wire delta: the shared core plus the fields only the
+ * client reads. Inferring this schema gives the SDK's `SyncDelta` type.
+ */
+export declare const clientSyncDeltaSchema: z.ZodObject<{
+    id: z.ZodNumber;
+    actionType: z.ZodEnum<{
+        I: "I";
+        U: "U";
+        D: "D";
+        A: "A";
+        V: "V";
+        C: "C";
+        G: "G";
+        S: "S";
+    }>;
+    modelName: z.ZodString;
+    modelId: z.ZodString;
+    data: z.ZodNullable<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodString]>>;
+    previousData: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodString]>>>;
+    syncGroups: z.ZodArray<z.ZodString>;
+    transactionId: z.ZodOptional<z.ZodString>;
+    correlationId: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodString;
+    createdBy: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodString]>>>;
+    clientMutationId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ClientSyncDelta = z.infer<typeof clientSyncDeltaSchema>;
+/**
+ * The server's view of a wire delta: the shared core plus the audit attribution the
+ * server adds to each broadcast. The client structurally ignores these fields. This
+ * projection also narrows `transactionId` to nullable, matching the stored column.
+ */
+export declare const serverSyncDeltaSchema: z.ZodObject<{
+    id: z.ZodNumber;
+    actionType: z.ZodEnum<{
+        I: "I";
+        U: "U";
+        D: "D";
+        A: "A";
+        V: "V";
+        C: "C";
+        G: "G";
+        S: "S";
+    }>;
+    modelName: z.ZodString;
+    modelId: z.ZodString;
+    data: z.ZodNullable<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodString]>>;
+    previousData: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodString]>>>;
+    syncGroups: z.ZodArray<z.ZodString>;
+    correlationId: z.ZodOptional<z.ZodString>;
+    createdAt: z.ZodString;
+    projectId: z.ZodString;
+    transactionId: z.ZodNullable<z.ZodString>;
+    createdBy: z.ZodNullable<z.ZodObject<{
+        kind: z.ZodEnum<{
+            user: "user";
+            agent: "agent";
+            system: "system";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strip>>;
+    actor: z.ZodNullable<z.ZodObject<{
+        kind: z.ZodEnum<{
+            user: "user";
+            agent: "agent";
+            system: "system";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strip>>;
+    onBehalfOf: z.ZodNullable<z.ZodObject<{
+        kind: z.ZodEnum<{
+            user: "user";
+            agent: "agent";
+            system: "system";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strip>>;
+    capabilityId: z.ZodNullable<z.ZodString>;
+    confirmationState: z.ZodNullable<z.ZodEnum<{
+        auto: "auto";
+        previewed: "previewed";
+        approved: "approved";
+        required_human_approval: "required_human_approval";
+        auto_historical: "auto_historical";
+    }>>;
+}, z.core.$strip>;
+export type ServerSyncDelta = z.infer<typeof serverSyncDeltaSchema>;
+/**
+ * The transaction-layer seam's transport-neutral projection of a broadcast
+ * delta. It removes delivery plumbing (`syncGroups`, `transactionId`, and
+ * `correlationId`) while retaining the row change and optional audit
+ * attribution. `TransactionLayer.observe()` yields this shape.
+ */
+export declare const deltaSchema: z.ZodObject<{
+    id: z.ZodNumber;
+    data: z.ZodNullable<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodString]>>;
+    actionType: z.ZodEnum<{
+        I: "I";
+        U: "U";
+        D: "D";
+        A: "A";
+        V: "V";
+        C: "C";
+        G: "G";
+        S: "S";
+    }>;
+    modelName: z.ZodString;
+    modelId: z.ZodString;
+    previousData: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodString]>>>;
+    createdAt: z.ZodString;
+    actor: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        kind: z.ZodEnum<{
+            user: "user";
+            agent: "agent";
+            system: "system";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strip>>>;
+    onBehalfOf: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        kind: z.ZodEnum<{
+            user: "user";
+            agent: "agent";
+            system: "system";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strip>>>;
+    capabilityId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    confirmationState: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        auto: "auto";
+        previewed: "previewed";
+        approved: "approved";
+        required_human_approval: "required_human_approval";
+        auto_historical: "auto_historical";
+    }>>>;
+}, z.core.$strip>;
+export type Delta = z.infer<typeof deltaSchema>;
+//# sourceMappingURL=delta.d.ts.map

package/dist/wire/delta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delta.d.ts","sourceRoot":"","sources":["../../src/wire/delta.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAQxB;;yCAEyC;AACzC,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAClE,YAAY,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAE/D,2EAA2E;AAC3E,eAAO,MAAM,uBAAuB;;;;;;EAMlC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAIxE;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;EAAmD,CAAC;AACtF,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,2FAEnB,CAAC;AACd,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB;;;;;;;iBAG/B,CAAC;AACH,YAAY,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAO9D;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;iBAYlC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE;;;GAGG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;iBAQhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE;;;;GAIG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAiBhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE;;;;;GAKG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAWpB,CAAC;AACL,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC"}