@abloatai/transaction 0.37.0

package/src/wire/feedCursor.ts

@@ -0,0 +1,91 @@
+/**
+ * The resume position for `GET /v1/logs`.
+ *
+ * The feed merges two independently-sequenced sources — the settlement log and
+ * the claim-event log — so one opaque cursor has to carry two positions. They
+ * cannot share a sequence: allocating claim positions from `next_sync_id` would
+ * put ephemeral leases into the log that clients materialize rows from and that
+ * WAL-echo promotion and compaction operate over, where a claim-churn storm
+ * would be indistinguishable from committed change.
+ *
+ * Encoded `"<log>.<claims>"`, and a bare `"<log>"` still parses — cursors are
+ * persisted by callers, and every one issued before this existed is a plain
+ * delta id. Those resume at claim position 0, which is correct: a caller who
+ * never asked for claim events has no claim position to preserve.
+ *
+ * **A malformed cursor is an error, never a position.** The previous reader was
+ * `parseInt(raw, 10)` with `NaN ? 0 : n`, so a truncated or garbled cursor
+ * silently resumed from the beginning of the log and replayed it in full. That
+ * is the worst available failure: it looks like a working follow, and the
+ * damage scales with how long the log has been running. Parsing returns null
+ * and the route answers `invalid_request`.
+ */
+
+import { z } from 'zod';
+
+export const feedCursorSchema = z.object({
+  /** Last delta id delivered. */
+  log: z.number().int().nonnegative(),
+  /** Last claim-event seq delivered. */
+  claims: z.number().int().nonnegative(),
+});
+export type FeedCursor = z.infer<typeof feedCursorSchema>;
+
+/**
+ * The cursor grammar, in one place, so the parser and the error that rejects a
+ * bad one cannot describe it differently. A reader who is told what shape was
+ * expected can fix the call; a reader told only that theirs was wrong cannot.
+ */
+export const FEED_CURSOR_FORMAT = '<log>[.<claims>]';
+
+/** A cursor that shows the grammar rather than only naming it. */
+export const FEED_CURSOR_EXAMPLE = '4210.17';
+
+/** The cursor a caller resumes from when they send none. */
+export const FEED_CURSOR_START: FeedCursor = { log: 0, claims: 0 };
+
+/**
+ * Reads a wire cursor. Returns null when the string is not one — the caller
+ * turns that into `invalid_request` rather than guessing a position.
+ *
+ * Deliberately strict: only digits and at most one separator. `Number()` alone
+ * would accept `'1e3'`, `'0x10'`, `' 42 '`, and `''`, each of which would
+ * resume somewhere the caller did not ask for.
+ */
+export function parseFeedCursor(raw: string): FeedCursor | null {
+  const match = /^(\d+)(?:\.(\d+))?$/.exec(raw);
+  if (!match) return null;
+  const parsed = feedCursorSchema.safeParse({
+    log: Number(match[1]),
+    claims: match[2] === undefined ? 0 : Number(match[2]),
+  });
+  if (!parsed.success) return null;
+  // Beyond 2^53 the positions stop round-tripping through JSON's number type,
+  // and a cursor that cannot round-trip is not a cursor.
+  if (
+    !Number.isSafeInteger(parsed.data.log) ||
+    !Number.isSafeInteger(parsed.data.claims)
+  ) {
+    return null;
+  }
+  return parsed.data;
+}
+
+/** Writes a wire cursor. Always both positions, so the shape never varies. */
+export function formatFeedCursor(cursor: FeedCursor): string {
+  return `${cursor.log}.${cursor.claims}`;
+}
+
+/**
+ * Whether `next` is ahead of `prev` on either axis — the guard a follow loop
+ * needs so a stale or duplicated page cannot rewind it.
+ *
+ * It lives here because the alternative is what every caller reaches for first:
+ * comparing the cursor STRINGS as numbers. `Number('42.10')` is `42.1`, which
+ * compares as *behind* `42.9` and re-serializes as `'42.1'` — a cursor that
+ * silently skips eight claim positions and looks like it worked. A cursor is
+ * opaque to its holder; only this module takes it apart.
+ */
+export function feedCursorAdvanced(prev: FeedCursor, next: FeedCursor): boolean {
+  return next.log > prev.log || next.claims > prev.claims;
+}

package/src/wire/feedEvent.ts

