@abloatai/transaction 0.59.2 → 0.61.0

package/src/client/ablo.ts

@@ -1,17 +1,16 @@
 /**
  * `Ablo` — the entry point to the coordination layer.
  *
- * The factory constructs the stateless client: typed model resources, commits,
- * claims, and session minting over request/response HTTP. It holds no socket,
- * no store, and no local copy of anything — the bearer credential is the
- * identity and the server resolves it on every request. This is the client a
- * server-side actor installs: an agent, a worker, a cron job, a route handler.
+ * The factory constructs the headless client: typed model resources, commits,
+ * and claims. API-key clients use request/response HTTP.
+ * Session clients use one reconnecting WebSocket by default; the session is
+ * the scoped identity and outlives any individual socket connection.
  *
  * ```ts
  * import { Ablo } from '@abloatai/ablo';
  * import { schema } from '../schema';
  *
- * const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY, transport: 'http' });
+ * const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
  * await ablo.items.update({ id: itemId, data: { status: 'done' } });
  * ```
  *
@@ -35,12 +34,18 @@ import type * as _Http from './resources/httpResources.js';
 /**
  * Create a coordination-layer client in one call.
  *
- * HTTP is the default. A resident process may select `transport: 'websocket'`
- * without changing the model, commit, or claim vocabulary.
+ * Transport follows identity by default: API keys use HTTP and sessions use a
+ * reconnecting WebSocket without changing the model, commit, or claim API.
  */
 export function Ablo<const S extends SchemaRecord>(
   options: PublicAbloOptions<S> & { readonly transport: 'websocket' },
 ): AbloWebSocketClient<S>;
+export function Ablo<const S extends SchemaRecord>(
+  options: PublicAbloOptions<S> & {
+    readonly session: NonNullable<PublicAbloOptions<S>['session']>;
+    readonly transport?: undefined;
+  },
+): AbloWebSocketClient<S>;
 export function Ablo<const S extends SchemaRecord>(
   options: PublicAbloOptions<S>,
 ): AbloHttpClient<S>;
@@ -51,10 +56,10 @@ export function Ablo<const S extends SchemaRecord>(
 }
 
 // ─────────────────────────────────────────────────────────────────────
-//  Ablo namespace — type access via namespace dots for stateless callers
+//  Ablo namespace — type access via namespace dots for headless callers
 // ─────────────────────────────────────────────────────────────────────
 //
-// The stateless subset of the type namespace the reactive package hangs off
+// The headless subset of the type namespace the reactive package hangs off
 // its own `Ablo` export: every entry a consumer of THIS client would write
 // out (`Ablo.Activity`, `Ablo.Commit.Receipt`, and so on), and nothing that
 // needs a store or a socket behind it. The

package/src/client/resources/httpResources.ts

@@ -1,6 +1,6 @@
 /**
  * Shared resource types for the typed clients and private HTTP transport.
- * the commit and claim shapes, the session-mint params and resource, and the
+ * the commit and claim shapes, and the
  * {@link HttpClaimApi} derivation. This module holds only types and has no runtime
  * imports.
  */
@@ -38,15 +38,9 @@ import type { ModelTarget, ModelClaim } from '../../coordination/schema.js';
 export type { ModelTarget, ModelClaim };
 import type { ResolveClaimMeta } from '../../types/global.js';
 import type { ParticipantKind } from '../../types/participant.js';
-import type { SchemaRecord } from '../../schema/schema.js';
-import type { SyncGroupInput } from '../../schema/roles.js';
 // The capability vocabulary — `auth/capability.ts` owns what a grant is on both
 // axes, and these params are the surface a developer declares it through.
-import type {
-  CapabilityCan,
-  CapabilityOperation,
-  EffectiveAuthority,
-} from '../../auth/capability.js';
+import type { EffectiveAuthority } from '../../auth/capability.js';
 import type {
   Claim,
   ClaimStream,
@@ -496,169 +490,3 @@ export interface HttpTransportModel<
    */
   claim: HttpClaimApi<T, Fields>;
 }
