ADR-0135: Roads-owned parameterization and dedicated view
Date: 2026-11-03
Status: accepted 2026-11-03; implemented; local workflow validated. Operator approval applies
to the replacement specification and dedicated layout at 9532a2968. This replaces
the former five-fallback editor proposal; its text remains historical evidence.
Decision provenance
Decision venue: operator/Codex task conversation, 2026-11-03, operator timezone America/Los_Angeles. Decision owner: Roger Lew. Implementer: Codex after review and human specification/layout gate. The operator explicitly requested driver overrides, a dedicated view, a Disturbed-like lifecycle, authoritative project state written with Roads, and contractual repository defaults. The operator subsequently stated "I approve. please proceed with implementation" after the reviewed replacement specification/layout were presented at9532a2968. The explicit human gate is satisfied; deployment remains separate.
Decision
Repository baseline authority consists of bundled Roads soil/management templates
and the documented selection/assembly rules, as specified in the
baseline contract.
Project authority is one additive _parameterization object in roads.nodb with
schema version, retained baseline contents and role-scoped overrides. The existing
_roads_params remains authoritative for existing physical/mapping settings.
The project/view contract defines exact
keys, precedence, lifecycle, transport and valid states.
Retain all current template texts and hashes inside the NoDb baseline, bound to resolver version1 and a deterministic manifest identity. This lets an old project reproduce its baseline after repository changes without a separate mutable CSV or multi-file configuration commit. Copies emitted for execution are derivatives. Read-only access never enrolls legacy projects. First explicit Save/Prepare binds the baseline; subsequent operations retain it. Reset removes overrides against that baseline; adoption of newer repository defaults is a separate future operation.
Expose default/multiply/absolute overrides for baseline conductivity, Ki, Kr and critical shear, separately for template-owned road/fill/buffer roles. Apply after ordinary template and traffic adjustments, before native serialization. Positive finite native-representable values are required; zero is a native estimation/bypass sentinel, not an off switch. Retain source values and distinguish input validity, study coverage and calibration claims. No universal response direction or arbitrary field-calibrated range is asserted.
The dedicated view shows source -> adjustments -> override -> emitted values, including mixed-template groups and role applicability, plus actual compatible run comparisons. Existing Roads lifecycle guards, NoDb locking, auth, CSRF, readonly, history and baseline-output isolation apply. Save invalidates Roads preparation/results and requires explicit Prepare/Run; it never implicitly reruns.
Exact delta and compatibility
Currently Roads stores ordinary settings and reads live repository templates during assembly. Users cannot independently override these native drivers. After approved implementation, bound projects use retained templates and saved driver overrides. Default-only generation must match current production output bytes across supported branches. No scientific default, native formula, binary, source soil, shared Disturbed table or baseline WEPP output changes in this proposal.
Add schema and request fields without removing existing keys. Existing unbound projects remain readable and historical results remain governed by current lifecycle admission. Additive provenance records distinguish legacy/unbound data from actual bound readback. An already-prepared unbound legacy project must explicitly Prepare before a new Run can bind to the new configuration; historical result viewing is preserved. This one-time Run preflight change is part of the approval scope. Geometry preparation and native soil/management assembly during Run are separate phases; the view must not claim native input readback after geometry preparation. The old proposed five-field API tightening and metadata-only object are withdrawn; ordinary API behavior remains unchanged outside the new payload.
Rationale and alternatives
The user needs controllable physical drivers, not just geometry fallbacks that may be unused or alter modeled area. Native Ki/Kr/shear and conductivity have traceable consumers. Separate role controls avoid a blanket change to unrelated landuse soils.
Reject editing generated .sol/.man as the authority: preparation would overwrite
intent. Reject a second editable CSV: it splits project configuration across mutable
stores. Disturbed provides a lifecycle analogy, not a requirement to duplicate its
CSV storage. Reject repository-only hashes: they detect drift but cannot recover
old content. Reject copying executable Python into state: bind a supported resolver
version instead. Reject automatic rebase/reset-to-latest: it changes saved projects.
Reject a generic optimizer or output multiplier: neither supplies the requested
transparent input parameterization. No new dependency, queue or service is needed.
Evidence and validation
The baseline inventory binds all18 template assets, role values and source/native identities. Source audit shows zero estimation sentinels, traffic Ki/Kr adjustment and management coupling. The existing 47-profile/four-project studies characterize geometry/traffic; they do not certify the new overrides. New bounded override and retained-baseline prototype results must be independently reviewed before the replacement approval request.
After approval, required evidence includes default byte parity, actual Roads NoDb persistence, all native writer paths, actual input readback, mixed-role no-op checks, invalid atomic saves, lifecycle invalidation, fork/archive/restore, and browser to native to fresh report propagation under production-equivalent identities/mounts. Independent scientific, correctness, security and UX reviews are required. Static prototype and isolated native runs do not substitute for implemented workflow proof.
Implementation evidence
The dedicated view and Roads-owned state are implemented. Actual local browser Save/Prepare/Run validates default and custom propagation across35 profiles and 105 role records, with independent native input, raw output and fresh-report readback. Canonical archive/reset/restore/full-fork checks preserve retained baselines, native artifacts and current-result eligibility; private authorization and readonly denial pass. Independent correctness, security and UX reviews pass. See the implementation results for exact evidence and final regression status. This evidence does not adopt new scientific defaults or authorize production deployment.
Risks and rollback
Extreme input values or coupled processes can fail native execution or produce unhelpful responses even when parser-valid; preserve failures and never publish incoherent results. Retained templates enlarge the NoDb payload modestly; prototype roundtrip/size evidence must be retained. Resolver versions require ongoing support for bound projects. Unknown versions or corrupt content fail explicitly rather than silently adopting defaults. Plain-text rendering and strict materialization allowlists prevent saved source content from becoming executable markup or arbitrary file paths.
Rollback of a future implementation must preserve saved state and historical artifacts, avoid interpreting new state as old defaults, and disable unsupported execution explicitly. No deployment or old-state migration is authorized here.