Entity Definitions

This document describes the core entities in the Release Orchestrator data model.

Entity Relationship Overview

┌─────────────────────────────────────────────────────────────────────────────┐
│                          ENTITY RELATIONSHIPS                               │
│                                                                             │
│  ┌──────────┐       ┌──────────────┐       ┌────────────┐                  │
│  │ Tenant   │───────│ Environment  │───────│ Target     │                  │
│  └──────────┘       └──────────────┘       └────────────┘                  │
│       │                    │                     │                          │
│       │                    │                     │                          │
│       ▼                    ▼                     ▼                          │
│  ┌──────────┐       ┌──────────────┐       ┌────────────┐                  │
│  │ Component│       │ Approval     │       │ Agent      │                  │
│  └──────────┘       │ Policy       │       └────────────┘                  │
│       │             └──────────────┘             │                          │
│       │                    │                     │                          │
│       ▼                    │                     ▼                          │
│  ┌──────────┐              │              ┌─────────────┐                  │
│  │ Version  │              │              │ Deployment  │                  │
│  │ Map      │              │              │ Task        │                  │
│  └──────────┘              │              └─────────────┘                  │
│       │                    │                     │                          │
│       │                    │                     │                          │
│       ▼                    │                     ▼                          │
│  ┌─────────────────────────┼─────────────────────────────┐                 │
│  │                         │                             │                 │
│  │  ┌──────────┐     ┌─────▼─────┐     ┌─────────────┐  │                 │
│  │  │ Release  │─────│ Promotion │─────│ Deployment  │  │                 │
│  │  └──────────┘     └───────────┘     │ Job         │  │                 │
│  │       │                 │           └─────────────┘  │                 │
│  │       │                 │                 │          │                 │
│  │       │                 ▼                 │          │                 │
│  │       │           ┌───────────┐           │          │                 │
│  │       │           │ Approval  │           │          │                 │
│  │       │           └───────────┘           │          │                 │
│  │       │                 │                 │          │                 │
│  │       │                 ▼                 ▼          │                 │
│  │       │           ┌───────────┐     ┌───────────┐   │                 │
│  │       │           │ Decision  │     │ Generated │   │                 │
│  │       │           │ Record    │     │ Artifacts │   │                 │
│  │       │           └───────────┘     └───────────┘   │                 │
│  │       │                 │                 │          │                 │
│  │       │                 └────────┬────────┘          │                 │
│  │       │                          │                   │                 │
│  │       │                          ▼                   │                 │
│  │       │                    ┌───────────┐             │                 │
│  │       └───────────────────►│ Evidence  │◄────────────┘                 │
│  │                            │ Packet    │                                │
│  │                            └───────────┘                                │
│  │                                  │                                      │
│  │                                  ▼                                      │
│  │                            ┌───────────┐                                │
│  │                            │ Version   │                                │
│  │                            │ Sticker   │                                │
│  │                            └───────────┘                                │
│  │                                                                         │
│  └─────────────────────────────────────────────────────────────────────────┘
└─────────────────────────────────────────────────────────────────────────────┘

Core Entities

Environment

Represents a deployment target environment (dev, staging, production).

Field	Type	Description
`id`	UUID	Primary key
`tenant_id`	UUID	Tenant reference
`name`	string	Unique name (e.g., “prod”)
`display_name`	string	Display name (e.g., “Production”)
`order_index`	integer	Promotion order
`config`	JSONB	Environment configuration
`freeze_windows`	JSONB	Active freeze windows
`required_approvals`	integer	Approvals needed for promotion
`require_sod`	boolean	Require separation of duties
`created_at`	timestamp	Creation time

Target

Represents a deployment target (host, service).

Field	Type	Description
`id`	UUID	Primary key
`tenant_id`	UUID	Tenant reference
`environment_id`	UUID	Environment reference
`name`	string	Target name
`target_type`	string	Type (docker_host, compose_host, etc.)
`connection`	JSONB	Connection configuration
`labels`	JSONB	Target labels
`health_status`	string	Current health status
`current_digest`	string	Currently deployed digest

Agent

Represents a deployment agent.

Field	Type	Description
`id`	UUID	Primary key
`tenant_id`	UUID	Tenant reference
`name`	string	Agent name
`version`	string	Agent version
`capabilities`	JSONB	Agent capabilities
`status`	string	online/offline/degraded
`last_heartbeat`	timestamp	Last heartbeat time

Component

Represents a deployable component (maps to an image repository).