-
-/** A single data operation a scoped **agent** session may perform on a model.
- *  The SDK-facing name for {@link CapabilityOperation}; the vocabulary itself is
- *  declared once, as a schema, in `auth/capability.ts`. */
-export type SessionOperation = CapabilityOperation;
-
-/** Parameters for minting an end-user session. Mints an `ek_` token.
- *  `user.id` is your end user's id from your
- *  own identity provider and becomes the session's `participantId`; Ablo does not
- *  model your users, so it is treated as an opaque string at the trust boundary. */
-export interface CreateUserSessionParams<S extends SchemaRecord> {
-  /** Your end user. `id` becomes the token's `participantId`. */
-  user: { id: string };
-  /** Mint the session into this organization instead of the key's own — for a
-   *  platform that serves many tenants from one backend. Requires the `sk_` key to
-   *  carry the `organization:act-as` scope; omit it for the normal
-   *  single-tenant case. */
-  organizationId?: string;
-  /** Resolve this session's schema from a shared project while its data stays
-   *  scoped to `organizationId`. Cross-organization mints default to the
-   *  platform key's own project, so most platforms can omit this. Specify it
-   *  only to override that default. Requires `organization:act-as`. */
-  schemaProject?: {
-    organizationId: string;
-    projectId: string;
-  };
-  /** Sync groups this session may subscribe to — typed (`'default'` or
-   *  `<namespace>:<id>`; build with `syncGroup(kind, id)` from
-   *  `@abloatai/transaction/schema`). Omit for the server default:
-   *  `[org:<your org>, user:<user.id>]`. */
-  syncGroups?: readonly SyncGroupInput[];
-  /** Required least-privilege grant. */
-  can: CapabilityCan<S>;
-  /** Token lifetime in seconds. Defaults to 900 (15 minutes). */
-  ttlSeconds?: number;
-  /** Opaque identity blob echoed back to the client as `ablo.user`. */
-  userMeta?: Record<string, unknown>;
-  agent?: never;
-}
-
-/** Mint params for a scoped **agent** session — mints a restricted `rk_` token
- *  gated to exactly the operations named in `can`. `can` is typed off your
- *  schema (no magic `'item.update'` strings): `{ Item: ['update'], Report: ['read'] }`
- *  — the SDK serializes each entry to the wire allowlist (`item.update`). */
-export interface CreateAgentSessionParams<S extends SchemaRecord> {
-  /** Your agent. `id` becomes the token's `participantId`. */
-  agent: { id: string };
-  /** The authenticated person who started this agent run. The backend holding
-   *  the secret key attests this identity, and every resulting delta records
-   *  the agent as actor plus this user as `onBehalfOf`. Persist the user id on
-   *  durable work before enqueueing it so a later worker can supply it here. */
-  onBehalfOf?: { readonly user: { readonly id: string } };
-  /** Per-model operation allowlist, typed against the schema's model names. */
-  can: CapabilityCan<S>;
-  /** Sync groups this session may subscribe to — typed (`'default'` or
-   *  `<namespace>:<id>`; build with `syncGroup(kind, id)` from
-   *  `@abloatai/transaction/schema`). Omit for the server default: the org
-   *  anchor (`org:<your org>`) + the agent's own anchor. */
-  syncGroups?: readonly SyncGroupInput[];
-  /** Token lifetime in seconds. Defaults to 900 (15 minutes). */
-  ttlSeconds?: number;
-  /** Opaque identity blob echoed back to the client as `ablo.agent`. */
-  userMeta?: Record<string, unknown>;
-  user?: never;
-}
-
-/** Params for {@link Ablo.sessions}.create — a discriminated union: pass
- *  `{ user, can }` for an end-user session (`ek_`) or `{ agent, can }`
- *  for a scoped agent session (`rk_`). */
-export type CreateSessionParams<S extends SchemaRecord> =
-  | CreateUserSessionParams<S>
-  | CreateAgentSessionParams<S>;
-
-/** Params for {@link Ablo.agents}.create — a flattened agent descriptor (no
- *  `{ agent }` discriminator: `agents.create` only ever mints an agent). Unlike
- *  {@link CreateSessionParams} it resolves to a connected, scoped {@link Ablo}
- *  client rather than a raw token. */
-export interface CreateAgentClientParams<S extends SchemaRecord> {
-  /** The wire participant identity (`agent:<id>`) that claim exclusion and the
-   *  FIFO queue gate on. Omit it to get a fresh random id — a distinct, independent
-   *  participant, which is the default and what you want for concurrent agents.
-   *  Pass a stable string only when one logical agent must re-attach to its own
-   *  held claims across reconnects or restarts. */
-  id?: string;
-  /** The authenticated person who started this run. Preserving it on durable
-   *  work and supplying it here gives every write dual-principal attribution. */
-  onBehalfOf?: { readonly user: { readonly id: string } };
-  /** A human-readable label for logs and attribution (carried in `userMeta.name`).
-   *  It is independent of `id`: two agents that share a `name` still receive
-   *  distinct ids and coordinate as separate participants — `name` never derives or
-   *  collapses identity. */
-  name?: string;
-  /** Per-model operation allowlist, typed against the schema's model names. */
-  can: CapabilityCan<S>;
-  /** Sync groups this agent may subscribe to — typed (`'default'` or
-   *  `<namespace>:<id>`). Omit for the server default (org anchor + the
-   *  agent's own anchor). */
-  syncGroups?: readonly SyncGroupInput[];
-  /** Token lifetime in seconds. Defaults to 900 (15 minutes); the returned client
-   *  re-mints before expiry, so a long-running agent never handles rotation
-   *  itself. */
-  ttlSeconds?: number;
-  /** Extra opaque identity blob echoed on the session scope. Merged with
-   *  `name` (the `name` param wins if you also set `userMeta.name`). */
-  userMeta?: Record<string, unknown>;
-}
-
-/** A minted session. `token` is the secret the holder presents as its bearer. */
-export interface AbloSession {
-  object: 'session';
-  /** Stable id of the minted credential (for revocation). */
-  id: string;
-  /** The short-lived session token — `ek_` for a `{ user }` session, `rk_`
-   *  for an `{ agent }` session. Hand this to the participant's runtime. */
-  token: string;
-  /** ISO-8601 expiry. */
-  expiresAt: string;
-  organizationId: string;
-  /** The grant this token carries, on both axes — the same shape the key row
-   *  stores and the gates enforce. */
-  scope: EffectiveAuthority;
-  userMeta: Record<string, unknown>;
-}
-
-/** Result of revoking a user or agent session. */
-export interface SessionRevocation {
-  id: string;
-  deleted: true;
-  activeSessionsClosed: number;
-}
-
-/** Rotation-with-overlap result for an agent session. */
-export interface SessionRotation {
-  id: string;
-  token: string;
-  expiresAt: string | null;
-  organizationId: string;
-  scope: EffectiveAuthority;
-  rotatedFrom: {
-    id: string;
-    expiresAt: string;
-  };
-}
-
-export interface RevokeSessionParams {
-  id: string;
-}
-
-export interface RotateSessionParams {
-  id: string;
-  /** How long the previous token remains valid. Defaults to 24 hours. */
-  graceSeconds?: number;
-  /** Optional lifetime for the replacement token. */
-  ttlSeconds?: number;
-}
-
-export interface SessionResource<S extends SchemaRecord> {
-  create(params: CreateSessionParams<S>): Promise<AbloSession>;
-  /** Immediately revoke an `ek_` or `rk_` session and close live connections. */
-  revoke(params: RevokeSessionParams): Promise<SessionRevocation>;
-  /**
-   * Rotate an agent `rk_` session with an overlap window. Browser `ek_`
-   * sessions rotate through their `authEndpoint` instead.
-   */
-  rotate(params: RotateSessionParams): Promise<SessionRotation>;
-}

