stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity

save checkpoint

Browse Source
This commit is contained in:
master
2026-02-11 01:32:14 +02:00
parent 5593212b41
commit cf5b72974f
2316 changed files with 68799 additions and 3808 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
docs/modules/release-orchestrator/README.md
View File

@@ -54,6 +54,7 @@ The Release Orchestrator extends Stella Ops from a vulnerability scanning platfo
- [Environment APIs](api/environments.md) — Environment endpoints
- [Release APIs](api/releases.md) — Release endpoints
- [Promotion APIs](api/promotions.md) — Promotion endpoints
- [Promotion Runtime Gap Closure Plan](promotion-runtime-gap-closure-plan.md) — Docs-to-runtime delivery sequence
- [Workflow APIs](api/workflows.md) — Workflow endpoints
- [Agent APIs](api/agents.md) — Agent endpoints
- [WebSocket APIs](api/websockets.md) — Real-time endpoints
@@ -62,6 +63,7 @@ The Release Orchestrator extends Stella Ops from a vulnerability scanning platfo
- [Template Structure](workflow/templates.md) — Workflow template specification
- [Execution State Machine](workflow/execution.md) — Workflow state machine
- [Promotion State Machine](workflow/promotion.md) — Promotion state machine
- [Evidence-Based Release Gates](workflow/evidence-based-release-gates.md) — Data-driven evidence gate contract and outcomes
### Security
- [Security Overview](security/overview.md) — Security principles
@@ -109,6 +111,7 @@ The Release Orchestrator extends Stella Ops from a vulnerability scanning platfo
- [Configuration Reference](appendices/config.md) — Configuration options
- [Error Codes](appendices/errors.md) — API error codes
- [Evidence Schema](appendices/evidence-schema.md) — Evidence packet format
- [Optional Promotion Capsule](appendices/promotion-capsule-optional.md) — Optional DSSE capsule and `human_decision` envelope profile
## Quick Reference

3
docs/modules/release-orchestrator/api/environments.md
View File

@@ -6,6 +6,9 @@
**Source:** [Architecture Advisory Section 6.3.2](../../../product/advisories/09-Jan-2026%20-%20Stella%20Ops%20Orchestrator%20Architecture.md)
**Related Modules:** [Environment Manager](../modules/environment-manager.md), [Agents](../modules/agents.md)
> Runtime note: environment APIs are documented here; controller implementation
> sequencing is tracked in `../promotion-runtime-gap-closure-plan.md`.
## Overview
The Environment Management API provides CRUD operations for environments, target groups, deployment targets, agents, freeze windows, and inventory synchronization. All endpoints require authentication and respect tenant isolation via Row-Level Security.

7
docs/modules/release-orchestrator/api/promotions.md
View File

@@ -6,10 +6,17 @@
**Source:** [Architecture Advisory Section 6.3.5](../../../product/advisories/09-Jan-2026%20-%20Stella%20Ops%20Orchestrator%20Architecture.md)
**Related Modules:** [Promotion Manager Module](../modules/promotion-manager.md), [Workflow Promotion](../workflow/promotion.md)
> Runtime note: promotion libraries and tests exist, while the API host controllers
> for these endpoints are tracked in `../promotion-runtime-gap-closure-plan.md`.
## Overview
The Promotion API provides endpoints for requesting release promotions between environments, managing approvals, and evaluating promotion gates. Promotions enforce separation of duties (SoD) and require configured approvals before deployment proceeds.
Gate contract references:
- `../../policy/promotion-gate-ownership-contract.md`
- `../../evidence-locker/promotion-evidence-contract.md`
---
## Promotion Endpoints

56
docs/modules/release-orchestrator/appendices/promotion-capsule-optional.md Normal file
View File

@@ -0,0 +1,56 @@
# Optional Promotion Capsule and `human_decision` Envelope
## Status
Optional profile. This appendix must not block baseline promotion delivery.
## Promotion Capsule (Optional)
The optional promotion capsule is a DSSE-wrapped bundle containing:
- Promotion identity (`promotionId`, source/target environment, artifact digests)
- Policy inputs (policy digest/version, gate input digest)
- Evidence references (evidence bundle id, attestation digests, Rekor refs)
- Decision output (allow/deny/pending + reason codes)
- Signatures and verification metadata
## Suggested Envelope Type
- Media type: `application/vnd.stellaops.promotion-capsule+json`
- Predicate type: `stella.ops/promotionCapsule@v1`
## Optional `human_decision` DSSE Envelope
For exception paths, the optional envelope captures accountable human override
decisions and links them to the promotion record.
Required fields:
- `decisionId` (stable id)
- `promotionId`
- `requestId` (Policy exception approval request id)
- `actorId`
- `decision` (`approve|reject|cancel`)
- `reason`
- `ticket`
- `expiresAtUtc` (if temporary override)
- `recordedAtUtc`
## Binding to Existing Approval Workflows
- Policy exception workflow APIs remain source of truth for request lifecycle.
- Optional DSSE `human_decision` envelope references Policy request/audit ids.
- Promotion decision records may include `humanDecisionEnvelopeId` when present.
## SLA and Governance Notes
- `human_decision` should be time-bounded and non-default.
- Override paths should require explicit scope and reason metadata.
- Expired override envelopes must not authorize future promotions.
## Related References
- `src/Policy/StellaOps.Policy.Gateway/Endpoints/ExceptionApprovalEndpoints.cs`
- `src/Policy/StellaOps.Policy.Gateway/Services/ApprovalWorkflowService.cs`
- `docs/product/decision-capsules.md`
- `docs/modules/release-orchestrator/workflow/promotion.md`

