@abloatai/ablo 0.34.1 → 0.35.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, claimHeartbeatReplySchema, claimListResponseSchema, } 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, 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 } from '../coordination/schema.js';
+import { subTarget, streamTarget } 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');
@@ -698,13 +729,8 @@ 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',
-        });
-        return {
-            active: body.claims ?? [],
-            queue: body.queue ?? [],
-        };
+        const body = await requestJson(`/v1/claims${suffix ? `?${suffix}` : ''}`, { method: 'GET' }, claimListResponseSchema);
+        return { active: body.claims, queue: body.queue };
     }
     async function applyClaimedPolicy(target, options, defaultPolicy = 'return') {
         const policy = options?.ifClaimed ?? defaultPolicy;
@@ -761,14 +787,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 +825,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 +910,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 +929,56 @@ 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,
-                }),
-            });
-            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' });
+            // 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);
+            // 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' });
             }
-            // `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;
+            const { id, fenceToken } = body.claim;
             return fenceToken !== undefined ? { id, fenceToken } : { 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,7 +992,7 @@ 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) {
@@ -952,7 +1003,7 @@ export function createHttpTransport(options) {
                 model: name,
                 id: params.id,
                 ...(params.field ? { field: params.field } : {}),
-                reason: params.description ?? 'editing',
+                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`.
@@ -971,12 +1022,12 @@ export function createHttpTransport(options) {
                 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
                 ? startClaimHeartbeatLoop({
                     beat: () => heartbeat(),
-                    intervalMs: heartbeatCadenceMs(params.ttl !== undefined ? toMs(params.ttl) : 60_000, params.heartbeat),
+                    intervalMs: heartbeatCadenceMs(params.ttl !== undefined ? toMs(params.ttl) : DEFAULT_CLAIM_TTL_MS, params.heartbeat),
                     ...(params.onHeartbeatLost ? { onLost: params.onHeartbeatLost } : {}),
                 })
                 : undefined;
@@ -984,20 +1035,22 @@ export function createHttpTransport(options) {
                 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,7 +1060,7 @@ 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(params.field)}` : ''}`, { method: 'GET' }, claimListResponseSchema);
         const claim = Object.assign(claimImpl, {
             release: releaseClaim,
             state: async (params) => {
@@ -1023,7 +1076,7 @@ export function createHttpTransport(options) {
                 };
             },
             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 +1189,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 {
@@ -1158,11 +1234,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 } : {}),
                 });
             },
         },

package/dist/{sync/NetworkProbe.d.ts → transaction/transport/networkProbe.d.ts}

@@ -23,11 +23,12 @@
  */
 import { z } from 'zod';
 import { type AuthTokenGetter } from '../auth/credentialSource.js';
+import { type Logger } from '../logger.js';
 /**
  * The complete set of probe outcomes. Each value carries both reachability and
- * credential state, so {@link ConnectionManager} can branch on one exhaustive
+ * credential state, so the connection state machine can branch on one exhaustive
  * discriminant instead of piecing the situation together from several booleans.
- * It mirrors the {@link RecoveryClass} taxonomy at the connectivity layer.
+ * It mirrors the `RecoveryClass` taxonomy at the connectivity layer.
  */
 export declare const PROBE_OUTCOMES: readonly ["reachable", "unreachable", "session_expired", "credential_stale", "auth_blocked"];
 /** Zod enum derived from {@link PROBE_OUTCOMES}. */
@@ -69,11 +70,13 @@ export interface NetworkProbeOptions {
     getAuthToken?: AuthTokenGetter;
     /** Compatibility fallback for callers with a copied token string. */
     authToken?: string | null;
+    /** Where probe outcomes are logged. Defaults to silent. */
+    logger?: Logger;
 }
 /**
  * Probes the sync server with a lightweight HEAD request, returning both
- * reachability and session status in a single call so {@link ConnectionManager}
- * can pick the right state transition without guessing.
+ * reachability and session status in a single call so the connection state
+ * machine can pick the right transition without guessing.
  *
  * @param input The sync-server base URL (an HTTP or WS scheme is accepted), or
  *              an options bag. A bare string is also accepted.

package/dist/{sync/NetworkProbe.js → transaction/transport/networkProbe.js}

@@ -22,15 +22,15 @@
  * @see https://developer.mozilla.org/en-US/docs/Web/API/Navigator/onLine
  */
 import { z } from 'zod';
-import { getContext } from '../context.js';
 import { classifyRecovery } from '../errors.js';
 import { withAuthHeaders } from '../auth/credentialSource.js';
-import { ABLO_DEFAULT_BASE_URL } from '../client/hostedEndpoints.js';
+import { ABLO_DEFAULT_BASE_URL } from '../auth/hostedEndpoints.js';
+import { noopLogger } from '../logger.js';
 /**
  * The complete set of probe outcomes. Each value carries both reachability and
- * credential state, so {@link ConnectionManager} can branch on one exhaustive
+ * credential state, so the connection state machine can branch on one exhaustive
  * discriminant instead of piecing the situation together from several booleans.
- * It mirrors the {@link RecoveryClass} taxonomy at the connectivity layer.
+ * It mirrors the `RecoveryClass` taxonomy at the connectivity layer.
  */
 export const PROBE_OUTCOMES = [
     /** Server reachable and the access credential is currently valid. */
@@ -72,8 +72,8 @@ function resolveProbeUrl(baseUrl) {
 }
 /**
  * Probes the sync server with a lightweight HEAD request, returning both
- * reachability and session status in a single call so {@link ConnectionManager}
- * can pick the right state transition without guessing.
+ * reachability and session status in a single call so the connection state
+ * machine can pick the right transition without guessing.
  *
  * @param input The sync-server base URL (an HTTP or WS scheme is accepted), or
  *              an options bag. A bare string is also accepted.
@@ -82,6 +82,7 @@ export async function probeNetwork(input) {
     const baseUrl = typeof input === 'string' ? input : input?.baseUrl;
     const getAuthToken = typeof input === 'string' ? undefined : input?.getAuthToken;
     const authToken = typeof input === 'string' ? undefined : input?.authToken;
+    const logger = (typeof input === 'string' ? undefined : input?.logger) ?? noopLogger;
     const url = resolveProbeUrl(baseUrl);
     // Fast-fail: if navigator.onLine is false, skip the probe entirely. This is
     // the one case where navigator.onLine is reliable (MDN: "false means
@@ -115,14 +116,14 @@ export async function probeNetwork(input) {
             const recovery = classifyRecovery(authFailure);
             switch (recovery) {
                 case 'session_expiry':
-                    getContext().logger.info('[NetworkProbe] Server reachable, login expired', {
+                    logger.info('[NetworkProbe] Server reachable, login expired', {
                         status: response.status,
                         code: authFailure,
                         latencyMs,
                     });
                     return { outcome: 'session_expired', latencyMs };
                 case 'access_credential_expiry':
-                    getContext().logger.info('[NetworkProbe] Server reachable, access key stale — will re-mint', {
+                    logger.info('[NetworkProbe] Server reachable, access key stale — will re-mint', {
                         status: response.status,
                         code: authFailure,
                         latencyMs,
@@ -136,7 +137,7 @@ export async function probeNetwork(input) {
                     // Re-authenticating re-mints the same rejected credential and
                     // retrying will not help, so stop rather than reconnect-loop or sign
                     // the user out.
-                    getContext().logger.debug('[NetworkProbe] Reachable but auth-blocked (non-retryable, non-expiry)', {
+                    logger.debug('[NetworkProbe] Reachable but auth-blocked (non-retryable, non-expiry)', {
                         status: response.status,
                         code: authFailure,
                         recovery,
@@ -168,7 +169,7 @@ export async function probeNetwork(input) {
             // counter falls through to `auth_blocked` (stop) — still never a spurious
             // logout. The invariant holds: null is the only terminal path, never a
             // bare 401.
-            getContext().logger.info('[NetworkProbe] Server reachable, bare 401 — re-mint (not sign-out)', {
+            logger.info('[NetworkProbe] Server reachable, bare 401 — re-mint (not sign-out)', {
                 latencyMs,
             });
             return { outcome: 'credential_stale', latencyMs };
@@ -178,14 +179,14 @@ export async function probeNetwork(input) {
         // expected 204; log a warning so misconfigurations surface instead of
         // silently passing.
         if (response.status < 200 || response.status >= 300) {
-            getContext().logger.debug('[NetworkProbe] Unexpected probe response', {
+            logger.debug('[NetworkProbe] Unexpected probe response', {
                 status: response.status,
                 url,
                 latencyMs,
             });
         }
         else {
-            getContext().logger.debug('[NetworkProbe] Server reachable, credential valid', {
+            logger.debug('[NetworkProbe] Server reachable, credential valid', {
                 status: response.status,
                 latencyMs,
             });
@@ -195,7 +196,7 @@ export async function probeNetwork(input) {
     catch (error) {
         clearTimeout(timeout);
         const isAbort = error instanceof DOMException && error.name === 'AbortError';
-        getContext().logger.info('[NetworkProbe] Probe failed', {
+        logger.info('[NetworkProbe] Probe failed', {
             reason: isAbort ? 'timeout' : error.message,
         });
         return { outcome: 'unreachable', latencyMs: null };