@oneciel-ai/ciel-runtime 0.2.22 → 0.2.23

package/docs/journal/2026/08/23/mia-openrouter-ox-alpha-latency-diagnosis.okf

@@ -0,0 +1,146 @@
+okf_version: "1.0"
+knowledge:
+  task:
+    id: mia-openrouter-ox-alpha-latency-diagnosis-20260823
+    date: "2026-08-23"
+    objective: >-
+      Determine from live host, runtime, source, and provider evidence why the
+      Mia Codex session using OpenRouter Ox Alpha is slow.
+    status: diagnosis_complete
+
+  scope:
+    host: aap-pool-hera
+    user: mia
+    session_id: 01a02d19-baff-7410-9d91-dc7b932aee82
+    runtime_version: 0.2.22-nightly.20260823-070606.65e69f1
+    provider: openrouter
+    model: stealth/ox-alpha
+
+  confirmed_evidence:
+    reasoning_projection:
+      codex_log_effort: low
+      installed_openrouter_adapter_override_present: false
+      projection_probe:
+        requested_effort: low
+        projected_effort: null
+      provider_request_builder_behavior: >-
+        Adds reasoning_effort only when the provider adapter returns a
+        non-empty normalized effort.
+      openrouter_model_metadata:
+        reasoning_mandatory: true
+        reasoning_default_enabled: true
+        reasoning_default_effort: max
+        supported_efforts: [max, high, low]
+      conclusion: >-
+        The Mia UI/Codex request selected low, but ciel-runtime omitted the
+        reasoning_effort field on the OpenRouter Chat Completions wire. Ox
+        Alpha therefore used its documented default max reasoning effort.
+
+    observed_latency:
+      first_ox_task:
+        model_calls: 19
+        minimum_seconds: 8.470
+        median_seconds: 19.171
+        maximum_seconds: 119.111
+      following_ox_task:
+        observed_model_calls: 17
+        minimum_seconds: 4.855
+        median_seconds: 11.076
+        maximum_seconds: 28.510
+
+    rate_limit:
+      observed_at_utc: "2026-08-23T07:45:46.900Z"
+      result: "429 Too Many Requests"
+      task_result: "exceeded retry limit"
+      local_rate_limit_rpm: 0
+      local_rate_limit_status: false
+      openrouter_key_is_free_tier: false
+      openrouter_key_limit: null
+
+    request_shape:
+      messages: 193
+      tools: 12
+      context_estimate_tokens: 112445
+      observed_router_request_tokens_range: [131060, 146479]
+      observed_router_request_bytes_range: [595898, 672272]
+      note: >-
+        This is a substantial repeated request load, but its independent share
+        of total latency was not isolated in this diagnosis.
+
+    network_and_host:
+      openrouter_models_http_samples: 5
+      openrouter_models_http_total_seconds_range: [0.137942, 0.156657]
+      router_process_cpu_percent: 0.7
+      router_process_rss_kib: 69680
+      conclusion: >-
+        No evidence was observed that Mia-to-OpenRouter network round-trip or
+        Mia host CPU saturation explains the multi-second model waits.
+
+    upstream_endpoint:
+      endpoint_count: 1
+      provider_name: Stealth
+      uptime_last_5m_percent: 99.98009342817709
+      latency_last_30m: null
+      throughput_last_30m: null
+
+  diagnosis:
+    primary_confirmed_cause: >-
+      ciel-runtime drops Codex's low reasoning effort for OpenRouter Ox Alpha,
+      causing the mandatory-reasoning model to fall back to max effort.
+    additional_confirmed_degradation:
+      - "The live session received an upstream 429 and the turn ended after the configured zero Codex retries."
+      - "Large 0.60-0.67 MB agent-history requests are sent on successive tool steps."
+    not_supported_by_evidence:
+      - "Mia host CPU saturation"
+      - "Mia-to-OpenRouter network latency"
+      - "A local Ollama bottleneck in this OpenRouter session"
+
+  mutations:
+    runtime_config_changed: false
+    process_restarted: false
+    source_code_changed: true
+    source_fix:
+      behavior: >-
+        OpenRouter now forwards the explicit request effort or the preserved
+        ciel_runtime_reasoning_effort metadata value on Chat Completions wires.
+      scope: provider-wide
+      mia_specific_exception: false
+
+  fix_verification:
+    projected_request:
+      requested_effort: low
+      forwarded_effort: low
+    live_openrouter_request:
+      http_status: 200
+      elapsed_seconds: 2.713
+      prompt_tokens: 91
+      completion_tokens: 3
+      cost: 0
+    focused_tests: "61 passed"
+    full_suite:
+      total: "2698 passed, 136 skipped"
+      unit: "1148 passed, 44 skipped"
+      router: "917 passed"
+      channel: "381 passed, 80 skipped"
+      runtime: "252 passed, 12 skipped"
+    quality:
+      ruff: passed
+      documentation_metadata: passed
+      package_dry_run: "passed; 404 entries"
+    local_install:
+      status: passed
+      path: C:/Users/djlov/.local/share/ciel-runtime
+      source_hash_matched: true
+      installed_projected_effort: low
+    nightly_publish:
+      status: passed
+      commit: c243e753eb9ba3d9a3471611421751a37806972a
+      version: 0.2.22-nightly.20260823-082018.c243e75
+      ci_run: 32627887859
+      publish_run: 32627887878
+      registry_git_head_matched: true
+      tarball_verified: true
+    npm_global_install:
+      status: passed
+      version: 0.2.22-nightly.20260823-082018.c243e75
+      installed_projected_effort: low

