# App Artifact Trust and Promotion v1

As of: March 9, 2026

## Purpose
Define the trust and promotion baseline for app-platform artifacts.

This baseline applies to both:
1. OCI artifacts, and
2. future non-OCI artifacts registered through the same control-plane artifact model.

## Scope
In scope:
1. artifact trust states,
2. promotion channels and environment progression,
3. verification requirements,
4. policy hooks,
5. audit requirements.

Out of scope:
1. final signing provider implementation,
2. runtime enforcement implementation details for every adapter,
3. full provenance and attestation backend rollout.

## Core Rules
1. digest-only deployment remains mandatory.
2. promotion is explicit and auditable.
3. trust policy must support more than one environment.
4. tags are convenience labels only, never deployment truth.

## Artifact Trust Model
Each artifact has two independent dimensions:
1. lifecycle state
2. trust state

Lifecycle state remains:
1. `published`
2. `promoted`
3. `deprecated`
4. `retired`

Trust state baseline:
1. `unverified`
2. `verified`
3. `failed_verification`
4. `revoked`

Meaning:
1. `unverified`: digest is registered, but required verification has not completed yet.
2. `verified`: digest and required trust checks passed for the current policy.
3. `failed_verification`: verification was attempted and failed.
4. `revoked`: previously accepted artifact is no longer eligible for new use.

## Verification Baseline
Minimum required verification:
1. immutable digest must be present,
2. digest format must be canonical,
3. artifact kind and source type must be explicit,
4. source must be policy-allowlisted.

Reserved trust inputs:
1. OCI signature result,
2. attestation or provenance result,
3. blob digest verification result,
4. source-policy decision result.

The baseline does not require a single signing provider yet, but it does require the control plane to model verification as first-class metadata.

## Platform Contract

`packages/platform/artifacts` is the shared platform contract for artifact trust
and promotion vocabulary. It defines:

1. lifecycle states: `published`, `promoted`, `deprecated`, `retired`;
2. trust states: `unverified`, `verified`, `failed_verification`, `revoked`;
3. promotion channels: `dev`, `test`, `staging`, `prod`;
4. `TrustEvidence`, the reusable evidence shape for digest, provenance, SBOM,
   release evidence, lifecycle, trust, and promotion metadata;
5. `EvaluatePromotionGate`, the first policy-neutral gate helper.

The existing app artifact APIs and inventory service remain the product-facing
implementation. The platform contract prevents those APIs, scripts, release
checks, and future artifact services from inventing incompatible state names or
promotion evidence expectations.

Initial promotion gate behavior:

| Target | Required posture |
|---|---|
| `dev`, `test`, `staging` | artifact is not deprecated/retired and `trust_state=verified` |
| `prod` | all lower-channel requirements plus `provenance_digest`, `sbom_ref`, and `release_evidence_ref` |

The prod requirements are intentionally stricter than the current bootstrap
seed path. They describe the target platform-control and external-app promotion
contract; environments can introduce the gate in report mode before making it
blocking.

## Promotion Model
Promotion is not an implicit consequence of publish.

Promotion dimensions:
1. `channel`
2. optional `target_environment`

Baseline channels:
1. `dev`
2. `test`
3. `staging`
4. `prod`

Rules:
1. promotion must record both source artifact and target channel,
2. promotion to a later channel must be explicit,
3. `prod` promotion must not be implied from `published`,
4. deprecated or retired artifacts are not promotable.

## Policy Hooks
The trust and promotion model must reserve policy decisions for:
1. allowed source types,
2. required verification level per environment or channel,
3. which actors may promote to which channel,
4. whether non-OCI artifacts are allowed for a given project or runtime class.

Examples:
1. `dev` may allow `unverified` artifacts for a project sandbox.
2. `prod` may require `verified` plus attestation.
3. only project admins or approved service accounts may promote to `prod`.

## Audit Requirements
Every trust and promotion mutation must record:
1. actor
2. project
3. artifact id
4. digest
5. artifact kind
6. source type
7. trust state transition or promotion target
8. correlation id

Required audit actions:
1. `app_artifact.register`
2. `app_artifact.verify`
3. `app_artifact.promote`
4. `app_artifact.deprecate`
5. `app_artifact.retire`
6. `app_artifact.revoke`

## Environment Progression Baseline
The same artifact may move through multiple channels or environments.

Recommended baseline:
1. `published` in project scope
2. `promoted` to `dev`
3. `promoted` to `test`
4. `promoted` to `staging`
5. `promoted` to `prod`

The platform must preserve the promotion history as metadata or audit trail, not only the latest promoted channel.

## Non-Negotiable Invariants
1. deployments use digest, not mutable tag,
2. promotion is explicit and auditable,
3. trust is modeled separately from lifecycle state,
4. the trust model works for OCI and non-OCI artifacts,
5. environment progression is not hardcoded to one environment forever.

## Related Docs
1. `doc/architecture/App_Platform_OCI_Registry_Baseline_v1.md`
2. `doc/architecture/App_Non_OCI_Artifact_Lifecycle_v1.md`
3. `doc/architecture/App_Platform_Gap_Tracker_v1.md`
4. `doc/architecture/Platform_Vault_Secrets_Baseline_v1.md`