Ecosystem package and cohort state
Purpose
The ecosystem package is an optional sidecar that declares the ecological state of a compiled dataset. It does not change the management dataset. A dataset with no package behaves exactly as before; the simulator, the optimizer, and every existing account keep working. When a package is present, the engine can read cohorts, aggregate them to fragments, and apply a declared bridge back to the management state.
The package starts with the state schema, the cohort table, and the null bridge. Process definitions and scenarios are recorded as optional files for later tasks; this page does not execute them.
Backward compatibility
The package lives at:
dataset/
manifest.json # the compiled management dataset
fragments.parquet
...
ecosystem/
manifest.json # the optional ecosystem package
state_variables.csv
cohorts.csv
bridges.csv
find_ecosystem_package(dataset_dir) returns the sidecar directory or None.
load_dataset_ecosystem(dataset_dir) returns the loaded package or None. A caller that
does not ask for the package never pays for it.
Manifest
The manifest is a closed schema. Unknown fields are rejected. Required fields:
schema_versionws4.ecosystem.v1.package_idProducer-assigned identifier.
created_utcISO-8601 creation timestamp.
producernameandversion.sourcesA list of
pathandsha256records.table_filesOptional table name to file name. The defaults are
state_variables.csv,cohorts.csv, andbridges.csv.table_hashesOptional table name to SHA-256 digest. When present, every digest is verified.
Optional fields:
processesA process-definition file. It is recorded and hashed, but not loaded yet.
scenariosA scenario-definition file. It is recorded and hashed, but not loaded yet.
calibrationA calibration file. It is recorded and hashed, but not loaded yet.
metadataFree-form, public-safe metadata.
Package tables are CSV. A non-CSV table is rejected rather than guessed at. The package fingerprint is a stable SHA-256 over the manifest and every loaded file.
State variables
state_variables.csv declares the typed state:
Column |
Type |
Scope |
Meaning |
|---|---|---|---|
|
string |
— |
Unique variable name. |
|
string |
— |
|
|
string |
— |
|
|
string |
— |
Unit label, or empty for dimensionless. |
|
string |
— |
Typed default, or empty when the variable has no default. |
|
string |
— |
Human-readable description. |
The cohort table requires six declared variables with scope cohort:
species (string), age (int), area_fraction (float), biomass_t_ha (float),
fuel_t_ha (float), and snag_t_ha (float). Additional cohort-scope variables may be
carried in attributes_json. The loader rejects an attribute that is not declared, and a
fixed column cannot be repeated as an attribute.
Cohorts
cohorts.csv stores the ecological state as area fractions of a fragment:
Column |
Type |
Meaning |
|---|---|---|
|
integer |
The dataset fragment. It must exist when the state is joined to a dataset. |
|
integer |
Unique within the fragment. |
|
string |
Species or species mixture label. |
|
integer |
Cohort age in years, non-negative. |
|
number |
Share of the fragment in (0, 1]. Fractions must sum to 1 per fragment. |
|
number |
Live biomass, non-negative. |
|
number |
Surface fuel, non-negative. |
|
number |
Standing dead, non-negative. |
|
string |
A JSON object of declared cohort-scope scalar attributes. |
A blank numeric cell uses the declared default. A blank cell with no default is an error. The cohort table may be empty; the package then declares a schema but no ecological state.
Aggregation
CohortState joins the cohorts to a dataset’s fragment areas and provides:
aggregate_to_fragments()— one row per covered fragment with area, cohort count, and area-weighted age, biomass, fuel, and snags.species_fractions()— one row per fragment and species with area fraction and area.cohort_areas()— the cohort rows plus fragment area and absolute cohort area.missing_fragments()— dataset fragments the package does not cover.check_area_conservation()— every covered fragment’s fractions sum to one and its cohort areas sum to the fragment area.
The area of a cohort is area_fraction × fragment area. The aggregation is exact by
construction; the conservation check makes the invariant explicit.
The null bridge
bridges.csv declares the bridge from ecological state to management state:
Column |
Type |
Meaning |
|---|---|---|
|
string |
Unique bridge identifier. |
|
string |
Only |
|
string |
A JSON object of bridge parameters. |
|
string |
Semicolon-separated declared state variables the bridge reads. |
|
string |
Semicolon-separated declared state variables the bridge writes. |
The null bridge is the explicit no-op. It returns the management frame unchanged and must
not declare state_writes. It is the contract the calibrated yield bridge will replace,
not a hidden default. A package must declare at least one bridge.
Command
ws4 ecosystem validate-package --package dataset/ecosystem
ws4 ecosystem validate-package --package dataset/ecosystem --json
The text report shows the package id, schema version, state-variable count, cohort count,
bridge ids, and fingerprint. --json emits a stable report with a valid flag and every
finding as code, where, and message.
Validation codes
ECOSYSTEM-MISSING-DIRThe package directory does not exist.
ECOSYSTEM-MISSING-MANIFESTmanifest.jsonis missing.ECOSYSTEM-BAD-MANIFESTThe manifest does not parse or has an unknown field.
ECOSYSTEM-SCHEMA-VERSIONThe schema version is not
ws4.ecosystem.v1.ECOSYSTEM-MISSING-TABLEA required table or optional file is missing.
ECOSYSTEM-MISSING-COLUMNA required column is missing.
ECOSYSTEM-EXTRA-COLUMNA table has an unexpected column.
ECOSYSTEM-DUPLICATEA declared key is not unique.
ECOSYSTEM-TABLE-FORMATA table is not CSV.
ECOSYSTEM-HASHA table digest does not match the manifest.
ECOSYSTEM-STATEA state-variable declaration is invalid.
ECOSYSTEM-STATE-MISSINGA required cohort variable is not declared.
ECOSYSTEM-STATE-TYPEA required cohort variable has the wrong dtype or scope.
ECOSYSTEM-COHORTA cohort row is invalid.
ECOSYSTEM-COHORT-FRACTIONA fragment’s area fractions do not sum to one.
ECOSYSTEM-BRIDGEA bridge declaration is invalid.
ECOSYSTEM-BRIDGE-MISSINGThe package declares no bridge.
ECOSYSTEM-UNKNOWN-FRAGMENTA cohort names a fragment outside the dataset.
ECOSYSTEM-DATASET-MISSINGThe dataset has no
fragments.parquet.ECOSYSTEM-DATASET-COLUMNSThe dataset fragment table lacks
fragment_idorarea_ha.
Limits
The package is dataset-independent until
cohort_state()joins it. The package validator does not know the dataset’s fragment ids.A fragment with no cohorts is allowed and reported by
missing_fragments().Only the null bridge is implemented. A calibrated yield bridge is a later task.
Process definitions and scenarios are recorded but not executed. The fire process and the scenario ensemble are later P144 tasks.
Tables are CSV. A columnar cohort table is a later performance decision.