@abloatai/transaction 0.37.0

package/src/transactionLayer.ts

@@ -0,0 +1,122 @@
+/**
+ * The transaction layer's seam — the surface the sync engine (and any other
+ * caller) sits on. ADR 0013's thesis as an interface: the layer defines,
+ * orders, settles, and authorizes changes; it holds no materialised state.
+ *
+ * `observe()` is the whole seam in one method. The sync engine is `observe()`
+ * piped into a local store — deltas → local store → IndexedDB → reactive
+ * re-render — plus local optimistic mutations reconciled against `commit()` /
+ * `settled()`. Everything reactive is downstream of that method; the
+ * transaction layer never calls up into it.
+ *
+ * `participant` stays the WHO (user | agent | system), never the name of this.
+ * The taught verbs map onto the seam directly: `create`/`update`/`delete` are
+ * operations inside a `commit()` payload; `claim` is `claim()`; `track` rides
+ * the commit payload's `track` field (a durable premise is a zero-operation
+ * commit). Presence (`join`) is deliberately absent: it is live observation
+ * over a socket, and it joins the seam when its core carrier type exists —
+ * see docs/plans/transaction-core-language.md, Tier 3.
+ *
+ * This is the contract, not a runtime: nothing in this package implements it
+ * yet. The first explicit implementation (a headless client, a test harness)
+ * gains a compile-time conformance pin against this interface.
+ */
+
+import type { CommitMessage } from './wire/frames.js';
+import type { ClientCommitReceipt } from './wire/commit.js';
+import type { Delta, HeldClaim, ClaimTarget, ClaimLeaseOptions } from './types/streams.js';
+import type { ModelData } from './types/modelData.js';
+import type { ModelScope } from './types/index.js';
+
+/**
+ * A commit's durable acceptance — `{ status: 'queued' }` with the correlation
+ * the settlement feed later confirms. The wire layer owns the receipt fields;
+ * the seam adds the client idempotency identity needed for a safe wait/retry.
+ */
+export type CommitReceipt = ClientCommitReceipt & {
+  /** The idempotency identity used to await/retry this commit. */
+  readonly clientTxId: string;
+};
+
+/**
+ * The seam's read grammar for {@link TransactionLayer.list} — filter, order,
+ * and page through settled rows. Mirrors the taught list options
+ * (`where` / `orderBy` / `limit` / `offset` / `state`) without binding the
+ * seam to the client's local-read machinery.
+ */
+export interface ListQuery {
+  /** Equality filter on field values. */
+  where?: ModelData;
+  /** Sort order, field → direction. */
+  orderBy?: Record<string, 'asc' | 'desc'>;
+  limit?: number;
+  offset?: number;
+  /** Lifecycle filter; defaults to `'live'`. */
+  state?: `${ModelScope}`;
+}
+
+export interface ObserveCursorStore {
+  load(key: string): Promise<string | null>;
+  save(key: string, cursor: string): Promise<void>;
+}
+
+export interface ObserveOptions {
+  /** Resume from a cursor previously returned by this feed. */
+  after?: string;
+  /** Restrict delivery to these model names. Credential scope still applies first. */
+  models?: string | readonly string[];
+  /** Stable name used with `cursorStore`; defaults to `default`. */
+  cursorKey?: string;
+  /** Optional durable cursor storage. Saving remains consumer-controlled. */
+  cursorStore?: ObserveCursorStore;
+  /** Delay after an empty page. */
+  pollIntervalMs?: number;
+  /** Stop polling and reject pending work. */
+  signal?: AbortSignal;
+}
+
+export type ObservedDelta = Delta & {
+  /** Resume position immediately after this delta. */
+  readonly cursor: string;
+  /** Persist this delta's cursor through the configured store. */
+  checkpoint(): Promise<void>;
+};
+
+/**
+ * The transaction layer. Reads return settled state, point-in-time — never a
+ * reactive subscription. A write is an intent submitted through `commit()`;
+ * durable acceptance is the receipt (`queued`), and `settled()` resolves when
+ * the sync log has appended it (`confirmed`).
+ */
+export interface TransactionLayer {
+  /** Authentication: mint or renew the short-lived credential (`ek_`). */
+  ready(): Promise<void>;
+
+  /** Read one settled row by id, or `null` when absent. */
+  get(model: string, id: string): Promise<ModelData | null>;
+
+  /** Read settled rows matching a {@link ListQuery}. */
+  list(model: string, query?: ListQuery): Promise<ModelData[]>;
+
+  /**
+   * Submit a batch of operations — with its idempotent `clientTxId`, its
+   * `reads` premise, and any durable `track` registrations — and receive
+   * durable acceptance.
+   */
+  commit(payload: CommitMessage['payload']): Promise<CommitReceipt>;
+
+  /** Resolve when the receipt's operations have appended to the sync log. */
+  settled(receipt: CommitReceipt): Promise<void>;
+
+  /**
+   * Take a FIFO lease with a fence token on a target; release through the
+   * handle (`await using` disposes it).
+   */
+  claim(target: ClaimTarget, options?: ClaimLeaseOptions): Promise<HeldClaim>;
+
+  /**
+   * The authoritative change feed, scoped to one or more sync groups —
+   * omitted, everything the credential can see.
+   */
+  observe(options?: ObserveOptions | string | readonly string[]): AsyncIterable<ObservedDelta>;
+}