@@ -0,0 +1,74 @@
+/**
+ * What `GET /v1/logs` returns: one envelope, two arms.
+ *
+ * The feed answers two questions that a caller without a socket cannot
+ * otherwise ask — "what changed" and "who is working on what" — and it answers
+ * them through one endpoint, one envelope, and one cursor grammar rather than
+ * growing a second feed with its own pagination dialect beside the first.
+ *
+ * The arms stay separately sequenced. A claim is a lease, not a settled fact,
+ * and putting one into the log that clients materialize rows from — and that
+ * WAL-echo promotion and compaction operate over — would make a claim-churn
+ * storm indistinguishable from committed change. They share a reading, not a
+ * sequence; {@link FeedCursor} is what carries both positions.
+ */
+
+import { z } from 'zod';
+import { logEventSchema, logOpSchema, type LogEvent } from './accountResponses.js';
+import { claimEventSchema, type ClaimEvent } from './claimEvent.js';
+import { listEnvelopeSchema, type ListEnvelope } from './listEnvelope.js';
+
+/**
+ * One entry, from either source. Discriminated on `object`, so a consumer
+ * reading an arm it does not know still parses the page and can skip the entry
+ * — which is what lets the claim arm be added to a running feed at all.
+ */
+export const feedEventSchema = z.discriminatedUnion('object', [
+  logEventSchema,
+  claimEventSchema,
+]);
+export type FeedEvent = LogEvent | ClaimEvent;
+
+/** `GET /v1/logs` — the canonical list envelope over the feed. */
+export const logListResponseSchema = listEnvelopeSchema(feedEventSchema);
+export type LogListResponse = ListEnvelope<FeedEvent>;
+
+/**
+ * The query string on `GET /v1/logs`.
+ *
+ * Values arrive as strings, so this describes the wire spelling rather than the
+ * parsed result — the same reason {@link listQuerySchema} does.
+ *
+ * Scope is NOT here and never will be: the plane, the organization and the sync
+ * groups all come off the credential. A caller cannot widen what it sees by
+ * asking, which is what makes this feed safe to hand an agent.
+ */
+export const logQuerySchema = z.object({
+  /**
+   * The `next_cursor` from the previous page, copied back unchanged. Omit it to
+   * start from the most recent entries — this is a tail, so the first page is
+   * the end of the log and `after` walks forward from there.
+   */
+  after: z.string().optional(),
+  /** Entries per page. Clamped server-side; the default is a short tail. */
+  limit: z.string().optional(),
+  /** Only this model's entries. */
+  model: z.string().optional(),
+  /** Only this kind of change. */
+  op: logOpSchema.optional(),
+  /** Only entries at or after this ISO 8601 timestamp. */
+  since: z.string().optional(),
+});
+export type LogQuery = z.infer<typeof logQuerySchema>;
+
+/**
+ * The claim arm has no producer yet: claim transitions are broadcast today and
+ * recorded nowhere, so there is no sequence to read `seq` from. Until that log
+ * exists the route emits only `log_event`s, and there is deliberately NO
+ * request parameter for selecting arms — a knob that cannot be honoured is how
+ * a contract comes to describe a server that does not exist.
+ *
+ * What is here is the definition the producer will fill: the union parses
+ * today's pages unchanged, and the cursor already carries the second position.
+ */
+

package/src/wire/frames.ts

@@ -0,0 +1,77 @@
+/**
+ * The write-path message shapes for the sync protocol. These cover the frames
+ * a client sends to commit work — {@link CommitMessage}, a batch of raw
+ * operations — and the server's {@link MutationResultMessage}
+ * acknowledgement. The same frames flow over a WebSocket connection and over
+ * the HTTP commit endpoint.
+ *
+ * Both the client and the server import these definitions from here, so the two
+ * sides cannot drift. Zod schemas are the definition site and every TypeScript
+ * shape is inferred from them. Changing any schema in this file changes the
+ * wire contract and requires the client and server to update together.
+ */
+import { z } from 'zod';
+// The runtime schema primitives are imported straight from the coordination
+// schema module to keep this file's runtime dependencies limited to Zod.
+import {
+  commitOperationSchema as coordinationCommitOperationSchema,
+  readDependencySchema,
+  trackDependencySchema,
+} from '../coordination/schema.js';
+import type { MutationResultMessageWire } from './commit.js';
+
+// ── Client → Server ────────────────────────────────────────────────────────
+
+/**
+ * A single operation within a commit batch and its authoritative runtime
+ * validator. Each operation is the smallest unit the server applies atomically
+ * — one create, update, delete, archive, or unarchive against one model row.
+ * Both commit transports — the WebSocket `commit` frame and the HTTP
+ * `/v1/commits` endpoint — run this check
+ * on every operation before it is applied, so a malformed operation is rejected
+ * at the edge. It builds on the shared coordination schema, widening `bypass`
+ * to also accept `null`. The TypeScript type is inferred from this schema so
+ * the runtime and compile-time contracts have one definition site.
+ */
+export const wireCommitOperationSchema = coordinationCommitOperationSchema.extend({
+  bypass: z.boolean().nullish(),
+});
+export type WireCommitOperation = z.infer<typeof wireCommitOperationSchema>;
+
+/**
+ * @deprecated Renamed to {@link WireCommitOperation} — coordination/schema owns
+ * the base `CommitOperation`; this is the wire-extended form, and the two are
+ * different types that shared one name. Removed in 0.36.0.
+ */
+export type CommitOperation = WireCommitOperation;
+/** @deprecated Renamed to {@link wireCommitOperationSchema}. Removed in 0.36.0. */
+export const commitOperationSchema = wireCommitOperationSchema;
+
+/**
+ * The authoritative payload schema for a client-to-server commit frame. It
+ * checks every field the server acts on — `operations`, `clientTxId`, and
+ * `reads` — validating each operation with {@link wireCommitOperationSchema} and
+ * each premise entry with the shared {@link readDependencySchema}.
+ */
+export const commitPayloadSchema = z.object({
+  operations: z.array(wireCommitOperationSchema),
+  clientTxId: z.string(),
+  reads: z.array(readDependencySchema).nullish(),
+  track: z.array(trackDependencySchema).nullish(),
+});
+
+/** A client-to-server frame that asks the server to commit a batch atomically. */
+export const commitMessageSchema = z.object({
+  type: z.literal('commit'),
+  payload: commitPayloadSchema,
+});
+export type CommitMessage = z.infer<typeof commitMessageSchema>;
+
+// ── Server → Client ──────────────────────────────────────────────────────
+
+/**
+ * The server's acknowledgement of a {@link CommitMessage}. Runtime shape and
+ * TypeScript type are both owned by `wire/commit.ts`; HTTP, WebSocket, and
+ * cached replay no longer maintain parallel receipt declarations.
+ */
+export type MutationResultMessage = MutationResultMessageWire;

