fix(notice): honour the ?scan_id= release pin on NOTICE downloads

Every other detail read accepts the release-snapshot anchor; NOTICE
resolved the latest succeeded scan internally, so the NOTICE for an
already-shipped release became unreachable once a newer scan succeeded.
The download-history row now records the scan actually rendered instead
of re-resolving "latest".

Author: haksungjang

apps/backend/api/v1/obligations.py

@@ -69,7 +69,7 @@
     get_project,
 )
 from services.report_download_service import record_report_download
-from services.scan_resolution import SnapshotScanNotFound, latest_succeeded_scan_id
+from services.scan_resolution import SnapshotScanNotFound
 
 router = APIRouter(prefix="/v1", tags=["obligations"])
 log = structlog.get_logger("obligations.api")
@@ -280,7 +280,7 @@ def _format_content_disposition(project_name: str, ext: str) -> str:
 
 @router.get(
     "/projects/{project_id}/notice",
-    summary="Compose a NOTICE attribution body for the project's latest scan",
+    summary="Compose a NOTICE attribution body for the project's latest scan (or a pinned one)",
     responses={
         200: {
             "description": (
@@ -297,8 +297,9 @@ def _format_content_disposition(project_name: str, ext: str) -> str:
         },
         404: {
             "description": (
-                "Project does not exist, or the caller is not a member of the "
-                "project's team (existence-hidden)."
+                "Project does not exist, the caller is not a member of the "
+                "project's team (existence-hidden), or a pinned ``scan_id`` is "
+                "not a succeeded scan of this project."
             )
         },
         429: {
@@ -311,6 +312,17 @@ def _format_content_disposition(project_name: str, ext: str) -> str:
 async def get_project_notice_endpoint(
     request: Request,
     project_id: uuid.UUID,
+    scan_id: uuid.UUID | None = Query(
+        default=None,
+        description=(
+            "Optional release-snapshot anchor. When given, compose the NOTICE "
+            "from this SPECIFIC succeeded scan instead of the project's latest "
+            "succeeded scan — this is how the attribution document for an "
+            "already-shipped release stays retrievable after a newer scan "
+            "succeeds. Must belong to this project and be succeeded, else 404. "
+            "Omit for the default latest-succeeded behaviour."
+        ),
+    ),
     fmt: str = Query(
         default="text",
         alias="format",
@@ -336,7 +348,10 @@ async def get_project_notice_endpoint(
             project_id=project_id,
             actor=actor,
             fmt=fmt,
+            snapshot_scan_id=scan_id,
         )
+    except SnapshotScanNotFound:
+        return _problem_for_snapshot_not_found(request)
     except (ObligationError, ProjectError) as exc:
         return _problem_for_obligation_error(request, exc)
 
@@ -370,9 +385,11 @@ async def get_project_notice_endpoint(
     # already enforced existence-hide team membership, so reaching this point
     # means the actor is allowed to read this project. We load the project for
     # its ``team_id`` (denormalised onto every history row so admin / team-wide
-    # queries do not need a join) and resolve the latest succeeded scan as the
-    # snapshot anchor, mirroring what the NOTICE service rendered against.
-    # Best-effort: ANY DB error inside the helper is logged + swallowed.
+    # queries do not need a join) and record the scan the service actually
+    # rendered against — re-resolving "latest succeeded" here would mislabel a
+    # pinned download, and could even disagree with an unpinned one if a scan
+    # succeeded mid-request. Best-effort: ANY DB error inside the helper is
+    # logged + swallowed.
     body_bytes = (
         payload["body"].encode("utf-8")
         if isinstance(payload["body"], str)
@@ -386,11 +403,10 @@ async def get_project_notice_endpoint(
         # between the two reads). Skip the emit silently — never 5xx.
         project = None
     if project is not None:
-        resolved_scan_id = await latest_succeeded_scan_id(session, project_id)
         await record_report_download(
             session,
             project=project,
-            scan_id=resolved_scan_id,
+            scan_id=payload["scan_id"],
             user=actor,
             report_type="notice",
             fmt=fmt,

apps/backend/services/obligation_service.py

@@ -1239,10 +1239,21 @@ async def generate_notice(
     project_id: uuid.UUID,
     actor: CurrentUser,
     fmt: str = "text",
+    snapshot_scan_id: uuid.UUID | None = None,
 ) -> dict[str, Any]:
     """
     Compose a NOTICE attribution body for the project's latest scan.
 
+    ``snapshot_scan_id`` pins the document to a SPECIFIC succeeded snapshot
+    instead of the latest succeeded scan — the same anchor every other detail
+    read already accepts (obligations / licenses / vulnerabilities / SBOM).
+    Without it, "give me the NOTICE we shipped with 4.0" became impossible the
+    moment a 4.1 scan succeeded: the attribution document a release earned is
+    exactly the artefact that must stay retrievable after the next scan lands.
+    Validated by :func:`services.scan_resolution.resolve_snapshot_scan_id`
+    (cross-project / non-succeeded / nonexistent → :class:`SnapshotScanNotFound`
+    → 404 at the router, so a pinned id cannot probe another project's scans).
+
     Output shape (text format)::
 
         Third-party Licenses for <project_name>
@@ -1300,16 +1311,18 @@ async def generate_notice(
 
     generated_at = datetime.now(tz=UTC)
 
-    # Anchor the NOTICE on the latest SUCCEEDED scan — not
+    # Anchor on the resolved snapshot scan — the pinned ``snapshot_scan_id``
+    # when given, else the latest SUCCEEDED scan; never
     # ``project.latest_scan_id`` (the last *attempted* scan). A failed newest
     # attempt must not erase the attribution document the last good scan earned.
     # See ``services.scan_resolution``.
-    scan_id = await latest_succeeded_scan_id(session, project_id)
+    scan_id = await resolve_snapshot_scan_id(session, project_id, snapshot_scan_id)
     if scan_id is None:
         body = _render_empty_notice(project.name, generated_at, fmt=fmt)
         return {
             "project_id": project.id,
             "project_name": project.name,
+            "scan_id": None,
             "generated_at": generated_at,
             "format": fmt,
             "body": body,
@@ -1345,6 +1358,10 @@ async def generate_notice(
     return {
         "project_id": project.id,
         "project_name": project.name,
+        # The scan this body was actually rendered against. The router reuses it
+        # for the Reports-center history row so the recorded snapshot is the one
+        # the user downloaded, not whatever is latest by the time we log.
+        "scan_id": scan_id,
         "generated_at": generated_at,
         "format": fmt,
         "body": body,

apps/backend/tests/integration/test_release_snapshots_api.py

@@ -487,6 +487,55 @@ async def test_gate_result_anchor_reflects_pinned_snapshot(client) -> None:
     assert pinned.json()["critical_cve_count"] == 2
 
 
+async def test_notice_anchor_pins_older_scan(client) -> None:
+    # The NOTICE is the artefact a shipped release is judged by, so it has to
+    # honour the same pin the tab above it does. Without the anchor, "give me
+    # the NOTICE we shipped with the previous release" stops being answerable
+    # the moment a newer scan succeeds.
+    user, project_id, older, _latest = await _seed_two_snapshot_project(client)
+    headers = _bearer_for(user)
+
+    # Default (latest succeeded): no license findings on that scan at all.
+    default = await client.get(f"/v1/projects/{project_id}/notice", headers=headers)
+    assert default.status_code == 200, default.text
+    assert default.headers["x-notice-license-count"] == "0"
+    assert "GPL-3.0-only" not in default.text
+
+    # Pinned to the OLDER scan: its forbidden license must be credited.
+    pinned = await client.get(
+        f"/v1/projects/{project_id}/notice",
+        headers=headers,
+        params={"scan_id": str(older)},
+    )
+    assert pinned.status_code == 200, pinned.text
+    assert pinned.headers["x-notice-license-count"] == "1"
+    assert "GPL-3.0-only" in pinned.text
+
+
+async def test_notice_anchor_non_succeeded_scan_id_is_404(client) -> None:
+    team, user = await _seed_team_with_user(client)
+    project_id = await _seed_empty_project(client, team_id=team.id)
+    headers = _bearer_for(user)
+    await _seed_succeeded_scan(
+        client, project_id=project_id, created_at=datetime(2026, 5, 20, tzinfo=UTC), n_high=1
+    )
+    failed_scan = await _seed_succeeded_scan(
+        client,
+        project_id=project_id,
+        created_at=datetime(2026, 5, 22, tzinfo=UTC),
+        status="failed",
+    )
+
+    for pinned_scan_id in (failed_scan, uuid.uuid4()):
+        response = await client.get(
+            f"/v1/projects/{project_id}/notice",
+            headers=headers,
+            params={"scan_id": str(pinned_scan_id)},
+        )
+        assert response.status_code == 404, response.text
+        assert response.headers["content-type"].startswith(PROBLEM_JSON)
+
+
 async def test_omitting_scan_id_returns_latest_succeeded(client) -> None:
     user, project_id, older, latest = await _seed_two_snapshot_project(client)
     headers = _bearer_for(user)
@@ -526,6 +575,7 @@ async def test_anchor_idor_other_project_scan_id_is_404(client) -> None:
         f"/v1/projects/{project_id}/obligations",
         f"/v1/projects/{project_id}/gate-result",
         f"/v1/projects/{project_id}/sbom",
+        f"/v1/projects/{project_id}/notice",
     ):
         response = await client.get(
             path, headers=headers, params={"scan_id": str(foreign_scan)}

apps/backend/tests/unit/openapi_endpoints.json

@@ -278,7 +278,8 @@
   "GET /v1/projects/{project_id}/notice": [
     "download",
     "format",
-    "project_id"
+    "project_id",
+    "scan_id"
   ],
   "GET /v1/projects/{project_id}/obligations": [
     "category",

apps/frontend/src/features/projects/api/obligationsApi.ts

@@ -201,6 +201,13 @@ export interface FetchNoticeParams {
   format?: NoticeFormat;
   /** When true, ask the backend to set Content-Disposition: attachment. */
   download?: boolean;
+  /**
+   * Release-snapshot anchor. When the tab is pinned to a past release, the
+   * NOTICE must be composed from that scan too — otherwise the downloaded
+   * attribution document describes the latest scan while the table above it
+   * shows the pinned one.
+   */
+  scanId?: string;
 }
 
 export async function fetchProjectNotice(
@@ -212,6 +219,9 @@ export async function fetchProjectNotice(
     params: {
       format: fmt,
       ...(params.download ? { download: true } : {}),
+      ...(params.scanId != null && params.scanId.length > 0
+        ? { scan_id: params.scanId }
+        : {}),
     },
     responseType: "text",
     transformResponse: [(raw: string) => raw],

apps/frontend/src/features/projects/api/useNotice.ts

@@ -22,6 +22,12 @@ import { safeFilenameToken, triggerBlobDownload } from "@/lib/download";
 
 export interface UseNoticeOptions {
   defaultFormat?: NoticeFormat;
+  /**
+   * Release-snapshot anchor forwarded to the backend. Pass the tab's pinned
+   * scan so the downloaded NOTICE describes the release on screen rather than
+   * whatever scan succeeded most recently.
+   */
+  scanId?: string;
 }
 
 export interface UseNoticeReturn {
@@ -69,6 +75,7 @@ export function useNotice(
         const result = await fetchProjectNotice(projectId, {
           format: fmt,
           download: true,
+          scanId: options.scanId,
         });
         const ext = fmt === "markdown" ? "md" : fmt === "html" ? "html" : "txt";
         const fallbackName = `NOTICE-${safeFilenameToken(projectName ?? projectId)}.${ext}`;
@@ -83,7 +90,7 @@ export function useNotice(
         setIsLoading(false);
       }
     },
-    [projectId, projectName, options.defaultFormat],
+    [projectId, projectName, options.defaultFormat, options.scanId],
   );
 
   return { download, isLoading, error, lastResult };

apps/frontend/src/features/projects/components/ComplianceTab.tsx

@@ -369,6 +369,7 @@ export function ComplianceTab({
       <ComplianceToolbar
         projectId={projectId}
         projectName={projectName}
+        scanId={scanId}
         search={search}
         onSearchChange={setSearch}
         categories={categories}
@@ -491,6 +492,8 @@ interface ComplianceToolbarProps {
   projectId: string;
   /** M-21 — names the downloaded NOTICE file (id fallback when null). */
   projectName: string | null;
+  /** Release-snapshot pin, so the NOTICE matches the grid below it. */
+  scanId?: string;
   search: string;
   onSearchChange: (value: string) => void;
   categories: LicenseCategoryName[];
@@ -506,6 +509,7 @@ interface ComplianceToolbarProps {
 function ComplianceToolbar({
   projectId,
   projectName,
+  scanId,
   search,
   onSearchChange,
   categories,
@@ -626,6 +630,7 @@ function ComplianceToolbar({
       <ComplianceNoticeDownload
         projectId={projectId}
         projectName={projectName}
+        scanId={scanId}
       />
     </div>
   );
@@ -643,13 +648,16 @@ function ComplianceToolbar({
 function ComplianceNoticeDownload({
   projectId,
   projectName,
+  scanId,
 }: {
   projectId: string;
   projectName: string | null;
+  scanId?: string;
 }) {
   const { t } = useTranslation("project_detail");
   const notice = useNotice(projectId, projectName ?? undefined, {
     defaultFormat: "text",
+    scanId,
   });
   const [format, setFormat] = useState<NoticeFormat>("text");
   return (

apps/frontend/src/features/projects/components/ObligationsTab.tsx

@@ -213,7 +213,7 @@ export function ObligationsTab({
   );
 
   const obligations = useObligations(projectId, filters);
-  const notice = useNotice(projectId, projectName ?? undefined);
+  const notice = useNotice(projectId, projectName ?? undefined, { scanId });
 
   const items: ObligationListItem[] = obligations.data?.items ?? [];
   const total = obligations.data?.total ?? 0;

apps/frontend/src/features/projects/components/ReportsTab.tsx

@@ -309,7 +309,11 @@ export function ReportsTab({
               read-only grid and the old ObligationsTab affordance is unrouted,
               so deep-linking there was a dead end. Same direct-download pattern
               as VulnPdfCard. */}
-          <NoticeCard projectId={projectId} projectName={projectName} />
+          <NoticeCard
+            projectId={projectId}
+            projectName={projectName}
+            scanId={scanId}
+          />
           {/* W4-C #21 — SBOM card scrolls to the in-page SBOM section below
               instead of navigating to a separate tab. */}
           <GenerateCard
@@ -580,13 +584,16 @@ function VulnPdfCard({ projectId }: { projectId: string }) {
 function NoticeCard({
   projectId,
   projectName,
+  scanId,
 }: {
   projectId: string;
   projectName?: string | null;
+  scanId?: string;
 }) {
   const { t } = useTranslation("project_detail");
   const notice = useNotice(projectId, projectName ?? undefined, {
     defaultFormat: "text",
+    scanId,
   });
   const [format, setFormat] = useState<NoticeFormat>("text");
   return (