@abloatai/ablo 0.35.0 → 0.36.0

package/dist/transaction/transport/httpTransport.js

@@ -12,10 +12,10 @@ 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, claimHeartbeatReplySchema, claimListResponseSchema, } from '../wire/claims.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 '../coordination/claimHeartbeatLoop.js';
+import { heartbeatCadenceMs, resolveHeartbeatOptions, resolveHeartbeatPlan, startClaimHeartbeatLoop, } from '../coordination/claimHeartbeatLoop.js';
 import { mintSession } from '../auth/sessionMint.js';
 import { parseIdentityResolveResponse } from '../auth/schemas.js';
 /**
@@ -34,8 +34,8 @@ 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 { claimDescription } from '../coordination/schema.js';
-import { subTarget, streamTarget } from '../coordination/locator.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';
@@ -698,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,
@@ -707,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();
@@ -730,7 +728,105 @@ export function createHttpTransport(options) {
             params.set('field', target.field);
         const suffix = params.toString();
         const body = await requestJson(`/v1/claims${suffix ? `?${suffix}` : ''}`, { method: 'GET' }, claimListResponseSchema);
-        return { active: body.claims, queue: body.queue };
+        // 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.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;
@@ -760,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,
@@ -953,30 +1049,21 @@ export function createHttpTransport(options) {
                 queue: params.queue ?? true,
             };
             const body = await requestJson(claimPath(params.id), { method: 'POST', body: JSON.stringify(request) }, claimAcquireResponseSchema);
-            // HELD BY ADR 0018 (`docs/decisions/0018-the-premise-is-the-missing-structure.md`).
-            // Raising a successful outcome as an exception is wrong, and this stays
-            // wrong on purpose: it is the symptom the ADR is derived from, so removing
-            // the smell without the structure would hide the reason for the work.
-            //
-            // Being queued is not a transport failure — it is "I cannot establish my
-            // premise yet." Premise is the structure the codebase approximates six
-            // ways and has never modelled, which is why this was never solvable here.
-            // A client-side polling loop is specifically ruled out: it would become a
-            // shape callers build against, and the better it worked the harder it
-            // would be to replace with the status this should be.
-            //
-            // A caller that must wait today can poll `GET /v1/claims/{claimId}`, which
-            // is served and published. That primitive is safe to build on; a blessed
-            // wait algorithm here is not.
-            // The two arms are told apart by `status`, which only the queued reply
-            // carries — see `claimAcquireResponseSchema` for why they cannot be a
-            // discriminated union.
-            if ('status' in body) {
-                throw new AbloClaimedError(`Target ${name}/${params.id} is held; queued at position ${body.position}. ` +
-                    `Poll \`GET /v1/claims/{claimId}\` for the grant — the HTTP client does not await it.`, { code: 'claim_queued' });
+            // 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') {
+                return awaitGrantOverHttp(`${name}/${params.id}`, body, params);
             }
-            const { id, fenceToken } = body.claim;
-            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) => requestRaw(claimPath(isClaimHandle(params) ? params.target.id : params.id), {
             method: 'DELETE',
@@ -996,13 +1083,30 @@ export function createHttpTransport(options) {
             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 } : {}),
+                ...(params.field ? { field: partName(params.field) } : {}),
                 description: claimDescription(params),
             });
             const { data, stamp } = await retrieveModel(name, { id: params.id });
@@ -1012,23 +1116,27 @@ 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 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) : DEFAULT_CLAIM_TTL_MS, 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 = () => {
@@ -1060,19 +1168,22 @@ export function createHttpTransport(options) {
                 [Symbol.asyncDispose]: release,
             };
         }
-        const claimsForEntity = (params) => requestJson(`/v1/claims?model=${encodeURIComponent(name)}&id=${encodeURIComponent(params.id)}${params.field ? `&field=${encodeURIComponent(params.field)}` : ''}`, { method: 'GET' }, claimListResponseSchema);
+        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) => {
@@ -1224,6 +1335,7 @@ export function createHttpTransport(options) {
         async dispose() { },
         async purge() { },
         commits,
+        claims,
         model,
         sessions: {
             async create(params) {

package/dist/transaction/transport/wsTransport.d.ts

@@ -21,7 +21,7 @@ import { EventEmitter } from 'events';
 import type { ParticipantKind } from '../types/participant.js';
 import type { BootstrapReason } from '../wire/bootstrapReason.js';
 import type { ClientSyncDelta } from '../wire/delta.js';
-import type { ClaimAcquired, PresenceUpdate, ClaimExpired, ClaimGranted, ClaimHeartbeatAckPayload, ClaimLost, ClaimQueue, ClaimQueued, ClaimRejection, StaleNotification, ReadDependency, TrackDependency } from '../coordination/schema.js';
+import type { ClaimAcquired, PresenceUpdate, ClaimExpired, ClaimGranted, ClaimHeartbeatAckPayload, ClaimLost, ClaimQueue, ClaimQueued, ClaimRejection, ParticipantClaimPayload, StaleNotification, ReadDependency, TrackDependency } from '../coordination/schema.js';
 import { type AuthTokenGetter } from '../auth/credentialSource.js';
 import { type CommitAck, type CommitFrameOperation } from './commitFrames.js';
 import { type Logger } from '../logger.js';
@@ -444,9 +444,7 @@ export declare class WsTransport<TCollaboration extends EventMap<TCollaboration>
      * and effective `ttlSeconds` once `claim_ack` arrives, or rejects with a typed
      * error on a failed ack, a timeout, or a disconnect.
      */
