LabDataStorageEvaluation/docs/rules/code-config-yaml.md

Code / Config - all tunables live in YAML, no magic numbers, no .env

Purpose + scope. Governs where every configurable value lives. Binding for all Python code in this repository. Any new configurable parameter MUST follow this rule when deciding where it goes.

The goal: one authoritative source per parameter, so regenerating any artifact with the same config is byte-identical, and changing a parameter never requires hunting constants across scripts.

---

1. The two YAML configs

File	Owns	Written by
./out/config/lab_config.yaml	The laboratory model: volumes (batches / wafers / coupons / tracks / cycles), the deposition matrix, physical-model coefficients, nominal test conditions, the random seed 20260711	Task 01, from the spec; regenerated only deliberately
./out/config/hw_prices.yaml	Hardware cost parameters for extrapolation (RAM $/GB, NVMe $/TB, server base prices)	Task 10 seeds editable defaults; the operator may edit

Rules:

• Scripts READ these files; they never duplicate values from them. Task 03 reads volumes, coefficients, and the seed from lab_config.yaml - it does not hardcode 588 coupons or seed 20260711. Task 10 reads prices from hw_prices.yaml - it does not inline dollar figures.
• A parameter needed by more than one task lives in the YAML, never copy-pasted between scripts.
• New tunables go into the appropriate YAML with a self-describing key; if neither file fits, propose a new config file in a docs/rules update first.

2. Spec-fixed constants - named, sourced, at the top

Values fixed by the specs that are NOT operator-tunable (the 120-200 MB size gate, the 30-minute cell timeout, the 50k-row transaction batch, the 50 ms RSS sampling interval) are module-level named constants at the top of the owning script, each with a one-line comment naming the spec:

SIZE_GATE_MB = (120, 200)      # abort bounds, spec 03
CELL_TIMEOUT_S = 30 * 60       # hard per-run timeout, spec 09

A bare number inline in the logic (if size > 209715200) is forbidden.

3. The PostgreSQL DSN - one env var, never hardcoded, never logged

The only external resource is the local PostgreSQL 16 instance. Its DSN:

• Comes from the environment variable TRIBO_PG_DSN; default when unset: postgresql://postgres@localhost:5432/tribo.
• Is read in ONE shared helper (e.g. common/pg.py: get_dsn()); scripts call the helper, never os.environ directly.
• Is never hardcoded in a script, never committed in a config file, and never logged (a DSN may embed a password - see obs-python-logging.md).

There are no other secrets in this project. There is no .env file; do not introduce one.

4. CLI flags - per-run choices only

Command-line flags are for choices that vary per invocation, not for model parameters: --log-level, --dry-run, an output-root override, a --limit for smoke runs. A physical coefficient or a volume as a CLI flag is forbidden - it would silently fork the config out of lab_config.yaml.

5. Anti-patterns

• Hardcoding a value that exists in lab_config.yaml (seed, volumes, coefficients) - the YAML is the single source; drift here breaks reproducibility silently.
• Adding a .env file or reading os.environ scattered through scripts - the DSN goes through the one shared helper; nothing else lives in the environment.
• Inline magic numbers for spec-fixed gates and timeouts - name them at the top with the spec reference.
• Dollar prices inlined in extrapolate.py - they live in hw_prices.yaml so the operator can re-cost without touching code.
• A model parameter as a CLI flag - per-run flags are for run mechanics, not for the lab model.
• Committing ./out/config/ generated files to git as if they were sources - the YAML under ./out/ is a generated artifact; its source of truth is spec 01 (see build-pipeline-tasks.md).

6. Related documents

• data-determinism.md - the seed contract.
• build-pipeline-tasks.md - the ./out/ tree and what is git-ignored.
• obs-python-logging.md - --log-level flag; DSN never logged.