package/docs/journal/2026/08/23/openrouter-opencode-ox-alpha-support.okf

@@ -0,0 +1,114 @@
+okf_version: "1.0"
+knowledge:
+  task:
+    id: openrouter-opencode-ox-alpha-support-20260823
+    date: "2026-08-23"
+    objective: >-
+      Add verified Ox Alpha model identities and wire-protocol routing for
+      OpenRouter, OpenCode Zen, and OpenCode Go.
+
+  official_evidence:
+    openrouter:
+      model_id: stealth/ox-alpha
+      models_api: https://openrouter.ai/api/v1/models
+      context_window: 1048576
+      max_output_tokens: 131072
+      input_modalities: [text, image, video]
+      output_modalities: [text]
+      supported_parameters:
+        - reasoning
+        - reasoning_effort
+        - tool_choice
+        - tools
+      openai_sdk_base_url: https://openrouter.ai/api/v1
+      anthropic_sdk_base_url: https://openrouter.ai/api
+    opencode_zen:
+      models_api: https://opencode.ai/zen/v1/models
+      model_id: x-preview-f-free
+      endpoint: https://opencode.ai/zen/v1/chat/completions
+      live_catalog_count: 64
+      retired_managed_fallback: qwen3.6-plus-free
+    opencode_go:
+      models_api: https://opencode.ai/zen/go/v1/models
+      model_id: ox-alpha-free
+      endpoint: https://opencode.ai/zen/go/v1/chat/completions
+      live_catalog_count: 29
+
+  implementation:
+    openrouter:
+      behavior:
+        - Adds stealth/ox-alpha to the configured model fallback catalog.
+        - Uses OpenAI Chat Completions for OpenAI/Codex requests.
+        - Uses OpenRouter's Anthropic Messages compatibility endpoint for Claude requests.
+        - Applies the verified 1,048,576 context and 131,072 output profile on selection.
+    opencode:
+      behavior:
+        - Adds the exact public Zen and Go model IDs to each provider catalog.
+        - Routes both aliases through their documented Chat Completions endpoints.
+        - Removes the retired qwen3.6-plus-free Zen fallback from new and migrated configs.
+        - Routes Zen GPT/Grok/Muse models through Responses and Gemini through Google Generative.
+        - Routes Zen DeepSeek/GLM/Hy3/Kimi/Laguna/MiMo/MiniMax/Nemotron models through Chat Completions.
+        - Routes Go GPT/Grok/Muse models through Responses, MiniMax/Qwen through Messages, and the remaining documented open models through Chat Completions.
+    migration:
+      behavior:
+        - Merges models into existing custom model lists.
+        - Preserves existing user-defined endpoint overrides.
+
+  verification:
+    public_model_api:
+      status: passed
+      observations:
+        - "OpenRouter returned HTTP 200 and contained stealth/ox-alpha."
+        - "OpenCode Zen returned HTTP 200 and contained x-preview-f-free."
+        - "OpenCode Go returned HTTP 200 and contained ox-alpha-free."
+    request_projection:
+      status: passed
+      openrouter_openai: https://openrouter.ai/api/v1/chat/completions
+      openrouter_anthropic: https://openrouter.ai/api/v1/messages
+      opencode_zen: https://opencode.ai/zen/v1/chat/completions
+      opencode_go: https://opencode.ai/zen/go/v1/chat/completions
+    live_catalog_route_matrix:
+      status: passed
+      opencode: "64 models checked; 0 protocol mismatches"
+      opencode_go: "29 models checked; 0 protocol mismatches"
+      retired_qwen_free_present: false
+    focused_tests: "114 passed"
+    full_suite:
+      total: "2696 passed, 136 skipped"
+      unit: "1148 passed, 44 skipped"
+      router: "915 passed"
+      channel: "381 passed, 80 skipped"
+      runtime: "252 passed, 12 skipped"
+    quality:
+      ruff: passed
+      documentation_metadata: passed
+      diff_check: passed
+      package_dry_run: "passed; 403 entries"
+    local_install:
+      status: passed
+      path: C:/Users/djlov/.local/share/ciel-runtime
+      version_output: ciel-runtime 0.2.22
+      source_hashes_matched: true
+      installed_catalog_and_route_check: passed
+      installed_live_catalog_matrix:
+        opencode: "64 models checked; 0 protocol mismatches"
+        opencode_go: "29 models checked; 0 protocol mismatches"
+    live_generation:
+      status: not_run
+      reason: >-
+        No OpenRouter, OpenCode Zen, or OpenCode Go API key was configured in
+        the process environment or local ciel-runtime provider configuration.
+    nightly_publish:
+      status: passed
+      workflow_run: 32624300464
+      workflow_url: https://github.com/OneCielAI/ciel-runtime/actions/runs/32624300464
+      commit: 70c5d32ece7636b0a61a43c38742b92ce2ea91a0
+      version: 0.2.22-nightly.20260823-070025.70c5d32
+      registry_git_head_matched: true
+    npm_global_install:
+      status: passed
+      version: 0.2.22-nightly.20260823-070025.70c5d32
+      path: C:/Users/djlov/AppData/Roaming/npm/node_modules/@oneciel-ai/ciel-runtime
+      installed_live_catalog_matrix:
+        opencode: "64 models checked; 0 protocol mismatches"
+        opencode_go: "29 models checked; 0 protocol mismatches"

