@abloatai/ablo 0.36.0 → 0.37.0

package/dist/transaction/wire/commit.js

@@ -1,321 +0,0 @@
-/**
- * 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(),
-});

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

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