ss-tools/specs/025-clean-release-compliance/data-model.md

Data Model: Clean Release Compliance Subsystem Redesign

Feature: 025-clean-release-compliance
Spec: spec.md
Research: research.md

1. Entity: ReleaseCandidate

Represents the release unit that is being prepared, checked, approved and published.

Fields

Field	Type	Required	Description
id	string	Yes	Stable candidate identifier.
version	string	Yes	Release version label.
source_snapshot_ref	string	Yes	Reference to code/source snapshot used to create candidate.
build_id	string	No	Upstream build or pipeline identifier.
created_at	datetime	Yes	Candidate creation timestamp.
created_by	string	Yes	Actor that created the candidate.
provenance_ref	string	No	Optional provenance or attestation reference.
status	enum	Yes	Current lifecycle state.

Validation Rules

• id, version, source_snapshot_ref, created_at, created_by, status must be present.
• status must be one of: DRAFT, PREPARED, MANIFEST_BUILT, CHECK_PENDING, CHECK_RUNNING, CHECK_PASSED, CHECK_BLOCKED, CHECK_ERROR, APPROVED, PUBLISHED, REVOKED.
• Terminal publication evidence cannot exist without a valid candidate.

Lifecycle / State Transitions

• DRAFT -> PREPARED
• PREPARED -> MANIFEST_BUILT
• MANIFEST_BUILT -> CHECK_PENDING
• CHECK_PENDING -> CHECK_RUNNING
• CHECK_RUNNING -> CHECK_PASSED
• CHECK_RUNNING -> CHECK_BLOCKED
• CHECK_RUNNING -> CHECK_ERROR
• CHECK_PASSED -> APPROVED
• APPROVED -> PUBLISHED
• PUBLISHED -> REVOKED

---

2. Entity: CandidateArtifact

Represents one artifact associated with a release candidate.

Fields

Field	Type	Required	Description
id	string	Yes	Stable artifact identifier.
candidate_id	string	Yes	Owning release candidate.
path	string	Yes	Artifact path or logical location.
sha256	string	Yes	Artifact checksum.
size	integer	Yes	Artifact size in bytes.
detected_category	string	No	Category determined by system or pipeline.
declared_category	string	No	Category declared by external input.
source_uri	string	No	Artifact source URI if known.
source_host	string	No	Parsed source host if known.
metadata	object	Yes	Additional attributes.

Validation Rules

• sha256 must be present and stable for the artifact content.
• size >= 0.
• declared_category and detected_category may differ, but the difference must remain observable.

---

3. Entity: DistributionManifest

Immutable snapshot describing the candidate payload selected for distribution.

Fields

Field	Type	Required	Description
id	string	Yes	Stable manifest identifier.
candidate_id	string	Yes	Owning release candidate.
manifest_version	integer	Yes	Monotonic manifest version per candidate.
manifest_digest	string	Yes	Overall digest of manifest content.
artifacts_digest	string	Yes	Digest over artifact selection.
created_at	datetime	Yes	Manifest creation time.
created_by	string	Yes	Actor that built the manifest.
source_snapshot_ref	string	Yes	Source snapshot bound to the manifest.
content_json	object	Yes	Serialized immutable manifest content.
immutable	boolean	Yes	Must be true after creation.

Validation Rules

• manifest_version >= 1 and strictly increases for a candidate.
• Existing manifest content cannot be overwritten.
• manifest_digest must uniquely reflect content_json.

---

4. Entity: CleanPolicySnapshot

Immutable policy snapshot used to evaluate a run.

Fields

Field	Type	Required	Description
id	string	Yes	Snapshot identifier.
policy_id	string	Yes	Logical policy identifier in trusted store.
policy_version	string	Yes	Trusted policy version.
created_at	datetime	Yes	Snapshot creation time.
content_json	object	Yes	Frozen policy content.
registry_snapshot_id	string	Yes	Bound source registry snapshot.
immutable	boolean	Yes	Must be true.

Validation Rules

• Snapshot must reference a valid registry snapshot.
• UI/env input cannot mutate content_json after creation.

---

5. Entity: SourceRegistrySnapshot

Immutable registry snapshot for allowed sources and schemes.

Fields

Field	Type	Required	Description
id	string	Yes	Snapshot identifier.
registry_id	string	Yes	Logical trusted registry identifier.
registry_version	string	Yes	Trusted registry version.
created_at	datetime	Yes	Snapshot creation time.
allowed_hosts	array[string]	Yes	Allowed hosts or host patterns.
allowed_schemes	array[string]	Yes	Allowed URL schemes.
allowed_source_types	array[string]	Yes	Allowed source type labels.
immutable	boolean	Yes	Must be true.

---

6. Entity: ComplianceRun

Operational record for one compliance execution request.

Fields

Field	Type	Required	Description
id	string	Yes	Run identifier.
candidate_id	string	Yes	Candidate being checked.
manifest_id	string	Yes	Manifest used for the run.
manifest_digest	string	Yes	Manifest digest copied at request time.
policy_snapshot_id	string	Yes	Policy snapshot used.
registry_snapshot_id	string	Yes	Registry snapshot used.
requested_by	string	Yes	Actor that requested the run.
requested_at	datetime	Yes	Request time.
started_at	datetime	No	Execution start time.
finished_at	datetime	No	Execution finish time.
status	enum	Yes	Execution status.
final_status	enum	No	Final compliance result.
failure_reason	string	No	System or validation failure summary.
task_id	string	No	Linked async task identifier.

Validation Rules

• status must be one of PENDING, RUNNING, SUCCEEDED, FAILED, CANCELLED.
• final_status, when present, must be one of PASSED, BLOCKED, ERROR.
• task_id is mutable only until execution binding is established.

---

7. Entity: ComplianceStageRun

