@abloatai/transaction 0.37.0

package/src/wire/index.ts

@@ -0,0 +1,328 @@
+/**
+ * The wire contract for the sync protocol: the HTTP envelope shapes and the
+ * write-path frames, with no dependency on the client runtime. A server — a
+ * route handler, an edge function — can import the envelope producers here
+ * without pulling in the full sync client.
+ *
+ * It has two halves, used across every endpoint:
+ *   - Error responses — {@link errorEnvelope}, {@link ErrorEnvelope}, and
+ *     {@link statusForType} turn any thrown value into the uniform
+ *     `{ type, code, param, message, doc_url, request_id }` body.
+ *   - List responses — {@link listEnvelope} and {@link ListEnvelope} stamp the
+ *     uniform `{ object: 'list', data, has_more, next_cursor }` collection.
+ *
+ * The {@link AbloError} hierarchy, {@link docUrlForCode}, and the wire-parsing
+ * helpers are re-exported too, so a single import lets a route throw the right
+ * typed error and serialize it back out.
+ */
+export {
+  errorEnvelopeSchema,
+  errorEnvelope,
+  statusForType,
+  INTERNAL_ERROR_PUBLIC_MESSAGE,
+} from './errorEnvelope.js';
+export type { ErrorEnvelope } from './errorEnvelope.js';
+export { listEnvelopeSchema, listEnvelope } from './listEnvelope.js';
+export type { ListEnvelope } from './listEnvelope.js';
+
+// The `GET /v1/logs` feed — the two arms, their envelope, and the cursor that
+// carries a position in each.
+export { claimEventSchema } from './claimEvent.js';
+export type { ClaimEvent } from './claimEvent.js';
+export {
+  feedEventSchema,
+  logListResponseSchema,
+  logQuerySchema,
+} from './feedEvent.js';
+export type { FeedEvent, LogListResponse, LogQuery } from './feedEvent.js';
+export {
+  feedCursorSchema,
+  parseFeedCursor,
+  formatFeedCursor,
+  feedCursorAdvanced,
+  FEED_CURSOR_START,
+  FEED_CURSOR_FORMAT,
+  FEED_CURSOR_EXAMPLE,
+} from './feedCursor.js';
+export type { FeedCursor } from './feedCursor.js';
+export { bootstrapReasonSchema } from './bootstrapReason.js';
+export type { BootstrapReason } from './bootstrapReason.js';
+
+// The write-path frame contract: the message shapes shared by the client and
+// the server. The runtime Zod validators sit beside the interfaces and are
+// pinned to them, and they gate every operation and payload on both commit
+// transports.
+export {
+  commitOperationSchema,
+  wireCommitOperationSchema,
+  commitPayloadSchema,
+  commitMessageSchema,
+} from './frames.js';
+
+// Protocol versioning: the single integer the client and server compare to
+// confirm they can speak to each other, plus the WebSocket close code used to
+// reject a mismatch. See protocolVersion.ts for the changelog and deploy rules.
+export {
+  PROTOCOL_VERSION,
+  MIN_SUPPORTED_PROTOCOL_VERSION,
+  DEFAULT_PROTOCOL_VERSION,
+  SUPPORTED_PROTOCOL_VERSIONS,
+  WS_CLOSE_PROTOCOL_VERSION,
+  PROTOCOL_VERSION_HEADER,
+  protocolVersionProblem,
+  resolveProtocolVersion,
+} from './protocolVersion.js';
+export type {
+  SupportedProtocolVersion,
+  ProtocolVersionProblem,
+} from './protocolVersion.js';
+export type {
+  CommitOperation,
+  WireCommitOperation,
+  CommitMessage,
+  MutationResultMessage,
+} from './frames.js';
+
+// Commit settlement backbone. The transport receipt, server execution cache,
+// and normalized client acknowledgement are different envelopes composed from
+// this one discriminated settlement vocabulary.
+export {
+  COMMIT_CORRELATION_ID_MAX_LENGTH,
+  correlationIdSchema,
+  commitStatusSchema,
+  commitWaitSchema,
+  commitSettlementSchema,
+  commitReceiptSchema,
+  rejectedCommitReceiptSchema,
+  mutationResultPayloadSchema,
+  mutationResultMessageSchema,
+  commitAckSchema,
+  mutationCommitResultSchema,
+  // The request side of the same boundary — one definition, which the published
+  // OpenAPI reference derives from rather than describing separately.
+  commitOperationControlShape,
+  commitOperationBodySchema,
+  commitRequestSchema,
+} from './commit.js';
+export type {
+  CommitOperationBody,
+  CommitRequest,
+  CorrelationId,
+  CommitStatus,
+  CommitWait,
+  CommitSettlement,
+  CommitReceiptWire,
+  RejectedCommitReceiptWire,
+  MutationResultPayload,
+  MutationResultMessageWire,
+  CommitAck,
+  MutationCommitResultInput,
+  MutationCommitResult,
+} from './commit.js';
+
+// The read-path delta contract: the shape the server broadcasts to clients as the
+// payload of a `delta` or `sync_response` frame, together with the shared
+// participant vocabulary it carries. Both ends derive their delta type from these
+// schemas, so the client and server cannot drift apart.
+export {
+  participantKindSchema,
+  confirmationStateSchema,
+  syncDeltaActionSchema,
+  wireDeltaDataSchema,
+  participantRefSchema,
+  syncDeltaWireCoreSchema,
+  clientSyncDeltaSchema,
+  serverSyncDeltaSchema,
+  deltaSchema,
+} from './delta.js';
+export type {
+  ParticipantKind,
+  ConfirmationState,
+  SyncDeltaAction,
+  WireDeltaData,
+  ParticipantRef,
+  SyncDeltaWireCore,
+  ClientSyncDelta,
+  ServerSyncDelta,
+  Delta,
+} from './delta.js';
+
+// The error surface a wire consumer needs to throw, classify, and serialize.
+export {
+  AbloError,
+  AbloAuthenticationError,
+  AbloPermissionError,
+  AbloValidationError,
+  AbloRateLimitError,
+  AbloIdempotencyError,
+  AbloConnectionError,
+  AbloNotFoundError,
+  AbloServerError,
+  AbloStaleContextError,
+  AbloContentionError,
+  AbloClaimedError,
+  CapabilityError,
+  AbloSessionError,
+  SyncSessionError,
+  docUrlForCode,
+  translateHttpError,
+  errorFromWire,
+  toAbloError,
+  ERROR_CONTRACT_VERSION,
+  // The table mapping each error code to its HTTP status and retryable flag —
+  // plain data a server can use to resolve a code's canonical status the same
+  // way the client's error serializer does.
+  errorCodeSpec,
+} from '../errors.js';
+export type { ErrorCode, WireErrorCode, RequiredCapability } from '../errors.js';
+
+// Protocol timing constants — the 30-second ping cadence and the lease window
+// derived from it, shared by the client heartbeat and the server keepalive,
+// claim leasing, and presence expiry (see protocol.ts) — plus the WebSocket
+// subprotocols used during the authenticated handshake.
+export {
+  PING_INTERVAL_MS,
+  LEASE_TTL_MS,
+  WS_BEARER_SUBPROTOCOL_PREFIX,
+  WS_SYNC_SUBPROTOCOL,
+} from './protocol.js';
+
+// The claim routes' half of the boundary — requests and responses both, beside
+// the commit body for the same reason: the server answers in these shapes, the
+// client reads them back through the same schemas, and the OpenAPI reference
+// derives from them rather than describing them from memory.
+export {
+  // The lease grammar and its one reading. The server parses TTLs with
+  // `claimTtlMs` rather than carrying a second parser — which is how a bare
+  // number came to mean seconds on one side and milliseconds on the other.
+  DEFAULT_CLAIM_TTL_MS,
+  claimTtlSchema,
+  claimTtlMs,
+  claimTargetSchema,
+  claimRequestSchema,
+  claimHeartbeatRequestSchema,
+  listQuerySchema,
+  claimListQuerySchema,
+  claimStateSchema,
+  claimAcquiredResponseSchema,
+  claimQueuedResponseSchema,
+  claimAcquireResponseSchema,
+  claimHeartbeatReplySchema,
+  claimHeartbeatBatchReplySchema,
+  claimListResponseSchema,
+  claimReorderRequestSchema,
+  claimReorderReplySchema,
+  claimReleaseReplySchema,
+} from './claims.js';
+export type {
+  ClaimTargetBody,
+  ClaimRequest,
+  ClaimHeartbeatRequest,
+  ListQuery,
+  ClaimListQuery,
+  ClaimState,
+  ClaimAcquiredResponse,
+  ClaimQueuedResponse,
+  ClaimAcquireResponse,
+  ClaimHeartbeatReply,
+  ClaimHeartbeatBatchReply,
+  ClaimListResponse,
+  ClaimReorderRequest,
+  ClaimReorderReply,
+  ClaimReleaseReply,
+} from './claims.js';
+
+// The model read routes' responses — the envelope around a row, which is
+// protocol, around `data`, which is the caller's schema.
+export {
+  modelReadResponseSchema,
+  modelListResponseSchema,
+} from './modelResponses.js';
+export type { ModelReadResponse, ModelListResponse } from './modelResponses.js';
+
+// What a model is made of — the artifact's own field and relation shapes, which
+// the schema read reports and every other layer derives its types from.
+export {
+  fieldTypeSchema,
+  fieldMetaSchema,
+  relationTypeSchema,
+  relationMetaSchema,
+} from './modelShape.js';
+export type {
+  FieldType,
+  FieldMeta,
+  RelationType,
+  RelationMeta,
+} from './modelShape.js';
+
+// The model write routes' body — the record in `data`, the guards beside it.
+export { modelMutationRequestSchema } from './modelMutations.js';
+export type { ModelMutationRequest } from './modelMutations.js';
+
+// The account routes' responses — projects, the deployed schema, the commit
+// log, usage. What the server, the CLI, and the MCP server agree on.
+export {
+  projectResponseSchema,
+  projectListResponseSchema,
+  provisionedKeySchema,
+  provisionKeyResponseSchema,
+  conflictAxisWireSchema,
+  schemaModelResponseSchema,
+  schemaReadResponseSchema,
+  logOpSchema,
+  LOG_OP_BY_ACTION,
+  logEventSchema,
+  usageBucketSchema,
+  usageReportResponseSchema,
+  controlKeySchema,
+  controlKeyListResponseSchema,
+  keyMintedResponseSchema,
+  keyRevokedResponseSchema,
+} from './accountResponses.js';
+export type {
+  ProjectResponse,
+  ProjectListResponse,
+  ProvisionedKey,
+  ProvisionKeyResponse,
+  SchemaModelResponse,
+  SchemaReadResponse,
+  LogOp,
+  LogEvent,
+  UsageBucket,
+  UsageReportResponse,
+  ControlKey,
+  ControlKeyListResponse,
+  KeyMintedResponse,
+  KeyRevokedResponse,
+} from './accountResponses.js';
+
+// The inbound socket surface: every frame the server can send, and how each
+// one's payload is validated.
+export {
+  WS_INBOUND_FRAMES,
+  wsInboundEnvelopeSchema,
+  isKnownInboundFrame,
+  isSchemaValidatedFrame,
+} from './inboundFrames.js';
+export type {
+  InboundFrameContract,
+  InboundFrameType,
+  InboundFramePayload,
+  SchemaValidatedFrameType,
+  WsInboundEnvelope,
+} from './inboundFrames.js';
+
+// Credential minting — the first call any caller makes, so the contract cannot
+// omit it. Response side lives in `auth/schemas.ts`.
+export {
+  ephemeralKeyUserSchema,
+  ephemeralKeyRequestSchema,
+  capabilityRequestSchema,
+  capabilityMintResponseSchema,
+} from './auth.js';
+export type {
+  EphemeralKeyUser,
+  EphemeralKeyRequest,
+  CapabilityRequest,
+  CapabilityMintResponse,
+} from './auth.js';