package/src/client/resources/modelOperations.ts

@@ -623,13 +623,3 @@ export interface ModelDeleteParams<T, Fields = T>
   readonly id: string;
   readonly claim?: Claim<T> | ClaimTargetOptions<Fields> | null;
 }
-
-/** Options for the WebSocket-only `ablo.<model>.join(ids, options?)`. */
-export interface JoinOptions {
-  /**
-   * Lease TTL for the underlying presence claim — the participant
-   * auto-releases after this if the holder dies. Compact duration string
-   * (`'5m'`) or ms number, mirroring the claim `ttl`.
-   */
-  ttl?: Duration;
-}

package/src/client/surface.ts

@@ -20,13 +20,11 @@ export type PublicAbloOptions<S extends SchemaRecord = SchemaRecord> = Omit<
 export const PUBLIC_ABLO_OPTION_KEYS = [
   'schema',
   'apiKey',
-  'authEndpoint',
+  'session',
   'authToken',
   'baseURL',
   'dangerouslyAllowBrowser',
   'fetch',
-  'authTimeoutMs',
-  'allowCrossOriginAuthEndpoint',
   'bootstrapBaseUrl',
   'defaultHeaders',
   'defaultQuery',
@@ -36,7 +34,7 @@ export const PUBLIC_ABLO_OPTION_KEYS = [
   'commitOutboxScope',
   'transport',
   'timeoutMs',
-  'syncGroups',
+  'groups',
   'collaborationEvents',
   'cursorStore',
   'cursorKey',

package/src/coordination/index.ts

@@ -41,7 +41,6 @@ export {
   claimQueuedSchema,
   claimQueueSchema,
   claimQueueEntrySchema,
-  claimExpiredSchema,
   claimEventReasonSchema,
   modelTargetSchema,
   // The one claim record, and the peer-visible projection of it.
@@ -50,16 +49,14 @@ export {
   modelClaimSchema,
   claimBeginPayloadSchema,
   claimAbandonPayloadSchema,
+  claimAbandonAckPayloadSchema,
   claimReorderPayloadSchema,
   claimHeartbeatPayloadSchema,
   claimHeartbeatAckPayloadSchema,
   claimHeartbeatBatchPayloadSchema,
   claimHeartbeatBatchAckPayloadSchema,
-  // Read interest — what a connection receives, leased (`claim`/`release`,
-  // the frames behind `join`) and unleased (`update_subscription`).
+  // Read interest — what a connection receives.
   MAX_FRAME_SYNC_GROUPS,
-  participantClaimPayloadSchema,
-  participantReleasePayloadSchema,
   updateSubscriptionPayloadSchema,
   subscriptionAckPayloadSchema,
   // Commit operation — carries the optimistic write-guard
@@ -96,7 +93,6 @@ export type {
   ClaimQueued,
   ClaimQueue,
   ClaimQueueEntry,
-  ClaimExpired,
   ClaimEventReason,
   ModelTarget,
   ClaimRecord,
@@ -104,14 +100,13 @@ export type {
   ModelClaim,
   ClaimBeginPayload,
   ClaimAbandonPayload,
+  ClaimAbandonAckPayload,
   ClaimReorderPayload,
   ClaimHeartbeatPayload,
   ClaimHeartbeatAckPayload,
   ClaimHeartbeatBatchPayload,
   ClaimHeartbeatBatchAckPayload,
-  // Read interest — leased and unleased
-  ParticipantClaimPayload,
-  ParticipantReleasePayload,
+  // Read interest
   UpdateSubscriptionPayload,
   SubscriptionAckPayload,
   // Commit operation — carries the optimistic write-guard

package/src/coordination/schema.ts

@@ -467,8 +467,8 @@ export type ClaimError = z.infer<typeof claimErrorSchema>;
  * frozen, and an older server may send a word not listed here. This is the
  * reader's side of it: a value that parses becomes the typed reason, and one
  * that does not is simply absent rather than smuggled through as prose.
- * {@link claimExpiredSchema} and {@link claimLostSchema} already spelled their
- * reasons as enums; this brings the refusals into line.
+ * {@link claimLostSchema} already spells its reasons as an enum; this brings
+ * the refusals into line.
  */
 export const claimEventReasonSchema = z.enum([
   'conflict',
@@ -644,17 +644,6 @@ export const claimQueueSchema = z.object({
 });
 export type ClaimQueue = z.infer<typeof claimQueueSchema>;
 
-/**
- * A held claim's TTL lapsed server-side. The claim is already inactive by the
- * time this arrives, so a consumer either re-claims with a fresh credential or
- * accepts the drop; there is nothing to release.
- */
-export const claimExpiredSchema = z.object({
-  claimId: z.string(),
-});
-export type ClaimExpired = z.infer<typeof claimExpiredSchema>;
-
-
 /**
  * The two states a claim can be observed in while it still exists.
  *
@@ -855,9 +844,20 @@ export const claimAbandonPayloadSchema = z.object({
   claimId: z.string(),
   entityType: z.string().optional(),
   entityId: z.string().optional(),
+  /** Correlates the server acknowledgement requested by current clients. */
+  requestId: z.string().optional(),
 });
 export type ClaimAbandonPayload = z.infer<typeof claimAbandonPayloadSchema>;
 
+/** Server confirmation that a held or queued claim is no longer retained. */
+export const claimAbandonAckPayloadSchema = z.object({
+  claimId: z.string(),
+  requestId: z.string(),
+});
+export type ClaimAbandonAckPayload = z.infer<
+  typeof claimAbandonAckPayloadSchema
+>;
+
 /**
  * The `claim_reorder` payload a client sends. A privileged participant, such as
  * a supervisor over its sub-agents, re-ranks the FIFO wait queue for an entity:
@@ -981,20 +981,9 @@ export type ClaimHeartbeatBatchAckPayload = z.infer<
 // ─────────────────────────────────────────────────────────────────────────
 //  Read interest — what a connection receives
 //
-//  Two frames set it, and they differ in exactly one way: whether the
-//  interest is leased.
-//
-//    • `claim`  — a PARTICIPANT claim. Adds a scope under a handle, with a
-//      TTL and an optional capability token, and announces the sender into
-//      that scope's roster. This is the frame `ablo.<model>.join(...)` sends;
-//      `release` drops it. Several may be open on one connection at once.
-//    • `update_subscription` — REPLACES the connection's whole read set. No
-//      handle, no lease, no roster entry.
-//
-//  Both are bounded by the connection credential's grant, and both name their
-//  groups the same way, so both parse their `syncGroups` through the same
-//  element schema. Neither is the row lease — that is `claim_begin`, in the
-//  pessimistic-claims block above, which shares only a word.
+//  `update_subscription` replaces the connection's whole read set. It is
+//  bounded by the connection credential's grant and is not a row lease;
+//  row leases use `claim_begin` in the pessimistic-claims block above.
 // ─────────────────────────────────────────────────────────────────────────
 
 /**
@@ -1012,67 +1001,15 @@ export const MAX_FRAME_SYNC_GROUPS = 200;
  * that does not parse matches nothing, and subscribing to nothing quietly is
  * the failure this element type exists to prevent.
  *
- * Strict because this is untrusted client input, and shared because the two
- * frames below carry the same value: when they disagreed, `claim` accepted a
- * malformed group that `update_subscription` refused, and the connection
- * ended up leased to a scope it could never receive.
+ * Strict because this is untrusted client input.
  */
 const frameSyncGroupsSchema = z
   .array(syncGroupInputSchema)
   .max(MAX_FRAME_SYNC_GROUPS);
 
-/**
- * The `claim` payload a client sends — the frame behind `join`.
- *
- * It opens one participant claim: the connection is added to each named
- * scope's fan-out under `claimId`, announced into its presence roster, and
- * holds that interest until `release`, the TTL lapses, or the socket closes.
- * The handle is client-chosen because the client must be able to `release`
- * the exact claim it opened while others stay open.
- *
- * This shape was, for a long time, written three times — built as a literal in
- * the transport, restated as an interface on the server, and read back through
- * a cast in the frame handler — which is how the frame came to be the only
- * coordination message with no runtime check on the way in.
- */
-export const participantClaimPayloadSchema = z.object({
-  /** Client-chosen handle. Echoed on `claim_ack`; names the claim to `release`. */
-  claimId: z.string().min(1),
-  syncGroups: frameSyncGroupsSchema,
-  /**
-   * A narrower capability to present for this claim than the connection's own.
-   * Absent means the connection's credential governs it.
-   */
-  capabilityToken: z.string().optional(),
-  /**
-   * Crash cleanup, in seconds. The server caps it at the capability's own TTL;
-   * absent means the claim lives until `release` or disconnect.
-   */
-  ttlSeconds: z.number().optional(),
-});
-export type ParticipantClaimPayload = z.infer<
-  typeof participantClaimPayloadSchema
->;
-
-/**
- * The `release` payload — drop one participant claim by its handle.
- *
- * A projection of the claim it releases rather than a second object, so the
- * handle cannot be spelled one way when opened and another when dropped.
- * Idempotent by contract: the server accepts an unknown handle silently, so a
- * client releasing everything at shutdown never has to check what is still open.
- */
-export const participantReleasePayloadSchema =
-  participantClaimPayloadSchema.pick({ claimId: true });
-export type ParticipantReleasePayload = z.infer<
-  typeof participantReleasePayloadSchema
->;
-
 /**
  * The `update_subscription` payload a client sends. It replaces the
- * connection's read interest with the complete set of sync groups — the
- * unleased counterpart to {@link participantClaimPayloadSchema}, with no
- * handle, no TTL, and no roster entry.
+ * connection's read interest with the complete set of sync groups.
  */
 export const updateSubscriptionPayloadSchema = z.object({
   syncGroups: frameSyncGroupsSchema,

package/src/errorCodes.ts

@@ -178,6 +178,23 @@ const wire = (
   observability: observabilityPolicy(category, httpStatus, operational),
 });
 
+/** Expected customer-controlled 5xx state: visible as a log, never an issue/page. */
+const expectedOperationalWire = (
+  category: ErrorCategory,
+  httpStatus: number,
+  retryable: boolean,
+  message: string,
+): ErrorCodeSpec => ({
+  ...wire(category, httpStatus, retryable, message),
+  observability: {
+    severity: 'warning',
+    sentry: 'log',
+    pagingEligible: false,
+    expectedVolume: 'normal',
+    owner: 'product',
+  },
+});
+
 const client = (
   category: ErrorCategory,
   message: string,
@@ -511,17 +528,13 @@ export const ERROR_CODES = {
   // A claim payload that cannot be parsed is a malformed request, not
   // contention — it is filed with `malformed_subscription` below rather than
   // with the 409s above, so the claim category stays purely about a target
-  // being held. This is the code for a claim that fails to name its target,
-  // over either transport — and for the participant claim behind `join`, which
-  // names scopes rather than a row but fails the same way and to the same
-  // caller. The copy covers both because the caller sees one word, `claim`, and
-  // needs to be told which shape was expected without being handed a lecture on
-  // the two frames.
+  // being held. This is the code for a row claim that fails to name its target,
+  // over either transport.
   malformed_claim: wire(
     'validation',
     400,
     false,
-    'The claim payload could not be parsed. A claim on a row must name the model and the entity it targets; a claim on a scope, which is what `join` opens, must name sync groups spelled `kind:id` or `default`. Check the payload shape and resend.'
+    'The claim payload could not be parsed. A row claim must name the model and entity it targets. Check the payload shape and resend.'
   ),
   malformed_subscription: wire(
     'validation',
@@ -558,11 +571,6 @@ export const ERROR_CODES = {
     'claim',
     'Claiming is unavailable on this model client. Construct it through the standard Ablo({ schema, apiKey }) client and retry.'
   ),
-  model_join_not_configured: client(
-    'claim',
-    'join() opens a presence/claim subscription and needs a live WebSocket, so it is unavailable on the HTTP transport and on model proxies built without a socket. Use the standard Ablo({ schema, apiKey }) client (default WebSocket transport).'
-  ),
-
   // ── stale context / idempotency (409) ──────────────────────────────
   // Not retryable at the transport: the rejected request carries its frozen
   // `readAt`, so resending the identical payload can never succeed. Recovery
@@ -1142,7 +1150,7 @@ export const ERROR_CODES = {
     false,
     'The Data Source key is not allowed to perform this operation.'
   ),
-  source_connector_not_attached: wire(
+  source_connector_not_attached: expectedOperationalWire(
     'transport',
     503,
     true,