semantics

backend/src/services/clean_release/approval_service.py

@@ -5,6 +5,10 @@
 # @RELATION DEPENDS_ON -> [CleanReleaseModels]
 # @RELATION DEPENDS_ON -> [AuditService]
 # @INVARIANT: Approval is allowed only for PASSED report bound to candidate; decisions are append-only.
+# @PRE: Report with PASSED final_status exists for candidate
+# @POST: Approval decision appended; candidate lifecycle advanced
+# @SIDE_EFFECT: Persists approval decisions, transitions candidate status
+# @DATA_CONTRACT: ApprovalRequest -> ApprovalDecision
 
 from __future__ import annotations
 
@@ -207,4 +211,4 @@ def reject_candidate(
 
 # #endregion reject_candidate
 
-# #endregion backend.src.services.clean_release.approval_service
+# #endregion ApprovalService

backend/src/services/clean_release/artifact_catalog_loader.py

@@ -1,8 +1,10 @@
-# #region ArtifactCatalogLoader [C:3] [TYPE Module] [SEMANTICS pydantic, clean-release, artifact, catalog, manifest]
+# #region ArtifactCatalogLoader [C:5] [TYPE Module] [SEMANTICS pydantic, clean-release, artifact, catalog, manifest]
 # @BRIEF Load bootstrap artifact catalogs for clean release real-mode flows.
 # @LAYER: Domain
 # @RELATION DEPENDS_ON -> [CleanReleaseModels]
 # @INVARIANT: Artifact catalog must produce deterministic CandidateArtifact entries with required identity and checksum fields.
+# @SIDE_EFFECT: Reads JSON file from filesystem
+# @DATA_CONTRACT: FilePath -> CandidateArtifact[]
 
 from __future__ import annotations
 
@@ -101,4 +103,4 @@ def load_bootstrap_artifacts(path: str, candidate_id: str) -> list[CandidateArti
 
 # #endregion load_bootstrap_artifacts
 
-# #endregion backend.src.services.clean_release.artifact_catalog_loader
+# #endregion ArtifactCatalogLoader

backend/src/services/clean_release/audit_service.py

@@ -1,8 +1,12 @@
 # #region AuditService [C:3] [TYPE Module] [SEMANTICS clean-release, audit, report, trail, release]
 # @BRIEF Provide lightweight audit hooks for clean release preparation/check/report lifecycle.
-# @LAYER: Infra
+# @LAYER: Infrastructure
 # @RELATION DEPENDS_ON -> [LoggerModule]
 # @INVARIANT: Audit hooks are append-only log actions.
+# @PRE: Logger configured
+# @POST: Audit events appended to log
+# @SIDE_EFFECT: Writes audit events to logger and repository
+# @DATA_CONTRACT: AuditAction -> LogEntry
 
 from __future__ import annotations
 
@@ -114,4 +118,4 @@ def audit_report(
     )
 
 
-# #endregion backend.src.services.clean_release.audit_service
+# #endregion AuditService

backend/src/services/clean_release/candidate_service.py

@@ -103,4 +103,4 @@ def register_candidate(
     return candidate
 # #endregion register_candidate
 
-# #endregion backend.src.services.clean_release.candidate_service
+# #endregion candidate_service

backend/src/services/clean_release/demo_data_service.py

@@ -1,8 +1,10 @@
-# #region DemoDataService [C:3] [TYPE Module] [SEMANTICS clean-release, demo, seed, fixture]
+# #region DemoDataService [C:5] [TYPE Module] [SEMANTICS clean-release, demo, seed, fixture]
 # @BRIEF Provide deterministic namespace helpers and isolated in-memory repository creation for demo and real modes.
 # @LAYER: Domain
 # @RELATION DEPENDS_ON -> [RepositoryRelations]
 # @INVARIANT: Demo and real namespaces must never collide for generated physical identifiers.
+# @SIDE_EFFECT: Writes demo entities to repository
+# @DATA_CONTRACT: SeedConfig -> DemoEntities
 
 from __future__ import annotations
 

backend/src/services/clean_release/manifest_builder.py

@@ -1,8 +1,10 @@
-# #region ManifestBuilder [C:3] [TYPE Module] [SEMANTICS clean-release, manifest, build, artifact, catalog]
+# #region ManifestBuilder [C:5] [TYPE Module] [SEMANTICS clean-release, manifest, build, artifact, catalog]
 # @BRIEF Build deterministic distribution manifest from classified artifact input.
 # @LAYER: Domain
 # @RELATION DEPENDS_ON -> [CleanReleaseModels]
 # @INVARIANT: Equal semantic artifact sets produce identical deterministic hash values.
+# @SIDE_EFFECT: Computes hash of artifact set
+# @DATA_CONTRACT: ArtifactSet -> Manifest
 
 from __future__ import annotations
 

backend/src/services/clean_release/preparation_service.py

@@ -1,10 +1,12 @@
-# #region PreparationService [C:3] [TYPE Module] [SEMANTICS clean-release, prepare, validate, policy, manifest]
+# #region PreparationService [C:5] [TYPE Module] [SEMANTICS clean-release, prepare, validate, policy, manifest]
 # @BRIEF Prepare release candidate by policy evaluation and deterministic manifest creation.
 # @LAYER: Domain
 # @RELATION DEPENDS_ON -> [PolicyEngine]
 # @RELATION DEPENDS_ON -> [ManifestBuilder]
 # @RELATION DEPENDS_ON -> [RepositoryRelations]
 # @INVARIANT: Candidate preparation always persists manifest and candidate status deterministically.
+# @SIDE_EFFECT: Persists candidate and manifest
+# @DATA_CONTRACT: PrepareRequest -> PrepareResult
 
 from __future__ import annotations
 

backend/src/services/clean_release/publication_service.py

@@ -209,4 +209,4 @@ def revoke_publication(
 
 # #endregion revoke_publication
 
-# #endregion backend.src.services.clean_release.publication_service
+# #endregion PublicationService

backend/src/services/clean_release/repository.py

@@ -1,8 +1,12 @@
-# #region RepositoryRelations [C:3] [TYPE Module] [SEMANTICS pydantic, clean-release, repository, relations, release]
+# #region RepositoryRelations [C:5] [TYPE Module] [SEMANTICS pydantic, clean-release, repository, relations, release]
 # @BRIEF Provide repository adapter for clean release entities with deterministic access methods.
-# @LAYER: Infra
+# @LAYER: Infrastructure
 # @RELATION DEPENDS_ON -> [CleanReleaseModels]
 # @INVARIANT: Repository operations are side-effect free outside explicit save/update calls.
+# @PRE: In-memory storage initialized
+# @POST: Repository operations exported
+# @SIDE_EFFECT: Modifies in-memory state on save/update
+# @DATA_CONTRACT: Entity -> RepositoryOperation
 
 from __future__ import annotations
 

backend/src/services/clean_release/source_isolation.py

@@ -1,8 +1,12 @@
-# #region SourceIsolation [C:3] [TYPE Module] [SEMANTICS clean-release, source, isolation, validate, resource]
+# #region SourceIsolation [C:5] [TYPE Module] [SEMANTICS clean-release, source, isolation, validate, resource]
 # @BRIEF Validate that all resource endpoints belong to the approved internal source registry.
 # @LAYER: Domain
 # @RELATION DEPENDS_ON -> [CleanReleaseModels]
 # @INVARIANT: Any endpoint outside enabled registry entries is treated as external-source violation.
+# @PRE: Source registry configured
+# @POST: Source isolation violations identified
+# @SIDE_EFFECT: None (read-only check)
+# @DATA_CONTRACT: SourceURL -> ViolationReport
 
 from __future__ import annotations
 

backend/src/services/clean_release/stages/__init__.py

@@ -1,9 +1,11 @@
-# #region ComplianceStages [C:3] [TYPE Module] [SEMANTICS clean-release, compliance, stage, package]
+# #region ComplianceStages [C:5] [TYPE Module] [SEMANTICS clean-release, compliance, stage, package]
 # @BRIEF Define compliance stage order and helper functions for deterministic run-state evaluation.
 # @LAYER: Domain
 # @RELATION DEPENDS_ON -> [CleanReleaseModels]
 # @RELATION DEPENDS_ON -> [ComplianceStageBase]
 # @INVARIANT: Stage order remains deterministic for all compliance runs.
+# @SIDE_EFFECT: Registers compliance stages
+# @DATA_CONTRACT: StagePipeline -> ComplianceResult
 
 from __future__ import annotations
 

backend/src/services/clean_release/stages/base.py

@@ -1,9 +1,11 @@
-# #region ComplianceStageBase [C:3] [TYPE Module] [SEMANTICS pydantic, clean-release, stage, compliance, context]
+# #region ComplianceStageBase [C:5] [TYPE Module] [SEMANTICS pydantic, clean-release, stage, compliance, context]
 # @BRIEF Define shared contracts and helpers for pluggable clean-release compliance stages.
 # @LAYER: Domain
 # @RELATION DEPENDS_ON -> [CleanReleaseModels]
 # @RELATION DEPENDS_ON -> [LoggerModule]
 # @INVARIANT: Stage execution is deterministic for equal input context.
+# @SIDE_EFFECT: None (deterministic execution)
+# @DATA_CONTRACT: Context -> StageResult
 
 from __future__ import annotations
 

backend/src/services/clean_release/stages/data_purity.py

@@ -1,9 +1,11 @@
-# #region data_purity [C:3] [TYPE Module] [SEMANTICS clean-release, data, purity, validate, manifest]
+# #region data_purity [C:5] [TYPE Module] [SEMANTICS clean-release, data, purity, validate, manifest]
 # @BRIEF Evaluate manifest purity counters and emit blocking violations for prohibited artifacts.
 # @LAYER: Domain
 # @RELATION IMPLEMENTS -> [ComplianceStage]
 # @RELATION DEPENDS_ON -> [ComplianceStageBase]
 # @INVARIANT: prohibited_detected_count > 0 always yields BLOCKED stage decision.
+# @SIDE_EFFECT: None (read-only validation)
+# @DATA_CONTRACT: Manifest -> DataPurityVerdict
 
 from __future__ import annotations
 

backend/src/services/clean_release/stages/internal_sources_only.py

@@ -1,9 +1,11 @@
-# #region internal_sources_only [C:3] [TYPE Module] [SEMANTICS clean-release, internal, source, validate]
+# #region internal_sources_only [C:5] [TYPE Module] [SEMANTICS clean-release, internal, source, validate]
 # @BRIEF Verify manifest-declared sources belong to trusted internal registry allowlist.
 # @LAYER: Domain
 # @RELATION IMPLEMENTS -> [ComplianceStage]
 # @RELATION DEPENDS_ON -> [ComplianceStageBase]
 # @INVARIANT: Any source host outside allowed_hosts yields BLOCKED decision with at least one violation.
+# @SIDE_EFFECT: None (read-only validation)
+# @DATA_CONTRACT: Sources -> SourceViolationReport
 
 from __future__ import annotations
 

backend/src/services/clean_release/stages/manifest_consistency.py

@@ -1,9 +1,11 @@
-# #region manifest_consistency [C:3] [TYPE Module] [SEMANTICS clean-release, manifest, consistency, validate]
+# #region manifest_consistency [C:5] [TYPE Module] [SEMANTICS clean-release, manifest, consistency, validate]
 # @BRIEF Ensure run is bound to the exact manifest snapshot and digest used at run creation time.
 # @LAYER: Domain
 # @RELATION IMPLEMENTS -> [ComplianceStage]
 # @RELATION DEPENDS_ON -> [ComplianceStageBase]
 # @INVARIANT: Digest mismatch between run and manifest yields ERROR with blocking violation evidence.
+# @SIDE_EFFECT: None (read-only validation)
+# @DATA_CONTRACT: RunData -> ConsistencyVerdict
 
 from __future__ import annotations
 

backend/src/services/clean_release/stages/no_external_endpoints.py

@@ -1,9 +1,11 @@
-# #region no_external_endpoints [C:3] [TYPE Module] [SEMANTICS clean-release, endpoint, validate, manifest, compliance]
+# #region no_external_endpoints [C:5] [TYPE Module] [SEMANTICS clean-release, endpoint, validate, manifest, compliance]
 # @BRIEF Block manifest payloads that expose external endpoints outside trusted schemes and hosts.
 # @LAYER: Domain
 # @RELATION IMPLEMENTS -> [ComplianceStage]
 # @RELATION DEPENDS_ON -> [ComplianceStageBase]
 # @INVARIANT: Endpoint outside allowed scheme/host always yields BLOCKED stage decision.
+# @SIDE_EFFECT: None (read-only validation)
+# @DATA_CONTRACT: Endpoints -> EndpointViolationReport
 
 from __future__ import annotations
 

backend/src/services/git/_remote_providers.py

@@ -50,47 +50,8 @@ class GitServiceGithubMixin:
                 pass
             raise HTTPException(status_code=response.status_code, detail=f"GitHub API error: {detail}")
         return response.json()
-    # endregion create_github_repository
-
-    # region create_github_pull_request [TYPE Function]
-    # @PURPOSE: Create pull request in GitHub or GitHub Enterprise.
-    # @PRE: Config and remote URL are valid.
-    # @POST: Returns normalized PR metadata.
-    # @RETURN: Dict[str, Any]
-    async def create_github_pull_request(
-        self, server_url: str, pat: str, remote_url: str, from_branch: str, to_branch: str,
-        title: str, description: str | None = None, draft: bool = False,
-    ) -> dict[str, Any]:
-        identity = self._parse_remote_repo_identity(remote_url)
-        base_url = self._normalize_git_server_url(server_url)
-        if "github.com" in base_url:
-            api_url = f"https://api.github.com/repos/{identity['namespace']}/{identity['repo']}/pulls"
-        else:
-            api_url = f"{base_url}/api/v3/repos/{identity['namespace']}/{identity['repo']}/pulls"
-        headers = {
-            "Authorization": f"token {pat.strip()}",
-            "Content-Type": "application/json",
-            "Accept": "application/vnd.github+json",
-        }
-        payload = {
-            "title": title, "head": from_branch, "base": to_branch,
-            "body": description or "", "draft": bool(draft),
-        }
-        try:
-            response = await self._http_client.post(api_url, headers=headers, json=payload)
-        except Exception as e:
-            raise HTTPException(status_code=503, detail=f"GitHub API is unavailable: {e!s}")
-        if response.status_code >= 400:
-            detail = response.text
-            try:
-                detail = response.json().get("message") or detail
-            except Exception:
-                pass
-            raise HTTPException(status_code=response.status_code, detail=f"GitHub API error: {detail}")
-        data = response.json()
-        return {"id": data.get("number") or data.get("id"), "url": data.get("html_url") or data.get("url"), "status": data.get("state") or "open"}
     # endregion create_github_pull_request
-
+# #endregion GitServiceGithubMixin
 
 # #region GitServiceGitlabMixin [C:3] [TYPE Class]
 # @BRIEF Mixin providing GitLab API operations for GitService.
@@ -176,4 +137,3 @@ class GitServiceGitlabMixin:
     # endregion create_gitlab_merge_request
 # #endregion GitServiceGitlabMixin
 # #endregion GitServiceRemoteMixin
-# #endregion GitServiceRemoteMixin

backend/src/services/mapping_service.py

@@ -1,7 +1,7 @@
-# #region mapping_service [C:3] [TYPE Module] [SEMANTICS mapping, database, superset, fuzzy, suggestion]
+# #region mapping_service [C:5] [TYPE Module] [SEMANTICS mapping, database, superset, fuzzy, suggestion]
 #
 # @BRIEF Orchestrates database fetching and fuzzy matching suggestions.
-# @LAYER:     Service
+# @LAYER: Service
 # @PRE: source/target environment identifiers are provided by caller.
 # @POST: Exposes stateless mapping suggestion orchestration over configured environments.
 # @SIDE_EFFECT: Performs remote metadata reads through Superset API clients.

backend/src/services/reports/__tests__/test_report_normalizer.py

@@ -2,7 +2,7 @@
 # @SEMANTICS: tests, reports, normalizer, fallback
 # @PURPOSE: Validate unknown task type fallback and partial payload normalization behavior.
 # @RELATION: TESTS ->[normalize_report:Function]
-# @LAYER: Domain (Tests)
+# @LAYER: Domain
 # @INVARIANT: Unknown plugin types are mapped to canonical unknown task type.
 
 from datetime import datetime

backend/src/services/resource_service.py

@@ -1,11 +1,13 @@
-# #region ResourceServiceModule [C:3] [TYPE Module] [SEMANTICS resource, git, task, status, superset]
+# #region ResourceServiceModule [C:5] [TYPE Module] [SEMANTICS resource, git, task, status, superset]
 # @BRIEF Shared service for fetching resource data with Git status and task status
-# @LAYER:     Service
+# @LAYER: Service
 # @RELATION DEPENDS_ON -> [SupersetClient]
 # @RELATION DEPENDS_ON -> [TaskManagerPackage]
 # @RELATION DEPENDS_ON -> [TaskManagerModels]
 # @RELATION DEPENDS_ON -> [GitService]
 # @INVARIANT: All resources include metadata about their current state
+# @SIDE_EFFECT: Queries multiple backends for status
+# @DATA_CONTRACT: ResourceQuery -> ResourceStatusSummary
 
 from datetime import UTC, datetime
 from typing import Any