package/src/wire/listEnvelope.ts

@@ -0,0 +1,51 @@
+/**
+ * The envelope every endpoint that returns a collection wraps its results in.
+ * Because the shape is always the same — `{ object: 'list', data, has_more,
+ * next_cursor }` — a consumer can detect and paginate any list the same way,
+ * instead of learning a different payload key for each endpoint.
+ *
+ * The list endpoints emit this shape and the {@link listEnvelope} helper
+ * produces it, so every list across the API reads from one definition. The
+ * generic type parameter carries the row type of `data`.
+ */
+import { z } from 'zod';
+
+/**
+ * Builds the authoritative list-envelope schema for a row schema. Keeping the
+ * item validator generic lets every endpoint share the same envelope contract
+ * without weakening `data` to `unknown[]`.
+ */
+export function listEnvelopeSchema<T>(itemSchema: z.ZodType<T>) {
+  return z.object({
+    object: z.literal('list'),
+    data: z.array(itemSchema).readonly(),
+    has_more: z.boolean(),
+    next_cursor: z.string().nullable(),
+  });
+}
+
+export type ListEnvelope<T> = Readonly<z.infer<
+  ReturnType<typeof listEnvelopeSchema<T>>
+>>;
+
+/**
+ * Wraps an already-fetched page of rows in the uniform {@link ListEnvelope}.
+ *
+ * Pagination stays the caller's job — fetch one more row than the limit to
+ * decide `hasMore`, and derive the cursor from the last row's sort key. This
+ * helper only applies the envelope so no endpoint has to build the shape by
+ * hand. The defaults describe a small, unpaginated collection
+ * (`has_more: false`, `next_cursor: null`); a paginated endpoint passes both
+ * explicitly.
+ */
+export function listEnvelope<T>(
+  data: readonly T[],
+  opts: { hasMore?: boolean; nextCursor?: string | null } = {},
+): ListEnvelope<T> {
+  return {
+    object: 'list',
+    data,
+    has_more: opts.hasMore ?? false,
+    next_cursor: opts.nextCursor ?? null,
+  };
+}

