@danypops/jittor 0.16.3 → 0.17.0

package/README.md

@@ -1,20 +1,28 @@
 # @danypops/jittor
 
-Supervised Bun daemon, router policy, provider telemetry adapters, and CLI for Jittor. See the [repo root README](../../README.md) for the two-package overview and [`@danypops/pi-jittor`](../pi-jittor) for the Pi extension that talks to this daemon.
+Token and context observability, optimization policies, provider integrations, supervised Bun daemon, and CLI for Jittor. See the [repo root README](../../README.md) for the two-package overview and [`@danypops/pi-jittor`](../pi-jittor) for the Pi extension that talks to this daemon.
 
 ## Architecture
 
-- `src/domain/metric.ts` — normalized timestamped metric observations
-- `src/ports/metric-store.ts` — storage boundary used by the application service
-- `src/adapters/sqlite-metric-store.ts` — SQLite time-series adapter
-- `src/service.ts` — authenticated operation registry
-- `src/client.ts` — operation-typed loopback client
-- `src/daemon.ts` — Bun composition root and maintenance loop
-- `src/index.ts` — the package's public surface: everything `@danypops/pi-jittor` (or any other consumer) imports
+`src/` is organized by Jittor's domain and concrete integrations:
 
-SQLite runs in WAL mode with versioned migrations, JSON validation, bounded queries, chronological indexes, pruning, and checkpoints. The database follows `XDG_DATA_HOME`; private authentication state follows `XDG_STATE_HOME`; the daemon handle follows `XDG_RUNTIME_DIR`.
+- `observability/` — token, cost, context, task-focus, model-run, and provider-budget observations; its store and source boundaries live beside that model
+- `optimization/routing/` — budget pressure, route decisions, overrides, and enforcement state
+- `optimization/model-selection/` — benchmark evidence, model ranking, and their source/store boundaries
+- `optimization/recovery/` — bounded recovery policies
+- `sessions/` — session identity and mutation authorization
+- `codex/`, `openrouter/`, `anthropic/`, `google-vertex/` — provider-specific translation and telemetry
+- `lmarena/`, `artificial-analysis/` — benchmark-source translation
+- `sqlite/` — observation and session persistence
+- `vehicle/` — authenticated operation transport
+- `daemon.ts` — composition root and maintenance loop
+- `index.ts` — stable public package surface
 
-Operations currently include bounded metric recording/query/pruning, benchmark refresh/status/query, context assessment, routing control, telemetry polling, and service checkpointing. Every operation is exposed through the authenticated typed client; benchmark operations also have CLI parity.
+Dependencies point toward `observability/` and `optimization/`; provider, SQLite, Vehicle, CLI, and Pi models are translated at their boundaries. SQLite runs in WAL mode with versioned migrations, bounded queries, pruning, and checkpoints.
+
+Operations currently include bounded metric recording/query/pruning, benchmark and provenance-bearing model-catalog refresh/status/query, context assessment and content-free snapshot deltas, routing control, telemetry polling, and service checkpointing. Every operation is exposed through the authenticated typed client; benchmark operations also have CLI parity.
+
+Token counts carry explicit scope and provenance (`provider-reported`, `provider-count-api`, `tokenizer-exact-text`, or `structural-estimate`). Provider aggregates remain authoritative, exact local tokenization is labeled exact for text only, and envelope/media/provider residuals remain explicit instead of being assigned to individual context items. See [`docs/TOKEN_MEASUREMENT.md`](docs/TOKEN_MEASUREMENT.md) for the contract, OpenAI-family adapter, privacy boundary, module benchmark, and E2E test layers.
 
 ## Provider telemetry
 
@@ -25,10 +33,16 @@ Operations currently include bounded metric recording/query/pruning, benchmark r
 
 Provider adapters currently include official OpenRouter key/usage/model telemetry and an explicitly experimental Codex subscription adapter. The Codex adapter follows the pinned open-source CLI `/wham/usage` payload and `x-codex-*` response-header contracts, accepts additional metered limits, and fails closed on malformed windows or impossible percentages. File credentials must be explicitly configured and private (`0600`); Jittor reads only the access token and account ID, never refreshes credentials, and never logs or persists OAuth secrets. Anthropic has no personal-account polling endpoint (its Admin/Rate Limits API is documented as unavailable for individual accounts), so Jittor instead reads the official `anthropic-ratelimit-*` response headers Pi observes on every Messages API call and fails closed on schema drift the same way. Google Vertex AI has neither a personal polling endpoint nor a documented remaining-quota response header, so Jittor never fabricates a Vertex budget bar; it instead classifies Vertex's `google.rpc.Status` failure shape (quota, authentication, invalid-request, overload, transport, unknown) from Pi's bounded, content-free `errorMessage` and records only a bounded failure-count metric.
 
