Baseline Configurations¶

A Trails project is configured through trails.toml — what the app IS. Baselines declare what the app SHOULD BE: portable, versionable, inheritable TOML files that define semantic contracts for schema strictness, policy requirements, pipeline rules, agent budgets, and federation compatibility. They are constraints ON the config, not the config itself. The full design lives in ADR-0027; the progressive-enhancement framing is ADR-0021.

What baselines are¶

A baseline is a named profile that declares what a Trails project must look like to be compliant. Think of it as .eslintrc for knowledge graphs — a machine-readable contract that trails doctor and trails baseline validate enforce.

Baselines are opt-in at every level. A project without a baseline works exactly as today. No overhead, no mode switches.

Built-in presets¶

Trails ships four baselines:

Every baseline without an explicit extends inherits from trails:default implicitly.

Writing custom baselines (TOML format)¶

Baselines live in baselines/ in a project directory or ~/.trails/baselines/ for user-global presets. Each is a TOML file with a [baseline] header:

[baseline]
name = "healthcare-fhir"
version = "1.0"
extends = "trails:strict"

[baseline.store]
backend = "oxigraph"
reasoning = "rdfs"
max_query_time_ms = 30000

[baseline.schema]
upper_ontology = "schema.org"
core_types = ["Patient", "Encounter", "Observation"]
alignment = "fhir-r4"
shacl_strictness = "closed"

[baseline.pipeline]
default_extractors = ["pdf", "html", "docx"]
enrichment_steps = ["ner", "linking", "dedup"]
validation = "strict"

[baseline.policy]
template = "hipaa"
audit_level = "full"

[baseline.agents]
default_model = "haiku"
max_cost_per_run_usd = 1.0
planner = "react"
budget_enforcement = true

[baseline.federation]
require_policy_alignment = true
minimum_peer_trust_level = "verified"

Every section is optional. A baseline that only declares [baseline.policy] constrains only the policy dimension — everything else is unconstrained.

Baseline sections¶

Minimal baseline example¶

A baseline can be as simple as one constraint:

[baseline]
name = "cost-aware"
version = "1.0"

[baseline.agents]
max_cost_per_run_usd = 2.0
budget_enforcement = true

This baseline only enforces agent cost limits — everything else is unconstrained.

Inheritance with extends¶

The extends field references a parent baseline. The child inherits all parent constraints and overrides at the leaf level:

[baseline]
name = "my-strict-healthcare"
version = "1.0"
extends = "trails:strict"

[baseline.schema]
core_types = ["Patient", "Encounter"]  # adds to strict's constraints

Supported extends formats¶

Multiple inheritance¶

A baseline can extend multiple parents:

[baseline]
name = "healthcare-compliant"
version = "1.0"
extends = ["trails:strict", "file:../compliance.toml"]

Conflicts are resolved left-to-right (last wins). A warning is emitted for each override so you know which parent contributed which constraint.

Inheritance rules¶

• Child values override parent values at the leaf level.
• trails:default is the implicit root — every baseline inherits from it even without an explicit extends.
• Deep chains (A extends B extends C) are resolved recursively. Use trails baseline diff to see the fully resolved result.

CLI commands¶

trails baseline validate¶

Checks the current trails.toml against the active baseline. Reports violations in the same format as trails doctor:

trails baseline validate

Baseline: healthcare-fhir v1.0

[PASS] store.backend = "oxigraph" (matches baseline)
[PASS] store.reasoning = "rdfs" (matches baseline)
[FAIL] schema.core_types: missing "Observation" — declared in baseline but no @node_type registered
[PASS] policy.template = "hipaa" (loaded)
[WARN] agents.max_cost_per_run_usd = 5.0 (baseline requires <= 1.0)

2 issues found (1 FAIL, 1 WARN)

trails baseline export¶

Exports the current trails.toml as a baseline file — useful for extracting a reusable baseline from a working project:

trails baseline export > baselines/extracted.toml

trails baseline diff¶

Compares two baselines section by section:

trails baseline diff baselines/v1.toml baselines/v2.toml

[baseline.schema]
  shacl_strictness: "open" → "closed"
  + core_types: ["Patient"]  (added in v2)

[baseline.agents]
  max_cost_per_run_usd: 5.0 → 1.0

