Complete deterministic Phase 6 reporting

Author: chriswayneh

backend/app/api.py

@@ -2,7 +2,7 @@
 
 from fastapi import APIRouter, Depends, HTTPException, Query, Response, status
 from fastapi.encoders import jsonable_encoder
-from fastapi.responses import JSONResponse
+from fastapi.responses import FileResponse, JSONResponse
 from sqlalchemy import func, select
 from sqlalchemy.orm import Session
 
@@ -19,6 +19,7 @@
 from app.intelligence import runner as intelligence_runner
 from app.inventory import get_asset, list_assets, list_observations, list_services
 from app.models import Asset, Dockyard, EvidenceRecord, Finding, FindingEvidence, Service
+from app.reporting import runner as reporting_runner
 from app.schemas import (
     AdapterRead,
     AssetDetailRead,
@@ -45,6 +46,8 @@
     ObservationRead,
     ProfileRead,
     RedPathGraphRead,
+    ReportCreate,
+    ReportRunRead,
     ScopeEntryCreate,
     ScopeEntryRead,
     ScopeEvaluateRequest,
@@ -453,6 +456,90 @@ def approve_intelligence_run(
         raise HTTPException(status_code=code, detail=message) from error
 
 
+@router.get("/dockyards/{dockyard_id}/reports", response_model=list[ReportRunRead])
+def read_reports(
+    dockyard_id: int, limit: int = ListLimit, session: Session = Depends(get_session)
+) -> list[ReportRunRead]:
+    require_dockyard(dockyard_id, session)
+    return reporting_runner.list_runs(session, dockyard_id, limit)
+
+
+@router.post(
+    "/dockyards/{dockyard_id}/reports",
+    response_model=ReportRunRead,
+    status_code=status.HTTP_201_CREATED,
+)
+def create_report(
+    dockyard_id: int,
+    payload: ReportCreate,
+    session: Session = Depends(get_session),
+) -> ReportRunRead:
+    """Snapshot all retained state; the empty request chooses no target or path."""
+    require_dockyard(dockyard_id, session)
+    try:
+        return reporting_runner.start_report(session, dockyard_id)
+    except reporting_runner.ReportRejected as error:
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=str(error)) from error
+
+
+@router.get("/dockyards/{dockyard_id}/reports/{run_id}", response_model=ReportRunRead)
+def read_report(
+    dockyard_id: int, run_id: int, session: Session = Depends(get_session)
+) -> ReportRunRead:
+    require_dockyard(dockyard_id, session)
+    run = reporting_runner.get_run(session, dockyard_id, run_id)
+    if run is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Report run not found")
+    return run
+
+
+def _report_artifact(dockyard_id: int, run_id: int, artifact: str, session: Session):
+    require_dockyard(dockyard_id, session)
+    run = reporting_runner.get_run(session, dockyard_id, run_id)
+    if run is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Report run not found")
+    try:
+        return reporting_runner.artifact_path(run, artifact)
+    except reporting_runner.ReportRejected as error:
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=str(error)) from error
+
+
+@router.get("/dockyards/{dockyard_id}/reports/{run_id}/technical")
+def read_technical_report(
+    dockyard_id: int, run_id: int, session: Session = Depends(get_session)
+):
+    path = _report_artifact(dockyard_id, run_id, "technical", session)
+    return FileResponse(path, media_type="text/markdown; charset=utf-8")
+
+
+@router.get("/dockyards/{dockyard_id}/reports/{run_id}/executive")
+def read_executive_report(
+    dockyard_id: int, run_id: int, session: Session = Depends(get_session)
+):
+    path = _report_artifact(dockyard_id, run_id, "executive", session)
+    return FileResponse(path, media_type="text/markdown; charset=utf-8")
+
+
+@router.get("/dockyards/{dockyard_id}/reports/{run_id}/manifest")
+def read_report_manifest(
+    dockyard_id: int, run_id: int, session: Session = Depends(get_session)
+):
+    path = _report_artifact(dockyard_id, run_id, "manifest", session)
+    return FileResponse(path, media_type="application/json")
+
+
+@router.get("/dockyards/{dockyard_id}/reports/{run_id}/dockpack")
+def download_dockpack(
+    dockyard_id: int, run_id: int, session: Session = Depends(get_session)
+):
+    path = _report_artifact(dockyard_id, run_id, "dockpack", session)
+    return FileResponse(
+        path,
+        media_type="application/zip",
+        filename=f"reddock-dockyard-{dockyard_id}-report-{run_id}.dockpack.zip",
+    )
+
+
 @router.get("/dockyards/{dockyard_id}/validations", response_model=list[ValidationRunRead])
 def read_validations(
     dockyard_id: int, limit: int = ListLimit, session: Session = Depends(get_session)

backend/app/config.py

@@ -9,8 +9,8 @@ class Settings(BaseModel):
     """Runtime settings kept intentionally small for the local foundation."""
 
     app_name: str = "RedDock"
-    version: str = "0.6.0"
-    phase: str = "Phase 5 — Intelligence"
+    version: str = "0.7.0"
+    phase: str = "Phase 6 — Reporting"
     database_url: str = "sqlite:///./data/reddock.db"
     evidence_dir: str = "./data/evidence"
     nmap_path: str | None = None
@@ -63,6 +63,16 @@ class Settings(BaseModel):
     max_intelligence_input_bytes: int = 512 * 1024
     max_intelligence_runs_per_dockyard: int = 200
 
+    # Reporting packages only database-referenced retained files. Fixed limits
+    # keep a local export from becoming an unbounded filesystem copy operation.
+    max_report_runs_per_dockyard: int = 200
+    max_report_assets: int = 2_000
+    max_report_services: int = 20_000
+    max_report_findings: int = 5_000
+    max_report_evidence_links: int = 20_000
+    max_report_evidence_files: int = 2_000
+    max_dockpack_bytes: int = 64 * 1024 * 1024
+
 
 @lru_cache
 def get_settings() -> Settings:

backend/app/evidence.py

@@ -15,6 +15,7 @@
     evidence/<dockyard-id>/validation/<validation-run-id>/
     evidence/<dockyard-id>/correlation/<correlation-run-id>/
     evidence/<dockyard-id>/intelligence/<intelligence-run-id>/
+    evidence/<dockyard-id>/reporting/<report-run-id>/
 """
 
 import json
@@ -35,6 +36,7 @@
 VALIDATION_SCOPE = "validation"
 CORRELATION_SCOPE = "correlation"
 INTELLIGENCE_SCOPE = "intelligence"
+REPORTING_SCOPE = "reporting"
 
 _ARTIFACT_NAME = re.compile(r"^[a-z0-9][a-z0-9._-]{0,63}$")
 #: A closed set, so a scope can never become a path fragment an operator chose.
@@ -45,6 +47,7 @@
         VALIDATION_SCOPE,
         CORRELATION_SCOPE,
         INTELLIGENCE_SCOPE,
+        REPORTING_SCOPE,
     }
 )
 
@@ -128,6 +131,30 @@ def write_metadata(
             scope,
         )
 
+    def write_export(
+        self,
+        dockyard_id: int,
+        run_id: int,
+        name: str,
+        media_type: str,
+        content: bytes,
+    ) -> StoredArtifact:
+        """Write one complete bounded Phase 6 export without evidence truncation."""
+        if not _ARTIFACT_NAME.match(name):
+            raise EvidenceError(f"Unsafe evidence artifact name: {name!r}")
+        if len(content) > get_settings().max_dockpack_bytes:
+            raise EvidenceError("Reporting artifact exceeds the fixed DockPack size limit")
+        return self._write(
+            dockyard_id,
+            run_id,
+            "export",
+            f"raw/{name}",
+            media_type,
+            content,
+            False,
+            REPORTING_SCOPE,
+        )
+
     def _write(
         self,
         dockyard_id: int,

backend/app/main.py

@@ -13,6 +13,7 @@
 from app.detection.runner import recover_interrupted_runs as recover_interrupted_detections
 from app.discovery.runner import recover_interrupted_runs
 from app.intelligence.runner import recover_interrupted_runs as recover_interrupted_intelligence
+from app.reporting.runner import recover_interrupted_runs as recover_interrupted_reports
 
 STATIC_DIRECTORY = Path(__file__).resolve().parents[2] / "static"
 
@@ -30,6 +31,7 @@ async def lifespan(_: FastAPI):
         detections = recover_interrupted_detections(session)
         correlations = recover_interrupted_correlations(session)
         intelligence = recover_interrupted_intelligence(session)
+        reports = recover_interrupted_reports(session)
     if interrupted:
         logger.warning("Marked %s discovery run(s) as interrupted by restart", interrupted)
     if detections:
@@ -38,6 +40,8 @@ async def lifespan(_: FastAPI):
         logger.warning("Marked %s correlation run(s) as interrupted by restart", correlations)
     if intelligence:
         logger.warning("Marked %s intelligence run(s) as interrupted by restart", intelligence)
+    if reports:
+        logger.warning("Marked %s report run(s) as interrupted by restart", reports)
     yield
 
 

backend/app/models.py

@@ -549,3 +549,33 @@ class IntelligenceRun(Base):
     approved_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
     started_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
     completed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+
+
+class ReportRun(Base):
+    """One immutable, reproducible reporting snapshot and DockPack export.
+
+    Report artifacts are derived only from stored database state and retained
+    evidence. The database keeps their hashes and summary rather than mutable
+    report bodies; downloads are re-verified against these hashes.
+    """
+
+    __tablename__ = "report_runs"
+    __table_args__ = (Index("ix_report_dockyard_status", "dockyard_id", "status"),)
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    dockyard_id: Mapped[int] = mapped_column(
+        ForeignKey("dockyards.id", ondelete="CASCADE"), index=True, nullable=False
+    )
+    status: Mapped[str] = mapped_column(String(16), nullable=False)
+    report_schema: Mapped[str] = mapped_column(String(32), nullable=False)
+    snapshot_sha256: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    technical_sha256: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    executive_sha256: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    manifest_sha256: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    dockpack_sha256: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    dockpack_bytes: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    evidence_path: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    source_counts: Mapped[dict | None] = mapped_column(JSON, nullable=True)
+    error: Mapped[str | None] = mapped_column(String(500), nullable=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
+    completed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)

backend/app/reporting/__init__.py

@@ -0,0 +1 @@
+"""Phase 6 deterministic reports and portable, evidence-linked DockPacks."""