package/src/transactions/settlement/commitEnvelope.ts

@@ -0,0 +1,192 @@
+/**
+ * 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 { readDependencySchema, trackDependencySchema } from '../../coordination/schema.js';
+import { wireCommitOperationSchema } from '../../wire/frames.js';
+import { correlationIdSchema } from '../../wire/commit.js';
+import { idempotencyKeySchema } from './idempotencyKey.js';
+import { snapshotJsonValue } from '../../utils/json.js';
+
+export const COMMIT_ENVELOPE_VERSION = 1 as const;
+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' },
+  );
+
+export type CommitEnvelopeMember = z.infer<typeof commitEnvelopeMemberSchema>;
+
+/** One operation stored exactly as the current commit transport sends it. */
+export const durableCommitOperationSchema = wireCommitOperationSchema
+  .pick({
+    type: true,
+    model: true,
+    id: true,
+    input: true,
+    transactionId: true,
+    readAt: true,
+    onStale: true,
+    fenceToken: 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(),
+  });
+
+export type DurableCommitOperation = z.infer<typeof durableCommitOperationSchema>;
+export type DurableCommitOperationInput = z.input<typeof durableCommitOperationSchema>;
+
+const durableCommitOptionsSchema = z.strictObject({
+  reads: z.array(readDependencySchema).nullable().optional(),
+  track: z.array(trackDependencySchema).nullable().optional(),
+});
+
+export const commitOutboxScopeSchema = z.strictObject({
+  organizationId: z.string().min(1),
+  participantId: z.string().min(1),
+  namespace: z.string().min(1),
+});
+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 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 evidence that a connected source accepted this exact request.
+     * Its server and customer idempotency keys are permanent, so an accepted
+     * envelope remains replayable until the WAL echo confirms it.
+     */
+    acceptedAt: z.number().int().nonnegative().optional(),
+    /** Opaque server-derived source-batch identity paired with `acceptedAt`. */
+    correlationId: correlationIdSchema.optional(),
+    /** 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.acceptedAt === undefined) !== (envelope.correlationId === undefined)) {
+      context.addIssue({
+        code: 'custom',
+        path: ['acceptedAt'],
+        message: 'Accepted commit envelopes require both acceptedAt and correlationId',
+      });
+    }
+    if (
+      envelope.acceptedAt !== undefined &&
+      envelope.acceptedAt < envelope.sealedAt
+    ) {
+      context.addIssue({
+        code: 'custom',
+        path: ['acceptedAt'],
+        message: 'Commit envelope cannot be accepted before it is sealed',
+      });
+    }
+    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 type DurableCommitEnvelope = z.infer<typeof durableCommitEnvelopeSchema>;
+
+export function commitEnvelopeRecordId(idempotencyKey: string): string {
+  return `${COMMIT_ENVELOPE_RECORD_PREFIX}${idempotencyKey}`;
+}
+
+/** Constructs validated member metadata when an in-memory batch is formed. */
+export function createCommitEnvelopeMember(
+  value: z.input<typeof commitEnvelopeMemberSchema>,
+): CommitEnvelopeMember {
+  return commitEnvelopeMemberSchema.parse(value);
+}
+
+/**
+ * Freezes the exact JSON request that will be persisted and sent. The shared
+ * snapshot contract makes framework proxies plain and rejects values that
+ * would be lost or corrupted by JSON serialization.
+ */
+export function createDurableCommitEnvelope(
+  value: Omit<
+    z.input<typeof durableCommitEnvelopeSchema>,
+    'id' | 'type' | 'storageVersion' | 'timestamp'
+  >,
+): DurableCommitEnvelope {
+  const candidate = {
+    ...value,
+    id: commitEnvelopeRecordId(value.idempotencyKey),
+    type: 'commit_envelope' as const,
+    storageVersion: COMMIT_ENVELOPE_VERSION,
+    timestamp: value.sealedAt,
+  };
+  return durableCommitEnvelopeSchema.parse(
+    snapshotJsonValue(candidate, '$.commitEnvelope'),
+  );
+}