+If Codex usage becomes `telemetry unavailable`, check `jittor telemetry poll --json`: the active daemon must list `codex-subscription`. A manually started or older npm-installed daemon can own the shared runtime handle while a correctly configured systemd service is inactive; stop that process and restart the configured service. The human status view reports this mismatch without displaying credential paths or values. Jittor never carries an expired percentage across its reset or assumes the reset replenished the subscription—until a fresh provider observation arrives, it reports `reset pending` instead.
+
 The third-party `anthropic-vertex` provider (Anthropic Claude models served through Google Vertex, e.g. via `@twogiants/pi-anthropic-vertex`) is tracked separately from both of the above: it reuses Pi's own Anthropic Messages stream implementation with Anthropic's official `@anthropic-ai/vertex-sdk` client, so its wire shape is Anthropic's, but its quota accounting is Google's. Jittor applies Google Vertex's failure classification to it (real-world reports confirm its 429s still carry GCP's own quota-exceeded shape even through Anthropic's own SDK) and, best-effort, also checks for genuine Anthropic rate-limit response headers on it, since it is unverified whether this specific passthrough ever forwards them. Either way, every metric is tagged `anthropic-vertex`, never blended into direct Anthropic's `anthropic` source or Pi's unrelated native `google-vertex` provider, since each represents a different account/quota pool.
 
 Blocking always has a daemon-independent escape hatch: `/jittor off` (in the extension) immediately enters persisted monitor-only mode and never blocks provider requests, regardless of daemon state.
 
+## Provenance-bearing model catalog
+
+Set `JITTOR_MODELS_DEV_CATALOG=1` to opt into bounded models.dev ingestion. `jittor catalog status|refresh|list [--json]` exposes last-good snapshot state and provider-serving limits, capabilities, modalities, lifecycle, and pricing with per-field authority. Live provider usage/cost remains authoritative; explicit local query overrides win over catalog metadata. See [`docs/MODEL_CATALOG.md`](docs/MODEL_CATALOG.md).
+
 ## Benchmark evidence
 
 Jittor can ingest bounded OpenRouter model metadata, p50 latency/throughput ordering, and Design Arena Elo rankings as provenance-bearing evidence without treating OpenRouter as model-scope authority. Enable online ingestion explicitly with `JITTOR_OPENROUTER_BENCHMARKS=1`; it is off by default. OpenRouter model metadata and operational ordering are public; Design Arena ingestion additionally uses `OPENROUTER_API_KEY` from the supervised service environment without retaining it. Snapshots preserve the upstream publisher, normalized model identities, immutable retrieval revisions, source URLs, confidence, license terms, and explicit freshness deadlines. A malformed or oversized refresh leaves the last complete snapshot visible and records only a payload-safe failure state.
