@abloatai/ablo 0.34.1 → 0.35.0

package/dist/transaction/auth/index.js

@@ -0,0 +1,304 @@
+/**
+ * Exchanges an API key for a capability token and the scope it grants.
+ *
+ * The `Ablo({...})` factory calls this during startup when you provide an
+ * `apiKey` but no explicit capability token, organization, or user identity. It
+ * sends one `POST /auth/capability` request; the server responds with the
+ * granted scope and any user metadata, which the client uses to populate its
+ * session state. The API key is the only credential you handle directly — this
+ * exchange happens automatically behind it.
+ */
+import { parseCapabilityExchangeResponse, parseEphemeralKeyResponse, parseIdentityResolveResponse, } from './schemas.js';
+import { AbloAuthenticationError, hasWireCode, translateHttpError } from '../errors.js';
+// The capability vocabulary — what a grant is, on both axes, in one place.
+// Served from this barrel so every minter reaches it through one import.
+export { capabilityOperationSchema, capabilityCanSchema, capabilityScopeSchema, capabilityRequestSchema, grantedOperationSchema, grantedOperations, expandReadYourWrites, modelWireNames, capabilityModelAliases, unresolvableOperations, } from './capability.js';
+export async function exchangeApiKey(options) {
+    if (!options.apiKey) {
+        throw new AbloAuthenticationError('No API key found. Set ABLO_API_KEY in your environment — `npx ablo login` ' +
+            'then `npx ablo dev` writes it into .env.local for you — or pass ' +
+            '`apiKey` to Ablo({ ... }) directly.', { code: 'apikey_missing' });
+    }
+    if (!options.baseUrl) {
+        throw new AbloAuthenticationError('baseUrl is required for capability exchange', { code: 'base_url_missing' });
+    }
+    const fetcher = options.fetch ?? fetch;
+    const url = `${options.baseUrl.replace(/\/+$/, '')}/auth/capability`;
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const controller = new AbortController();
+    const timer = setTimeout(() => { controller.abort(); }, timeoutMs);
+    let response;
+    try {
+        response = await fetcher(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${options.apiKey}`,
+            },
+            body: JSON.stringify({
+                participantKind: options.participantKind,
+                ...(options.participantId ? { participantId: options.participantId } : {}),
+                syncGroups: options.syncGroups,
+                operations: options.operations,
+                wideScope: options.wideScope,
+                ttlSeconds: options.ttlSeconds,
+                label: options.label,
+                userMeta: options.userMeta,
+            }),
+            signal: controller.signal,
+        });
+    }
+    catch (err) {
+        throw new AbloAuthenticationError(`apiKey exchange failed: ${err instanceof Error ? err.message : String(err)}`, { code: 'exchange_network_error', cause: err });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (!response.ok) {
+        let body = null;
+        try {
+            body = await response.json();
+        }
+        catch {
+            // ignore — server returned non-JSON error
+        }
+        // Route the error through the wire-error translator so the server's envelope
+        // (`code`, `message`, `doc_url`) is preserved and mapped to the matching
+        // AbloError subclass. Fall back to `exchange_failed` only when the body
+        // carried no recognizable error code.
+        const requestId = response.headers.get('x-request-id') ?? undefined;
+        throw hasWireCode(body)
+            ? translateHttpError(response.status, body, requestId)
+            : new AbloAuthenticationError(`apiKey exchange rejected (${response.status})`, { code: 'exchange_failed', httpStatus: response.status });
+    }
+    return parseCapabilityExchangeResponse(await response.json());
+}
+/**
+ * Mints an end-user session key (an `ek_` key) by calling
+ * `POST /auth/ephemeral-keys`, using your secret key as authorization. Your
+ * backend calls this to issue a session that a browser can present as its bearer
+ * credential; the server trusts the resulting key because a secret key minted it.
+ *
+ * This is a distinct endpoint from `/auth/capability`, which exchanges keys for
+ * agents and systems and cannot mint sessions for human users.
+ */
+export async function mintUserSessionKey(options) {
+    if (!options.apiKey) {
+        throw new AbloAuthenticationError('No API key found. Set ABLO_API_KEY in your environment or pass `apiKey` ' +
+            'to Ablo({ ... }) directly — user sessions are minted by your backend.', { code: 'apikey_missing' });
+    }
+    if (!options.baseUrl) {
+        throw new AbloAuthenticationError('baseUrl is required for user-session mint', { code: 'base_url_missing' });
+    }
+    const fetcher = options.fetch ?? fetch;
+    const url = `${options.baseUrl.replace(/\/+$/, '')}/auth/ephemeral-keys`;
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const controller = new AbortController();
+    const timer = setTimeout(() => { controller.abort(); }, timeoutMs);
+    let response;
+    try {
+        response = await fetcher(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${options.apiKey}`,
+            },
+            body: JSON.stringify({
+                user: { id: options.userId },
+                ...(options.organizationId ? { organizationId: options.organizationId } : {}),
+                // The public option is project-centric; map it to the flat wire keys the
+                // endpoint expects.
+                ...(options.schemaProject
+                    ? {
+                        schemaProjectId: options.schemaProject.projectId,
+                        schemaOwnerOrgId: options.schemaProject.organizationId,
+                    }
+                    : {}),
+                ...(options.syncGroups ? { syncGroups: options.syncGroups } : {}),
+                ttlSeconds: options.ttlSeconds,
+                ...(options.label ? { label: options.label } : {}),
+            }),
+            signal: controller.signal,
+        });
+    }
+    catch (err) {
+        throw new AbloAuthenticationError(`user-session mint failed: ${err instanceof Error ? err.message : String(err)}`, { code: 'exchange_network_error', cause: err });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (!response.ok) {
+        let body = null;
+        try {
+            body = await response.json();
+        }
+        catch {
+            // ignore — server returned non-JSON error
+        }
+        const requestId = response.headers.get('x-request-id') ?? undefined;
+        throw hasWireCode(body)
+            ? translateHttpError(response.status, body, requestId)
+            : new AbloAuthenticationError(`user-session mint rejected (${response.status})`, { code: 'exchange_failed', httpStatus: response.status });
+    }
+    return parseEphemeralKeyResponse(await response.json());
+}
+/**
+ * Resolves the caller's identity from an authenticated request by calling
+ * `GET /auth/identity`. This lets browser and session flows learn who the
+ * current user is without requiring the application to pass a user id up front —
+ * for example, to key local storage.
+ */
+export async function resolveIdentity(options) {
+    if (!options.baseUrl) {
+        throw new AbloAuthenticationError('baseUrl is required for identity resolve', {
+            code: 'base_url_missing',
+        });
+    }
+    const fetcher = options.fetch ?? fetch;
+    const url = `${options.baseUrl.replace(/\/+$/, '')}/auth/identity`;
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const controller = new AbortController();
+    const timer = setTimeout(() => { controller.abort(); }, timeoutMs);
+    let response;
+    try {
+        const headers = { Accept: 'application/json' };
+        if (options.authToken) {
+            headers.Authorization = `Bearer ${options.authToken}`;
+        }
+        response = await fetcher(url, {
+            method: 'GET',
+            headers,
+            signal: controller.signal,
+        });
+    }
+    catch (err) {
+        throw new AbloAuthenticationError(`identity resolve failed: ${err instanceof Error ? err.message : String(err)}`, { code: 'identity_network_error', cause: err });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (!response.ok) {
+        let body = null;
+        try {
+            body = await response.json();
+        }
+        catch {
+            // ignore non-JSON auth errors
+        }
+        // Translate the error envelope the same way `exchangeApiKey` does, so the
+        // server's precise auth diagnosis (for example `jwt_issuer_untrusted` with
+        // its full message) reaches the caller instead of collapsing every 401 to a
+        // generic `identity_resolve_failed`.
+        const requestId = response.headers.get('x-request-id') ?? undefined;
+        throw hasWireCode(body)
+            ? translateHttpError(response.status, body, requestId)
+            : new AbloAuthenticationError(`identity resolve rejected (${response.status})`, { code: 'identity_resolve_failed', httpStatus: response.status });
+    }
+    return parseIdentityResolveResponse(await response.json());
+}
+const DEFAULT_BUFFER_FLOOR_MS = 60_000;
+const DEFAULT_BUFFER_RATIO = 0.1;
+export function createRefreshScheduler(options) {
+    const now = options.now ?? Date.now;
+    const setTimer = options.setTimer ?? setTimeout;
+    const clearTimer = options.clearTimer ?? clearTimeout;
+    let expiresAtMs = options.initialExpiresAtMs;
+    let timer = null;
+    let inFlight = null;
+    let disposed = false;
+    // Attach the visibility listener only in a browser-like environment. A
+    // non-browser runtime has no `document`, so the default behaves correctly
+    // without an explicit opt-out.
+    const wantsVisibility = options.attachVisibilityListener ?? true;
+    const hasDocument = typeof document !== 'undefined';
+    const visibilityActive = wantsVisibility && hasDocument;
+    function bufferFor(currentExpiresAtMs) {
+        if (typeof options.bufferMs === 'number')
+            return options.bufferMs;
+        const ttl = currentExpiresAtMs - now();
+        return Math.max(DEFAULT_BUFFER_FLOOR_MS, Math.floor(ttl * DEFAULT_BUFFER_RATIO));
+    }
+    function clearTimerIfAny() {
+        if (timer !== null) {
+            clearTimer(timer);
+            timer = null;
+        }
+    }
+    function schedule() {
+        if (disposed)
+            return;
+        clearTimerIfAny();
+        const buffer = bufferFor(expiresAtMs);
+        const delay = Math.max(0, expiresAtMs - buffer - now());
+        timer = setTimer(() => {
+            void refreshNow().catch(() => {
+                // onError already fired inside refreshNow; swallow here so
+                // the timer callback doesn't surface as an unhandled rejection.
+            });
+        }, delay);
+    }
+    function refreshNow() {
+        if (disposed) {
+            return Promise.reject(new Error('refreshScheduler: disposed'));
+        }
+        if (inFlight)
+            return inFlight;
+        inFlight = (async () => {
+            try {
+                const result = await options.refresh();
+                if (disposed)
+                    return result;
+                expiresAtMs = result.expiresAtMs;
+                options.onRefreshed?.({ expiresAtMs });
+                schedule();
+                return result;
+            }
+            catch (err) {
+                const error = err instanceof Error ? err : new Error(String(err));
+                options.onError?.(error);
+                // Reschedule even on failure so the next window still triggers.
+                // The user's apiKey may have been temporarily unreachable.
+                if (!disposed)
+                    schedule();
+                throw error;
+            }
+            finally {
+                inFlight = null;
+            }
+        })();
+        return inFlight;
+    }
+    function onVisibilityChange() {
+        if (disposed)
+            return;
+        if (typeof document === 'undefined')
+            return;
+        if (document.visibilityState !== 'visible')
+            return;
+        const buffer = bufferFor(expiresAtMs);
+        if (expiresAtMs - now() <= buffer) {
+            void refreshNow().catch(() => {
+                // already routed through onError
+            });
+        }
+    }
+    if (visibilityActive) {
+        document.addEventListener('visibilitychange', onVisibilityChange);
+    }
+    schedule();
+    return {
+        refreshNow,
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            clearTimerIfAny();
+            if (visibilityActive) {
+                document.removeEventListener('visibilitychange', onVisibilityChange);
+            }
+        },
+        get expiresAtMs() {
+            return expiresAtMs;
+        },
+    };
+}