Field	Type	Description
`id`	UUID	Primary key
`tenant_id`	UUID	Tenant reference
`name`	string	Tenant-unique component name
`display_name`	string	Display name
`description`	string	Optional operator description
`image_repository`	string	Default image repository used for registry sync and release authoring
`registry_integration_id`	string	Default tenant registry integration used to resolve tags to digests
`versioning_strategy`	string	Version label strategy: `semver`, `branch-tag`, or `label`
`status`	string	`active` or `retired`
`default_channel`	string	Default version channel
`default_version_label`	string	Optional fallback label used when the strategy cannot derive a label
`environment_registry_overrides`	JSON object	Optional per-environment registry integration and repository override
`labels`	JSON object	Tenant-defined component labels
`created_at`	timestamp	Creation time
`updated_at`	timestamp	Last update time

Version Map

Maps image tags to immutable digests and operator-facing version labels.

Field	Type	Description
`id`	UUID	Primary key
`tenant_id`	UUID	Tenant reference
`component_id`	UUID	Component reference
`tag`	string	Image tag
`digest`	string	Image digest (sha256:…)
`version_label`	string	Operator-facing version label derived from the component strategy
`channel`	string	Version channel (for example `stable`, `main`, `prod`)
`source_commit_sha`	string	Source commit captured from registry/OCI labels when present
`source_repo_url`	string	Source repository URL captured from registry/OCI config labels or operator override
`source_branch`	string	Source branch/ref captured from registry/OCI config labels or operator override
`scm_manually_set`	boolean	True when operator-supplied SCM values should survive registry re-sync
`discovered_at`	timestamp	Time the tag/digest pair was recorded
`built_at`	timestamp	Optional build timestamp from registry metadata
`metadata`	JSON object	Registry and OCI label metadata retained for audit/debugging

The digest is the immutable release identity. Tags and labels remain human-facing metadata. Mutable branch tags are safe because each distinct (component_id, tag, digest) is stored as its own version row.

Release Component (truth-store binding)

Each release pins its component digests in release_orchestrator.release_components (the DTO lives in component_json; scalar columns are audit-query projections). Sprint 20260704_007 (RL-1) adds source lineage — the “birth certificate” that answers which commit produced release X — as columns on this table (not a joined table: lineage is 1:1 with a pinned digest).

Field	Type	Description
`source_commit_sha`	string	Source git commit the digest was built from. From OCI labels (`org.opencontainers.image.revision`), the `component_versions` sync, or operator input — never invented.
`source_repo_url`	string	Source repository URL (`org.opencontainers.image.source` / `component_versions` / operator).
`pipeline_ref`	string	CI pipeline/run reference, when known.
`provenance_attestation_ref`	string	Evidence uuid of a build-provenance attestation discovered for the digest at component add (RL-2c): an entry of a configured provenance artifact kind (`ReleaseOrchestrator:Provenance:ProvenanceArtifactKinds`, default `slsa-provenance`) whose artifact binds exactly to the digest. NULL ⇒ `provenance: absent`.
`lineage_status`	string	`known` \| `ambiguous` (digest maps to >1 distinct commit — newest-sync recorded, collision flagged) \| `unknown` (honest absence).

Populated at component-add from the resolved component version’s OCI-label lineage, from a component_versions lookup by digest for the raw-digest ingress path, and by an Attestor provenance lookup; and back-filled onto already-pinned components by the component_versions sync write-through (digest is the join key; tags never). Surfaced in the release-detail UI, in stella release show, and as the advisory provenance-present predicate in the gate decision basis (RL-3).

source_commit_sha, source_repo_url and pipeline_ref record lineage from labels, sync or operator input; they are not attested and never count as CI evidence. The CI evidence receipt and the Chain of Custody Source and Build stages read the provenance attestation itself, at request time, through the first-delivery API.

Release

A versioned bundle of component digests.

Field	Type	Description
`id`	UUID	Primary key
`tenant_id`	UUID	Tenant reference
`name`	string	Release name
`display_name`	string	Display name
`components`	JSONB	Component/digest mappings
`source_ref`	JSONB	Source code reference
`status`	string	draft/ready/deployed/deprecated
`created_by`	UUID	Creator user reference

Promotion

A request to promote a release to an environment.