4
docs/modules/release-orchestrator/modules/promotion-manager.md
View File

@@ -111,6 +111,10 @@ interface Approval {
| **Data Entities** | `DecisionRecord`, `GateResult` |
| **Events Produced** | `decision.evaluated`, `decision.recorded` |
Policy ownership note: PASS/FAIL promotion gate semantics are owned by Policy
Engine and consumed by promotion workflows. Concelier remains ingestion-only for
advisory/linkset data.
**Decision Record Structure**:
```typescript
interface DecisionRecord {

62
docs/modules/release-orchestrator/promotion-runtime-gap-closure-plan.md Normal file
View File

@@ -0,0 +1,62 @@
# Promotion Runtime Gap Closure Plan
## Scope
Close the gap between documented Release Orchestrator promotion/environment APIs
and currently implemented runtime controllers.
## Current Runtime Reality
Implemented HTTP controllers:
| Runtime surface | Implemented controller |
| --- | --- |
| Compliance APIs | `src/ReleaseOrchestrator/StellaOps.ReleaseOrchestrator.Api/Controllers/ComplianceController.cs` |
| Rollback intelligence APIs | `src/ReleaseOrchestrator/__Apps/StellaOps.ReleaseOrchestrator.WebApi/Controllers/RollbackIntelligenceController.cs` |
Promotion libraries are implemented and test-covered, but promotion/environment
HTTP controllers are not yet present in these API hosts.
## Gap Inventory (Docs vs Runtime)
| API group | Doc status | Runtime status | Priority |
| --- | --- | --- | --- |
| `/api/v1/environments` | Documented | Missing controller | P0 |
| `/api/v1/promotions` | Documented | Missing controller | P0 |
| `/api/v1/promotions/{id}/decision` | Documented | Missing controller | P0 |
| `/api/v1/promotions/{id}/evidence` | Documented | Missing controller | P1 |
| `/api/v1/approval-policies` | Documented | Missing controller | P1 |
## Delivery Sequence
1. Add Environment API controller surface backed by `IEnvironmentService`.
2. Add Promotion API controller surface backed by `IPromotionManager` and
decision services.
3. Add decision/evidence endpoints with deterministic response models.
4. Add approval-policy endpoints and SoD enforcement bindings.
5. Add integration tests for end-to-end promotion request -> decision retrieval.
## Acceptance Criteria
- Endpoint group implementation is tracked by API group with owning project path.
- Promotion state transitions match `docs/modules/release-orchestrator/workflow/promotion.md`.
- Decision records include policy digest and evidence references.
- Fail-closed behavior is enforced when gate providers error.
- Replay-oriented deterministic assertions are present in tests.
## Test Targets
- `src/ReleaseOrchestrator/__Tests/StellaOps.ReleaseOrchestrator.Promotion.Tests/`
- `src/ReleaseOrchestrator/__Tests/StellaOps.ReleaseOrchestrator.Environment.Tests/`
- `src/ReleaseOrchestrator/__Tests/StellaOps.ReleaseOrchestrator.Integration.Tests/`
Minimum acceptance test mapping:
- Policy gate and decision flow: `Gate/PolicyGateTests.cs`, `Decision/DecisionEngineTests.cs`
- Deterministic gate evaluation ordering: `Gate/GateEvaluatorTests.cs`
- Environment promotion sequencing: `Environment.Tests/Services/EnvironmentServiceTests.cs`
## Related Contracts
- Policy ownership: `docs/modules/policy/promotion-gate-ownership-contract.md`
- Evidence contract: `docs/modules/evidence-locker/promotion-evidence-contract.md`
- Optional capsule profile: `docs/modules/release-orchestrator/appendices/promotion-capsule-optional.md`

95
docs/modules/release-orchestrator/workflow/evidence-based-release-gates.md Normal file
View File

@@ -0,0 +1,95 @@
# Evidence-Based Release Gates Contract
**Status:** Implemented baseline in promotion runtime (2026-02-10)
**Related:** `docs/modules/release-orchestrator/workflow/promotion.md`, `docs/modules/attestor/repro-bundle-profile.md`, `docs/modules/evidence-locker/architecture.md`
## Purpose
Define a deterministic, policy-driven promotion gate model where release decisions are made from verifiable evidence, not ad hoc logic. This contract translates the evidence-based gate advisory into Stella Ops module boundaries and delivery tasks.
## Gate Policy Model (Data-Driven)
Gate policy is treated as versioned data (for example CUE compiled to JSON, or equivalent policy-pack JSON). At minimum, the gate policy profile must declare:
- `name`, `environment`
- `evidence.min_score`, `evidence.required_links`, `evidence.product_digest_alg`
- `signatures.k_of_n.k`, `signatures.k_of_n.n`, `signatures.allowed_keys`, `signatures.dsse_algos`
- `rekor.required`, `rekor.instance_url`, `rekor.max_fresh_secs`
- `retry.backoff_initial_ms`, `retry.backoff_factor`, `retry.max_retries`
- `escalation.mode`, `escalation.human_queue`, `escalation.require_signed_human_decision`
- `slo.p50_ms`, `slo.p90_ms`, `slo.p99_ms`, `slo.async_hold_sla_hours`, `slo.evidence_ttl_hours`
## Required Promotion Checks
Promotion gate evaluation must enforce all enabled checks below:
1. Evidence score threshold
- Require `evidence_score >= policy.evidence.min_score`.
2. Rekor inclusion and freshness
- Require inclusion proof present and verified when `policy.rekor.required=true`.
- Require proof freshness within `policy.rekor.max_fresh_secs`.
3. In-toto build link + digest binding
- Require `build` link when configured in `policy.evidence.required_links`.
- Require build product digest to exactly match release artifact digest under `policy.evidence.product_digest_alg`.
4. DSSE signer threshold (k-of-n)
- Count only valid signatures whose key IDs and algorithms are in policy allowlists.
- Require `valid_unique_signers >= policy.signatures.k_of_n.k`.
## Decision Workflow Contract
Promotion flow for evidence gates:
`collect_evidence -> evaluate_gate_sync -> { approve | hold_async | escalate }`
Decision semantics:
- `approve`: all enabled checks pass.
- `hold_async`: heavyweight evidence still pending; re-evaluate on evidence arrival or TTL expiry.
- `escalate`: retries exhausted or policy requires human disposition; require DSSE-signed human decision when configured.
Runtime mapping:
- `hold_async` is persisted as `DecisionOutcome.HoldAsync` (legacy `PendingGate` remains for compatibility).
- `escalate` is persisted as `DecisionOutcome.Escalate`.
## Lane Defaults
- Sovereign and air-gap lanes default to `fail_closed`.
- Dev lanes may use `fail_open_with_alert` only with mandatory audit record and alert emission.
## Audit and Replay Requirements
For each gate decision, persist immutable evidence pointers and gate inputs:
- policy identifier and version/digest
- gate input hashes and evidence bundle references
- DSSE envelope references and signer IDs counted toward k-of-n
- Rekor UUIDs/log index/inclusion proof references and freshness timestamp
- decision outcome, reason codes, retries, escalation routing
- wall-clock timing metrics for SLO tracking
- human decision DSSE reference when escalation occurs
## SLO Targets
Synchronous gate targets:
- P50 <= 200 ms
- P90 <= 2 s
- P99 <= 15 s
Asynchronous hold targets:
- `async_hold_sla_hours <= 12` (default profile)
- `evidence_ttl_hours <= 24` with re-evaluation when stale
## Implementation Notes (2026-02-10)
- `SecurityGate` now enforces policy-configured checks for:
- `minEvidenceScore` threshold (`SEC_REPRO_EVIDENCE_SCORE_THRESHOLD`)
- in-toto build-link presence + digest binding (`SEC_REPRO_BUILD_LINK_MISSING`, `SEC_REPRO_BUILD_DIGEST_MISMATCH`)
- DSSE k-of-n signer threshold (`SEC_REPRO_DSSE_THRESHOLD`)
- Rekor freshness TTL with retry + escalation mode (`SEC_REPRO_REKOR_FRESHNESS_*`, `SEC_ESCALATION_*`)
- Environment gate-specific policy config is now propagated into gate evaluation context by `DecisionEngine`.
- Decision recording now captures SLO metadata (`p50/p90/p99`, async hold SLA, evidence TTL) and DSSE human decision reference when present.

6
docs/modules/release-orchestrator/workflow/promotion.md
View File

@@ -4,6 +4,12 @@
Promotions move releases through environments (Dev -> Staging -> Production). The promotion state machine manages the lifecycle from request to completion.
For policy-driven evidence gate inputs, checks, and outcomes, see `evidence-based-release-gates.md`.
Evidence-gate outcomes include explicit `hold_async` and `escalate` semantics in decision records:
- `hold_async` maps to `DecisionOutcome.HoldAsync` for asynchronous evidence completion.
- `escalate` maps to `DecisionOutcome.Escalate` when retry budgets are exhausted or lane policy requires human disposition.
## Promotion States
```