Add RFC 0001 for field-level environment aliases#354
Conversation
Propose first-class field-level environment projections in ortho_config: a declarative `env(...)` field attribute binding a field to one or more environment-variable names, with deterministic intra-environment precedence (canonical name shadows aliases by default), empty-value handling, and secret-redaction metadata. Motivated by the vk (GITHUB_TOKEN fallback) and podbot (hand-written env-to-path table) use cases. The RFC keeps the orthodox precedence (defaults < files < environment < CLI) and the single-environment-layer merge model: aliases SELECT one value before the layer, never concatenate, so collection append strategies are unaffected. It specifies the macro grammar, internal resolver glue (not public API), the Secret<T> + secret-path-set redaction model, a backwards-compatible EnvMetadata IR extension (ir_version 1.1 -> 1.2), and vk/podbot migration. The "env var names as values" primitive (podbot env_allowlist) is deferred to RFC 0002. Grounded in prior art (pydantic AliasChoices, Viper BindEnv, clap env, config-rs ignore_empty, GitHub CLI GH_TOKEN/GITHUB_TOKEN ordering, 12-factor) and revised after a multi-perspective design review (recorded in section 13). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Plus Run ID: 📒 Files selected for processing (2)
👮 Files not reviewed due to content moderation or server errors (2)
RFC 0001: Field-level environment aliasesThis pull request introduces RFC 0001, the repository's first Request for Comments document, proposing first-class support for field-level environment-variable aliases in the ProposalThe RFC proposes a declarative The resolution model operates by selection rather than concatenation: only one value per field is chosen from the declared candidate variables in a fixed precedence order. The implementation extends the internal Motivation and Use CasesThe design addresses two concrete use cases documented in the proposal:
The proposal moves environment-variable binding logic from consumer code into the library's standard layering, documentation, and redaction machinery, ensuring that external names appear in generated help text, the documentation IR, agent-context output, and provenance records. Scope and CompatibilityThe change maintains backward compatibility and the orthodox precedence order (defaults < files < environment < CLI). Fields without the new attribute behave identically to the current implementation. The RFC is deliberately narrow: it does not add global "scan the whole environment" modes. Every external variable name must be declared explicitly, preventing unintended collisions and ambient secret leakage. The proposal defers the distinct primitive for "list of environment-variable names" (used by Documentation Changes
The RFC status is WalkthroughAdds a new RFC document ( ChangesRFC 0001: Field-level environment aliases
🚥 Pre-merge checks | ✅ 19 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (19 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![codescene-delta-analysis[bot]](https://avatars.githubusercontent.com/in/53921?s=60&v=4){kind=small}
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
1 participant
Summary
This branch adds the repository's first Request for Comments,
RFC 0001: Field-level environment aliases,
and indexes it from the documentation contents file. The RFC proposes that
ortho_configgrow first-class, field-level environment projections: adeclarative
env(...)field attribute binding a configuration field to one ormore environment-variable names, with deterministic intra-environment
precedence (the prefixed canonical name shadows aliases by default),
empty-value handling, and secret-redaction metadata. It is motivated by two
consumers —
vk(aGITHUB_TOKENfallback resolved today by bespoke code) andpodbot(a hand-written environment-to-config-path table) — and lets bothdelete that hand-rolled machinery without the crate ever scanning the whole
process environment.
This is a documentation-only change carrying a proposal for review. The RFC
status is
Proposed; no runtime, derive-macro, or IR code changes in thisbranch. There is no associated roadmap task, issue, or execplan: the document
itself is the deliverable, and it is the artefact under review.
Review walkthrough
docs/rfcs/0001-field-level-environment-aliases.md
— the proposal itself. Sections 1–4 establish the problem, the current
single-environment-layer behaviour, and the goals and non-goals.
§5 Proposed design:
the precedence model and the central invariant that aliases select a single
value before the one environment layer and never concatenate (§5.4), the
macro attribute grammar (§5.2), the internal resolver glue (§5.3), the
Secret<T>plus secret-path-set redaction model (§5.5), and thebackwards-compatible
EnvMetadataIR extension with the honestir_versionbump (§5.6).§7 Compatibility and migration
for the before/after
vkandpodbotmigrations and the SemVer impact, and§9 Alternatives considered
and §10 Prior art
for the rejected options and the precedents they draw on.
§13 Design-review findings folded in,
which records the material findings from a multi-perspective review and where
each was addressed.
docs/contents.md
for the new "Requests for comments (RFCs)" section linking the document.
Scope notes
(
podbot'senv_allowlist, the proposedenv_value_names/EnvPassthrough)is deliberately deferred to a planned companion, RFC 0002. The conceptual
separation is settled in §5.7; the concrete design is out of scope here
because it shares no mechanism with aliasing beyond the secret vocabulary.
prior-art research, then stress-tested through a multi-perspective design
review before being revised; the panel's verdict was "revise", and the
material findings are folded into the current draft (see §13).
Validation
make markdownlint: 61 files linted, 0 errors.make nixie: all Mermaid diagrams validated successfully (includingFigure 1 in the RFC).
References