package/src/transactions/settlement/httpCommitEnvelope.ts

@@ -0,0 +1,250 @@
+/** Crash-durable exact HTTP request used by the stateless agent client. */
+
+import { z } from 'zod';
+import { v5 as uuidv5 } from 'uuid';
+import { snapshotJsonValue, stableStringify } from '../../utils/json.js';
+import { correlationIdSchema } from '../../wire/commit.js';
+import { PROTOCOL_VERSION } from '../../wire/protocolVersion.js';
+import { idempotencyKeySchema } from './idempotencyKey.js';
+
+export const HTTP_COMMIT_ENVELOPE_VERSION = 1 as const;
+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: string): boolean {
+  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;
+  }
+}
+
+/** Snapshot the JSON contract once, then make object-key order canonical. */
+export function canonicalHttpCommitBody(value: unknown): string {
+  return stableStringify(snapshotJsonValue(value, '$.body'));
+}
+
+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,
+    /**
+     * The wire contract used when this exact request was sealed. Entries from
+     * before protocol versioning omitted the field and are v1 by definition.
+     */
+    protocolVersion: z.number().int().positive().default(1),
+    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 evidence that the server accepted this exact request for a
+     * connected source. Such server keys are permanent, so this envelope must
+     * remain replayable past the ordinary hosted 24-hour window until its WAL
+     * echo confirms.
+     */
+    acceptedAt: z.number().int().nonnegative().optional(),
+    /** Opaque server-derived source-batch identity paired with `acceptedAt`. */
+    correlationId: correlationIdSchema.optional(),
+    /** 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',
+      });
+    }
+    if ((envelope.acceptedAt === undefined) !== (envelope.correlationId === undefined)) {
+      context.addIssue({
+        code: 'custom',
+        path: ['acceptedAt'],
+        message: 'Accepted HTTP envelopes require both acceptedAt and correlationId',
+      });
+    }
+    if (
+      envelope.acceptedAt !== undefined &&
+      envelope.acceptedAt < envelope.sealedAt
+    ) {
+      context.addIssue({
+        code: 'custom',
+        path: ['acceptedAt'],
+        message: 'HTTP envelope cannot be accepted before it is sealed',
+      });
+    }
+
+    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: unknown;
+    try {
+      body = JSON.parse(envelope.request.body) as unknown;
+    } 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 as Record<string, unknown>;
+    // `envelope.idempotencyKey` is replayed as the `Idempotency-Key` header.
+    // Older sealed bodies may also carry `idempotencyKey`/`clientTxId`; accept
+    // and replay them byte-for-byte, but current requests do not duplicate the
+    // key in JSON.
+    if (path === '/v1/commits') {
+      if (!Array.isArray(record.operations) || record.operations.length === 0) {
+        context.addIssue({
+          code: 'custom',
+          path: ['request', 'body'],
+          message: 'Commit-route body must carry 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 type DurableHttpCommitEnvelope = z.infer<
+  typeof durableHttpCommitEnvelopeSchema
+>;
+
+/**
+ * The HTTP verbs a durable commit envelope can carry, projected out of the
+ * persisted schema above. Callers that build, seal, or dispatch an envelope
+ * take this rather than restating the verbs: the envelope is a stored contract,
+ * so a verb the schema does not accept must not be constructible.
+ */
+export type DurableHttpCommitMethod = DurableHttpCommitEnvelope['request']['method'];
+
+export function httpCommitEnvelopeRecordId(
+  idempotencyKey: string,
+  scopeNamespace?: string,
+): string {
+  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: {
+  idempotencyKey: string;
+  request: {
+    method: DurableHttpCommitMethod;
+    path: string;
+    body: unknown;
+  };
+  scopeNamespace: string;
+  createdAt?: number;
+  sealedAt?: number;
+  sequence?: number;
+}): DurableHttpCommitEnvelope {
+  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,
+    protocolVersion: PROTOCOL_VERSION,
+    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: Pick<DurableHttpCommitEnvelope, 'sealedAt' | 'acceptedAt'>,
+  now = Date.now(),
+): boolean {
+  // Connected-source mutation-log and customer idempotency keys are
+  // permanent. Once acceptance is durable, age can no longer make replay
+  // ambiguous; only the matching WAL echo may settle the envelope.
+  if (envelope.acceptedAt !== undefined) return false;
+  return now - envelope.sealedAt >= HTTP_COMMIT_REPLAY_WINDOW_MS;
+}

