@juspay/neurolink 12.17.0 → 12.17.2

package/dist/types/proxy.d.ts

@@ -1,3 +1,5 @@
+import type { ProxyTokenBudgetSnapshot } from "./proxyBudget.js";
+import type { ProxyContextEvidence, ProxyPreparedContext } from "./proxyContext.js";
 /**
  * Proxy type definitions for NeuroLink
  *
@@ -556,6 +558,27 @@ export type ProxyAccountSortMetrics = {
     scopedSaturated: boolean;
 };
 export type RequestLogEntry = {
+    /** Whether model identifies observed serving output rather than a routing target. */
+    servingModelStatus?: "observed" | "unavailable";
+    /** Whether retrying unchanged input can resolve this terminal failure. */
+    retryable?: boolean;
+    tokenBudget?: ProxyTokenBudgetSnapshot;
+    contextPreflight?: ProxyContextEvidence;
+    /** Internal adapter requests link to their one client-facing parent. */
+    parentRequestId?: string;
+    accountingScope?: "client" | "internal";
+    /** Exactly this request owns usage; bridge parents never duplicate it. */
+    usageOwnerRequestId?: string;
+    /** API price-table estimate, never a subscription charge or quota measure.
+     * Null when complete usage and an exact model rate are not both available. */
+    apiEquivalentCostUsd?: number | null;
+    /** API-equivalent cache-read savings against uncached input at the same rate. */
+    apiEquivalentCacheSavingsUsd?: number | null;
+    pricingStatus?: "exact" | "inferred" | "unavailable" | "usage_incomplete" | "owned_by_child";
+    pricingBasis?: "api_price_table";
+    pricingProvider?: string;
+    /** Credential identity is unavailable when the SDK does not expose it. */
+    accountIdentityStatus?: "observed" | "unavailable";
     /** First text, refusal or populated tool output, excluding SSE control frames. */
     firstUsefulOutputMs?: number;
     /** Why first-useful-output timing is absent; never substitute a zero. */
@@ -646,7 +669,10 @@ export type ProcessedProxyBodyCapture = {
     headers?: Record<string, string>;
     stored: StoredBodyArtifact;
     error?: string;
+    /** Admission plus worker queue time; retained for existing consumers. */
     queueWaitMs?: number;
+    admissionWaitMs?: number;
+    workerQueueWaitMs?: number;
     processingMs?: number;
     admission?: ProxyBodyCaptureAdmission;
 };
