# The Road Graph (engine A's data) — build, host, and the laws

Engine A routes over a **CSR road-graph binary** built from OpenStreetMap and
hosted on Cloudflare R2. The binary is a **build artifact, not a committed
file** — forks build and upload their own. Everything needed is committed:
two maintainer scripts and this doc. All of it is **$0** (Overpass public
instance, R2 free tier, Workers free plan).

## The fork contract (your graph, your bucket)

1. **Create your bucket** (once, per Cloudflare account):

   ```
   npx wrangler r2 bucket create araharah-graphs
   ```

   If `wrangler` reports that R2 is not enabled, activate it once in the
   Cloudflare dashboard (**R2 → Get started**) — account-owner steps, then
   re-run the command. Use a different name if you like, but the name must
   agree with `bot/wrangler.jsonc`'s `ROAD_GRAPH` binding (`bucket_name`).

2. **Build the KL graph** (or your own region — tune `DRIVABLE_CLASSES` /
   the bbox in the script):

   ```
   node routing/scripts/build-road-graph.mjs
   ```

   Computes the bbox from the committed corpus (gazetteer + golden pairs,
   ± 0.05°), fetches ONE Overpass extract (drivable classes only), encodes
   the pinned CSR binary through `encodeGraph`, and writes
   `routing/data/kl-roadgraph.v1.bin` — **only** after the encode round-trip
   and the size gate pass. Exit 1 leaves any previous binary untouched.

3. **Check the artifact** (decode + stats, no network):

   ```
   node routing/scripts/build-road-graph.mjs --check routing/data/kl-roadgraph.v1.bin
   ```

4. **Upload to R2**:

   ```
   node routing/scripts/upload-road-graph.mjs
   # = npx wrangler r2 object put araharah-graphs/kl-roadgraph.v1.bin \
   #       --file routing/data/kl-roadgraph.v1.bin --remote
   ```

   Verify the round-trip:

   ```
   npx wrangler r2 object get araharah-graphs/kl-roadgraph.v1.bin \
       --file /tmp/opencode/graph-roundtrip.bin --remote
   node routing/scripts/build-road-graph.mjs --check /tmp/opencode/graph-roundtrip.bin
   ```

5. **Deploy the Worker** (`npm run deploy -w bot`). `wrangler.jsonc` binds
   the bucket as `ROAD_GRAPH`; `worker-router.ts` loads the object
   `kl-roadgraph.v1.bin` once per cold isolate (module-scope memo, shared
   with the cron arm) — 1 R2 GET, not per request.

**Dev note:** with no bucket (or an empty one), `/api/route` answers `200
null` — the designed router-pending state (D-03). Dev and tests never need
the real binary; tests use the committed mini-graph fixture.

## The envelope law (D-01)

| Gate | Value | Enforcement |
|------|-------|-------------|
| Ceiling | **≤ 80 MB** | enforced — build + upload + `--check` all exit 1 over it |
| Floor | **> 1 MB** | enforced — a smaller "road graph" is a broken build |
| Expected band | **30–80 MB** | advisory — a smaller build prints a WARNING (verify the class filter) and continues |

The binary lives in `routing/data/` and is gitignored (`*.bin`): it is
ODbL-derived data, regenerated at will, never source.

## The CPU gate (A1) — OPEN: measured over the free-plan budget

Workers free plan: **10 ms CPU per request** (Error 1102 beyond it). The A\*
cost over the REAL graph is measured, never hoped:

```
node routing/scripts/measure-route-cpu.mjs
```

25 pairs (golden-corpus routes + quadrant-sampled cross-city pairs; directed
dead-end probes reported separately) timed around `routeAstar` over the real
binary. **The gate is p95 ≤ 8 ms** (20% margin under the ceiling).

**Measured state (2026-10-24, the 311k-node linked graph): GATE FAIL.** The
mitigation ladder was executed in order:

| Ladder step | Outcome |
|-------------|---------|
| full graph, unidirectional A\* | p95 ≈ 38 ms — FAIL |
| (a) drop tertiary+residential, rebuild | p95 ≈ 18 ms — FAIL **and** 12/25 pairs became unreachable (the dropped classes are the fine mesh tying landmarks to arterials) — rejected on correctness, reverted |
| (b) bidirectional A\* (BH, Ikeda potentials) | p95 ≈ 38 ms — FAIL: the potential split halves each side's heuristic steering, cancelling the halved search radius. Kept: sound (A1's 625-pair Dijkstra equivalence still passes) and better on short product routes |
| (c) Workers Paid | **NOT applied — breaks the $0 law; needs a maintainer decision** |

The decision this gate now escalates: **(c1) Workers Paid ($5/mo — breaks
$0)**, **(c2) a graph-layout v2 with ALT landmark preprocessing (still $0 at
runtime, real build-time engineering)**, or **(c3) accept free-plan routing
with honest degradation** (long reroutes may hit 1102; the client's
`createHttpRoutingSource` then degrades to the router-pending state).
Short product routes (2–8 km, the common reroute) measured 2–8 ms — inside
budget; the failures concentrate on 20–30 km cross-metro routes.

## Licensing (the ODbL attribution)

The graph is derived from OpenStreetMap data —
**© OpenStreetMap contributors, ODbL 1.0**
(<https://opendatacommons.org/licenses/odbl/1-0/>), fetched via the public
Overpass API. Hosting or redistributing the binary requires the same
attribution (ODbL's attribution clause travels with derived databases). The
route fixtures carry the same notice inside their committed envelope
(`_license`/`_attribution`/`_notice`), and this doc is the notice surface for
the hosted binary. Keep it intact in forks.

## Key facts

| What | Where |
|------|-------|
| Build tool (Overpass → CSR) | `routing/scripts/build-road-graph.mjs` |
| Upload tool (wrangler shell) | `routing/scripts/upload-road-graph.mjs` |
| CPU measurement gate | `routing/scripts/measure-route-cpu.mjs` |
| Binary (gitignored artifact) | `routing/data/kl-roadgraph.v1.bin` |
| R2 object key | `kl-roadgraph.v1.bin` (pinned in `worker-router.ts` as `GRAPH_KEY`) |
| Binding | `ROAD_GRAPH` in `bot/wrangler.jsonc` (bucket, NEVER a KV namespace — GE5) |
| Loader (isolate-memoized) | `bot/src/routing/worker-router.ts` → `loadGraph` |
| Binary layout authority | `routing/src/graph.ts` (`encodeGraph`/`decodeGraph`, pinned CSR v1) |