@abloatai/transaction 0.57.0 → 0.58.0

package/src/{coordination/awaitClaimGrant.ts → claims/awaitGrant.ts}

@@ -21,7 +21,7 @@ import {
   formatClaimedErrorMessage,
   claimTargetLabel,
 } from '../errors.js';
-import type { ClaimRejection } from './schema.js';
+import type { ClaimRejection } from '../coordination/schema.js';
 import { modelTarget } from './locator.js';
 import { noopLogger, type Logger } from '../logger.js';
 
@@ -189,7 +189,7 @@ export function awaitClaimGrant(
           settle(() => {
             const error = new CapabilityError(
               'capability_scope_denied',
-              rejection.policyReason ??
+              rejection.message ??
                 `This credential may not claim ${target}.`,
             );
             observe(() => options?.onFailed?.(error));
@@ -200,7 +200,7 @@ export function awaitClaimGrant(
         if (rejection.reason === 'invalid_target') {
           settle(() => {
             const error = new AbloValidationError(
-              rejection.policyReason ?? `Invalid claim target ${target}.`,
+              rejection.message ?? `Invalid claim target ${target}.`,
               { code: 'invalid_body' },
             );
             observe(() => options?.onFailed?.(error));
@@ -214,7 +214,7 @@ export function awaitClaimGrant(
               targetLabel: target,
               heldBy: rejection.heldBy,
               claim: rejection.heldByClaim,
-              policyReason: rejection.policyReason,
+              detail: rejection.message,
               fallback: `Claim rejected for ${target}.`,
             }),
             {

package/src/{wire/claims.ts → claims/contract.ts}

@@ -12,7 +12,7 @@
 
 import { z } from 'zod';
 import { durationSchema, parseDurationMs } from '../utils/duration.js';
-import { listEnvelopeSchema } from './listEnvelope.js';
+import { listEnvelopeSchema } from '../wire/listEnvelope.js';
 import {
   publicClaimStatusSchema,
   wireParticipantKindSchema,

package/src/{coordination → claims}/events.ts

@@ -1,14 +1,14 @@
 /**
  * In-process observation events emitted by the transaction layer's
- * coordination protocol. The wire claim and stale-write contracts live in
- * `coordination/schema.ts`; these two projections are the stable event shapes
+ * coordination protocol. The wire contracts live in `coordination/schema.ts`;
+ * these projections are the stable event shapes
  * an observer receives after those frames have been interpreted.
  */
 
 import type { ParticipantKind } from '../types/participant.js';
 
-export type { ClaimEventReason } from './schema.js';
-import type { ClaimEventReason } from './schema.js';
+export type { ClaimEventReason } from '../coordination/schema.js';
+import type { ClaimEventReason } from '../coordination/schema.js';
 
 /** The participant that blocked a claim — present on `rejected`. */
 export interface ClaimCounterparty {
@@ -55,12 +55,8 @@ export interface ClaimEvent {
   description?: string;
   /** Why the claim ended or was refused. Absent while it is simply alive. */
   reason?: ClaimEventReason;
-  /**
-   * A policy's own words when a policy decided the outcome — free text by
-   * nature, and kept beside the closed {@link ClaimEvent.reason} rather than
-   * collapsed into it.
-   */
-  policyReason?: string;
+  /** Human-readable detail accompanying the machine-readable reason. */
+  message?: string;
   /**
    * Who blocked this claim. Present on `rejected`, where the wire already
    * carried the holder and this projection used to discard it.
@@ -68,7 +64,7 @@ export interface ClaimEvent {
   heldBy?: ClaimCounterparty;
 }
 
-/** A committed notify-instead-of-abort stale-write collision. */
+/** A rejected stale-write or foreign-claim collision. */
 export interface ConflictEvent {
   clientTxId: string;
   rows: readonly {

package/src/claims/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Claim subsystem.
+ *
+ * Start here and descend through contracts, target location, admission,
+ * heartbeat, metadata, events, and diagnostics.
+ */
+export * from './contract.js';
+export * from './routes.js';
+export * from './eventContract.js';
+export * from './locator.js';
+export * from './awaitGrant.js';
+export * from './heartbeat.js';
+export * from './meta.js';
+export type {
+  ClaimCounterparty,
+  ClaimEvent as ClaimObservationEvent,
+  ConflictEvent,
+  CoordinationObserver,
+} from './events.js';
+export * from './targetConflict.js';
+export * from './trace.js';

package/src/claims/lifetime.ts

@@ -0,0 +1,78 @@
+/**
+ * Package-internal lifecycle for one granted claim handle.
+ *
+ * A handle is bound to one server grant. Wrappers may add row data or model
+ * typing, but they all share this object so a loss observed at the transport
+ * boundary removes the same handle from every client-side index. The public
+ * cancellation surface is deliberately not defined here yet; this file first
+ * establishes one truthful terminal transition for the existing API.
+ */
+
+export interface ClaimLifetime {
+  /** Whether this exact grant has ended. */
+  readonly ended: boolean;
+  /** Why it ended, when the transport supplied a typed error. */
+  readonly reason: Error | undefined;
+  /** End the grant once. Later calls are no-ops. */
+  end(reason?: Error): void;
+  /** Run when the grant ends. An already-ended grant invokes immediately. */
+  onEnd(listener: (reason: Error | undefined) => void): () => void;
+}
+
+const lifetimeByHandle = new WeakMap<object, ClaimLifetime>();
+
+/** Create the single lifecycle shared by every wrapper around one grant. */
+export function createClaimLifetime(): ClaimLifetime {
+  let ended = false;
+  let reason: Error | undefined;
+  const listeners = new Set<(reason: Error | undefined) => void>();
+
+  return {
+    get ended() {
+      return ended;
+    },
+    get reason() {
+      return reason;
+    },
+    end(nextReason?: Error) {
+      if (ended) return;
+      ended = true;
+      reason = nextReason;
+      for (const listener of listeners) {
+        try {
+          listener(reason);
+        } catch {
+          // A cleanup observer cannot keep sibling cleanup from running.
+        }
+      }
+      listeners.clear();
+    },
+    onEnd(listener) {
+      if (ended) {
+        listener(reason);
+        return () => undefined;
+      }
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+  };
+}
+
+/** Associate a wrapper with the lifecycle of the grant it represents. */
+export function bindClaimLifetime<T extends object>(
+  handle: T,
+  lifetime: ClaimLifetime,
+): T {
+  lifetimeByHandle.set(handle, lifetime);
+  return handle;
+}
+
+/** Read a handle's package-internal lifecycle, if it was minted by this SDK. */
+export function claimLifetimeOf(handle: unknown): ClaimLifetime | undefined {
+  if ((typeof handle !== 'object' && typeof handle !== 'function') || handle === null) {
+    return undefined;
+  }
+  return lifetimeByHandle.get(handle);
+}

package/src/{coordination → claims}/locator.ts

@@ -16,18 +16,18 @@
  * the locator again should touch this module and the schema, not every hop.
  */
 
-import type { ClaimPart, ModelTarget, TargetRef, WireClaim } from './schema.js';
+import type { ClaimPart, ModelTarget, TargetRef, WireClaim } from '../coordination/schema.js';
 import {
   fieldSelection,
   type FieldRef,
   type FieldSelector,
 } from '../schema/fieldRef.js';
-import { partName } from './schema.js';
+import { partName } from '../coordination/schema.js';
 import type { ClaimTarget, PresenceTarget } from '../types/streams.js';
 import type { ResolveClaimMeta } from '../types/global.js';
 // The one declared→wire conversion for claim metadata; `declaredMeta` is its
 // counterpart, called by the decodes that build a public claim.
-import { wireMeta } from './claimMeta.js';
+import { wireMeta } from './meta.js';
 
 /**
  * The part of a claim that narrows it below the whole entity. A claim with none

package/src/claims/routes.ts

@@ -0,0 +1,81 @@
+/**
+ * Where the claim routes live, named once.
+ *
+ * A path is a contract between two programs, and it was being stated twice: the
+ * server registered `/v1/models/:model/:id/claim` and every client wrote the
+ * same string out again with its parameters interpolated. Nothing held the two
+ * spellings together, so a rename would have compiled on both sides and failed
+ * at the first request — the one class of drift that survives a green build.
+ *
+ * The two ends need the path differently. A router wants the `:param` pattern;
+ * a caller wants the filled URL. Both come from the same literal here: the
+ * pattern is the definition, and every builder below is a substitution into it,
+ * so a path can be corrected in exactly one place.
+ *
+ * Percent-encoding belongs here too. A model or row id is caller-supplied, and
+ * an id containing `/` silently addressed a different route when each call site
+ * remembered to encode on its own.
+ */
+
+/**
+ * Claim route patterns, in the `:param` spelling a router registers.
+ *
+ * `as const` is load-bearing: it keeps each value a literal type, which is what
+ * lets a typed router infer a route's parameter names from the pattern it is
+ * handed. Widening these to `string` would compile and quietly cost the server
+ * its `c.req.param()` typing.
+ */
+export const CLAIM_ROUTES = {
+  /** List claims, and take one. */
+  collection: '/v1/claims',
+  /** Beat every lease this caller holds, in one call. */
+  collectionHeartbeat: '/v1/claims/heartbeat',
+  /** Poll one claim, or release it. */
+  byId: '/v1/claims/:claimId',
+  /** Beat one named lease. */
+  byIdHeartbeat: '/v1/claims/:claimId/heartbeat',
+  /** The model-scoped surface, mirroring `ablo.<model>.claim({ id })`. */
+  onModel: '/v1/models/:model/:id/claim',
+  onModelHeartbeat: '/v1/models/:model/:id/claim/heartbeat',
+  onModelReorder: '/v1/models/:model/:id/claim/reorder',
+  /** The pre-`/v1` spelling, still mounted for clients that predate it. */
+  legacyCollection: '/sync/claims',
+  legacyById: '/sync/claims/:claimId',
+} as const;
+
+/** The row a model-scoped claim route addresses. */
+export interface ClaimRouteTarget {
+  readonly model: string;
+  readonly id: string;
+}
+
+function forTarget(pattern: string, target: ClaimRouteTarget): string {
+  return pattern
+    .replace(':model', encodeURIComponent(target.model))
+    .replace(':id', encodeURIComponent(target.id));
+}
+
+/** `POST` to take the lease on a row, `DELETE` to give it back. */
+export function claimOnModelPath(target: ClaimRouteTarget): string {
+  return forTarget(CLAIM_ROUTES.onModel, target);
+}
+
+/** `POST` to say the holder is still working. */
+export function claimHeartbeatOnModelPath(target: ClaimRouteTarget): string {
+  return forTarget(CLAIM_ROUTES.onModelHeartbeat, target);
+}
+
+/** `POST` to move a waiter within the line. */
+export function claimReorderOnModelPath(target: ClaimRouteTarget): string {
+  return forTarget(CLAIM_ROUTES.onModelReorder, target);
+}
+
+/** `GET` to poll one claim's state, `DELETE` to release it by its own id. */
+export function claimByIdPath(claimId: string): string {
+  return CLAIM_ROUTES.byId.replace(':claimId', encodeURIComponent(claimId));
+}
+
+/** `POST` to beat one named lease. */
+export function claimHeartbeatByIdPath(claimId: string): string {
+  return CLAIM_ROUTES.byIdHeartbeat.replace(':claimId', encodeURIComponent(claimId));
+}

package/src/{coordination → claims}/trace.ts

@@ -1,7 +1,7 @@
 /**
  * A claim log — the simplest way to watch agents collide. The engine reports
  * the claim lifecycle (`acquired → queued → granted → lost / rejected /
- * expired`) and the notify-instead-of-abort stale write through two channels:
+ * expired`) and rejected write collisions through two channels:
  * human-readable `logger` lines (shown with `new Ablo({ debug: true })`) and
  * structured `observability.captureClaim` / `captureConflict` calls.
  *
@@ -36,19 +36,19 @@ export function formatClaim(e: ClaimEvent): string {
       ? ` — held by ${actor}`
       : ` — by ${actor}`
     : '';
-  // The cause when there is one, in the policy's own words when a policy
-  // decided; otherwise what the holder said they were doing. A line never
+  // The cause when there is one, with human-readable detail when supplied;
+  // otherwise what the holder said they were doing. A line never
   // shows both, because a claim that ended has a cause and a claim that is
   // simply alive has only its description.
   const why = e.reason
-    ? `: ${e.policyReason ?? e.reason}`
+    ? `: ${e.message ?? e.reason}`
     : e.description
       ? `: ${e.description}`
       : '';
   return `claim ${e.phase}: ${target}${scope}${pos}${by}${why}`;
 }
 
-/** A notify-instead-of-abort stale write as one readable line. */
+/** A rejected stale write or foreign-claim collision as one readable line. */
 export function formatConflict(e: ConflictEvent): string {
   const rows = e.rows
     .map((r) => {

package/src/{ablo.ts → client/ablo.ts}

@@ -9,7 +9,7 @@
  *
  * ```ts
  * import { Ablo } from '@abloatai/ablo';
- * import { schema } from './schema';
+ * import { schema } from '../schema';
  *
  * const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY, transport: 'http' });
  * await ablo.items.update({ id: itemId, data: { status: 'done' } });
@@ -24,12 +24,11 @@ import {
   createAbloHttpClient,
   type AbloHttpClient,
   type AbloHttpClientOptions,
-} from './transport/httpClient.js';
-import type { SchemaRecord } from './schema/schema.js';
-import type * as _Streams from './types/streams.js';
-import type * as _SchemaTypes from './schema/schema.js';
-import type * as _Global from './types/global.js';
-import type * as _Policy from './policy/types.js';
+} from '../transport/http/client.js';
+import type { SchemaRecord } from '../schema/schema.js';
+import type * as _Streams from '../types/streams.js';
+import type * as _SchemaTypes from '../schema/schema.js';
+import type * as _Global from '../types/global.js';
 import type * as _Http from './resources/httpResources.js';
 
 /**
@@ -54,8 +53,8 @@ export function Ablo<const S extends SchemaRecord>(
 // 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
-// types live in their canonical homes (`types/streams`, `policy/types`,
-// `resources/httpResources`, `schema/schema`); the namespace is a convenience
+// types live in their canonical homes (`types/streams`, `claims/policy`,
+// `client/resources/httpResources`, `schema/schema`); the namespace is a convenience
 // path, not a second definition.
 // eslint-disable-next-line @typescript-eslint/no-namespace
 export namespace Ablo {
@@ -115,17 +114,6 @@ export namespace Ablo {
       _SchemaTypes.InferModelNames<S>;
   }
 
-  // ── Conflict (type + sub-namespace via declaration merge) ─────────
-  export type Conflict = _Policy.Conflict;
-  // eslint-disable-next-line @typescript-eslint/no-namespace
-  export namespace Conflict {
-    export type Kind = _Policy.ConflictKind;
-    export type Operation = _Policy.ConflictOperation;
-    export type Decision = _Policy.ConflictDecision;
-    export type Policy = _Policy.ConflictPolicy;
-    export type Axis = _Policy.ConflictAxis;
-  }
-
   // ── Commit (sub-namespace — write-side cohort) ────────────────────
   // eslint-disable-next-line @typescript-eslint/no-namespace
   export namespace Commit {

package/src/{transactionLayer.ts → client/contract.ts}

@@ -10,10 +10,9 @@
  * 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
+ * The taught verbs map onto the seam directly: `read` returns settled state,
+ * `create`/`update`/`delete` are operations inside a `commit()` payload, and
+ * `claim` is `claim()`. 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.
  *
@@ -22,11 +21,11 @@
  * 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';
+import type { CommitMessage } from '../wire/frames.js';
+import type { ClientCommitReceipt } from '../commit/contract.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
@@ -93,15 +92,14 @@ export interface TransactionLayer {
   ready(): Promise<void>;
 
   /** Read one settled row by id, or `null` when absent. */
-  get(model: string, id: string): Promise<ModelData | null>;
+  read(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.
+   * Submit a batch of operations with its idempotent `clientTxId` and compact
+   * `reads` evidence, then receive durable acceptance.
    */
   commit(payload: CommitMessage['payload']): Promise<CommitReceipt>;
 

package/src/{headlessClient.ts → client/headless.ts}

@@ -2,20 +2,20 @@ import {
   createAbloHttpClient,
   type AbloHttpClient,
   type AbloHttpClientOptions,
-} from './transport/httpClient.js';
-import { createHttpFeed } from './transport/httpFeed.js';
-import type { SchemaRecord } from './schema/schema.js';
-import { fieldRef } from './schema/fieldRef.js';
+} from '../transport/http/client.js';
+import { createHttpFeed } from '../observation/httpFeed.js';
+import type { SchemaRecord } from '../schema/schema.js';
+import { fieldRef } from '../schema/fieldRef.js';
 import type { ClaimParams, ServerReadOptions } from './resources/modelOperations.js';
-import type { ModelData } from './types/modelData.js';
-import type { ClaimLeaseOptions, ClaimTarget, HeldClaim } from './types/streams.js';
-import type { CommitMessage } from './wire/frames.js';
+import type { ModelData } from '../types/modelData.js';
+import type { ClaimLeaseOptions, ClaimTarget, HeldClaim } from '../types/streams.js';
+import type { CommitMessage } from '../wire/frames.js';
 import type {
   CommitReceipt,
   ListQuery,
   TransactionLayer,
-} from './transactionLayer.js';
-import { AbloConnectionError } from './errors.js';
+} from './contract.js';
+import { AbloConnectionError } from '../errors.js';
 
 export interface TransactionClientOptions<S extends SchemaRecord>
   extends AbloHttpClientOptions<S> {}
@@ -26,14 +26,14 @@ export type TransactionClient<S extends SchemaRecord> =
   & { dispose(): Promise<void> };
 
 type DynamicModel = {
-  get(options: { id: string }): Promise<ModelData | undefined>;
+  read(options: { id: string }): Promise<ModelData | undefined>;
   list(options?: ServerReadOptions<ModelData>): Promise<ModelData[]>;
   claim(options: ClaimParams<ModelData>): Promise<HeldClaim>;
 };
 
 const LAYER_MEMBERS = new Set<PropertyKey>([
   'ready',
-  'get',
+  'read',
   'list',
   'commit',
   'settled',
@@ -56,12 +56,10 @@ function toCommitOptions(payload: CommitMessage['payload']) {
       id: operation.id,
       data: operation.input,
       readAt: operation.readAt,
-      onStale: operation.onStale,
       transactionId: operation.transactionId,
       fenceToken: operation.fenceToken,
     })),
     reads: payload.reads,
-    track: payload.track,
   } as const;
 }
 
@@ -86,8 +84,8 @@ export function createTransactionClient<S extends SchemaRecord>(
 
   const layer: TransactionLayer & { dispose(): Promise<void> } = {
     ready: () => http.ready(),
-    async get(modelName, id) {
-      return (await model(modelName).get({ id })) ?? null;
+    async read(modelName, id) {
+      return (await model(modelName).read({ id })) ?? null;
     },
     list(modelName, query?: ListQuery) {
       return model(modelName).list({

package/src/client/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Public transaction client subsystem.
+ *
+ * Start here and descend through the transaction contract, headless runtime,
+ * typed Ablo factory, and model resource contracts.
+ */
+export * from './contract.js';
+export * from './headless.js';
+export * from './ablo.js';
+export * from './resources/functionalUpdate.js';

package/src/{resources → client/resources}/functionalUpdate.ts

@@ -10,7 +10,7 @@
  * caller. The write either lands or, at the extreme, throws a single
  * {@link AbloContentionError} once the reconcile budget is spent.
  *
- * Correctness comes from the `readAt` watermark plus `onStale: 'reject'`
+ * Correctness comes from the `readAt` watermark
  * (optimistic concurrency, or compare-and-swap), not from participant identity.
  * That is why it is immune to the shared-credential silent-overwrite hazard and
  * behaves identically on both transports: the HTTP and WebSocket clients inject
@@ -27,8 +27,8 @@ import {
   AbloStaleContextError,
   AbloClaimedError,
   AbloContentionError,
-} from '../errors.js';
-import type { ReadDependency } from '../coordination/schema.js';
+} from '../../errors.js';
+import type { ReadDependency } from '../../coordination/schema.js';
 
 /**
  * The functional form of an update: given the freshly-read row, return the
@@ -81,7 +81,7 @@ function backoffMs(attempt: number): number {
  * and retry" rather than a genuine failure to surface. These are the
  * optimistic-concurrency signals the functional update reconciles against:
  *   - `stale_context` — the `readAt` watermark was overtaken by a concurrent write
- *   - `claim_lost`    — a holder preempted the write (for example a human under `humansOverwrite`)
+ *   - `claim_lost`    — the write's holder lost its lease
  *   - `claim_queued`  — a holder is actively editing the row right now
  */
 export function isReconcilableConflict(err: unknown): boolean {