ops-warden/wiki/CatalogLaneScaffoldContract.md

Catalog lane scaffold contract — P4 owner proposal

Date: 2026-10-03 · Owner: ops-warden · Work: WARDEN-WP-0041 Origin: CUST-WP-0075; proposal 79549660-4fc8-44d5-989e-074f6c7b6f07. Status: proposed seam for railiance-platform review. This document authorizes no apply.

Existing surfaces

src/warden/plan.py::_ccr_stub offers a prose checklist for an unroutable need. It does not create files or a CCR-schema-valid request. RouteEntry and routing/catalog.py already define and validate the pointer catalog; wiki/playbooks/catalog-lane-promotion.md defines promotion evidence. The platform's scripts/credential-change.py already validates CCR v1, renders policy/role metadata and operator runbooks, and records lifecycle evidence. The missing piece is reviewed draft generation across these owner surfaces, not another policy applier or approval implementation.

Ownership and proposed input

The first supported shape is one exact KV-v2 workload read lane. Login, ceremony, dynamic-secret and tenant paths need their own reviewed extensions; no generic fallback may manufacture an identity or auth binding.

A proposed non-secret input document has schema_version: 1, lane_id, title, need_keywords, consumer_repo, owner_repo, workload_ref, risk, wiki_ref, canon_ref, and platform_request_ref. workload_ref uses the existing catalog structure without inference from a repository, lane name or secret path. Missing owner identity remains explicit unknown_reason. risk must be supplied and covers the entire readable path. platform_request_ref points to the platform-owned draft request rather than duplicating its path, field set, policies, auth-role claims or ESO bindings. The two references must point to their reviewed eventual owner destinations.

ops-warden owns validation of those catalog fields and a draft catalog fragment plus playbook checklist. It owns no CCR renderer. railiance-platform owns the CCR schema/input extension, CCR draft, policy/role rendering, ESO manifest and evidence scaffold under RPF-WP-0050-T04. Its implementation must decide and publish the precise platform request schema and invocation; this proposal contains no invented command to invoke it.

Output and verification contract

Generation writes into a caller-selected staging directory and fails on any existing output by default. It does not insert into a live catalog, modify an owner repo, call OpenBao, query credentials, approve a request or contact a cluster. File names and references are deterministic and contain no values.

The catalog fragment always has status: draft, warden_executes: false, exec_capable: false, and no executable fetch command. Delegation and rotation remain explicit owner-reviewed questions, never an inferred permanent proxy. The playbook is a checklist with owner pointers, not a copied platform procedure.

Platform output remains status: proposed, frontdoor pending-review and unresolvable, with no approval, bound-claims confirmation or verification receipt invented. A draft is not an admission or a capability. ExternalSecret metadata must retain the current annotation-containment requirements. Evidence scaffolds use metadata/capability checks and contain no secret reads or raw subprocess error dumps. The platform owner chooses those implementations.

Offline acceptance covers schema/unknown-field errors, collision refusal, round-trip catalog validation, missing identity, explicit risk, secret-material rejection, immutable input, no network/subprocess execution, and all outputs remaining draft. A representative platform fixture must prove cross-owner references and field mapping before end-to-end generation is claimed.

Activation remains separate

Review and merge of generated metadata does not replace CCR approval, confirmed identity/auth bindings, attended value provisioning, deployment approval or positive/negative evidence. Existing catalog promotion criteria still apply. Novel authority, trust-root or value-delivery design needs its own work record; routine lanes fitting an accepted template may become PRs. The proposal's “only the value step needs the window” is a goal, not a claim that current approvals disappeared.

Evidence receipt

Source review: catalog models/validator, _ccr_stub, promotion checklist, platform credential-change validator and CCR-2026-0031 (metadata only). Knowledge: emergent-security 0.2.6, start and local-work, verified-files, orientation-only; package digest 8d1d6a9d4d07fec7b619618de7dfe2be2254c1790f85f4198c7fe19db9751c02.

Offline catalog command — 2026-10-04

warden route scaffold --input <warden-request.yaml> --output-dir <new-staging-dir> validates the closed v1 request against catalog entry rules and refuses an existing catalog lane ID or staging destination. The request fields above also require explicit reviewed: YYYY-MM-DD text for deterministic review metadata. Explicit ungraded risk is retained with the catalog's existing fail-safe meaning; no default risk or workload identity is inferred. Outputs are catalog.yaml, playbook.md and the unchanged semantic request in request.yaml. The output catalog is draft with execution disabled and no fetch command. This command does not invoke a platform renderer or replace the owner's admission lifecycle.

Cross-owner offline verification — 2026-10-04

Platform owns scripts/credential-change.py scaffold-lane --input <platform-request.yaml> --catalog-manifest <warden-request.yaml> --output-dir <new-staging-directory>. Its accepted synthetic paired manifests are at railiance-platform/examples/catalog-lane-scaffold/. The platform schema and renderer remain authoritative there. Warden emits three staging artifacts; platform emits six proposed review artifacts, including its CCR, policy/auth drafts, ESO metadata and unexecuted evidence checklist.

The exact shared fixture preserves lane, owner, consumer, risk, CCR pointer and manifest-byte digest across both commands. Warden's unknown workload identity remains unknown; platform claims remain unconfirmed. Both supported commands were executed offline, with no credential or production traffic. The retained receipt is docs/evidence/2026-10-04-catalog-scaffold.json. Routine exact supported lanes may now begin from these draft commands; novel authority or custody flows retain their separately reviewed work.