package/src/wire/modelMutations.ts

@@ -0,0 +1,55 @@
+/**
+ * The body of a model-scoped write — `POST /v1/models/{model}`,
+ * `PATCH /v1/models/{model}/{id}`, `DELETE /v1/models/{model}/{id}`.
+ *
+ * The record travels in `data`, and everything else is a control field beside
+ * it rather than inside it. That separation is the point: a row with a column
+ * called `claim` or `readAt` is not a reason for a write to stop being guarded,
+ * and a flat body would make the two indistinguishable.
+ *
+ * This lived in `routes/commit.ts` and the published reference described these
+ * routes as taking a bare row — so a client built from the document sent the
+ * record flat, and every field of it went missing at once. The failure surfaced
+ * as `not_null_violation` from the column, which reads as a schema problem
+ * rather than an envelope one. One definition, derived, is what stops that:
+ * the server validates against this and the reference is generated from it.
+ */
+
+import { z } from 'zod';
+import { onStaleModeSchema } from '../coordination/schema.js';
+
+export const modelMutationRequestSchema = z.object({
+  /** The record. Its shape is your schema's; everything around it is protocol. */
+  data: z.record(z.string(), z.unknown()).nullish(),
+  /**
+   * The row id.
+   *
+   * On `POST` this is where it comes from, and it is **yours to choose** —
+   * Ablo mints none. Derive it as UUID v5 of `"<model>:<Idempotency-Key>"` in
+   * namespace `aa4ba6d4-bf0b-5b38-9c45-116f79a6e548` and a retry after a lost
+   * response inserts the same id, colliding with the original rather than
+   * writing a second row — with no server state to consult, so it holds across
+   * instances and outlives any idempotency record.
+   *
+   * On `PATCH` and `DELETE` the path names the row and this is redundant.
+   */
+  id: z.string().nullish(),
+  /** The claim this write is made under — a claim id you hold. */
+  claim: z.string().nullish(),
+  /** What to do when the row moved since `readAt`. Defaults to rejecting. */
+  onStale: onStaleModeSchema.nullish(),
+  /**
+   * The watermark this write's decision was made against — the `stamp` from
+   * the read. Ablo rejects the write if the row moved in between, which is
+   * what makes read → decide → write safe without a lock across the deciding.
+   */
+  readAt: z.number().nullish(),
+  /**
+   * The fencing token from the claim's grant. Closes the window `readAt` alone
+   * cannot: a lease that lapsed and whose successor came and went.
+   */
+  fenceToken: z.number().nullish(),
+  /** @compat HTTP idempotency belongs in the `Idempotency-Key` header. */
+  idempotencyKey: z.string().optional(),
+});
+export type ModelMutationRequest = z.infer<typeof modelMutationRequestSchema>;

