Propose customizable configuration layering policy for OrthoConfig

[lodyai]

Summary

This branch adds RFC 0002, which proposes a generic file-layer resolution
policy API for the ortho-config crate. The proposed API sits between
candidate-path generation and the MergeComposer, giving downstream
applications a native way to express ordered, fail-closed explicit selection
and multi-scope stacking without baking any application-specific names into
the library. The leynos/netsuke build tool, whose src/cli/discovery.rs
hand-rolls this policy today, serves as the proof case throughout.

This pull request carries a proposed, not yet accepted, design. The RFC is the
artefact under review; no library code changes on this branch.

• Status: Proposed.
• No roadmap task, issue, or execplan is tracked by this branch.

Review walkthrough

• Start with the RFC document
  for the problem statement, the current OrthoConfig and Netsuke behaviour, and
  the proposed runtime surface: ConfigPathSelector, ExplicitMode,
  AutomaticMode with DiscoveryScope, ConfigFilePolicy, and
  FileLayerOutcome.
• Focus next on the
  file-layer error policy
  for the suppression-gate semantics and the absent-versus-invalid error
  classification, then the
  alternatives considered
  for the rejected trait-seam shape and the Figment-reuse decision.
• Finish with the
  contents index entry
  for the new "Requests for comments (RFCs)" group.

Design process

The design was developed with an agent design team, stress-tested by the
Logisphere design-review panel across six lenses, and revised in response. The
notable revisions include snapshotting the environment at resolve time, a
scalar-only memoised merged_file_value, a fold-preserving (not lossless)
From lift, an origins() provenance trace, #[non_exhaustive] structs with
a stability-surface note, and a deferred derive policy_hook. The RFC is
numbered 0002 because RFC 0001 is reserved on another branch.

Validation

• make markdownlint: 61 files, 0 errors.
• make nixie: all Mermaid diagrams validated.

References

• Lody session: https://lody.ai/leynos/sessions/daa573d8-d9fe-4e48-a053-f567b9e3e571

[sourcery-ai]

Sorry @LodyAI[bot], you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[coderabbitai]

Note

Reviews paused

It 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 reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 5cade8f6-b902-4972-8421-96561f64ce9a

📥 Commits

Reviewing files that changed from the base of the PR and between 6bb29c1 and d88168f.

📒 Files selected for processing (2)

• docs/contents.md
• docs/rfcs/0002-config-layer-resolution-policy.md

👮 Files not reviewed due to content moderation or server errors (2)

• docs/contents.md
• docs/rfcs/0002-config-layer-resolution-policy.md

---

RFC 0002: Customizable configuration layering policy

This PR introduces RFC 0002, proposing a new, additive runtime API for the ortho_config::discovery module to enable customisable configuration file-layer resolution policies. The RFC addresses the limitation that OrthoConfig's current primitives cannot directly express ordered explicit selection, fail-closed exclusive selection, multi-scope automatic stacking, and early access to resolved layers—all required by downstream applications like Netsuke.

Proposed API

The proposal introduces six new types: ConfigPathSelector for ordered exclusive selection chains; ExplicitMode and AutomaticMode enums for selection strategies; DiscoveryScope for scope identification; ConfigFilePolicy as a resolver interface; and FileLayerOutcome as a replayable result type that snapshots the environment once and supports both early "peek" of merged scalar values and later "replay" into an existing MergeComposer without re-reading disk.

The design implements a refined error classification model: fatal selected_error for exclusive explicit-selection failures, reportable_errors for present-but-invalid automatic files (surfaced even when later layers succeed), and ignorable_errors for absent probes (surfaced only when discovery is exhausted).

Design refinements

The RFC reflects significant design-review feedback from the Logisphere panel, with key decisions including environment snapshots captured at resolve time; a scalar-only memoised merged_file_value with explicit None semantics; a fold-preserving (non-lossless) From lift; scope-tagged errors; an origins() provenance trace; and #[non_exhaustive] annotations on all new struct and enum types with stability-surface notes. A trait-seam alternative approach was considered but rejected in favour of the declarative form to enable integration with OrthoConfig's derive macro and agent-context tooling.

Proof case

Netsuke is mapped throughout as the proof case, with its src/cli/discovery.rs bespoke helper logic directly corresponding to the proposed API semantics. The RFC includes a compatibility table showing mechanical migration paths for Netsuke's existing helpers.

Delivery plan

The work is decomposed into five atomic, dependency-ordered steps: (1) add runtime types with fold-preserving lift and drains; (2) add scoped resolution with suppression and environment snapshotting; (3) add the explicit selector chain; (4) add optional derive attributes (env_vars, explicit_mode, automatic_mode, scope_order, project_root_from), deferred until the runtime API settles; and (5) add comprehensive test coverage including fail-closed selection, auto-discovery scope stacking, and SemVer additivity validation.

Changes

• docs/contents.md: Added entry for RFC 0002 in the Requests for comments section (+7/-0)
• docs/rfcs/0002-config-layer-resolution-policy.md: Full RFC document with preamble, problem statement, current state, proposed design, requirements, compatibility guidance, alternatives analysis, and integrated delivery plan (+910/-0)

The change is purely additive documentation; no library code changes are included. All new items reside in ortho_config::discovery with no modifications to existing public signatures or behaviour, making this a pre-1.0 minor-version release under semantic versioning.

Walkthrough

