de8fb10f52
Phase 42 PRD (docs/CONTROL_PLANE_PRD.md:144): "truth/ dir at repo
root — rule files, versioned in git." Didn't exist. Landing both the
dir + its loader.
New files:
truth/
README.md — documents file format, rule shape,
composition model (file rules are
additive on top of in-code default_
truth_store), explicit non-goals
(no hot reload, no inheritance)
staffing.fill.toml — 2 staffing.fill rules:
endorsed-count-matches-target,
city-required (both Reject via
FieldEmpty)
staffing.any.toml — 1 staffing.any rule:
no-destructive-sql-in-context via
FieldContainsAny (parallel to the
queryd SQL gate we already ship)
crates/truth/src/loader.rs — load_from_dir(store, dir)
— 5 tests: happy path, duplicate-ID
rejection within files, duplicate-ID
rejection against in-code rules,
non-toml files skipped, missing-dir
error. Alphabetical file order for
reproducible error messages.
crates/truth/src/lib.rs — new pub fn all_rule_ids() helper on
TruthStore so the loader can detect
collisions without breaching the
private `rules` field.
crates/truth/Cargo.toml — adds `toml` workspace dep.
Composition model: file rules are ADDITIVE on top of what
default_truth_store() registers in code. Operators can tune
thresholds/needles/descriptions at the file layer without a code
deploy. Schema changes (new RuleCondition variants) still need a
code bump.
Integration hook (not in this commit, flagged for follow-up):
main.rs should call loader::load_from_dir(&mut store, "truth/")
after default_truth_store() so file-backed rules take effect on
gateway boot. Deliberately separate: this commit lands the
machinery; wiring it on happens when the team is ready to own
the rule file lifecycle.
Total: 37 truth tests green (was 32). Workspace warnings still 0.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2.4 KiB
Truth rules — file-backed policy
Phase 42 PRD: "truth/ dir at repo root — rule files, versioned in git."
This directory is the canonical home for TruthStore rules loaded from
disk. Each *.toml file holds a set of TruthRule records for one
task class. The truth crate's load_from_dir(path) walks this
directory, parses every .toml file, and registers the rules it finds.
Structure
truth/
├── README.md ← this file
├── staffing.fill.toml ← rules for task_class="staffing.fill"
└── staffing.any.toml ← rules for task_class="staffing.any"
File naming is informational — load_from_dir respects whatever
task_class the rule declares internally, NOT the filename. Using
task-class-matching filenames is a convention for humans reading the
git tree.
Rule shape
[[rule]]
id = "worker-active"
task_class = "staffing.fill"
description = "Worker must be active"
condition = { type = "FieldEquals", field = "worker.status", value = "active" }
action = { type = "Pass" }
condition.type is one of:
Always— always trueFieldEquals { field, value }FieldMismatch { field, value }FieldEmpty { field }FieldGreater { field, threshold }FieldContainsAny { field, needles }
action.type is one of:
Pass— rule informational; no enforcementReject { message }— short-circuit with errorRedact { fields }— mutate the context, strip fieldsBlock { message }— hard stop, alert
Composition
The crate's default_truth_store() continues to register rules
in code for backward-compat. Operators can layer file-backed
rules ON TOP via load_from_dir:
let store = truth::default_truth_store();
let store = truth::load_from_dir(&store, "/home/profit/lakehouse/truth")?;
File-loaded rules are additive — they do NOT replace in-code rules.
This lets the staffing team tune rules at the file level (edit a
threshold, add a new FieldContainsAny blocklist) without waiting
for a code deploy.
Explicit non-goals
- No hot reload — per Phase 42 PRD ("Truth reload is explicit
in this phase"). Operators bounce the gateway or POST
/v1/contextrefresh endpoint (future) to pick up changes. - No inheritance — each file stands alone; rule IDs must be unique across all files. Duplicate-ID detection is a load-time error.