@abloatai/transaction 0.37.0

package/src/auth/sessionMint.ts

@@ -0,0 +1,126 @@
+/**
+ * Mints a session token. This is the single implementation behind
+ * `sessions.create`, shared by the WebSocket and HTTP clients so the two never
+ * disagree on how a token is produced.
+ *
+ * Minting is a plain control-plane HTTP call — no socket, no synced data. A
+ * backend holding a secret key (`sk_`) exchanges it for a short-lived, scoped
+ * token whose kind depends on the session requested:
+ *
+ *   `{ user }`  → POST /v1/ephemeral_keys, returning an `ek_` key carrying the
+ *                 explicit grant in `can`. This is the only route that mints a
+ *                 user session; the capability route rejects a `user`
+ *                 participant with `invalid_participant_kind`.
+ *   `{ agent }` → POST /v1/capabilities, returning an `rk_` key scoped to exactly
+ *                 the operations named in `can`. For example
+ *                 `can: { tasks: ['update'] }` becomes the wire allowlist entry
+ *                 `tasks.update`, which the server matches against the model's
+ *                 registered names.
+ *
+ * The caller supplies the already-resolved secret key and base URL in
+ * {@link MintSessionContext}. Choosing which key to pass — the original secret
+ * key, not a derived key that an earlier exchange may have produced — is the
+ * caller's responsibility.
+ */
+import {
+  exchangeApiKey,
+  mintUserSessionKey,
+} from '../auth/index.js';
+import {
+  capabilityCanSchemaFor,
+  grantedOperations,
+} from './capability.js';
+import type { SchemaRecord } from '../schema/schema.js';
+import type { AbloSession, CreateSessionParams } from '../resources/httpResources.js';
+
+/**
+ * The resolved control-plane details a mint needs: a secret key, a base URL,
+ * and an optional `fetch`. When `fetch` is omitted, the auth helpers fall back
+ * to the runtime's global `fetch`.
+ */
+export interface MintSessionContext {
+  readonly apiKey: string;
+  readonly baseUrl: string;
+  readonly fetch?: typeof fetch;
+  /**
+   * Each schema key mapped to its wire type name, from
+   * {@link modelWireNames} over the client's own schema. Required, and derived
+   * rather than assembled: `can` is keyed by schema key while a capability is
+   * scoped by the type name the server checks, so
+   * `can: { documents: ['update'] }` on a model whose type name is overridden
+   * to `Document` must mint `document.update`. A caller who leaves this out
+   * mints a grant the server denies on the first write.
+   */
+  readonly modelTypenames: Readonly<Record<string, string>>;
+}
+
+/**
+ * Mints a session token from an already-resolved secret key and base URL.
+ * Routes the `{ user }` or `{ agent }` request to the matching mint endpoint
+ * and reshapes the response into an {@link AbloSession}.
+ */
+export async function mintSession<S extends SchemaRecord>(
+  params: CreateSessionParams<S>,
+  ctx: MintSessionContext,
+): Promise<AbloSession> {
+  const { apiKey, baseUrl } = ctx;
+  // Static typing and runtime validation consume the same schema-bound grant
+  // contract. This catches JavaScript callers, decoded JSON, and unsafe casts
+  // before a credential reaches either mint endpoint.
+  const can = capabilityCanSchemaFor(ctx.modelTypenames).parse(params.can);
+
+  if (params.user) {
+    const operations = grantedOperations(can, ctx.modelTypenames);
+    const res = await mintUserSessionKey({
+      apiKey,
+      baseUrl,
+      userId: params.user.id,
+      ...(params.organizationId ? { organizationId: params.organizationId } : {}),
+      ...(params.syncGroups ? { syncGroups: [...params.syncGroups] } : {}),
+      operations,
+      ttlSeconds: params.ttlSeconds ?? 900,
+      ...(ctx.fetch ? { fetch: ctx.fetch } : {}),
+    });
+    return {
+      object: 'session',
+      id: res.id,
+      token: res.token,
+      expiresAt: res.expiresAt,
+      organizationId: res.organizationId,
+      // The ephemeral mint stores scope on the key row; reshape its flat
+      // response into the session resource's scope block.
+      scope: {
+        organizationId: res.organizationId,
+        syncGroups: res.syncGroups,
+        operations: res.operations,
+        participantKind: 'user',
+        participantId: res.participantId,
+      },
+      userMeta: params.userMeta ?? { id: res.participantId },
+    };
+  }
+
+  // One translation from the declared grant to the wire allowlist, shared with
+  // every other door that mints — see `auth/capability.ts`.
+  const operations = grantedOperations(can, ctx.modelTypenames);
+  const res = await exchangeApiKey({
+    apiKey,
+    baseUrl,
+    participantKind: 'agent',
+    participantId: params.agent.id,
+    ...(params.syncGroups ? { syncGroups: [...params.syncGroups] } : {}),
+    operations,
+    ttlSeconds: params.ttlSeconds ?? 900,
+    ...(params.userMeta ? { userMeta: params.userMeta } : {}),
+    ...(ctx.fetch ? { fetch: ctx.fetch } : {}),
+  });
+  return {
+    object: 'session',
+    id: res.capabilityId,
+    token: res.token,
+    expiresAt: res.expiresAt,
+    organizationId: res.organizationId,
+    scope: res.scope,
+    userMeta: res.userMeta,
+  };
+}

