@graphorin/provider 0.5.0

package/dist/internal/sse.js

@@ -0,0 +1,104 @@
+//#region src/internal/sse.ts
+/**
+* Minimal `text/event-stream` chunk parser. Lives here because three
+* adapters consume the same shape (`llamaCppServerAdapter`,
+* `openAICompatibleAdapter`, plus the OpenAI-compatible legacy path
+* inside `ollamaAdapter`). Keeping it local avoids pulling in a
+* dedicated SSE package.
+*
+* @internal
+*/
+/**
+* Parse a Web `Response`'s body as Server-Sent Events. Yields one
+* payload per `data: <payload>` line; ignores `event:` / `id:` / `:`
+* comments lines per the SSE spec. Terminates on `data: [DONE]` per
+* the OpenAI-compatible convention.
+*
+* @internal
+*/
+async function* parseEventStream(body, options = {}) {
+	if (body === null) return;
+	const reader = body.getReader();
+	const decoder = new TextDecoder("utf-8");
+	let buffer = "";
+	try {
+		while (true) {
+			if (options.signal?.aborted) return;
+			const { value, done } = await reader.read();
+			if (done) break;
+			buffer += decoder.decode(value, { stream: true });
+			let separatorIdx = findSeparator(buffer);
+			while (separatorIdx !== -1) {
+				const eventBlock = buffer.slice(0, separatorIdx);
+				buffer = buffer.slice(separatorIdx + matchSeparatorLength(buffer, separatorIdx));
+				const dataPayload = extractDataLines(eventBlock);
+				if (dataPayload === "[DONE]") return;
+				if (dataPayload !== null) yield dataPayload;
+				separatorIdx = findSeparator(buffer);
+			}
+		}
+		const tail = buffer.trim();
+		if (tail.length > 0) {
+			const dataPayload = extractDataLines(tail);
+			if (dataPayload !== null && dataPayload !== "[DONE]") yield dataPayload;
+		}
+	} finally {
+		reader.releaseLock();
+	}
+}
+function findSeparator(buffer) {
+	const lf = buffer.indexOf("\n\n");
+	const crlf = buffer.indexOf("\r\n\r\n");
+	if (lf === -1) return crlf;
+	if (crlf === -1) return lf;
+	return lf < crlf ? lf : crlf;
+}
+function matchSeparatorLength(buffer, idx) {
+	return buffer.startsWith("\r\n\r\n", idx) ? 4 : 2;
+}
+function extractDataLines(block) {
+	const dataLines = [];
+	for (const rawLine of block.split(/\r?\n/)) {
+		const line = rawLine;
+		if (line.startsWith(":")) continue;
+		if (line.startsWith("data:")) dataLines.push(line.slice(5).replace(/^ /, ""));
+	}
+	if (dataLines.length === 0) return null;
+	return dataLines.join("\n");
+}
+/**
+* Parse a newline-delimited JSON stream. Used by the native Ollama
+* `/api/chat` path which emits one JSON object per `\n`-terminated
+* line (NOT SSE).
+*
+* @internal
+*/
+async function* parseNdJsonStream(body, options = {}) {
+	if (body === null) return;
+	const reader = body.getReader();
+	const decoder = new TextDecoder("utf-8");
+	let buffer = "";
+	try {
+		while (true) {
+			if (options.signal?.aborted) return;
+			const { value, done } = await reader.read();
+			if (done) break;
+			buffer += decoder.decode(value, { stream: true });
+			let nlIdx = buffer.indexOf("\n");
+			while (nlIdx !== -1) {
+				const line = buffer.slice(0, nlIdx).trim();
+				buffer = buffer.slice(nlIdx + 1);
+				if (line.length > 0) yield line;
+				nlIdx = buffer.indexOf("\n");
+			}
+		}
+		const tail = buffer.trim();
+		if (tail.length > 0) yield tail;
+	} finally {
+		reader.releaseLock();
+	}
+}
+
+//#endregion
+export { parseEventStream, parseNdJsonStream };
+//# sourceMappingURL=sse.js.map

