Artifact contracts
The run directory and the demo catalogue use five artifact contracts:
brushline.plan.v1: the owner-contractor plan.brushline.run.v1: the run manifest.brushline.pareto.v1: the multi-objective archive.brushline.timeline.v1: the operations timeline.brushline.demo.v1: the public demo manifest.
Each contract has a Pydantic model, a validator, and a named-error report. The report uses the shared
brushline.model.validation.ContractValidation shape.
Plan
A plan has a versioned header, one or more actions, and named assumptions.
PlanHeader: plan id, version, status, scenario, dataset, data version, model versions, configuration, currency, creation time, creator, parent plan, seed, service standards, and notes.PlanAction: action id, segment, year, season, method, intensity, treatment unit, quantities, cost lines, assumptions, and risk notes.CostLine: category, amount, description, optional quantity and rate, currency, and source.PlanAssumption: assumption id, statement, source, and impact.
The validator checks duplicate action and assumption ids, unknown segments when a known set is supplied, currency consistency, and a plan that names itself as its parent. An action without an explicit assumption is a warning.
Run
A run manifest names the run type, status, data version, model versions, configuration, seed, artifact index, and summary.
RunArtifact: name, relative path, schema version, media type, availability, SHA-256, and a reason when unavailable.RunManifest: run id, run type, status, creation time, data version, model versions, configuration, artifacts, creator, seed, and summary.
An available artifact needs a SHA-256. An unavailable artifact needs a reason. A complete run with no available artifact, or a failed run with an available artifact, is a warning.
Pareto archive
The archive keeps the non-dominated plans from a search portfolio.
Objective: name, direction (minimizeormaximize), and unit.Scalarization: id, weights, and description. The weights must be non-negative and sum to 1.ArchiveMember: plan id, plan path, objective vector, feasibility, seed, evidence path, budget, and metadata.ParetoArchive: instance, run, objectives, scalarizations, members, eviction policy, creation time, and creator.
The validator checks duplicate objective, scalarization, and member ids; unknown scalarization weights;
member objective keys; and non-dominance. A dominated member fails with PARETO-DOMINANCE. An empty
archive is valid but warned.
Operations timeline
The timeline is a sequence of timestamped events for the 2D map and 3D scene.
TimelineEvent: event id, resource id and type, segment, event type, start and end time, state, optional action, cost, currency, and notes.OperationsTimeline: run id, events, creation time, and creator.
Timestamps are timezone-aware. An end time before the start time fails. The validator checks duplicate event ids, non-decreasing start times, and segment references. An event without an end time is a warning; the animation shows an open event rather than inventing a position.
Demo manifest
The demo manifest describes one public example.
DemoSource: name, licence, version, and URL.DemoMetric: name, value, and unit.DemoArtifacts: run, plan, reports, optional Pareto archive, and optional timeline.DemoManifest: id, title, sector, region, AOI, question, sources, scenarios, artifacts, metrics, caveats, pilot link, status, creation time, and contact.
The id is a lowercase slug. A published demo needs a run, a plan, and reports. A draft or retired demo, a missing Pareto archive, and a missing timeline are warnings. Artifact and AOI paths are relative and must stay inside the demo directory.
Named errors
Prefix |
Meaning |
|---|---|
|
Duplicate ids, unknown segments, currency mismatches, and version problems. |
|
Duplicate artifact names and status/availability warnings. |
|
Duplicate ids, member keys, scalarization weights, dominance, and an empty archive. |
|
Duplicate events, ordering, segment references, and open events. |
|
Missing licences, missing published artifacts, and non-published status. |
Plan example
{
"header": {
"schema_version": "brushline.plan.v1",
"plan_id": "plan-1",
"version": 1,
"status": "proposed",
"scenario_id": "scenario-1",
"dataset_id": "dataset-1",
"data_version": "sha256:abc",
"model_versions": {"growth": "p1", "treatment": "p1"},
"currency": "CAD",
"created_utc": "2026-11-14T00:00:00Z",
"created_by": "brushline"
},
"actions": [
{
"action_id": "a1",
"segment_id": "s1",
"year": 2026,
"season": "summer",
"method": "mowing",
"intensity": 0.8,
"quantity_ha": 1.0,
"cost_lines": [
{"category": "labour", "quantity": 10.0, "rate": 100.0, "amount": 1000.0}
],
"assumptions": ["Rates from the 2026 contract."]
}
],
"assumptions": [
{"assumption_id": "as1", "statement": "One pass per segment.", "source": "owner"}
]
}
Python use
from pathlib import Path
from brushline.model.plan import Plan, validate_plan
plan = Plan.model_validate_json(Path("plan.json").read_text())
report = validate_plan(plan, known_segment_ids={"s1", "s2"})
if not report.is_valid:
raise SystemExit("\n".join(report.errors))