package/src/auth/token.ts

@@ -0,0 +1,4 @@
+import { z } from 'zod';
+
+/** Canonical bearer-token field used by every successful auth response. */
+export const authTokenSchema = z.string().trim().min(1);

package/src/batching/index.ts

@@ -0,0 +1,200 @@
+/**
+ * A small, dependency-free primitive that coalesces work into batches.
+ *
+ * It accumulates items enqueued close together — the common case being a
+ * synchronous burst such as `Promise.all([ a(), b(), c() ])` within one
+ * event-loop tick — and dispatches them as a single batch rather than one call
+ * each. It is a pure state machine: it stages items on the microtask queue,
+ * flushes on size, cost, or time triggers, and applies in-flight backpressure,
+ * with no dependency on any data model, storage layer, or network. You supply
+ * the dispatch function through {@link BatchSchedulerHooks}.
+ *
+ * Guarantees:
+ *   - each batch is a single `dispatchBatch(items)` call, applied atomically.
+ *   - if a dispatch fails, every enqueued promise in that batch rejects with
+ *     the same error.
+ *   - items dispatch in enqueue order, optionally reordered by `compare` just
+ *     before a batch is cut; batches run first-in, first-out under a
+ *     `maxInFlight` cap.
+ */
+
+export interface BatchSchedulerOptions<T> {
+  /** Master switch. When false, every `enqueue` dispatches solo immediately. Default true. */
+  readonly enabled?: boolean;
+  /** Coalescing window in ms. `0` (default) → flush on the next microtask (zero added latency). */
+  readonly windowMs?: number;
+  /** Max items per batch before a forced flush. Default 256. */
+  readonly maxBatchSize?: number;
+  /** Max accumulated `costOf` per batch before a forced flush. Default `Infinity` (disabled). */
+  readonly maxBatchCost?: number;
+  /** Per-item cost used by `maxBatchCost` (e.g. serialized bytes). Default `() => 0`. */
+  readonly costOf?: (item: T) => number;
+  /** Max dispatches in flight at once (backpressure). Default 1 → strictly ordered. */
+  readonly maxInFlight?: number;
+}
+
+export interface BatchSchedulerHooks<T, R> {
+  /** The single dispatch for one batch. One call → atomic at this layer. */
+  dispatchBatch(items: T[]): Promise<R>;
+  /**
+   * Optional ordering applied to the staged items just before a batch is cut —
+   * for example, to send parent rows ahead of the rows that reference them. Omit
+   * for first-in, first-out order. This changes only the order of items within
+   * the dispatched array, not which items share a batch.
+   */
+  compare?(a: T, b: T): number;
+}
+
+export interface BatchScheduler<T, R> {
+  /** Stage one item; resolves with its batch's dispatch result, or rejects with the batch error. */
+  enqueue(item: T): Promise<R>;
+  /** Stage an item that must dispatch in a batch of its own — for example, one carrying an explicit idempotency key. */
+  enqueueSolo(item: T): Promise<R>;
+  /** Force-flush the pending batch and resolve once everything in flight has settled. */
+  flush(): Promise<void>;
+  /** Stop scheduling and clear timers. Pending/in-flight promises still settle. */
+  dispose(): void;
+}
+
+interface Deferred<R> {
+  resolve(result: R): void;
+  reject(error: unknown): void;
+}
+
+interface Batch<T, R> {
+  items: T[];
+  deferreds: Deferred<R>[];
+  cost: number;
+}
+
+export function createBatchScheduler<T, R>(
+  hooks: BatchSchedulerHooks<T, R>,
+  options?: BatchSchedulerOptions<T>,
+): BatchScheduler<T, R> {
+  const enabled = options?.enabled ?? true;
+  const windowMs = options?.windowMs ?? 0;
+  const maxBatchSize = options?.maxBatchSize ?? 256;
+  const maxBatchCost = options?.maxBatchCost ?? Infinity;
+  const costOf = options?.costOf ?? (() => 0);
+  const maxInFlight = options?.maxInFlight ?? 1;
+
+  let pending: Batch<T, R> | null = null;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let microtaskScheduled = false;
+  const ready: Batch<T, R>[] = [];
+  let inFlight = 0;
+  let idleWaiters: (() => void)[] = [];
+  let disposed = false;
+
+  function scheduleFlush(): void {
+    if (microtaskScheduled || timer) return;
+    if (windowMs > 0) {
+      timer = setTimeout(() => {
+        timer = null;
+        flushPending();
+      }, windowMs);
+    } else {
+      microtaskScheduled = true;
+      queueMicrotask(() => {
+        microtaskScheduled = false;
+        flushPending();
+      });
+    }
+  }
+
+  function flushPending(): void {
+    if (timer) {
+      clearTimeout(timer);
+      timer = null;
+    }
+    microtaskScheduled = false;
+    if (!pending) return;
+    if (hooks.compare) pending.items.sort(hooks.compare);
+    ready.push(pending);
+    pending = null;
+    pump();
+  }
+
+  function pump(): void {
+    while (inFlight < maxInFlight && ready.length > 0) {
+      const batch = ready.shift();
+      if (!batch) break;
+      inFlight++;
+      let dispatched: Promise<R>;
+      try {
+        dispatched = hooks.dispatchBatch(batch.items);
+      } catch (error) {
+        dispatched = Promise.reject(error);
+      }
+      dispatched
+        .then(
+          (result) => {
+            for (const d of batch.deferreds) d.resolve(result);
+          },
+          (error: unknown) => {
+            for (const d of batch.deferreds) d.reject(error);
+          },
+        )
+        .finally(() => {
+          inFlight--;
+          pump();
+          notifyIdleIfDrained();
+        });
+    }
+  }
+
+  function notifyIdleIfDrained(): void {
+    if (inFlight === 0 && ready.length === 0 && idleWaiters.length > 0) {
+      const waiters = idleWaiters;
+      idleWaiters = [];
+      for (const w of waiters) w();
+    }
+  }
+
+  function enqueueSolo(item: T): Promise<R> {
+    return new Promise<R>((resolve, reject) => {
+      ready.push({ items: [item], deferreds: [{ resolve, reject }], cost: costOf(item) });
+      pump();
+    });
+  }
+
+  function enqueue(item: T): Promise<R> {
+    if (disposed) return Promise.reject(new Error('batch scheduler disposed'));
+    if (!enabled) return enqueueSolo(item);
+    const cost = costOf(item);
+    return new Promise<R>((resolve, reject) => {
+      const deferred: Deferred<R> = { resolve, reject };
+      // Rollover: if appending would blow a cap, flush the current batch first.
+      if (pending && (pending.items.length + 1 > maxBatchSize || pending.cost + cost > maxBatchCost)) {
+        flushPending();
+      }
+      if (!pending) pending = { items: [], deferreds: [], cost: 0 };
+      pending.items.push(item);
+      pending.deferreds.push(deferred);
+      pending.cost += cost;
+      if (pending.items.length >= maxBatchSize || pending.cost >= maxBatchCost) {
+        flushPending();
+      } else {
+        scheduleFlush();
+      }
+    });
+  }
+
+  async function flush(): Promise<void> {
+    flushPending();
+    while (ready.length > 0 || inFlight > 0) {
+      await new Promise<void>((resolve) => idleWaiters.push(resolve));
+    }
+  }
+
+  function dispose(): void {
+    disposed = true;
+    if (timer) {
+      clearTimeout(timer);
+      timer = null;
+    }
+    microtaskScheduled = false;
+  }
+
+  return { enqueue, enqueueSolo, flush, dispose };
+}

