Prototype: compile and simulate

The P1.6 prototype is the smallest end-to-end path that exercises the contracts. It compiles the synthetic fixture into a validated dataset, replays a plan or schedule, and writes a run directory with the account values, state values, schedule, report, and run.json.

It is not the calibrated model. The growth rule is linear and the treatment transition is a simple fractional reduction. The calibrated model is P4.

Compile

brushline build --fixture examples/synthetic-corridor --out build/compiled

The compiler reads dataset/segments.csv, corridor.json, and state.json, joins the service standards and corridor attributes onto the segments, and writes:

  • segments.parquet: segment id, corridor, length, geometry, span, sequence, treatment unit, service standard, access point, maximum height, and minimum clearance.

  • states.parquet: segment, year, functional group, state class, height, cover, density, age, confidence, source, and source version.

  • manifest.json: the brushline.dataset.v1 manifest with both tables, checksums, and the content digest.

Simulate

brushline simulate \
  --dataset build/compiled \
  --out runs/prototype \
  --plan examples/synthetic-corridor/plan.json \
  --years 5 \
  --start-year 2026

Or replay a schedule CSV:

brushline simulate \
  --dataset build/compiled \
  --out runs/prototype \
  --schedule path/to/schedule.csv \
  --years 5

The schedule CSV columns are segment_id, year, action_id, method, intensity, efficacy, and cost. Exactly one of --plan and --schedule is required.

The prototype writes:

  • schedule.csv: the replayed actions with applied or outside_horizon status.

  • account_values.csv: long account values by year.

  • state_values.csv: per-segment, per-year state values.

  • reports/summary.md: a short run report.

  • run.json: the brushline.run.v1 manifest with the artifact index and summary.

One-command path

brushline prototype \
  --fixture examples/synthetic-corridor \
  --out runs/prototype \
  --years 5

The command compiles under runs/prototype/dataset and simulates under runs/prototype/run.

Prototype rules

  • Growth: height increases by 0.25 m per year and cover by 2 percentage points per year, capped at 10 m and 100 percent.

  • Density: grows by 5 percent per year when it is known.

  • Treatment: height and cover are multiplied by 1 - efficacy; density is multiplied by 1 - 0.5 * efficacy; the action cost is charged in its year.

  • An unknown state does not grow and remains unknown.

  • A clearing violation is a known state whose height exceeds the segment’s service standard maximum.

  • No action is invented: the simulator replays only the plan or schedule.

Accounts

The prototype writes seven accounts:

Account

Unit

Meaning

vegetation.mean_height_m

m

Mean height across known states.

vegetation.mean_cover_pct

%

Mean cover across known states.

vegetation.max_height_m

m

Maximum height across known states.

vegetation.unknown_segments

count

Segments whose state is unknown.

vegetation.clearing_violations

count

Known states above the service standard maximum.

treatment.cost

currency

Cost charged in the year.

treatment.segments

count

Actions applied in the year.

Reproducibility

The simulator is deterministic given the dataset and the schedule. The same schedule reproduces the same account_values.csv and state_values.csv. run.json records the dataset content digest, the prototype model versions, the configuration, and the artifact checksums.

Validation

The test suite compiles the fixture, simulates the plan, checks the five-year accounts, replays the written schedule, compares the outputs, and exercises the three CLI paths. It also checks that a schedule with an unknown segment fails.