railiance-platform/docs/catalog-lane-scaffold.md

Offline exact KV-v2 workload-read lane scaffold

Owner: railiance-platform, RPF-WP-0050-T04. Warden pointer seam: ops-warden/wiki/CatalogLaneScaffoldContract.md, WARDEN-WP-0041.

Run python3 scripts/credential-change.py scaffold-lane --input <platform-request.yaml> --catalog-manifest <warden-request.yaml> --output-dir <new-external-staging-dir>. The catalog manifest is optional for ordinary local preparation and required for cross-owner fixture acceptance. Both inputs are metadata only; this command has no execute, credential, network, approval or apply option. jsonschema and PyYAML are required, as used by the local validation environment.

schemas/catalog-lane-scaffold.schema.json is the closed platform request v1. Explicit owner/consumer/lane, prospective Kubernetes SA/namespace/role/audience, exact KV mount/path/field names, namespace-restricted ESO destination, risk for the entire readable path and required review roles must be supplied. Missing claims and risk are not inferred. The first shape supports one prospective ESO reader, audience openbao and a maximum fifteen-minute token TTL. Tenant/dynamic secret, OIDC/ceremony, wildcard, metadata listing, self-lifecycle and executable fetching need separate reviewed extensions. No credential values or protected URLs belong in this input. Unknown fields, malformed/duplicate YAML keys, control characters, secret markers, invalid calendar dates and mismatched mappings are refused with safe errors. Warden's unknown workload identity remains unknown and does not confirm the prospective platform auth binding.

The generator reuses credential-change.py's generated_policy_hcl and auth_payload, preserving one exact data-read path and explicit policies/claims. It emits six draft review artifacts: a CCR under credential-change-requests/, its policy under openbao/policies/, auth payload under openbao/auth/, ESO review manifest under manifests/, a non-executed evidence checklist under docs/evidence/, and README. The policy path in the CCR is the eventual owner repository destination, relative to the staged bundle. Auth payloads are wrapped in draft metadata; no command executes them. No Secret object or value is emitted.

CCR status is proposed, review comments empty, bound claims unconfirmed and frontdoor pending-review/unresolvable. Store/ExternalSecret annotations also say pending-review. The ExternalSecret target has explicit annotation metadata to contain source last-applied annotation copying. Evidence is not-executed and verified=false; it lists metadata/capability/negative/cleanup receipts the owner must produce later using its reviewed output-suppressing tools. It is a scaffold, not a successful verification receipt. Nothing is apply-ready authority.

Generation requires a new output directory outside the platform or other owner repository, refuses existing paths including symlinks, and never overwrites any file. Caller-selected staging beneath the system temporary root is supported. Inputs remain immutable and artifacts are deterministic; explicit dates and request/catalog SHA256 bind provenance without clock/network reads.

Cross-owner fixture

examples/catalog-lane-scaffold/platform-request.yaml and warden-request.yaml use synthetic lane example-workload-kv, consumer example-consumer, prospective reader example-consumer-eso and CCR-2099-9001. No published workload identity, existing client or credential is claimed. Warden manifest references the platform request and eventual CCR destination, includes explicit reviewed date and whole path risk. Platform checks shared schema/lane/title/consumer/owner/risk and exact CCR destination; Warden validates its own complete pointer schema.

Run both owner scaffold commands into separate new temporary directories and compare the Warden draft catalog with the proposed CCR. Same lane and pointers, risk/owner/consumer parity, retained unknown identity, unconfirmed platform claims, unresolvable frontdoor and absence of executable fetch/approval state are required. The synthetic fixture does not admit an actual lane. Source parity remains distinct from any founder custody choice, attended dated window or production promotion.