package/src/wire/modelResponses.ts

@@ -0,0 +1,48 @@
+/**
+ * What the model read routes answer with — `GET /v1/models/{model}/{id}` and
+ * `GET /v1/models/{model}`.
+ *
+ * `data` is `unknown` here on purpose. The transport that reads these responses
+ * is schema-agnostic: it moves rows for whatever schema the caller declared, so
+ * it validates the envelope around a row and leaves the row itself to the typed
+ * surface above it. Everything outside `data` — the watermark, the claims, the
+ * pagination — is protocol, and protocol is validated here.
+ */
+
+import { z } from 'zod';
+import { modelClaimSchema } from '../coordination/schema.js';
+import { listEnvelopeSchema } from './listEnvelope.js';
+
+/**
+ * `GET /v1/models/{model}/{id}`.
+ *
+ * `stamp` is the row's watermark: the log position the read reflects. A write
+ * that guards on this premise (`readAt`) is rejected if the row moved on in
+ * between, which is what makes a read→decide→write sequence safe without a
+ * lock. A missing row answers 404, so `data` is always present here.
+ */
+export const modelReadResponseSchema = z.object({
+  object: z.literal('model'),
+  model: z.string(),
+  id: z.string(),
+  data: z.unknown(),
+  stamp: z.number(),
+  /** Who holds this row right now — empty when no claim store is configured. */
+  claims: z.array(modelClaimSchema).readonly(),
+});
+export type ModelReadResponse = z.infer<typeof modelReadResponseSchema>;
+
+/**
+ * `GET /v1/models/{model}` — the list envelope, with the two fields the model
+ * routes add to it: the model's name and the org-wide watermark the page was
+ * read at.
+ *
+ * The envelope is derived, not restated. A schema-agnostic row is `z.unknown()`,
+ * which the generic helper accepts like any other item schema, so there is no
+ * layer at which the shared fields have to be spelled a second time.
+ */
+export const modelListResponseSchema = listEnvelopeSchema(z.unknown()).extend({
+  model: z.string(),
+  stamp: z.number(),
+});
+export type ModelListResponse = z.infer<typeof modelListResponseSchema>;