package/dist/internal/sse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.js","names":["dataLines: string[]"],"sources":["../../src/internal/sse.ts"],"sourcesContent":["/**\n * Minimal `text/event-stream` chunk parser. Lives here because three\n * adapters consume the same shape (`llamaCppServerAdapter`,\n * `openAICompatibleAdapter`, plus the OpenAI-compatible legacy path\n * inside `ollamaAdapter`). Keeping it local avoids pulling in a\n * dedicated SSE package.\n *\n * @internal\n */\n\n/**\n * Parse a Web `Response`'s body as Server-Sent Events. Yields one\n * payload per `data: <payload>` line; ignores `event:` / `id:` / `:`\n * comments lines per the SSE spec. Terminates on `data: [DONE]` per\n * the OpenAI-compatible convention.\n *\n * @internal\n */\nexport async function* parseEventStream(\n  body: ReadableStream<Uint8Array> | null,\n  options: { readonly signal?: AbortSignal } = {},\n): AsyncIterable<string> {\n  if (body === null) return;\n  const reader = body.getReader();\n  const decoder = new TextDecoder('utf-8');\n  let buffer = '';\n  try {\n    while (true) {\n      if (options.signal?.aborted) return;\n      const { value, done } = await reader.read();\n      if (done) break;\n      buffer += decoder.decode(value, { stream: true });\n      let separatorIdx = findSeparator(buffer);\n      while (separatorIdx !== -1) {\n        const eventBlock = buffer.slice(0, separatorIdx);\n        buffer = buffer.slice(separatorIdx + matchSeparatorLength(buffer, separatorIdx));\n        const dataPayload = extractDataLines(eventBlock);\n        if (dataPayload === '[DONE]') return;\n        if (dataPayload !== null) yield dataPayload;\n        separatorIdx = findSeparator(buffer);\n      }\n    }\n    const tail = buffer.trim();\n    if (tail.length > 0) {\n      const dataPayload = extractDataLines(tail);\n      if (dataPayload !== null && dataPayload !== '[DONE]') yield dataPayload;\n    }\n  } finally {\n    reader.releaseLock();\n  }\n}\n\nfunction findSeparator(buffer: string): number {\n  const lf = buffer.indexOf('\\n\\n');\n  const crlf = buffer.indexOf('\\r\\n\\r\\n');\n  if (lf === -1) return crlf;\n  if (crlf === -1) return lf;\n  return lf < crlf ? lf : crlf;\n}\n\nfunction matchSeparatorLength(buffer: string, idx: number): number {\n  return buffer.startsWith('\\r\\n\\r\\n', idx) ? 4 : 2;\n}\n\nfunction extractDataLines(block: string): string | null {\n  const dataLines: string[] = [];\n  for (const rawLine of block.split(/\\r?\\n/)) {\n    const line = rawLine;\n    if (line.startsWith(':')) continue;\n    if (line.startsWith('data:')) {\n      dataLines.push(line.slice(5).replace(/^ /, ''));\n    }\n  }\n  if (dataLines.length === 0) return null;\n  return dataLines.join('\\n');\n}\n\n/**\n * Parse a newline-delimited JSON stream. Used by the native Ollama\n * `/api/chat` path which emits one JSON object per `\\n`-terminated\n * line (NOT SSE).\n *\n * @internal\n */\nexport async function* parseNdJsonStream(\n  body: ReadableStream<Uint8Array> | null,\n  options: { readonly signal?: AbortSignal } = {},\n): AsyncIterable<string> {\n  if (body === null) return;\n  const reader = body.getReader();\n  const decoder = new TextDecoder('utf-8');\n  let buffer = '';\n  try {\n    while (true) {\n      if (options.signal?.aborted) return;\n      const { value, done } = await reader.read();\n      if (done) break;\n      buffer += decoder.decode(value, { stream: true });\n      let nlIdx = buffer.indexOf('\\n');\n      while (nlIdx !== -1) {\n        const line = buffer.slice(0, nlIdx).trim();\n        buffer = buffer.slice(nlIdx + 1);\n        if (line.length > 0) yield line;\n        nlIdx = buffer.indexOf('\\n');\n      }\n    }\n    const tail = buffer.trim();\n    if (tail.length > 0) yield tail;\n  } finally {\n    reader.releaseLock();\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAkBA,gBAAuB,iBACrB,MACA,UAA6C,EAAE,EACxB;AACvB,KAAI,SAAS,KAAM;CACnB,MAAM,SAAS,KAAK,WAAW;CAC/B,MAAM,UAAU,IAAI,YAAY,QAAQ;CACxC,IAAI,SAAS;AACb,KAAI;AACF,SAAO,MAAM;AACX,OAAI,QAAQ,QAAQ,QAAS;GAC7B,MAAM,EAAE,OAAO,SAAS,MAAM,OAAO,MAAM;AAC3C,OAAI,KAAM;AACV,aAAU,QAAQ,OAAO,OAAO,EAAE,QAAQ,MAAM,CAAC;GACjD,IAAI,eAAe,cAAc,OAAO;AACxC,UAAO,iBAAiB,IAAI;IAC1B,MAAM,aAAa,OAAO,MAAM,GAAG,aAAa;AAChD,aAAS,OAAO,MAAM,eAAe,qBAAqB,QAAQ,aAAa,CAAC;IAChF,MAAM,cAAc,iBAAiB,WAAW;AAChD,QAAI,gBAAgB,SAAU;AAC9B,QAAI,gBAAgB,KAAM,OAAM;AAChC,mBAAe,cAAc,OAAO;;;EAGxC,MAAM,OAAO,OAAO,MAAM;AAC1B,MAAI,KAAK,SAAS,GAAG;GACnB,MAAM,cAAc,iBAAiB,KAAK;AAC1C,OAAI,gBAAgB,QAAQ,gBAAgB,SAAU,OAAM;;WAEtD;AACR,SAAO,aAAa;;;AAIxB,SAAS,cAAc,QAAwB;CAC7C,MAAM,KAAK,OAAO,QAAQ,OAAO;CACjC,MAAM,OAAO,OAAO,QAAQ,WAAW;AACvC,KAAI,OAAO,GAAI,QAAO;AACtB,KAAI,SAAS,GAAI,QAAO;AACxB,QAAO,KAAK,OAAO,KAAK;;AAG1B,SAAS,qBAAqB,QAAgB,KAAqB;AACjE,QAAO,OAAO,WAAW,YAAY,IAAI,GAAG,IAAI;;AAGlD,SAAS,iBAAiB,OAA8B;CACtD,MAAMA,YAAsB,EAAE;AAC9B,MAAK,MAAM,WAAW,MAAM,MAAM,QAAQ,EAAE;EAC1C,MAAM,OAAO;AACb,MAAI,KAAK,WAAW,IAAI,CAAE;AAC1B,MAAI,KAAK,WAAW,QAAQ,CAC1B,WAAU,KAAK,KAAK,MAAM,EAAE,CAAC,QAAQ,MAAM,GAAG,CAAC;;AAGnD,KAAI,UAAU,WAAW,EAAG,QAAO;AACnC,QAAO,UAAU,KAAK,KAAK;;;;;;;;;AAU7B,gBAAuB,kBACrB,MACA,UAA6C,EAAE,EACxB;AACvB,KAAI,SAAS,KAAM;CACnB,MAAM,SAAS,KAAK,WAAW;CAC/B,MAAM,UAAU,IAAI,YAAY,QAAQ;CACxC,IAAI,SAAS;AACb,KAAI;AACF,SAAO,MAAM;AACX,OAAI,QAAQ,QAAQ,QAAS;GAC7B,MAAM,EAAE,OAAO,SAAS,MAAM,OAAO,MAAM;AAC3C,OAAI,KAAM;AACV,aAAU,QAAQ,OAAO,OAAO,EAAE,QAAQ,MAAM,CAAC;GACjD,IAAI,QAAQ,OAAO,QAAQ,KAAK;AAChC,UAAO,UAAU,IAAI;IACnB,MAAM,OAAO,OAAO,MAAM,GAAG,MAAM,CAAC,MAAM;AAC1C,aAAS,OAAO,MAAM,QAAQ,EAAE;AAChC,QAAI,KAAK,SAAS,EAAG,OAAM;AAC3B,YAAQ,OAAO,QAAQ,KAAK;;;EAGhC,MAAM,OAAO,OAAO,MAAM;AAC1B,MAAI,KAAK,SAAS,EAAG,OAAM;WACnB;AACR,SAAO,aAAa"}

package/dist/internal/url-utils.js

@@ -0,0 +1,24 @@
+//#region src/internal/url-utils.ts
+/**
+* Tiny URL helpers shared between the provider adapters. Kept regex-free
+* so CodeQL does not flag the (otherwise harmless) `/+` quantifier on
+* adapter base URLs.
+*
+* @internal
+*/
+/**
+* Strip every trailing `/` from a URL string. Operates in `O(n)` time
+* with a single linear scan from the end, so it is safe to call on
+* adversarial inputs without bounding the length first.
+*
+* @internal
+*/
+function stripTrailingSlashes(url) {
+	let end = url.length;
+	while (end > 0 && url.charCodeAt(end - 1) === 47) end -= 1;
+	return end === url.length ? url : url.slice(0, end);
+}
+
+//#endregion
+export { stripTrailingSlashes };
+//# sourceMappingURL=url-utils.js.map

package/dist/internal/url-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-utils.js","names":[],"sources":["../../src/internal/url-utils.ts"],"sourcesContent":["/**\n * Tiny URL helpers shared between the provider adapters. Kept regex-free\n * so CodeQL does not flag the (otherwise harmless) `/+` quantifier on\n * adapter base URLs.\n *\n * @internal\n */\n\n/**\n * Strip every trailing `/` from a URL string. Operates in `O(n)` time\n * with a single linear scan from the end, so it is safe to call on\n * adversarial inputs without bounding the length first.\n *\n * @internal\n */\nexport function stripTrailingSlashes(url: string): string {\n  let end = url.length;\n  while (end > 0 && url.charCodeAt(end - 1) === 0x2f /* '/' */) end -= 1;\n  return end === url.length ? url : url.slice(0, end);\n}\n"],"mappings":";;;;;;;;;;;;;;;AAeA,SAAgB,qBAAqB,KAAqB;CACxD,IAAI,MAAM,IAAI;AACd,QAAO,MAAM,KAAK,IAAI,WAAW,MAAM,EAAE,KAAK,GAAgB,QAAO;AACrE,QAAO,QAAQ,IAAI,SAAS,MAAM,IAAI,MAAM,GAAG,IAAI"}

package/dist/middleware/compose.d.ts

@@ -0,0 +1,85 @@
+import { Provider, ProviderMiddleware } from "@graphorin/core";
+
+//#region src/middleware/compose.d.ts
+
+/**
+ * Symbol attached to every middleware-produced provider so the
+ * composer can detect and validate the chain. The symbol is opaque
+ * and cross-realm safe via `Symbol.for`.
+ *
+ * @stable
+ */
+declare const MIDDLEWARE_KIND: unique symbol;
+/**
+ * Canonical middleware ordering — outermost → innermost. The table
+ * is enforced by {@link composeProviderMiddleware} and is part of the
+ * provider layer's public contract (DEC-145 / ADR-039).
+ *
+ * ## Why this order
+ *
+ * Composition is outermost-first, so a request flows top→bottom and a
+ * response flows bottom→top:
+ *
+ * - `withTracing` is outermost so the span wraps everything below —
+ *   including retries — and records true end-to-end latency.
+ * - `withRetry` sits above the rate/cost limiters so each retry
+ *   attempt is independently counted and throttled.
+ * - `withRateLimit` → `withCostLimit` → `withCostTracking` form the
+ *   budget stack: throttle before admitting, reject over-budget calls
+ *   before spending, then meter what actually went through.
+ * - `withFallback` is just above redaction so a fallback to a
+ *   secondary provider still passes through the redactor.
+ * - `withRedaction` is **innermost** (closest to the provider) so it
+ *   is the last thing to touch the outbound payload and the first to
+ *   touch the inbound stream — guaranteeing every retry, fallback, and
+ *   cost-tracked request sees an already-redacted payload and no
+ *   secret can bypass it.
+ *
+ * @stable
+ */
+declare const CANONICAL_MIDDLEWARE_ORDER: readonly string[];
+/**
+ * Read the discriminant kind attached to a middleware-produced
+ * provider. Returns `undefined` if the provider is the bare adapter
+ * or a custom wrapper that does not declare a kind.
+ *
+ * @stable
+ */
+declare function getMiddlewareKind(provider: Provider): string | undefined;
+/**
+ * Return `true` iff the chain rooted at `provider` contains a
+ * middleware whose kind matches `name`.
+ *
+ * @stable
+ */
+declare function providerHasMiddleware(provider: Provider, name: string): boolean;
+/**
+ * Wrap an adapter in a middleware chain whose order is validated
+ * against {@link CANONICAL_MIDDLEWARE_ORDER}. The argument array MUST
+ * be ordered outermost → innermost — the same way the layers appear
+ * in the documented composition example. The composer validates that
+ * every kind known to the canonical order is monotonically non-
+ * decreasing in index, throws otherwise.
+ *
+ * Custom middleware whose kind is NOT in the canonical order is
+ * silently allowed at any position — operators registering bespoke
+ * layers via {@link defineProviderMiddleware} carry the
+ * responsibility of placing them sensibly.
+ *
+ * @stable
+ */
+declare function composeProviderMiddleware(middlewares: ReadonlyArray<ProviderMiddleware>): ProviderMiddleware;
+/**
+ * Decorator factory used internally by every built-in middleware. The
+ * returned function attaches the canonical kind discriminator and the
+ * inner-provider symbol so the composer can introspect chains.
+ *
+ * @stable
+ */
+declare function defineProviderMiddleware<T>(args: {
+  readonly kind: string;
+  readonly factory: (opts: T) => ProviderMiddleware;
+}): (opts: T) => ProviderMiddleware;
+//#endregion
+export { CANONICAL_MIDDLEWARE_ORDER, MIDDLEWARE_KIND, composeProviderMiddleware, defineProviderMiddleware, getMiddlewareKind, providerHasMiddleware };
+//# sourceMappingURL=compose.d.ts.map

package/dist/middleware/compose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose.d.ts","names":[],"sources":["../../src/middleware/compose.ts"],"sourcesContent":[],"mappings":";;;;AAgMA;;;;;;;cAzKa;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA6BA;;;;;;;;iBAqCG,iBAAA,WAA4B;;;;;;;iBA2B5B,qBAAA,WAAgC;;;;;;;;;;;;;;;;iBAmBhC,yBAAA,cACD,cAAc,sBAC1B;;;;;;;;iBAuDa;;2BAEW,MAAM;WACtB,MAAM"}

package/dist/middleware/compose.js

@@ -0,0 +1,174 @@
+import { MiddlewareOrderingError } from "../errors/errors.js";
+
+//#region src/middleware/compose.ts
+/**
+* Symbol attached to every middleware-produced provider so the
+* composer can detect and validate the chain. The symbol is opaque
+* and cross-realm safe via `Symbol.for`.
+*
+* @stable
+*/
+const MIDDLEWARE_KIND = Symbol.for("graphorin.provider.middleware.kind");
+/**
+* Canonical middleware ordering — outermost → innermost. The table
+* is enforced by {@link composeProviderMiddleware} and is part of the
+* provider layer's public contract (DEC-145 / ADR-039).
+*
+* ## Why this order
+*
+* Composition is outermost-first, so a request flows top→bottom and a
+* response flows bottom→top:
+*
+* - `withTracing` is outermost so the span wraps everything below —
+*   including retries — and records true end-to-end latency.
+* - `withRetry` sits above the rate/cost limiters so each retry
+*   attempt is independently counted and throttled.
+* - `withRateLimit` → `withCostLimit` → `withCostTracking` form the
+*   budget stack: throttle before admitting, reject over-budget calls
+*   before spending, then meter what actually went through.
+* - `withFallback` is just above redaction so a fallback to a
+*   secondary provider still passes through the redactor.
+* - `withRedaction` is **innermost** (closest to the provider) so it
+*   is the last thing to touch the outbound payload and the first to
+*   touch the inbound stream — guaranteeing every retry, fallback, and
+*   cost-tracked request sees an already-redacted payload and no
+*   secret can bypass it.
+*
+* @stable
+*/
+const CANONICAL_MIDDLEWARE_ORDER = [
+	"withTracing",
+	"withRetry",
+	"withRateLimit",
+	"withCostLimit",
+	"withCostTracking",
+	"withFallback",
+	"withRedaction"
+];
+const CANONICAL_INDEX = Object.freeze(CANONICAL_MIDDLEWARE_ORDER.reduce((acc, name, idx) => {
+	acc[name] = idx;
+	return acc;
+}, {}));
+/**
+* Symbol used to walk the chain — every wrapper exposes the inner
+* provider so the composer can introspect the full stack at startup.
+*
+* @stable
+*/
+const INNER_PROVIDER = Symbol.for("graphorin.provider.middleware.inner");
+/**
+* Read the discriminant kind attached to a middleware-produced
+* provider. Returns `undefined` if the provider is the bare adapter
+* or a custom wrapper that does not declare a kind.
+*
+* @stable
+*/
+function getMiddlewareKind(provider) {
+	return provider[MIDDLEWARE_KIND];
+}
+/**
+* Walk the middleware chain inside `provider` and return the array of
+* declared kinds (outer → inner).
+*
+* @stable
+*/
+function listMiddlewareKinds(provider) {
+	const kinds = [];
+	let cur = provider;
+	while (cur !== void 0) {
+		const kind = cur[MIDDLEWARE_KIND];
+		if (kind !== void 0) kinds.push(kind);
+		cur = cur[INNER_PROVIDER];
+	}
+	return kinds;
+}
+/**
+* Return `true` iff the chain rooted at `provider` contains a
+* middleware whose kind matches `name`.
+*
+* @stable
+*/
+function providerHasMiddleware(provider, name) {
+	return listMiddlewareKinds(provider).includes(name);
+}
+/**
+* Wrap an adapter in a middleware chain whose order is validated
+* against {@link CANONICAL_MIDDLEWARE_ORDER}. The argument array MUST
+* be ordered outermost → innermost — the same way the layers appear
+* in the documented composition example. The composer validates that
+* every kind known to the canonical order is monotonically non-
+* decreasing in index, throws otherwise.
+*
+* Custom middleware whose kind is NOT in the canonical order is
+* silently allowed at any position — operators registering bespoke
+* layers via {@link defineProviderMiddleware} carry the
+* responsibility of placing them sensibly.
+*
+* @stable
+*/
+function composeProviderMiddleware(middlewares) {
+	return (next) => {
+		let chain = next;
+		for (let i = middlewares.length - 1; i >= 0; i--) {
+			const factory = middlewares[i];
+			if (typeof factory !== "function") throw new TypeError(`composeProviderMiddleware: entry at index ${i} is not a ProviderMiddleware function.`);
+			chain = factory(chain);
+		}
+		validateMiddlewareOrder(chain);
+		return chain;
+	};
+}
+/**
+* Validate the kinds present in `provider` against the canonical
+* order. Exposed for tests; the composer calls it on every chain.
+*
+* @stable
+*/
+function validateMiddlewareOrder(provider) {
+	const kinds = listMiddlewareKinds(provider);
+	const recognised = [];
+	for (const kind of kinds) {
+		const idx = CANONICAL_INDEX[kind];
+		if (idx !== void 0) recognised.push({
+			kind,
+			index: idx
+		});
+	}
+	for (let i = 1; i < recognised.length; i++) {
+		const prev = recognised[i - 1];
+		const cur = recognised[i];
+		if (prev !== void 0 && cur !== void 0 && cur.index < prev.index) throw new MiddlewareOrderingError({
+			offendingPair: [prev.kind, cur.kind],
+			canonicalOrder: CANONICAL_MIDDLEWARE_ORDER
+		});
+	}
+}
+/**
+* Decorator factory used internally by every built-in middleware. The
+* returned function attaches the canonical kind discriminator and the
+* inner-provider symbol so the composer can introspect chains.
+*
+* @stable
+*/
+function defineProviderMiddleware(args) {
+	return (opts) => {
+		const built = args.factory(opts);
+		return (next) => {
+			const wrapped = built(next);
+			const branded = Object.create(wrapped);
+			Object.defineProperty(branded, MIDDLEWARE_KIND, {
+				value: args.kind,
+				enumerable: false
+			});
+			Object.defineProperty(branded, INNER_PROVIDER, {
+				value: next,
+				enumerable: false
+			});
+			return branded;
+		};
+	};
+}
+
+//#endregion
+export { CANONICAL_MIDDLEWARE_ORDER, MIDDLEWARE_KIND, composeProviderMiddleware, defineProviderMiddleware, getMiddlewareKind, providerHasMiddleware };
+//# sourceMappingURL=compose.js.map

package/dist/middleware/compose.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose.js","names":["MIDDLEWARE_KIND: unique symbol","CANONICAL_MIDDLEWARE_ORDER: readonly string[]","CANONICAL_INDEX: Readonly<Record<string, number>>","INNER_PROVIDER: unique symbol","kinds: string[]","cur: KindedProvider | undefined","chain: Provider","recognised: { kind: string; index: number }[]","branded: Provider"],"sources":["../../src/middleware/compose.ts"],"sourcesContent":["/**\n * Canonical-order middleware composer. The composer enforces the\n * documented ordering at startup and throws\n * {@link MiddlewareOrderingError} on violation. Manual\n * `withRetry(withRedaction(p))` style still works but emits a one-time\n * WARN unless the consumer flips `strict: true`, in which case the\n * composer also throws on manual nesting that violates the canonical\n * order.\n *\n * @packageDocumentation\n */\n\nimport type { Provider, ProviderMiddleware } from '@graphorin/core';\n\nimport { MiddlewareOrderingError } from '../errors/errors.js';\n\n/**\n * Symbol attached to every middleware-produced provider so the\n * composer can detect and validate the chain. The symbol is opaque\n * and cross-realm safe via `Symbol.for`.\n *\n * @stable\n */\nexport const MIDDLEWARE_KIND: unique symbol = Symbol.for('graphorin.provider.middleware.kind');\n\n/**\n * Canonical middleware ordering — outermost → innermost. The table\n * is enforced by {@link composeProviderMiddleware} and is part of the\n * provider layer's public contract (DEC-145 / ADR-039).\n *\n * ## Why this order\n *\n * Composition is outermost-first, so a request flows top→bottom and a\n * response flows bottom→top:\n *\n * - `withTracing` is outermost so the span wraps everything below —\n *   including retries — and records true end-to-end latency.\n * - `withRetry` sits above the rate/cost limiters so each retry\n *   attempt is independently counted and throttled.\n * - `withRateLimit` → `withCostLimit` → `withCostTracking` form the\n *   budget stack: throttle before admitting, reject over-budget calls\n *   before spending, then meter what actually went through.\n * - `withFallback` is just above redaction so a fallback to a\n *   secondary provider still passes through the redactor.\n * - `withRedaction` is **innermost** (closest to the provider) so it\n *   is the last thing to touch the outbound payload and the first to\n *   touch the inbound stream — guaranteeing every retry, fallback, and\n *   cost-tracked request sees an already-redacted payload and no\n *   secret can bypass it.\n *\n * @stable\n */\nexport const CANONICAL_MIDDLEWARE_ORDER: readonly string[] = [\n  'withTracing',\n  'withRetry',\n  'withRateLimit',\n  'withCostLimit',\n  'withCostTracking',\n  'withFallback',\n  'withRedaction',\n];\n\nconst CANONICAL_INDEX: Readonly<Record<string, number>> = Object.freeze(\n  CANONICAL_MIDDLEWARE_ORDER.reduce<Record<string, number>>((acc, name, idx) => {\n    acc[name] = idx;\n    return acc;\n  }, {}),\n);\n\ninterface KindedProvider extends Provider {\n  readonly [MIDDLEWARE_KIND]?: string;\n  readonly [INNER_PROVIDER]?: Provider;\n}\n\n/**\n * Symbol used to walk the chain — every wrapper exposes the inner\n * provider so the composer can introspect the full stack at startup.\n *\n * @stable\n */\nexport const INNER_PROVIDER: unique symbol = Symbol.for('graphorin.provider.middleware.inner');\n\n/**\n * Read the discriminant kind attached to a middleware-produced\n * provider. Returns `undefined` if the provider is the bare adapter\n * or a custom wrapper that does not declare a kind.\n *\n * @stable\n */\nexport function getMiddlewareKind(provider: Provider): string | undefined {\n  return (provider as KindedProvider)[MIDDLEWARE_KIND];\n}\n\n/**\n * Walk the middleware chain inside `provider` and return the array of\n * declared kinds (outer → inner).\n *\n * @stable\n */\nexport function listMiddlewareKinds(provider: Provider): readonly string[] {\n  const kinds: string[] = [];\n  let cur: KindedProvider | undefined = provider as KindedProvider;\n  while (cur !== undefined) {\n    const kind = cur[MIDDLEWARE_KIND];\n    if (kind !== undefined) kinds.push(kind);\n    cur = cur[INNER_PROVIDER] as KindedProvider | undefined;\n  }\n  return kinds;\n}\n\n/**\n * Return `true` iff the chain rooted at `provider` contains a\n * middleware whose kind matches `name`.\n *\n * @stable\n */\nexport function providerHasMiddleware(provider: Provider, name: string): boolean {\n  return listMiddlewareKinds(provider).includes(name);\n}\n\n/**\n * Wrap an adapter in a middleware chain whose order is validated\n * against {@link CANONICAL_MIDDLEWARE_ORDER}. The argument array MUST\n * be ordered outermost → innermost — the same way the layers appear\n * in the documented composition example. The composer validates that\n * every kind known to the canonical order is monotonically non-\n * decreasing in index, throws otherwise.\n *\n * Custom middleware whose kind is NOT in the canonical order is\n * silently allowed at any position — operators registering bespoke\n * layers via {@link defineProviderMiddleware} carry the\n * responsibility of placing them sensibly.\n *\n * @stable\n */\nexport function composeProviderMiddleware(\n  middlewares: ReadonlyArray<ProviderMiddleware>,\n): ProviderMiddleware {\n  return (next: Provider): Provider => {\n    let chain: Provider = next;\n    // Apply innermost → outermost so the composed call order matches\n    // the array's outer → inner declaration.\n    for (let i = middlewares.length - 1; i >= 0; i--) {\n      const factory = middlewares[i];\n      if (typeof factory !== 'function') {\n        throw new TypeError(\n          `composeProviderMiddleware: entry at index ${i} is not a ProviderMiddleware function.`,\n        );\n      }\n      chain = factory(chain);\n    }\n    validateMiddlewareOrder(chain);\n    return chain;\n  };\n}\n\n/**\n * Validate the kinds present in `provider` against the canonical\n * order. Exposed for tests; the composer calls it on every chain.\n *\n * @stable\n */\nexport function validateMiddlewareOrder(provider: Provider): void {\n  const kinds = listMiddlewareKinds(provider);\n  // Filter to the kinds we recognise.\n  const recognised: { kind: string; index: number }[] = [];\n  for (const kind of kinds) {\n    const idx = CANONICAL_INDEX[kind];\n    if (idx !== undefined) recognised.push({ kind, index: idx });\n  }\n  // The recognised list runs outer → inner; canonical indices must\n  // increase monotonically. The first decreasing pair is the\n  // violation.\n  for (let i = 1; i < recognised.length; i++) {\n    const prev = recognised[i - 1];\n    const cur = recognised[i];\n    if (prev !== undefined && cur !== undefined && cur.index < prev.index) {\n      throw new MiddlewareOrderingError({\n        offendingPair: [prev.kind, cur.kind],\n        canonicalOrder: CANONICAL_MIDDLEWARE_ORDER,\n      });\n    }\n  }\n}\n\n/**\n * Decorator factory used internally by every built-in middleware. The\n * returned function attaches the canonical kind discriminator and the\n * inner-provider symbol so the composer can introspect chains.\n *\n * @stable\n */\nexport function defineProviderMiddleware<T>(args: {\n  readonly kind: string;\n  readonly factory: (opts: T) => ProviderMiddleware;\n}): (opts: T) => ProviderMiddleware {\n  return (opts: T): ProviderMiddleware => {\n    const built = args.factory(opts);\n    return (next: Provider): Provider => {\n      const wrapped = built(next);\n      const branded: Provider = Object.create(wrapped) as Provider;\n      Object.defineProperty(branded, MIDDLEWARE_KIND, {\n        value: args.kind,\n        enumerable: false,\n      });\n      Object.defineProperty(branded, INNER_PROVIDER, {\n        value: next,\n        enumerable: false,\n      });\n      return branded;\n    };\n  };\n}\n"],"mappings":";;;;;;;;;;AAuBA,MAAaA,kBAAiC,OAAO,IAAI,qCAAqC;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6B9F,MAAaC,6BAAgD;CAC3D;CACA;CACA;CACA;CACA;CACA;CACA;CACD;AAED,MAAMC,kBAAoD,OAAO,OAC/D,2BAA2B,QAAgC,KAAK,MAAM,QAAQ;AAC5E,KAAI,QAAQ;AACZ,QAAO;GACN,EAAE,CAAC,CACP;;;;;;;AAaD,MAAaC,iBAAgC,OAAO,IAAI,sCAAsC;;;;;;;;AAS9F,SAAgB,kBAAkB,UAAwC;AACxE,QAAQ,SAA4B;;;;;;;;AAStC,SAAgB,oBAAoB,UAAuC;CACzE,MAAMC,QAAkB,EAAE;CAC1B,IAAIC,MAAkC;AACtC,QAAO,QAAQ,QAAW;EACxB,MAAM,OAAO,IAAI;AACjB,MAAI,SAAS,OAAW,OAAM,KAAK,KAAK;AACxC,QAAM,IAAI;;AAEZ,QAAO;;;;;;;;AAST,SAAgB,sBAAsB,UAAoB,MAAuB;AAC/E,QAAO,oBAAoB,SAAS,CAAC,SAAS,KAAK;;;;;;;;;;;;;;;;;AAkBrD,SAAgB,0BACd,aACoB;AACpB,SAAQ,SAA6B;EACnC,IAAIC,QAAkB;AAGtB,OAAK,IAAI,IAAI,YAAY,SAAS,GAAG,KAAK,GAAG,KAAK;GAChD,MAAM,UAAU,YAAY;AAC5B,OAAI,OAAO,YAAY,WACrB,OAAM,IAAI,UACR,6CAA6C,EAAE,wCAChD;AAEH,WAAQ,QAAQ,MAAM;;AAExB,0BAAwB,MAAM;AAC9B,SAAO;;;;;;;;;AAUX,SAAgB,wBAAwB,UAA0B;CAChE,MAAM,QAAQ,oBAAoB,SAAS;CAE3C,MAAMC,aAAgD,EAAE;AACxD,MAAK,MAAM,QAAQ,OAAO;EACxB,MAAM,MAAM,gBAAgB;AAC5B,MAAI,QAAQ,OAAW,YAAW,KAAK;GAAE;GAAM,OAAO;GAAK,CAAC;;AAK9D,MAAK,IAAI,IAAI,GAAG,IAAI,WAAW,QAAQ,KAAK;EAC1C,MAAM,OAAO,WAAW,IAAI;EAC5B,MAAM,MAAM,WAAW;AACvB,MAAI,SAAS,UAAa,QAAQ,UAAa,IAAI,QAAQ,KAAK,MAC9D,OAAM,IAAI,wBAAwB;GAChC,eAAe,CAAC,KAAK,MAAM,IAAI,KAAK;GACpC,gBAAgB;GACjB,CAAC;;;;;;;;;;AAYR,SAAgB,yBAA4B,MAGR;AAClC,SAAQ,SAAgC;EACtC,MAAM,QAAQ,KAAK,QAAQ,KAAK;AAChC,UAAQ,SAA6B;GACnC,MAAM,UAAU,MAAM,KAAK;GAC3B,MAAMC,UAAoB,OAAO,OAAO,QAAQ;AAChD,UAAO,eAAe,SAAS,iBAAiB;IAC9C,OAAO,KAAK;IACZ,YAAY;IACb,CAAC;AACF,UAAO,eAAe,SAAS,gBAAgB;IAC7C,OAAO;IACP,YAAY;IACb,CAAC;AACF,UAAO"}

package/dist/middleware/index.d.ts

@@ -0,0 +1,10 @@
+import { CANONICAL_MIDDLEWARE_ORDER, MIDDLEWARE_KIND, composeProviderMiddleware, defineProviderMiddleware, getMiddlewareKind, providerHasMiddleware } from "./compose.js";
+import { ProductionStartupHookOptions, assertProductionMiddleware } from "./production-hook.js";
+import { WithCostLimitOptions, withCostLimit } from "./with-cost-limit.js";
+import { CostAccumulator, CostTrackingTotals, WithCostTrackingOptions, createCostAccumulator, withCostTracking } from "./with-cost-tracking.js";
+import { WithFallbackOptions, withFallback } from "./with-fallback.js";
+import { WithRateLimitOptions, withRateLimit } from "./with-rate-limit.js";
+import { PromptRedactionPolicy, PromptRedactionScanScope, PromptRedactionViolation, withRedaction } from "./with-redaction.js";
+import { WithRetryOptions, withRetry } from "./with-retry.js";
+import { WithTracingOptions, withTracing } from "./with-tracing.js";
+export { CANONICAL_MIDDLEWARE_ORDER, type CostAccumulator, type CostTrackingTotals, MIDDLEWARE_KIND, type ProductionStartupHookOptions, type PromptRedactionPolicy, type PromptRedactionScanScope, type PromptRedactionViolation, type WithCostLimitOptions, type WithCostTrackingOptions, type WithFallbackOptions, type WithRateLimitOptions, type WithRetryOptions, type WithTracingOptions, assertProductionMiddleware, composeProviderMiddleware, createCostAccumulator, defineProviderMiddleware, getMiddlewareKind, providerHasMiddleware, withCostLimit, withCostTracking, withFallback, withRateLimit, withRedaction, withRetry, withTracing };

package/dist/middleware/index.js

@@ -0,0 +1,11 @@
+import { CANONICAL_MIDDLEWARE_ORDER, MIDDLEWARE_KIND, composeProviderMiddleware, defineProviderMiddleware, getMiddlewareKind, providerHasMiddleware } from "./compose.js";
+import { assertProductionMiddleware } from "./production-hook.js";
+import { withCostLimit } from "./with-cost-limit.js";
+import { createCostAccumulator, withCostTracking } from "./with-cost-tracking.js";
+import { withFallback } from "./with-fallback.js";
+import { withRateLimit } from "./with-rate-limit.js";
+import { withRedaction } from "./with-redaction.js";
+import { withRetry } from "./with-retry.js";
+import { withTracing } from "./with-tracing.js";
+
+export { CANONICAL_MIDDLEWARE_ORDER, MIDDLEWARE_KIND, assertProductionMiddleware, composeProviderMiddleware, createCostAccumulator, defineProviderMiddleware, getMiddlewareKind, providerHasMiddleware, withCostLimit, withCostTracking, withFallback, withRateLimit, withRedaction, withRetry, withTracing };

package/dist/middleware/production-hook.d.ts

@@ -0,0 +1,27 @@
+import { Provider } from "@graphorin/core";
+
+//#region src/middleware/production-hook.d.ts
+
+/**
+ * Options for {@link assertProductionMiddleware}.
+ *
+ * @stable
+ */
+interface ProductionStartupHookOptions {
+  /** Middleware kinds that must be present. Defaults to `['withRedaction']`. */
+  readonly requiredKinds?: ReadonlyArray<string>;
+  /** Force the check regardless of `NODE_ENV`. */
+  readonly force?: boolean;
+}
+/**
+ * Throw {@link MissingProductionMiddlewareError} if a required
+ * middleware is missing from the chain rooted at `provider`. The
+ * check runs only when `NODE_ENV === 'production'` unless `force` is
+ * `true`.
+ *
+ * @stable
+ */
+declare function assertProductionMiddleware(provider: Provider, options?: ProductionStartupHookOptions): void;
+//#endregion
+export { ProductionStartupHookOptions, assertProductionMiddleware };
+//# sourceMappingURL=production-hook.d.ts.map

package/dist/middleware/production-hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"production-hook.d.ts","names":[],"sources":["../../src/middleware/production-hook.ts"],"sourcesContent":[],"mappings":";;;;;;;;;UAmBiB,4BAAA;;2BAEU;;;;;;;;;;;;iBAaX,0BAAA,WACJ,oBACD"}

package/dist/middleware/production-hook.js

@@ -0,0 +1,21 @@
+import { MissingProductionMiddlewareError } from "../errors/errors.js";
+import { providerHasMiddleware } from "./compose.js";
+
+//#region src/middleware/production-hook.ts
+/**
+* Throw {@link MissingProductionMiddlewareError} if a required
+* middleware is missing from the chain rooted at `provider`. The
+* check runs only when `NODE_ENV === 'production'` unless `force` is
+* `true`.
+*
+* @stable
+*/
+function assertProductionMiddleware(provider, options = {}) {
+	if (!(process.env.NODE_ENV === "production") && options.force !== true) return;
+	const required = options.requiredKinds ?? ["withRedaction"];
+	for (const kind of required) if (!providerHasMiddleware(provider, kind)) throw new MissingProductionMiddlewareError(kind);
+}
+
+//#endregion
+export { assertProductionMiddleware };
+//# sourceMappingURL=production-hook.js.map

package/dist/middleware/production-hook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"production-hook.js","names":[],"sources":["../../src/middleware/production-hook.ts"],"sourcesContent":["/**\n * Production startup hook — fails fast when a security-critical\n * middleware is missing from the composed chain. The default\n * configuration enforces `withRedaction`; consumers can extend the\n * `requiredKinds` list to lock additional middlewares.\n *\n * @packageDocumentation\n */\n\nimport type { Provider } from '@graphorin/core';\n\nimport { MissingProductionMiddlewareError } from '../errors/errors.js';\nimport { providerHasMiddleware } from './compose.js';\n\n/**\n * Options for {@link assertProductionMiddleware}.\n *\n * @stable\n */\nexport interface ProductionStartupHookOptions {\n  /** Middleware kinds that must be present. Defaults to `['withRedaction']`. */\n  readonly requiredKinds?: ReadonlyArray<string>;\n  /** Force the check regardless of `NODE_ENV`. */\n  readonly force?: boolean;\n}\n\n/**\n * Throw {@link MissingProductionMiddlewareError} if a required\n * middleware is missing from the chain rooted at `provider`. The\n * check runs only when `NODE_ENV === 'production'` unless `force` is\n * `true`.\n *\n * @stable\n */\nexport function assertProductionMiddleware(\n  provider: Provider,\n  options: ProductionStartupHookOptions = {},\n): void {\n  const isProd = process.env.NODE_ENV === 'production';\n  if (!isProd && options.force !== true) return;\n  const required = options.requiredKinds ?? ['withRedaction'];\n  for (const kind of required) {\n    if (!providerHasMiddleware(provider, kind)) {\n      throw new MissingProductionMiddlewareError(kind);\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;AAkCA,SAAgB,2BACd,UACA,UAAwC,EAAE,EACpC;AAEN,KAAI,EADW,QAAQ,IAAI,aAAa,iBACzB,QAAQ,UAAU,KAAM;CACvC,MAAM,WAAW,QAAQ,iBAAiB,CAAC,gBAAgB;AAC3D,MAAK,MAAM,QAAQ,SACjB,KAAI,CAAC,sBAAsB,UAAU,KAAK,CACxC,OAAM,IAAI,iCAAiC,KAAK"}

package/dist/middleware/with-cost-limit.d.ts

@@ -0,0 +1,46 @@
+import * as _graphorin_core1 from "@graphorin/core";
+
+//#region src/middleware/with-cost-limit.d.ts
+
+/**
+ * `withCostLimit` — enforce per-session / per-run / per-agent /
+ * per-hour cost ceilings. Couples with {@link withCostTracking} for
+ * the underlying accumulator. The middleware is positioned between
+ * `withRateLimit` and `withCostTracking` per the canonical order so a
+ * budget breach trips before the request hits the underlying
+ * provider.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Options for {@link withCostLimit}.
+ *
+ * @stable
+ */
+interface WithCostLimitOptions {
+  /** Maximum cumulative USD cost per session. */
+  readonly maxPerSession?: number;
+  /** Maximum cumulative USD cost per run. */
+  readonly maxPerRun?: number;
+  /** Maximum cumulative USD cost per hour. */
+  readonly maxPerHour?: number;
+  /** What to do on breach. Default `'throw'`. */
+  readonly onExceed?: 'throw' | 'warn';
+  /**
+   * Resolver returning the current observed cost for the relevant
+   * scope. The resolver lets consumers wire any accumulator (the
+   * shipped `@graphorin/observability/cost.CostTracker` works out of
+   * the box). When unset, the middleware is a no-op (a placeholder
+   * for tooling that wires the accumulator later).
+   */
+  readonly resolveObservedCost?: (scope: 'session' | 'run' | 'hour', metadata: Readonly<Record<string, unknown>> | undefined) => number;
+  /** Optional sink for `'warn'` mode. Defaults to `console.warn`. */
+  readonly logger?: (message: string, meta?: object) => void;
+}
+/**
+ * @stable
+ */
+declare const withCostLimit: (opts: WithCostLimitOptions) => _graphorin_core1.ProviderMiddleware;
+//#endregion
+export { WithCostLimitOptions, withCostLimit };
+//# sourceMappingURL=with-cost-limit.d.ts.map

package/dist/middleware/with-cost-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-cost-limit.d.ts","names":[],"sources":["../../src/middleware/with-cost-limit.ts"],"sourcesContent":[],"mappings":";;;;;;;AAqBA;AA2BA;;;;;;;;;;;UA3BiB,oBAAA;;;;;;;;;;;;;;;;+EAkBH,SAAS;;;;;;;cASV,sBAAa,yBAAA,gBAAA,CAAA"}

package/dist/middleware/with-cost-limit.js

@@ -0,0 +1,66 @@
+import { CostBudgetExceededError } from "../errors/errors.js";
+import { defineProviderMiddleware } from "./compose.js";
+
+//#region src/middleware/with-cost-limit.ts
+/**
+* @stable
+*/
+const withCostLimit = defineProviderMiddleware({
+	kind: "withCostLimit",
+	factory: (opts) => {
+		const onExceed = opts.onExceed ?? "throw";
+		const resolver = opts.resolveObservedCost;
+		const logger = opts.logger ?? defaultLogger;
+		if ((opts.maxPerSession !== void 0 || opts.maxPerRun !== void 0 || opts.maxPerHour !== void 0) && resolver === void 0) logger("[graphorin/provider] withCostLimit: a cost ceiling is configured but no `resolveObservedCost` was supplied, so the limit is UNENFORCED (no-op). Wire a resolver (e.g. from createCostAccumulator / @graphorin/observability).");
+		return (next) => ({
+			name: next.name,
+			modelId: next.modelId,
+			capabilities: next.capabilities,
+			...next.acceptsSensitivity !== void 0 ? { acceptsSensitivity: next.acceptsSensitivity } : {},
+			stream(req) {
+				if (resolver !== void 0) check(asRecord(req.metadata), resolver, opts, onExceed, logger);
+				return next.stream(req);
+			},
+			async generate(req) {
+				if (resolver !== void 0) check(asRecord(req.metadata), resolver, opts, onExceed, logger);
+				return next.generate(req);
+			},
+			...next.countTokens ? { countTokens: next.countTokens.bind(next) } : {}
+		});
+	}
+});
+function check(metadata, resolver, opts, onExceed, logger) {
+	const checks = [
+		["session", opts.maxPerSession],
+		["run", opts.maxPerRun],
+		["hour", opts.maxPerHour]
+	];
+	for (const [scope, limit] of checks) {
+		if (limit === void 0) continue;
+		const observed = resolver(scope, metadata);
+		if (observed > limit) {
+			if (onExceed === "throw") throw new CostBudgetExceededError({
+				scope,
+				limit,
+				observed
+			});
+			logger(`[graphorin/provider] withCostLimit: ${scope} budget breach (${observed.toFixed(4)} > ${limit.toFixed(4)} USD).`, {
+				scope,
+				limit,
+				observed
+			});
+		}
+	}
+}
+function defaultLogger(message, meta) {
+	if (meta !== void 0) console.warn(message, meta);
+	else console.warn(message);
+}
+function asRecord(value) {
+	if (value === void 0 || value === null) return void 0;
+	return value;
+}
+
+//#endregion
+export { withCostLimit };
+//# sourceMappingURL=with-cost-limit.js.map

package/dist/middleware/with-cost-limit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-cost-limit.js","names":["checks: Array<['session' | 'run' | 'hour', number | undefined]>"],"sources":["../../src/middleware/with-cost-limit.ts"],"sourcesContent":["/**\n * `withCostLimit` — enforce per-session / per-run / per-agent /\n * per-hour cost ceilings. Couples with {@link withCostTracking} for\n * the underlying accumulator. The middleware is positioned between\n * `withRateLimit` and `withCostTracking` per the canonical order so a\n * budget breach trips before the request hits the underlying\n * provider.\n *\n * @packageDocumentation\n */\n\nimport type { Provider } from '@graphorin/core';\n\nimport { CostBudgetExceededError } from '../errors/errors.js';\nimport { defineProviderMiddleware } from './compose.js';\n\n/**\n * Options for {@link withCostLimit}.\n *\n * @stable\n */\nexport interface WithCostLimitOptions {\n  /** Maximum cumulative USD cost per session. */\n  readonly maxPerSession?: number;\n  /** Maximum cumulative USD cost per run. */\n  readonly maxPerRun?: number;\n  /** Maximum cumulative USD cost per hour. */\n  readonly maxPerHour?: number;\n  /** What to do on breach. Default `'throw'`. */\n  readonly onExceed?: 'throw' | 'warn';\n  /**\n   * Resolver returning the current observed cost for the relevant\n   * scope. The resolver lets consumers wire any accumulator (the\n   * shipped `@graphorin/observability/cost.CostTracker` works out of\n   * the box). When unset, the middleware is a no-op (a placeholder\n   * for tooling that wires the accumulator later).\n   */\n  readonly resolveObservedCost?: (\n    scope: 'session' | 'run' | 'hour',\n    metadata: Readonly<Record<string, unknown>> | undefined,\n  ) => number;\n  /** Optional sink for `'warn'` mode. Defaults to `console.warn`. */\n  readonly logger?: (message: string, meta?: object) => void;\n}\n\n/**\n * @stable\n */\nexport const withCostLimit = defineProviderMiddleware<WithCostLimitOptions>({\n  kind: 'withCostLimit',\n  factory: (opts: WithCostLimitOptions) => {\n    const onExceed = opts.onExceed ?? 'throw';\n    const resolver = opts.resolveObservedCost;\n    const logger = opts.logger ?? defaultLogger;\n    // PS-8: a ceiling without a resolver is a silent no-op — the limits look\n    // enforced but never trip. Warn loudly so the gap is visible. (No ceiling\n    // + no resolver is the documented inert placeholder, so it stays quiet.)\n    const hasCeiling =\n      opts.maxPerSession !== undefined ||\n      opts.maxPerRun !== undefined ||\n      opts.maxPerHour !== undefined;\n    if (hasCeiling && resolver === undefined) {\n      logger(\n        '[graphorin/provider] withCostLimit: a cost ceiling is configured but no ' +\n          '`resolveObservedCost` was supplied, so the limit is UNENFORCED (no-op). ' +\n          'Wire a resolver (e.g. from createCostAccumulator / @graphorin/observability).',\n      );\n    }\n    return (next: Provider): Provider => ({\n      name: next.name,\n      modelId: next.modelId,\n      capabilities: next.capabilities,\n      ...(next.acceptsSensitivity !== undefined\n        ? { acceptsSensitivity: next.acceptsSensitivity }\n        : {}),\n      stream(req) {\n        if (resolver !== undefined) {\n          check(asRecord(req.metadata), resolver, opts, onExceed, logger);\n        }\n        return next.stream(req);\n      },\n      async generate(req) {\n        if (resolver !== undefined) {\n          check(asRecord(req.metadata), resolver, opts, onExceed, logger);\n        }\n        return next.generate(req);\n      },\n      ...(next.countTokens ? { countTokens: next.countTokens.bind(next) } : {}),\n    });\n  },\n});\n\nfunction check(\n  metadata: Readonly<Record<string, unknown>> | undefined,\n  resolver: (\n    scope: 'session' | 'run' | 'hour',\n    metadata?: Readonly<Record<string, unknown>>,\n  ) => number,\n  opts: WithCostLimitOptions,\n  onExceed: 'throw' | 'warn',\n  logger: (message: string, meta?: object) => void,\n): void {\n  const checks: Array<['session' | 'run' | 'hour', number | undefined]> = [\n    ['session', opts.maxPerSession],\n    ['run', opts.maxPerRun],\n    ['hour', opts.maxPerHour],\n  ];\n  for (const [scope, limit] of checks) {\n    if (limit === undefined) continue;\n    const observed = resolver(scope, metadata);\n    if (observed > limit) {\n      if (onExceed === 'throw') {\n        throw new CostBudgetExceededError({ scope, limit, observed });\n      }\n      logger(\n        `[graphorin/provider] withCostLimit: ${scope} budget breach (${observed.toFixed(4)} > ${limit.toFixed(4)} USD).`,\n        { scope, limit, observed },\n      );\n    }\n  }\n}\n\nfunction defaultLogger(message: string, meta?: object): void {\n  if (meta !== undefined) console.warn(message, meta);\n  else console.warn(message);\n}\n\nfunction asRecord(value: unknown): Readonly<Record<string, unknown>> | undefined {\n  if (value === undefined || value === null) return undefined;\n  return value as Readonly<Record<string, unknown>>;\n}\n"],"mappings":";;;;;;;AAgDA,MAAa,gBAAgB,yBAA+C;CAC1E,MAAM;CACN,UAAU,SAA+B;EACvC,MAAM,WAAW,KAAK,YAAY;EAClC,MAAM,WAAW,KAAK;EACtB,MAAM,SAAS,KAAK,UAAU;AAQ9B,OAHE,KAAK,kBAAkB,UACvB,KAAK,cAAc,UACnB,KAAK,eAAe,WACJ,aAAa,OAC7B,QACE,gOAGD;AAEH,UAAQ,UAA8B;GACpC,MAAM,KAAK;GACX,SAAS,KAAK;GACd,cAAc,KAAK;GACnB,GAAI,KAAK,uBAAuB,SAC5B,EAAE,oBAAoB,KAAK,oBAAoB,GAC/C,EAAE;GACN,OAAO,KAAK;AACV,QAAI,aAAa,OACf,OAAM,SAAS,IAAI,SAAS,EAAE,UAAU,MAAM,UAAU,OAAO;AAEjE,WAAO,KAAK,OAAO,IAAI;;GAEzB,MAAM,SAAS,KAAK;AAClB,QAAI,aAAa,OACf,OAAM,SAAS,IAAI,SAAS,EAAE,UAAU,MAAM,UAAU,OAAO;AAEjE,WAAO,KAAK,SAAS,IAAI;;GAE3B,GAAI,KAAK,cAAc,EAAE,aAAa,KAAK,YAAY,KAAK,KAAK,EAAE,GAAG,EAAE;GACzE;;CAEJ,CAAC;AAEF,SAAS,MACP,UACA,UAIA,MACA,UACA,QACM;CACN,MAAMA,SAAkE;EACtE,CAAC,WAAW,KAAK,cAAc;EAC/B,CAAC,OAAO,KAAK,UAAU;EACvB,CAAC,QAAQ,KAAK,WAAW;EAC1B;AACD,MAAK,MAAM,CAAC,OAAO,UAAU,QAAQ;AACnC,MAAI,UAAU,OAAW;EACzB,MAAM,WAAW,SAAS,OAAO,SAAS;AAC1C,MAAI,WAAW,OAAO;AACpB,OAAI,aAAa,QACf,OAAM,IAAI,wBAAwB;IAAE;IAAO;IAAO;IAAU,CAAC;AAE/D,UACE,uCAAuC,MAAM,kBAAkB,SAAS,QAAQ,EAAE,CAAC,KAAK,MAAM,QAAQ,EAAE,CAAC,SACzG;IAAE;IAAO;IAAO;IAAU,CAC3B;;;;AAKP,SAAS,cAAc,SAAiB,MAAqB;AAC3D,KAAI,SAAS,OAAW,SAAQ,KAAK,SAAS,KAAK;KAC9C,SAAQ,KAAK,QAAQ;;AAG5B,SAAS,SAAS,OAA+D;AAC/E,KAAI,UAAU,UAAa,UAAU,KAAM,QAAO;AAClD,QAAO"}