@axonflow/sdk 9.1.0 → 9.3.0

package/dist/esm/client.js

@@ -1,9 +1,51 @@
 import { VERSION } from './version.js';
 import { maybeSendHeartbeat, flushHeartbeat } from './heartbeat.js';
 import { sendTelemetryPingNow } from './telemetry.js';
+import { buildEnvelope, evaluateEnvelope } from './authzen.js';
 import { AuthenticationError, APIError, PolicyViolationError, ConfigurationError, ConnectorError, PlanExecutionError, RateLimitError, VersionConflictError, IdempotencyKeyMismatchError, ObligationNotFulfillableError, } from './errors.js';
 import { CONTENT_TYPE_TEXT, DECIDE_PATH, OBLIGATION_REDACT_PII, PHASE_REQUEST, REQUEST_REDACTION_PATH, VERDICT_ALLOW, endpointPathMatches, stripUndefined, } from './pep.js';
 import { generateRequestId, debugLog } from './utils/helpers.js';
+import { HEADER_USER_TOKEN, applyReadIdentity, readScopeErrorFor, readScopeOf, refuseVacuousScopedPage, stripCredentialsOffOrigin, } from './read-identity.js';
+/**
+ * State backing each client's {@link AxonFlow.heartbeatReady}, keyed by the
+ * client's `heartbeatRoot`.
+ *
+ * KEYED ON THE ROOT, NOT ON `this`, AND THAT IS A BUG FIX RATHER THAN A
+ * REFINEMENT. `asUser()` derives with `Object.assign(derived, this)`, which
+ * copies the `heartbeatReady` PROMISE onto the derived client but cannot copy a
+ * WeakMap entry keyed on the parent. Keyed on `this`, a derived client's first
+ * request looked up nothing, resolved nothing, and `await derived.heartbeatReady`
+ * hung forever — while the README told callers to await exactly that after
+ * their first call. A documented deadlock.
+ *
+ * `heartbeatRoot` is a plain own property, so `Object.assign` copies it and every
+ * derived client reaches the same entry. That is also the correct semantics: the
+ * heartbeat gate is process-global, there is ONE ping, and the promise copied
+ * onto the derived client is the same object — so whichever client sends first
+ * settles it for all of them.
+ *
+ * It is a non-function property, which keeps the `read-identity.test.ts`
+ * invariant ("a fresh instance has no own-property functions") green — that test
+ * is what caught the first attempt at storing a resolver on the instance.
+ */
+const heartbeatReadyState = new WeakMap();
+/**
+ * Redirect statuses the identity-aware follower handles, and the hop bound.
+ * Mirrors what `fetch` would have done itself, minus the header leak.
+ */
+const IDENTITY_REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+const MAX_IDENTITY_REDIRECTS = 10;
+/** Whether `url` is the same origin as the configured endpoint. */
+function sameOriginAs(url, endpoint) {
+    if (!endpoint)
+        return false;
+    try {
+        return url.origin === new URL(endpoint).origin;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Extract a typed IdempotencyKeyMismatchError from an APIError with HTTP 409 and
  * `error.code === "IDEMPOTENCY_KEY_MISMATCH"` in the response body. Returns null if
@@ -98,6 +140,14 @@ export class AxonFlow {
         // mode-based default-suppression rule are gone.
         this.interceptors = [];
         this.sessionCookie = null;
+        /**
+         * Identity of the client that owns this heartbeat promise.
+         *
+         * `this` on an original client; copied by `Object.assign` onto every client
+         * derived from it with `asUser()`, so a derived client settles the SAME
+         * promise rather than one nothing can reach. See {@link heartbeatReadyState}.
+         */
+        this.heartbeatRoot = this;
         // Configuration validation
         if (config.clientSecret && !config.clientId) {
             throw new ConfigurationError('clientSecret requires clientId to be set. ' +
@@ -118,12 +168,49 @@ export class AxonFlow {
         // always pass an explicit endpoint. The previous default
         // (staging-eu.getaxonflow.com) was decommissioned 2026-04-09.
         const endpoint = config.endpoint ?? 'http://localhost:8080';
+        // THE `cache` OPTION IS REFUSED, BECAUSE IT NEVER DID ANYTHING
+        // (sdk-typescript#267, axonflow-enterprise#3682 item 4).
+        //
+        // It was accepted, normalised into `this.config`, and read by NO request
+        // path. So a caller passing `{ enabled: true, ttl: 60000 }` was making a
+        // cost and latency assumption the SDK silently did not honour — and the
+        // default resolved to `enabled: true`, so every client reported caching ON
+        // and got none.
+        //
+        // Refusing beats implementing. The four sibling SDKs all shipped a fix this
+        // week for the SAME defect in their caches: a client derived with `asUser`
+        // shared the parent's cache, and the key carried the write-path body token
+        // but NOT the identity the request presents, so two derived clients asking
+        // one question hashed to one entry and the second caller was served the
+        // first's governed response. Adding a fifth instance of that shape, to
+        // close a checklist item, on the one SDK that has no cache at all, is
+        // taking on the exact risk the others just paid to remove. If a cache is
+        // ever wanted here it gets built deliberately, with the identity in the key
+        // from the first commit.
+        //
+        // ONLY AN EXPLICIT `cache` THROWS. A blanket construction-time throw would
+        // break every existing application, including the overwhelming majority
+        // that never asked for a cache and merely accepted the default — which,
+        // because of that `!== false`, was every one of them. The distinction is
+        // the difference between a targeted, informative error and a breaking
+        // change for everyone.
+        if (config.cache !== undefined) {
+            throw new ConfigurationError('The `cache` option is not supported and has never had any effect: it was accepted ' +
+                'and normalised but read by no request path, so responses were never cached. It is ' +
+                'now refused rather than silently ignored, so the assumption is corrected at the ' +
+                'call site instead of at runtime. Remove the option. If you need caching, cache at ' +
+                'your own call site, where you control the key — note that any cache in front of ' +
+                'this SDK MUST include the effective user identity in its key, or a client derived ' +
+                'with asUser() can be served another identity\u2019s governed response. See ' +
+                'https://github.com/getaxonflow/axonflow-sdk-typescript/issues/267');
+        }
         // Credentials check: OAuth2-style (clientId/clientSecret)
         const hasCredentials = !!(config.clientId && config.clientSecret);
         // Set configuration
         this.config = {
             clientId: config.clientId,
             clientSecret: config.clientSecret,
+            userToken: config.userToken,
             endpoint,
             mode: config.mode ?? 'production',
             tenant: config.tenant ?? '',
@@ -135,10 +222,6 @@ export class AxonFlow {
                 maxAttempts: config.retry?.maxAttempts ?? 3,
                 delay: config.retry?.delay ?? 1000,
             },
-            cache: {
-                enabled: config.cache?.enabled !== false,
-                ttl: config.cache?.ttl ?? 60000,
-            },
         };
         // Interceptors removed in v3.0.0 (deprecated wrapOpenAIClient/wrapAnthropicClient)
         this.interceptors = [];
@@ -151,21 +234,38 @@ export class AxonFlow {
                 authMethod,
             });
         }
-        // Heartbeat gate: at most one anonymous ping per environment per
-        // 7 days, gated by SDK activity. Constructor kicks off the gate AND
-        // chains the in-flight delivery Promise so `heartbeatReady` resolves
-        // only once the POST has settled — callers in short-lived processes
-        // (CLI, Lambda boot) can `await client.heartbeatReady` to guarantee
-        // delivery before exit. Subsequent gate runs happen async via
-        // _preRequestHook on every public HTTP request site. See
-        // src/heartbeat.ts.
-        this.heartbeatReady = (async () => {
-            await this._preRequestHook();
-            const inFlight = flushHeartbeat();
-            if (inFlight) {
-                await inFlight;
-            }
-        })();
+        // NO HEARTBEAT HERE ANY MORE (axonflow-enterprise#3682). The gate is
+        // consulted on this client's FIRST OUTBOUND REQUEST instead, in
+        // `_preRequestHook`, which every request already passes through.
+        //
+        // Why: every framework adapter takes a client, so an adapter cannot exist
+        // until this constructor has returned. Pinging here meant an adapter
+        // registering from its own constructor could never reach the first ping,
+        // and the 7-day stamp then suppressed the next one for a week — so a
+        // short-lived process using an adapter reported it never. See
+        // `registerAdapter` in telemetry.ts.
+        //
+        // A client that is constructed and never used no longer pings. That is
+        // deliberate and disclosed: a heartbeat is a claim about usage.
+        //
+        // `heartbeatReady` is now settled by the first gate run rather than by a
+        // constructor ping — see its docstring; it stays PENDING for a client that
+        // never makes a request, which is the honest answer for "has the heartbeat
+        // finished" when there was none.
+        this.heartbeatReady = new Promise(resolve => {
+            // The resolver lives in a module-level WeakMap, NOT on the instance.
+            //
+            // `asUser()` derives a client with `Object.create`, so an own-property
+            // FUNCTION would not be shared the way a prototype method is — which is
+            // exactly the invariant `read-identity.test.ts` pins with "a fresh
+            // instance has no own-property functions". Storing the resolver as a
+            // field broke that test, and the test was right: this is the mechanism
+            // that keeps every request-issuing member reachable on a derived client.
+            //
+            // A WeakMap also means the entry disappears with the client rather than
+            // pinning it alive.
+            heartbeatReadyState.set(this, { resolve, settled: false });
+        });
     }
     /**
      * Single hook invoked at the start of every public HTTP request path
@@ -189,6 +289,25 @@ export class AxonFlow {
             endpoint: this.config.endpoint,
             debug: this.config.debug,
         }));
+        // Settle `heartbeatReady` once the FIRST gate run has finished and any
+        // delivery it started has settled. Guarded to one call: this hook runs on
+        // every request, and re-resolving is harmless but chaining flushHeartbeat
+        // on every request would not be.
+        const state = heartbeatReadyState.get(this.heartbeatRoot);
+        if (state && !state.settled) {
+            state.settled = true;
+            // AWAITED, not fire-and-forget. `heartbeatReady` exists so a short-lived
+            // process can `await` it and then exit without truncating the POST, so
+            // resolving before the in-flight delivery settles would make the promise
+            // a lie — it would resolve, the caller would `process.exit(0)`, and the
+            // ping would be lost. `telemetry-adapter-registry.test.ts` asserts the
+            // checkpoint actually received the POST at the moment this resolves.
+            const inFlight = flushHeartbeat();
+            if (inFlight) {
+                await inFlight;
+            }
+            state.resolve();
+        }
     }
     /**
      * Single HTTP wrapper used by every public-API request path. Schedules
@@ -199,9 +318,71 @@ export class AxonFlow {
      * itself (sendTelemetryPingNow / detectPlatformVersion). Those use raw
      * `fetch` to avoid recursive heartbeat triggering.
      */
-    async _fetch(input, init) {
+    async _fetch(input, init, identity) {
         void this._preRequestHook();
-        return fetch(input, init);
+        // The SDK's ONE identity site. Every request goes through here, and the
+        // platform likewise reads X-User-Token once, in the middleware in front of
+        // every proxied route rather than per route — so a per-method sprinkle
+        // would be a second copy of a decision made in one place on both sides.
+        //
+        // `identity === undefined` means "this call said nothing", so the
+        // client-wide value applies. A string — INCLUDING an empty one — is a
+        // deliberate per-call choice and must not fall back, because
+        // "unidentified" is a state the platform treats as distinct.
+        const token = identity === undefined ? this.config.userToken : identity;
+        // The header bag is copied and MUTATED as a plain record, keeping the shape
+        // every other caller and test observes on `fetch`. A `Headers` instance
+        // here would work on the wire and change what every existing assertion
+        // sees, which is a much larger change than an identity fix should be.
+        const headers = {
+            ...(init?.headers ?? {}),
+        };
+        let url = new URL(typeof input === 'string' ? input : input.toString());
+        applyReadIdentity(headers, url, this.config.endpoint, token ?? undefined);
+        if (!(HEADER_USER_TOKEN in headers)) {
+            // No credential in flight, so `fetch` keeps its own redirect behaviour
+            // rather than acquiring a second, subtly different implementation.
+            return fetch(input, init ? { ...init, headers } : { headers });
+        }
+        // An identity is attached, so redirects are followed BY HAND.
+        //
+        // The fetch spec strips Authorization on a cross-origin redirect and its
+        // list is fixed; X-User-Token is not on it. Measured on Node 25: the
+        // redirect target received `authorization: undefined` and
+        // `x-user-token: SENTINEL` — the per-user credential outliving the tenant
+        // one, on exactly the hop where the caller never named the host. Following
+        // by hand re-runs applyReadIdentity per hop, so the identity is dropped the
+        // moment the origin changes; the redirect itself is still followed, and the
+        // scoped read that lands unscoped then REFUSES visibly rather than quietly
+        // answering nothing.
+        let request = { ...init, headers, redirect: 'manual' };
+        for (let hop = 0; hop <= MAX_IDENTITY_REDIRECTS; hop++) {
+            const response = await fetch(url, request);
+            const location = response.headers.get('location');
+            if (!IDENTITY_REDIRECT_STATUSES.has(response.status) || !location) {
+                return response;
+            }
+            url = new URL(location, url);
+            const nextHeaders = { ...headers };
+            // EVERY credential is dropped off-origin, not just the identity.
+            // `fetch`'s own follower strips Authorization on a cross-origin hop; the
+            // moment this code follows by hand that stops happening and becomes this
+            // code's job. Dropping only the new header would make setting `userToken`
+            // leak `clientSecret` to a host the caller never named — a fix for one
+            // credential that exports another.
+            if (!sameOriginAs(url, this.config.endpoint)) {
+                stripCredentialsOffOrigin(nextHeaders);
+            }
+            applyReadIdentity(nextHeaders, url, this.config.endpoint, token ?? undefined);
+            // 303, and 301/302 on a non-GET, become GET without a body per the spec.
+            const method = (init?.method ?? 'GET').toUpperCase();
+            const becomesGet = response.status === 303 ||
+                ((response.status === 301 || response.status === 302) && method === 'POST');
+            request = becomesGet
+                ? { ...init, method: 'GET', body: undefined, headers: nextHeaders, redirect: 'manual' }
+                : { ...init, headers: nextHeaders, redirect: 'manual' };
+        }
+        throw new Error(`stopped after ${MAX_IDENTITY_REDIRECTS} redirects`);
     }
     /**
      * Get authentication headers based on configured credentials.
@@ -2133,11 +2314,56 @@ export class AxonFlow {
      * }
      * ```
      */
-    async explainDecision(decisionId) {
+    /**
+     * A client identical to this one but presenting `userToken`.
+     *
+     * The shape to reach for when one process acts on behalf of several people —
+     * a gateway, a bot. Unlike the per-call `{ userToken }` option, which only
+     * the read methods accept, this reaches EVERY method: there is no carve-out
+     * to remember and no path on which the identity silently widens back to the
+     * process's own.
+     *
+     * ```typescript
+     * const forAlice = client.asUser(aliceToken);
+     * const rows = await forAlice.listDecisions();
+     * ```
+     *
+     * The returned client shares this one's interceptors and session cookie —
+     * it is a view, not a new connection pool — so deriving one per request is
+     * cheap.
+     *
+     * It shares no CACHE, because this SDK has none: the `cache` option was
+     * inert and is now refused (sdk-typescript#267). That absence is why this
+     * SDK was never exposed to the cross-user response leak the other four
+     * fixed — there is no shared entry to serve to the wrong identity. It is an
+     * absence of the mechanism, not a defence, which is exactly why any cache
+     * built here later must be identity-keyed from the first commit. Only the identity differs; this client is not modified.
+     * The session cookie is copied by value, so a `loginToPortal` on either after
+     * the derivation is invisible to the other; derive after logging in if the
+     * derived client needs the portal plane, which authenticates with the cookie
+     * rather than with this identity.
+     *
+     * An empty token returns a client presenting no identity at all, which on an
+     * enterprise stack reads nothing (see `ReadScope.None`).
+     */
+    asUser(userToken) {
+        const derived = Object.create(Object.getPrototypeOf(this));
+        Object.assign(derived, this);
+        // `config` is replaced rather than mutated, so the derivation cannot reach
+        // back into the client it came from — the failure that would make asUser
+        // silently change the ORIGINAL caller's identity.
+        const config = this.config;
+        derived.config = {
+            ...config,
+            userToken: (userToken ?? '').trim() || undefined,
+        };
+        return derived;
+    }
+    async explainDecision(decisionId, options) {
         if (!decisionId) {
             throw new Error('decisionId is required');
         }
-        const response = await this.orchestratorRequest('GET', `/api/v1/decisions/${encodeURIComponent(decisionId)}/explain`);
+        const response = await this.orchestratorRequest('GET', `/api/v1/decisions/${encodeURIComponent(decisionId)}/explain`, undefined, { resource: 'decision', identifier: decisionId, userToken: options?.userToken });
         return this.parseDecisionExplanation(response);
     }
     /**
@@ -2166,7 +2392,7 @@ export class AxonFlow {
      * }
      * ```
      */
-    async listDecisions(opts) {
+    async listDecisions(opts, options) {
         const qs = buildListDecisionsQuery(opts);
         const path = qs ? `/api/v1/decisions?${qs}` : '/api/v1/decisions';
         // Hand-roll the request so we can branch on 429 BEFORE
@@ -2177,7 +2403,7 @@ export class AxonFlow {
             method: 'GET',
             headers,
             signal: AbortSignal.timeout(this.config.timeout),
-        });
+        }, options?.userToken);
         if (response.status === 429) {
             const text = await response.text();
             try {
@@ -2203,11 +2429,112 @@ export class AxonFlow {
         }
         const body = (await response.json());
         const rows = body?.decisions ?? [];
+        // An empty page under ReadScope.None is the fail-closed shape, not a
+        // finding: the platform returned zero rows because it resolved no identity
+        // to scope on, so the page says nothing about what exists. Guarded on
+        // emptiness as well as on the scope, so a non-empty page is never turned
+        // into an error whatever the header says — and only `none` refuses, because
+        // an own-rows read that legitimately found nothing is a real answer.
+        const scopeError = refuseVacuousScopedPage(response, 'decisions', rows.length);
+        if (scopeError)
+            throw scopeError;
         return rows.map(parseDecisionSummary);
     }
     // ------------------------------------------------------------------ //
     // Decision Mode PEP: decide -> fulfill -> forward (ADR-056, #2563)    //
     // ------------------------------------------------------------------ //
+    // ------------------------------------------------------------------ //
+    // AuthZEN-native authorization (ADR-065)                              //
+    // ------------------------------------------------------------------ //
+    /**
+     * The transport `src/authzen.ts` runs its envelopes through.
+     *
+     * It is this client's own authenticated HTTP path — same credentials, same
+     * `X-Axonflow-Client` attribution, same heartbeat gate — with the status left
+     * uninterpreted, because on this route a 4xx body is a typed refusal document
+     * rather than an error string.
+     */
+    //
+    // A PROTOTYPE METHOD, not a class-field arrow. As a field it was an own
+    // enumerable property holding the parent's lexical `this`, so `asUser`'s
+    // Object.assign copied it and every `evaluate()` on a derived client sent the
+    // PARENT's identity — from construction, not merely after some ordering. A
+    // prototype method has no captured `this`; it binds at the call site, which is
+    // the derived client. See `asUser` and
+    // `a fresh instance has no own-property functions`.
+    async sendAuthZEN(path, body, extraHeaders) {
+        const response = await this._fetch(`${this.config.endpoint}${path}`, {
+            method: 'POST',
+            headers: { ...this.buildAuthHeaders(), ...extraHeaders },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(this.config.timeout),
+        });
+        return { status: response.status, body: await response.text() };
+    }
+    /**
+     * Ask whether one subject may perform one action on one resource.
+     *
+     * The AuthZEN-native surface (`POST /api/v1/access/evaluation`). New
+     * integrations should be written against this rather than
+     * {@link AxonFlow.decide}: at v11 the engine behind it becomes the ADR-065
+     * Policy Decision Point with no wire change, so an integration written here
+     * migrates once instead of twice.
+     *
+     * @example
+     * ```typescript
+     * const decision = await axonflow.evaluate({
+     *   subject: { type: 'gateway', id: 'llm-gateway-01' },
+     *   action: { name: 'llm.completion' },
+     *   resource: { type: 'llm', id: 'llm' },
+     *   context: { args: { query: userPrompt } },
+     * });
+     * if (!decision.allowed) throw new Error(`blocked: ${decision.state}`);
+     * ```
+     *
+     * @throws AuthZENRefusal when the request was NOT evaluated. This is not a
+     *   denial — `pointer` names the member to fix, and only `retryable` is worth
+     *   sending again.
+     * @throws AuthZENProtocolError when the server answered 200 with a body this
+     *   build cannot safely act on.
+     * @throws AuthenticationError on 401 — the gateway refused the credentials
+     *   before the route ran.
+     */
+    async evaluate(request) {
+        // Bound at the CALL SITE, so the transport belongs to whichever client
+        // is calling — including one derived by `asUser`. Passing the method
+        // unbound would lose `this` entirely; capturing it in a field would
+        // reintroduce the parent-bound copy this method exists to avoid.
+        return evaluateEnvelope(this.sendAuthZEN.bind(this), buildEnvelope(request));
+    }
+    /**
+     * Ask whether ONE operation is permitted against several preconditions.
+     *
+     * It returns ONE decision, not one per entry. The entries of a bulk request
+     * are preconditions of a single operation — moving a ticket must be
+     * authorized against the destination project as well as against the ticket —
+     * so they combine to the least permissive outcome: one denied entry denies
+     * the operation. An API returning a list would invite a caller to act on the
+     * entry it liked.
+     *
+     * Any member an entry omits is inherited from the envelope's shared base, so
+     * the common case is a shared subject and action with one resource per entry.
+     *
+     * @example
+     * ```typescript
+     * const decision = await axonflow.evaluateAll({
+     *   subject: { type: 'gateway', id: 'llm-gateway-01' },
+     *   action: { name: 'tool.call' },
+     *   context: { args: { query: userPrompt } },
+     *   evaluations: [
+     *     { resource: { type: 'tool', id: 'jira/move_issue' } },
+     *     { resource: { type: 'tool', id: 'jira/update_project' } },
+     *   ],
+     * });
+     * ```
+     */
+    async evaluateAll(bulk) {
+        return evaluateEnvelope(this.sendAuthZEN.bind(this), buildEnvelope(undefined, bulk));
+    }
     /**
      * Ask the PDP for a verdict on a request (`POST /api/v1/decide`).
      *
@@ -2458,7 +2785,17 @@ export class AxonFlow {
         if (this.config.debug) {
             debugLog('Searching audit logs', { limit, offset });
         }
-        const response = await this.orchestratorRequest('POST', '/api/v1/audit/search', body);
+        // The audit reads are in the same role-scoped family as decisions
+        // (platform/orchestrator applyReadScopeHeader), so they inherit the same
+        // rule: an empty page under scope `none` could not have contained a row,
+        // and reporting it as data is the vacuous read this SDK now refuses. The
+        // count is taken inside orchestratorRequest, which sees BOTH shapes the
+        // platform sends — a bare array or the wrapped envelope — so the rule
+        // cannot hold on only whichever branch the server happened to take.
+        const response = await this.orchestratorRequest('POST', '/api/v1/audit/search', body, {
+            resource: 'audit entries',
+            pageKey: 'entries',
+        });
         // Handle both array and wrapped response formats
         if (Array.isArray(response)) {
             const entries = response.map(e => this.parseAuditLogEntry(e));
@@ -2512,7 +2849,11 @@ export class AxonFlow {
             debugLog('Getting audit logs for tenant', { tenantId, limit, offset });
         }
         const path = `/api/v1/audit/tenant/${encodeURIComponent(tenantId)}?limit=${limit}&offset=${offset}`;
-        const response = await this.orchestratorRequest('GET', path);
+        // Same rule, same family as searchAuditLogs.
+        const response = await this.orchestratorRequest('GET', path, undefined, {
+            resource: 'audit entries',
+            pageKey: 'entries',
+        });
         // Handle both array and wrapped response formats
         if (Array.isArray(response)) {
             const entries = response.map(e => this.parseAuditLogEntry(e));
@@ -3733,7 +4074,7 @@ export class AxonFlow {
     /**
      * Generic HTTP request helper for APIs (routes through single endpoint per ADR-026)
      */
-    async orchestratorRequest(method, path, body) {
+    async orchestratorRequest(method, path, body, scoped) {
         const url = `${this.config.endpoint}${path}`;
         const headers = this.buildAuthHeaders();
         const options = {
@@ -3744,9 +4085,24 @@ export class AxonFlow {
         if (body && (method === 'POST' || method === 'PUT' || method === 'PATCH')) {
             options.body = JSON.stringify(body);
         }
-        const response = await this._fetch(url, options);
+        const response = await this._fetch(url, options, scoped?.userToken);
         if (!response.ok) {
             const errorText = await response.text();
+            // A scoped miss reports WHY it missed. Only 404 is interpreted: the scope
+            // header is stamped before the handler writes its status, so it also
+            // rides a 500 from further down the handler, and explaining a server
+            // fault as a scoping outcome would be exactly the confidently-wrong
+            // diagnosis this type exists to prevent.
+            if (scoped && response.status === 404) {
+                const scopeError = readScopeErrorFor({
+                    resource: scoped.resource,
+                    identifier: scoped.identifier,
+                    scope: readScopeOf(response),
+                    statusCode: response.status,
+                });
+                if (scopeError)
+                    throw scopeError;
+            }
             if (response.status === 401 || response.status === 403) {
                 throw new AuthenticationError(`Request failed: ${errorText}`);
             }
@@ -3759,7 +4115,18 @@ export class AxonFlow {
         if (response.status === 204) {
             return undefined;
         }
-        return response.json();
+        const parsed = (await response.json());
+        if (scoped?.pageKey !== undefined) {
+            const rows = Array.isArray(parsed)
+                ? parsed.length
+                : Array.isArray(parsed?.[scoped.pageKey])
+                    ? parsed[scoped.pageKey].length
+                    : 0;
+            const scopeError = refuseVacuousScopedPage(response, scoped.resource, rows);
+            if (scopeError)
+                throw scopeError;
+        }
+        return parsed;
     }
     // Note: getPortalUrl() was removed in v2.0.0 (ADR-026 Single Entry Point).
     // All routes now go through the single Agent endpoint (this.config.endpoint).