# 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`