@@ -662,6 +688,11 @@ export type ProxyBodyCaptureAdmission = {
     maxPendingBytes: number;
 };
 export type ProxyBodyCaptureWorkerSnapshot = {
+    processing?: number;
+    publishing?: number;
+    oldestAdmissionWaitMs?: number;
+    oldestProcessingMs?: number;
+    oldestPublicationMs?: number;
     attempted: number;
     completed: number;
     rejected: number;
@@ -686,6 +717,13 @@ export type ProxyBodyDeliveryResult = {
     unconfirmedChunks: number;
     droppedChunks: number;
     notSubmittedChunks?: number;
+    /** Total publication elapsed time, including capacity and exporter waits. */
+    publicationMs?: number;
+    capacityWaitMs?: number;
+    /** Maximum per-chunk residence before an OTLP export starts. */
+    maxChunkQueueWaitMs?: number;
+    /** Maximum per-chunk transport duration; never sums overlapping exports. */
+    maxChunkExportMs?: number;
     reason?: string;
 };
 /** One bounded body publication, tracked across exporter callbacks. */
@@ -694,6 +732,8 @@ export type ProxyBodyPublicationProgress = {
     unconfirmed: number;
     dropped: number;
     emitted: number;
+    maxChunkQueueWaitMs?: number;
+    maxChunkExportMs?: number;
     notify?: () => void;
 };
 /** Bounded metadata-only evidence for an unconfirmed or locally rejected OTLP batch. */
@@ -714,6 +754,8 @@ export type ProxyTelemetryBackend = {
     baseUrl: string;
     organization: string;
     stream: string;
+    /** Optional separate backend storage for bulk body chunks. */
+    bodyStream?: string;
     authorization?: string;
     collectorMetricsUrl?: string;
 };
@@ -741,6 +783,10 @@ export type ProxyTelemetryDoctorOptions = {
     endTime: number;
     proxyUrl?: string;
     maxRows?: number;
+    /** Explicit age-search horizon; older admissions are outside this proof. */
+    admissionLookbackMs?: number;
+    requestTimeoutMs?: number;
+    ingestionGraceMs?: number;
     fetchImpl?: typeof fetch;
 };
 export type ProxyTelemetryCheck = {
@@ -766,6 +812,8 @@ export type ProxyTelemetryStoredRecord = Partial<RequestLogEntry> & {
     event?: string;
     telemetryStatus?: string;
     outcomeSource?: string;
+    requestTimeoutMs?: number;
+    redactionLossy?: boolean;
 };
 export type ProxyTelemetryFieldCoverage = {
     records: number;
@@ -786,6 +834,14 @@ export type ProxyRequestLoggerSnapshot = {
     debug: ProxyRequestLogSinkSnapshot;
 };
 export type RequestAttemptLogEntry = {
+    /** False for a local context/budget refusal before a provider call. */
+    upstreamDispatched?: boolean;
+    /** Client model name retained independently of the dispatched model. */
+    requestedModel?: string;
+    tokenBudget?: ProxyTokenBudgetSnapshot;
+    contextPreflight?: ProxyContextEvidence;
+    accountingScope?: "client" | "internal";
+    usageOwnerRequestId?: string;
     timestamp: string;
     requestId: string;
     /** Parent client request for an internal fallback invocation. */
@@ -825,10 +881,14 @@ export type RequestAttemptLogEntry = {
     quotaResetAt?: number;
     /** Unknown scope never implies an account-wide long-window rejection. */
     quotaScope?: "session" | "weekly" | "unknown";
+    /** True when input includes the cache breakdown (native Codex wire usage). */
+    inputIncludesCachedTokens?: boolean;
     inputTokens?: number;
     outputTokens?: number;
     cacheCreationTokens?: number;
     cacheReadTokens?: number;
+    /** Reasoning tokens are a subset of output, never additional usage. */
+    reasoningTokens?: number;
     /** Provider that received this upstream attempt. */
     provider?: string;
     /** OTel trace ID for correlation with distributed traces */
@@ -839,9 +899,9 @@ export type RequestAttemptLogEntry = {
     traceFlags?: number;
 };
 /** Additional fields recorded when a Codex response becomes client-final. */
-export type CodexFinalLogExtra = Partial<Pick<RequestLogEntry, "errorType" | "errorMessage" | "errorCode" | "transportScope" | "inputTokens" | "outputTokens" | "cacheReadTokens" | "cacheCreationTokens" | "reasoningTokens" | "terminalOutcome" | "firstUsefulOutputMs" | "firstUsefulOutputStatus" | "firstUsefulOutputEvent">>;
+export type CodexFinalLogExtra = Partial<Pick<RequestLogEntry, "errorType" | "errorMessage" | "errorCode" | "transportScope" | "inputTokens" | "outputTokens" | "cacheReadTokens" | "cacheCreationTokens" | "reasoningTokens" | "terminalOutcome" | "firstUsefulOutputMs" | "firstUsefulOutputStatus" | "firstUsefulOutputEvent" | "retryable">>;
 /** Additional fields recorded for each upstream Codex account attempt. */
-export type CodexAttemptLogExtra = Partial<Pick<RequestAttemptLogEntry, "errorType" | "errorMessage" | "errorCode" | "transportScope" | "retryable" | "rateLimitKind" | "cooldownReason" | "quotaResetAt" | "quotaScope">>;
+export type CodexAttemptLogExtra = Partial<Pick<RequestAttemptLogEntry, "inputTokens" | "outputTokens" | "cacheReadTokens" | "cacheCreationTokens" | "reasoningTokens" | "inputIncludesCachedTokens" | "errorType" | "errorMessage" | "errorCode" | "transportScope" | "retryable" | "rateLimitKind" | "cooldownReason" | "quotaResetAt" | "quotaScope">>;
 /** Minimal persistence contract needed by Codex rotating-token refreshes. */
 export type CodexRefreshTokenStore = {
     peekTokens(provider: string): Promise<StoredOAuthTokens | null>;
@@ -876,6 +936,7 @@ export type ClaudeFinalRequestLogger = (status: number, accountLabel: string, ac
     cacheReadTokens?: number;
     reasoningTokens?: number;
     errorCode?: string;
+    retryable?: boolean;
     transportScope?: ProxyTransportScope;
 }) => void;
 export type ClaudeLoggedErrorBuilder = (status: number, message: string, errorType?: string, extra?: {
@@ -883,6 +944,7 @@ export type ClaudeLoggedErrorBuilder = (status: number, message: string, errorTy
     accountType?: string;
     attempt?: number;
     errorCode?: string;
+    retryable?: boolean;
     transportScope?: ProxyTransportScope;
 }) => ClaudeErrorResponse;
 export type ClaudeRequestRuntimeContext = {
@@ -935,6 +997,7 @@ export type AnthropicLoopState = {
 export type AnthropicUpstreamBody = {
     bodyStr: string;
     sessionId?: string;
+    preparedContext: ProxyPreparedContext<ClaudeRequest>;
 };
 export type AnthropicUpstreamBodyBuilder = (token: string) => AnthropicUpstreamBody;
 export type LoadedClaudeAccountContext = {
@@ -1044,6 +1107,7 @@ export type PreparedAnthropicAccountAttempt = {
     headers?: Record<string, string>;
     buildUpstreamBody?: AnthropicUpstreamBodyBuilder;
     finalBodyStr?: string;
+    preparedContext?: ProxyPreparedContext<ClaudeRequest>;
     fetchStartMs?: number;
     upstreamSpan?: Span;
 };
@@ -1681,8 +1745,12 @@ export type ProxyRequestContext = {
      * every non-Anthropic model prices to $0.
      */
     provider?: string;
-    /** An internal fallback is an attempt; its parent owns request/token metrics. */
+    /** Whether this span owns client request, latency, and error metrics. */
     recordRequestMetrics?: boolean;
+    /** Provider usage ownership. Defaults to recordRequestMetrics for backwards
+     * compatibility: internal Codex fallback spans suppress both, while bridge
+     * children explicitly retain usage and their parent owns client outcomes. */
+    recordUsageMetrics?: boolean;
 };
 /** Response-side details parsed from the upstream reply (model, finish, tools). */
 export type ResponseInfoContext = {
@@ -1722,6 +1790,11 @@ export type UsageContext = {
     rateLimitAfter5h?: number;
     rateLimitAfter7d?: number;
 };
+/** Keep trace usage when a child request owns its token and cost metrics. */
+export type ProxyUsageAttributionOptions = {
+    /** Defaults to the tracer's configured ownership when omitted. */
+    recordMetrics?: boolean;
+};
 /** Where a proxy env file path was sourced from. */
 export type ProxyEnvSource = "cli" | "environment" | "default" | "none";
 /** Result of resolving which proxy env file to load. */
@@ -1765,6 +1838,11 @@ export type ProxyActivitySnapshot = {
 export type ProxyRuntimeActivity = {
     activeRequests: number;
     lastActivityAt: string | null;
+    /** Supervisor-wide resources that must settle before process replacement. */
+    drainingWorkers?: number;
+    queuedSockets?: number;
+    pendingTransfers?: number;
+    candidateWorkers?: number;
 };
 /** Terminal state observed while the HTTP adapter relays a response body. */
 export type ProxyResponseTerminalOutcome = "completed" | "bodyless" | "client_cancelled" | "stream_error";
@@ -1790,6 +1868,13 @@ export type ProxyLifecycleEventName = "runtime_sample" | "supervisor_event" | "r
 export type ProxyLifecycleTerminalOutcome = ProxyResponseTerminalOutcome | "handler_error" | "unknown";
 /** Content-free lifecycle event accepted by the bounded metadata logger. */
 export type ProxyLifecycleEventInput = {
+    /** Hard admission-to-terminal deadline used by reconciliation. */
+    requestTimeoutMs?: number;
+    /** Internal adapter requests link to their one client-facing parent. */
+    parentRequestId?: string;
+    accountingScope?: "client" | "internal";
+    /** Exactly this request owns usage; bridge parents never duplicate it. */
+    usageOwnerRequestId?: string;
     event: ProxyLifecycleEventName;
     requestId: string;
     method: string;
@@ -1976,6 +2061,9 @@ export type ProxyAnalysisReport = {
             providerFinalRecorded: boolean;
         }>;
         accepted: number;
+        internalAccepted?: number;
+        internalTerminal?: number;
+        internalUnsettled?: number;
         /** Accepted metadata requests that do not require model final records. */
         auxiliaryRequests: number;
         headers: number;
@@ -1988,6 +2076,8 @@ export type ProxyAnalysisReport = {
     };
     requests: {
         completed: number;
+        /** Linked internal adapter finals excluded from client request totals. */
+        internalCompleted?: number;
         success: number;
         errors: number;
         finalRateLimits: number;
@@ -2075,6 +2165,9 @@ export type ProxyAnalysisAttemptRecord = {
 };
 /** Final request fields retained while joining offline proxy log records. */
 export type ProxyAnalysisFinalRequestRecord = {
+    accountingScope?: "client" | "internal";
+    parentRequestId?: string;
+    usageOwnerRequestId?: string;
     firstUsefulOutputMs: number | null;
     timestamp: string;
     status: number;
@@ -2114,6 +2207,9 @@ export type ProxyCancellableTransformer<I, O> = Transformer<I, O> & {
  * a null result as "not observed", never as "zero tokens".
  */
 export type CodexStreamUsage = {
+    /** Distinguish missing provider usage from a reported zero. */
+    inputTokensObserved?: boolean;
+    outputTokensObserved?: boolean;
     inputTokens: number;
     outputTokens: number;
     cacheReadTokens: number;
@@ -2146,6 +2242,12 @@ export type ProxyAnalysisRoutingRecord = {
 };
 /** Request metadata retained by the HTTP adapter for terminal error logging. */
 export type RuntimeRequestMetadata = {
+    /** Internal adapter requests link to their one client-facing parent. */
+    parentRequestId?: string;
+    accountingScope?: "client" | "internal";
+    /** Exactly this request owns usage; bridge parents never duplicate it. */
+    usageOwnerRequestId?: string;
+    abortController?: AbortController;
     /** Last dispatched attempt, retained until this HTTP request terminates. */
     lastUpstreamAttempt?: RequestAttemptLogEntry;
     requestId: string;
@@ -2331,6 +2433,14 @@ export type CompareProxyReplayOptions = {
 };
 /** Persisted artifact produced when a body is stored to disk. */
 export type StoredBodyArtifact = {
+    /** Bytes supplied to redaction, after any source observer limit. */
+    inputRetainedBytes?: number;
+    inputEncoding?: "utf8_text" | "structured_object";
+    sourceTruncated?: boolean;
+    processingTruncated?: boolean;
+    /** Invalid structured frames were removed for secret safety. */
+    redactionLossy?: boolean;
+    unparseableRedactedFrames?: number;
     bodyPath?: string;
     bodySha256?: string;
     redactedBodyBytes?: number;
@@ -4029,4 +4139,39 @@ type ProxyBodyCaptureWaitingSnapshot = {
     admissionWaits: number;
     admissionTimeouts: number;
 };
+/** Immutable package selection used by the proxy launcher, never by global npm. */
+export type ProxyPackageSelection = {
+    version: string;
+    entryScript: string;
+    nodePath: string;
+};
+/** Atomically published active and rollback package selections. */
+export type ProxyPackageSelectionState = {
+    schemaVersion: 1;
+    active: ProxyPackageSelection | null;
+    previous: ProxyPackageSelection | null;
+};
+/** Bounded asynchronous package installation with injectable subprocesses. */
+export type ProxyStagedInstallOptions = {
+    version: string;
+    packagesDir: string;
+    installer: Pick<GlobalInstallerProbe, "kind" | "bin">;
+    idleTimeoutMs?: number;
+    maxDurationMs?: number;
+    killGraceMs?: number;
+    spawn?: typeof import("node:child_process").spawn;
+    execFileSync?: GlobalInstallerExecFile;
+    onProgress?: (progress: {
+        elapsedMs: number;
+        outputBytes: number;
+    }) => void;
+};
+/** Saved launchd settings retained when installing the service again. */
+export type ProxyServiceInstallSettings = {
+    envFile?: string;
+    configFile?: string;
+    host?: string;
+    port?: number;
+    environment: Record<string, string>;
+};
 export {};

package/dist/types/proxy.js

@@ -1,16 +1 @@
-/**
- * Proxy type definitions for NeuroLink
- *
- * Consolidates all proxy-related types from:
- * - src/lib/proxy/claudeFormat.ts (Claude API types, SSE types, internal result)
- * - src/lib/proxy/cloaking/types.ts (cloaking pipeline types)
- * - src/lib/proxy/cloaking/plugins/ (plugin option types)
- * - src/lib/proxy/modelRouter.ts (routing types)
- * - src/lib/proxy/proxyConfig.ts (config file types)
- * - src/lib/proxy/requestLogger.ts (log entry type)
- * - src/lib/proxy/usageStats.ts (stats types)
- * - src/lib/proxy/tokenRefresh.ts (refresh types)
- * - src/lib/proxy/accountQuota.ts (quota type)
- * - src/lib/server/routes/claudeProxyRoutes.ts (runtime state, deps)
- */
 export {};

package/dist/types/proxyBudget.d.ts

@@ -0,0 +1,74 @@
+/** Operator-configured proxy token caps. All caps are optional and disabled by default. */
+export type ProxyTokenBudgetPolicy = {
+    /** Per-provider/account estimated outstanding input plus maximum output. */
+    maxInFlightTokens?: number;
+    /** Charged tokens in the account's fixed window, including outstanding reservations. */
+    accountWindowTokens?: number;
+    /** Charged tokens across providers/accounts sharing the same client session. */
+    sessionWindowTokens?: number;
+    windowMs?: number;
+};
+export type ProxyTokenBudgetReservation = {
+    provider: string;
+    accountKey: string;
+    sessionKey: string;
+    requestId: string;
+    reservationTokens: number;
+    policy?: ProxyTokenBudgetPolicy;
+    estimateProvenance?: string;
+};
+export type ProxyTokenBudgetSnapshot = {
+    scope: "disabled" | "process" | "supervisor";
+    reservationTokens: number;
+    accountChargedTokens: number;
+    accountInFlightTokens: number;
+    sessionChargedTokens: number;
+    sessionInFlightTokens: number;
+    windowMs: number;
+    estimateProvenance: string;
+    settlement?: "provider_reported" | "estimate_retained" | "cancelled_before_dispatch" | "unconfirmed";
+};
+export type ProxyTokenBudgetLease = {
+    leaseId: string;
+    snapshot: ProxyTokenBudgetSnapshot;
+    settle: (actualTotalTokens?: number) => Promise<void>;
+    cancelBeforeDispatch: () => Promise<void>;
+};
+export type ProxyTokenBudgetBucket = {
+    chargedTokens: number;
+    inFlightTokens: number;
+    startedAt: number;
+    windowMs: number;
+    lastTouched: number;
+};
+export type ProxyTokenBudgetRecord = {
+    owner: string;
+    accountKey: string;
+    sessionKey: string;
+    estimate: number;
+    snapshot: ProxyTokenBudgetSnapshot;
+};
+export type ProxyTokenBudgetRpcRequest = {
+    type: "proxy-budget:request";
+    rpcId: string;
+    pid: number;
+    generation: number;
+    action: "reserve" | "settle" | "cancel";
+    reservation?: ProxyTokenBudgetReservation;
+    leaseId?: string;
+    actualTotalTokens?: number;
+};
+export type ProxyTokenBudgetRpcResponse = {
+    type: "proxy-budget:response";
+    rpcId: string;
+    ok: boolean;
+    leaseId?: string;
+    snapshot?: ProxyTokenBudgetSnapshot;
+    errorCode?: string;
+    error?: string;
+};
+export type ProxyTokenBudgetRpcPending = {
+    resolve: (result: ProxyTokenBudgetRpcResponse) => void;
+    reject: (error: Error) => void;
+    timer: NodeJS.Timeout;
+};

package/dist/types/proxyBudget.js

@@ -0,0 +1 @@
+export {};

package/dist/types/proxyContext.d.ts

@@ -0,0 +1,35 @@
+/** Explicit proxy context controls; all token quantities remain estimates. */
+export type ProxyContextPolicy = {
+    maxInputTokens?: number;
+    outputReserveTokens?: number;
+    enforceDiscoveredLimits?: boolean;
+    toolAllowlist?: string[];
+    models?: Record<string, {
+        contextWindow: number;
+        maxOutputTokens?: number;
+    }>;
+};
+export type ProxyContextEvidence = {
+    provider: string;
+    model: string;
+    inputTokensEstimate: number;
+    toolsTokensEstimate: number;
+    instructionsTokensEstimate: number;
+    schemaTokensEstimate: number;
+    outputTokensReserve: number;
+    reasoningIncludedInOutputReserve: true;
+    contextWindow?: number;
+    contextLimitSource: "configured" | "discovered" | "unknown";
+    tokenCountSource: "estimated";
+    multimodalEstimate: boolean;
+    originalToolCount: number;
+    retainedToolCount: number;
+    historyModified: false;
+};
+export type ProxyPreparedContext<T> = {
+    body: T;
+    inputTokensEstimate: number;
+    outputTokensReserve: number;
+    totalTokensReservation: number;
+    evidence: ProxyContextEvidence;
+};

package/dist/types/proxyContext.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/toolChoice.d.ts

@@ -2,3 +2,22 @@ import type { Tool, ToolChoice } from "../types/index.js";
 export declare function resolveToolChoice(options: {
     toolChoice?: ToolChoice<Record<string, Tool>>;
 }, tools: Record<string, Tool> | undefined, shouldUseTools: boolean): ToolChoice<Record<string, Tool>> | "none";
+/**
+ * Normalise an already-resolved tool choice into the shape
+ * `toolChoiceToAnthropic` (and its peers) accept.
+ *
+ * A provider's model handle sees a value that has *already* been through
+ * `resolveToolChoice` upstream, so it must translate rather than re-resolve —
+ * re-resolving there would apply the `auto`/`none` defaulting twice, and the
+ * `tools`/`shouldUseTools` inputs it needs are not in scope at that layer
+ * anyway.
+ *
+ * What does vary is the shape. The value arrives either as a bare string
+ * (`"auto"` / `"none"` / `"required"`), as `{ type: "tool", toolName }`, or —
+ * on the native loop's tool-free re-ask — as an injected `{ type: "none" }`
+ * object. Reading `.type` off the string forms yields `undefined`, which is
+ * how string choices were silently dropped from the Anthropic generate
+ * request. This exists so that normalisation lives in one place instead of
+ * being re-derived at each call site.
+ */
+export declare function normalizeResolvedToolChoice(value: unknown): ToolChoice<Record<string, Tool>> | undefined;

package/dist/utils/toolChoice.js

@@ -4,3 +4,42 @@ export function resolveToolChoice(options, tools, shouldUseTools) {
     }
     return options.toolChoice ?? "auto";
 }
+/**
+ * Normalise an already-resolved tool choice into the shape
+ * `toolChoiceToAnthropic` (and its peers) accept.
+ *
+ * A provider's model handle sees a value that has *already* been through
+ * `resolveToolChoice` upstream, so it must translate rather than re-resolve —
+ * re-resolving there would apply the `auto`/`none` defaulting twice, and the
+ * `tools`/`shouldUseTools` inputs it needs are not in scope at that layer
+ * anyway.
+ *
+ * What does vary is the shape. The value arrives either as a bare string
+ * (`"auto"` / `"none"` / `"required"`), as `{ type: "tool", toolName }`, or —
+ * on the native loop's tool-free re-ask — as an injected `{ type: "none" }`
+ * object. Reading `.type` off the string forms yields `undefined`, which is
+ * how string choices were silently dropped from the Anthropic generate
+ * request. This exists so that normalisation lives in one place instead of
+ * being re-derived at each call site.
+ */
+export function normalizeResolvedToolChoice(value) {
+    if (typeof value === "string") {
+        return value;
+    }
+    if (value && typeof value === "object") {
+        const candidate = value;
+        if (candidate.type === "tool") {
+            // A tool choice that names no tool cannot be honoured. Fall through to
+            // the provider default rather than emitting the bare string "tool",
+            // which is not one of the valid auto/none/required forms and would be
+            // rejected downstream.
+            return candidate.toolName
+                ? { type: "tool", toolName: candidate.toolName }
+                : undefined;
+        }
+        if (candidate.type) {
+            return candidate.type;
+        }
+    }
+    return undefined;
+}

package/docs/assets/dashboards/README.md

@@ -0,0 +1,37 @@
+# Proxy dashboard accounting
+
+Import `neurolink-proxy-observability-dashboard.json` into OpenObserve after
+the matching proxy release emits the indexed accounting and pricing fields.
+The template is an artifact; changing it does not update an installed dashboard
+or activate a proxy release. Request panels query the metadata log stream.
+Bulk body captures can use a separate stream.
+
+Client traffic, errors, and latency belong to the outer request. An internal
+bridge request owns provider usage when `proxy_usage_owner_request_id` names
+that child; the parent contributes no second token charge. Cached input is
+included once according to `ai_input_includes_cached_tokens`.
+
+Log queries first collapse exact producer retries, ignoring ingestion-time
+changes. The stable identity combines service instance and producer event ID;
+older records fall back to request ID where available. Contradictory payloads
+under one identity are excluded from aggregate totals. The Traffic & Health
+conflict counter reports those exclusions. A nonzero counter means totals
+cover only the verified subset; use telemetry doctor for the conflicting raw
+payloads. Rows without any stable identity cannot establish retry deduplication.
+
+Cost panels sum `ai_cost_api_equivalent_usd` only when
+`ai_pricing_status='exact'`. These are estimates from this release's API price
+table and complete provider usage, **not subscription charges or quota usage**.
+Prefix-inferred prices, missing rates, partial token usage, and a bridge parent's
+delegated usage do not receive an invented dollar amount. Pricing-gap panels
+show the excluded usage owners; a blank known-cost total is not zero spending.
+Cache savings compare cache reads with the same table's uncached input rate.
+The offline analyzer's historical estimates separately retain their existing
+`requestsPricedByPrefix` and `modelsPricedByPrefix` disclosures.
+
+The deterministic capture-pipeline suite executes the shipped request, token,
+cost, and conflict SQL on an in-memory database and records exact price-table,
+partial-usage, and unknown-model OTLP fixtures. SQLite validates the standard SQL
+logic; verify field availability and query compatibility in the target
+OpenObserve version when installing the dashboard. Metric panels retain their
+scrape/window semantics and are not a substitute for reconciled request logs.