Scenario price paths
Purpose
A prices.v1 table states product prices or costs for named scenarios. WS4 reads
one table, compares every named path with the base path, and writes the comparison
with its provenance.
The table is a scenario input. It does not enter the compiled dataset, the simulator’s growth, the objective, the schedule, or the solver. WS4 does not forecast a price, convert a currency, adjust for inflation, or fill a missing product or period.
Warning
The values are assumptions, not a forecast. Every table must say so in its
not_a_forecast field, and the command repeats the statement in its output and in
the written report.
Schema
The table is UTF-8 JSON with schema_version set to prices.v1. Its top-level
fields are:
Field |
Contents |
|---|---|
|
|
|
Stable table identifier. |
|
Producer generation timestamp, as text. |
|
A non-empty statement that includes the words |
|
Optional list of additional source or interpretation caveats. |
|
One object per path/product/period, described below. |
Each row has these fields:
Field |
Type |
Meaning |
|---|---|---|
|
string |
|
|
string |
Product identifier, such as |
|
integer |
Non-negative period index. |
|
number |
Finite, non-negative value in |
|
string |
Unit of the value, such as |
|
string |
Currency code, such as |
|
string |
Region the value applies to. |
|
string |
Source identifier for the value. |
|
string |
Source version, vintage, or access date. |
The named paths are base, high, low, and policy_shock. base is
mandatory because it is the comparison baseline; a table may carry any subset of the
other named paths. Every path must cover exactly the base path’s product/period grid.
A product keeps one unit across all paths, and the whole table has one currency and one
region.
Example
{
"schema_version": "prices.v1",
"table_id": "fixture-scenario-prices",
"generated_utc": "2026-11-03T00:00:00+00:00",
"not_a_forecast": "Synthetic scenario inputs; not a forecast of market prices.",
"caveats": ["No inflation adjustment or currency conversion is applied."],
"rows": [
{
"path_id": "base",
"product": "sawlog",
"period": 1,
"value": 72.5,
"unit": "CAD/m3",
"currency": "CAD",
"region": "British Columbia, Canada",
"source": "synthetic-fixture",
"source_version": "2026-11-03"
}
]
}
Command
ws4 price-paths --table tests/fixtures/prices/paths.json --out runtime/prices
The command writes three files:
File |
Contents |
|---|---|
|
One row per path/product/period with |
|
A human-readable report with the caveat, the table’s provenance, a per-path and per-product summary, the full comparison, and the limits. |
|
A |
The delta is value - base_value at the same product and period. The percent delta is
100 * delta / base_value. The report does not rank the paths or claim that one is
more likely.
Provenance and limits
The sidecar hashes the input table and the two report files; it does not hash the data behind a source or prove who produced it.
A digest detects change. It is not a signature, a timestamp authority, or a trust anchor.
The loader rejects a table that omits the base path, names an unknown path, repeats a row, disagrees on the product/period grid, mixes a product’s unit, currency, or region, contains a negative or non-finite value, or lacks the
not a forecaststatement.Reading the table changes no model behaviour. There is no objective weight, constraint, growth curve, schedule, or solver change.