package/docs/journal/2026/08/23/tabitoken-provider-model-catalog.okf

@@ -0,0 +1,97 @@
+okf_version: "1.0"
+knowledge:
+  task:
+    id: tabitoken-provider-model-catalog-20260823
+    date: "2026-08-23"
+    objective: >-
+      Determine whether ciel-runtime supports tabitoken.com and implement its
+      currently published provider endpoints and model catalog.
+    status: complete
+
+  official_evidence:
+    pricing_page:
+      url: https://tabitoken.com/pricing
+      observed_enabled_models: 4
+      models:
+        - claude-opus-4-8
+        - claude-opus-4-8-thinking
+        - claude-opus-5
+        - claude-opus-5-thinking
+      endpoint_badges: [anthropic, openai]
+      displayed_context_tag: 1M
+    pricing_api:
+      url: https://tabitoken.com/api/pricing
+      status: 200
+      success: true
+      anthropic: "POST /v1/messages"
+      openai: "POST /v1/chat/completions"
+    api_detail:
+      base_url: https://tabitoken.com
+      authentication: "Authorization: Bearer <TOKEN> for all endpoints"
+      anthropic_alternative_authentication: x-api-key
+      thinking_models_parameter: reasoning_effort
+      thinking_models_default_effort: medium
+      non_thinking_models_parameter: temperature
+      shared_parameters_include: [stream, tools, tool_choice]
+
+  prior_support_audit:
+    repository_search: >-
+      A case-insensitive search for tabitoken and tabi-token returned no source,
+      test, documentation, alias, or provider registration match.
+    result: unsupported_before_this_change
+
+  implementation:
+    provider_id: tabitoken
+    aliases: [tabi, tabiai, tabi-token]
+    adapter: ciel_runtime_support/providers/tabitoken.py
+    protocols: [anthropic_messages, openai_chat]
+    authentication: bearer
+    context_window: 1000000
+    reasoning_scope: "Only model IDs ending in -thinking"
+    fallback_models_source: https://tabitoken.com/api/pricing
+
+  verification:
+    focused_tests: "57 passed"
+    full_suite:
+      total: "2704 passed, 136 skipped"
+      unit: "1148 passed, 44 skipped"
+      router: "923 passed"
+      channel: "381 passed, 80 skipped"
+      runtime: "252 passed, 12 skipped"
+    ruff: passed
+    documentation_metadata: "passed; 22 Markdown files"
+    package_dry_run: "passed; 406 entries"
+    live_unauthenticated_route_probe:
+      /v1/models: 403
+      /v1/chat/completions: 403
+      /v1/messages: 403
+      interpretation: >-
+        The public host protected all three configured routes. No Tabitoken API
+        key was available, so authenticated model inference was not performed.
+    runtime_projection:
+      normalized_alias: tabitoken
+      openai_url: https://tabitoken.com/v1/chat/completions
+      anthropic_url: https://tabitoken.com/v1/messages
+      models: 4
+
+  deployment:
+    local:
+      status: passed
+      path: C:/Users/djlov/.local/share/ciel-runtime
+      source_hash_matched: true
+      installed_models: 4
+      installed_openai_url: https://tabitoken.com/v1/chat/completions
+      installed_anthropic_url: https://tabitoken.com/v1/messages
+    nightly:
+      status: passed
+      source_commit: d81eb003b7896d55b91588fbcf020fc364ef8c5b
+      version: 0.2.22-nightly.20260823-085017.d81eb00
+      ci_run: 32629221468
+      publish_run: 32629221482
+      registry_git_head_matched: true
+      published_tarball_verified: true
+      npm_global_install:
+        status: passed
+        installed_version: 0.2.22-nightly.20260823-085017.d81eb00
+        source_hash_matched: true
+        installed_models: 4