Adds RFC 0002 (docs/rfcs/0002-config-layer-resolution-policy.md, 910 lines) proposing a new additive runtime API in ortho_config::discovery for customisable configuration file-layer resolution, and registers the RFC under a new "Requests for comments" section in docs/contents.md.

Changes

RFC 0002: Customisable Config Layering Policy

Layer / File(s)	Summary
Contents entry, RFC preamble, and problem framing docs/contents.md, docs/rfcs/0002-config-layer-resolution-policy.md	Registers the RFC in the table of contents and opens the document with preamble, current-state limitations, the Netsuke motivating proof case, and goals/non-goals.
Core policy model: selectors, modes, and scopes docs/rfcs/0002-config-layer-resolution-policy.md	Specifies ConfigPathSelector and ExplicitMode (exclusive/optional semantics), AutomaticMode, and DiscoveryScope, including deterministic invariants for extends resolution and cross-scope canonical-path de-duplication.
Resolver, FileLayerOutcome, and error classification docs/rfcs/0002-config-layer-resolution-policy.md	Defines ConfigFilePolicy, FileLayerOutcome, and ResolvedSelection with environment snapshotting, peek/replay APIs, origin tracing, three-bucket error model (selected_error, reportable_errors, ignorable_errors), drain precedence, and a worked behaviour mapping with resolution flow diagram.
Derive-macro extension, requirements, alternatives, and delivery plan docs/rfcs/0002-config-layer-resolution-policy.md	Specifies the staged derive-macro extension (declarative policy keys, enum-string forms, project_root_from), SemVer compatibility stance, alternatives considered with Option C recommendation, and atomic additive delivery steps with acceptance criteria.

🗂️ A policy takes shape in layered prose,
Selectors explicit, each scope neatly posed.
Peek first, then replay — no re-reading disk,
Three buckets of errors to manage the risk.
The RFC is filed, the plan set in stone,
Netsuke shall shed its hand-rolled chaperone! 🦀

🚥 Pre-merge checks | ✅ 20

✅ Passed checks (20 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly and clearly describes the main change: proposing a customizable configuration layering policy for OrthoConfig, which aligns precisely with the RFC 0002 addition.
Description check	✅ Passed	The description comprehensively covers the RFC proposal, the API design, the Netsuke proof case, and the design-review process—all directly related to the changeset.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Testing (Overall)	✅ Passed	PR adds only documentation (RFC 0002 design document, 910 lines; contents.md index update, 7 lines). No Rust code or functionality implemented. Testing check does not apply without new functionality.
User-Facing Documentation	✅ Passed	RFC 0002 is a proposed design document with no code implementation and no actual user-facing functionality changes. The PR adds only documentation (RFC text and contents index). No migration or use...
Developer Documentation	✅ Passed	This PR introduces a proposed RFC (Status: Proposed) with comprehensive design documentation in docs/rfcs/0002-config-layer-resolution-policy.md, properly indexed in docs/contents.md. No actual int...
Module-Level Documentation	✅ Passed	No code modules are added in this PR—only RFC and documentation files. The check applies to code modules, not design documents, so it does not apply here.
Testing (Unit And Behavioural)	✅ Passed	PR contains only RFC documentation (+917 lines across 2 files) with zero code changes; no tests are required for design proposal documents lacking implementation.
Testing (Property / Proof)	✅ Passed	The PR is a design-only RFC with no implementation code. The RFC documents two scope-stacking invariants and proposes unit-test coverage in its delivery plan; property-based testing is not applicab...
Testing (Compile-Time / Ui)	✅ Passed	This PR adds only documentation (RFC 0002 and index entry), with no library code implementation. The PR explicitly states "no library code changes on this branch." Compile-time and snapshot tests a...
Unit Architecture	✅ Passed	RFC 0002 proposes an architecture exemplifying Unit Architecture principles: explicit error classification and surfacing, environment snapshots, query/command separation, dependency injection of al...
Domain Architecture	✅ Passed	This PR contains only documentation (RFC proposal and index entry); no code changes. The proposed design demonstrates proper domain architecture: OrthoConfig owns generic mechanics, applications ow...
Observability	✅ Passed	This PR contains only documentation (RFC proposal and index update) with no code implementation or operational behaviour changes. Observability requirements apply only to code that introduces or al...
Security And Privacy	✅ Passed	RFC documentation introduces no secrets, credentials, unsafe deserialization, trust boundary violations, or privacy leaks. Environment variables are properly handled with empty-value filtering; pat...
Performance And Resource Use	✅ Passed	PR contains only RFC documentation and contents update; no executable code, algorithms, memory management, or I/O implementations to review.
Concurrency And State	✅ Passed	This PR adds only documentation (RFC proposal and index entry); no implementation code, concurrency primitives, shared state, async code, or synchronisation mechanisms have been introduced.
Architectural Complexity And Maintainability	✅ Passed	RFC 0002 proposes a bounded, well-justified API for file-layer resolution. The design isolates a real seam (file selection & stacking), removes demonstrable duplication (Netsuke's bespoke ~200-300...
Rust Compiler Lint Integrity	✅ Passed	PR modifies only Markdown documentation files (docs/contents.md, docs/rfcs/0002-config-layer-resolution-policy.md); no Rust source code changes. Rust compiler lint integrity check does not apply.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch rfc-0002-config-layer-resolution-policy

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}