package/src/transactions/settlement/idempotencyKey.ts

@@ -0,0 +1,11 @@
+/**
+ * Identity shared by the durable write records.
+ *
+ * A retry must reuse the same non-empty key so the server can recognize the
+ * same logical write. This is a persistence invariant, not a second commit
+ * protocol.
+ */
+import { z } from 'zod';
+
+export const idempotencyKeySchema = z.string().min(1).max(255).brand<'IdempotencyKey'>();
+export type IdempotencyKey = z.output<typeof idempotencyKeySchema>;

package/src/transactions/settlement/pendingWrite.ts

@@ -0,0 +1,24 @@
+/**
+ * The persisted shape of a write awaiting a definitive outcome.
+ *
+ * Owns one authoritative union over the two durable commit envelopes — the
+ * WebSocket envelope and its HTTP counterpart — so an injected store and the
+ * engine that reads back from it agree on exactly one set of records. The
+ * envelope schemas in this directory remain authoritative for their own fields;
+ * this module only unions them.
+ *
+ * The port that persists these records is a behavior contract, not a persisted
+ * shape, so it lives outside this directory in `src/durableWrites.ts`.
+ */
+
+import { z } from 'zod';
+import { durableCommitEnvelopeSchema } from './commitEnvelope.js';
+import { durableHttpCommitEnvelopeSchema } from './httpCommitEnvelope.js';
+
+/** Every write shape that Ablo may ask an injected store to persist. */
+export const pendingWriteSchema = z.union([
+  durableCommitEnvelopeSchema,
+  durableHttpCommitEnvelopeSchema,
+]);
+
+export type PendingWrite = z.infer<typeof pendingWriteSchema>;