@abloatai/ablo 0.34.1 → 0.36.0

package/dist/{client → transaction/transport}/httpTransport.js

@@ -7,13 +7,16 @@
  */
 import { AbloClaimedError, AbloAuthenticationError, AbloConnectionError, AbloIdempotencyError, AbloValidationError, AbloNotFoundError, claimedError, translateHttpError, } from '../errors.js';
 import { v5 as uuidv5 } from 'uuid';
-import { reconcileFunctionalUpdate, } from './functionalUpdate.js';
-import { assertBrowserSafety, readProcessEnv, resolveApiKey, resolveApiKeyValue, resolveAuthToken, resolveBaseURL, resolveBootstrapBaseUrl, rejectRemovedDatabaseUrlOption, warnIfCliKeyMismatch, } from './auth.js';
+import { z } from 'zod';
+import { reconcileFunctionalUpdate, } from '../resources/functionalUpdate.js';
+import { assertBrowserSafety, readProcessEnv, resolveApiKey, resolveApiKeyValue, resolveAuthToken, resolveBaseURL, resolveBootstrapBaseUrl, rejectRemovedDatabaseUrlOption, warnIfCliKeyMismatch, } from '../auth/apiKey.js';
 import { PROTOCOL_VERSION, PROTOCOL_VERSION_HEADER } from '../wire/protocolVersion.js';
 import { commitReceiptSchema } from '../wire/commit.js';
+import { claimAcquireResponseSchema, claimHeartbeatBatchReplySchema, claimHeartbeatReplySchema, claimListResponseSchema, claimStateSchema, } from '../wire/claims.js';
+import { modelListResponseSchema, modelReadResponseSchema, } from '../wire/modelResponses.js';
 import { toMs } from '../utils/duration.js';
-import { heartbeatCadenceMs, resolveHeartbeatOptions, startClaimHeartbeatLoop, } from './claimHeartbeatLoop.js';
-import { mintSession } from './sessionMint.js';
+import { heartbeatCadenceMs, resolveHeartbeatOptions, resolveHeartbeatPlan, startClaimHeartbeatLoop, } from '../coordination/claimHeartbeatLoop.js';
+import { mintSession } from '../auth/sessionMint.js';
 import { parseIdentityResolveResponse } from '../auth/schemas.js';
 /**
  * Interpret a heartbeat reply for a lease this handle HOLDS: anything other
@@ -31,12 +34,20 @@ function heldHeartbeatReply(reply, label) {
     }
     throw new AbloClaimedError(`The lease behind ${label} is no longer held — it expired or was granted onward. Re-acquire the claim and retry; a write attempted under the old lease is rejected by its \`readAt\` guard.`, { code: 'claim_lost' });
 }
-import { assertWriteOptions } from './writeOptionsSchema.js';
-import { createDurableHttpCommitEnvelope, canonicalHttpCommitBody, durableHttpCommitEnvelopeSchema, httpCommitEnvelopeRecordId, isHttpCommitReplayExpired, } from '../transactions/httpCommitEnvelope.js';
-import { resolveDurableWrites } from './durableWrites.js';
+import { claimDescription, partName } from '../coordination/schema.js';
+import { subTarget, streamTarget, batchFence, fenceTokenFor, } from '../coordination/locator.js';
+import { declaredMeta, wireMeta } from '../coordination/claimMeta.js';
+import { assertWriteOptions } from '../resources/writeOptionsSchema.js';
+import { createDurableHttpCommitEnvelope, canonicalHttpCommitBody, durableHttpCommitEnvelopeSchema, httpCommitEnvelopeRecordId, isHttpCommitReplayExpired, } from '../transactions/settlement/httpCommitEnvelope.js';
+import { resolveDurableWrites } from '../durableWrites.js';
 /** @internal Default per-request deadline for the private HTTP transport. */
 export const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
 const HTTP_CONFIRMATION_POLL_INTERVAL_MS = 250;
