docs planning RUST_STATION_INGESTION_RST10

RST-10 — Experimental protocol and performance budgets

Status: PROTOCOL_FROZEN — no code, database, network or load-runner change. Date: 2026-10-09. Scope: RUST_STATION_INGESTION_PLAN.md RST-10, consuming RST-07 as the bounded pilot. The full campaign method lives in the sibling benchmark plan; this file freezes only the protocol artifacts below, without duplicating it. Language: English document; user communication in Portuguese.

1. Inventory (frozen context)

• Lab: Intel i7-13620H workstation, disposable PostGIS 18.6/3.6.4.
• Target class: VPS from infra/compose.prod.yml (db 8 GiB, api 2 GiB, worker 4 GiB); lab numbers are not production promises.
• Queries: SearchStations, NearbyStations, FixDistanceM plus the prep pipeline (parse/join/dedup/spill/emit) at station-prep 0.2.0.
• Versions: migration chain through 000051, sqlc v1.31.1, Go 1.27, Rust 1.99, csv 1.4.0 / serde 1.0.229 / serde_json 1.0.151 / sha2 0.10.9 (Cargo.lock tracked).
• Data: synthetic deterministic fixtures only (seeds fixed); real census size unmeasured — national fetch out of scope.
• Gaps (block SLO language until closed): no pg_stat_statements / auto_explain, single-client benches only (8-client evidence missing), one workstation (no hardware matrix).

2. Frozen artifacts (v1)

Run-manifest schema a campaign run must fill before any verdict:

{
  "id": "run-manifest-schema",
  "version": 1,
  "required": ["run_id", "workload_id", "hardware", "software", "dataset", "started_at", "metrics", "verdict"],
  "metrics": ["wall_ms", "rows_per_sec", "peak_rss_kb", "p50_ms", "p95_ms", "p99_ms", "planning_ms", "execution_ms", "table_mib", "indexes_mib", "error_count", "drop_count"],
  "verdict": ["pass", "fail", "aborted"],
  "rule": "verdict is decided from the frozen budgets below before results are seen; post-hoc thresholds are forbidden"
}

Metric dictionary (units fixed; percentiles over client-measured iterations):

{
  "id": "metric-dictionary",
  "version": 1,
  "rows_per_sec": "accepted input rows per wall second",
  "wall_ms": "end-to-end workload wall time",
  "peak_rss_kb": "process peak RSS (/usr/bin/time -v) or HeapAlloc for Go stages",
  "p50_ms": "median client-measured iteration",
  "p95_ms": "95th percentile client-measured iteration",
  "p99_ms": "99th percentile client-measured iteration",
  "planning_ms": "PostGIS planning time (EXPLAIN ANALYZE)",
  "execution_ms": "PostGIS execution time (EXPLAIN ANALYZE)",
  "table_mib": "pg_total_relation_size of the measured table",
  "indexes_mib": "pg_indexes_size of the measured table",
  "error_count": "failed operations (any failure aborts SLO claims)",
  "drop_count": "shed load (any drop aborts SLO claims)"
}

Workload IDs (fixed datasets, seeds and parameters):

{
  "id": "workload-ids",
  "version": 1,
  "W-parse-100k": "bench_generate 100000 7, both layouts, bench_parse + StageCSV",
  "W-parse-1M": "bench_generate 1000000 7, raised caps only, streaming follow-up owed",
  "W-city-dense": "Reader.Search SP/densest-code limit 20, first page",
  "W-city-sparse": "Reader.Search SP/sparsest-code limit 20, first page",
  "W-nearby-dense": "Reader.Nearby cluster center radius 5000 limit 20",
  "W-nearby-sparse": "Reader.Nearby empty area radius 5000 limit 20",
  "W-smoke-500": "existing infra load smoke (500 stations, 20 s, 8 clients)"
}

Resource ceilings and stop conditions (violations abort the run):

{
  "id": "ceilings-and-stops",
  "version": 1,
  "ceilings": {
    "parser_rss": "cap-bound, ~2.2 KiB per accepted row (interim ~1.1 GiB at 500k rows)",
    "bench_scratch": "5 GiB under /tmp, never committed",
    "single_run_wall": "30 minutes",
    "target_db": "8 GiB VPS class"
  },
  "stop_conditions": [
    "RowCap/byte-cap refusal instead of unbounded growth",
    "3-strike provider retry budget then dead-letter",
    "p99 above 2x budget aborts the run",
    "scratch above ceiling aborts the run",
    "any invented, guessed or production-scraped datum aborts the campaign"
  ],
  "allowed_variants": ["baseline vs covering index", "spill caps", "1/8/32 clients (8 required for SLO language)"]
}

3. Worksheet (budgets provisional hypotheses until 8-client evidence)

Scenario	p95 budget	p99 budget	Pilot measured
W-parse-100k	500 ms wall	1 s wall	310 ms (Rust)
W-parse-1M	30 s wall	60 s wall	3.9 s parse (raised caps)
W-city-dense	100 ms	250 ms	49.2 ms indexed at 1M
W-city-sparse	10 ms	25 ms	3.1 ms at 1M
W-nearby-dense	150 ms	300 ms	44.2 ms at 1M
W-nearby-sparse	5 ms	10 ms	0.3 ms at 1M

Parser RSS has no SLO: streaming emission is owed first (RST-07). Recovery target: crash mid-run replays to identical bytes with no partial publication (proven for staging/prep/discovery in RST-03/05/08); production recovery drills belong to the campaign.

4. Exit and next task

A reviewer reproduces any row above from the workload ID plus seed and decides pass/fail from the frozen budgets without inventing thresholds. Next (smallest, separately authorized): RST-11 datasets and geography.