Freeway: self-hosted OpenAI-compatible gateway for free-tier providers

One endpoint in front of every free LLM tier, with automatic failover and no
provider key ever leaving the box.

Providers are data, not code: adding one is a JSON file plus an env var, never
a TypeScript change. Ships 12 providers pre-written; `verify-provider --apply`
derives the live model list from your own key.

- core: registry, bucketed quota meter (rolling + UTC-calendar windows),
  key-pool store, 6-step model router with diagnostic rejection reasons
- gateway: node:http, failover that commits to a stream only after 200 headers,
  SSE passthrough with usage sniffing, virtual keys with admin/inference roles
- context engine: sqlite sessions and a 5-rung refit ladder, so a 128k thread
  keeps working when it fails over to an 8k model
- cache: exact (sha256, safe-by-default) + opt-in semantic (flat Float32Array)
- guard: inbound limits, quota forecasting, limit calibration from upstream
  headers, key health, secret/PII/injection scanning
- dashboard: one self-contained HTML file, live SSE request log, token usage
- sdk: zero-dep typed client, drop-in for the OpenAI SDK

Zero runtime dependencies. 326 tests, 27-check smoke suite against a scripted
mock upstream so routing is testable without spending quota.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docker-compose.yml

@@ -0,0 +1,52 @@
+services:
+  freeway:
+    build: .
+    image: freeway:local
+    container_name: freeway
+    restart: unless-stopped
+
+    # Bound to loopback on the host. Freeway itself refuses to serve an open
+    # gateway on a public interface, but the port mapping is the outer gate.
+    ports:
+      - "127.0.0.1:8787:8787"
+
+    env_file:
+      - .env
+
+    environment:
+      HOST: 0.0.0.0
+      PORT: 8787
+      FREEWAY_ROOT: /app
+      FREEWAY_PROVIDERS: /app/providers
+      FREEWAY_DATA: /app/data
+      FREEWAY_CONFIG: /app/freeway.config.json
+      NODE_ENV: production
+
+    volumes:
+      # Read-only: adding a provider is editing a JSON file on the host and
+      # hitting POST /api/reload — no rebuild, and the container cannot rewrite
+      # its own provider definitions.
+      - ./providers:/app/providers:ro
+      - ./freeway.config.json:/app/freeway.config.json:ro
+      # Read-write: quota counters, conversation history, cache, pasted keys.
+      # This is what makes a monthly quota survive a restart.
+      - ./data:/app/data
+
+    healthcheck:
+      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:8787/healthz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
+      interval: 30s
+      timeout: 3s
+      start_period: 5s
+      retries: 3
+
+    # Nothing here needs root or any elevated capability.
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "3"