Promotion Gate Ownership Contract
Serving interfaces and ownership verified against
60913a04352cb4899ab6443e596811b11cc3f01aon 2026-09-30. Source verification does not establish deployed acceptance. Recheck the client and endpoint classes below withrg -n 'MapPost|MapGet|RequireAuthorization' src/Policy/StellaOps.Policy.Engine/Endpoints/PolicyPackEndpoints.cs src/Policy/StellaOps.Policy.Engine/Endpoints/Gateway/GateEndpoints.cs.
Purpose and owners
This contract separates policy evaluation from permission to promote and execute a release. The complete governed journey also needs target observations, recovery, the exact decision evidence and later risk response. Those outcomes remain subject to the core acceptance contract.
| Responsibility | Owner and boundary |
|---|---|
| Advisory/VEX source observations and corpus publication | Vulnerabilities hub, including its carried Concelier/Excititor libraries. Ingestion does not authorize a release. |
| Scan attempts, component inventory and scan evidence | Scanner, through its owner API/events. A completed scan is not a promotion decision. |
| Policy evaluation and effective policy inputs | Policy Engine, using its own data and authorized owner contracts. |
| Release identity, environment binding, approval policy and committed release decision | Release Orchestrator (RO). It records the evaluated basis and owns promotion state. |
| Approval, exception and dispatch enforcement | RO applies its current quorum, signing, evidence, target and execution rules. An active signed exception remains distinct from a passing gate. |
| Identity and grants | Authority issues identity/scopes; each serving owner enforces its authorization and tenant boundary. |
| Proof custody and verification | Consolidated Evidence; Signer remains a separate key owner. |
Policy and RO each own a physical database and role. Cross-service reads use the owner’s API, events or registered read contract; no Policy-to-RO database join is authorized by this document. See database ownership.
Current serving interfaces
Two evaluation interfaces serve different workflows. Their payloads are not interchangeable.
| Workflow | Current interface | Request and result |
|---|---|---|
| RO evaluates its selected pack | POST /api/policy/packs/{packId}/revisions/{version}/evaluate | HttpPolicyEngineGateClient sends packId, version, subject. The response carries packId, version, digest, decision, correlationId, cached, optional evidence and attestationRef. |
| CI evaluates an image against a baseline | POST /api/v1/policy/gate/evaluate | GateEvaluateRequest names imageDigest, optional baseline/policy and CI context. GateEvaluateResponse carries decision ID, Pass/Warn/Fail status, exit code, baseline resolution, gate results and optional attestation. The route requires policy:run. |
| Read the CI decision | GET /api/v1/policy/gate/decision/{decisionId} | Reads the recorded decision under policy:read; it does not re-evaluate current inputs. |
| Request a release promotion | POST /api/v1/release-orchestrator/releases/{id}/promote | RO resolves release/environment context, evaluates the configured gates and records its own decision/approval state. A successful policy response alone is insufficient to authorize dispatch. |
Tenant identity comes from the authenticated context. RO’s PolicyEngineServiceTokenHandler supplies its authorized service identity for the Policy call; the operator’s privileges are not broadened by forwarding that call.
Source authorities:
src/ReleaseOrchestrator/__Apps/StellaOps.ReleaseOrchestrator.WebApi/Services/HttpPolicyEngineGateClient.cssrc/ReleaseOrchestrator/__Apps/StellaOps.ReleaseOrchestrator.WebApi/Services/PolicyDrivenGateDecisionEvaluator.cssrc/Policy/StellaOps.Policy.Engine/Endpoints/PolicyPackEndpoints.cssrc/Policy/StellaOps.Policy.Engine/Endpoints/Gateway/GateEndpoints.cssrc/Policy/StellaOps.Policy.Engine/Contracts/Gateway/GateContracts.cs
Decision, authorization and history
- Missing or invalid inputs retain the configured deny, waiting or unavailable outcome. A skipped or advisory gate does not establish a completed allow decision.
- Missing CI baselines block by default. Explicit
warnorbootstrapbehavior is recorded in the gate result. A bootstrap receipt is not proof that all tenant advisory inputs are complete. - RO checks approval state and evidence through
ApprovalSafetyGuardandReleaseTruthGuard;DeploymentDispatchProcessorrechecks the current decision before execution. Rejection follows its own authorized path. Base operator/security profiles do not implicitly receive publish or bypass grants. - Deterministic evaluation requires the same resolved inputs and policy version, not merely the same HTTP request when its referenced data can change. Preserve the owner canonicalization rules; a Policy determinism hash and an RO signed decision digest are distinct values.
- RO stores the decision basis and envelope through
PromotionRequestProcessor. The current signed request path can apply operator metadata after that initial write. CCP-050 must capture the finalized immutable revision when creating durable seal intent; it must not substitute the latest decision later. - New advisory, VEX or reachability evidence changes the current assessment. The prior decision and proof keep their recorded inputs. Exception expiry/revocation is checked by its owner before a protected operation; remediation is attributable successor work.
Implementation and acceptance limits
The APIs and enforcement classes above exist in source. Complete first delivery, tenant-complete advisory/VEX input, changed-risk response and exception/remediation closure still require the program’s CA-01–CA-12 receipts. Durable seal recovery is planned work, not an existing guarantee. Approval does not prove target completion, and evidence receipt does not prove signature validity, trusted policy acceptance or deterministic replay.
Relevant existing test entry points include RO Integration.Tests ApprovalSafetyGuardTests, ApprovalQueueHygieneTests, DeploymentDispatchDurableTransitionTests and ReleaseTruthRepositoryPersistenceTests; Policy.Engine.Tests includes PolicyEngineGateFirstBaselineEnrollmentTests and PostgresFindingsLookupProjectionMatchTests. Run the selected owner tests and authorized live scenarios before claiming their runtime boundary.
Related contracts
- Promotion evidence
- Release Orchestrator architecture
- Policy gateway guide
- Accepted product decisions