-    sendClaim(claimId: string, syncGroups: readonly string[], options?: {
-        capabilityToken?: string;
-        ttlSeconds?: number;
+    sendClaim(claimId: string, syncGroups: readonly string[], options?: Pick<ParticipantClaimPayload, 'capabilityToken' | 'ttlSeconds'> & {
         timeoutMs?: number;
     }): Promise<{
         syncGroups: string[];

package/dist/transaction/transport/wsTransport.js

@@ -19,7 +19,7 @@
  */
 import { EventEmitter } from 'events';
 import { AbloConnectionError, AbloError, AbloSessionError, AbloValidationError, toAbloError, } from '../errors.js';
-import { updateSubscriptionPayloadSchema } from '../coordination/schema.js';
+import { participantClaimPayloadSchema, updateSubscriptionPayloadSchema, } from '../coordination/schema.js';
 import { PROTOCOL_VERSION, WS_CLOSE_PROTOCOL_VERSION } from '../wire/protocolVersion.js';
 import { WS_BEARER_SUBPROTOCOL_PREFIX, WS_SYNC_SUBPROTOCOL, } from '../auth/credentialSource.js';
 import { buildCommitFrame } from './commitFrames.js';
@@ -685,6 +685,20 @@ export class WsTransport extends EventEmitter {
         if (this.ws?.readyState !== WebSocket.OPEN) {
             return Promise.reject(this.notConnectedError('claim'));
         }
+        // Checked against the schema the server ingests it with, for the same
+        // reason `updateSubscription` below is: the two frames name their scopes
+        // identically, so a group that would be refused there is refused here, at
+        // the call that asked for it, rather than coming back as a failed ack a
+        // round trip later with nothing to point at.
+        const payload = participantClaimPayloadSchema.safeParse({
+            claimId,
+            syncGroups: [...syncGroups],
+            capabilityToken: options?.capabilityToken,
+            ttlSeconds: options?.ttlSeconds,
+        });
+        if (!payload.success) {
+            return Promise.reject(new AbloValidationError(`join was given a sync group the protocol does not accept: ${payload.error.issues[0]?.message ?? 'unreadable'}. A group is 'default' or 'kind:id'.`, { code: 'malformed_claim' }));
+        }
         const timeoutMs = options?.timeoutMs ?? 15_000;
         return new Promise((resolve, reject) => {
             const timeout = setTimeout(() => {
@@ -695,15 +709,7 @@ export class WsTransport extends EventEmitter {
             }, timeoutMs);
             this.pendingClaims.set(claimId, { resolve, reject, timeout });
             try {
-                this.ws.send(JSON.stringify({
-                    type: 'claim',
-                    payload: {
-                        claimId,
-                        syncGroups: [...syncGroups],
-                        capabilityToken: options?.capabilityToken,
-                        ttlSeconds: options?.ttlSeconds,
-                    },
-                }));
+                this.ws.send(JSON.stringify({ type: 'claim', payload: payload.data }));
             }
             catch (error) {
                 clearTimeout(timeout);

package/dist/transaction/types/streams.d.ts

@@ -446,6 +446,16 @@ export interface Claim<T = Record<string, unknown>, M = ResolveClaimMeta> {
      * claiming.
      */
     readonly ttlSeconds?: number;
+    /**
+     * The claim's open metadata bag, as it stands on the wire.
+     *
+     * A heartbeat's `details` land here under `progress` — last beat wins — so
+     * an observer can read what a long hold is doing without waiting for the
+     * holder to release. Deliberately the open record rather than the declared
+     * `ClaimMeta`: a shape the program declared has no member for a key the
+     * coordinator wrote, and `target.meta` beside it is that declared shape.
+     */
+    readonly meta?: Record<string, unknown>;
     /**
      * 0-based place in the FIFO line — present only when `status: 'queued'`
      * (`0` = next behind the holder). Absent for the active holder.

package/dist/transaction/utils/duration.d.ts

@@ -12,14 +12,39 @@
  * caller can pass the same field interchangeably. {@link toMs} returns
  * milliseconds; {@link toSeconds} returns whole seconds.
  */
+import { z } from 'zod';
 export type Duration = number | `${number}ms` | `${number}s` | `${number}m` | `${number}h`;
+/**
+ * The same grammar as a boundary schema, so a duration crossing the wire is
+ * checked against the parser that will read it rather than against a second
+ * description of it.
+ *
+ * The regex is shared with {@link toMs} deliberately: `z.toJSONSchema` emits it
+ * as a `pattern`, which is how a non-TypeScript caller learns the grammar at
+ * all. A union of `number | string` — which is what this used to be on the
+ * claim bodies — publishes as "some number or some string" and leaves the units
+ * to be guessed.
+ */
+export declare const durationSchema: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
 /**
  * Parses a duration and returns the equivalent number of milliseconds. Accepts
  * either a bare number, interpreted as seconds, or a unit-suffixed string such
  * as `'500ms'`, `'30s'`, `'3m'`, or `'24h'`. Throws an
  * {@link AbloValidationError} with code `duration_invalid` when a string does
  * not match a supported unit.
+ *
+ * Two doors, one implementation. {@link toMs} takes the narrow {@link Duration}
+ * template type, so an SDK caller writing a literal gets the unit checked at
+ * compile time. {@link parseDurationMs} takes the widened `string | number` that
+ * {@link durationSchema} infers — the shape a value has after it crossed the
+ * wire and was validated at the boundary. Neither is a cast of the other, and
+ * neither carries its own copy of the grammar.
  */
 export declare function toMs(input: Duration): number;
+/**
+ * {@link toMs} for a value that arrived over the wire, where the type system
+ * knows only `string | number` because that is what the boundary schema infers.
+ */
+export declare function parseDurationMs(input: string | number): number;
 /** Parses a duration like {@link toMs} but returns whole seconds, rounding down. */
 export declare function toSeconds(input: Duration): number;

package/dist/transaction/utils/duration.js

@@ -12,8 +12,26 @@
  * caller can pass the same field interchangeably. {@link toMs} returns
  * milliseconds; {@link toSeconds} returns whole seconds.
  */
+import { z } from 'zod';
 import { AbloValidationError } from '../errors.js';
 const PATTERN = /^(\d+(?:\.\d+)?)(ms|s|m|h)$/;
+/**
+ * The same grammar as a boundary schema, so a duration crossing the wire is
+ * checked against the parser that will read it rather than against a second
+ * description of it.
+ *
+ * The regex is shared with {@link toMs} deliberately: `z.toJSONSchema` emits it
+ * as a `pattern`, which is how a non-TypeScript caller learns the grammar at
+ * all. A union of `number | string` — which is what this used to be on the
+ * claim bodies — publishes as "some number or some string" and leaves the units
+ * to be guessed.
+ */
+export const durationSchema = z.union([
+    z.number().positive(),
+    z.string().regex(PATTERN, {
+        message: 'expected a duration such as "500ms", "30s", "3m" or "24h"',
+    }),
+]);
 const UNIT_MS = {
     ms: 1,
     s: 1_000,
@@ -26,8 +44,22 @@ const UNIT_MS = {
  * as `'500ms'`, `'30s'`, `'3m'`, or `'24h'`. Throws an
  * {@link AbloValidationError} with code `duration_invalid` when a string does
  * not match a supported unit.
+ *
+ * Two doors, one implementation. {@link toMs} takes the narrow {@link Duration}
+ * template type, so an SDK caller writing a literal gets the unit checked at
+ * compile time. {@link parseDurationMs} takes the widened `string | number` that
+ * {@link durationSchema} infers — the shape a value has after it crossed the
+ * wire and was validated at the boundary. Neither is a cast of the other, and
+ * neither carries its own copy of the grammar.
  */
 export function toMs(input) {
+    return parseDurationMs(input);
+}
+/**
+ * {@link toMs} for a value that arrived over the wire, where the type system
+ * knows only `string | number` because that is what the boundary schema infers.
+ */
+export function parseDurationMs(input) {
     if (typeof input === 'number')
         return input * 1_000;
     const match = PATTERN.exec(input);

package/dist/transaction/wire/accountResponses.d.ts

@@ -131,6 +131,29 @@ export declare const schemaModelResponseSchema: z.ZodObject<{
         }>>;
     }, z.core.$strip>>;
     hash: z.ZodString;
+    fields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        type: z.ZodEnum<{
+            string: "string";
+            number: "number";
+            boolean: "boolean";
+            date: "date";
+            enum: "enum";
+            json: "json";
+        }>;
+        isOptional: z.ZodBoolean;
+        isIndexed: z.ZodBoolean;
+        column: z.ZodOptional<z.ZodString>;
+        enumValues: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    }, z.core.$strip>>>;
+    relations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        type: z.ZodEnum<{
+            belongsTo: "belongsTo";
+            hasMany: "hasMany";
+            hasOne: "hasOne";
+        }>;
+        target: z.ZodString;
+        foreignKey: z.ZodString;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type SchemaModelResponse = z.infer<typeof schemaModelResponseSchema>;
 /**
@@ -168,6 +191,29 @@ export declare const schemaReadResponseSchema: z.ZodDiscriminatedUnion<[z.ZodObj
             }>>;
         }, z.core.$strip>>;
         hash: z.ZodString;
+        fields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            type: z.ZodEnum<{
+                string: "string";
+                number: "number";
+                boolean: "boolean";
+                date: "date";
+                enum: "enum";
+                json: "json";
+            }>;
+            isOptional: z.ZodBoolean;
+            isIndexed: z.ZodBoolean;
+            column: z.ZodOptional<z.ZodString>;
+            enumValues: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+        }, z.core.$strip>>>;
+        relations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            type: z.ZodEnum<{
+                belongsTo: "belongsTo";
+                hasMany: "hasMany";
+                hasOne: "hasOne";
+            }>;
+            target: z.ZodString;
+            foreignKey: z.ZodString;
+        }, z.core.$strip>>>;
     }, z.core.$strip>>>;
 }, z.core.$strip>, z.ZodObject<{
     active: z.ZodLiteral<true>;
@@ -194,6 +240,29 @@ export declare const schemaReadResponseSchema: z.ZodDiscriminatedUnion<[z.ZodObj
             }>>;
         }, z.core.$strip>>;
         hash: z.ZodString;
+        fields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            type: z.ZodEnum<{
+                string: "string";
+                number: "number";
+                boolean: "boolean";
+                date: "date";
+                enum: "enum";
+                json: "json";
+            }>;
+            isOptional: z.ZodBoolean;
+            isIndexed: z.ZodBoolean;
+            column: z.ZodOptional<z.ZodString>;
+            enumValues: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+        }, z.core.$strip>>>;
+        relations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            type: z.ZodEnum<{
+                belongsTo: "belongsTo";
+                hasMany: "hasMany";
+                hasOne: "hasOne";
+            }>;
+            target: z.ZodString;
+            foreignKey: z.ZodString;
+        }, z.core.$strip>>>;
     }, z.core.$strip>>>;
     schemaId: z.ZodString;
     version: z.ZodNumber;

package/dist/transaction/wire/accountResponses.js

@@ -13,6 +13,10 @@
  * schemas is what removes them from it.
  */
 import { z } from 'zod';
+// Composed, never restated: these are the artifact's own shapes, and a
+// hand-written mirror here would be a second copy of the exact record this
+// response exists to stop withholding.
+import { fieldMetaSchema, relationMetaSchema } from './modelShape.js';
 import { onStaleModeSchema } from '../coordination/schema.js';
 /**
  * One project — an app's own schema, data planes, and keys. `default` marks the
@@ -85,8 +89,39 @@ export const schemaModelResponseSchema = z.object({
     typename: z.string(),
     /** Declared disposition, or null for the engine default. */
     conflict: conflictAxisWireSchema.nullable(),
-    /** Per-model content hash — the unit of the client's drift check. */
+    /**
+     * Per-model content hash — the unit of the client's drift check, and the
+     * revalidation key for everything below it.
+     *
+     * `fields` and `relations` change only when this does, so a client reads the
+     * shape once and thereafter compares hashes: a cheap poll that refetches on a
+     * push and never otherwise. Introspection that costs one request per schema
+     * version rather than one per question.
+     */
     hash: z.string(),
+    /**
+     * The model's fields, by name.
+     *
+     * The schema artifact has always carried these and this response dropped
+     * them, so a caller with no local schema declaration — which is every caller
+     * that is not TypeScript — had no way to learn that `task.title` is a
+     * required string. It found out from a 400 at the end of a round trip.
+     *
+     * For an agent that is not merely slow, it is a reasoning detour: a typo
+     * discovered through a rejected write costs a turn and an explanation, where
+     * the same typo checked locally costs a millisecond.
+     *
+     * Absent on an artifact written before this was reported, which is why it is
+     * optional rather than empty — "this server does not tell me" and "this model
+     * has no fields" are different facts.
+     */
+    fields: z.record(z.string(), fieldMetaSchema).optional(),
+    /**
+     * The model's relations, by name — what a caller may expand, and into what.
+     *
+     * Optional for the same reason as {@link fields}.
+     */
+    relations: z.record(z.string(), relationMetaSchema).optional(),
 });
 /**
  * `GET /api/schema` — the schema active on the caller's plane.

package/dist/transaction/wire/auth.d.ts

@@ -44,6 +44,13 @@ export type EphemeralKeyRequest = z.infer<typeof ephemeralKeyRequestSchema>;
  * `auth/capability.ts` — the grant is one structure, and its request form is a
  * face of it rather than a separate shape. Re-exported here so the wire barrel
  * stays the single import path for the boundary.
+ *
+ * This is the only import wire makes for something larger than a schema leaf,
+ * so it carries exactly the shape the barrel forwards and nothing else: the
+ * grant's own vocabulary — the verb enum, the `model.verb` spelling, the
+ * helpers that derive one from the other — is read from `auth/capability.ts`
+ * by the callers that build a grant, not through here.
  */
-export { capabilityRequestSchema, grantedOperationSchema, capabilityOperationSchema, } from '../auth/capability.js';
-export type { CapabilityRequest, GrantedOperation, CapabilityOperation, } from '../auth/capability.js';
+export { capabilityRequestSchema, capabilityMintResponseSchema, } from '../auth/capability.js';
+export type { CapabilityMintResponse } from '../auth/capability.js';
+export type { CapabilityRequest } from '../auth/capability.js';