Intervention YAML Reference

Field-level specification for Intervention YAML definitions (interventions/int_*.yaml).

Interventions are the how of the Sense 19 chain. A deterministic, machine-executable edit. Paired (optionally) with a Suggestion which carries the what.

File Convention

• Location: afs/interventions/int_*.yaml
• intervention_id must match the filename stem (e.g. int_foo.yaml requires intervention_id: int_foo)
• Validator: python3 scripts/interventioncheck.py
• Contract: contracts/intervention_contract.v1.json (JSON Schema)
• Storage tier: B-tier — lives on whatever branch you authored it on. Each scenario branch carries its own intervention set

Top-Level Fields

Field	Type	Required	Description
intervention_id	string	Yes	Must match filename stem. Pattern: ^int_[a-z0-9_]+$
version	string	Yes	Semver-shaped
suggestion_id	string	No	The sug_* this Intervention realises. Soft FK — recorded for audit, not enforced
type	string	Yes	One of the Intervention Types below
target_file	string	Yes	AFS-relative path to the file the intervention edits or creates
changes	list	Yes	At least one entry. Shape varies by type — see below
deterministic	boolean	Yes	True if applying produces the same output on identical input. Phase 2 only applies deterministic: true
reversible	boolean	Yes	True if an undo intervention could be derived from from/to. Informational today; useful when Phase 5 lands
description	i18n mapping	No	At least en recommended for the Compare UI tooltip
author	mapping	No	See Author
modified_at	string	No	ISO 8601 timestamp

Security: target_file constraints

The validator and the apply mechanism both refuse:

• Absolute paths (leading /) — could write anywhere on disk
• .. segments — could escape the AFS root via symlink or traversal

A target_file like /etc/passwd or ../../../something fails validation at author time AND refuses to apply at runtime. Defense in depth: the verb that mutates files cannot reach outside the AFS.

Intervention Types

Value	Implemented in Phase 2?	Description
yaml_edit	Yes	Change values in a YAML artifact
artifact_add	Reserved	Add a new signal/thesis/verdict/smebit/notebook
artifact_remove	Reserved	Remove an instrument
config_change	Reserved	Modify tenant config
seed_edit	Reserved	Modify a seed CSV (e.g., update a reference table)

Phase 2 only applies yaml_edit. The other types are valid in the schema but the apply step refuses them — they’re forward-declared for future phases.

yaml_edit — Changes Shape

For type: yaml_edit, each entry in changes is:

Field	Type	Required	Description
path	string	Yes	Dotted YAML path. Supports list-index: severity_rules[0].severity
from	any	No	Expected current value. The apply refuses if the actual value differs (drift check). Omit to skip the check
to	any	No	New value to set. null means delete the key. Omit to make this a pure drift-check (no mutation)

Either from, to, or both must be present.

Path Syntax

Path	Walks to
thresholds.amount_chf	doc['thresholds']['amount_chf']
severity_rules[0].severity	doc['severity_rules'][0]['severity']
a.b[2].c[0].d	doc['a']['b'][2]['c'][0]['d']

The apply refuses to create missing keys — path: completely_new_field errors out because the intervention can’t invent a top-level field. That’s an artifact_add-shape change, not a yaml_edit.

Drift Check Semantics

• Both from and to set, file value matches from: apply to, increment change counter.
• Both from and to set, file value differs from from: refuse with InterventionDriftError. The intervention was authored against a different baseline.
• Only to set: blind-apply — write to without checking.
• Only from set: pure verification — fail if from doesn’t match. No write. Useful as a precondition check at the start of a changes list.
• Already-applied (from == to == current): noop. The file isn’t rewritten (mtime preserved).

Author

Field	Type	Required	Description
name	string	No	Person or team name
role	string	No	Their role (analyst, pack-author, …)
date	string	No	ISO date the intervention was authored

Example

intervention_id: int_lower_revenue_threshold
version: '1'
suggestion_id: sug_tighten_revenue_leakage
type: yaml_edit
target_file: signals/signal_revenue_leakage.yaml
changes:
  - path: thresholds.amount_chf
    from: 10
    to: 5
deterministic: true
reversible: true
description:
  en: Lower the threshold to 5 CHF to catch smaller leakage cases.
author:
  name: mig
  role: analyst
  date: 2026-05-22
modified_at: 2026-05-22T08:00:00Z

After Authoring

python3 scripts/interventioncheck.py    # validate against contract

# Create a scenario branch with this intervention applied:
jin scenario create tighter_revenue int_lower_revenue_threshold

# Build the scenario KLS:
jin scenario build tighter_revenue

See also

• Simulation guide — the full chain end-to-end.
• Suggestion YAML reference — the paired what shape.
• The Simulation — architecture — the apply mechanism’s safety properties, the A-tier / B-tier storage split, the commit-message-as-source-of-truth choice for scenario metadata.