package/docs/journal/2026/08/23/usage-stream-snapshot-implementation.okf

@@ -0,0 +1,134 @@
+okf_version: "1.0"
+knowledge:
+  task:
+    id: usage-stream-snapshot-implementation-20260823
+    date: "2026-08-23"
+    objective: >-
+      Implement workspace-scoped token usage capture, authenticated real-time
+      delivery, time-range snapshots, retry-safe per-key cursors, daily audit
+      delivery, legacy backfill, startup environment configuration, and the
+      equivalent ciel-runtimectl configuration surface.
+    status: implementation-complete
+
+  architecture:
+    storage:
+      kind: sqlite
+      workspace_scoped: true
+      relative_path: usage/usage.sqlite3
+      immutable_event_sequence: true
+    inbound_interfaces:
+      events: GET /ca/usage/events
+      stream: GET /ca/usage/stream
+      snapshot: GET /ca/usage/snapshot
+      key_administration: /ca/usage/keys
+    outbound_interfaces:
+      event_type: ai.oneciel.ciel-runtime.usage.recorded
+      audit_type: ai.oneciel.ciel-runtime.usage.audit
+      envelope: CloudEvents-1.0
+      retry_rule: cursor advances only after HTTP 2xx
+      idempotency_rule: event ID and Idempotency-Key remain stable across retry
+      cursor_identity: endpoint ID plus URL plus expanded authorization fingerprint
+    audit:
+      default_interval_seconds: 86400
+      contains: [period, totals, rates, groups, sequence_coverage]
+    backfill:
+      inputs: [workspace-owned usage-events.jsonl, usage-events.jsonl.1, explicit paths]
+      cursor: per-source-byte-offset
+      rotation_deduplication: deterministic legacy event ID
+      incomplete_trailing_line: deferred
+
+  configuration:
+    startup_environment:
+      - CIEL_RUNTIME_USAGE_API_KEY
+      - CIEL_RUNTIME_USAGE_API_KEYS
+      - CIEL_RUNTIME_USAGE_PUSH_ID
+      - CIEL_RUNTIME_USAGE_PUSH_URL
+      - CIEL_RUNTIME_USAGE_PUSH_AUTHORIZATION
+      - CIEL_RUNTIME_USAGE_PUSH_API_KEY
+      - CIEL_RUNTIME_USAGE_PUSH_ENDPOINTS
+      - CIEL_RUNTIME_USAGE_AUDIT_INTERVAL_SECONDS
+      - CIEL_RUNTIME_USAGE_BACKFILL_PATHS
+      - CIEL_RUNTIME_USAGE_LOG
+    ctl:
+      usage_events:
+        command: ciel-runtimectl usage-events
+        values:
+          - endpoint_id
+          - enabled
+          - url
+          - authorization
+          - api_key
+          - timeout_seconds
+          - poll_interval_seconds
+          - start_mode
+          - audit_interval_seconds
+          - audit_emit_on_start
+          - jsonl_enabled
+          - backfill_paths
+      usage_api_key:
+        command: ciel-runtimectl usage-api-key
+        actions: [issue, list, revoke]
+        exact_environment_equivalents: [key_id, api_key, name, scopes, expires_at]
+      persistence: workspace config plus keyed-digest API-key repository
+      shell_environment_mutation: false
+
+  confirmed_limits:
+    native_direct_runtime_usage: >-
+      Requests that bypass the Ciel router are not observed by the router ledger.
+    unrecoverable_history: >-
+      A historical period with no Ciel JSONL record and no native CLI usage
+      record cannot be reconstructed.
+    unowned_global_jsonl: >-
+      A legacy global JSONL file with no workspace identity is not assigned
+      automatically and requires an explicit backfill path.
+
+  verification:
+    focused_usage_service: "8 passed"
+    focused_event_settings_cli: "34 passed"
+    architecture_contracts: "261 passed, 42 skipped"
+    ruff: passed
+    diff_check: passed
+    main_module_lines: 4980
+    ctl_wrapper_probe:
+      destination_saved: true
+      destination_report_masked_authorization: true
+      daily_interval_seconds: 86400
+      jsonl_enabled: false
+      backfill_path_count: 1
+      exact_api_key_id: env_auditor
+      key_metadata_listed: true
+      ledger_created: true
+      pepper_created: true
+    full_suite:
+      unit: "1164 passed, 44 skipped"
+      router: "923 passed"
+      channel: "381 passed, 80 skipped"
+      runtime: "252 passed, 12 skipped"
+    documentation_metadata: "passed; 23 Markdown files"
+    package_dry_run: "passed; 411 files"
+
+  deployment:
+    local:
+      status: passed
+      path: C:/Users/djlov/.local/share/ciel-runtime
+      source_hash_matched: true
+      installed_version: 0.2.22
+    nightly:
+      status: passed
+      source_commit: 45a9456ffaa554598e5196bae3df18a936f3c88b
+      version: 0.2.22-nightly.20260823-234610.45a9456
+      ci_run: 32674465612
+      publish_run: 32674465609
+      registry_git_head_matched: true
+      published_tarball_verified: true
+      clean_registry_install:
+        status: passed
+        installed_version: 0.2.22-nightly.20260823-234610.45a9456
+        source_hash_matched: true
+      first_publish_attempt:
+        run: 32674354694
+        status: failed
+        confirmed_cause: >-
+          A Windows-specific test fixture used drive-letter paths while the
+          Linux runner used ':' as os.pathsep, producing four parts instead of
+          two. The fixture now constructs platform-native paths.