+/**
+ * The server's acquire window, mirrored here as the client-side default for a
+ * claim that names no `ttl` — it sets the auto-heartbeat cadence.
+ */
+const DEFAULT_CLAIM_TTL_MS = 60_000;
 function parseSuccessfulCommitResponse(value, idempotencyKey) {
     const parsed = commitReceiptSchema.safeParse(value);
     if (!parsed.success || parsed.data.clientTxId !== idempotencyKey) {
@@ -51,6 +62,10 @@ function parseSuccessfulCommitResponse(value, idempotencyKey) {
 }
 /** Decode the HTTP claim DTO into the one public Claim shape. */
 function claimFromModelClaim(claim) {
+    // The handle a caller reads back is a public claim, so its `meta` is the
+    // declared shape; the rest of the sub-entity locator crosses whole rather
+    // than member by member, which is how `fields` used to die on this hop.
+    const { meta, ...details } = subTarget(claim.target);
     return {
         object: 'claim',
         id: claim.id,
@@ -62,12 +77,9 @@ function claimFromModelClaim(claim) {
         expiresAt: claim.expiresAt,
         ...(claim.position !== undefined ? { position: claim.position } : {}),
         target: {
-            type: claim.target.model,
-            id: claim.target.id,
-            ...(claim.target.path ? { path: claim.target.path } : {}),
-            ...(claim.target.range ? { range: claim.target.range } : {}),
-            ...(claim.target.field ? { field: claim.target.field } : {}),
-            ...(claim.target.meta ? { meta: claim.target.meta } : {}),
+            ...streamTarget(claim.target),
+            ...details,
+            ...(meta !== undefined ? { meta: declaredMeta(meta) } : {}),
         },
     };
 }
@@ -159,7 +171,7 @@ export function createHttpTransport(options) {
             }
             : undefined;
         if (!scope) {
-            const rawIdentity = await requestJson('/auth/identity', { method: 'GET' }, true);
+            const rawIdentity = await requestRaw('/auth/identity', { method: 'GET' }, true);
             const identity = parseIdentityResolveResponse(rawIdentity);
             scope = {
                 organizationId: identity.accountScope,
@@ -226,7 +238,15 @@ export function createHttpTransport(options) {
         return target.toString();
     }
     const requestTimeoutMs = options.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
-    async function requestJson(path, init, skipReady = false) {
+    /**
+     * Issues one request and returns its decoded body without a contract.
+     *
+     * Use this only where the response has no shape worth checking — a release
+     * that answers `{}` — or where the caller runs a richer check of its own, as
+     * the commit paths do with their receipt schema. Everywhere else, go through
+     * {@link requestJson}, which will not let a response past unvalidated.
+     */
+    async function requestRaw(path, init, skipReady = false) {
         if (!skipReady)
             await ready();
         const { idempotencyKey, sealedProtocolVersion, ...requestInit } = init;
@@ -295,6 +315,22 @@ export function createHttpTransport(options) {
         }
         return body;
     }
+    /**
+     * Issues one request and validates its body against the route's schema.
+     *
+     * The schema is the route's response contract, declared once in `wire/` and
+     * shared with the server that produces it. A body that does not match is a
+     * version disagreement between the two, so it is refused whole rather than
+     * read field by field and half-trusted.
+     */
+    async function requestJson(path, init, responseSchema, skipReady = false) {
+        const body = await requestRaw(path, init, skipReady);
+        const parsed = responseSchema.safeParse(body);
+        if (!parsed.success) {
+            throw new AbloConnectionError(`The Ablo API returned a response for ${init.method ?? 'GET'} ${path} that this client could not read; nothing was applied.`, { code: 'malformed_response', cause: parsed.error });
+        }
+        return parsed.data;
+    }
     function isDefinitiveHttpRejection(error) {
         if (typeof error !== 'object' || error === null)
             return false;
@@ -388,7 +424,7 @@ export function createHttpTransport(options) {
                 }, remaining)
                 : null;
             try {
-                const raw = await requestJson(request.path, {
+                const raw = await requestRaw(request.path, {
                     method: request.method,
                     idempotencyKey: request.idempotencyKey,
                     ...(request.sealedProtocolVersion !== undefined
@@ -456,7 +492,7 @@ export function createHttpTransport(options) {
             a.id.localeCompare(b.id));
         for (const envelope of envelopes) {
             try {
-                const raw = await requestJson(envelope.request.path, {
+                const raw = await requestRaw(envelope.request.path, {
                     method: envelope.request.method,
                     idempotencyKey: envelope.idempotencyKey,
                     sealedProtocolVersion: envelope.protocolVersion,
@@ -613,7 +649,7 @@ export function createHttpTransport(options) {
             };
             let response;
             try {
-                const raw = await requestJson(exactRequest.path, {
+                const raw = await requestRaw(exactRequest.path, {
                     method: exactRequest.method,
                     idempotencyKey: exactRequest.idempotencyKey,
                     ...(exactRequest.sealedProtocolVersion !== undefined
@@ -654,11 +690,6 @@ export function createHttpTransport(options) {
             ? crypto.randomUUID()
             : `tx_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
     }
-    function createClaimId() {
-        return typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
-            ? `int_${crypto.randomUUID()}`
-            : `int_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
-    }
     function createModelId(modelName, idempotencyKey) {
         if (idempotencyKey) {
             return uuidv5(`${modelName}:${idempotencyKey}`, 'aa4ba6d4-bf0b-5b38-9c45-116f79a6e548');
@@ -667,7 +698,7 @@ export function createHttpTransport(options) {
             ? crypto.randomUUID()
             : `id_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
     }
-    function normalizeCommitOperation(op, defaults, fenceToken) {
+    function normalizeCommitOperation(op, defaults, fence) {
         return {
             action: op.action,
             model: op.model,
@@ -676,18 +707,16 @@ export function createHttpTransport(options) {
             transactionId: op.transactionId ?? null,
             readAt: op.readAt ?? defaults.readAt ?? null,
             onStale: op.onStale ?? defaults.onStale ?? null,
-            // The batch's claim (if any) supplies one token for every op, mirroring
-            // how it supplies the batch `readAt`.
-            fenceToken: op.fenceToken ?? fenceToken ?? null,
+            fenceToken: op.fenceToken ?? fenceTokenFor(fence, op.model, op.id ?? null),
         };
     }
-    function normalizeCommitOperations(commitOptions, fenceToken) {
+    function normalizeCommitOperations(commitOptions, fence) {
         if (commitOptions.operations.length === 0) {
             throw new AbloValidationError('Commit requires a non-empty `operations` array.', {
                 code: 'commit_operation_required',
             });
         }
-        return commitOptions.operations.map((op) => normalizeCommitOperation(op, commitOptions, fenceToken));
+        return commitOptions.operations.map((op) => normalizeCommitOperation(op, commitOptions, fence));
     }
     async function listClaimState(target) {
         const params = new URLSearchParams();
@@ -698,14 +727,107 @@ export function createHttpTransport(options) {
         if (target?.field)
             params.set('field', target.field);
         const suffix = params.toString();
-        const body = await requestJson(`/v1/claims${suffix ? `?${suffix}` : ''}`, {
-            method: 'GET',
-        });
+        const body = await requestJson(`/v1/claims${suffix ? `?${suffix}` : ''}`, { method: 'GET' }, claimListResponseSchema);
+        // One list, one resource in two states: holders and waiters are told
+        // apart by each entry's `status`, not by bespoke envelope members.
         return {
-            active: body.claims ?? [],
-            queue: body.queue ?? [],
+            active: body.data.filter((row) => row.status !== 'queued'),
+            queue: body.data.filter((row) => row.status === 'queued'),
         };
     }
+    // The claim-ticket surface: everything a caller does holding only a
+    // `claimId` — which is all a queued acquire leaves in its hand. Each method
+    // is a thin cast of its route; the reply schemas are the wire's own, so the
+    // surface cannot describe a response the server does not send.
+    const claims = {
+        retrieve({ claimId }) {
+            return requestJson(`/v1/claims/${encodeURIComponent(claimId)}`, { method: 'GET' }, claimStateSchema);
+        },
+        heartbeat({ claimId, ttl }) {
+            return requestJson(`/v1/claims/${encodeURIComponent(claimId)}/heartbeat`, {
+                method: 'POST',
+                body: JSON.stringify(ttl !== undefined ? { ttl } : {}),
+            }, claimHeartbeatReplySchema);
+        },
+        async heartbeatAll(options) {
+            const reply = await requestJson('/v1/claims/heartbeat', {
+                method: 'POST',
+                body: JSON.stringify(options?.ttl !== undefined ? { ttl: options.ttl } : {}),
+            }, claimHeartbeatBatchReplySchema);
+            return reply.results;
+        },
+        async release({ claimId }) {
+            await requestRaw(`/v1/claims/${encodeURIComponent(claimId)}`, {
+                method: 'DELETE',
+            });
+        },
+    };
+    // How the stateless client waits its turn. The queued slot is real server
+    // state, so one heartbeat per tick does both jobs: it refreshes this
+    // waiter's slot and reports the line's answer — `queued` (still waiting) or
+    // `held` (granted). The first check comes quickly because most holds are a
+    // short claim→write→release; after that the cadence relaxes, with jitter so
+    // a fleet of waiters doesn't beat in step.
+    const GRANT_POLL_FIRST_MS = 250;
+    const GRANT_POLL_INTERVAL_MS = 1_000;
+    // An abort cuts the sleep short so the wait ends within a tick of the
+    // signal, not at the next scheduled beat.
+    const sleep = (ms, signal) => new Promise((resolve) => {
+        const done = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', done);
+            resolve();
+        };
+        const timer = setTimeout(done, ms);
+        signal?.addEventListener('abort', done, { once: true });
+    });
+    async function awaitGrantOverHttp(targetLabel, queued, options) {
+        // The queued reply is a claim resource in its waiting state, so the
+        // handle is its `id` — same rule as the 201 and the poll.
+        const claimId = queued.id;
+        const { signal } = options;
+        // Leave the line before rejecting: an abandoned slot would otherwise sit
+        // in the queue until its TTL lapses, stalling every waiter behind it.
+        const rejectAndLeave = async (error) => {
+            await claims.release({ claimId }).catch(() => { });
+            throw error;
+        };
+        if (options.maxQueueDepth !== undefined && queued.position >= options.maxQueueDepth) {
+            return rejectAndLeave(new AbloClaimedError(`Claim queue for ${targetLabel} is ${queued.position} deep (max ${options.maxQueueDepth}).`, { code: 'queue_too_deep' }));
+        }
+        const deadline = options.waitTimeoutMs !== undefined ? Date.now() + options.waitTimeoutMs : undefined;
+        let delay = GRANT_POLL_FIRST_MS;
+        for (;;) {
+            if (signal?.aborted) {
+                return rejectAndLeave(new AbloClaimedError(`The wait for the claim on ${targetLabel} was aborted before the grant arrived.`, { code: 'claim_wait_aborted' }));
+            }
+            if (deadline !== undefined && Date.now() >= deadline) {
+                return rejectAndLeave(new AbloClaimedError(`Timed out after ${options.waitTimeoutMs}ms waiting for the queue grant on ${targetLabel}.`, { code: 'grant_timeout' }));
+            }
+            await sleep(deadline !== undefined ? Math.min(delay, Math.max(0, deadline - Date.now())) : delay, signal);
+            if (signal?.aborted) {
+                return rejectAndLeave(new AbloClaimedError(`The wait for the claim on ${targetLabel} was aborted before the grant arrived.`, { code: 'claim_wait_aborted' }));
+            }
+            delay = GRANT_POLL_INTERVAL_MS * (0.85 + Math.random() * 0.3);
+            // A lease that ended answers the beat with 409 `claim_lost`, which the
+            // wire error mapping raises as AbloClaimedError before this reads
+            // anything — the wait fails with the loss, as the socket wait does.
+            const beat = await claims.heartbeat({ claimId });
+            if (beat.status !== 'held')
+                continue;
+            // Granted. The heartbeat ack does not carry the fence token — the claim
+            // state does, server-stamped at grant.
+            const state = await claims.retrieve({ claimId });
+            if (state.status !== 'active') {
+                return rejectAndLeave(new AbloClaimedError(`Claim lost while queued for ${targetLabel}.`, {
+                    code: 'claim_lost',
+                }));
+            }
+            return state.fenceToken !== undefined
+                ? { id: claimId, fenceToken: state.fenceToken }
+                : { id: claimId };
+        }
+    }
     async function applyClaimedPolicy(target, options, defaultPolicy = 'return') {
         const policy = options?.ifClaimed ?? defaultPolicy;
         if (policy === 'return')
@@ -734,7 +856,7 @@ export function createHttpTransport(options) {
                 ...commitOptions,
                 readAt: commitOptions.readAt ?? claim?.readAt ?? null,
                 onStale: commitOptions.onStale ?? (claim?.readAt !== undefined ? 'reject' : null),
-            }, claim?.fenceToken ?? null);
+            }, batchFence(claim?.target, claim?.fenceToken));
             const requestBody = {
                 operations,
                 reads: commitOptions.reads,
@@ -761,14 +883,14 @@ export function createHttpTransport(options) {
                 })));
                 throw error;
             }
-            // `requestJson` throws via `translateHttpError` on any non-2xx,
-            // so reaching here implies success. Narrow `status` to the
-            // `CommitWait`-compatible subset; `'rejected'` only appears on
-            // the rejection body (already thrown).
-            const status = body.status === 'queued' ? 'queued' : 'confirmed';
+            // `requestJson` throws via `translateHttpError` on any non-2xx, so
+            // reaching here implies success and `body` is already the success-only
+            // receipt union — a rejection is a separate type that never arrives here.
+            // The settlement status therefore passes through verbatim: no branch may
+            // collapse a state the server reported into a different one.
             return {
                 id: body.id ?? body.clientTxId,
-                status,
+                status: body.status,
                 lastSyncId: body.lastSyncId,
                 ...(body.notifications && body.notifications.length > 0
                     ? { notifications: body.notifications }
@@ -799,26 +921,26 @@ export function createHttpTransport(options) {
             }
         }
         const qs = params.toString();
-        const res = await requestJson(`/v1/models/${encodeURIComponent(modelName)}${qs ? `?${qs}` : ''}`, { method: 'GET' });
-        return res.data ?? [];
+        const res = await requestJson(`/v1/models/${encodeURIComponent(modelName)}${qs ? `?${qs}` : ''}`, { method: 'GET' }, modelListResponseSchema);
+        // The envelope is checked; the rows are not, and cannot be here. This
+        // transport is schema-agnostic — it moves rows for whatever schema the
+        // caller declared, and `T` is that declaration. Row validation belongs to
+        // the typed facade above, which holds the model's schema.
+        return res.data;
     }
     async function retrieveModel(modelName, params) {
         await applyClaimedPolicy({ model: modelName, id: params.id }, params);
-        const query = await requestJson(`/v1/models/${encodeURIComponent(modelName)}/${encodeURIComponent(params.id)}`, {
-            method: 'GET',
-        });
+        const query = await requestJson(`/v1/models/${encodeURIComponent(modelName)}/${encodeURIComponent(params.id)}`, { method: 'GET' }, modelReadResponseSchema);
         // A miss is `data: undefined`, not a thrown error. The WebSocket client's
         // `retrieve` returns `T | undefined` for a missing row; throwing only here
         // made the obvious read ("does this row exist?") a hard edge that an agent
         // had to wrap in try/catch. Both transports agree: an absent row means absent
         // data. Callers branch on `.data` (the documented `.data?.x` usage).
         // Normalize a miss to `undefined` (the server may send `null` or omit it).
+        // The row itself is the caller's declared type — see the note in `listModel`
+        // on why this transport validates the envelope and not the row.
         const data = (query.data ?? undefined);
-        return {
-            data,
-            stamp: query.stamp ?? 0,
-            claims: query.claims ?? [],
-        };
+        return { data, stamp: query.stamp, claims: query.claims };
     }
     /**
      * A single-operation mutation over the model-scoped routes — the canonical
@@ -884,13 +1006,12 @@ export function createHttpTransport(options) {
             recordCoordinationConflict(error, clientTxId, [{ model: modelName, id }]);
             throw error;
         }
-        // `requestJson` throws via `translateHttpError` on any non-2xx, so reaching
-        // here implies success. Narrow `status` to the `CommitWait`-compatible
-        // subset; `'rejected'` only appears on a thrown rejection body.
-        const status = body.status === 'queued' ? 'queued' : 'confirmed';
+        // Same contract as `commits.create` above: a non-2xx already threw, so
+        // `body` is the success-only receipt union and its settlement status passes
+        // through verbatim rather than through a catch-all branch.
         return {
             id: body.serverTxId,
-            status,
+            status: body.status,
             lastSyncId: body.lastSyncId,
         };
     }
@@ -904,30 +1025,47 @@ export function createHttpTransport(options) {
             value.object === 'claim' &&
             typeof value.id === 'string' &&
             typeof value.release === 'function';
-        const claimMeta = (options) => options?.meta;
         const acquireClaim = async (params) => {
-            const body = await requestJson(claimPath(params.id), {
-                method: 'POST',
-                body: JSON.stringify({
-                    description: params.description ?? 'editing',
-                    ...(params.ttl !== undefined ? { ttl: params.ttl } : {}),
-                    ...(claimMeta(params) ? { meta: claimMeta(params) } : {}),
-                    // `queue` (default true) → queue behind the holder; false → fail-fast
-                    // with AbloClaimedError (work-distribution dedup).
-                    queue: params.queue ?? true,
-                }),
-            });
+            // The row is named by the URL, so `target` carries only the narrowing a
+            // claim adds below it. Sending it is what makes a field-scoped claim
+            // actually field-scoped: the server's conflict rule reads `path`,
+            // `range`, and `field`, so a claim that keeps them client-side takes a
+            // lease on the whole row while its handle says otherwise.
+            // Projected in one move rather than member by member. The member-by-member
+            // version is how `field` came to be sent while `fields` was not, which
+            // left a set-scoped claim silently holding the whole row.
+            const narrowing = subTarget(params);
+            // Typed as the request contract rather than a bare literal — the omission
+            // above was invisible for exactly as long as this was an untyped object.
+            const request = {
+                description: claimDescription(params),
+                ...(params.ttl !== undefined ? { ttl: params.ttl } : {}),
+                // The caller's `meta` is the declared shape; the body is wire-shaped,
+                // so it crosses through the same conversion `subTarget` used above.
+                ...(params.meta !== undefined ? { meta: wireMeta(params.meta) } : {}),
+                ...(Object.keys(narrowing).length > 0 ? { target: narrowing } : {}),
+                // `queue` (default true) → queue behind the holder; false → fail-fast
+                // with AbloClaimedError (work-distribution dedup).
+                queue: params.queue ?? true,
+            };
+            const body = await requestJson(claimPath(params.id), { method: 'POST', body: JSON.stringify(request) }, claimAcquireResponseSchema);
+            // One resource, two states, discriminated by `status`. The queued arm
+            // WAITS, exactly as the socket client does: `claim({ id })` means
+            // "serialize me behind the holder" on every transport, and the grant
+            // machinery is the SDK's to own, not a loop each caller re-derives.
+            // (Being queued is still not an error — ADR 0018 — which is precisely
+            // why it no longer surfaces as one here. The `claims` namespace remains
+            // the manual ticket surface.)
             if (body.status === 'queued') {
-                throw new AbloClaimedError(`Target ${name}/${params.id} is held; queued at position ${body.position ?? 0}. ` +
-                    `The HTTP client cannot await the grant without a WebSocket.`, { code: 'claim_queued' });
+                return awaitGrantOverHttp(`${name}/${params.id}`, body, params);
             }
-            // `claimId` is the field name the queued response uses; check it alongside
-            // the other id shapes the response may carry.
-            const id = body.claim?.id ?? body.id ?? body.claimId ?? createClaimId();
-            const fenceToken = body.claim?.fenceToken;
-            return fenceToken !== undefined ? { id, fenceToken } : { id };
+            // The lease's own fields are mirrored at the top level, the same place
+            // the poll puts them — one reader for both answers.
+            return body.fenceToken !== undefined
+                ? { id: body.id, fenceToken: body.fenceToken }
+                : { id: body.id };
         };
-        const releaseClaim = (params) => requestJson(claimPath(isClaimHandle(params) ? params.target.id : params.id), {
+        const releaseClaim = (params) => requestRaw(claimPath(isClaimHandle(params) ? params.target.id : params.id), {
             method: 'DELETE',
         }).then(() => undefined);
         // One beat on the held lease. A lapsed lease answers `claim_lost`
@@ -941,18 +1079,35 @@ export function createHttpTransport(options) {
                     ...(options.ttl !== undefined ? { ttl: options.ttl } : {}),
                     ...(options.details !== undefined ? { details: options.details } : {}),
                 }),
-            });
+            }, claimHeartbeatReplySchema);
             return heldHeartbeatReply(reply, `claim ${claimId} on ${name}/${id}`);
         };
         async function claimImpl(params) {
-            const { id: claimId, fenceToken } = await acquireClaim(params);
+            let acquired;
+            try {
+                acquired = await acquireClaim(params);
+            }
+            catch (error) {
+                // The try-claim: a held target is an expected outcome of `queue:
+                // false`, not an error — resolve `null` and let the caller move on.
+                // Every other failure (auth, validation, network) stays a rejection,
+                // and the write-site claim path calls `acquireClaim` directly, so a
+                // write that could not claim still fails loudly.
+                if (params.queue === false &&
+                    error instanceof AbloClaimedError &&
+                    (error.code === 'entity_claimed' || error.code === 'claim_conflict')) {
+                    return null;
+                }
+                throw error;
+            }
+            const { id: claimId, fenceToken } = acquired;
             observability?.captureClaim({
                 phase: 'acquired',
                 claimId,
                 model: name,
                 id: params.id,
-                ...(params.field ? { field: params.field } : {}),
-                reason: params.description ?? 'editing',
+                ...(params.field ? { field: partName(params.field) } : {}),
+                description: claimDescription(params),
             });
             const { data, stamp } = await retrieveModel(name, { id: params.id });
             // A held claim hands back a snapshot; the typed `HeldClaim.data` is `T`.
@@ -961,43 +1116,49 @@ export function createHttpTransport(options) {
             if (data === undefined) {
                 throw new AbloNotFoundError(`Cannot claim ${name}/${params.id}: it does not exist (or is outside this credential's scope).`, [params.id]);
             }
+            // One reading of the heartbeat options — cadence and callbacks from
+            // whichever spelling the caller used (plan object, shorthand, or the
+            // deprecated flat callbacks).
+            const plan = resolveHeartbeatPlan(params);
             const heartbeat = async (beatOptions) => {
                 const resolved = resolveHeartbeatOptions(beatOptions);
                 const beat = await heartbeatClaim(params.id, claimId, {
                     ttl: resolved.ttl ?? params.ttl,
                     ...(resolved.details !== undefined ? { details: resolved.details } : {}),
                 });
-                params.onHeartbeat?.(beat);
+                plan.onBeat?.(beat);
                 return beat;
             };
             // Opt-in auto-heartbeat — the background-worker cadence. The stateless
-            // HTTP claim defaults to the server's 60s acquire window when no TTL
+            // HTTP claim defaults to the server's acquire window when no TTL
             // was requested, so the default cadence lands at 20s beats.
-            const stopHeartbeatLoop = params.heartbeat
+            const stopHeartbeatLoop = plan.loop
                 ? startClaimHeartbeatLoop({
                     beat: () => heartbeat(),
-                    intervalMs: heartbeatCadenceMs(params.ttl !== undefined ? toMs(params.ttl) : 60_000, params.heartbeat),
-                    ...(params.onHeartbeatLost ? { onLost: params.onHeartbeatLost } : {}),
+                    intervalMs: heartbeatCadenceMs(params.ttl !== undefined ? toMs(params.ttl) : DEFAULT_CLAIM_TTL_MS, plan.cadence),
+                    ...(plan.onLost ? { onLost: plan.onLost } : {}),
                 })
                 : undefined;
             const release = () => {
                 stopHeartbeatLoop?.();
                 return releaseClaim(params);
             };
+            // The handle handed back is a public claim, so its `meta` is the declared
+            // shape — the same crossing the two decodes above make, spelled the same
+            // way. `subTarget` is wire-shaped by contract, including here, where the
+            // value happens to have started out declared.
+            const { meta, ...narrowed } = subTarget(params);
             return {
                 object: 'claim',
                 id: claimId,
                 readAt: stamp,
                 ...(fenceToken !== undefined ? { fenceToken } : {}),
                 target: {
-                    type: name,
-                    id: params.id,
-                    ...(params.field ? { field: params.field } : {}),
-                    ...(params.path ? { path: params.path } : {}),
-                    ...(params.range ? { range: params.range } : {}),
-                    ...(claimMeta(params) ? { meta: claimMeta(params) } : {}),
+                    ...streamTarget({ model: name, id: params.id }),
+                    ...narrowed,
+                    ...(meta !== undefined ? { meta: declaredMeta(meta) } : {}),
                 },
-                description: params.description ?? 'editing',
+                description: claimDescription(params),
                 data,
                 release,
                 revoke: () => {
@@ -1007,23 +1168,26 @@ export function createHttpTransport(options) {
                 [Symbol.asyncDispose]: release,
             };
         }
-        const claimsForEntity = async (params) => requestJson(`/v1/claims?model=${encodeURIComponent(name)}&id=${encodeURIComponent(params.id)}${params.field ? `&field=${encodeURIComponent(params.field)}` : ''}`, { method: 'GET' });
+        const claimsForEntity = (params) => requestJson(`/v1/claims?model=${encodeURIComponent(name)}&id=${encodeURIComponent(params.id)}${params.field ? `&field=${encodeURIComponent(partName(params.field))}` : ''}`, { method: 'GET' }, claimListResponseSchema);
         const claim = Object.assign(claimImpl, {
             release: releaseClaim,
             state: async (params) => {
                 const res = await claimsForEntity(params);
-                const first = res.claims?.[0];
+                // Holders come first in the one list; a `queued` entry is a waiter.
+                const first = res.data.find((row) => row.status !== 'queued');
                 return first ? claimFromModelClaim(first) : null;
             },
             queue: async (params) => {
                 const res = await claimsForEntity(params);
                 return {
                     object: 'list',
-                    data: (res.queue ?? []).map(claimFromModelClaim),
+                    data: res.data
+                        .filter((row) => row.status === 'queued')
+                        .map(claimFromModelClaim),
                 };
             },
             reorder: async (params) => {
-                await requestJson(`${claimPath(params.id)}/reorder`, {
+                await requestRaw(`${claimPath(params.id)}/reorder`, {
                     method: 'POST',
                     // The reorder route's payload is `{ heldBy, claimId }[]` — a Claim's id
                     // is the claimId.
@@ -1136,6 +1300,29 @@ export function createHttpTransport(options) {
                     return mutateModel('delete', name, params.id, undefined, options);
                 });
             },
+            async track(params) {
+                const dependency = {
+                    model: name.toLowerCase(),
+                    id: params.id,
+                    ...(params.readAt !== undefined ? { readAt: params.readAt } : {}),
+                };
+                // A track carries no write, so it rides the commit lane as a
+                // zero-operation body — the shape `/v1/commits` accepts for registering
+                // a premise without one. Going through the same durable lane as every
+                // other commit means a disconnect replays the registration rather than
+                // dropping it, and a notification that had already fired is not lost to
+                // a retry.
+                const body = await dispatchHttpCommit({
+                    path: '/v1/commits',
+                    method: 'POST',
+                    idempotencyKey: createClientTxId(),
+                    body: { track: [dependency] },
+                    wait: 'confirmed',
+                });
+                return body.notifications && body.notifications.length > 0
+                    ? { notifications: body.notifications }
+                    : {};
+            },
         };
     }
     return {
@@ -1148,6 +1335,7 @@ export function createHttpTransport(options) {
         async dispose() { },
         async purge() { },
         commits,
+        claims,
         model,
         sessions: {
             async create(params) {
@@ -1158,11 +1346,21 @@ export function createHttpTransport(options) {
                 if (!apiKey) {
                     throw new AbloAuthenticationError('sessions.create requires a secret (sk_) API key — call it from your backend, not the browser.', { code: 'apikey_missing' });
                 }
+                // A transport built without a schema has no way to translate `can`'s
+                // schema keys into the type names the server gates on. Minting anyway
+                // would spell every override wrong and surface as
+                // `capability_scope_denied` on the agent's first write, so refuse here
+                // instead of guessing.
+                if (!options.modelTypenames) {
+                    throw new AbloValidationError('sessions.create needs the schema this client is bound to. Construct it ' +
+                        "through Ablo({ schema, apiKey, transport: 'http' }) rather than the " +
+                        'bare transport.', { code: 'invalid_options', param: 'schema' });
+                }
                 return mintSession(params, {
                     apiKey,
                     baseUrl: apiBaseUrl,
+                    modelTypenames: options.modelTypenames,
                     ...(options.fetch ? { fetch: options.fetch } : {}),
-                    ...(options.modelTypenames ? { modelTypenames: options.modelTypenames } : {}),
                 });
             },
         },