package/src/wire/inboundFrames.ts

@@ -0,0 +1,182 @@
+/**
+ * Every frame the server can send, in one list.
+ *
+ * Before this existed, "what frames are there" was answerable only by reading
+ * the dispatch table, the transport's event map, and each handler's defensive
+ * narrowing together — three places that agreed by convention. This registry is
+ * the single answer, and it carries how each frame's payload is validated.
+ *
+ * A frame is validated one of two ways. Most carry a `payload` schema and are
+ * parsed here, before the handler runs, so a handler receives a value whose
+ * shape is already proven. The rest are marked `handler` because their
+ * validation is genuinely load-bearing elsewhere — a delta is checked once
+ * downstream against the schema the materialiser holds, and a commit receipt
+ * has to tolerate an older server's spelling before it can be parsed. Each of
+ * those says where its check lives, so `handler` is a citation and never an
+ * excuse.
+ *
+ * A frame type absent from this registry is rejected. That is deliberate: the
+ * server and this package ship from one repository, so an unrecognised frame
+ * means the two have drifted, and failing loudly beats materialising a change
+ * nobody validated. Application-level collaboration events are the exception —
+ * they are registered by the consumer at construction time, not by the
+ * protocol, and are dispatched separately.
+ */
+
+import { z } from 'zod';
+import { commitReceiptSchema } from './commit.js';
+import { clientSyncDeltaSchema } from './delta.js';
+import {
+  claimAcquiredSchema,
+  claimExpiredSchema,
+  claimGrantedSchema,
+  claimHeartbeatAckPayloadSchema,
+  claimLostSchema,
+  claimQueuedSchema,
+  claimQueueSchema,
+  claimRejectionSchema,
+  presenceUpdateSchema,
+  subscriptionAckPayloadSchema,
+} from '../coordination/schema.js';
+
+/**
+ * The envelope itself: a type and a payload. `catchall` keeps the extra keys,
+ * because the oldest delta form puts a delta's own fields at the top level
+ * instead of under `payload`, and the dispatcher still has to recognise it.
+ */
+export const wsInboundEnvelopeSchema = z
+  .object({
+    type: z.string().optional(),
+    payload: z.unknown().optional(),
+  })
+  .catchall(z.unknown());
+export type WsInboundEnvelope = z.infer<typeof wsInboundEnvelopeSchema>;
+
+/** How one frame's payload is checked. */
+export type InboundFrameContract =
+  /** Parsed against `payload` before the handler runs. */
+  | { readonly validation: 'schema'; readonly payload: z.ZodType }
+  /**
+   * Checked inside the handler. `where` says which handler, and `checkedBy`
+   * names the schema it parses with — as the schema itself, not its name in
+   * prose, so renaming or deleting it fails the build here instead of leaving
+   * a citation pointing at nothing. Frames whose check is a hand-narrowing or
+   * lives in another package have no symbol to point at and carry only `where`.
+   */
+  | {
+      readonly validation: 'handler';
+      readonly where: string;
+      readonly checkedBy?: z.ZodType;
+    };
+
+/**
+ * The protocol's inbound surface. Adding a frame to the server means adding it
+ * here, which is the point — the compiler cannot enforce that, but the throw on
+ * an unrecognised type does.
+ */
+export const WS_INBOUND_FRAMES = {
+  // ── Keepalive ──────────────────────────────────────────────────────────
+  ping: { validation: 'handler', where: 'dispatchWsFrame — ignored, no payload' },
+  pong: { validation: 'handler', where: 'dispatchWsFrame — ignored, no payload' },
+
+  // ── Materialisation ────────────────────────────────────────────────────
+  delta: {
+    validation: 'handler',
+    // Not parsed at dispatch because a delta frame carries a batch: each entry
+    // is validated on its own so one malformed delta is dropped rather than
+    // sinking the batch around it.
+    where: 'the materialiser parses each delta as it applies it',
+    checkedBy: clientSyncDeltaSchema,
+  },
+  sync_response: {
+    validation: 'handler',
+    // No `checkedBy`: the schema lives in the reactive engine
+    // (`sync/schemas.ts`), which consumes this package. The core cannot name a
+    // symbol from its own consumer, and inverting the dependency to make this
+    // citation checkable would put materialisation vocabulary in the core —
+    // the exact thing the seam exists to keep out.
+    where: 'the reactive engine validates it while advancing its resume cursor',
+  },
+  bootstrap_response: {
+    validation: 'handler',
+    // No `checkedBy`, for the same reason as `sync_response` above.
+    where: 'the reactive engine validates the bootstrap payload as it applies it',
+  },
+
+  // ── Commit ─────────────────────────────────────────────────────────────
+  mutation_result: {
+    validation: 'handler',
+    where: 'handleMutationResult — it lifts the frame\'s notifications and missingIds alongside the payload before this can parse',
+    checkedBy: commitReceiptSchema,
+  },
+
+  // ── Requests we made ───────────────────────────────────────────────────
+  claim_ack: {
+    validation: 'handler',
+    where: 'handleClaimAck narrows field by field, because a rejection carries a typed capability error it has to re-raise as CapabilityError',
+  },
+  subscription_ack: {
+    validation: 'handler',
+    // Not parsed at dispatch because the handler must first claim the oldest
+    // pending request: a payload that failed here would otherwise leave that
+    // request hanging until its timeout instead of being rejected with a cause.
+    where: 'handleSubscriptionAck',
+    checkedBy: subscriptionAckPayloadSchema,
+  },
+
+  // ── Coordination ───────────────────────────────────────────────────────
+  presence_update: { validation: 'schema', payload: presenceUpdateSchema },
+  claim_expired: { validation: 'schema', payload: claimExpiredSchema },
+  claim_rejected: { validation: 'schema', payload: claimRejectionSchema },
+  claim_acquired: { validation: 'schema', payload: claimAcquiredSchema },
+  claim_queued: { validation: 'schema', payload: claimQueuedSchema },
+  claim_granted: { validation: 'schema', payload: claimGrantedSchema },
+  claim_lost: { validation: 'schema', payload: claimLostSchema },
+  claim_queue: { validation: 'schema', payload: claimQueueSchema },
+  claim_heartbeat_ack: {
+    validation: 'schema',
+    payload: claimHeartbeatAckPayloadSchema,
+  },
+} as const satisfies Record<string, InboundFrameContract>;
+
+/** Every frame type the protocol declares. */
+export type InboundFrameType = keyof typeof WS_INBOUND_FRAMES;
+
+/**
+ * The validated payload type of each schema-checked frame, read straight off
+ * the registry. A handler that takes one of these gets the shape the
+ * dispatcher proved, with no second declaration to keep in step and no cast at
+ * the point of use.
+ */
+export type InboundFramePayload = {
+  [K in InboundFrameType]: (typeof WS_INBOUND_FRAMES)[K] extends {
+    readonly payload: infer P extends z.ZodType;
+  }
+    ? z.infer<P>
+    : never;
+};
+
+/** The frame types the dispatcher parses before calling a handler. */
+export type SchemaValidatedFrameType = {
+  [K in InboundFrameType]: (typeof WS_INBOUND_FRAMES)[K] extends {
+    readonly validation: 'schema';
+  }
+    ? K
+    : never;
+}[InboundFrameType];
+
+/** Whether the protocol declares this frame type at all. */
+export function isKnownInboundFrame(type: string): type is InboundFrameType {
+  return Object.prototype.hasOwnProperty.call(WS_INBOUND_FRAMES, type);
+}
+
+/**
+ * Whether this frame's payload is parsed before dispatch. Declared as a
+ * predicate, and declared here, because the fact it asserts is a fact about the
+ * registry directly above it: the two cannot be edited apart.
+ */
+export function isSchemaValidatedFrame(
+  type: InboundFrameType,
+): type is SchemaValidatedFrameType {
+  return WS_INBOUND_FRAMES[type].validation === 'schema';
+}