core: split secret resolution into a pure plan and an executor

[domenkozar]

Closes #124.

Splits secret resolution into a pure, I/O-free plan and a small executor that consumes it, so deciding what to do (profile merge, effective config, address derivation, provider routing, grouping) no longer interleaves with doing it (fetching, fallbacks, defaults, generation). Shipped as four reviewable slices plus one behavior fix.

Slices

1. Pure plan (secretspec/src/plan.rs, new): build_plan() turns the manifest + alias maps into an immutable ResolutionPlan with no I/O — fully unit-testable without any provider.
2. Executor: execute_plan() builds a provider per primary-store group, fetches groups concurrently, walks fallbacks, generates, and applies defaults. validate_audited shrinks from ~380 lines to a reason-gate + build_plan → coordinate-check → execute_plan + one audit event.
3. get/set on the plan: single-secret operations plan via the same plan_secret/route_for, so per-secret decisions (effective config, address, route) can't drift between single-secret ops and batch validation.
4. Single-store ref coordinate validation: a ref routed at exactly one store (an explicit --provider, a single-provider chain, or the default) is checked for coordinate compatibility before any fetch; a ref on a multi-store chain defers to per-store checking at read time.

Behavior refinements (see CHANGELOG)

• Fallback chains are tried strictly in order. The plan resolves only a chain's primary up front; each fallback link is resolved lazily, only when a read reaches it. So check/run/get stop at the first provider that answers and an undefined or unreachable link past it is never touched. This also fixes a pre-existing case where a live fallback sitting before an undefined alias wrongly failed the read.
• Single-store ref coordinate mismatches fail fast (e.g. a field ref pointed at a .env file), with a clear message, before contacting the store — and, for the value-free report, without contacting it at all.

Invariants preserved

Wire formats and JSON schemas are unchanged (the plan is crate-internal, not serialized); exactly one Check audit event still fires per read with keys populated even on a route error; build_plan performs no provider construction or network I/O (the coordinate check that builds providers lives in the executor side).

Testing

cargo test --all green (388 secretspec unit tests + derive/ffi/node/py/integration/doc suites, 0 failures); clippy + rustfmt clean. New unit coverage for planning, routing, tried-in-order fallback, and coordinate validation. Independently reviewed by a verification pass that traced the fallback and coordinate logic and confirmed behavior preservation.

🤖 Generated with Claude Code

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	secretspec	20197a0	Commit Preview URL Branch Preview URL	Jul 10 2026, 05:13 PM