package/docs/usage-observability.md

@@ -0,0 +1,141 @@
+# Usage observability
+
+Ciel Runtime stores routed model usage in a workspace-scoped SQLite ledger and
+exposes authenticated event, stream, and period-snapshot interfaces.
+
+## Startup environment
+
+The first router start can provision consumer keys and outbound delivery without
+writing secrets into `config.json`.
+
+```powershell
+$env:CIEL_RUNTIME_USAGE_API_KEYS = '[{"id":"auditor","key":"replace-me","scopes":["usage:read","usage:stream"]}]'
+$env:CIEL_RUNTIME_USAGE_PUSH_ENDPOINTS = '[{"id":"audit-service","url":"https://audit.example/v1/ciel-usage","authorization":"Bearer ${AUDIT_SERVICE_API_KEY}","start_mode":"tail","audit_interval_seconds":86400}]'
+$env:AUDIT_SERVICE_API_KEY = 'replace-me'
+ciel-runtime
+```
+
+Single-destination variables are also supported:
+
+```text
+CIEL_RUNTIME_USAGE_API_KEY
+CIEL_RUNTIME_USAGE_PUSH_ID
+CIEL_RUNTIME_USAGE_PUSH_URL
+CIEL_RUNTIME_USAGE_PUSH_AUTHORIZATION
+CIEL_RUNTIME_USAGE_PUSH_API_KEY
+CIEL_RUNTIME_USAGE_AUDIT_INTERVAL_SECONDS
+CIEL_RUNTIME_USAGE_BACKFILL_PATHS
+```
+
+The same persistent workspace settings can be injected with
+`ciel-runtimectl`. This writes the workspace `config.json`; it does not mutate
+the parent shell's environment:
+
+```powershell
+ciel-runtimectl usage-events endpoint_id=audit enabled=true url=https://audit.example/v1/ciel-usage 'authorization=Bearer ${AUDIT_SERVICE_API_KEY}' start_mode=tail audit_interval_seconds=86400
+ciel-runtimectl usage-events endpoint_id=audit
+ciel-runtimectl usage-api-key issue name=auditor 'scopes=read,stream' ttl_seconds=2592000
+ciel-runtimectl usage-api-key list
+ciel-runtimectl usage-api-key revoke key_id=uk_replace_me
+```
+
+`usage-events` accepts `endpoint_id`, `enabled`, `url`, `authorization`,
+`api_key`, `timeout_seconds`, `poll_interval_seconds`, `start_mode`,
+`audit_interval_seconds`, `audit_emit_on_start`, `jsonl_enabled`, and
+`backfill_paths`. On
+Windows, delimit multiple `backfill_paths` with `;`; on POSIX systems use `:`.
+The issued usage API key is displayed once, while only its keyed digest is
+persisted. A running router reloads outbound destinations on its next poll;
+new `backfill_paths` are scanned on the next router start.
+
+To provision the exact identity and secret supplied through
+`CIEL_RUNTIME_USAGE_API_KEYS`, pass `key_id=... api_key=... expires_at=...` to
+`usage-api-key issue`. Omitting those values generates a new ID and secret.
+
+`CIEL_RUNTIME_USAGE_PUSH_ENDPOINTS` is a JSON array. It replaces configured
+`usage.push_endpoints` for that process. Each item supports `id`, `url`,
+`authorization` or `api_key`, `timeout_seconds`, `poll_interval_seconds`,
+`start_mode` (`tail` or `beginning`), `audit_interval_seconds`, and
+`audit_emit_on_start`.
+
+Authorization values may contain `${ENVIRONMENT_VARIABLE}` references. A
+missing reference prevents delivery and does not advance the cursor.
+
+## Consumer keys
+
+Consumer keys are distinct from upstream provider credentials and the router's
+external administration token. Only a keyed digest is stored. The plaintext is
+returned once when a key is issued.
+
+Issue a key locally, or externally with the router administration token:
+
+```http
+POST /ca/usage/keys
+Content-Type: application/json
+Authorization: Bearer <router-administration-token>
+
+{"name":"auditor","scopes":["usage:read","usage:stream"]}
+```
+
+List key metadata with `GET /ca/usage/keys`. Revoke a key with:
+
+```json
+{"action":"revoke","key_id":"uk_..."}
+```
+
+sent to `POST /ca/usage/keys` under router administration authentication.
+
+## Interfaces
+
+All consumer routes accept `Authorization: Bearer <usage-api-key>` or
+`x-ciel-usage-key: <usage-api-key>`.
+
+- `GET /ca/usage/events?from=<RFC3339-or-epoch>&to=<...>&after=<seq>&limit=200`
+  returns immutable events. Optional filters are `runtime`, `provider`, and
+  `model`.
+- `GET /ca/usage/stream?after=<seq>` streams durable events with the SQLite
+  sequence as the SSE `id`. Reconnect with the last acknowledged sequence.
+- `GET /ca/usage/snapshot?from=<RFC3339-or-epoch>&to=<...>` returns totals,
+  provider/model/runtime groups, sequence coverage, estimated/incomplete event
+  counts, requests per hour, tokens per hour, and cache-read ratio.
+
+When `from` and `to` are omitted, snapshot and event queries cover the previous
+24 hours.
+
+## Outbound delivery and audit
+
+Each configured receiver gets two CloudEvents:
+
+- `ai.oneciel.ciel-runtime.usage.recorded` for each new usage event.
+- `ai.oneciel.ciel-runtime.usage.audit` for each configured audit interval.
+
+The audit event contains the exact period boundaries, first and last ledger
+sequence, totals, rates, and provider/model/runtime groups. A percentage of a
+provider quota is not fabricated when the provider does not expose that quota.
+
+Delivery state is keyed by endpoint ID, URL, and authorization-key fingerprint.
+HTTP failure leaves both the event cursor and audit-period cursor unchanged.
+Retries reuse the same CloudEvent ID and `Idempotency-Key`; a cursor advances
+only after a 2xx response.
+
+The ledger is stored under the current workspace state directory at
+`usage/usage.sqlite3`, so different workspaces do not share usage data.
+
+## Pre-deployment backfill
+
+At router startup Ciel imports workspace-owned `usage-events.jsonl` files and
+their `.1` rotation into the SQLite ledger. Each source has a durable byte
+cursor, incomplete trailing records are left for the next startup, and legacy
+records without an event ID receive a deterministic content ID so rotation does
+not duplicate them.
+
+Older global files cannot be assigned to a workspace from their contents. They
+are therefore imported only when explicitly named:
+
+```powershell
+$env:CIEL_RUNTIME_USAGE_BACKFILL_PATHS = '["C:\\Users\\me\\AppData\\Roaming\\ciel-runtime\\usage-events.jsonl"]'
+```
+
+Backfilled legacy rows without cache/reasoning fields are marked
+`is_incomplete=true`. A period in which neither Ciel nor the native CLI stored a
+usage record cannot be reconstructed by this importer.

