de8fb10f52
Some checks failed
lakehouse/auditor 4 blocking issues: todo!() macro call in tests/real-world/scrum_master_pipeline.ts
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>
72 lines
2.4 KiB
Markdown
72 lines
2.4 KiB
Markdown
# 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
|
|
|
|
```toml
|
|
[[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 true
|
|
- `FieldEquals { field, value }`
|
|
- `FieldMismatch { field, value }`
|
|
- `FieldEmpty { field }`
|
|
- `FieldGreater { field, threshold }`
|
|
- `FieldContainsAny { field, needles }`
|
|
|
|
`action.type` is one of:
|
|
- `Pass` — rule informational; no enforcement
|
|
- `Reject { message }` — short-circuit with error
|
|
- `Redact { fields }` — mutate the context, strip fields
|
|
- `Block { 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`:
|
|
|
|
```rust
|
|
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/context`
|
|
refresh 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.
|