dsh-opencode-go 0.1.23 → 0.2.0

package/lib/types/accounts.d.ts

@@ -1,33 +1,98 @@
-/** Client-safe account metadata. Secrets stay in the host credential service. */
-import type { GoAccountOperation } from './account-operations.ts';
-export type GoAccount = {
-    id: string;
-    name: string;
-    apiKeyEnv: string;
-};
-export declare const MAX_ACCOUNTS = 20;
-export declare const ACCOUNT_REF_PREFIX = "DSH_OPENCODE_GO_ACCOUNT_";
-export declare const DEFAULT_ACCOUNT_REF = "OPENCODE_API_KEY";
-/** A credential reference is a bare environment variable name, never empty or decorated. */
-export declare const ACCOUNT_REF_PATTERN: RegExp;
-export interface AccountSettings {
-    apiKeyEnv?: string;
-    /** Omission/null preserves legacy credentials; an explicit empty list removes all accounts. */
-    accounts?: readonly GoAccount[] | null;
-    autoSwitch?: boolean;
-    /** Recovery intentions owned by this exact settings/profile document. */
-    accountOperations?: readonly GoAccountOperation[];
+/** Serialized account commands, primary selection and official quota reads. */
+import { type SettingsWriteResult, type GoAccountSwitch, type AccountCommand, type GoUsage } from './contracts.ts';
+import { type CredentialProvider } from '@deepseek-ai/dsh-credentials';
+import type { GoAccountSettlement } from './adapter.ts';
+import { type OpencodeGoConfig } from './config.ts';
+import type { Context } from '@deepseek-ai/cordis';
+import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+import { ProxyTransport } from './transport.ts';
+export interface AccountSettingsWriter {
+    describe(): readonly {
+        ns: string;
+        revision: number;
+        value: unknown;
+    }[];
+    mutate(ns: string, ops: readonly {
+        op: 'set';
+        path: string[];
+        value: unknown;
+    }[], expectedRevision?: number): Promise<unknown>;
 }
-export declare function accountRefOf(settings: AccountSettings): string;
-/** Promote one account while preserving every other account's relative order. */
-export declare function moveAccountFirst(accounts: readonly GoAccount[], ref: string): readonly GoAccount[];
-/** Read legacy selections as the first account until the host persists their order. */
-export declare function accountsOf(settings: AccountSettings): readonly GoAccount[];
-export declare function assertAccounts(accounts: readonly GoAccount[] | null | undefined, selectedRef?: string): void;
-/** Safe UI notice for a successful request using a fallback account. */
-export interface GoAccountSwitch {
-    fromRef: string;
-    toRef: string;
-    reason: 'quota' | 'credential';
-    at: number;
+/** Locate the profile entry that owns this mount's account metadata. */
+export declare function accountSettingsRow(settings: AccountSettingsWriter): {
+    ns: string;
+    revision: number;
+    value: unknown;
+} | undefined;
+export interface AttemptOutcome {
+    failure?: {
+        code: string;
+    };
+    emitted: boolean;
+    totalTokens: number;
+    aborted: boolean;
+    hasNext: boolean;
 }
+/** Switching accounts must never replay output or already charged work. */
+export declare function accountFallback(outcome: AttemptOutcome): GoAccountSwitch['reason'] | undefined;
+/** Gateway credential, rate and quota failures cool down this account for five minutes. */
+export declare function isGatewayKeyRejection(failure: {
+    code: string;
+}): boolean;
+type AccountCredentials = Pick<CredentialProvider, 'describe' | 'resolve' | 'set' | 'unset'>;
+/** One mount serializes account edits, credential writes and fallback promotion in memory. */
+export declare class GoAccountManager {
+    private readonly config;
+    private readonly logger;
+    private connection;
+    private queue;
+    private generation;
+    private signature;
+    private credentialGeneration;
+    private latestSeq;
+    private notice;
+    constructor(config: () => OpencodeGoConfig, logger: {
+        warn(message: string): void;
+    });
+    connect(settings: AccountSettingsWriter, credentials: AccountCredentials): () => void;
+    private enqueue;
+    private read;
+    private write;
+    execute(raw: AccountCommand): Promise<SettingsWriteResult>;
+    private executeCommand;
+    /** A freshness fence prevents an old request from overriding a later user choice. */
+    capture(): number;
+    credentialChanged(): void;
+    lastSwitch(): GoAccountSwitch | undefined;
+    settle(event: GoAccountSettlement): void;
+}
+/** The browser sends commands; the host owns credentials and metadata writes. */
+export declare class GoAccountsService extends TypertRemoteService {
+    private readonly options;
+    constructor(ctx: Context, options: {
+        manager: GoAccountManager;
+    });
+    execute(command: AccountCommand): Promise<SettingsWriteResult>;
+}
+interface UsageOptions {
+    baseURL: () => string;
+    proxyURL?: () => string;
+    transport?: ProxyTransport;
+    resolveApiKey: (ref?: string) => Promise<string | undefined>;
+    activeRef?: () => string;
+    accountRefs?: () => readonly string[];
+    lastSwitch?: () => GoAccountSwitch | undefined;
+}
+/** Account statistics are fetched on the Host; credentials never enter the browser. */
+export declare class GoUsageService extends TypertRemoteService {
+    private readonly options;
+    private readonly identities;
+    private readonly pending;
+    private readonly transport;
+    constructor(ctx: Context, options: UsageOptions);
+    read(): Promise<GoUsage>;
+    readAccount(ref: string): Promise<GoUsage>;
+    private readRef;
+    private fetchUsage;
+}
+export {};

package/lib/types/adapter.d.ts

@@ -1,35 +1,21 @@
-/**
- * The OpenCode Go adapter: one route, one catalog, per-request routing header.
- *
- * Every request to the gateway carries two Harness-owned headers: the
- * attribution User-Agent (`deepseek-harness/<version>`), which pi-ai's client
- * lets request headers override, and `x-opencode-session`, which the gateway
- * requires and uses to route a conversation and share its prompt cache. The
- * header value is the request's session id, stable across continuation and
- * restore. Actual cache reads remain an upstream usage fact. A request with no
- * session id gets a fresh random value rather than a shared constant, because
- * a constant would merge unrelated traffic into one cache bucket.
- *
- * Multi-turn correctness rides on the shared pi-ai conversion machinery
- * (`toPiContext` reconstructs provider-native replay state from the session
- * log; `toStreamChunks` maps events to seam chunks), so assistant history,
- * tool calls, and usage land in the session log exactly as the generic pi-ai
- * adapter records them. Image content rides the same machinery: models whose
- * catalog entry declares the image modality convert attachments through the
- * durable attachment service, and every other model refuses image content
- * before any provider I/O.
- *
- * @module dsh-llm-opencode-go/adapter
- */
-import { LlmAdapter } from '@deepseek-ai/dsh-llm';
-import type { GenerateOptions, ImageAttachmentAccess, LlmModelInfo, LlmResolvedModelInfo, StreamChunk } from '@deepseek-ai/dsh-llm';
+/** Request snapshots, SDK dispatch, deadlines and seamless account fallback. */
+import { type OpencodeGoModelLimits, type GoAccountSwitch } from './contracts.ts';
+import { type GenerateOptions, type ImageAttachmentAccess, type StreamChunk, LlmAdapter, type LlmModelInfo, type LlmResolvedModelInfo } from '@deepseek-ai/dsh-llm';
 import type { AttachmentStore, ImageAttachmentRef } from '@deepseek-ai/dsh-attachment';
+import type { Api, Model, Provider } from './sdk-types.ts';
+import { type OpencodeGoConfig } from './config.ts';
+import { ProxyTransport } from './transport.ts';
 import { OpencodeGoCatalog } from './catalog.ts';
-import { ProxyTransport } from './proxy.ts';
-import type { OpencodeGoConfig } from './config.ts';
-import { type GoAccountSwitch } from './accounts.ts';
-import { type GoCallTrace } from './call-trace.ts';
-export type { GoCallTrace } from './call-trace.ts';
+/**
+ * Reserve 64k by default only for deepseek-v4.1-flash. Other models retain the
+ * SDK's default when neither the caller nor settings specify an allowance.
+ * Per-model settings continue to cap caller values for every model. The model
+ * has already had capacity overrides applied.
+ */
+export declare function requestMaxTokens(model: {
+    id: string;
+    maxTokens: number;
+}, limits: OpencodeGoModelLimits, requested?: number): number | undefined;
 /**
  * The attachment-service bridges one image request reads. Construction-time
  * (context-dependent); the config-dependent policy numbers are merged per
@@ -41,6 +27,33 @@ export interface OpencodeGoImageAccess {
     /** Bridge one attachment reference into the current model-tool execution world. */
     resolveImageAccess: (attachments: AttachmentStore, ref: ImageAttachmentRef) => ImageAttachmentAccess | undefined;
 }
+/** Host dependencies used by a single attempt, independent of account selection. */
+export interface OpencodeGoRequestExecutorOptions {
+    /** Resolve the credential reference captured with this call's endpoint; missing must fail loud. */
+    resolveApiKey: (config: OpencodeGoConfig, signal?: AbortSignal) => Promise<string | undefined>;
+    /**
+     * Image input machinery; absent refuses image content, which is the posture
+     * for direct construction without a durable attachment service behind it.
+     */
+    imageAccess?: OpencodeGoImageAccess;
+    /** Observe assistant history degrading to provider-neutral conversion. */
+    onReplayDegrade?: (reason: string) => void;
+}
+/** Inputs already resolved by the adapter, including one account and the wire session ID. */
+export interface OpencodeGoRequestSnapshot {
+    config: OpencodeGoConfig;
+    model: Model<Api>;
+    provider: Provider;
+    sessionId: string;
+}
+/** Shares the adapter's transport without owning its lifetime or retrying accounts. */
+export declare class OpencodeGoRequestExecutor {
+    private readonly options;
+    private readonly transport;
+    constructor(options: OpencodeGoRequestExecutorOptions, transport: ProxyTransport);
+    /** One account, one SDK attempt; host recovery still owns failures after output. */
+    stream(options: GenerateOptions, snapshot: OpencodeGoRequestSnapshot): AsyncIterable<StreamChunk>;
+}
 /** One request's serving account, with the identity captured before discovery. */
 export interface GoAccountSettlement {
     seq: number;
@@ -50,28 +63,17 @@ export interface GoAccountSettlement {
     notice?: GoAccountSwitch;
 }
 /** Constructor inputs for {@link OpencodeGoAdapter}. */
-export interface OpencodeGoAdapterOptions {
+export interface OpencodeGoAdapterOptions extends OpencodeGoRequestExecutorOptions {
     /** Shared with Host usage reads for this plugin mount. */
     transport?: ProxyTransport;
     /** Mount-owned discovery; direct construction supplies its own manager. */
     catalog?: (config: OpencodeGoConfig) => OpencodeGoCatalog;
-    /** Optional directory for bounded HTTP error evidence; request contents are omitted. */
-    debugDirectory?: () => string | undefined;
     /**
      * The current configuration, re-read at every operation: a settings write
      * reaches the next request without a restart, and one operation never mixes
      * two configuration generations.
      */
     config: () => OpencodeGoConfig;
-    /** Resolve the credential reference captured with this call's endpoint; missing must fail loud. */
-    resolveApiKey: (config: OpencodeGoConfig, signal?: AbortSignal) => Promise<string | undefined>;
-    /** Observe one bounded, content-free summary for every dispatched call. */
-    onCallTrace?: (trace: GoCallTrace) => void;
-    /**
-     * Image input machinery; absent refuses image content, which is the posture
-     * for direct construction without a durable attachment service behind it.
-     */
-    imageAccess?: OpencodeGoImageAccess;
     /** Observe the catalog falling back to the curated table. */
     onFallback?: (detail: {
         url: string;
@@ -81,8 +83,6 @@ export interface OpencodeGoAdapterOptions {
     /** Observe live ids the curated table cannot route. */
     onOmitted?: (ids: readonly string[]) => void;
     onCatalogWarning?: (warning: string) => void;
-    /** Observe assistant history degrading to provider-neutral conversion. */
-    onReplayDegrade?: (reason: string) => void;
     /** Re-read picker models after a background catalog refresh commits. */
     onCatalogRefresh?: () => void;
     /** Host account-state version for actual requests, captured before asynchronous model discovery. */
@@ -101,6 +101,7 @@ export declare class OpencodeGoAdapter extends LlmAdapter {
     private readonly options;
     private readonly resolveCatalog;
     private readonly transport;
+    private readonly requestExecutor;
     /** Per-reference rejection deadlines, isolated by the gateway that rejected it. */
     private readonly rejectedKeys;
     /** Reference updates invalidate rejections from attempts using an older key. */
@@ -130,10 +131,8 @@ export declare class OpencodeGoAdapter extends LlmAdapter {
         model: LlmResolvedModelInfo;
         stream: (options: GenerateOptions) => AsyncIterable<StreamChunk>;
     }>;
-    /** Describe one model: capacities plus the reasoning levels it actually offers. */
+    /** Report the same default allowance used by dispatch so the host can budget compaction. */
     private modelInfo;
-    /** Validate an explicit effort against the model's own levels, without clamping. */
-    private resolveReasoningLevel;
     stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
     private streamWithSnapshot;
     private dispatch;
@@ -141,6 +140,4 @@ export declare class OpencodeGoAdapter extends LlmAdapter {
     private rememberRejectedKey;
     /** A stored change to a reference outranks the gateway's last rejection of it. */
     forgetRejectedKey(ref: string): void;
-    /** One account, one SDK attempt; host recovery still owns failures after output. */
-    private streamAttempt;
 }

package/lib/types/analytics.d.ts

@@ -0,0 +1,345 @@
+import type { Context } from '@deepseek-ai/cordis';
+import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+/**
+ * OpenCode Go plan snapshot: monthly limits and the one peak-pricing window the
+ * official tariff defines. Prices themselves stay on models.dev (the catalog's
+ * model.cost); this file only carries what models.dev does not publish.
+ *
+ * Source: https://opencode.ai/v2/docs/console/go/ (Go and Go Plus tables).
+ * The snapshot is reviewed when the model list or the plan changes; the report
+ * shows {@link GO_PLAN_AS_OF}, so a stale table is visible rather than silent.
+ *
+ */
+/** Date the limits below were read from the official plan page. */
+export declare const GO_PLAN_AS_OF = "2026-10-18";
+/** Human-readable source for the limit snapshot. */
+export declare const GO_PLAN_SOURCE = "https://opencode.ai/v2/docs/console/go/";
+/** Why a row has no numeric limit. */
+export type GoLimitNote = 'unlimited' | 'limited-time';
+/** One model's monthly allowance on each plan (USD), or a note instead. */
+export interface GoMonthlyLimit {
+    /** Go plan monthly limit in USD; null when the row is unlimited. */
+    readonly go: number | null;
+    /** Go Plus plan monthly limit in USD; null when the row is unlimited. */
+    readonly goPlus: number | null;
+    readonly note?: GoLimitNote;
+}
+/**
+ * Monthly limits by model id. Promo rows use the effective (post-strike-through)
+ * value and carry {@link GoLimitNote} 'limited-time'; free rows are unlimited.
+ */
+export declare const GO_MONTHLY_LIMITS: Readonly<Record<string, GoMonthlyLimit>>;
+/**
+ * Read one model's limit snapshot.
+ * @param model - catalog model id.
+ * @returns the row, or undefined when the plan page lists no such model.
+ */
+export declare function goMonthlyLimit(model: string): GoMonthlyLimit | undefined;
+/** Models with a documented peak/off-peak tariff (DeepSeek V4.1 Flash and V4 Pro). */
+export declare const PEAK_PRICED_MODELS: ReadonlySet<string>;
+/**
+ * Whether a request started inside the documented DeepSeek peak window:
+ * 01:00-04:00 and 06:00-10:00 UTC, Monday through Friday. All other hours,
+ * including weekends, are off-peak.
+ * @param at - request start time in Unix epoch milliseconds.
+ * @returns true when the peak multiplier applies.
+ */
+export declare function isPeakPricedAt(at: number): boolean;
+/** The four billable rates, in USD per one million tokens. */
+export interface CostRates {
+    readonly input: number;
+    readonly output: number;
+    readonly cacheRead: number;
+    readonly cacheWrite: number;
+}
+/** One context-length tier; the highest matching threshold prices the attempt. */
+export interface CostTier extends CostRates {
+    readonly inputTokensAbove: number;
+}
+/** Structural face of the catalog's ModelCost. */
+export interface ModelCostLike extends CostRates {
+    readonly tiers?: readonly CostTier[];
+}
+/** The token components one request reported. */
+export interface UsageCounts {
+    readonly input: number;
+    readonly output: number;
+    readonly cacheRead: number;
+    readonly cacheWrite: number;
+}
+/**
+ * Billed input tokens: reported input plus cache reads and writes.
+ * @param usage - one request's token components.
+ * @returns the total the tier threshold is compared against.
+ */
+export declare function billedInput(usage: UsageCounts): number;
+/**
+ * Whether every rate of a model is zero (a free row).
+ * @param cost - the model's catalog cost.
+ * @returns true when no component could ever charge.
+ */
+export declare function isFreeCost(cost: ModelCostLike): boolean;
+/**
+ * Price one settled request.
+ * @param model - the model id that served the request.
+ * @param usage - its token components.
+ * @param cost - the catalog cost for that model.
+ * @param at - request start time, used for the DeepSeek peak window.
+ * @returns the estimated cost in integer micro-USD.
+ */
+export declare function priceUsage(model: string, usage: UsageCounts, cost: ModelCostLike, at: number): number;
+/** Route id used by this plugin before 0.1.16. */
+export declare const LEGACY_PROVIDER_ID = "opencode-go";
+/** 0.1.16 isolated the plugin route; later legacy-id records belong to DSH native. */
+export declare const LEGACY_ROUTE_CUTOFF_MS: number;
+/** Minimal structural event face; the Host owns the real session types. */
+export interface AnalyticsEventLike {
+    readonly type: string;
+    readonly seq: number;
+    readonly time: number;
+    readonly data?: unknown;
+}
+/** Minimal structural snapshot returned by readSession. */
+export interface AnalyticsSnapshotLike {
+    readonly inheritedEventCount: number;
+    readonly events: readonly AnalyticsEventLike[];
+}
+/** One model request that the dashboard can price. */
+export interface RequestFact {
+    /** Request start, Unix epoch milliseconds. */
+    readonly at: number;
+    readonly model: string;
+    readonly input: number;
+    readonly output: number;
+    readonly cacheRead: number;
+    readonly cacheWrite: number;
+    /** The request was recorded under the pre-0.1.16 route id. */
+    readonly legacy: boolean;
+    readonly kind: 'message' | 'summary';
+    /** The request settled without a usable usage report. */
+    readonly missingUsage: boolean;
+}
+/** Everything one session contributes, before date filtering. */
+export interface FoldedSession {
+    readonly facts: RequestFact[];
+    /** Start times of attempts that committed no surface message. */
+    readonly attempts: number[];
+    /** Model calls with no usable routing header or model id. */
+    readonly unattributed: number[];
+    /** Events that passed the fork-prefix filter — never the inherited prefix (review P11). */
+    readonly events: number;
+}
+/**
+ * Whether a recorded provider id belongs to this plugin.
+ * @param provider - the provider id in a request header or summary event.
+ * @param at - the request start time.
+ * @param cutoff - legacy route cutoff, overridable in tests.
+ * @returns true when the request is this plugin's.
+ */
+export declare function isPluginRoute(provider: unknown, at: number, cutoff?: number): boolean;
+/**
+ * Fold one session snapshot.
+ * @param snapshot - complete raw event log plus its fork-inherited prefix length.
+ * @param options - test seams; the cutoff defaults to the 0.1.16 release.
+ * @returns the session's priceable facts and counters.
+ */
+export declare function foldSession(snapshot: AnalyticsSnapshotLike, options?: {
+    cutoff?: number;
+}): FoldedSession;
+/** Why an analytics read failed. */
+export type AnalyticsFailureReason = 'no-session-query' | 'invalid-range' | 'scan-failed';
+/** One dashboard read. Dates are Unix epoch milliseconds. */
+export interface AnalyticsQuery {
+    /** Inclusive start. */
+    from: number;
+    /** Exclusive end. */
+    to: number;
+    /** IANA timezone used to bucket days. */
+    timeZone: string;
+    /** Session scan cap, 1..2000; the Host default applies when absent. */
+    maxSessions?: number;
+}
+/** Totals over the requested range. */
+export interface AnalyticsTotals {
+    requests: number;
+    unsettledAttempts: number;
+    summaries: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    estimatedMicroUsd: number;
+    pricedRequests: number;
+    unpricedRequests: number;
+    missingUsage: number;
+}
+/** One model's share of the range. */
+export interface AnalyticsModelRow {
+    model: string;
+    name?: string;
+    requests: number;
+    missingUsage: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    estimatedMicroUsd: number;
+    pricedRequests: number;
+    unpricedRequests: number;
+    /** Go monthly limit in USD; null when unlimited or unknown. */
+    limitGoUsd: number | null;
+    /** Go Plus monthly limit in USD; null when unlimited or unknown. */
+    limitGoPlusUsd: number | null;
+    limitNote?: 'unlimited' | 'limited-time' | 'unknown';
+}
+/** One local calendar day. */
+export interface AnalyticsDayRow {
+    /** YYYY-MM-DD in the query timezone. */
+    day: string;
+    requests: number;
+    tokens: number;
+    estimatedMicroUsd: number;
+}
+/** Coverage and budget limits for this report. */
+export interface AnalyticsCoverage {
+    listedSessions: number;
+    scannedSessions: number;
+    matchedSessions: number;
+    failedSessions: number;
+    eventsScanned: number;
+    summaries: number;
+    legacyRequests: number;
+    missingUsage: number;
+    truncated: boolean;
+    truncation?: 'sessions' | 'events' | 'time';
+    scanMs: number;
+    timeZoneFallback?: true;
+    /**
+     * Sessions listed but never scanned because the slice cap or a budget
+     * stopped first (review P16/P18/M1). Observability only — this never
+     * implies the requested range was fully covered.
+     */
+    unreadSessions?: number;
+    /**
+     * Cache entries the end-of-run trim dropped after this report was computed
+     * from run-local results; the next run re-reads them (review P3/S1).
+     */
+    evictedSessions?: number;
+    /**
+     * Model calls in range with no usable routing header or model id, counted
+     * for visibility only — never in tokens or cost (review P12).
+     */
+    unattributedRequests?: number;
+    /** Session listing wall time; scanMs excludes it (review S6). */
+    listMs?: number;
+    /** Pricing harvest wall time; scanMs excludes it (review S6/P4). */
+    pricingMs?: number;
+}
+/** Where the prices came from. */
+export interface AnalyticsPricing {
+    source: 'models.dev';
+    updatedAt?: number;
+    /**
+     * True only when the whole price table was unavailable; unpricedModels then
+     * lists every model that actually appeared in the range (review P15). A
+     * table that loaded but lacks a model leaves this unset and lists the model.
+     */
+    unavailable?: true;
+    unpricedModels: string[];
+}
+/** One complete dashboard response. */
+export interface AnalyticsReport {
+    generatedAt: number;
+    range: {
+        from: number;
+        to: number;
+    };
+    timeZone: string;
+    totals: AnalyticsTotals;
+    byModel: AnalyticsModelRow[];
+    byDay: AnalyticsDayRow[];
+    coverage: AnalyticsCoverage;
+    pricing: AnalyticsPricing;
+}
+/** Structural face of one sessionQuery record. */
+export interface AnalyticsSessionRecord {
+    readonly header?: {
+        readonly id?: string;
+        readonly createdAt?: number;
+    };
+    readonly live?: boolean;
+    readonly persisted?: boolean;
+}
+/** The subset of ctx.sessionQuery this service needs. */
+export interface AnalyticsSessionQuery {
+    listSessions(signal?: AbortSignal): Promise<readonly AnalyticsSessionRecord[]>;
+    readSession(id: string): Promise<AnalyticsSnapshotLike>;
+}
+/** Structural face of one catalog model. */
+export interface AnalyticsPricingModel {
+    readonly id?: string;
+    readonly name?: string;
+    readonly cost?: ModelCostLike;
+}
+/** Pricing data and its last update, when known. */
+export interface AnalyticsPriceBook {
+    readonly models: ReadonlyMap<string, AnalyticsPricingModel>;
+    readonly updatedAt?: number;
+}
+/** Structural face of the catalog data the price book builder consumes. */
+export interface AnalyticsCatalogSnapshotLike {
+    readonly models: ReadonlyMap<string, AnalyticsPricingModel>;
+    readonly details?: ReadonlyMap<string, {
+        readonly costKnown?: false;
+    }>;
+    readonly metadataUpdatedAtMs?: number;
+}
+/** Construction options; tests inject fakes for every seam. */
+export interface AnalyticsOptions {
+    query: () => AnalyticsSessionQuery | undefined;
+    pricing: () => Promise<AnalyticsPriceBook | undefined>;
+    now?: () => number;
+    budgetMs?: number;
+    maxSessions?: number;
+    maxEvents?: number;
+    maxFacts?: number;
+    /**
+     * Maximum concurrent session reads (review P1/S3). One or less scans
+     * serially — the rollback path for a Host whose readSession cannot run
+     * concurrently.
+     */
+    maxConcurrency?: number;
+}
+/**
+ * Build the analytics price book from one catalog snapshot (review P14 core
+ * half). A model the metadata marked `costKnown: false` — upstream published
+ * no cost block, or a malformed one whose fabricated zeros are
+ * indistinguishable from a genuinely free model — is entered without a cost,
+ * so its requests land in the unpriced bucket instead of being priced at 0.
+ * A published block with legal components stays priced even when all zero.
+ */
+export declare function analyticsPriceBook(snapshot: AnalyticsCatalogSnapshotLike): AnalyticsPriceBook;
+/** One mount owns the scan cache; multiple dashboard opens share it. */
+export declare class GoAnalyticsService extends TypertRemoteService {
+    private readonly options;
+    private readonly cache;
+    private readonly pending;
+    /** The most recent successful price table; stale-on-error fallback (review P4/S4). */
+    private lastPriceBook;
+    private factTotal;
+    constructor(ctx: Context, options: AnalyticsOptions);
+    /**
+     * Read one aggregate report.
+     * @param raw - the validated query from the RPC codec.
+     * @param signal - caller cancellation, injected by the gateway after the
+     *   business parameters and never carried on the wire.
+     * @returns the report; failures carry a reason in the domain error details.
+     */
+    read(raw: AnalyticsQuery, signal?: AbortSignal): Promise<AnalyticsReport>;
+    private now;
+    private limitOf;
+    private run;
+    private remember;
+    /** The one eviction point; returns how many entries it dropped (review S1/P2). */
+    private trim;
+}