@animalabs/agent-framework 0.22.2 → 0.22.4

package/src/mcpl/push-coalescer.ts

@@ -129,11 +129,15 @@ interface Rendering<E> {
 
 /** What an assembly did, per subject, for the turn being assembled. */
 export interface AssemblyResult {
-  /** Subjects whose render this assembly waited on to completion. */
+  /** Subjects this assembly finished with: it waited on their render to
+   *  completion, or freeze() declined them for this agent. */
   settled: Set<string>;
   /** Of those, the subjects whose render or fallback was delivered as content.
    *  A settled subject that is not here gave the turn nothing to read: empty
-   *  or blank render (§5.2), cancelled, or revoked at response. */
+   *  or blank render (§5.2), cancelled, revoked before the render or at its
+   *  response, a render-start that could not be made durable (the batch then
+   *  waits for its recovery wake), or a batch whose audience doesn't include
+   *  the agent. */
   materialized: Set<string>;
 }
 
@@ -205,7 +209,12 @@ export interface CoalescerHost<E> {
   /** Persist one receipt now, before the acceptance is acknowledged. Throws
    *  on failure, which fails the acceptance (the producer retries). */
   recordReceipt?(record: CoalescingReceiptRecord): void;
-  /** Make every write so far DURABLE (fsync, group-committed by the host).
+  /** One call per ADMITTED occurrence (never for a producer retry the receipt
+   *  deduplicates), after its receipt is recorded. Observation only: a throw
+   *  is contained here and never fails the acceptance. */
+  accepted?(occurrence: CoalescedOccurrence<E>): void;
+  /** Make every write so far DURABLE (an fsync; the coalescer requests each
+   *  commit under its lock, so no two acceptances share one).
    *  Awaited before an acceptance is acknowledged and before push/render is
    *  issued: a kill after either boundary must find the receipt, the
    *  accepted work, and the render-start on disk. Rejects on failure. */
@@ -245,15 +254,21 @@ function mergeIdentity(prior: CoalescedOccurrence['identity'], next: CoalescedOc
  * Validate wire content before it is stored, rendered or converted.
  *
  * Its shape and its visible emptiness, nothing else. An incoming coalesced
- * occurrence reaches context through the converters an uncoalesced message
+ * occurrence reaches context through the converter an uncoalesced message
  * goes through: a plain occurrence the moment it is admitted (the coalescer
  * only remembers where it landed), a deferred one when its render settles or
  * falls back to it. Its content must be an array of objects. A block the
- * converters can't render (a video, an unknown type, an image with neither
+ * converter can't render (a video, an unknown type, an image with neither
  * uri nor data) becomes a placeholder, as it does uncoalesced, and so does a
- * malformed one, since the converters take any object without throwing: a
- * type, text, data, mimeType or uri that isn't a string counts as absent, a
- * text block's as no text. The uncoalesced lane doesn't check the array:
+ * malformed one, since the converter takes any object without throwing: a
+ * type, data, mimeType or uri that isn't a string counts as absent, and a
+ * text block whose text isn't a string shows as its own placeholder, which
+ * counts as no text where MCPL content is admitted: here, on the wire blocks,
+ * and at the uncoalesced boundaries, through isVisiblyEmptyConversion. The
+ * framework's backstops read converted content with isVisiblyEmptyContent,
+ * which would count the placeholder as text, but they see only content one of
+ * those checks has passed. The uncoalesced
+ * lane doesn't check the array:
  * there a member that isn't an object becomes the untyped placeholder, and a
  * null member or content that isn't an array throws in conversion
  * (agent-framework#297 brings that lane to this rule).
@@ -265,8 +280,8 @@ function mergeIdentity(prior: CoalescedOccurrence['identity'], next: CoalescedOc
  *
  * A render result, which the host delivers in the occurrence's place, gets
  * these checks, as RFC-006 §5.2 gives it every check a pushed payload gets,
- * and one more (`checkBlockShapes`): each block must be one the converters
- * show as itself or as a reference stub, not as a placeholder. A malformed
+ * and one more (`checkBlockShapes`): each block must be one the converter
+ * shows as itself or as a reference stub, not as a placeholder. A malformed
  * render falls back to the occurrence's own content; a pushed payload has
  * nothing to fall back to, and gets its placeholders.
  *
@@ -289,12 +304,12 @@ export function validateCoalescedContent(
 }
 
 /**
- * Whether the converters (`convertBlock` in push-handler.ts and
- * channel-registry.ts) show a block as itself, its text or its image or
+ * Whether the converter (`convertBlock` in convert-block.ts, which every lane
+ * uses) shows a block as itself, its text or its image or
  * audio source, or as a reference stub, and not as a placeholder: an
- * unrecognized block, a no-data or no-media-type one, or withheld inline
- * data. A text block whose text isn't a string, which they show as no text,
- * is refused too. This follows their branches in their order.
+ * unrecognized block, a no-data or no-media-type one, withheld inline data,
+ * or a text block whose text isn't a string. This follows its branches in
+ * their order.
  */
 function showsAsItself(b: Record<string, unknown>): boolean {
   if (b.type === 'text') return typeof b.text === 'string';
@@ -485,6 +500,11 @@ export class PushCoalescer<E = unknown> {
       throw new CoalesceError('eventId', 'host could not persist the acceptance; retry', -32000);
     }
     this.receipts.set(receiptKey, entry);
+    try {
+      this.host.accepted?.(occurrence);
+    } catch (error) {
+      this.host.audit({ kind: 'accepted-observer-failed', subject, eventId: occurrence.eventId, error: String(error) });
+    }
     this.prune();
     this.persist();
     // Written but not yet durable: the in-memory receipt deduplicates a retry
@@ -667,7 +687,8 @@ export class PushCoalescer<E = unknown> {
       // be flattened by `then`, holding the lock until the render settled —
       // and the settlement itself needs the lock.
       const started = await this.locked(() => this.freeze(subject, agentName));
-      if (started) {
+      if (started === 'declined') result.settled.add(subject);
+      else if (started) {
         work.push(started.done.then(() => {
           result.settled.add(subject);
           if (started.rendering.materialized) result.materialized.add(subject);
@@ -683,27 +704,42 @@ export class PushCoalescer<E = unknown> {
    * Under the lock: decide whether `subject`'s batch renders for `agentName`,
    * freeze it, make the render-start durable, re-check authority, and start
    * the RPC. Returns the render's completion (shared by every assembly that
-   * waits on this batch, vector 25) or undefined when nothing was started.
+   * waits on this batch, vector 25). Returns 'declined' when the turn being
+   * assembled gets nothing of the batch: the agent isn't in its audience,
+   * whether or not another assembly is rendering it (the batch is left as it
+   * is); authority was revoked before the render could start (the batch is
+   * dropped); or the render-start could not be made durable (the batch is
+   * kept for its recovery wake). Returns undefined when the batch was not
+   * this assembly's to decide on: there is none, the subject moved on during
+   * the audience lookup, or the host is stopping.
    */
-  private async freeze(subject: string, agentName: string): Promise<{ done: Promise<void>; rendering: Rendering<E> } | undefined> {
+  private async freeze(subject: string, agentName: string): Promise<{ done: Promise<void>; rendering: Rendering<E> } | 'declined' | undefined> {
     const state = this.subjects.get(subject);
     if (!state || this.suspended) return undefined;
     if (state.rendering) {
-      // Another assembly froze this batch; share its outcome (vector 25).
+      // Another assembly froze this batch; share its outcome (vector 25),
+      // unless this agent isn't in its audience, as below.
       const rendering = state.rendering;
-      return (await this.host.audience(rendering.batch.latest)).includes(agentName) && state.rendering === rendering ? { done: rendering.done, rendering } : undefined;
+      const audience = await this.host.audience(rendering.batch.latest);
+      if (state.rendering !== rendering) return undefined;
+      if (!audience.includes(agentName)) return 'declined';
+      return { done: rendering.done, rendering };
     }
     const batch = state.batch;
     if (!batch) return undefined;
     // The audience lookup may spawn a fork. Under the lock no admission can
     // move the subject on meanwhile; the identity check guards the host.
     const audience = await this.host.audience(batch.latest);
-    if (!audience.includes(agentName) || state.batch !== batch || state.rendering) return undefined;
+    if (state.batch !== batch || state.rendering) return undefined;
+    // Not this agent's batch, or no longer: an agent woken for it can have left
+    // its audience since. This turn has nothing of it to show. The batch stays
+    // pending; nothing here wakes its current audience.
+    if (!audience.includes(agentName)) return 'declined';
     state.batch = undefined;
     this.host.cancelWake(subject);
     if (!this.host.authorized(batch.latest)) {
       this.host.audit({ kind: 'revoked', subject, eventId: batch.latest.eventId });
-      return undefined;
+      return 'declined';
     }
     const rendering: Rendering<E> = { batch, cancelled: false, done: Promise.resolve() };
     state.rendering = rendering;
@@ -721,7 +757,7 @@ export class PushCoalescer<E = unknown> {
       // unrelated traffic happens by. Re-wake with backoff, so a persistent
       // storage outage does not become a tight loop of model turns.
       this.scheduleRecovery(subject, state);
-      return undefined;
+      return 'declined';
     }
     this.clearRecovery(subject);
     if (this.suspended) { state.rendering = undefined; state.batch = batch; return undefined; }
@@ -731,7 +767,7 @@ export class PushCoalescer<E = unknown> {
     if (!this.host.authorized(batch.latest)) {
       this.host.audit({ kind: 'revoked', subject, eventId: batch.latest.eventId });
       state.rendering = undefined;
-      return undefined;
+      return 'declined';
     }
     rendering.done = this.render(subject, state, rendering, agentName);
     return { done: rendering.done, rendering };

package/src/mcpl/push-handler.ts

@@ -8,10 +8,9 @@
  */
 
 import type { ContentBlock } from '@animalabs/membrane';
-import { INLINE_WITHHELD_TEXT, isInlineContradiction, referenceStubOrNull } from './references.js';
+import { convertBlock } from './convert-block.js';
 
 import type {
-  McplContentBlock,
   PushEventParams,
   PushEventResult,
 } from './types.js';
@@ -19,7 +18,8 @@ import type { FeatureSetManager } from './feature-set-manager.js';
 import { McplFeatureSetError } from './feature-set-manager.js';
 import { expandCoreTags } from './tags.js';
 import { coalesceRejectionReason, EmptyContentError, validateCoalescedContent } from './push-coalescer.js';
-import { isSilentHeartbeatMarker, isVisiblyEmptyContent } from './visible-content.js';
+import type { InboundSource } from './inbound-source.js';
+import { isSilentHeartbeatMarker, isVisiblyEmptyConversion } from './visible-content.js';
 import { logDetail, logValue } from './log-value.js';
 import { RefusalLines } from './refusal-lines.js';
 
@@ -50,91 +50,11 @@ export interface McplPushEvent {
   coalescingSubject?: string;
   /** RFC-006 assembly: materialized for this agent's turn (store directly). */
   assemblingFor?: string;
-}
-
-// ============================================================================
-// Content conversion: McplContentBlock → membrane ContentBlock
-// ============================================================================
-
-/**
- * Convert a single MCPL wire-format content block to a membrane ContentBlock,
- * as the channel lane's convertBlock (channel-registry.ts) does, apart from
- * the provenance its reference stubs name. Hook context injections convert
- * through hook-orchestrator.ts's own.
- */
-export function convertBlock(block: McplContentBlock): ContentBlock {
-  switch (block.type) {
-    case 'text':
-      // Text that isn't a string is no text, as the request sanitizer and
-      // the visible-content check already read it.
-      return { type: 'text', text: typeof block.text === 'string' ? block.text : '' };
-
-    case 'image':
-      if (isInlineContradiction(block)) {
-        // RFC-005 vector 2: inline data claiming bulk disposition — fail
-        // closed, withhold the data (checked BEFORE the data branch).
-        return { type: 'text', text: INLINE_WITHHELD_TEXT };
-      }
-      if (isFilledString(block.uri) && block.disposition) {
-        // RFC-005 uri-form media with a disposition claim: stub, do not
-        // hand the URI to the provider or inline it.
-        return { type: 'text', text: referenceStubOrNull(block, 'attachment on push event') ?? '[reference]' };
-      }
-      if (isFilledString(block.data) && isFilledString(block.mimeType)) {
-        return {
-          type: 'image',
-          source: { type: 'base64', data: block.data, mediaType: block.mimeType },
-        } as ContentBlock;
-      }
-      if (isFilledString(block.uri)) {
-        return {
-          type: 'image',
-          source: { type: 'url', url: block.uri },
-        } as ContentBlock;
-      }
-      return { type: 'text', text: isFilledString(block.data) ? '[Image: no media type]' : '[Image: no data]' };
-
-    case 'audio':
-      if (isInlineContradiction(block)) {
-        // RFC-005 vector 2: inline data claiming bulk disposition — fail
-        // closed, withhold the data (checked BEFORE the data branch).
-        return { type: 'text', text: INLINE_WITHHELD_TEXT };
-      }
-      if (isFilledString(block.uri) && block.disposition) {
-        // RFC-005 uri-form media with a disposition claim: stub, do not
-        // hand the URI to the provider or inline it.
-        return { type: 'text', text: referenceStubOrNull(block, 'attachment on push event') ?? '[reference]' };
-      }
-      if (isFilledString(block.data) && isFilledString(block.mimeType)) {
-        return {
-          type: 'audio',
-          source: { type: 'base64', data: block.data, mediaType: block.mimeType },
-        } as ContentBlock;
-      }
-      return { type: 'text', text: isFilledString(block.data) ? '[Audio: no media type]' : '[Audio: no data]' };
-
-    case 'resource':
-      // RFC-005: reference blocks become bounded stubs — never raw URIs
-      // (a signed URL is a bearer credential that looks like a location).
-      return { type: 'text', text: referenceStubOrNull(block, 'attachment on push event') ?? '[reference]' };
-
-    default: {
-      // Unknown wire block types previously fell off the exhaustive switch
-      // and propagated `undefined` into ContentBlock[]. Fail visibly. A type
-      // that isn't a string is no type, and is never converted to one: an
-      // object can throw when it is.
-      const type: unknown = (block as { type?: unknown }).type;
-      return { type: 'text', text: `[unrecognized content block: ${typeof type === 'string' ? type : 'untyped'}]` };
-    }
-  }
-}
-
-/** A string with something in it: the only data, mimeType or uri a block's
- *  source is built from, and the only uri that makes it a reference. Anything
- *  else a sender puts there leaves the block without it, so conversion never
- *  throws and never copies a non-string. */
-function isFilledString(value: unknown): value is string {
-  return typeof value === 'string' && value !== '';
+  /** Host acceptance time (epoch ms), stamped where the push is admitted. */
+  acceptedAt?: number;
+  /** Framework-owned source envelope, frozen at a coalesced occurrence's
+   *  acceptance so its later delivery cannot restamp it (inbound-source.ts). */
+  inboundSource?: InboundSource;
 }
 
 // ============================================================================
@@ -199,6 +119,10 @@ export class PushHandler {
     emitTraceFn: (event: { type: string; [key: string]: unknown }) => void,
     shouldTriggerInference?: (content: string, metadata: Record<string, unknown>) => boolean,
     private readonly handleCoalesced?: (serverId: string, params: PushEventParams, event: McplPushEvent) => Promise<PushEventResult>,
+    /** An ordinary (uncoalesced) push was just admitted, before it is queued
+     *  or acknowledged: return its source envelope, frozen now
+     *  (mcpl/inbound-source.ts). Coalesced work is stamped by its own path. */
+    private readonly acceptInbound?: (event: McplPushEvent) => InboundSource | undefined,
   ) {
     this.featureSetManager = featureSetManager;
     this.pushEventFn = pushEventFn;
@@ -275,8 +199,8 @@ export class PushHandler {
 
     // 2. Convert content blocks, and refuse content with nothing visible in
     // it — before dedup, so a refused eventId is not burned for a retry.
-    const content: ContentBlock[] = params.payload.content.map(convertBlock);
-    if (!emptyAllowed && isVisiblyEmptyContent(content)) {
+    const content: ContentBlock[] = params.payload.content.map((block) => convertBlock(block, 'attachment on push event', serverId));
+    if (!emptyAllowed && isVisiblyEmptyConversion(params.payload.content, content)) {
       const err = new EmptyContentError();
       this.traceEmptyRejection(serverId, params);
       if (responder?.respondError) responder.respondError(err.code, err.message, { field: err.field });
@@ -326,6 +250,7 @@ export class PushHandler {
       timestamp: params.timestamp,
       inferenceId,
       triggerInference,
+      acceptedAt: Date.now(),
     };
     if (coalesced) {
       // RFC-006: the coalescer decides whether this occurrence replaces an
@@ -344,6 +269,11 @@ export class PushHandler {
       }
       return;
     }
+    // The source envelope is frozen at admission, before queueing or the
+    // acknowledgement: nothing that changes while the push waits in the
+    // queue can rewrite where it came from.
+    const inboundSource = this.acceptInbound?.(pushEvent);
+    if (inboundSource) pushEvent.inboundSource = inboundSource;
     this.pushEventFn(pushEvent);
 
     // 7. Emit trace

package/src/mcpl/reference-fetcher.ts

@@ -3,7 +3,8 @@
  * dereferences a reference, and it fails closed on every axis the RFC names:
  *
  *  - **origin binding (§6.1, revision 3):** authenticated fetches go only to
- *    the origin the reference's server connection was dialed to. This v1 does
+ *    the origin a server's connection was dialed to, for a reference that
+ *    server delivered, with that server's credential. This v1 does
  *    not fetch third-party origins at all (deferred with declared reference
  *    origins); the connection credential is applied as an Authorization
  *    header by this code alone and never surfaces to model, script, or URI.
@@ -29,15 +30,22 @@
  */
 import { createHash } from 'node:crypto';
 import type { ReferenceRecord } from './references.js';
-import { EXPIRY_REASON, isReferenceExpired, referenceExpiry, REFERENCE_LIMITS, sanitizeLabel } from './references.js';
+import { EXPIRY_REASON, isReferenceExpired, referenceExpiry, REFERENCE_LIMITS, sanitizeLabel, UNBOUND_REASON } from './references.js';
 
 /** Per-fetch hard ceiling on actual bytes (overridable per server / call). */
 export const DEFAULT_FETCH_MAX_BYTES = 256 * 1024 * 1024;
 /** Eager (autofetch) threshold: at most what could have shipped inline. */
 export const DEFAULT_EAGER_FETCH_MAX_BYTES = 256 * 1024;
-/** Cumulative per-server budget for this process. */
+/** Cumulative per-server budget for this process: every byte a fetch dialed
+ *  through a server reads counts against that server's, whether or not it's
+ *  kept. */
 export const DEFAULT_MAX_TOTAL_BYTES = 1024 * 1024 * 1024;
 const FETCH_TIMEOUT_MS = 60_000;
+/** What a refusal by the per-server budget adds. The total lives as long as
+ *  this fetcher, one per framework, so only someone running the host renews
+ *  it, by starting a new one, or raises the budget (the server's config's
+ *  autofetch.maxTotalBytes, which each fetch reads afresh). */
+const BUDGET_LASTS = "the budget doesn't renew on its own, so calling again won't change that unless whoever runs this host raises or renews it";
 const EAGER_FETCH_TIMEOUT_MS = 10_000;
 
 export interface ResolvedServerBinding {
@@ -102,6 +110,10 @@ export function normalizedOrigin(url: string): string | null {
 }
 
 export class ReferenceFetcher {
+  /** Bytes read through each server in this process, charged to the server a
+   *  fetch dials through as each chunk is read, kept or not. Concurrent
+   *  fetches through one server share the total, so each checks what the
+   *  others have taken. */
   private totals = new Map<string, number>();
   private inFlight = new Map<string, Promise<FetchOutcome>>();
 
@@ -113,16 +125,34 @@ export class ReferenceFetcher {
   ) {}
 
   /** Would the eager (autofetch) default fetch this record? Not one the
-   *  fetcher refuses as expired, which would only take an eager slot. */
+   *  fetcher refuses as expired, which would only take an eager slot. It
+   *  takes the eager limit of the server the fetch would dial. */
   isEagerEligible(record: ReferenceRecord): boolean {
     if (record.fetchedPath) return false;
     if (isReferenceExpired(record.testimony)) return false;
-    if (record.serverId === undefined) return false;
-    const binding = this.resolveServer(record.serverId);
-    if (!binding) return false;
-    const cap = binding.autofetch?.maxBytes ?? DEFAULT_EAGER_FETCH_MAX_BYTES;
-    if (record.testimony.sizeBytes === undefined || record.testimony.sizeBytes > cap) return false;
-    return this.originCheck(record, binding) === null;
+    const server = this.serverFor(record);
+    if ('refusal' in server) return false;
+    const cap = server.binding.autofetch?.maxBytes ?? DEFAULT_EAGER_FETCH_MAX_BYTES;
+    return record.testimony.sizeBytes !== undefined && record.testimony.sizeBytes <= cap;
+  }
+
+  /** The server to dial for a record (§6.2): the first, in the order they
+   *  delivered it, whose address is on the uri's origin. When none is, the
+   *  first server's refusal (unknown to this host, or the origin check's),
+   *  and for a record no server delivered, that it's unbound. */
+  private serverFor(record: ReferenceRecord): { serverId: string; binding: ResolvedServerBinding } | { refusal: string } {
+    let refusal: string | undefined;
+    for (const serverId of record.serverIds) {
+      const binding = this.resolveServer(serverId);
+      if (!binding) {
+        refusal ??= `unknown server: ${serverId}`;
+        continue;
+      }
+      const offOrigin = this.originCheck(record, binding);
+      if (offOrigin === null) return { serverId, binding };
+      refusal ??= offOrigin;
+    }
+    return { refusal: refusal ?? `reference ${UNBOUND_REASON}` };
   }
 
   /** §6.1/§7.1 policy check; returns a refusal reason or null. */
@@ -158,24 +188,33 @@ export class ReferenceFetcher {
 
   private async doFetch(record: ReferenceRecord, opts?: { maxBytes?: number; timeoutMs?: number }): Promise<FetchOutcome> {
     const t = record.testimony;
-    if (record.serverId === undefined) return { ok: false, error: 'reference has no server binding' };
-    const binding = this.resolveServer(record.serverId);
-    if (!binding) return { ok: false, error: `unknown server: ${record.serverId}` };
-
-    const refusal = this.originCheck(record, binding);
-    if (refusal) return { ok: false, error: refusal };
+    const server = this.serverFor(record);
+    if ('refusal' in server) return { ok: false, error: server.refusal };
+    const { serverId, binding } = server;
     const expiry = referenceExpiry(t);
     if (expiry) return { ok: false, error: `reference ${EXPIRY_REASON[expiry]}` };
 
     const ceiling = opts?.maxBytes ?? DEFAULT_FETCH_MAX_BYTES;
-    // Vector 4: a claim already over the ceiling refuses without dialing.
-    if (t.sizeBytes !== undefined && t.sizeBytes > ceiling) {
-      return { ok: false, error: `claimed ${t.sizeBytes} bytes exceeds fetch ceiling ${ceiling}` };
-    }
+    // The budget is checked before the ceiling, here and while reading: a
+    // larger max_bytes lifts the ceiling, and nothing the caller does lifts
+    // the budget, so a fetch past both is told about the budget.
     const budget = binding.autofetch?.maxTotalBytes ?? DEFAULT_MAX_TOTAL_BYTES;
-    const used = this.totals.get(record.serverId) ?? 0;
+    const used = this.totals.get(serverId) ?? 0;
     if (used >= budget) {
-      return { ok: false, error: `per-server fetch budget exhausted (${used}/${budget} bytes)` };
+      return { ok: false, error: `per-server fetch budget exhausted (${used}/${budget} bytes); ${BUDGET_LASTS}` };
+    }
+    // Vector 4: a claim already over the ceiling refuses without dialing. One
+    // that's also over what's left of the budget is told about the budget,
+    // which no max_bytes lifts. A claim over what's left but within the
+    // ceiling still dials, and the budget stops it at its first chunk past.
+    if (t.sizeBytes !== undefined && t.sizeBytes > ceiling) {
+      if (t.sizeBytes > budget - used) {
+        return {
+          ok: false,
+          error: `claimed ${t.sizeBytes} bytes exceeds what's left of the per-server fetch budget (${used}/${budget} bytes); ${BUDGET_LASTS}`,
+        };
+      }
+      return { ok: false, error: `claimed ${t.sizeBytes} bytes exceeds fetch ceiling ${ceiling}` };
     }
 
     const controller = new AbortController();
@@ -198,10 +237,17 @@ export class ReferenceFetcher {
         const { done, value } = await reader.read();
         if (done) break;
         received += value.byteLength;
-        if (received > ceiling || received > budget - used) {
+        // What's read is charged at once, kept or not: other fetches from
+        // this server read the same total, so none spends what another took.
+        const total = (this.totals.get(serverId) ?? 0) + value.byteLength;
+        this.totals.set(serverId, total);
+        if (total > budget) {
+          controller.abort();
+          return { ok: false, error: `aborted: per-server fetch budget exhausted (${total}/${budget} bytes); ${BUDGET_LASTS}` };
+        }
+        if (received > ceiling) {
           controller.abort();
-          const which = received > ceiling ? 'ceiling' : 'per-server budget';
-          return { ok: false, error: `aborted: actual bytes exceeded ${which} at ${received}` };
+          return { ok: false, error: `aborted: actual bytes exceeded ceiling at ${received}` };
         }
         const buf = Buffer.from(value);
         hash.update(buf);
@@ -232,7 +278,6 @@ export class ReferenceFetcher {
       const path = await this.saveFile(`${record.refId}.${ext}`, data, observedMime);
       if (path === null) return { ok: false, error: 'no writable workspace mount to store the payload' };
 
-      this.totals.set(record.serverId, used + data.length);
       record.fetchedPath = path;
       record.verifiedBytes = data.length;
       record.verifiedMimeType = observedMime;