package/dist/{auth → transaction/auth}/schemas.d.ts

@@ -8,7 +8,7 @@ export declare const CapabilityExchangeResponseSchema: z.ZodObject<{
     scope: z.ZodObject<{
         organizationId: z.ZodString;
         syncGroups: z.ZodArray<z.ZodString>;
-        operations: z.ZodArray<z.ZodString>;
+        operations: z.ZodArray<z.ZodTemplateLiteral<`${string}.update` | `${string}.create` | `${string}.delete` | `${string}.read`>>;
         participantKind: z.ZodEnum<{
             user: "user";
             agent: "agent";

package/dist/{auth → transaction/auth}/schemas.js

@@ -1,6 +1,12 @@
 import { z } from 'zod';
+import { participantKindSchema } from '../coordination/schema.js';
+import { capabilityScopeSchema } from './capability.js';
 import { AbloAuthenticationError } from '../errors.js';
-const AuthParticipantKindSchema = z.enum(['user', 'agent', 'system']);
+// Not a second enum. The auth responses carry the same participant vocabulary
+// the coordination plane parses, so they validate against the same schema — a
+// kind the delta plane accepts must not throw here on an otherwise-valid
+// identity-resolve response.
+const AuthParticipantKindSchema = participantKindSchema;
 export const AuthTokenSchema = z.string().trim().min(1);
 export const CapabilityExchangeResponseSchema = z
     .object({
@@ -8,18 +14,12 @@ export const CapabilityExchangeResponseSchema = z
     token: AuthTokenSchema,
     expiresAt: z.string().min(1),
     organizationId: z.string().min(1),
-    scope: z
-        .object({
-        organizationId: z.string().min(1),
-        syncGroups: z.array(z.string()),
-        operations: z.array(z.string()),
-        participantKind: AuthParticipantKindSchema,
-        participantId: z.string().min(1),
-    })
-        .passthrough(),
+    // The grant the mint settled on, in the one shape the key row stores and
+    // the gates read — not a second description of it.
+    scope: capabilityScopeSchema.loose(),
     userMeta: z.record(z.string(), z.unknown()),
 })
-    .passthrough();
+    .loose();
 export const IdentityResolveResponseSchema = z
     .object({
     participantKind: AuthParticipantKindSchema,
@@ -35,7 +35,7 @@ export const IdentityResolveResponseSchema = z
     syncGroups: z.array(z.string()),
     userMeta: z.record(z.string(), z.unknown()),
 })
-    .passthrough();
+    .loose();
 /**
  * The response shape of `POST /auth/ephemeral-keys`, the endpoint that mints an
  * end-user session key (an `ek_` key). The shape is flat, with no nested scope
@@ -53,7 +53,7 @@ export const EphemeralKeyResponseSchema = z
     participantId: z.string().min(1),
     syncGroups: z.array(z.string()),
 })
-    .passthrough();
+    .loose();
 function formatIssues(error) {
     return error.issues
         .map((issue) => {

package/dist/{client → transaction/auth}/sessionMint.d.ts

@@ -1,5 +1,5 @@
 import type { SchemaRecord } from '../schema/schema.js';
-import type { AbloSession, CreateSessionParams } from './resourceTypes.js';
+import type { AbloSession, CreateSessionParams } from '../resources/httpResources.js';
 /**
  * The resolved control-plane details a mint needs: a secret key, a base URL,
  * and an optional `fetch`. When `fetch` is omitted, the auth helpers fall back
@@ -10,15 +10,15 @@ export interface MintSessionContext {
     readonly baseUrl: string;
     readonly fetch?: typeof fetch;
     /**
-     * Maps each schema key to its wire type name. Every public client supplies
-     * this; it stays optional only for isolated private-transport use. A
-     * capability is scoped by the lowercased type name the server checks, but
-     * `can` is keyed by schema key — so
+     * Each schema key mapped to its wire type name, from
+     * {@link modelWireNames} over the client's own schema. Required, and derived
+     * rather than assembled: `can` is keyed by schema key while a capability is
+     * scoped by the type name the server checks, so
      * `can: { documents: ['update'] }` on a model whose type name is overridden
-     * to `Document` must mint `document.update`, not `documents.update`, or the
-     * server denies the write with `capability_scope_denied`.
+     * to `Document` must mint `document.update`. A caller who leaves this out
+     * mints a grant the server denies on the first write.
      */
-    readonly modelTypenames?: Readonly<Record<string, string>>;
+    readonly modelTypenames: Readonly<Record<string, string>>;
 }
 /**
  * Mints a session token from an already-resolved secret key and base URL.

package/dist/{client → transaction/auth}/sessionMint.js

@@ -23,6 +23,7 @@
  * caller's responsibility.
  */
 import { exchangeApiKey, mintUserSessionKey } from '../auth/index.js';
+import { grantedOperations } from './capability.js';
 /**
  * Mints a session token from an already-resolved secret key and base URL.
  * Routes the `{ user }` or `{ agent }` request to the matching mint endpoint
@@ -58,13 +59,9 @@ export async function mintSession(params, ctx) {
             userMeta: params.userMeta ?? { id: res.participantId },
         };
     }
-    const operations = Object.entries(params.can).flatMap(([model, ops]) => {
-        // Translate the schema key the developer used in `can` into the wire type
-        // name the server checks — see `modelTypenames` above. The key fallback is
-        // private transport tolerance; every public client supplies the schema map.
-        const ns = ctx.modelTypenames?.[model] ?? model;
-        return (ops ?? []).map((op) => `${ns.toLowerCase()}.${op}`);
-    });
+    // One translation from the declared grant to the wire allowlist, shared with
+    // every other door that mints — see `auth/capability.ts`.
+    const operations = grantedOperations(params.can, ctx.modelTypenames);
     const res = await exchangeApiKey({
         apiKey,
         baseUrl,

package/dist/transaction/coordination/awaitClaimGrant.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Waits for a queued claim to reach the head of the line — the client side of
+ * the fair-queue handover. When a claim is contended, the server puts it in a
+ * queue and replies that it is queued (HTTP 202 on `/v1/claims`, or a
+ * `claim_queued` frame over the WebSocket). The grant is delivered later, when
+ * the claim reaches the head, as a `claim_granted` frame. This resolves once
+ * that frame arrives for the given `claimId`, so the caller's `claim` promise
+ * stays pending — event-driven, with no polling — until it is actually the
+ * caller's turn. It rejects if the claim is lost (`claim_lost`: taken away by a
+ * TTL lapse on disconnect, or revoked) or if an optional timeout elapses.
+ *
+ * It needs only a minimal `{ subscribe }` transport, so it can be tested
+ * against a fake; the duplex `WsTransport` satisfies it.
+ */
+import { type Logger } from '../logger.js';
+export interface GrantTransport {
+    subscribe(event: 'claim_acquired' | 'claim_granted' | 'claim_lost' | 'claim_queued' | 'claim_rejected', handler: (payload: Record<string, unknown>) => void): () => void;
+}
+export interface ClaimGrantInfo {
+    /**
+     * True when the grant arrived as `claim_granted` — the target was held when
+     * the caller asked, and the caller waited in the FIFO line behind the holder.
+     * False for the immediate `claim_acquired`, where the target was free.
+     *
+     * Callers read this to know the row may have changed while they queued. Claim
+     * visibility is scoped to the entity, so a broad, organization-wide
+     * subscription receives no presence or claim fan-out, and the local
+     * coordination snapshot cannot be trusted to tell whether the caller waited.
+     * The grant frame itself is the authoritative signal.
+     */
+    readonly waited: boolean;
+    /**
+     * The fencing token the server minted for this grant (Option B), read off the
+     * grant frame — the authoritative source, since the token is server-stamped.
+     * `undefined` when the server does not fence (no minter wired).
+     */
+    readonly fenceToken?: number;
+}
+export declare function awaitClaimGrant(transport: GrantTransport, claimId: string, options?: {
+    timeoutMs?: number;
+    /**
+     * Backpressure: reject instead of waiting if, when we join the line, the
+     * server reports `position >= maxQueueDepth` (i.e. that many claims are
+     * already ahead of us). Omit to wait however deep the queue is.
+     */
+    maxQueueDepth?: number;
+    /** Where grant transitions are logged. Defaults to silent. */
+    logger?: Logger;
+}): Promise<ClaimGrantInfo>;

package/dist/transaction/coordination/awaitClaimGrant.js

@@ -0,0 +1,112 @@
+/**
+ * Waits for a queued claim to reach the head of the line — the client side of
+ * the fair-queue handover. When a claim is contended, the server puts it in a
+ * queue and replies that it is queued (HTTP 202 on `/v1/claims`, or a
+ * `claim_queued` frame over the WebSocket). The grant is delivered later, when
+ * the claim reaches the head, as a `claim_granted` frame. This resolves once
+ * that frame arrives for the given `claimId`, so the caller's `claim` promise
+ * stays pending — event-driven, with no polling — until it is actually the
+ * caller's turn. It rejects if the claim is lost (`claim_lost`: taken away by a
+ * TTL lapse on disconnect, or revoked) or if an optional timeout elapses.
+ *
+ * It needs only a minimal `{ subscribe }` transport, so it can be tested
+ * against a fake; the duplex `WsTransport` satisfies it.
+ */
+import { AbloClaimedError, formatClaimedErrorMessage, claimTargetLabel, } from '../errors.js';
+import { modelTarget } from './locator.js';
+import { noopLogger } from '../logger.js';
+/** Read the server-stamped fencing token off a grant frame, if present. */
+function readFenceToken(p) {
+    return typeof p.fenceToken === 'number' ? p.fenceToken : undefined;
+}
+export function awaitClaimGrant(transport, claimId, options) {
+    const logger = options?.logger ?? noopLogger;
+    return new Promise((resolve, reject) => {
+        const unsubs = [];
+        let timer;
+        const settle = (fn) => {
+            if (timer)
+                clearTimeout(timer);
+            for (const u of unsubs)
+                u();
+            fn();
+        };
+        // The target was free → `claim_acquired` (immediate); it was contended,
+        // we waited in line, and reached the head → `claim_granted`. Either frame
+        // means the lease is now ours; `waited` records which path it was.
+        unsubs.push(transport.subscribe('claim_acquired', (p) => {
+            if (p?.claimId === claimId) {
+                logger.debug(`claim: acquired ${claimId} (target was free)`);
+                const fenceToken = readFenceToken(p);
+                settle(() => {
+                    resolve({ waited: false, ...(fenceToken !== undefined ? { fenceToken } : {}) });
+                });
+            }
+        }));
+        unsubs.push(transport.subscribe('claim_granted', (p) => {
+            if (p?.claimId === claimId) {
+                // Promoted to the head of the line — the creator's "it's the agent's
+                // turn now" moment after waiting behind a holder.
+                logger.info(`claim: granted ${claimId} — your turn (waited in queue)`);
+                const fenceToken = readFenceToken(p);
+                settle(() => {
+                    resolve({ waited: true, ...(fenceToken !== undefined ? { fenceToken } : {}) });
+                });
+            }
+        }));
+        if (options?.maxQueueDepth !== undefined) {
+            const max = options.maxQueueDepth;
+            unsubs.push(transport.subscribe('claim_queued', (p) => {
+                if (p?.claimId !== claimId)
+                    return;
+                const position = typeof p.position === 'number' ? p.position : 0;
+                if (position >= max) {
+                    settle(() => {
+                        reject(new AbloClaimedError(`Claim queue for ${claimId} is ${position} deep (max ${max}).`, { code: 'queue_too_deep' }));
+                    });
+                }
+            }));
+        }
+        unsubs.push(transport.subscribe('claim_rejected', (p) => {
+            const rejection = p;
+            if (rejection.claimId !== claimId)
+                return;
+            const target = rejection.target
+                ? claimTargetLabel({
+                    ...modelTarget(rejection.target),
+                    field: rejection.target.field,
+                })
+                : claimId;
+            settle(() => {
+                reject(new AbloClaimedError(formatClaimedErrorMessage({
+                    targetLabel: target,
+                    heldBy: rejection.heldBy,
+                    claim: rejection.heldByClaim,
+                    policyReason: rejection.policyReason,
+                    fallback: `Claim rejected for ${target}.`,
+                }), {
+                    code: rejection.reason === 'conflict'
+                        ? 'claim_conflict'
+                        : 'claim_lease_unavailable',
+                    claims: rejection.heldByClaim ? [rejection.heldByClaim] : undefined,
+                }));
+            });
+        }));
+        unsubs.push(transport.subscribe('claim_lost', (p) => {
+            if (p?.claimId === claimId) {
+                settle(() => {
+                    reject(new AbloClaimedError(`Claim lost while queued for ${claimId}.`, {
+                        code: 'claim_lost',
+                    }));
+                });
+            }
+        }));
+        if (options?.timeoutMs && options.timeoutMs > 0) {
+            timer = setTimeout(() => {
+                settle(() => {
+                    reject(new AbloClaimedError(`Timed out waiting for the queue grant on claim ${claimId}.`, { code: 'grant_timeout' }));
+                });
+            }, options.timeoutMs);
+        }
+    });
+}

package/dist/transaction/coordination/claimMeta.d.ts

@@ -0,0 +1,49 @@
+/**
+ * A claim's application metadata, crossing between the wire and the shape the
+ * program declared for it.
+ *
+ * The wire contract for `meta` is deliberately permissive — `targetRefSchema`
+ * parses it as `z.record(z.string(), z.unknown())` and always will, because a
+ * newer peer must be able to send a field this build has never heard of and
+ * still be understood. The read surface is the opposite: `Register`'s
+ * `ClaimMeta` slot names the one shape this program's claims carry, so
+ * `claim.state({ id })?.target.meta` reads without a guard.
+ *
+ * Those two facts meet here, and only here, in both directions. A decode calls
+ * {@link declaredMeta} on its way from a parsed record to a public `Claim`; the
+ * locator projection calls {@link wireMeta} on the way back out, where a
+ * caller's declared value is put on the socket or in the HTTP body. Between
+ * them they are the one place the SDK takes the caller's word for a shape it
+ * did not check — written down once, with the reason, instead of being asserted
+ * at each crossing.
+ *
+ * The two directions are not symmetric in cost. Losing the declared shape on
+ * the way out is harmless, because the wire has always accepted any record;
+ * gaining it on the way in is the promise the read surface makes, so
+ * `declaredMeta` is the one to audit when a claim reads back a shape its holder
+ * never wrote.
+ */
+import type { ResolveClaimMeta } from '../types/global.js';
+/**
+ * Read a parsed `meta` as the declared shape. Call it only where a decode hands
+ * a wire value to a public claim, and only for a value already known present —
+ * the absent case is an omitted member, not a declared-shaped `undefined`.
+ *
+ * The exported names are `declaredMeta` and `wireMeta` rather than a `claimMeta`
+ * pair because two claim surfaces already read a caller's `meta` back off the
+ * options it passed in, and spell that local reader `claimMeta`.
+ */
+export declare function declaredMeta(raw: unknown): ResolveClaimMeta;
+/**
+ * Write a declared `meta` as the permissive record the wire carries. Every path
+ * from a caller's target to a frame or request body goes through `subTarget`,
+ * so this has exactly one caller — widening it is how the declared shape stops
+ * being a compile error at the edge of the protocol instead of stopping there.
+ *
+ * The parameter is `unknown` rather than {@link ResolveClaimMeta} on purpose: a
+ * program may register an `interface` for its claim metadata, and an interface
+ * carries no implicit index signature, so a directly-typed parameter would make
+ * the conversion itself unrepresentable at the one site that needs it. Widening
+ * the input is what keeps the assertion single.
+ */
+export declare function wireMeta(meta: unknown): Record<string, unknown>;