package/src/wire/modelShape.ts

@@ -0,0 +1,83 @@
+/**
+ * What a model is made of — its fields and its edges.
+ *
+ * These shapes travel twice: they are what `ablo push` serializes into the
+ * schema artifact, and what `GET /api/schema` reports back about the artifact
+ * that is deployed. Two crossings, one definition, and the definition lives
+ * here because `wire/` is the leaf every other layer may depend on.
+ *
+ * They were TypeScript interfaces, so the schema-read route could not send them
+ * without hand-writing a second copy of the record it was refusing to send — the
+ * shadow type wearing the fix's clothes. Declared as Zod and derived back into
+ * TypeScript, there is nowhere for a second copy to live.
+ *
+ * **Vocabulary ownership.** `type` is a CLOSED enum: the engine owns the set of
+ * types it can store and serialize, so a value outside it is a bug, not an
+ * extension. `enumValues` is an OPEN list: the values belong to the application
+ * that declared them, and the protocol never interprets one.
+ */
+
+import { z } from 'zod';
+
+/**
+ * The engine's type vocabulary — closed, and owned by the engine.
+ *
+ * Each member maps to storage and serialization behaviour, so this is the whole
+ * set by construction. A schema's own richer types (a `z.email()`, a branded id)
+ * narrow one of these; they do not add a member.
+ */
+export const fieldTypeSchema = z.enum([
+  'string',
+  'number',
+  'boolean',
+  'date',
+  'enum',
+  'json',
+]);
+export type FieldType = z.infer<typeof fieldTypeSchema>;
+
+/** One field of a model, as the schema artifact records it. */
+export const fieldMetaSchema = z.object({
+  /** Sync-engine type tag, which maps to storage and serialization hints. */
+  type: fieldTypeSchema,
+  /** Whether the field was marked optional via `.optional()` or `.nullable()`. */
+  isOptional: z.boolean(),
+  /** Whether the field was marked indexed via `.indexed()`. */
+  isIndexed: z.boolean(),
+  /**
+   * Physical database column name override. When absent, SQL layers derive the
+   * column from the field name using the active casing convention.
+   */
+  column: z.string().optional(),
+  /**
+   * For enums: the allowed values.
+   *
+   * The application's vocabulary, carried verbatim — an open list, because the
+   * protocol has no opinion about what a caller's statuses are called.
+   */
+  enumValues: z.array(z.string()).readonly().optional(),
+});
+export type FieldMeta = z.infer<typeof fieldMetaSchema>;
+
+/**
+ * How one model points at another. Closed, like {@link fieldTypeSchema}: the
+ * engine resolves exactly these three when it plans a read.
+ */
+export const relationTypeSchema = z.enum(['belongsTo', 'hasMany', 'hasOne']);
+export type RelationType = z.infer<typeof relationTypeSchema>;
+
+/**
+ * One edge of a model — what a caller may expand, and what it expands into.
+ *
+ * Reported alongside the fields because half the answer is not an answer: an
+ * agent asking what a model looks like wants its shape AND its edges, and
+ * shipping only the scalars invites the second question immediately.
+ */
+export const relationMetaSchema = z.object({
+  type: relationTypeSchema,
+  /** The schema key of the model on the other end. */
+  target: z.string(),
+  /** The field on the owning side that carries the link. */
+  foreignKey: z.string(),
+});
+export type RelationMeta = z.infer<typeof relationMetaSchema>;

