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

schema_version

prices.v1.

table_id

Stable table identifier.

generated_utc

Producer generation timestamp, as text.

not_a_forecast

A non-empty statement that includes the words not a forecast. The table is rejected when the phrase is absent.

caveats

Optional list of additional source or interpretation caveats.

rows

One object per path/product/period, described below.

Each row has these fields:

Field

Type

Meaning

path_id

string

base, high, low, or policy_shock.

product

string

Product identifier, such as sawlog or pulp.

period

integer

Non-negative period index.

value

number

Finite, non-negative value in unit.

unit

string

Unit of the value, such as CAD/m3.

currency

string

Currency code, such as CAD.

region

string

Region the value applies to.

source

string

Source identifier for the value.

source_version

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

price_path_comparison.csv

One row per path/product/period with value, base_value, delta, and delta_pct. delta_pct is null when base_value is zero.

price_path_report.md

A human-readable report with the caveat, the table’s provenance, a per-path and per-product summary, the full comparison, and the limits.

price_path_provenance.json

A ws4.prices.report.v1 record with the input file’s name, byte size, and SHA-256, the path and product/period grid, each distinct path/source/source-version combination with the products and periods it covers, the caveat, the comparison definition, and each output file’s size and digest.

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 forecast statement.

  • Reading the table changes no model behaviour. There is no objective weight, constraint, growth curve, schedule, or solver change.

Cross-references