@@ -47,15 +61,23 @@ jittor benchmarks list --source openrouter-models [--model provider/model] [--di
 
 Only complete snapshots are queryable. Query output reports both completeness and freshness. See [`docs/BENCHMARK_SOURCES.md`](docs/BENCHMARK_SOURCES.md) for source authority, provenance, conflict, and redistribution rules.
 
-The ranking operation (`domain/model-ranking.ts`) accepts an explicit bounded candidate set and never adds identities found only in evidence. It scores quality (a domain-specific dimension, e.g. `quality-coding`, and a type-specific dimension, e.g. `quality-type-planning`, each optional and additive over the universal `quality-general` fallback), cost, latency, context, and local reliability with bounded user weights, budget-pressure adjustment, component confidence, freshness, provenance, and deterministic tie-breaking. Missing evidence remains unknown and lowers confidence.
+The ranking operation (`optimization/model-selection/ranking.ts`) accepts an explicit bounded candidate set and never adds identities found only in evidence. It scores quality (a domain-specific dimension, e.g. `quality-coding`, and a type-specific dimension, e.g. `quality-type-planning`, each optional and additive over the universal `quality-general` fallback), cost, latency, context, and local reliability with bounded user weights, budget-pressure adjustment, component confidence, freshness, provenance, and deterministic tie-breaking. Missing evidence remains unknown and lowers confidence.
 
 Jittor separately records content-free local model observations from Pi's public lifecycle: TTFT, wall latency, output throughput, token/cache/cost efficiency, provider retries, tool-loop counts, failures, and two independent classifications derived only from bounded tool names: domain (subject matter, e.g. `coding`) and type (activity, e.g. `research`, `planning`). Prompts, responses, tool arguments/results, credentials, and project paths are never retained. Robust aggregates report sample size, median, p90, median absolute deviation, recency, and confidence without merging local observations into external benchmark facts.
 
+## Content-free OTLP export
+
+Configure `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` (or the standard generic endpoint) to opt into bounded asynchronous OTLP/HTTP JSON export. `jittor export status|flush [--json]` reports credential-safe health. The mapper pins evolving GenAI conventions and has no content-capture mode. See [`docs/OTLP_EXPORT.md`](docs/OTLP_EXPORT.md).
+
+## Historical Pi usage backfill
+
+`jittor backfill status|dry-run|run|cancel [--json]` imports only persisted content-free Pi usage facts into the same charts as live observations. Opaque identities and atomic SQLite claims make reimport, concurrency, moved sessions, and restart safe; scans and progress are bounded and cancelable. See [`docs/USAGE_BACKFILL.md`](docs/USAGE_BACKFILL.md).
+
 ## Context pressure
 
-Papyrus emits content-free prompt-injection observations through Pi's shared extension event bus. Jittor validates and records their exact Rule/Task character sizes, prompt share, fingerprint repetition, and explicitly estimated token size. Jittor also records completed, aborted, and unmatched Pi compactions with duration, reason, retry state, pre-compaction context usage, and bounded turns/injection/provider/cache usage since the previous compaction.
+Papyrus emits content-free prompt-injection observations through Pi's shared extension event bus. Jittor validates and records their exact Rule/Task character sizes, prompt share, fingerprint repetition, and explicitly estimated token size. Jittor also records completed, aborted, and unmatched Pi compactions with duration, reason, retry state, provenance-bearing pre/post context, summary size, reduction, regrowth milestones, mechanism identity, and bounded turns/injection/provider/cache/tool/outcome counters since the previous compaction. See [`docs/COMPACTION_EFFECTIVENESS.md`](docs/COMPACTION_EFFECTIVENESS.md).
 
-`jittor context [--since <epoch-ms>] [--until <epoch-ms>] [--json]` reports bounded average/p95/max injection, Rule/Task mix, unchanged rate, compaction frequency/duration/reasons, and between-compaction provider/cache facts. Repeated prompt content is not labeled billed waste: provider-reported input/cache usage and an injection-disabled control are required before making cost or compaction-causality claims.
+`jittor context [--since <epoch-ms>] [--until <epoch-ms>] [--json]` reports bounded average/p95/max injection, Rule/Task mix, unchanged rate, compaction frequency/duration/reasons, and between-compaction provider/cache facts. `jittor context delta --session-id <opaque-id> [--json]` exposes the latest content-free structural delta; Pi's `/context` view resolves that opaque identity itself. Repeated prompt content is not labeled billed waste: provider-reported input/cache usage and an injection-disabled control are required before making cost or compaction-causality claims. See [`docs/CONTEXT_SNAPSHOTS.md`](docs/CONTEXT_SNAPSHOTS.md) for privacy, lifecycle, truncation, persistence, and stable-prefix semantics.
 
 ## CLI operations
 
@@ -71,6 +93,9 @@ jittor metrics cost-by-task --since <ms> --until <ms> [--json]
 jittor service checkpoint [--json]
 jittor telemetry poll [--json]
 jittor compaction estimate [--json]
+jittor catalog status|refresh|list [--provider <id>] [--model <id>] [--limit <n>] [--json]
+jittor backfill status|dry-run|run|cancel [--json]
+jittor export status|flush [--json]
 jittor session register --session-id <id> [--json]
 jittor session release --session-id <id> [--session-secret <secret>] [--json]
 jittor router status|decide|pause|resume|clear-override [--session-id <id>] [--session-secret <secret>] [--json]

package/docs/COMPACTION_EFFECTIVENESS.md

@@ -0,0 +1,34 @@
+# Compaction effectiveness and regrowth
+
+Jittor treats compaction as an observed intervention, not as proof that information was lost or that
+provider caching improved. Pi's public compaction lifecycle supplies the mechanism, reason,
+completion/abort/retry state, duration, and pre-compaction token estimate. The first subsequent
+content-free provider snapshot supplies the post-compaction structural token estimate.
+
+Every pre/post/summary/regrowth token value carries explicit provenance. Current Pi-native summary
+and provider-payload structure values are `structural-estimate`; provider-reported request totals
+remain separate and authoritative for billing. A completed compaction without a subsequent snapshot
+remains a duration observation and does not fabricate effectiveness.
+
+`compaction-effectiveness` records the reduction ratio, pre/post token sizes, mechanism
+(`pi-native`, `provider-side`, or `extension`), provider/model, and summary size. Regrowth emits each
+50%, 80%, and 100% milestone once with turns and elapsed time. Interval attributes also retain only
+bounded counts for tool classes, retries/failures, cache reads/writes, and explicit accepted/rejected
+outcomes. Tool arguments, results, commands, paths, prompts, responses, and summaries are never
+persisted.
+
+`jittor context` and `/jittor context` aggregate these observations by period and mechanism. Missing
+samples remain unknown. Repeated tool-class activity is a content-free proxy only; it is never
+labeled waste or information loss without explicit outcome/control evidence.
+
+## External mechanisms
+
+External compactors such as `pi-mega-compact` should emit the same capability inputs through an
+extension boundary: call `begin()` with `mechanism: "extension"`, record completion with summary
+measurement provenance, and pass the first final provider-request snapshot to
+`observeContextSnapshot()`. Provider-side compaction uses `mechanism: "provider-side"`. Core Jittor
+has no dependency on either implementation and does not invoke or control a compactor.
+
+Capture and daemon-write failures are isolated from provider delivery. An extension/daemon restart
+may leave a completed duration without a correlated post snapshot; Jittor reports the missing
+sample rather than correlating across an uncertain lifecycle boundary.

package/docs/CONTEXT_SNAPSHOTS.md

@@ -0,0 +1,53 @@
+# Content-free context snapshots and deltas
+
+Jittor observes Pi's `before_provider_request` boundary to compare the structure of consecutive
+provider requests. This is observability only: capture never modifies or delays the request, and a
+capture/daemon failure cannot block provider delivery.
+
+## Persisted contract
+
+A snapshot contains only:
+
+- bounded source categories (`base-prompt`, `tool-definitions`, `rules`, `skills`,
+  `project-context`, `conversation-message`, `thinking`, `tool-call`, `tool-result`);
+- non-negative token sizes, request positions, timestamps, and lifecycle state;
+- opaque logical IDs and content fingerprints produced by keyed HMAC;
+- provider/model identity and an honest truncation flag.
+
+Snapshots are capped at 512 segments. Values are canonicalized only in memory with depth,
+collection, node, and string bounds. Jittor never persists prompts, responses, tokenizer input,
+tool arguments/results, images, shell commands, paths, credentials, or reversible/plain hashes.
+Images retain structural identity with zero locally attributed tokens because image token cost is
+provider/model-specific.
+
+Pi's final payload supplies active request order. Its real `SessionManager` tree additionally marks
+entries omitted by compaction as `compacted` and abandoned branches as `inactive`; historical
+entries have no request position and therefore cannot inflate stable-prefix evidence.
+
+## Delta semantics
+
+For each logical segment, a delta reports `added`, `retained`, `changed`, `evicted`, `compacted`, or
+`inactive`, plus source-level token growth. Equal repeated structures remain distinct logical
+segments even when their content fingerprints are equal. A provider, model, or opaque session
+change resets comparison rather than correlating incompatible request shapes.
+
+`stablePrefixTokens` is the sum of unchanged leading active request segments, and
+`firstChangedSegment` identifies the first structural divergence. This is correlation evidence for
+request churn. It is **not proof of provider cache behavior, cache eligibility, cache hits, billing,
+or causality**. Provider-reported usage remains authoritative at aggregate request scope.
+
+## Operations
+
+```text
+jittor context delta --session-id <opaque-id> [--json]
+jittor context snapshot --snapshot <content-free-json> [--json]
+```
+
+`context.snapshot` is a single-execution local write and is never transport-retried.
+`context.delta` is a bounded read and may reconnect/retry once. Pi's `/context` view derives the
+opaque session ID internally and displays stable-prefix size, first change, lifecycle counts,
+source growth, truncation, and the cache-evidence caveat alongside its searchable context tree.
+
+Snapshots and their deltas are committed atomically through `MetricStore.recordBatch()`. The latest
+snapshot reloads from SQLite after daemon restart. A late stale capture remains queryable as
+history but cannot replace a newer snapshot as the session's latest state.

package/docs/MODEL_CATALOG.md

@@ -0,0 +1,43 @@
+# Provenance-bearing model catalog
+
+Jittor can ingest the open-source [models.dev](https://models.dev) provider catalog from
+`https://models.dev/api.json`. Network access is off by default. Set
+`JITTOR_MODELS_DEV_CATALOG=1`, then run `jittor catalog refresh`; an optional
+`JITTOR_MODELS_DEV_CATALOG_URL` is intended for a trusted mirror or loopback integration test.
+
+The direct translator preserves provider serving identity, aliases, context/input/output limits,
+modalities, capabilities, lifecycle status, input/output/reasoning/cache prices, over-200k prices,
+and context price tiers. A bounded response is validated as one complete snapshot. Its SHA-256
+content revision, source URL, retrieval time, freshness deadline, and upstream MIT license are
+stored. The complete marker is published last, so malformed, partial, oversized, timed-out, or
+offline refreshes cannot replace the last complete snapshot.
+
+Catalog prices are USD per million tokens and remain metadata estimates. Provider-reported usage
+and cost are authoritative for actual billing. Provider serving entries override base-model
+metadata in models.dev itself. Explicit query-time local overrides then win over catalog fields;
+every resolved field reports `models-dev-provider` or `user-override` authority. Aliases are matched
+only inside the selected provider, so a shared model name never merges provider quota pools or
+serving variants.
+
+Commands:
+
+```text
+jittor catalog status [--json]
+jittor catalog refresh [--force] [--json]
+jittor catalog list [--provider <id>] [--model <id>] [--limit <n>] [--json]
+```
+
+Local limit/price overrides are available on `catalog list` through `--context-tokens`,
+`--input-tokens`, `--output-tokens`, `--input-price`, and `--output-price`.
+
+## Source and redistribution
+
+models.dev is Copyright (c) 2025 models.dev and distributed under the MIT License. Jittor stores only
+translated metadata plus its source/provenance; redistributors must retain the upstream copyright
+and permission notice when the license requires it. See the upstream repository for the complete
+license and contribution history.
+
+OpenRouter's model endpoint remains useful operational marketplace metadata for OpenRouter-specific
+availability and pricing. It is not used as a base-model authority and cannot replace models.dev's
+cross-provider serving catalog. Conversely, models.dev metadata does not override live OpenRouter
+account/response telemetry. The two sources retain distinct provenance and authority.

package/docs/OTLP_EXPORT.md

@@ -0,0 +1,63 @@
+# Content-free OTLP export
+
+Jittor can asynchronously export observations to any OTLP/HTTP JSON metrics collector. It is off by
+default and has no Phoenix, Langfuse, or other backend dependency.
+
+Configure one standard OpenTelemetry endpoint variable:
+
+```text
+OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://collector.example/v1/metrics
+# or OTEL_EXPORTER_OTLP_ENDPOINT=https://collector.example/
+OTEL_EXPORTER_OTLP_HEADERS=authorization=Bearer%20...
+```
+
+`OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` is exact. The generic endpoint receives `v1/metrics`.
+Endpoints and headers exist only at the concrete transport boundary; status, errors, local metrics,
+and logs never contain them. Plain HTTP is accepted only for loopback collectors.
+
+```text
+jittor export status [--json]
+jittor export flush [--json]
+```
+
+Status reports enabled/disabled state, queue depth, exported/dropped counts, failed batches, last
+success/failure timestamps, and the pinned convention revision. It never reports endpoint or
+credential data.
+
+## Semantic mapping
+
+The mapping is pinned to OpenTelemetry GenAI semantic-conventions commit
+`46d43c8949afb53765a202e89f4534eeb75ca3fa` with core semantic conventions `v1.44.0`. GenAI
+conventions are still Development and currently have no schema URL, so Jittor reports this complete
+pin as `genai@46d43...+core-v1.44.0` and isolates names in one mapper.
+
+- input/output tokens → `gen_ai.client.token.usage` with `gen_ai.token.type`
+- latency → `gen_ai.client.operation.duration`
+- TTFT → `gen_ai.client.operation.time_to_first_chunk`
+- provider/model/operation/thinking → current `gen_ai.*` attributes
+- readily available opaque session correlation → `gen_ai.conversation.id`
+- cache/reasoning tokens and output throughput → `jittor.gen_ai.*`
+- compaction, context, budget, and routing facts → bounded `jittor.*` metrics/attributes
+- failures → low-cardinality `error.type`; raw provider errors are never exported
+
+The standard token metric allows only input/output token types, so cache and reasoning observations
+stay distinct under Jittor's namespace rather than inventing non-standard values for
+`gen_ai.token.type`. Provider-reported values retain their local authority; export does not
+re-tokenize content.
+
+## Privacy and failure isolation
+
+The mapper is an allowlist. It has no configuration switch for content and cannot emit
+`gen_ai.input.messages`, `gen_ai.output.messages`, `gen_ai.system_instructions`, prompt variables,
+tool definitions, prompts, responses, tool arguments/results, shell commands, file paths,
+credentials, environment values, or raw provider errors.
+
+Local SQLite persistence completes before an observation is enqueued. Export is detached from Pi's
+provider lifecycle. The in-memory queue, batch, interval, timeout, and one-retry policy are bounded;
+backpressure drops and counts the oldest item. Collector failure only increments credential-safe
+health counters and cannot change local persistence or routing. Shutdown performs a bounded final
+flush; a restart intentionally starts with an empty queue while SQLite remains authoritative.
+
+Generic OpenTelemetry Collector, Phoenix OTLP ingestion, and Langfuse OTLP ingestion can consume the
+same endpoint shape when configured by their own documentation. Jittor neither detects nor couples
+to those products.

package/docs/PROVIDER_RESEARCH.md

@@ -194,7 +194,7 @@ Two API surfaces matter here, and they answer different questions:
 - **`billingAccounts.budgets.get`/`.list`** (REST, project-scoped per above) returns only the budget's *policy* — its cap (`amount`), alert `thresholdRules`, and filters. It does **not** return current spend. Resolving which billing account owns a given project first requires `projects.getBillingInfo` (`cloudbilling.googleapis.com`, also just `resourcemanager.projects.get`/Project Viewer).
 - **Cloud Billing's own programmatic budget notifications**, delivered over Pub/Sub, are the real signal: Google's docs state notifications are "sent to the Pub/Sub topic **multiple times per day** with the current status of your budget" (not only on threshold crossings), each message carrying real dollar figures — `costAmount`, `budgetAmount`, `costIntervalStart`, `currencyCode`, and (only once actually exceeded) `alertThresholdExceeded`/`forecastThresholdExceeded` (schema verified against `docs.cloud.google.com/billing/docs/how-to/budgets-programmatic-notifications#notification-format` and the worked fixture in `.../billing/docs/how-to/listen-to-notifications`, fetched 2026-07-23). Since Jittor is a local, loopback-only daemon with no public inbound endpoint, it **pulls** (never pushes) this topic via a Pub/Sub pull subscription (`pubsub.googleapis.com/v1/{subscription}:pull`), authenticated the same ADC way.
 
-This is still not a fully real-time signal, and the docs are explicit about both caveats Jittor must preserve rather than paper over: (1) "Budgets use estimated Cloud Billing data which is subject to change until your invoice is finalized", and (2) "Pub/Sub only provides at-least-once delivery. You might receive a message multiple times, and messages might arrive out of order." Jittor's `GoogleVertexBudgetTelemetryAdapter` (`src/providers/google-vertex-budget.ts`) selects the freshest pulled message by its own Pub/Sub `publishTime`, fails closed (throws) on any message that doesn't match the documented schema, and reports this signal at a lower confidence (`0.6`, vs. `0.8` for Codex's header-derived windows) than a per-response header would earn. `spend`/`cap` are recorded as real USD metrics and their `spend-fraction` ratio is left unclamped (so a genuine over-cap soft-quota period stays visible); only the policy-facing `BudgetWindow.usedFraction` is clamped to `1.0`, since a known-to-be-≥100% real number floored to the window's documented `[0,1]` invariant is not the same thing as fabricating one from nothing.
+This is still not a fully real-time signal, and the docs are explicit about both caveats Jittor must preserve rather than paper over: (1) "Budgets use estimated Cloud Billing data which is subject to change until your invoice is finalized", and (2) "Pub/Sub only provides at-least-once delivery. You might receive a message multiple times, and messages might arrive out of order." Jittor's `GoogleVertexBudgetTelemetryAdapter` (`src/google-vertex/budget-telemetry.ts`) selects the freshest pulled message by its own Pub/Sub `publishTime`, fails closed (throws) on any message that doesn't match the documented schema, and reports this signal at a lower confidence (`0.6`, vs. `0.8` for Codex's header-derived windows) than a per-response header would earn. `spend`/`cap` are recorded as real USD metrics and their `spend-fraction` ratio is left unclamped (so a genuine over-cap soft-quota period stays visible); only the policy-facing `BudgetWindow.usedFraction` is clamped to `1.0`, since a known-to-be-≥100% real number floored to the window's documented `[0,1]` invariant is not the same thing as fabricating one from nothing.
 
 Setting this up requires one-time configuration outside Jittor for each individual project: create a Pub/Sub topic, connect it to the project's budget (Project Owner/Editor role, plus Pub/Sub Admin on whichever project holds the topic), and create a pull subscription on it. Jittor only consumes the subscription; it does not provision any of this GCP-side configuration itself.
 

package/docs/TOKEN_MEASUREMENT.md

@@ -0,0 +1,53 @@
+# Token measurement provenance
+
+Jittor treats token counts as measurements with explicit scope and provenance. A number is not enough: provider request usage, a provider count API, exact tokenization of one text value, and `char/4` structural estimates have different authority and must not be blended or relabeled.
+
+## Stable measurement shape
+
+`TokenMeasurement` contains only bounded metadata:
+
+- `tokens`: a non-negative safe integer.
+- `scope`: `request-context`, `request-input`, `response-output`, `cache-read`, `cache-write`, `context-item`, or `unattributed-residual`.
+- `provenance`: `provider-reported`, `provider-count-api`, `tokenizer-exact-text`, or `structural-estimate`.
+- `method`: a bounded counter identity such as `pi-assistant-usage`, `gpt-tokenizer:o200k_base`, or `char/4`.
+- Optional provider/model identity, present together.
+
+Raw text, prompts, responses, tool arguments/results, paths, credentials, and tokenizer input are not valid fields and fail strict validation.
+
+## Authority and reconciliation
+
+Provider-reported request totals remain the runtime authority. Exact local tokenization applies only to the supplied text; it does not include provider message envelopes, chat templates, tool schemas, images, cache-control serialization, or provider-side rewrites.
+
+`reconcileRequestTokens()` therefore keeps three distinct facts:
+
+1. The unchanged provider aggregate.
+2. The sum of locally attributed items.
+3. An explicit unattributed residual, plus any estimate overshoot.
+
+The residual is never distributed across individual items. Until a complete request snapshot can be counted safely, an assistant turn's provider aggregate is represented with zero attributed items and the complete request count as its visible residual.
+
+## OpenAI-family local adapter
+
+`loadOpenAiTextTokenCounter(provider, model)` conservatively maps known OpenAI-family model identities to `cl100k_base`, `o200k_base`, or `o200k_harmony`. It returns `null` for an unknown provider/model instead of guessing. OpenRouter identities are supported only when the model is explicitly under `openai/`.
+
+The BPE tables are dynamically loaded only when `/context` requests exact text attribution. Importing Jittor's public API does not load them or increase daemon startup memory. Pi falls back to a visibly marked `char/4` measurement if loading or mapping fails.
+
+## TypeScript module evaluation
+
+Measured under Bun 1.3.14 on 2026-08-09 with a 1,232,000-byte corpus repeated for 20 encodes. The corpus mixed TypeScript, prose, Unicode scripts/emoji, and high-entropy hexadecimal text. Results are environment-specific engineering evidence, not universal performance claims.
+
+| Module | Version/license | Representative o200k throughput | Package/cold-load trade-off | Decision |
+|---|---|---:|---|---|
+| `gpt-tokenizer` | 3.4.0, MIT | 27.51 MB/s | About 53.1 MB npm unpacked. Standalone o200k load measured ~0.26 s / 176 MB RSS. Jittor public-index import remains ~0.02 s / 52 MB RSS; lazy GPT-5 counter load measured ~0.37 s / 185 MB RSS. | Selected for the first adapter, dynamically and one encoding at a time. |
+| `js-tiktoken` | 1.0.21, MIT | 4.95 MB/s | About 22.4 MB npm unpacked; measured ~0.02 s / 53 MB RSS cold import. Lower startup/memory, materially slower on this corpus. | Retained as prior art/fallback candidate, not a production dependency. |
+| `@huggingface/tokenizers` | 0.1.3, Apache-2.0 | Not benchmarked without a model tokenizer configuration | About 301 KB npm unpacked, excluding model `tokenizer.json` and `tokenizer_config.json`. Broad open-model support, but configuration provenance/download bounds and regex compatibility must be handled per model. | Deferred to a bounded open-model/catalog integration. |
+
+Both tested OpenAI implementations produced 6,160,000 tokens across the 20 corpus iterations. The benchmark used encoding-level APIs, not chat/request encoding, because Jittor labels this capability exact for text only.
+
+## Test layers
+
+- Domain tests validate strict serialization, provenance, fallback, residuals, overshoot, Unicode, and model mapping.
+- Adapter tests execute real `gpt-tokenizer` encodings.
+- Context integration tests attach measurements to the real hierarchy while preserving legacy `estimatedTokens` compatibility.
+- `pi-tui-harness` runs the context viewport through a real headless VT implementation.
+- `pi-process-harness` starts a real isolated Pi process, faux provider, and Jittor daemon, then verifies provider-reported token provenance through SQLite and the authenticated CLI without retaining prompt/response content.

package/docs/USAGE_BACKFILL.md

@@ -0,0 +1,35 @@
+# Historical Pi usage backfill
+
+Jittor can populate usage and cost charts from Pi's supported v1-v3 JSONL session format. The
+import boundary is separate from live extension collection and is local-only: it performs no
+network requests and never writes to Pi sessions.
+
+```text
+jittor backfill status [--json]
+jittor backfill dry-run [--json]
+jittor backfill run [--json]
+jittor backfill cancel [--json]
+```
+
+The source defaults to `$HOME/.pi/agent/sessions`; `JITTOR_PI_SESSIONS_DIR` selects a different
+supported Pi session root. Scans are bounded by file count, per-file and total bytes, entries,
+records, and elapsed time. A truncated or canceled run reports that state and can safely be resumed
+by running it again.
+
+Only assistant, compaction, and branch-summary usage objects are translated. Persisted facts are:
+timestamp, provider/model/thinking identity, input/output/cache-read/cache-write tokens,
+provider-reported total cost, and a SHA-256 opaque identity derived from the high-entropy session
+identity plus entry identity. Prompts, responses, summaries, tool arguments/results, commands,
+paths, session names, credentials, and raw session/entry IDs are discarded before the daemon store
+boundary.
+
+Each opaque identity is claimed in the same SQLite transaction as its five usage/cost observations.
+Repeated, concurrent, moved-directory, and restart imports are therefore idempotent. A matching
+live observation at the same provider/model/timestamp and values is recognized before insertion,
+so imported history does not double-count live collection. Imported rows retain `imported: true`;
+they otherwise use the same `pi` source, provider/model scope, metric names, and provider-reported
+token provenance as live rows, so existing charts work without a second query path.
+
+Import status and the last bounded cursor/progress result survive daemon restart. A stale `running`
+flag is never trusted after restart. Database recreation intentionally loses both metrics and import
+identities; rerunning the import repopulates the new database deterministically.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@danypops/jittor",
-  "version": "0.16.3",
-  "description": "Just-in-Time Token Optimizing Router for Pi -- supervised daemon, router policy, and CLI",
+  "version": "0.17.0",
+  "description": "Just-in-Time Token Optimization Router for Pi -- token and context observability with optimization policies",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -19,7 +19,8 @@
     "@danypops/vehicle-core": "^0.12.1",
     "@danypops/vehicle-server": "^0.17.0",
     "@danypops/vehicle-client": "^0.5.1",
-    "google-auth-library": "^10.9.0"
+    "google-auth-library": "^10.9.0",
+    "gpt-tokenizer": "^3.4.0"
   },
   "devDependencies": {
     "bun-types": "latest"

package/src/{providers/anthropic-contracts.ts → anthropic/rate-limits.ts}

@@ -1,4 +1,4 @@
-import type { MetricObservation } from "../domain/metric.ts";
+import type { MetricObservation } from "../observability/metric.ts";
 
 /**
  * Official Anthropic Messages API rate-limit response headers, verified against

package/src/{adapters/artificial-analysis-direct-source.ts → artificial-analysis/benchmark-source.ts}

@@ -1,12 +1,12 @@
 import { BENCHMARK_MAX_MODELS_PER_SOURCE, BENCHMARK_REFRESH_INTERVAL_MS, BENCHMARK_SOURCE_MAX_RESPONSE_BYTES } from "../constants.ts";
+import { contractRecord } from "../openrouter/contracts.ts";
 import {
 	type BenchmarkObservation,
 	type BenchmarkSourceSnapshot,
 	normalizeModelIdentity,
 	validateBenchmarkObservation,
-} from "../domain/benchmark.ts";
-import type { BenchmarkSource } from "../ports/benchmark-source.ts";
-import { contractRecord } from "../providers/openrouter-contracts.ts";
+} from "../optimization/model-selection/benchmark.ts";
+import type { BenchmarkSource } from "../optimization/model-selection/source.ts";
 
 const SOURCE_ID = "artificial-analysis-direct";
 const ENDPOINT = "https://artificialanalysis.ai/api/v2/data/llms/models";

package/src/cli-commands/backfill.ts

@@ -0,0 +1,51 @@
+import type { UsageImportResult, UsageImportStatus } from "../observability/usage-import.ts";
+import type { CliDependencies } from "./support.ts";
+
+export const BACKFILL_USAGE_LINES = ["  backfill <status|dry-run|run|cancel> [--json]"];
+
+export function formatUsageImportResult(result: UsageImportResult): string {
+	return [
+		`Pi usage backfill: ${result.dryRun ? "dry run" : result.canceled ? "canceled" : "complete"}${result.truncated ? " · bounded/truncated" : ""}`,
+		`Records: ${result.discovered.toLocaleString()} discovered · ${result.imported.toLocaleString()} imported · ${result.duplicates.toLocaleString()} duplicates`,
+		`Scanned: ${result.filesScanned.toLocaleString()} files · ${result.entriesScanned.toLocaleString()} entries · ${result.bytesScanned.toLocaleString()} bytes · ${result.malformedEntries.toLocaleString()} malformed`,
+	].join("\n");
+}
+
+export function formatUsageImportStatus(status: UsageImportStatus): string {
+	if (!status.lastResult)
+		return `Pi usage backfill: ${status.running ? "running" : "not run"}${status.cancelRequested ? " · cancellation requested" : ""}`;
+	return `${status.running ? "Running" : "Last run"}${status.cancelRequested ? " · cancellation requested" : ""}\n${formatUsageImportResult(status.lastResult)}`;
+}
+
+export async function runBackfillCommand(
+	action: string | undefined,
+	rest: string[],
+	deps: CliDependencies,
+	usage: () => number,
+): Promise<number> {
+	if (!action || !["status", "dry-run", "run", "cancel"].includes(action)) return usage();
+	let json = false;
+	for (const argument of rest) {
+		if (argument !== "--json") return usage();
+		json = true;
+	}
+	try {
+		const result =
+			action === "status"
+				? await deps.client.call("usage.import_status", {})
+				: action === "cancel"
+					? await deps.client.call("usage.import_cancel", {})
+					: await deps.client.call("usage.import", { dryRun: action === "dry-run" });
+		deps.stdout(
+			json
+				? JSON.stringify(result)
+				: action === "run" || action === "dry-run"
+					? formatUsageImportResult(result as UsageImportResult)
+					: formatUsageImportStatus(result as UsageImportStatus),
+		);
+		return 0;
+	} catch (error) {
+		deps.stderr(error instanceof Error ? error.message : String(error));
+		return 1;
+	}
+}

package/src/cli-commands/benchmarks.ts

@@ -7,10 +7,10 @@ import {
 	MODEL_RANKING_DEFAULT_RELIABILITY_WEIGHT,
 	MODEL_RANKING_MAX_SOURCES,
 } from "../constants.ts";
-import type { BenchmarkQuery, BenchmarkQueryResult, BenchmarkRefreshResult } from "../domain/benchmark.ts";
-import { type ModelTaskDomain, type ModelTaskType, TASK_DOMAINS, TASK_TYPES } from "../domain/model-observation.ts";
-import type { ModelCandidate, ModelRankingResult, ScopeAuthority, UtilityWeights } from "../domain/model-ranking.ts";
-import type { ModelRecommendationInput } from "../domain/model-ranking-service.ts";
+import { type ModelTaskDomain, type ModelTaskType, TASK_DOMAINS, TASK_TYPES } from "../observability/model-observation.ts";
+import type { BenchmarkQuery, BenchmarkQueryResult, BenchmarkRefreshResult } from "../optimization/model-selection/benchmark.ts";
+import type { ModelRecommendationInput } from "../optimization/model-selection/ranker.ts";
+import type { ModelCandidate, ModelRankingResult, ScopeAuthority, UtilityWeights } from "../optimization/model-selection/ranking.ts";
 import { parseCandidate } from "./route-args.ts";
 import { type CliDependencies, humanField } from "./support.ts";