package/src/wire/protocol.ts

@@ -0,0 +1,39 @@
+/**
+ * The timing constants both sides of the protocol must agree on: the ping
+ * cadence and the lease window derived from it. Defining them here once keeps
+ * the client and the server from skewing apart — a change to the ping interval
+ * that did not also move the lease window would make claim expiry and presence
+ * timeouts disagree between the two.
+ *
+ * {@link PING_INTERVAL_MS} is how often the connection pings to prove it is
+ * alive. {@link LEASE_TTL_MS} is how long a claim or presence entry stays valid
+ * without a renewing ping. On the client, these set the heartbeat cadence and
+ * the fallback expiry for a claim taken without an explicit lease. On the
+ * server, they set the keepalive interval, the lease granted per keepalive, and
+ * the presence-entry lifetime, so a silently disconnected client drops off the
+ * roster within one lease window.
+ *
+ * The lease is three ping intervals long and is renewed on every ping, so a
+ * live holder always has at least two intervals of runway and a silent one
+ * lapses about two missed pings after it stops renewing. The window measures
+ * liveness, not how long a task may run: widening the lease without also
+ * widening the ping makes holders flap, and neither value should be redefined
+ * anywhere else.
+ */
+export const PING_INTERVAL_MS = 30_000;
+export const LEASE_TTL_MS = 3 * PING_INTERVAL_MS;
+
+/**
+ * The WebSocket subprotocols that carry the bearer credential out of the URL.
+ *
+ * A browser cannot set an `Authorization` header on a WebSocket, so the client
+ * offers the token as a `Sec-WebSocket-Protocol` value — `ablo.bearer.<token>` —
+ * alongside the real `ablo.sync.v1` protocol the server selects. This keeps the
+ * credential out of the query string, which access logs, proxies, and browser
+ * history would otherwise capture. The server reads the token from the
+ * subprotocol and echoes back only `ablo.sync.v1`, never the token-bearing
+ * value. Both the client and the server import these constants, so the
+ * handshake format cannot drift.
+ */
+export const WS_BEARER_SUBPROTOCOL_PREFIX = 'ablo.bearer.';
+export const WS_SYNC_SUBPROTOCOL = 'ablo.sync.v1';