Developer Guide

Developer Guide

Core modules

File	Purpose
types.py	Dataclasses for policies, predicates, devices, backend metrics, and metadata
policy_parser.py	JSON policy/device loader
registry.py	Default backend capability registry and metrics loader
cost.py	Normalized cost calculation
selector.py	CAPS-ZK selector and fail-closed filtering
verifier.py	Verifier-side metadata guard
synthetic_benchmarks.py	Clearly labeled synthetic trace generator from summary statistics

Adding a new backend

1. Add a capability entry in default_backend_registry().
2. Add benchmark summary data to results/summary/.
3. Extend load_backend_metrics() if the table format differs.
4. Add policy tests to tests/.
5. Re-run python experiments/run_all.py and pytest -q.

Adding a new policy class

1. Create a new JSON file under configs/policies/.
2. Set the semantics field clearly.
3. Specify revealed attributes, hidden attributes, predicates, unlinkability, status, and resource budgets.
4. Run python experiments/selector_demo.py.
5. Check that rejected backend reasons match expected safety behavior.