Field	Type	Description
`id`	UUID	Primary key
`tenant_id`	UUID	Tenant reference
`release_id`	UUID	Release reference
`source_environment_id`	UUID	Source environment (nullable)
`target_environment_id`	UUID	Target environment
`status`	string	Promotion status
`decision_record`	JSONB	Gate evaluation results
`workflow_run_id`	UUID	Associated workflow run
`requested_by`	UUID	Requesting user
`requested_at`	timestamp	Request time

Approval

An approval or rejection of a promotion.

Field	Type	Description
`id`	UUID	Primary key
`promotion_id`	UUID	Promotion reference
`approver_id`	UUID	Approving user
`action`	string	approved/rejected
`comment`	string	Approval comment
`approved_at`	timestamp	Approval time

Deployment Job

A deployment execution job.

Field	Type	Description
`id`	UUID	Primary key
`promotion_id`	UUID	Promotion reference
`release_id`	UUID	Release reference
`environment_id`	UUID	Environment reference
`status`	string	Job status
`strategy`	string	Deployment strategy
`artifacts`	JSONB	Generated artifacts
`rollback_of`	UUID	If rollback, original job

Deployment Task

A task to deploy to a single target.

Field	Type	Description
`id`	UUID	Primary key
`job_id`	UUID	Job reference
`target_id`	UUID	Target reference
`digest`	string	Digest to deploy
`status`	string	Task status
`agent_id`	UUID	Assigned agent
`logs`	text	Execution logs
`previous_digest`	string	Previous digest (for rollback)

Evidence Packet

Immutable audit evidence for a promotion/deployment.

Field	Type	Description
`id`	UUID	Primary key
`promotion_id`	UUID	Promotion reference
`packet_type`	string	Type of evidence
`content`	JSONB	Evidence content
`content_hash`	string	SHA-256 of content
`signature`	string	Cryptographic signature
`signer_key_ref`	string	Signing key reference
`created_at`	timestamp	Creation time (no update)

Version Sticker

Version marker placed on deployment targets.

Field	Type	Description
`id`	UUID	Primary key
`target_id`	UUID	Target reference
`release_id`	UUID	Release reference
`promotion_id`	UUID	Promotion reference
`sticker_content`	JSONB	Sticker JSON content
`content_hash`	string	Content hash
`written_at`	timestamp	Write time
`drift_detected`	boolean	Drift detection flag

Workflow Entities

Workflow Template

A reusable workflow definition.

Field	Type	Description
`id`	UUID	Primary key
`tenant_id`	UUID	Tenant reference (null for builtin)
`name`	string	Template name
`version`	integer	Template version
`nodes`	JSONB	Step nodes
`edges`	JSONB	Step edges
`inputs`	JSONB	Input definitions
`outputs`	JSONB	Output definitions
`is_builtin`	boolean	Is built-in template

Workflow Run

An execution of a workflow template.

Field	Type	Description
`id`	UUID	Primary key
`template_id`	UUID	Template reference
`template_version`	integer	Template version at execution
`status`	string	Run status
`context`	JSONB	Execution context
`inputs`	JSONB	Input values
`outputs`	JSONB	Output values
`started_at`	timestamp	Start time
`completed_at`	timestamp	Completion time

Step Run

Execution of a single step within a workflow run.

Field	Type	Description
`id`	UUID	Primary key
`workflow_run_id`	UUID	Workflow run reference
`node_id`	string	Node ID from template
`status`	string	Step status
`inputs`	JSONB	Resolved inputs
`outputs`	JSONB	Produced outputs
`logs`	text	Execution logs
`attempt_number`	integer	Retry attempt number

Plugin Entities

Plugin

A registered plugin.

Field	Type	Description
`id`	UUID	Primary key
`plugin_id`	string	Unique plugin identifier
`version`	string	Plugin version
`vendor`	string	Plugin vendor
`manifest`	JSONB	Plugin manifest
`status`	string	Plugin status
`entrypoint`	string	Plugin entrypoint path

Plugin Instance

A tenant-specific plugin configuration.

Field	Type	Description
`id`	UUID	Primary key
`plugin_id`	UUID	Plugin reference
`tenant_id`	UUID	Tenant reference
`config`	JSONB	Tenant configuration
`enabled`	boolean	Is enabled for tenant

Integration Entities

Integration

A configured external integration.

Field	Type	Description
`id`	UUID	Primary key
`tenant_id`	UUID	Tenant reference
`type_id`	string	Integration type
`name`	string	Integration name
`config`	JSONB	Integration configuration
`credential_ref`	string	Vault credential reference
`health_status`	string	Connection health