[baseline.policy]
  (no changes)

Also useful for seeing the fully resolved baseline after inheritance:

trails baseline diff trails:default baselines/my-strict.toml

trails baseline list¶

Lists available baselines (built-in + project + user-global):

trails baseline list

Built-in:
  trails:default     Minimal, no constraints, open-world
  trails:strict      SHACL closed, full provenance, Cedar required
  trails:research    RDF-star, RDFS reasoning, relaxed limits
  trails:compliance  Full audit, consent, PROV-O, budget enforcement

Project (baselines/):
  healthcare-fhir    v1.0 (extends trails:strict)

User (~/.trails/baselines/):
  cost-aware         v1.0 (extends trails:default)

trails baseline show¶

Shows the fully resolved baseline after inheritance:

trails baseline show healthcare-fhir

# Resolved baseline: healthcare-fhir v1.0
# Extends: trails:strict → trails:default

[baseline]
name = "healthcare-fhir"
version = "1.0"

[baseline.store]
backend = "oxigraph"
reasoning = "rdfs"
max_query_time_ms = 30000

[baseline.schema]
upper_ontology = "schema.org"
core_types = ["Patient", "Encounter", "Observation"]
# ...

Doctor integration¶

trails doctor gains baseline-awareness automatically when an active baseline exists at baselines/active.toml:

trails doctor

=== Baseline checks (healthcare-fhir v1.0) ===

[PASS] baseline: store.backend matches (oxigraph)
[PASS] baseline: store.reasoning matches (rdfs)
[FAIL] baseline: schema.core_types — "Observation" not registered
[PASS] baseline: policy.template loaded (hipaa)
[PASS] baseline: agents.budget_enforcement active
[WARN] baseline: pipeline.enrichment_steps — "dedup" not registered

=== Other checks ===
...

Each baseline check maps to a HealthCheck(name="baseline: <section>"). Violations produce status="warn" (soft baseline) or status="fail" (strict baseline with validation = "strict" in [baseline.pipeline]).

What doctor checks¶

trails new --baseline¶

Scaffold a new project with a baseline applied:

trails new myapp --baseline healthcare-fhir

This generates:

• trails.toml pre-configured to satisfy the baseline constraints
• baselines/active.toml recording the active baseline
• Starter @node_type stubs for declared core_types
• Cedar policy template if [baseline.policy] declares one

# Use a built-in preset
trails new myapp --baseline trails:strict

# Use a file-based baseline
trails new myapp --baseline file:../shared/healthcare.toml

Progressive enhancement¶

Baselines follow ADR-0021's additive model. Each level is a strict superset of the previous:

A project at Level 0 is completely unaffected by baseline features existing in the codebase. No overhead, no implicit behavior.

Complete example: healthcare project¶

1. Write the baseline¶

# baselines/healthcare-fhir.toml

[baseline]
name = "healthcare-fhir"
version = "1.0"
extends = "trails:compliance"

[baseline.store]
backend = "oxigraph"
reasoning = "rdfs"

[baseline.schema]
core_types = ["Patient", "Encounter", "Observation"]
shacl_strictness = "closed"

[baseline.policy]
template = "hipaa"
audit_level = "full"

[baseline.agents]
default_model = "haiku"
max_cost_per_run_usd = 1.0

2. Scaffold the project¶

trails new clinical-trial --baseline file:baselines/healthcare-fhir.toml

3. Develop the app¶

Write @node_type declarations for Patient, Encounter, Observation. Add capabilities. Write Cedar policies.

4. Validate against the baseline¶

trails baseline validate
# All checks pass — the app satisfies the healthcare-fhir contract

trails doctor
# Baseline checks integrated into the standard health report

5. Share the baseline¶

Other teams starting FHIR projects can reuse the same baseline:

trails new another-fhir-app --baseline file:../shared/healthcare-fhir.toml

No copy-paste drift. One baseline, many projects.

Reference¶

See also¶

• ADR-0027 — full baseline design
• Enrichment Pipeline — enrichment steps declared in [baseline.pipeline]
• Schema Transformation — schema migration that baselines can constrain
• Policy & Authorization — Cedar policies referenced by [baseline.policy]
• Federation — baseline exchange during federation negotiation