package/src/coordination/awaitClaimGrant.ts

@@ -0,0 +1,243 @@
+/**
+ * Waits for a queued claim to reach the head of the line — the client side of
+ * the fair-queue handover. When a claim is contended, the server puts it in a
+ * queue and replies that it is queued (HTTP 202 on `/v1/claims`, or a
+ * `claim_queued` frame over the WebSocket). The grant is delivered later, when
+ * the claim reaches the head, as a `claim_granted` frame. This resolves once
+ * that frame arrives for the given `claimId`, so the caller's `claim` promise
+ * stays pending — event-driven, with no polling — until it is actually the
+ * caller's turn. It rejects if the claim is lost (`claim_lost`: taken away by a
+ * TTL lapse on disconnect, or revoked) or if an optional timeout elapses.
+ *
+ * It needs only a minimal `{ subscribe }` transport, so it can be tested
+ * against a fake; the duplex `WsTransport` satisfies it.
+ */
+
+import {
+  AbloClaimedError,
+  AbloValidationError,
+  CapabilityError,
+  formatClaimedErrorMessage,
+  claimTargetLabel,
+} from '../errors.js';
+import type { ClaimRejection } from './schema.js';
+import { modelTarget } from './locator.js';
+import { noopLogger, type Logger } from '../logger.js';
+
+export interface GrantTransport {
+  subscribe(
+    event:
+      | 'claim_acquired'
+      | 'claim_granted'
+      | 'claim_lost'
+      | 'claim_queued'
+      | 'claim_rejected',
+    handler: (payload: Record<string, unknown>) => void,
+  ): () => void;
+}
+
+export interface ClaimGrantInfo {
+  /**
+   * True when the grant arrived as `claim_granted` — the target was held when
+   * the caller asked, and the caller waited in the FIFO line behind the holder.
+   * False for the immediate `claim_acquired`, where the target was free.
+   *
+   * Callers read this to know the row may have changed while they queued. Claim
+   * visibility is scoped to the entity, so a broad, organization-wide
+   * subscription receives no presence or claim fan-out, and the local
+   * coordination snapshot cannot be trusted to tell whether the caller waited.
+   * The grant frame itself is the authoritative signal.
+   */
+  readonly waited: boolean;
+  /**
+   * The fencing token the server minted for this grant (Option B), read off the
+   * grant frame — the authoritative source, since the token is server-stamped.
+   * `undefined` when the server does not fence (no minter wired).
+   */
+  readonly fenceToken?: number;
+}
+
+/** Read the server-stamped fencing token off a grant frame, if present. */
+function readFenceToken(p: Record<string, unknown>): number | undefined {
+  return typeof p.fenceToken === 'number' ? p.fenceToken : undefined;
+}
+
+export function awaitClaimGrant(
+  transport: GrantTransport,
+  claimId: string,
+  options?: {
+    timeoutMs?: number;
+    /**
+     * Backpressure: reject instead of waiting if, when we join the line, the
+     * server reports `position >= maxQueueDepth` (i.e. that many claims are
+     * already ahead of us). Omit to wait however deep the queue is.
+     */
+    maxQueueDepth?: number;
+    /**
+     * Abort the wait from outside — the same signal that cancels everything
+     * else in the program. Rejects with `claim_wait_aborted`; once the grant
+     * has arrived the signal is ignored, so a held lease is never torn down
+     * by a late abort.
+     */
+    signal?: AbortSignal;
+    /** Where grant transitions are logged. Defaults to silent. */
+    logger?: Logger;
+  },
+): Promise<ClaimGrantInfo> {
+  const logger = options?.logger ?? noopLogger;
+  return new Promise<ClaimGrantInfo>((resolve, reject) => {
+    const unsubs: (() => void)[] = [];
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const settle = (fn: () => void): void => {
+      if (timer) clearTimeout(timer);
+      for (const u of unsubs) u();
+      fn();
+    };
+
+    // The target was free → `claim_acquired` (immediate); it was contended,
+    // we waited in line, and reached the head → `claim_granted`. Either frame
+    // means the lease is now ours; `waited` records which path it was.
+    unsubs.push(
+      transport.subscribe('claim_acquired', (p) => {
+        if (p?.claimId === claimId) {
+          logger.debug(`claim: acquired ${claimId} (target was free)`);
+          const fenceToken = readFenceToken(p);
+          settle(() => {
+            resolve({ waited: false, ...(fenceToken !== undefined ? { fenceToken } : {}) });
+          });
+        }
+      }),
+    );
+    unsubs.push(
+      transport.subscribe('claim_granted', (p) => {
+        if (p?.claimId === claimId) {
+          // Promoted to the head of the line — the creator's "it's the agent's
+          // turn now" moment after waiting behind a holder.
+          logger.info(`claim: granted ${claimId} — your turn (waited in queue)`);
+          const fenceToken = readFenceToken(p);
+          settle(() => {
+            resolve({ waited: true, ...(fenceToken !== undefined ? { fenceToken } : {}) });
+          });
+        }
+      }),
+    );
+    if (options?.maxQueueDepth !== undefined) {
+      const max = options.maxQueueDepth;
+      unsubs.push(
+        transport.subscribe('claim_queued', (p) => {
+          if (p?.claimId !== claimId) return;
+          const position = typeof p.position === 'number' ? p.position : 0;
+          if (position >= max) {
+            settle(() =>
+              { reject(
+                new AbloClaimedError(
+                  `Claim queue for ${claimId} is ${position} deep (max ${max}).`,
+                  { code: 'queue_too_deep' },
+                ),
+              ); },
+            );
+          }
+        }),
+      );
+    }
+    unsubs.push(
+      transport.subscribe('claim_rejected', (p) => {
+        const rejection = p as ClaimRejection;
+        if (rejection.claimId !== claimId) return;
+        const target = rejection.target
+          ? claimTargetLabel({
+              ...modelTarget(rejection.target),
+              field: rejection.target.field,
+            })
+          : claimId;
+        if (rejection.reason === 'capability_denied') {
+          settle(() => {
+            reject(
+              new CapabilityError(
+                'capability_scope_denied',
+                rejection.policyReason ??
+                  `This credential may not claim ${target}.`,
+              ),
+            );
+          });
+          return;
+        }
+        if (rejection.reason === 'invalid_target') {
+          settle(() => {
+            reject(
+              new AbloValidationError(
+                rejection.policyReason ?? `Invalid claim target ${target}.`,
+                { code: 'invalid_body' },
+              ),
+            );
+          });
+          return;
+        }
+        settle(() =>
+          { reject(
+            new AbloClaimedError(
+              formatClaimedErrorMessage({
+                targetLabel: target,
+                heldBy: rejection.heldBy,
+                claim: rejection.heldByClaim,
+                policyReason: rejection.policyReason,
+                fallback: `Claim rejected for ${target}.`,
+              }),
+              {
+                code: rejection.reason === 'conflict'
+                  ? 'claim_conflict'
+                  : 'claim_lease_unavailable',
+                claims: rejection.heldByClaim ? [rejection.heldByClaim] : undefined,
+              },
+            ),
+          ); },
+        );
+      }),
+    );
+    unsubs.push(
+      transport.subscribe('claim_lost', (p) => {
+        if (p?.claimId === claimId) {
+          settle(() =>
+            { reject(
+              new AbloClaimedError(`Claim lost while queued for ${claimId}.`, {
+                code: 'claim_lost',
+              }),
+            ); },
+          );
+        }
+      }),
+    );
+
+    if (options?.signal) {
+      const signal = options.signal;
+      const abort = (): void =>
+        settle(() => {
+          reject(
+            new AbloClaimedError(
+              `The wait for claim ${claimId} was aborted before the grant arrived.`,
+              { code: 'claim_wait_aborted' },
+            ),
+          );
+        });
+      if (signal.aborted) {
+        abort();
+        return;
+      }
+      signal.addEventListener('abort', abort, { once: true });
+      unsubs.push(() => { signal.removeEventListener('abort', abort); });
+    }
+
+    if (options?.timeoutMs && options.timeoutMs > 0) {
+      timer = setTimeout(() => {
+        settle(() =>
+          { reject(
+            new AbloClaimedError(
+              `Timed out waiting for the queue grant on claim ${claimId}.`,
+              { code: 'grant_timeout' },
+            ),
+          ); },
+        );
+      }, options.timeoutMs);
+    }
+  });
+}