scoutline 0.10.2 → 0.12.0

package/dist/lib/consumption.js

@@ -0,0 +1,161 @@
+/**
+ * Consumption event + sink (Plan B — PB-T2).
+ *
+ * A **typed consumption event** represents one billable Provider
+ * transport attempt. Shared execution emits it at the execution seam
+ * (`lib/execution.ts`) — after the cache-miss check, around each
+ * `operation.invoke()` call — so cache hits emit nothing and a retried
+ * operation emits one event per attempt.
+ *
+ * Boundary rules:
+ *   - Imports quota-store types (the sink writes to it) and provider
+ *     identity types. No provider transport, no command presentation.
+ *   - The sink is **best-effort**: a record failure is converted to a
+ *     redacted warning and never propagates. A successful Provider
+ *     result still returns; the retry/fallback classifier is never
+ *     consulted on accounting state.
+ *   - The amount is an explicit exact/estimate/unknown discriminated
+ *     value. There is no `number = 1` default — Research/Vision and
+ *     other variable-cost capabilities persist `unknown` or an
+ *     explicit estimate rather than fake-precise consumption.
+ *
+ * Persistence lifecycle:
+ *   - The sink's `record()` promise is awaited before the billable
+ *     invoke returns outward, so the consumption write survives the
+ *     bin's immediate `process.exit(status)`. A rejection is converted
+ *     to a stderr warning; the outer promise still resolves.
+ *
+ * Relation to PB-T1 / PB-T3:
+ *   - The sink calls PB-T1's `QuotaStore.writeConsumption`, advancing
+ *     `locallyUpdatedAt` and adjusting the matching category's count
+ *     set when one is exposed. `observedAt` (ground truth) never moves.
+ *   - The event carries canonical data (capability ID, category, unit,
+ *     amount). PB-T3 maps capabilities→categories and PB-T4 ranks;
+ *     PB-T2 records raw, provider-neutral events and lets later layers
+ *     interpret them.
+ */
+// ---------------------------------------------------------------------------
+// Default amount per capability (honest cost model)
+// ---------------------------------------------------------------------------
+/**
+ * Default {@link ConsumptionAmount} for a capability when the wrapper
+ * has no response-usage to derive from. Most providers do not return
+ * per-call usage, so the default is **unknown** — never a fake-precise
+ * "1".
+ *
+ * Capabilities whose unit-cost is reliably one (Search, Repository,
+ * Reader, Map) get `{ kind: "estimate", value: 1 }`. Capabilities
+ * with variable cost (Research = 4–250 credits, Vision = variable
+ * tokens, Crawl = per-page) default to `unknown`. PB-T3 refines these
+ * mappings; PB-T2 records the honest default.
+ */
+export function defaultAmountForCapability(capabilityId) {
+    switch (capabilityId) {
+        case "search":
+        case "reader":
+        case "repository-exploration":
+        case "map":
+            // Single-call cost; count-bearing categories get decremented by 1.
+            return { kind: "estimate", value: 1 };
+        case "vision":
+        case "crawl":
+        case "research":
+            // Variable-cost: vision bills tokens; crawl bills per-page
+            // credits; research bills 4–250 credits per request. Without a
+            // response-carried usage, persist `unknown` rather than a
+            // fake-precise number.
+            return { kind: "unknown" };
+        default:
+            // Unrecognized capability — never guess.
+            return { kind: "unknown" };
+    }
+}
+function defaultConsumptionWarning(message) {
+    process.stderr.write(`scoutline: ${message}\n`);
+}
+/**
+ * Build a production {@link ConsumptionSink} that writes through
+ * {@link QuotaStore.writeConsumption}. The sink is fail-safe: any
+ * internal rejection (disk full, permission, race) is converted to a
+ * warning and the recorded promise resolves so shared execution never
+ * observes an accounting failure.
+ *
+ * The store's per-file mutex serializes concurrent writes within the
+ * process; cross-process concurrency is last-write-wins (acceptable
+ * for an observational heuristic; PB-T1's atomic rename keeps the
+ * final state crash-safe).
+ */
+export function createQuotaStoreConsumptionSink(options) {
+    const store = options.store;
+    const now = options.now ?? Date.now;
+    const onWarning = options.onWarning ?? defaultConsumptionWarning;
+    return {
+        async record(event) {
+            try {
+                await store.writeConsumption(event.provider, {
+                    ...(event.category !== undefined ? { category: event.category } : {}),
+                    ...(event.unit !== undefined ? { unit: event.unit } : {}),
+                    amount: event.amount,
+                }, event.at ?? now());
+            }
+            catch (error) {
+                // Redacted: never log event detail (provider, capability) —
+                // accounting failure is observational only.
+                const reason = error instanceof Error ? error.message : String(error);
+                onWarning(`quota consumption recording failed: ${reason}`);
+            }
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// In-memory sink double (tests)
+// ---------------------------------------------------------------------------
+/**
+ * Build an in-memory {@link ConsumptionSink} for hermetic tests. Records
+ * every event in `events` (in arrival order); never rejects. Use this
+ * to assert exact event sequences for cache-hit suppression, retry
+ * emission, and observational-handler silence.
+ */
+export function createInMemoryConsumptionSink() {
+    const events = [];
+    return {
+        async record(event) {
+            events.push(event);
+        },
+        get events() {
+            return events;
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Emission helper — used by executeProviderOperation
+// ---------------------------------------------------------------------------
+/**
+ * Emit one {@link ConsumptionEvent} through `sink`, deriving the event
+ * from `context` + `attempt`. The promise ALWAYS resolves: a sink
+ * failure has already been converted to a warning inside the sink, and
+ * this helper adds a defensive outer try/catch so an exception in the
+ * context-derivation path can never escape into the retry classifier.
+ *
+ * Returns void — shared execution awaits it before the invoke returns
+ * outward, but the resolution value carries no information.
+ */
+export async function emitConsumption(sink, context, attempt, now) {
+    try {
+        await sink.record({
+            provider: context.provider,
+            capabilityId: context.capabilityId,
+            ...(context.category !== undefined ? { category: context.category } : {}),
+            ...(context.unit !== undefined ? { unit: context.unit } : {}),
+            amount: context.amount,
+            attempt,
+            at: now(),
+        });
+    }
+    catch {
+        // Defensive double-wall: the production sink already swallows.
+        // If a test sink throws, we still don't let it reach the retry
+        // classifier.
+    }
+}
+//# sourceMappingURL=consumption.js.map

package/dist/lib/consumption.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consumption.js","sourceRoot":"","sources":["../../src/lib/consumption.ts"],"names":[],"mappings":"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"}

package/dist/lib/errors.d.ts

@@ -50,7 +50,18 @@ export declare class ValidationError extends ScoutlineError {
 export declare class UnsupportedCapabilityError extends ScoutlineError {
     constructor(provider: string, capability: string);
 }
+/**
+ * Provider-specific option unsupported by a Capability. The constructor
+ * signature is unchanged so all current throw sites keep compiling without
+ * modification; the structured fields expose the same information notices
+ * used to extract from the message string. Provider-fallback notices read
+ * these fields directly (the message format MUST stay stable — it is
+ * checked verbatim by existing adapter tests).
+ */
 export declare class UnsupportedOptionError extends ScoutlineError {
+    readonly provider: string;
+    readonly capability: string;
+    readonly option: string;
     constructor(provider: string, capability: string, option: string);
 }
 export declare class ConfigurationError extends ScoutlineError {

package/dist/lib/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,MAAM,MAAM,kBAAkB,GAC1B,YAAY,GACZ,eAAe,GACf,eAAe,GACf,kBAAkB,GAClB,aAAa,GACb,wBAAwB,GACxB,oBAAoB,GACpB,WAAW,GACX,YAAY,GACZ,eAAe,CAAC;AAEpB,MAAM,WAAW,qBAAqB;IACpC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,kBAAkB,GAAG,MAAM,CAAC;IAC3C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,YACE,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,kBAAkB,GAAG,MAAM,EACjC,OAAO,GAAE,qBAA0B,EASpC;CACF;AAED;;;;;;GAMG;AACH,qBAAa,QAAS,SAAQ,cAAc;IAC1C,YAAY,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAG5E;CACF;AAED,qBAAa,eAAgB,SAAQ,cAAc;IACjD,YAAY,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAOzC;CACF;AAED,qBAAa,0BAA2B,SAAQ,cAAc;IAC5D,YAAY,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAO/C;CACF;AAED,qBAAa,sBAAuB,SAAQ,cAAc;IACxD,YAAY,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAO/D;CACF;AAED,qBAAa,kBAAmB,SAAQ,cAAc;IACpD,YAAY,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAOzC;CACF;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,UAAW,SAAQ,cAAc;IAC5C,YAAY,OAAO,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAQ1C;CACF;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAKxD;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAKvD;AAOD,qBAAa,SAAU,SAAQ,QAAQ;IAMrC,YAAY,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAK5C;CACF;AAED,qBAAa,QAAS,SAAQ,QAAQ;IACpC,YAAY,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAE9C;CACF;AAED,qBAAa,YAAa,SAAQ,QAAQ;IACxC,YAAY,OAAO,EAAE,MAAM,EAE1B;CACF;AAED,qBAAa,YAAa,SAAQ,QAAQ;IACxC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,YAAY,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAQ3C;CACF;AAED,qBAAa,SAAU,SAAQ,QAAQ;IACrC,YAAY,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAEzC;CACF;AAiBD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAwCxD"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":"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"}

package/dist/lib/errors.js

@@ -65,10 +65,24 @@ export class UnsupportedCapabilityError extends ScoutlineError {
         this.name = "UnsupportedCapabilityError";
     }
 }
+/**
+ * Provider-specific option unsupported by a Capability. The constructor
+ * signature is unchanged so all current throw sites keep compiling without
+ * modification; the structured fields expose the same information notices
+ * used to extract from the message string. Provider-fallback notices read
+ * these fields directly (the message format MUST stay stable — it is
+ * checked verbatim by existing adapter tests).
+ */
 export class UnsupportedOptionError extends ScoutlineError {
+    provider;
+    capability;
+    option;
     constructor(provider, capability, option) {
         super(`Provider "${provider}" does not support option "${option}" for capability "${capability}"`, "UNSUPPORTED_OPTION", { exitCode: 1 });
         this.name = "UnsupportedOptionError";
+        this.provider = provider;
+        this.capability = capability;
+        this.option = option;
     }
 }
 export class ConfigurationError extends ScoutlineError {

package/dist/lib/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":"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"}

package/dist/lib/execution.d.ts

@@ -27,6 +27,7 @@ import type { RepositoryOperation, RepositoryOperationKind } from "../capabiliti
 import type { ReaderFetchRequest, ReaderFetchResult, ReaderOperation, ReaderOperationKind } from "../capabilities/reader.js";
 import { type ResponseCache } from "./cache.js";
 import type { ProviderId } from "../providers/types.js";
+import type { ConsumptionSink, ConsumptionContext } from "./consumption.js";
 /**
  * Retry policy for a single Provider operation. Defaults are applied
  * per-operation from {@link defaultRetryPolicy}.
@@ -40,11 +41,21 @@ export interface RetryPolicy {
 /**
  * Dependencies shared execution requires. `sleep` and `random` are
  * injected so retry backoff is deterministic under test.
+ *
+ * `consume` (PB-T2) is an OPTIONAL consumption sink. When present and
+ * a billable wrapper supplies a {@link ConsumptionContext}, the retry
+ * loop emits one event per `invoke()` attempt through this sink. When
+ * absent (the default — and what every existing test passes), no event
+ * is emitted and behavior is byte-for-byte identical to pre-PB-T2.
+ * The sink is awaited; its failure is converted to a warning inside
+ * the sink and never reaches the retry classifier.
  */
 export interface ExecutionDependencies {
-    cache: ResponseCache;
-    sleep(ms: number): Promise<void>;
-    random(): number;
+    readonly cache: ResponseCache;
+    readonly sleep: (ms: number) => Promise<void>;
+    readonly random: () => number;
+    readonly consume?: ConsumptionSink;
+    readonly now?: () => number;
 }
 /**
  * Provider operations that share a single retry policy table.
@@ -76,8 +87,25 @@ export declare function defaultRetryPolicy(operation: ProviderOperation): RetryP
  * caller supplies the invoke thunk and the cache strategy. Each
  * outward Provider operation has exactly one retry wrapper; Adapter
  * transport methods perform one attempt and never retry internally.
+ *
+ * PB-T2 — Consumption emission (the execution seam):
+ *   - When `dependencies.consume` AND `consumption` are both supplied,
+ *     one {@link ConsumptionEvent} is emitted **per `invoke()` call**
+ *     (success or failure), BEFORE the invoke runs. Wrappers that have
+ *     already returned on a cache hit never reach this loop, so cache
+ *     hits emit no event. `quota` / `diagnostics` call this function
+ *     directly with no `consumption` argument, so observational
+ *     handlers emit nothing.
+ *   - When either is absent (the default), zero events are emitted
+ *     and behavior is byte-for-byte identical to pre-PB-T2.
+ *   - The sink promise is awaited; its rejection is converted to a
+ *     warning inside the sink and never reaches the retry classifier.
+ *
+ * The 5th parameter is additive and optional; existing 4-arg callers
+ * (Quota, Doctor, and every pre-PB-T2 test) compile and behave
+ * unchanged.
  */
-export declare function executeProviderOperation<T>(operation: ProviderOperation, invoke: () => Promise<T>, dependencies: Pick<ExecutionDependencies, "sleep" | "random">, retryPolicy?: RetryPolicy): Promise<T>;
+export declare function executeProviderOperation<T>(operation: ProviderOperation, invoke: () => Promise<T>, dependencies: Pick<ExecutionDependencies, "sleep" | "random" | "consume" | "now">, retryPolicy?: RetryPolicy, consumption?: ConsumptionContext): Promise<T>;
 /**
  * Execute a normalized Search through the shared pipeline:
  * validate → cache identity → new-key read → optional legacy

package/dist/lib/execution.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"execution.d.ts","sourceRoot":"","sources":["../../src/lib/execution.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"execution.d.ts","sourceRoot":"","sources":["../../src/lib/execution.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC/F,OAAO,KAAK,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAClG,OAAO,KAAK,EAEV,kBAAkB,EAClB,iBAAiB,EACjB,eAAe,EACf,mBAAmB,EACpB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EAAyB,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AACvE,OAAO,KAAK,EAAsB,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAC5E,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AA2C5E;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,QAAQ,CAAC,MAAM,EAAE,MAAM,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,CAAC;IACnC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,iBAAiB,GACzB,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,aAAa,GACb,uBAAuB,GACvB,mBAAmB,GACnB,OAAO,GACP,KAAK,GACL,UAAU,CAAC;AAMf;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,iBAAiB,GAAG,WAAW,CAiC5E;AAuCD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,wBAAwB,CAAC,CAAC,EAC9C,SAAS,EAAE,iBAAiB,EAC5B,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACxB,YAAY,EAAE,IAAI,CAAC,qBAAqB,EAAE,OAAO,GAAG,QAAQ,GAAG,SAAS,GAAG,KAAK,CAAC,EACjF,WAAW,CAAC,EAAE,WAAW,EACzB,WAAW,CAAC,EAAE,kBAAkB,GAC/B,OAAO,CAAC,CAAC,CAAC,CAwBZ;AAoBD;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CACjC,UAAU,EAAE,gBAAgB,EAC5B,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,WAAW,CAAC,EAAE,WAAW,CAAA;CAAE,EACzE,YAAY,EAAE,qBAAqB,GAClC,OAAO,CAAC,SAAS,YAAY,EAAE,CAAC,CA2ElC;AAMD;;;;;;GAMG;AACH,MAAM,WAAW,wBAAwB;IACvC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAsB,0BAA0B,CAAC,OAAO,EAAE,MAAM,EAC9D,SAAS,EAAE,mBAAmB,CAAC,OAAO,EAAE,MAAM,CAAC,EAC/C,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,wBAAwB,EACjC,YAAY,EAAE,qBAAqB,GAClC,OAAO,CAAC,MAAM,CAAC,CA0FjB;AAOD;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAsB,sBAAsB,CAC1C,SAAS,EAAE,eAAe,CAAC,kBAAkB,EAAE,iBAAiB,CAAC,EACjE,OAAO,EAAE,kBAAkB,EAC3B,OAAO,EAAE,oBAAoB,EAC7B,YAAY,EAAE,qBAAqB,GAClC,OAAO,CAAC,iBAAiB,CAAC,CAoF5B;AAMD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,aAAa,CAAC,OAAO,EAAE,MAAM;IAC5C,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;CACrC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe,CAAC,OAAO,EAAE,MAAM;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACjC;;;OAGG;IACH,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,aAAa,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAChE;;;OAGG;IACH,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAAC;IAC5C;;;;;;;;;;OAUG;IACH,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACjE;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAC1D,SAAS,EAAE,eAAe,CAAC,OAAO,EAAE,MAAM,CAAC,EAC3C,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,oBAAoB,EAC7B,YAAY,EAAE,qBAAqB,GAClC,OAAO,CAAC,MAAM,CAAC,CA4EjB"}

package/dist/lib/execution.js

@@ -24,6 +24,43 @@
  */
 import { ScoutlineError } from "./errors.js";
 import { buildProviderCacheKey } from "./cache.js";
+import { emitConsumption, defaultAmountForCapability } from "./consumption.js";
+import { getCapabilityMapping } from "./quota-mapping.js";
+// ---------------------------------------------------------------------------
+// Consumption category resolution (PB-T2 → PB-T3 seam)
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the snapshot category name a consumption event should target
+ * for `(provider, capability)` by routing through PB-T3's mapping table.
+ *
+ * The four billable wrappers derive a {@link ConsumptionContext} at the
+ * emission site. Pre-W1 they hardcoded the capability id (`"search"`,
+ * `"reader"`, ...) as the `category`, which only matched the snapshot
+ * category name for Tavily (whose endpoint names coincide with capability
+ * ids). Z.AI stores categories as `"requests"`/`"tokens"` and Firecrawl
+ * as `"Credits"`, so `writeConsumption`'s name match missed → only
+ * `locallyUpdatedAt` advanced, no numeric decrement (W1).
+ *
+ * This helper uses the first static alias (or the provider-level
+ * fallback) from {@link getCapabilityMapping} so the emitted category
+ * matches the name the provider's normalizer wrote into the snapshot.
+ *
+ * For unmapped `(provider, capability)` pairs — observational
+ * capabilities (`quota`/`diagnostics`), providers excluded from the
+ * mapping table by policy (Brave/Exa), and MiniMax's empty-alias
+ * sentinel — the capability id is returned unchanged. It matches no
+ * snapshot category, so only `locallyUpdatedAt` advances, which is the
+ * correct behavior for observational / non-spend capabilities.
+ */
+function resolveConsumptionCategory(provider, capabilityId) {
+    const mapping = getCapabilityMapping(provider, capabilityId);
+    if (!mapping)
+        return capabilityId;
+    const alias = mapping.categoryAliases[0];
+    if (alias)
+        return alias;
+    return mapping.providerFallbackCategory ?? capabilityId;
+}
 const DEFAULT_BASE_DELAY_MS = 500;
 const DEFAULT_MAX_DELAY_MS = 8000;
 const DEFAULT_JITTER_MS = 250;
@@ -54,17 +91,21 @@ export function defaultRetryPolicy(operation) {
         case "repository-read-file":
         case "repository-list-directory":
         case "reader-fetch":
-        case "map":
             return { ...base, maxRetries: 1 };
         case "crawl":
         case "research":
-            // No retry — double-charge risk. Both are cost-bearing operations
-            // whose create-POST must not be retried by shared execution (crawl
-            // is per-page; research is per-request). The Adapter's invoke()
-            // owns the full create→poll→state-file lifecycle; reclaim-on-miss
-            // (crawl) / state-file resume recover a lost create-POST on the
-            // next user invocation rather than an automatic retry (tech-plan
-            // D2 / §3).
+        case "map":
+            // No retry — double-charge risk. All three are cost-bearing
+            // operations whose create-POST must not be retried by shared
+            // execution (crawl is per-page; research is per-request; map
+            // charges per batch). The Adapter's invoke() owns the full
+            // create→poll→state-file lifecycle; reclaim-on-miss (crawl)
+            // / state-file resume (research) recover a lost create-POST on
+            // the next user invocation rather than an automatic retry.
+            // Map has no server-side state to reclaim, so retry would
+            // strictly double-charge; the documented `--no-fallback` cost
+            // guarantee of `1/1/1` per command depends on this default
+            // (tech-plan D2 / §3; 0.11.0 review Fix 1).
             return { ...base, maxRetries: 0 };
     }
 }
@@ -111,11 +152,37 @@ function isOperationRetryableError(error) {
  * caller supplies the invoke thunk and the cache strategy. Each
  * outward Provider operation has exactly one retry wrapper; Adapter
  * transport methods perform one attempt and never retry internally.
+ *
+ * PB-T2 — Consumption emission (the execution seam):
+ *   - When `dependencies.consume` AND `consumption` are both supplied,
+ *     one {@link ConsumptionEvent} is emitted **per `invoke()` call**
+ *     (success or failure), BEFORE the invoke runs. Wrappers that have
+ *     already returned on a cache hit never reach this loop, so cache
+ *     hits emit no event. `quota` / `diagnostics` call this function
+ *     directly with no `consumption` argument, so observational
+ *     handlers emit nothing.
+ *   - When either is absent (the default), zero events are emitted
+ *     and behavior is byte-for-byte identical to pre-PB-T2.
+ *   - The sink promise is awaited; its rejection is converted to a
+ *     warning inside the sink and never reaches the retry classifier.
+ *
+ * The 5th parameter is additive and optional; existing 4-arg callers
+ * (Quota, Doctor, and every pre-PB-T2 test) compile and behave
+ * unchanged.
  */
-export async function executeProviderOperation(operation, invoke, dependencies, retryPolicy) {
+export async function executeProviderOperation(operation, invoke, dependencies, retryPolicy, consumption) {
     const policy = retryPolicy ?? defaultRetryPolicy(operation);
+    const sink = dependencies.consume;
+    const now = dependencies.now ?? Date.now;
     let attempt = 0;
     for (;;) {
+        // PB-T2: emit BEFORE invoke. One event per loop iteration = one
+        // event per invoke() call. Cache hits never reach here (wrappers
+        // return before invoking). A retrying failure emits once per
+        // attempt.
+        if (sink && consumption) {
+            await emitConsumption(sink, consumption, attempt + 1, now);
+        }
         try {
             return await invoke();
         }
@@ -193,7 +260,25 @@ export async function executeSearch(capability, request, options, dependencies)
     }
     // 5 + 6. Invoke through executeProviderOperation; retryable failures
     //        are retried with backoff driven by the injected sleep+random.
-    const result = await executeProviderOperation("search", () => capability.invoke(request), dependencies, options.retryPolicy);
+    //
+    // PB-T2: when a consumption sink is wired, derive a ConsumptionContext
+    //        from the cache identity (provider + canonical capability id)
+    //        and pass it through. The category is routed through PB-T3's
+    //        mapping table (W1) so it matches the provider-specific snapshot
+    //        category name (ZAI `"requests"`, Firecrawl `"Credits"`, Tavily
+    //        endpoint names) rather than the raw capability id. The default
+    //        amount is the honest per-capability estimate (Search = 1
+    //        estimated request). Cache hits returned above emit nothing.
+    const consumption = dependencies.consume !== undefined
+        ? {
+            provider: identity.provider,
+            capabilityId: "search",
+            category: resolveConsumptionCategory(identity.provider, "search"),
+            unit: "requests",
+            amount: defaultAmountForCapability("search"),
+        }
+        : undefined;
+    const result = await executeProviderOperation("search", () => capability.invoke(request), dependencies, options.retryPolicy, consumption);
     // 7. Cache the full normalized result before count is applied.
     if (!options.noCache) {
         await dependencies.cache.set(newKey, result);
@@ -287,11 +372,27 @@ export async function executeRepositoryOperation(operation, request, options, de
     // 5. Retry-wrapped invoke. Auth, Validation, Unsupported, and
     //    exhausted Quota failures are terminal; transient timeout,
     //    network, and 5xx/429-equivalent failures get one retry.
+    //
+    // PB-T2: when a sink is wired, derive a ConsumptionContext from the
+    //        adapter-owned cache identity. The canonical capability id is
+    //        the descriptor capability (`repository-exploration`); the
+    //        category is routed through PB-T3's mapping table (W1) so it
+    //        matches the provider-specific snapshot category name. Cache
+    //        hits returned above emit nothing.
+    const consumption = dependencies.consume !== undefined
+        ? {
+            provider: identity.provider,
+            capabilityId: "repository-exploration",
+            category: resolveConsumptionCategory(identity.provider, "repository-exploration"),
+            unit: "requests",
+            amount: defaultAmountForCapability("repository-exploration"),
+        }
+        : undefined;
     const result = await executeProviderOperation(
     // `operation.kind` is `RepositoryOperationKind`, which is
     // composed into `ProviderOperation` directly — no cast needed
     // and a future kind union change propagates automatically.
-    operation.kind, () => operation.invoke(request), dependencies, options.retryPolicy);
+    operation.kind, () => operation.invoke(request), dependencies, options.retryPolicy, consumption);
     // 6. Cache the full normalized result before returning.
     if (!options.noCache) {
         await dependencies.cache.set(newKey, result);
@@ -383,7 +484,23 @@ export async function executeReaderOperation(operation, request, options, depend
     // 5. Retry-wrapped invoke. Auth, Validation, Unsupported, and
     //    exhausted Quota failures are terminal; transient timeout,
     //    network, and 5xx/429-equivalent failures get one retry.
-    const result = await executeProviderOperation(operation.kind, () => operation.invoke(request), dependencies, options.retryPolicy);
+    //
+    // PB-T2: when a sink is wired, derive a ConsumptionContext from the
+    //        adapter-owned cache identity. Canonical capability id is
+    //        `reader`; the category is routed through PB-T3's mapping table
+    //        (W1) so it matches the provider-specific snapshot category name
+    //        (ZAI `"requests"`, Tavily `"extract"`, Firecrawl `"Credits"`).
+    //        Cache hits returned above emit nothing.
+    const consumption = dependencies.consume !== undefined
+        ? {
+            provider: identity.provider,
+            capabilityId: "reader",
+            category: resolveConsumptionCategory(identity.provider, "reader"),
+            unit: "requests",
+            amount: defaultAmountForCapability("reader"),
+        }
+        : undefined;
+    const result = await executeProviderOperation(operation.kind, () => operation.invoke(request), dependencies, options.retryPolicy, consumption);
     // 6. Cache the full normalized result before returning.
     if (!options.noCache) {
         await dependencies.cache.set(newKey, result);
@@ -449,7 +566,33 @@ export async function executeCachedOperation(operation, request, options, depend
     //    Unsupported, and exhausted Quota failures are terminal; transient
     //    timeout, network, and 5xx/429-equivalent failures get the
     //    operation-specific retry count.
-    const result = await executeProviderOperation(identity.capability, () => operation.invoke(request, options.signal), dependencies, options.retryPolicy);
+    //
+    // PB-T2: when a sink is wired, derive a ConsumptionContext from the
+    //        adapter-owned cache identity. The category is routed through
+    //        PB-T3's mapping table (W1) so it matches the provider-specific
+    //        snapshot category name (Firecrawl `"Credits"`, Tavily endpoint
+    //        names) rather than the raw capability id. Cost model:
+    //          - `crawl`  → unknown (per-page credits, count varies)
+    //          - `map`    → estimate 1 (single batch cost)
+    //          - `research` → unknown (4–250 credits, request-dependent)
+    //        Cache hits returned above emit nothing.
+    const capabilityId = identity.capability;
+    const consumption = dependencies.consume !== undefined
+        ? {
+            provider: identity.provider,
+            capabilityId,
+            category: resolveConsumptionCategory(identity.provider, capabilityId),
+            ...(capabilityId === "crawl"
+                ? { unit: "credits" }
+                : capabilityId === "map"
+                    ? { unit: "credits" }
+                    : capabilityId === "research"
+                        ? { unit: "credits" }
+                        : {}),
+            amount: defaultAmountForCapability(capabilityId),
+        }
+        : undefined;
+    const result = await executeProviderOperation(identity.capability, () => operation.invoke(request, options.signal), dependencies, options.retryPolicy, consumption);
     // 5. Cache the full normalized result before returning.
     if (!options.noCache) {
         await dependencies.cache.set(newKey, result);

package/dist/lib/execution.js.map

@@ -1 +1 @@
-{"version":3,"file":"execution.js","sourceRoot":"","sources":["../../src/lib/execution.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"execution.js","sourceRoot":"","sources":["../../src/lib/execution.ts"],"names":[],"mappings":"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"}

package/dist/lib/mcp-client.d.ts

@@ -41,6 +41,15 @@ export interface ZaiMcpClientOptions {
     noCache?: boolean;
     disableRetry?: boolean;
     utcpFactory?: () => Promise<UtcpClient>;
+    /**
+     * T2b — Credential view: the resolved env (injected env + file keys)
+     * captured at handler dispatch. When omitted, ambient `process.env`
+     * is used so existing direct constructors keep working. When supplied,
+     * the credential, mode, base URL, retry knobs, cache fingerprint, and
+     * configured-secret scrub set all derive from this view rather than
+     * `process.env`.
+     */
+    env?: NodeJS.ProcessEnv;
 }
 /**
  * Unified MCP client for all Z.AI MCP services
@@ -70,6 +79,9 @@ export declare class ZaiMcpClient {
      * `tool-cache.ts` needs to compute a stable key). Owned here because
      * the inputs come from this class's options and the shared config
      * module; the extracted module stays pure of `loadConfig` / `getMcpEndpoints`.
+     *
+     * T2b: `loadConfig` consults the captured env so tool-cache identity
+     * follows the same invocation credential view as registration.
      */
     private getToolCacheConfig;
     /**