Stage-level execution record inside one run.

Fields

Field	Type	Required	Description
id	string	Yes	Stage run identifier.
run_id	string	Yes	Owning compliance run.
stage_name	string	Yes	Canonical stage name.
status	string	Yes	Stage execution status.
started_at	datetime	No	Stage start time.
finished_at	datetime	No	Stage finish time.
decision	string	No	PASSED, BLOCKED, or ERROR.
details_json	object	Yes	Structured stage details.

---

8. Entity: ComplianceViolation

Violation produced by one stage within one run.

Fields

Field	Type	Required	Description
id	string	Yes	Violation identifier.
run_id	string	Yes	Owning compliance run.
stage_name	string	Yes	Stage that detected the issue.
code	string	Yes	Canonical violation code.
severity	string	Yes	Severity label.
artifact_path	string	No	Related artifact path.
artifact_sha256	string	No	Related artifact checksum.
message	string	Yes	Human-readable explanation.
evidence_json	object	Yes	Structured evidence.

Validation Rules

• Violations cannot be deleted in real mode.
• code, severity, message must be present.

---

9. Entity: ComplianceReport

Immutable result derived from a completed run.

Fields

Field	Type	Required	Description
id	string	Yes	Report identifier.
run_id	string	Yes	Source compliance run.
candidate_id	string	Yes	Candidate checked by this run.
final_status	string	Yes	Final outcome.
summary_json	object	Yes	Structured summary of stages and violations.
generated_at	datetime	Yes	Report generation time.
immutable	boolean	Yes	Must be true.

---

10. Entity: ApprovalDecision

Approval or rejection bound to a candidate and report.

Fields

Field	Type	Required	Description
id	string	Yes	Decision identifier.
candidate_id	string	Yes	Candidate being decided.
report_id	string	Yes	Report used as approval basis.
decision	string	Yes	APPROVED or REJECTED.
decided_by	string	Yes	Actor making the decision.
decided_at	datetime	Yes	Decision timestamp.
comment	string	No	Optional operator note.

---

11. Entity: PublicationRecord

Publication or revocation record bound to a candidate.

Fields

Field	Type	Required	Description
id	string	Yes	Publication identifier.
candidate_id	string	Yes	Published candidate.
report_id	string	Yes	Approved report used as basis.
published_by	string	Yes	Publishing actor.
published_at	datetime	Yes	Publish time.
target_channel	string	Yes	Target release channel.
publication_ref	string	No	External publish reference.
status	string	Yes	Publication status label.

---

12. Entity: CandidateOverviewDTO

Read model used by CLI, TUI and API to show current candidate state.

Fields

Field	Type	Required	Description
candidate_id	string	Yes	Candidate identifier.
version	string	Yes	Candidate version.
source_snapshot_ref	string	Yes	Source snapshot ref.
status	string	Yes	Current lifecycle status.
latest_manifest_id	string	No	Latest manifest identifier.
latest_manifest_digest	string	No	Latest manifest digest.
latest_run_id	string	No	Latest run identifier.
latest_run_status	string	No	Latest run execution status.
latest_report_id	string	No	Latest report identifier.
latest_report_final_status	string	No	Latest report final status.
latest_policy_snapshot_id	string	No	Latest policy snapshot identifier.
latest_policy_version	string	No	Latest policy version used for latest run.
latest_registry_snapshot_id	string	No	Latest registry snapshot identifier.
latest_registry_version	string	No	Latest registry version used for latest run.
latest_approval_decision	string	No	Latest approval decision affecting publication gate.
latest_publication_id	string	No	Latest publication identifier.
latest_publication_status	string	No	Latest publication status.

---

13. Entity: ComplianceRunDTO

Read model for run status tracking.

Fields

Field	Type	Required	Description
run_id	string	Yes	Run identifier.
candidate_id	string	Yes	Candidate identifier.
status	string	Yes	Run execution status.
final_status	string	No	Final compliance result.
report_id	string	No	Final report identifier.
task_id	string	Yes	Linked task identifier.

---

14. Entity: ReportDTO

Compact report view used by interfaces.

Fields

Field	Type	Required	Description
report_id	string	Yes	Report identifier.
candidate_id	string	Yes	Candidate identifier.
final_status	string	Yes	Final report result.
policy_version	string	Yes	Policy version used for the report.
manifest_digest	string	Yes	Manifest digest used for the run.
violation_count	integer	Yes	Number of violations.
generated_at	datetime	Yes	Report generation time.

---

15. Relationships

• ReleaseCandidate 1 -> N CandidateArtifact
• ReleaseCandidate 1 -> N DistributionManifest
• ReleaseCandidate 1 -> N ComplianceRun
• ComplianceRun 1 -> N ComplianceStageRun
• ComplianceRun 1 -> N ComplianceViolation
• ComplianceRun 1 -> 1 ComplianceReport (for terminal runs that produce a report)
• ComplianceReport 1 -> N ApprovalDecision (history allowed, latest valid decision governs)
• ReleaseCandidate 1 -> N PublicationRecord
• CleanPolicySnapshot 1 -> 1 SourceRegistrySnapshot

16. Invariants

• Policy, registry, manifest, report, approval and publication snapshots are immutable after creation.
• Real mode compliance evidence is append-only and not user-deletable.
• APPROVED requires a valid PASSED report.
• PUBLISHED requires a valid approval.
• REJECTED is modeled as an immutable latest approval decision, not as a separate candidate lifecycle state.
• Demo namespace never shares identifiers or historical storage with real mode.

17. Scale Assumptions

• Candidate histories may accumulate multiple manifests and multiple compliance runs per release.
• A single run may produce many violations and stage details, so read models should not require loading all artifacts for each overview request.
• Most interface reads use latest-only summary views, while audit and compliance screens require full history retrieval.