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	Reference (Attestor uuid/subject) to a build-provenance attestation discovered for the digest (RL-2c). 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).

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