package/install.ps1

@@ -37,13 +37,34 @@ $prefix = if ($env:PREFIX) { $env:PREFIX } else { Join-Path $HOME ".local" }
 $defaultShareDir = Join-Path $prefix "share\ciel-runtime"
 $runtimeHome = [string]$env:CIEL_RUNTIME_HOME
 $snapshotHome = $runtimeHome -and ((Split-Path -Leaf $runtimeHome) -match '^ciel-runtime-[0-9a-f]{7,40}$')
+$expandedRuntimeHome = if ($runtimeHome) {
+    [System.IO.Path]::GetFullPath(
+        [Environment]::ExpandEnvironmentVariables($runtimeHome)
+    ).TrimEnd('\')
+} else {
+    ""
+}
+$expandedTempHome = [System.IO.Path]::GetFullPath(
+    [System.IO.Path]::GetTempPath()
+).TrimEnd(
+    [System.IO.Path]::DirectorySeparatorChar,
+    [System.IO.Path]::AltDirectorySeparatorChar
+) + [System.IO.Path]::DirectorySeparatorChar
+$temporaryRuntimeHome = (
+    $expandedRuntimeHome -and
+    $expandedRuntimeHome.StartsWith(
+        $expandedTempHome,
+        [System.StringComparison]::OrdinalIgnoreCase
+    )
+)
+$ephemeralRuntimeHome = $snapshotHome -or $temporaryRuntimeHome
 $shareDir = if ($env:CIEL_RUNTIME_INSTALL_HOME) {
     $env:CIEL_RUNTIME_INSTALL_HOME
-} elseif ($runtimeHome -and -not $snapshotHome) {
+} elseif ($runtimeHome -and -not $ephemeralRuntimeHome) {
     $runtimeHome
 } else {
-    if ($snapshotHome) {
-        Write-Warning "Ignoring snapshot CIEL_RUNTIME_HOME during install: $runtimeHome"
+    if ($ephemeralRuntimeHome) {
+        Write-Warning "Ignoring ephemeral CIEL_RUNTIME_HOME during install: $runtimeHome"
     }
     $defaultShareDir
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oneciel-ai/ciel-runtime",
-  "version": "0.2.22",
+  "version": "0.2.23",
   "description": "Universal AI coding-agent runtime and model-routing layer for Claude, Codex, AGY, and compatible runtimes.",
   "license": "MIT",
   "author": "One Ciel LLC",
@@ -42,6 +42,7 @@
     "install.sh",
     "install.ps1",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE",
     "NOTICE",
     "docs/"