# Runtime Model Routing And Tokenomics Telemetry

Issue: #189

## Purpose

This note defines runtime model routing, tokenomics telemetry, and inference-use policy for the source-grounded assistant.

It is an architecture and control-plane note. It does not approve broad public provider-backed usage, add billing integration, add a database, add an external telemetry service, add current/public retrieval, add file uploads, expose provider secrets, weaken grounding, or create model auto-selection that bypasses review.

## Routing Baseline

Package-only mode remains the default runtime route.

Default model choice is configured outside the repository through the server-side provider adapter. In the current proof boundary, the adapter identity is `openai_compatible`, the model identifier is read from server-side configuration, and the safe public label is `configured externally` unless an approved admin-visible response explicitly exposes a model label.

Provider adapter identity may be shown as admin-visible run metadata. Provider secrets, API keys, base URLs, cookies, Cloudflare tokens, OTP values, and internal-only configuration must never be exposed in browser-visible metadata or package material.

Model identifier exposure rules:

- normal user-facing answer areas should not depend on exact model identifiers
- admin-visible run details may show a safe `model_label`, `model_tier`, or exact model identifier only when the server boundary marks it safe for response metadata
- exact model identifiers are runtime configuration evidence, not source authority, provider approval, model approval, or production approval
- model labels must not hide grounding failures, citation gaps, refusal reasons, provider errors, or unsupported prompts

Future model tiers may be introduced only through reviewed configuration and validation. They must preserve deterministic pre-provider refusals, approved-source selection, citation class separation, token visibility, and cost metadata discipline.

## Mode-Specific Routing

| Mode or future capability | Current route | Provider call condition | Required boundary |
|---|---|---|---|
| Answer | Package-only source selection, then server-side provider boundary when approved sources exist. | Approved package refs selected and no deterministic refusal applies. | Package citations remain source authority. |
| Explain | Same as Answer with explanatory prompt strategy. | Approved package refs selected and no deterministic refusal applies. | Generated explanation is derivative interpretation. |
| Assess | Deterministic missing-evidence refusal before provider when proposal evidence is insufficient. | Approved package refs selected and proposal evidence is sufficient. | Assessment cannot imply approval. |
| Find evidence | Package source selection with minimal synthesis. | Approved package refs selected and no deterministic refusal applies. | Source evidence remains package evidence, not model authority. |
| Package + current context | Explicit gated mode. Current retrieval uses the server-side allowlisted adapter after package support exists. | Provider call runs only after package refs and current/public refs exist. | Response must preserve `Package says`, `Current/public source says`, `Synthesis / implications`, and `Divergence / update candidate` lanes. |
| Future current/public retrieval | Not implemented here. | Only after a server-side retrieval adapter returns separately cited current/public sources. | Current/public citations stay separate from package citations. |
| Future file/session-source routing | Not implemented here. | Only after a separate upload/session-source design is approved. | Uploaded/session citations must remain session-scoped and visibly labeled. |
| Future formatting/report generation | Not implemented here. | Only after source and output boundaries are reviewed. | Formatting may improve presentation but cannot add unsupported claims. |

## Inference-Use Policy

The assistant may infer, explain, synthesize, and format using approved supplied sources. That inference is allowed only as generated interpretation.

The assistant must distinguish:

- source-grounded statement: a claim directly supported by approved package citations or separately cited current/public sources when that mode exists
- generated interpretation: synthesis, implication, explanation, formatting, or assessment produced from supplied source material
- not found or uncertainty: unsupported material, missing source authority, stale current context, provider error, or approval-boundary refusal

The approved corpus remains source authority for package-grounded mode. The model is not the source of truth. Model memory must not supply source claims. External/current context must be labeled separately when a server-side retrieval adapter supplies current/public citations.

## Runtime Telemetry Fields

Each run should normalize the following non-durable metadata when available:

| Field | Meaning | Visibility |
|---|---|---|
| `mode` | Answer, Explain, Assess, or Find evidence. | User and admin. |
| `context_mode` | Package only or Package + current context. | User and admin. |
| `provider_status` | Provider skipped, executed, failed, blocked, or not configured. | Admin. |
| `provider_adapter` | Adapter identity, such as `openai_compatible`. | Admin. |
| `model_label` | Safe model tier or model label. | Admin. |
| `model_identifier_exposure` | Whether model identifier was safely exposed. | Admin. |
| `selected_source_count` | Number of approved package refs sent or used. | User and admin. |
| `package_citation_count` | Number of package citations returned. | User and admin. |
| `current_public_citation_count` | Number of current/public citations returned. | User and admin. |
| `external_retrieval_count` | Number of current/public retrieval results returned by an approved adapter. | Admin. |
| `source_grounded_api_request_count` | Browser calls to `/api/source-grounded-chat` for the displayed run. | Admin. |
| `server_api_request_count` | Server/API boundary calls represented by the response. | Admin. |
| `direct_browser_provider_request_count` | Direct browser requests to provider endpoints. Must remain zero. | Admin. |
| `prompt_context_estimate_tokens` | Estimate of selected prompt/context size before provider usage is returned. | Admin. |
| `prompt_tokens` | Provider-returned prompt/input token count when available. | Admin. |
| `completion_tokens` | Provider-returned completion/output token count when available. | Admin. |
| `total_tokens` | Provider-returned total token count when available. | Admin. |
| `token_usage_available` | Whether provider token usage was returned. | Admin. |
| `token_usage` | Normalized token object. | Admin. |
| `latency_ms` | Server or browser-observed latency for the displayed run. | Admin. |
| `cost_metadata` | `not available` unless provider/model pricing configuration exists. | Admin. |
| `telemetry_persistence` | `none` for this proof boundary. | Admin. |

Cost metadata is not a browser-side calculator. Future cost estimates must be driven by reviewed provider/model pricing configuration and must record when pricing is unknown, stale, unavailable, or not approved for cost reporting.

## User-Visible Versus Admin-Visible Details

Normal users should see:

- grounded answer or deterministic refusal
- citation and provenance list
- source boundary language
- selected source count when useful
- context mode and current-context disabled state when relevant

Admin-visible run details may include:

- provider adapter
- provider/API status
- model tier or safe model label
- selected source count
- package citation count
- current/public citation count
- prompt/context estimate
- provider-returned token usage
- latency
- server/API request count
- direct browser provider request count
- cost metadata or `not available`
- telemetry persistence status

Admin-visible metadata is for operational review. It is not a durable audit log, billing record, user tracking system, provider approval, or source authority.

## Durable Telemetry Policy

This issue defines durable telemetry expectations but does not implement durable collection.

Before any database-backed telemetry, external logging, learning loop, question logging, selected-source history, answer/refusal history, feedback capture, or improvement queue is enabled, a later issue must define:

- privacy and data-boundary rules for storing user questions
- consent or notice expectations
- retention and deletion expectations
- allowed fields and forbidden fields
- access control for operator-visible run history
- redaction rules for secrets, internal-only content, private data, and provider configuration
- cost-estimate configuration ownership
- feedback capture workflow and review ownership

No user question logging should happen silently. No durable run history should exist until the telemetry/privacy model is approved.

## Validation And Receipts

Validation should prove:

- package-only remains default
- unsupported or no-source prompts refuse before provider execution
- Package + current context remains explicit and package-first
- unavailable current-context retrieval returns a visible not-retrieved diagnostic
- current/public citations remain zero while the adapter is disabled
- external retrieval count remains zero while the adapter is disabled
- direct browser provider request count remains zero
- runtime metadata is bounded and does not expose secrets
- token usage reports provider-returned values when available and honest unavailable states otherwise
- cost metadata is `not available` unless reviewed pricing configuration exists
- telemetry persistence is `none`

Receipts should state whether a change is design-only or includes safe runtime metadata normalization. Receipts must also state no real current retrieval, no durable telemetry/database, no uploads/session attachments, no Cloudflare Access/WAF changes, no provider secrets exposed, and no codex-automerge.