From 27080475c1e7382593a8a7f6f847330403d943b9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?D=C3=A1vid=20Balatoni?= <balcsida@gmail.com>
Date: Tue, 22 Sep 2026 22:30:44 +0200
Subject: [PATCH 1/5] feat(supply-chain): add review-preserving retention and
 document reviews and MCP

Prune snapshots per stream beyond a configurable count while always
keeping the current snapshot and any snapshot referenced by a policy
result, decision, or conclusion; drop unreferenced documents, bounded
failed attempts, and old finished jobs on the scheduler tick; export
enrichment queue depth. Add GRAPHNEST_SUPPLY_CHAIN_RETAIN_SNAPSHOTS to
config, Compose docs, and the Helm chart, and document the review
workflow, policies, MCP tools, and retention in the operations guide,
README, and CHANGELOG.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CHANGELOG.md                                  | 14 ++++
 README.md                                     |  2 +
 cmd/graphnest-server/main.go                  | 12 ++++
 deploy/helm/graphnest/ci/optional-values.yaml |  1 +
 .../helm/graphnest/templates/configmaps.yaml  |  1 +
 deploy/helm/graphnest/tests/render.sh         |  1 +
 deploy/helm/graphnest/values.schema.json      |  3 +-
 deploy/helm/graphnest/values.yaml             |  2 +
 docs/operations.md                            | 54 +++++++++++++++-
 internal/config/config.go                     | 16 ++++-
 internal/config/supply_chain_test.go          |  5 +-
 internal/postgres/supply_chain.go             | 53 +++++++++++++++
 internal/postgres/supply_chain_test.go        | 64 +++++++++++++++++++
 13 files changed, 221 insertions(+), 7 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f3cb196c..c8c31ecc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -45,6 +45,20 @@ the compatibility and migration notes before upgrading.
   (`GET /v1/supply-chain/exports/{id}/derived.spdx.json`) names GraphNest as
   creator, links the preserved original, and carries assessments as comments
   only. Migration 035 adds imports and upload grants.
+- Review workflows: a queue of occurrences needing review, human license
+  conclusions recorded as immutable evidence, scoped approve/reject/exception
+  decisions with optimistic concurrency on the evidence fingerprint
+  (`409 stale_basis`), versioned policies evaluated over the SPDX expression
+  tree with a clearly labelled example fixture and no auto-approval of
+  unknowns, repository-scoped review grants, and an append-only audit trail
+  under `/v1/supply-chain/review/*` and `/v1/supply-chain/policies`.
+  Migration 036 adds the review tables.
+- Read-only MCP tools `search_dependency_inventory`,
+  `find_component_repositories`, and `inspect_component_license` over the
+  same authorized services as REST.
+- Retention for inventory snapshots (`GRAPHNEST_SUPPLY_CHAIN_RETAIN_SNAPSHOTS`)
+  that always preserves the current snapshot and any snapshot referenced by
+  a review record, plus bounded collection and job history.
 
 ## [0.5.0] - 2026-09-18
 
diff --git a/README.md b/README.md
index 8d569ebc..8f1a18cf 100644
--- a/README.md
+++ b/README.md
@@ -213,6 +213,8 @@ What the inventory is and is not:
 - A failed refresh (403, 404, rate limit, malformed or oversized document, outage) records a collection attempt and leaves the last successful snapshot in place; the status reports `collection: failed` alongside the retained inventory.
 - Inventory eligibility is repository authorization alone. It works for repositories with no Zoekt index, no SCIP upload, and no graph enrichment, and inventory work never blocks lexical indexing.
 
+License review is a separate, auditable layer: reviewers with a repository-scoped grant record human conclusions and approve/reject/exception decisions against the exact evidence they saw (a changed evidence fingerprint is refused), versioned policies are evaluated over the SPDX expression tree (the shipped policy is a labelled example, and unknown licensing never auto-approves), and three read-only MCP tools expose the inventory to agents through the same authorization as REST.
+
 SBOMs produced elsewhere (Syft, ORT, or any tool writing SPDX 2.3 JSON or CycloneDX 1.6 JSON) can be imported into separate `import:<subject>:<label>` streams with `POST /v1/supply-chain/imports`; the uploader is recorded apart from the producer the document claims, and a derived SPDX export links back to the preserved original. Portfolio views (`/v1/supply-chain/overview`, `/components`, `/facets`, exports, comparison) aggregate only over the caller's authorized repositories and name every denominator.
 
 Every read resolves the live principal's repository scope before any inventory row is touched; snapshot and job identifiers outside that scope are indistinguishable from missing ones. Manual refresh (`POST /v1/supply-chain/repositories/{id}/refresh`) only enqueues a bounded background job and requires administrator access. The published snapshot is also projected into the existing GitHub-sourced SCIP package mappings; manual mappings are never touched. See [Operations](docs/operations.md#dependencies--licenses-inventory) and [ADR-0017](docs/adr/0017-supply-chain-inventory.md).
diff --git a/cmd/graphnest-server/main.go b/cmd/graphnest-server/main.go
index ed0f3599..6803a7b9 100644
--- a/cmd/graphnest-server/main.go
+++ b/cmd/graphnest-server/main.go
@@ -569,6 +569,18 @@ func startSupplyChain(ctx context.Context, settings config.SupplyChain, store *p
 			if _, err := scheduler.Tick(ctx); err != nil && ctx.Err() == nil {
 				logger.Error("supply chain scheduling failed", "error", err)
 			}
+			if settings.RetainSnapshots > 0 {
+				if _, _, err := store.PruneSupplyChainSnapshots(ctx, settings.RetainSnapshots, 200); err != nil && ctx.Err() == nil {
+					logger.Error("supply chain snapshot retention failed", "error", err)
+				}
+			}
+			if _, _, err := store.PruneSupplyChainHistory(ctx, 50, 30*24*time.Hour); err != nil && ctx.Err() == nil {
+				logger.Error("supply chain history retention failed", "error", err)
+			}
+			if depths, err := store.EnrichmentQueueDepths(ctx); err == nil {
+				metrics.SetSupplyChainQueueDepth("enrichment_queued", depths["queued"])
+				metrics.SetSupplyChainQueueDepth("enrichment_running", depths["running"])
+			}
 		}
 		tick()
 		ticker := time.NewTicker(reconcileInterval)
diff --git a/deploy/helm/graphnest/ci/optional-values.yaml b/deploy/helm/graphnest/ci/optional-values.yaml
index 1f898269..b969bda6 100644
--- a/deploy/helm/graphnest/ci/optional-values.yaml
+++ b/deploy/helm/graphnest/ci/optional-values.yaml
@@ -28,6 +28,7 @@ server:
     workers: 2
     maxDocumentBytes: 33554432
     maxComponents: 60000
+    retainSnapshots: 5
     registries:
       npm: {url: https://npm.example.invalid/, namespaces: ["@acme", "@internal"], allowPrivate: false, token: true}
       nuget: {url: "", namespaces: [], allowPrivate: false}
diff --git a/deploy/helm/graphnest/templates/configmaps.yaml b/deploy/helm/graphnest/templates/configmaps.yaml
index 56fe9b0f..6123ea7d 100644
--- a/deploy/helm/graphnest/templates/configmaps.yaml
+++ b/deploy/helm/graphnest/templates/configmaps.yaml
@@ -73,6 +73,7 @@ data:
   GRAPHNEST_SUPPLY_CHAIN_WORKERS: {{ .Values.server.supplyChain.workers | quote }}
   GRAPHNEST_SUPPLY_CHAIN_MAX_DOCUMENT_BYTES: {{ printf "%d" (int64 .Values.server.supplyChain.maxDocumentBytes) | quote }}
   GRAPHNEST_SUPPLY_CHAIN_MAX_COMPONENTS: {{ .Values.server.supplyChain.maxComponents | quote }}
+  GRAPHNEST_SUPPLY_CHAIN_RETAIN_SNAPSHOTS: {{ .Values.server.supplyChain.retainSnapshots | quote }}
   {{- range $ecosystem, $route := (pick .Values.server.supplyChain.registries "npm" "nuget" "maven") }}
   {{- if $route.url }}
   {{- $prefix := printf "GRAPHNEST_SUPPLY_CHAIN_REGISTRY_%s_" (upper $ecosystem) }}
diff --git a/deploy/helm/graphnest/tests/render.sh b/deploy/helm/graphnest/tests/render.sh
index d1fe3dbd..0c5b35f4 100644
--- a/deploy/helm/graphnest/tests/render.sh
+++ b/deploy/helm/graphnest/tests/render.sh
@@ -384,6 +384,7 @@ require 'GRAPHNEST_SUPPLY_CHAIN_INTERVAL: "12h"' "$tmp/optional.yaml"
 require 'GRAPHNEST_SUPPLY_CHAIN_WORKERS: "2"' "$tmp/optional.yaml"
 require 'GRAPHNEST_SUPPLY_CHAIN_MAX_DOCUMENT_BYTES: "33554432"' "$tmp/optional.yaml"
 require 'GRAPHNEST_SUPPLY_CHAIN_MAX_COMPONENTS: "60000"' "$tmp/optional.yaml"
+require 'GRAPHNEST_SUPPLY_CHAIN_RETAIN_SNAPSHOTS: "5"' "$tmp/optional.yaml"
 require 'GRAPHNEST_SUPPLY_CHAIN_REGISTRY_NPM_URL: "https://npm.example.invalid/"' "$tmp/optional.yaml"
 require 'GRAPHNEST_SUPPLY_CHAIN_REGISTRY_NPM_NAMESPACES: "@acme,@internal"' "$tmp/optional.yaml"
 require 'GRAPHNEST_SUPPLY_CHAIN_REGISTRY_NPM_TOKEN_FILE: /var/run/secrets/graphnest/registries/npm-token' "$tmp/optional.yaml"
diff --git a/deploy/helm/graphnest/values.schema.json b/deploy/helm/graphnest/values.schema.json
index 5097edc3..1f4fcfdc 100644
--- a/deploy/helm/graphnest/values.schema.json
+++ b/deploy/helm/graphnest/values.schema.json
@@ -279,13 +279,14 @@
         "supplyChain": {
           "type": "object",
           "additionalProperties": false,
-          "required": ["enabled", "interval", "workers", "maxDocumentBytes", "maxComponents", "registries"],
+          "required": ["enabled", "interval", "workers", "maxDocumentBytes", "maxComponents", "retainSnapshots", "registries"],
           "properties": {
             "enabled": {"type": "boolean"},
             "interval": {"$ref": "#/definitions/duration"},
             "workers": {"type": "integer", "minimum": 1, "maximum": 8},
             "maxDocumentBytes": {"type": "integer", "minimum": 1, "maximum": 268435456},
             "maxComponents": {"type": "integer", "minimum": 1, "maximum": 500000},
+            "retainSnapshots": {"type": "integer", "minimum": 0, "maximum": 1000},
             "registries": {
               "type": "object",
               "additionalProperties": false,
diff --git a/deploy/helm/graphnest/values.yaml b/deploy/helm/graphnest/values.yaml
index e16cd2dc..fe4ec6e2 100644
--- a/deploy/helm/graphnest/values.yaml
+++ b/deploy/helm/graphnest/values.yaml
@@ -61,6 +61,8 @@ server:
     workers: 1
     maxDocumentBytes: 16777216
     maxComponents: 50000
+    # Snapshots kept per repository stream beyond those referenced by reviews; 0 disables pruning.
+    retainSnapshots: 10
     # License enrichment routes; an ecosystem without a url produces no registry traffic.
     registries:
       npm: {url: "", namespaces: [], allowPrivate: false, token: false}
diff --git a/docs/operations.md b/docs/operations.md
index f5e3c372..824eb301 100644
--- a/docs/operations.md
+++ b/docs/operations.md
@@ -112,6 +112,7 @@ mode; ordinary repositories need no workflow or configuration file.
 | `GRAPHNEST_SUPPLY_CHAIN_WORKERS` | `1` | Collection workers per server process (maximum 8). Each leases one job at a time. |
 | `GRAPHNEST_SUPPLY_CHAIN_MAX_DOCUMENT_BYTES` | `16777216` | Maximum SBOM export size (whole HTTP body, maximum 256 MiB). Larger exports record `too_large`. |
 | `GRAPHNEST_SUPPLY_CHAIN_MAX_COMPONENTS` | `50000` | Maximum packages per document (maximum 500000). |
+| `GRAPHNEST_SUPPLY_CHAIN_RETAIN_SNAPSHOTS` | `10` | Snapshots kept per repository stream in addition to the current one and any snapshot referenced by a policy result, decision, or conclusion; `0` disables pruning. Unreferenced documents are removed with their last snapshot. |
 
 GitHub permissions: the GitHub App needs `Contents: read` on the repository,
 the same permission indexing already requires. The collector calls only
@@ -152,8 +153,13 @@ server. Routes and the page disappear, workers stop, and existing
 `supply_chain_*` tables are left in place. Backup and restore follow the
 PostgreSQL policy for other durable state; documents are stored inline
 (`supply_chain_documents.body`), so database size grows with the number of
-distinct SBOM exports retained. Retention pruning is not implemented in this
-milestone.
+distinct SBOM exports retained. Retention runs on the scheduler tick: it
+keeps the newest `GRAPHNEST_SUPPLY_CHAIN_RETAIN_SNAPSHOTS` snapshots per
+stream plus every snapshot a review record refers to, trims failed collection
+attempts beyond the newest 50 per stream, and removes finished jobs after 30
+days. Repository removal or a revoked installation removes inventory
+visibility immediately through the authorization queries and cascades the
+rows; shared registry evidence (which is not repository data) is retained.
 
 Metrics: `graphnest_supply_chain_collections_total{outcome}`,
 `graphnest_supply_chain_collection_duration_seconds{outcome}`,
@@ -284,6 +290,50 @@ curl --fail-with-body -X POST "https://graphnest.example/v1/supply-chain/imports
   -H "Authorization: Bearer $GRAPHNEST_TOKEN" -H 'Content-Type: application/spdx+json' --data-binary @reports/bom.spdx.json
 ```
 
+### Review workflows and policies
+
+Three record kinds stay separate: a **conclusion** corrects license evidence
+(stored as immutable `human` evidence that overrides, but never deletes,
+automated evidence; disagreement stays visible in the assessment's conflict
+detail); a **policy result** applies one versioned policy to one occurrence;
+a **decision** approves or rejects usage of exact coordinates in one
+repository, or grants an exception with an expiry within a year. Every
+decision records the reviewer, reason, usage context, policy version and
+verdict, and the assessment evidence fingerprint it was made against. A newer
+record supersedes the previous one; nothing is edited, and
+`supply_chain_review_events` is append-only.
+
+Optimistic concurrency: the review queue (`GET /v1/supply-chain/review/queue`)
+hands out each occurrence's `basis` fingerprint, and conclusions/decisions
+must echo it back; a changed basis is refused with `409 stale_basis`, so a
+reviewer cannot approve evidence they have not seen. When evidence changes
+after a decision, or an exception expires, the occurrence returns to the queue
+with the reason and history reports `current_stale`. Re-evaluation runs in the
+background every minute and retains historical results.
+
+Permissions: reading the queue and history needs only repository read access;
+recording conclusions and decisions needs a repository-scoped review grant
+(`PUT /v1/supply-chain/review/grants`, administrator-only; reviewers cannot
+grant themselves) in addition to read access; creating or activating policies
+(`POST /v1/supply-chain/policies`) is administrator-only. No pretend legal
+policy ships: the embedded policy is labelled `kind: example` and is installed
+only on request; `unknown_handling` must be `review_required` or
+`prohibited`, never approve. Policies are evaluated over the SPDX expression
+tree (AND takes the worst operand, OR the best, `WITH` pairs are their own
+terms and are never approved by their base license); an acceptable OR branch
+is reported, but choosing it is a separate recorded decision. Verdicts are
+`approved`, `prohibited`, `review_required`, or `unknown` and are not legal
+advice or release gates.
+
+### MCP tools
+
+With the module enabled, `/mcp` exposes three read-only tools through the
+same authorized services as REST: `search_dependency_inventory`,
+`find_component_repositories`, and `inspect_component_license`. Responses
+include snapshot IDs, provenance, scope, and truncation, and state that
+package, license, and evidence content is untrusted data. There are no
+approval, import, or refresh tools over MCP.
+
 Derived export: `GET /v1/supply-chain/exports/{id}/derived.spdx.json` returns
 an SPDX 2.3 JSON document created by GraphNest that links the preserved
 original by URL and SHA-256 and adds assessments as `licenseComments` only
diff --git a/internal/config/config.go b/internal/config/config.go
index 3004b6d9..4412d3d3 100644
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -97,6 +97,9 @@ type SupplyChain struct {
 	Workers          int
 	MaxDocumentBytes int64
 	MaxComponents    int
+	// RetainSnapshots is how many snapshots per repository stream are kept
+	// beyond those referenced by reviews; 0 disables pruning.
+	RetainSnapshots int
 }
 
 type SCIM struct {
@@ -176,7 +179,7 @@ func Load() (Config, error) {
 }
 
 func loadSupplyChain(databaseURL string) (SupplyChain, error) {
-	settings := SupplyChain{Interval: 24 * time.Hour, Workers: 1, MaxDocumentBytes: 16 << 20, MaxComponents: 50000}
+	settings := SupplyChain{Interval: 24 * time.Hour, Workers: 1, MaxDocumentBytes: 16 << 20, MaxComponents: 50000, RetainSnapshots: 10}
 	switch os.Getenv("GRAPHNEST_SUPPLY_CHAIN") {
 	case "", "false":
 		return settings, nil
@@ -200,7 +203,16 @@ func loadSupplyChain(databaseURL string) (SupplyChain, error) {
 	if err := intValue("GRAPHNEST_SUPPLY_CHAIN_MAX_COMPONENTS", &settings.MaxComponents); err != nil {
 		return SupplyChain{}, err
 	}
-	if settings.Interval < time.Minute || settings.Workers > 8 || settings.MaxDocumentBytes > 256<<20 || settings.MaxComponents > 500000 {
+	switch value := os.Getenv("GRAPHNEST_SUPPLY_CHAIN_RETAIN_SNAPSHOTS"); value {
+	case "":
+	case "0":
+		settings.RetainSnapshots = 0
+	default:
+		if err := intValue("GRAPHNEST_SUPPLY_CHAIN_RETAIN_SNAPSHOTS", &settings.RetainSnapshots); err != nil {
+			return SupplyChain{}, err
+		}
+	}
+	if settings.Interval < time.Minute || settings.Workers > 8 || settings.MaxDocumentBytes > 256<<20 || settings.MaxComponents > 500000 || settings.RetainSnapshots > 1000 {
 		return SupplyChain{}, invalid("supply chain settings exceed server safety caps")
 	}
 	return settings, nil
diff --git a/internal/config/supply_chain_test.go b/internal/config/supply_chain_test.go
index de85b0fc..6de3eaeb 100644
--- a/internal/config/supply_chain_test.go
+++ b/internal/config/supply_chain_test.go
@@ -18,7 +18,7 @@ func TestLoadSupplyChainDisabledByDefault(t *testing.T) {
 		t.Fatalf("supply chain enabled without GRAPHNEST_SUPPLY_CHAIN: %#v", got.SupplyChain)
 	}
 	// Defaults are populated even while disabled so documentation and wiring can rely on them.
-	if got.SupplyChain.Interval != 24*time.Hour || got.SupplyChain.Workers != 1 || got.SupplyChain.MaxDocumentBytes != 16<<20 || got.SupplyChain.MaxComponents != 50000 {
+	if got.SupplyChain.Interval != 24*time.Hour || got.SupplyChain.Workers != 1 || got.SupplyChain.MaxDocumentBytes != 16<<20 || got.SupplyChain.MaxComponents != 50000 || got.SupplyChain.RetainSnapshots != 10 {
 		t.Fatalf("defaults = %#v", got.SupplyChain)
 	}
 }
@@ -31,11 +31,12 @@ func TestLoadSupplyChainEnabledWithOverrides(t *testing.T) {
 	t.Setenv("GRAPHNEST_SUPPLY_CHAIN_WORKERS", "2")
 	t.Setenv("GRAPHNEST_SUPPLY_CHAIN_MAX_DOCUMENT_BYTES", "1048576")
 	t.Setenv("GRAPHNEST_SUPPLY_CHAIN_MAX_COMPONENTS", "1000")
+	t.Setenv("GRAPHNEST_SUPPLY_CHAIN_RETAIN_SNAPSHOTS", "0")
 	got, err := Load()
 	if err != nil {
 		t.Fatal(err)
 	}
-	want := SupplyChain{Enabled: true, Interval: 6 * time.Hour, Workers: 2, MaxDocumentBytes: 1 << 20, MaxComponents: 1000}
+	want := SupplyChain{Enabled: true, Interval: 6 * time.Hour, Workers: 2, MaxDocumentBytes: 1 << 20, MaxComponents: 1000, RetainSnapshots: 0}
 	if got.SupplyChain != want {
 		t.Fatalf("supply chain = %#v, want %#v", got.SupplyChain, want)
 	}
diff --git a/internal/postgres/supply_chain.go b/internal/postgres/supply_chain.go
index 600af1b6..c3c924a6 100644
--- a/internal/postgres/supply_chain.go
+++ b/internal/postgres/supply_chain.go
@@ -669,3 +669,56 @@ func escapeLike(value string) string {
 	}
 	return string(out)
 }
+
+// PruneSupplyChainSnapshots deletes, per repository stream, snapshots beyond
+// the newest keep count, except the stream's latest snapshot and any snapshot
+// referenced by a review record (a policy result, a decision's occurrence, or
+// a conclusion basis through its components). Documents unreferenced by any
+// remaining snapshot are removed afterwards. Returns snapshots and documents
+// deleted. Bounded per call.
+func (s *Store) PruneSupplyChainSnapshots(ctx context.Context, keep int, limit int) (int64, int64, error) {
+	if keep < 1 {
+		keep = 1
+	}
+	tx, err := s.pool.Begin(ctx)
+	if err != nil {
+		return 0, 0, err
+	}
+	defer tx.Rollback(ctx)
+	result, err := tx.Exec(ctx, `delete from supply_chain_snapshots where id in (
+			select snap.id from (
+				select id, repository_id, stream_key, row_number() over (partition by repository_id, stream_key order by id desc) as position from supply_chain_snapshots
+			) snap
+			where snap.position > $1
+			and not exists (select 1 from supply_chain_streams st where st.latest_snapshot_id=snap.id)
+			and not exists (select 1 from supply_chain_policy_results pr where pr.snapshot_id=snap.id)
+			and not exists (select 1 from supply_chain_components c join supply_chain_decisions d on d.repository_id=snap.repository_id and d.ecosystem=coalesce(c.ecosystem, '') and d.namespace=coalesce(c.purl_namespace, '') and d.name=coalesce(c.purl_name, '') and d.version=coalesce(c.purl_version, c.version, '') where c.snapshot_id=snap.id)
+			and not exists (select 1 from supply_chain_components c join supply_chain_conclusions k on k.ecosystem=coalesce(c.ecosystem, '') and k.namespace=coalesce(c.purl_namespace, '') and k.name=coalesce(c.purl_name, '') and k.version=coalesce(c.purl_version, c.version, '') where c.snapshot_id=snap.id)
+			order by snap.id limit $2)`, keep, limit)
+	if err != nil {
+		return 0, 0, err
+	}
+	snapshots := result.RowsAffected()
+	documents, err := tx.Exec(ctx, `delete from supply_chain_documents doc where not exists (select 1 from supply_chain_snapshots snap where snap.document_id=doc.id)
+		and not exists (select 1 from supply_chain_collections col where col.document_id=doc.id and col.snapshot_id is not null)`)
+	if err != nil {
+		return 0, 0, err
+	}
+	return snapshots, documents.RowsAffected(), tx.Commit(ctx)
+}
+
+// PruneSupplyChainHistory bounds collection attempts and finished jobs per
+// stream so operational tables do not grow without limit.
+func (s *Store) PruneSupplyChainHistory(ctx context.Context, keepCollections int, finishedJobsOlderThan time.Duration) (int64, int64, error) {
+	collections, err := s.pool.Exec(ctx, `delete from supply_chain_collections where id in (
+			select id from (select id, row_number() over (partition by repository_id, stream_key order by id desc) as position from supply_chain_collections) ranked
+			where ranked.position > $1) and snapshot_id is null`, keepCollections)
+	if err != nil {
+		return 0, 0, err
+	}
+	jobs, err := s.pool.Exec(ctx, `delete from supply_chain_jobs where state in ('succeeded','failed','cancelled','superseded') and updated_at < now() - $1::interval`, finishedJobsOlderThan)
+	if err != nil {
+		return 0, 0, err
+	}
+	return collections.RowsAffected(), jobs.RowsAffected(), nil
+}
diff --git a/internal/postgres/supply_chain_test.go b/internal/postgres/supply_chain_test.go
index afc09760..cbab53af 100644
--- a/internal/postgres/supply_chain_test.go
+++ b/internal/postgres/supply_chain_test.go
@@ -412,3 +412,67 @@ func TestSupplyChainRepositoryRemovalCascades(t *testing.T) {
 		t.Fatalf("snapshot survived removal: %v", err)
 	}
 }
+
+func TestSupplyChainRetentionPreservesReviewedSnapshots(t *testing.T) {
+	store := migratedStore(t)
+	repositoryID := supplyChainRepository(t, store, 101, "widgets")
+	document := supplyChainFixture(t)
+	var snapshotIDs []int64
+	for index := range 5 {
+		// Each publication must differ so five snapshots exist.
+		variant := append(bytes.TrimRight(document, "\n"), bytes.Repeat([]byte{' '}, index+1)...)
+		collection, err := store.PublishSupplyChainSnapshot(t.Context(), publication(t, repositoryID, claimSupplyChain(t, store, repositoryID, "w"), variant))
+		if err != nil {
+			t.Fatal(err)
+		}
+		snapshotIDs = append(snapshotIDs, *collection.SnapshotID)
+	}
+	// A policy result references the second-oldest snapshot's component.
+	var componentID int64
+	if err := store.pool.QueryRow(t.Context(), `select id from supply_chain_components where snapshot_id=$1 order by ordinal limit 1`, snapshotIDs[1]).Scan(&componentID); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := store.pool.Exec(t.Context(), `insert into supply_chain_policies (name, version, kind, rules, unknown_handling, created_by, active) values ('p', 1, 'example', '{}', 'review_required', 't', false)`); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := store.pool.Exec(t.Context(), `insert into supply_chain_policy_results (component_id, snapshot_id, policy_id, verdict, explanation) values ($1, $2, (select id from supply_chain_policies), 'review_required', 'x')`, componentID, snapshotIDs[1]); err != nil {
+		t.Fatal(err)
+	}
+	snapshots, documents, err := store.PruneSupplyChainSnapshots(t.Context(), 2, 100)
+	if err != nil {
+		t.Fatal(err)
+	}
+	// Keep the newest 2 (ids 4,5) plus the reviewed one (id 2); delete 1 and 3.
+	if snapshots != 2 || documents != 2 {
+		t.Fatalf("pruned %d snapshots, %d documents", snapshots, documents)
+	}
+	remaining, err := store.SupplyChainSnapshots(t.Context(), repositoryID, supplychain.StreamGitHubSource, 0, 10)
+	if err != nil || len(remaining) != 3 {
+		t.Fatalf("remaining = %d %v", len(remaining), err)
+	}
+	ids := map[int64]bool{}
+	for _, snapshot := range remaining {
+		ids[snapshot.ID] = true
+	}
+	if !ids[snapshotIDs[1]] || !ids[snapshotIDs[3]] || !ids[snapshotIDs[4]] || ids[snapshotIDs[0]] || ids[snapshotIDs[2]] {
+		t.Fatalf("remaining ids = %v", ids)
+	}
+	// The latest pointer and its document are intact; the reviewed snapshot's document survives.
+	stream, err := store.SupplyChainStream(t.Context(), repositoryID, supplychain.StreamGitHubSource)
+	if err != nil || *stream.LatestSnapshotID != snapshotIDs[4] {
+		t.Fatalf("stream = %+v %v", stream, err)
+	}
+	if _, _, _, err := store.SupplyChainDocument(t.Context(), snapshotIDs[1], []int64{repositoryID}); err != nil {
+		t.Fatalf("reviewed snapshot document lost: %v", err)
+	}
+	// History pruning keeps the newest attempts and removes finished jobs older than the cutoff.
+	if _, err := store.pool.Exec(t.Context(), `update supply_chain_jobs set updated_at=now()-interval '10 days'`); err != nil {
+		t.Fatal(err)
+	}
+	// Five attempts exist; the newest three stay, and of the older two only the one whose
+	// snapshot was pruned (snapshot link nulled by cascade) is removable.
+	collections, jobs, err := store.PruneSupplyChainHistory(t.Context(), 3, 7*24*time.Hour)
+	if err != nil || jobs != 5 || collections != 1 {
+		t.Fatalf("history prune = %d collections, %d jobs, %v", collections, jobs, err)
+	}
+}

From 02cd8a67e5d20ce1cf4b1671dc06ac7623e5e3f7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?D=C3=A1vid=20Balatoni?= <balcsida@gmail.com>
Date: Tue, 22 Sep 2026 22:40:49 +0200
Subject: [PATCH 2/5] test(supply-chain): record portfolio query plans on a
 50k-occurrence dataset

Add an opt-in integration benchmark that seeds 200 repositories x 250
components, records EXPLAIN ANALYZE for the overview, unique-coordinate,
portfolio page, coordinate-occurrence, and review-queue queries, and
writes the evidence to docs/supply-chain-query-plans.md with the dataset
and environment named. Add the pilot comparison checklist.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 docs/supply-chain-pilot-checklist.md          | 104 +++++++++
 docs/supply-chain-query-plans.md              | 198 ++++++++++++++++++
 .../postgres/supply_chain_benchmark_test.go   | 113 ++++++++++
 3 files changed, 415 insertions(+)
 create mode 100644 docs/supply-chain-pilot-checklist.md
 create mode 100644 docs/supply-chain-query-plans.md
 create mode 100644 internal/postgres/supply_chain_benchmark_test.go

diff --git a/docs/supply-chain-pilot-checklist.md b/docs/supply-chain-pilot-checklist.md
new file mode 100644
index 00000000..88d55632
--- /dev/null
+++ b/docs/supply-chain-pilot-checklist.md
@@ -0,0 +1,104 @@
+# Dependencies & Licenses pilot comparison checklist
+
+Use this checklist to compare GraphNest's inventory against an existing
+assessment of the **same repositories, builds, and artifacts** (for example
+those already reviewed by a Code Insight team). It measures coverage and gaps;
+it does not claim replacement parity, and it does not migrate proprietary
+audit history. Fill it in per repository or artifact and keep the filled copy
+with the pilot report.
+
+## Setup (once)
+
+- [ ] `GRAPHNEST_SUPPLY_CHAIN=true` on the server; migrations 033–036 applied.
+- [ ] GitHub App has `Contents: read` on every pilot repository; the
+      dependency graph is enabled on GHES for them.
+- [ ] Registry routes configured only for the ecosystems in scope
+      (`GRAPHNEST_SUPPLY_CHAIN_REGISTRY_*`), pointing at the organization's
+      mirrors; `ALLOW_PRIVATE` set only where the mirror is internal.
+- [ ] Upload and review grants issued to the pilot participants
+      (`PUT /v1/supply-chain/upload-grants`, `PUT /v1/supply-chain/review/grants`).
+- [ ] The organization policy authored and activated
+      (`POST /v1/supply-chain/policies`); the example policy left inactive.
+
+## Per repository / artifact
+
+Record the identifiers first so every later row is reproducible:
+
+| Field | Value |
+| --- | --- |
+| Repository (GitHub ID, name) | |
+| Existing assessment reference (tool, report ID, date, exact commit or artifact digest it covered) | |
+| GraphNest GitHub snapshot ID, `collected_at`, `subject_assurance` (always `unknown` for GHES) | |
+| GraphNest import snapshot IDs (stream, `uploaded_by`, producer tool, `subject_assurance`) | |
+
+### Component coverage
+
+- [ ] Components in the existing assessment: ___ (unique coordinates).
+- [ ] Components in the GraphNest GitHub snapshot: ___ occurrences /
+      ___ unique coordinates (from `GET /v1/supply-chain/repositories/{id}`
+      and the overview).
+- [ ] Components in the GraphNest import snapshot(s): ___ / ___.
+- [ ] Present in the existing assessment but absent from every GraphNest
+      stream (list, with the likely reason: ecosystem not in the dependency
+      graph, build-time only, container base image, vendored source):
+- [ ] Present in GraphNest but absent from the existing assessment (list):
+- [ ] Version disagreements for the same package (list `name`, theirs, ours,
+      and which stream):
+- [ ] Components without a purl or version in GraphNest (`without_purl`,
+      `without_version` on the overview): ___ / ___ — are they identifiable
+      in the existing assessment?
+- [ ] Coverage warnings on the GraphNest snapshot (`warning_count`, codes):
+
+Note: GHES exports describe the default branch at collection time, not a
+commit or a release. Compare an artifact assessment only against an
+**artifact** import stream (Syft/ORT of the same build), never against the
+GitHub observation.
+
+### License evidence
+
+- [ ] Assessment counts on the GraphNest snapshot (`license_summary`):
+      resolved ___, declared ___, conflict ___, unlicensed ___, unknown ___,
+      not_applicable ___, unassessed ___.
+- [ ] For a sample of ≥ 20 components (or all if fewer), compare the existing
+      concluded license with GraphNest's assessed expression:
+      agree ___ / disagree ___ / GraphNest unknown ___ / theirs unknown ___.
+- [ ] For each disagreement, record the evidence GraphNest shows
+      (`GET .../component?element=`: declarations, registry rows with
+      `route`, `raw_value`, `parse_status`, `outcome`) and the basis of the
+      existing conclusion (scan finding, curation, manual review).
+- [ ] Components where the existing tool relied on source scanning that
+      GraphNest does not perform (license files inside packages, headers,
+      copyright): list them; these are expected GraphNest gaps.
+- [ ] Registry lookups that failed (`not_found`, `unavailable`, `rejected`)
+      and why (route not configured, private package, mirror outage).
+
+### Unknowns, conflicts, and review
+
+- [ ] Number of occurrences in the GraphNest review queue for the repository
+      (`GET /v1/supply-chain/review/queue`), by verdict.
+- [ ] Number of those already decided in the existing process; are the
+      decisions reproducible as GraphNest decisions with reason and scope?
+- [ ] Conflicts GraphNest surfaced that the existing process had not:
+- [ ] Decisions in the existing process that GraphNest cannot represent
+      (list the missing concept: e.g. product-level scope, obligation
+      tracking, redistribution class):
+
+### Workflow gaps observed
+
+- [ ] Missing filters, views, or exports the pilot team needed:
+- [ ] Time to answer "where is package X used?" via
+      `find_component_repositories` / `/v1/supply-chain/components/{key}`
+      versus the existing tool:
+- [ ] Data the team needed from the original document that GraphNest only
+      keeps in the preserved original (CycloneDX `evidence`, ORT curations):
+
+## Summary for the pilot report
+
+- Component coverage (GitHub stream vs existing): ___ % of the existing
+  assessment's coordinates present; ___ additional coordinates surfaced.
+- License evidence agreement on the sample: ___ %; unresolved by GraphNest:
+  ___ %.
+- Conflicts and unknowns newly surfaced: ___.
+- Review workflow gaps: (list).
+- Explicit non-goals confirmed: no source-license scanning, no vulnerability
+  data, no obligation advice, no migration of the existing audit history.
diff --git a/docs/supply-chain-query-plans.md b/docs/supply-chain-query-plans.md
new file mode 100644
index 00000000..73831e8b
--- /dev/null
+++ b/docs/supply-chain-query-plans.md
@@ -0,0 +1,198 @@
+# Supply-chain portfolio query plans
+
+Recorded by `TestSupplyChainPortfolioQueryPlans` (`go test -tags=integration
+./internal/postgres -run TestSupplyChainPortfolioQueryPlans` with
+`GRAPHNEST_TEST_SUPPLY_CHAIN_PLANS=<file>`) on 2026-09-22 against PostgreSQL
+18.6 in Docker (OrbStack, Apple Silicon). Times are measurements of this
+dataset in this environment, not a latency commitment.
+
+Reading: overview counts, coordinate lookup, and the review queue use the
+stream/component indexes and stay in low milliseconds. Unique-coordinate
+counting and the portfolio page aggregate every authorized latest-snapshot
+occurrence (a full pass with an external-merge sort at 50k rows, ~110-120 ms
+here). The upgrade path when that grows past the budget is a per-snapshot
+coordinate summary table refreshed at publication (decision D7 in the
+execution plan); it is not needed at this scale.
+
+
+Dataset: 200 repositories x 250 components = 50000 occurrences, ~5000 unique coordinates; seeded in 2.513s.
+PostgreSQL: PostgreSQL 18.6 (Debian 18.6-1.pgdg13+2) on aarch64-unknown-linux-gnu, compiled by gcc (Debian 14.2.0-19) 14.2.0, 64-bit
+
+## overview counts
+
+```
+Aggregate  (cost=31.57..31.58 rows=1 width=24) (actual time=0.108..0.108 rows=1.00 loops=1)
+  Buffers: shared hit=17
+  ->  Hash Left Join  (cost=26.50..29.57 rows=200 width=20) (actual time=0.072..0.101 rows=200.00 loops=1)
+        Hash Cond: (st.latest_snapshot_id = snap.id)
+        Buffers: shared hit=17
+        ->  Hash Left Join  (cost=9.00..11.54 rows=200 width=8) (actual time=0.037..0.054 rows=200.00 loops=1)
+              Hash Cond: (r.id = st.repository_id)
+              Buffers: shared hit=4
+              ->  Function Scan on unnest r  (cost=0.00..2.00 rows=200 width=8) (actual time=0.008..0.013 rows=200.00 loops=1)
+              ->  Hash  (cost=6.50..6.50 rows=200 width=16) (actual time=0.028..0.028 rows=200.00 loops=1)
+                    Buckets: 1024  Batches: 1  Memory Usage: 18kB
+                    Buffers: shared hit=4
+                    ->  Seq Scan on supply_chain_streams st  (cost=0.00..6.50 rows=200 width=16) (actual time=0.005..0.018 rows=200.00 loops=1)
+                          Filter: ((stream_key)::text = 'github:source'::text)
+                          Buffers: shared hit=4
+        ->  Hash  (cost=15.00..15.00 rows=200 width=20) (actual time=0.034..0.034 rows=200.00 loops=1)
+              Buckets: 1024  Batches: 1  Memory Usage: 19kB
+              Buffers: shared hit=13
+              ->  Seq Scan on supply_chain_snapshots snap  (cost=0.00..15.00 rows=200 width=20) (actual time=0.002..0.023 rows=200.00 loops=1)
+                    Buffers: shared hit=13
+Planning:
+  Buffers: shared hit=107 read=1
+Planning Time: 0.207 ms
+Execution Time: 0.127 ms
+```
+
+Wall time including plan output: 1ms
+
+## unique coordinates
+
+```
+Aggregate  (cost=4562.43..4562.44 rows=1 width=8) (actual time=112.801..112.803 rows=1.00 loops=1)
+  Buffers: shared hit=1009, temp read=576 written=577
+  ->  Sort  (cost=4403.04..4482.74 rows=31877 width=72) (actual time=97.434..106.055 rows=50200.00 loops=1)
+        Sort Key: (ROW(c.ecosystem, COALESCE(c.purl_namespace, ''::text), COALESCE(c.purl_name, c.name), COALESCE(c.purl_version, c.version, ''::text)))
+        Sort Method: external merge  Disk: 4608kB
+        Buffers: shared hit=1009, temp read=576 written=577
+        ->  Hash Join  (cost=9.59..2018.61 rows=31877 width=72) (actual time=0.035..8.901 rows=50200.00 loops=1)
+              Hash Cond: (c.snapshot_id = st.latest_snapshot_id)
+              Buffers: shared hit=1004
+              ->  Seq Scan on supply_chain_components c  (cost=0.00..1502.00 rows=50200 width=80) (actual time=0.003..2.069 rows=50200.00 loops=1)
+                    Buffers: shared hit=1000
+              ->  Hash  (cost=8.00..8.00 rows=127 width=8) (actual time=0.030..0.030 rows=200.00 loops=1)
+                    Buckets: 1024  Batches: 1  Memory Usage: 16kB
+                    Buffers: shared hit=4
+                    ->  Seq Scan on supply_chain_streams st  (cost=0.50..8.00 rows=127 width=8) (actual time=0.007..0.021 rows=200.00 loops=1)
+                          Filter: (((stream_key)::text = 'github:source'::text) AND (repository_id = ANY ('{1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129,130,131,132,133,134,135,136,137,138,139,140,141,142,143,144,145,146,147,148,149,150,151,152,153,154,155,156,157,158,159,160,161,162,163,164,165,166,167,168,169,170,171,172,173,174,175,176,177,178,179,180,181,182,183,184,185,186,187,188,189,190,191,192,193,194,195,196,197,198,199,200}'::bigint[])))
+                          Buffers: shared hit=4
+Planning:
+  Buffers: shared hit=93 read=1
+Planning Time: 0.230 ms
+Execution Time: 113.205 ms
+```
+
+Wall time including plan output: 115ms
+
+## portfolio page (first 100)
+
+```
+Limit  (cost=3845.99..3846.24 rows=101 width=48) (actual time=119.237..119.245 rows=101.00 loops=1)
+  Buffers: shared hit=1021, temp read=562 written=563
+  ->  Sort  (cost=3845.99..3858.32 rows=4933 width=48) (actual time=119.236..119.241 rows=101.00 loops=1)
+        Sort Key: grouped.key
+        Sort Method: top-N heapsort  Memory: 32kB
+        Buffers: shared hit=1021, temp read=562 written=563
+        ->  Subquery Scan on grouped  (cost=3298.51..3657.10 rows=4933 width=48) (actual time=104.812..118.684 rows=4560.00 loops=1)
+              Buffers: shared hit=1021, temp read=562 written=563
+              ->  GroupAggregate  (cost=3298.51..3607.77 rows=4933 width=176) (actual time=104.811..118.514 rows=4560.00 loops=1)
+                    Group Key: (COALESCE(c.ecosystem, ''::character varying)), (COALESCE(c.purl_namespace, ''::text)), (COALESCE(c.purl_name, c.name)), (COALESCE(c.purl_version, c.version, ''::text))
+                    Buffers: shared hit=1021, temp read=562 written=563
+                    ->  Sort  (cost=3298.51..3325.07 rows=10625 width=208) (actual time=104.759..112.406 rows=50200.00 loops=1)
+                          Sort Key: (COALESCE(c.ecosystem, ''::character varying)), (COALESCE(c.purl_namespace, ''::text)), (COALESCE(c.purl_name, c.name)), (COALESCE(c.purl_version, c.version, ''::text)), st.repository_id
+                          Sort Method: external merge  Disk: 4496kB
+                          Buffers: shared hit=1021, temp read=562 written=563
+                          ->  Hash Join  (cost=38.45..2587.95 rows=10625 width=208) (actual time=0.115..11.612 rows=50200.00 loops=1)
+                                Hash Cond: (c.snapshot_id = snap.id)
+                                Buffers: shared hit=1021
+                                ->  Seq Scan on supply_chain_components c  (cost=0.00..2380.50 rows=16733 width=88) (actual time=0.006..7.557 rows=50200.00 loops=1)
+                                      Filter: ((((((((COALESCE(ecosystem, ''::character varying))::text || '
'::text) || COALESCE(purl_namespace, ''::text)) || '
'::text) || COALESCE(purl_name, name)) || '
'::text) || COALESCE(purl_version, version, ''::text)) > ''::text)
+                                      Buffers: shared hit=1000
+                                ->  Hash  (cost=36.86..36.86 rows=127 width=24) (actual time=0.107..0.109 rows=200.00 loops=1)
+                                      Buckets: 1024  Batches: 1  Memory Usage: 19kB
+                                      Buffers: shared hit=21
+                                      ->  Hash Join  (cost=28.68..36.86 rows=127 width=24) (actual time=0.059..0.099 rows=200.00 loops=1)
+                                            Hash Cond: (st.repository_id = r.id)
+                                            Buffers: shared hit=21
+                                            ->  Hash Join  (cost=18.00..25.84 rows=127 width=24) (actual time=0.037..0.065 rows=200.00 loops=1)
+                                                  Hash Cond: (st.latest_snapshot_id = snap.id)
+                                                  Buffers: shared hit=17
+                                                  ->  Seq Scan on supply_chain_streams st  (cost=0.50..8.00 rows=127 width=16) (actual time=0.007..0.021 rows=200.00 loops=1)
+                                                        Filter: (((stream_key)::text = 'github:source'::text) AND (repository_id = ANY ('{1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129,130,131,132,133,134,135,136,137,138,139,140,141,142,143,144,145,146,147,148,149,150,151,152,153,154,155,156,157,158,159,160,161,162,163,164,165,166,167,168,169,170,171,172,173,174,175,176,177,178,179,180,181,182,183,184,185,186,187,188,189,190,191,192,193,194,195,196,197,198,199,200}'::bigint[])))
+                                                        Buffers: shared hit=4
+                                                  ->  Hash  (cost=15.00..15.00 rows=200 width=8) (actual time=0.028..0.029 rows=200.00 loops=1)
+                                                        Buckets: 1024  Batches: 1  Memory Usage: 16kB
+                                                        Buffers: shared hit=13
+                                                        ->  Seq Scan on supply_chain_snapshots snap  (cost=0.00..15.00 rows=200 width=8) (actual time=0.001..0.021 rows=200.00 loops=1)
+                                                              Buffers: shared hit=13
+                                            ->  Hash  (cost=10.30..10.30 rows=30 width=8) (actual time=0.020..0.020 rows=200.00 loops=1)
+                                                  Buckets: 1024  Batches: 1  Memory Usage: 16kB
+                                                  Buffers: shared hit=4
+                                                  ->  Seq Scan on repositories r  (cost=0.00..10.30 rows=30 width=8) (actual time=0.003..0.012 rows=200.00 loops=1)
+                                                        Buffers: shared hit=4
+Planning:
+  Buffers: shared hit=106 read=2
+Planning Time: 0.472 ms
+Execution Time: 119.604 ms
+```
+
+Wall time including plan output: 121ms
+
+## coordinate occurrences
+
+```
+Limit  (cost=0.14..2037.64 rows=1 width=19) (actual time=3.533..3.534 rows=0.00 loops=1)
+  Buffers: shared hit=1005
+  ->  Nested Loop  (cost=0.14..2037.64 rows=1 width=19) (actual time=3.532..3.533 rows=0.00 loops=1)
+        Join Filter: (st.repository_id = r.id)
+        Buffers: shared hit=1005
+        ->  Nested Loop  (cost=0.14..2026.97 rows=1 width=19) (actual time=3.532..3.532 rows=0.00 loops=1)
+              Join Filter: (c.snapshot_id = st.latest_snapshot_id)
+              Buffers: shared hit=1005
+              ->  Index Scan using supply_chain_streams_pkey on supply_chain_streams st  (cost=0.14..21.06 rows=127 width=16) (actual time=0.019..0.030 rows=200.00 loops=1)
+                    Index Cond: ((repository_id = ANY ('{1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129,130,131,132,133,134,135,136,137,138,139,140,141,142,143,144,145,146,147,148,149,150,151,152,153,154,155,156,157,158,159,160,161,162,163,164,165,166,167,168,169,170,171,172,173,174,175,176,177,178,179,180,181,182,183,184,185,186,187,188,189,190,191,192,193,194,195,196,197,198,199,200}'::bigint[])) AND ((stream_key)::text = 'github:source'::text))
+                    Index Searches: 1
+                    Buffers: shared hit=5
+              ->  Materialize  (cost=0.00..2004.01 rows=1 width=19) (actual time=0.017..0.017 rows=0.00 loops=200)
+                    Storage: Memory  Maximum Storage: 17kB
+                    Buffers: shared hit=1000
+                    ->  Seq Scan on supply_chain_components c  (cost=0.00..2004.00 rows=1 width=19) (actual time=3.488..3.488 rows=0.00 loops=1)
+                          Filter: (((COALESCE(ecosystem, ''::character varying))::text = 'npm'::text) AND (COALESCE(purl_namespace, ''::text) = ''::text) AND (COALESCE(purl_name, name) = 'pkg-0005'::text) AND (COALESCE(purl_version, version, ''::text) = '5.0.2'::text))
+                          Rows Removed by Filter: 50200
+                          Buffers: shared hit=1000
+        ->  Seq Scan on repositories r  (cost=0.00..10.30 rows=30 width=16) (never executed)
+Planning:
+  Buffers: shared hit=11
+Planning Time: 0.192 ms
+Execution Time: 3.545 ms
+```
+
+Wall time including plan output: 5ms
+
+## review queue (no results yet)
+
+```
+Limit  (cost=0.92..312.27 rows=101 width=8) (actual time=0.021..1.000 rows=101.00 loops=1)
+  Buffers: shared hit=12
+  ->  Nested Loop  (cost=0.92..97778.08 rows=31718 width=8) (actual time=0.021..0.996 rows=101.00 loops=1)
+        Join Filter: (c.snapshot_id = st.latest_snapshot_id)
+        Rows Removed by Join Filter: 19900
+        Buffers: shared hit=12
+        ->  Merge Left Join  (cost=0.41..2616.92 rows=49949 width=16) (actual time=0.013..0.034 rows=101.00 loops=1)
+              Merge Cond: (c.id = pr.component_id)
+              Filter: ((COALESCE(pr.verdict, 'unknown'::character varying))::text <> 'approved'::text)
+              Buffers: shared hit=8
+              ->  Index Scan using supply_chain_components_pkey on supply_chain_components c  (cost=0.29..2441.79 rows=50200 width=16) (actual time=0.011..0.022 rows=101.00 loops=1)
+                    Index Cond: (id > 0)
+                    Index Searches: 1
+                    Buffers: shared hit=7
+              ->  Index Scan using supply_chain_policy_results_current on supply_chain_policy_results pr  (cost=0.12..46.33 rows=220 width=58) (actual time=0.000..0.001 rows=0.00 loops=1)
+                    Index Searches: 1
+                    Buffers: shared hit=1
+        ->  Materialize  (cost=0.50..8.63 rows=127 width=8) (actual time=0.000..0.004 rows=198.03 loops=101)
+              Storage: Memory  Maximum Storage: 23kB
+              Buffers: shared hit=4
+              ->  Seq Scan on supply_chain_streams st  (cost=0.50..8.00 rows=127 width=8) (actual time=0.006..0.020 rows=200.00 loops=1)
+                    Filter: (((stream_key)::text = 'github:source'::text) AND (repository_id = ANY ('{1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129,130,131,132,133,134,135,136,137,138,139,140,141,142,143,144,145,146,147,148,149,150,151,152,153,154,155,156,157,158,159,160,161,162,163,164,165,166,167,168,169,170,171,172,173,174,175,176,177,178,179,180,181,182,183,184,185,186,187,188,189,190,191,192,193,194,195,196,197,198,199,200}'::bigint[])))
+                    Buffers: shared hit=4
+Planning:
+  Buffers: shared hit=108 read=3
+Planning Time: 0.278 ms
+Execution Time: 1.013 ms
+```
+
+Wall time including plan output: 2ms
+
diff --git a/internal/postgres/supply_chain_benchmark_test.go b/internal/postgres/supply_chain_benchmark_test.go
new file mode 100644
index 00000000..07b53288
--- /dev/null
+++ b/internal/postgres/supply_chain_benchmark_test.go
@@ -0,0 +1,113 @@
+//go:build integration
+
+package postgres
+
+import (
+	"fmt"
+	"os"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/balcsida/graphnest/internal/supplychain"
+)
+
+// TestSupplyChainPortfolioQueryPlans seeds a representative synthetic
+// inventory (200 repositories x 250 components, 50,000 occurrences over
+// ~5,000 unique coordinates) and records EXPLAIN ANALYZE output for the
+// portfolio queries when GRAPHNEST_TEST_SUPPLY_CHAIN_PLANS names an output
+// file. Without the variable it only asserts the queries complete. Timings
+// are environment-specific evidence, not a latency promise.
+func TestSupplyChainPortfolioQueryPlans(t *testing.T) {
+	if os.Getenv("GRAPHNEST_TEST_SUPPLY_CHAIN_PLANS") == "" {
+		t.Skip("set GRAPHNEST_TEST_SUPPLY_CHAIN_PLANS to seed 50,000 occurrences and record plans")
+	}
+	store := migratedStore(t)
+	const repositories, componentsPer, uniqueVersions = 200, 250, 5000
+	if err := store.UpsertInstallation(t.Context(), InstallationUpdate{GitHubID: 10, AccountLogin: "acme", AccountType: "Organization", Status: "active"}); err != nil {
+		t.Fatal(err)
+	}
+	ids := make([]int64, 0, repositories)
+	started := time.Now()
+	for index := range repositories {
+		repo, err := store.UpsertRepository(t.Context(), RepositoryUpdate{GitHubID: int64(1000 + index), InstallationID: 10, Owner: "acme", Name: fmt.Sprintf("repo-%03d", index), CloneURL: "c", WebURL: "w", DefaultBranch: "main", Enabled: true})
+		if err != nil {
+			t.Fatal(err)
+		}
+		ids = append(ids, repo.ID)
+		var packages []string
+		var relationships []string
+		for component := range componentsPer {
+			coordinate := (index*7 + component*13) % uniqueVersions
+			ecosystem := []string{"npm", "maven", "nuget", "golang", "pypi"}[coordinate%5]
+			name := fmt.Sprintf("pkg-%04d", coordinate)
+			version := fmt.Sprintf("%d.%d.%d", coordinate%9, coordinate%5, coordinate%3)
+			id := fmt.Sprintf("SPDXRef-%d", component)
+			packages = append(packages, fmt.Sprintf(`{"SPDXID":%q,"name":%q,"versionInfo":%q,"licenseDeclared":"NOASSERTION","externalRefs":[{"referenceType":"purl","referenceLocator":"pkg:%s/%s@%s"}]}`, id, ecosystem+":"+name, version, ecosystem, name, version))
+			relationships = append(relationships, fmt.Sprintf(`{"spdxElementId":"SPDXRef-root","relationshipType":"DEPENDS_ON","relatedSpdxElement":%q}`, id))
+		}
+		document := []byte(fmt.Sprintf(`{"spdxVersion":"SPDX-2.3","SPDXID":"SPDXRef-DOCUMENT","name":"acme/repo-%03d","creationInfo":{"created":"2026-09-01T00:00:00Z","creators":["Tool: GitHub.com-Dependency-Graph"]},"documentDescribes":["SPDXRef-root"],"packages":[{"SPDXID":"SPDXRef-root","name":"root"},%s],"relationships":[%s]}`,
+			index, strings.Join(packages, ","), strings.Join(relationships, ",")))
+		normalized, err := supplychain.NormalizeSPDX23(document, supplychain.Limits{})
+		if err != nil {
+			t.Fatal(err)
+		}
+		if _, err := store.PublishSupplyChainSnapshot(t.Context(), SupplyChainPublication{RepositoryID: repo.ID, Producer: supplychain.ProducerGitHub, Subject: supplychain.SubjectSource, StreamKey: supplychain.StreamGitHubSource,
+			Format: supplychain.FormatSPDX23JSON, MediaType: "application/json", Document: document, Normalized: normalized, CollectedAt: time.Now(), StartedAt: time.Now(), SubjectAssurance: supplychain.AssuranceUnknown}); err != nil {
+			t.Fatal(err)
+		}
+	}
+	seedDuration := time.Since(started)
+	if _, err := store.pool.Exec(t.Context(), `analyze supply_chain_components; analyze supply_chain_snapshots; analyze supply_chain_streams; analyze supply_chain_component_assessments`); err != nil {
+		t.Fatal(err)
+	}
+	var report strings.Builder
+	fmt.Fprintf(&report, "# Supply-chain portfolio query plans\n\nDataset: %d repositories x %d components = %d occurrences, ~%d unique coordinates; seeded in %s.\nPostgreSQL: ", repositories, componentsPer, repositories*componentsPer, uniqueVersions, seedDuration.Round(time.Millisecond))
+	var version string
+	if err := store.pool.QueryRow(t.Context(), `select version()`).Scan(&version); err != nil {
+		t.Fatal(err)
+	}
+	report.WriteString(version + "\n\n")
+	run := func(label string, query string, args ...any) {
+		startedQuery := time.Now()
+		rows, err := store.pool.Query(t.Context(), "explain (analyze, buffers, format text) "+query, args...)
+		if err != nil {
+			t.Fatalf("%s: %v", label, err)
+		}
+		fmt.Fprintf(&report, "## %s\n\n```\n", label)
+		for rows.Next() {
+			var line string
+			if err := rows.Scan(&line); err != nil {
+				t.Fatal(err)
+			}
+			report.WriteString(line + "\n")
+		}
+		rows.Close()
+		fmt.Fprintf(&report, "```\n\nWall time including plan output: %s\n\n", time.Since(startedQuery).Round(time.Millisecond))
+	}
+	staleBefore := time.Now().Add(-48 * time.Hour)
+	run("overview counts", `select count(*) filter (where st.latest_snapshot_id is not null), count(*) filter (where snap.collected_at < $3), coalesce(sum(snap.component_count), 0)
+		from unnest($1::bigint[]) as r(id) left join supply_chain_streams st on st.repository_id=r.id and st.stream_key=$2 left join supply_chain_snapshots snap on snap.id=st.latest_snapshot_id`, ids, supplychain.StreamGitHubSource, staleBefore)
+	run("unique coordinates", `select count(distinct (c.ecosystem, coalesce(c.purl_namespace, ''), coalesce(c.purl_name, c.name), coalesce(c.purl_version, c.version, ''))) from supply_chain_streams st
+		join supply_chain_components c on c.snapshot_id=st.latest_snapshot_id where st.repository_id=any($1) and st.stream_key=$2`, ids, supplychain.StreamGitHubSource)
+	run("portfolio page (first 100)", `with occurrences as (
+			select c.*, st.repository_id, snap.collected_at, r.github_id, a.status as assessment_status, a.normalized_expression,
+				coalesce(c.ecosystem, '') as eco, coalesce(c.purl_namespace, '') as ns, coalesce(c.purl_name, c.name) as pname, coalesce(c.purl_version, c.version, '') as pversion
+			from supply_chain_streams st join supply_chain_snapshots snap on snap.id=st.latest_snapshot_id join repositories r on r.id=st.repository_id
+			join supply_chain_components c on c.snapshot_id=st.latest_snapshot_id left join supply_chain_component_assessments a on a.component_id=c.id
+			where st.repository_id=any($1) and st.stream_key=$2
+		), grouped as (
+			select eco || chr(1) || ns || chr(1) || pname || chr(1) || pversion as key, count(distinct repository_id) as repositories, count(*) as occurrences from occurrences group by eco, ns, pname, pversion
+		) select key, repositories, occurrences from grouped where key>'' order by key limit 101`, ids, supplychain.StreamGitHubSource)
+	run("coordinate occurrences", `select r.github_id, c.element_id from supply_chain_streams st join repositories r on r.id=st.repository_id join supply_chain_components c on c.snapshot_id=st.latest_snapshot_id
+		where st.repository_id=any($1) and st.stream_key=$2 and coalesce(c.ecosystem, '')='npm' and coalesce(c.purl_namespace, '')='' and coalesce(c.purl_name, c.name)='pkg-0005' and coalesce(c.purl_version, c.version, '')='5.0.2' limit 101`, ids, supplychain.StreamGitHubSource)
+	run("review queue (no results yet)", `select c.id from supply_chain_streams st join supply_chain_components c on c.snapshot_id=st.latest_snapshot_id
+		left join supply_chain_component_assessments a on a.component_id=c.id left join supply_chain_policy_results pr on pr.component_id=c.id and pr.current
+		where st.repository_id=any($1) and st.stream_key=$2 and c.id>0 and coalesce(pr.verdict, 'unknown') <> 'approved' order by c.id limit 101`, ids, supplychain.StreamGitHubSource)
+	if path := os.Getenv("GRAPHNEST_TEST_SUPPLY_CHAIN_PLANS"); path != "" {
+		if err := os.WriteFile(path, []byte(report.String()), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	t.Logf("seeded %d occurrences in %s", repositories*componentsPer, seedDuration.Round(time.Millisecond))
+}

From c5ac38ef8db4d53a8b0e246726b4f993f3da9525 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?D=C3=A1vid=20Balatoni?= <balcsida@gmail.com>
Date: Tue, 22 Sep 2026 22:45:22 +0200
Subject: [PATCH 3/5] docs(supply-chain): record M2-M7 progress, validation,
 gaps, and next task

Co-Authored-By: Claude <noreply@anthropic.com>
---
 docs/execplans/supply-chain.md | 133 +++++++++++++++++++++++++--------
 1 file changed, 103 insertions(+), 30 deletions(-)

diff --git a/docs/execplans/supply-chain.md b/docs/execplans/supply-chain.md
index b8226a77..460632ba 100644
--- a/docs/execplans/supply-chain.md
+++ b/docs/execplans/supply-chain.md
@@ -306,15 +306,53 @@ Detailed task lists are appended when each milestone starts.
     cross-installation isolation, and projection.
   - `docs(supply-chain)` (`5dc15aa`): light/dark screenshots of the real page
     rendered in Chromium against a stubbed API (`docs/images/supply-chain-*.png`).
-- Next task: M2 license enrichment, starting with the bounded SPDX expression
-  parser (`internal/supplychain/spdxexpr`) and migration
-  `034_supply_chain_license.sql`.
+- 2026-09-22: **M2 complete** (`feat/supply-chain/m2-license-core`): bounded
+  SPDX expression parser over the embedded SPDX License List 3.27.0 (fuzzed);
+  npm/NuGet/Maven resolvers behind explicitly configured routes with pinned
+  origin/base path, private-address denial, decompression bounds, credential
+  isolation, and no public fallback; immutable evidence rows (duplicates are
+  new observations; outages keep earlier resolved evidence); deterministic
+  per-occurrence assessments with conflict detection; enrichment worker
+  queued from publication; evidence detail route; UI license column and
+  evidence panel; Helm route values/secrets; docs.
+- 2026-09-22: **M3 complete** (`feat/supply-chain/m3-portfolio`): overview
+  with named denominators, keyset-paginated unique coordinates with
+  filter-bound cursors, facets, coordinate detail, CSV export with provenance
+  and formula-safe cells, snapshot comparison separating component/license/
+  edge changes from metadata; Overview/Components/comparison UI views with
+  screenshots in both themes.
+- 2026-09-22: **M4 complete** (`feat/supply-chain/m4-imports`): SPDX 2.3 JSON
+  and CycloneDX 1.6 JSON imports into `import:<subject>:<label>` streams with
+  content-based format detection, explicit rejection of other versions,
+  byte-preserving storage, uploader recorded apart from the claimed producer,
+  producer-asserted subject binding, idempotency, quotas, upload grants;
+  derived SPDX export naming GraphNest as creator and linking the original.
+- 2026-09-22: **M5 complete** (`feat/supply-chain/m5-review`): tree-walking
+  policy evaluator with a truth table (AND/OR/WITH/unknown/or-later), labelled
+  example policy, admin-only versioned policies that refuse auto-approval of
+  unknowns, review queue, human conclusions as immutable evidence,
+  approve/reject/exception decisions with optimistic concurrency on the
+  evidence fingerprint, expiry and stale detection, repository-scoped review
+  grants, append-only audit trail, background re-evaluation retaining history.
+- 2026-09-22: **M6 complete** (`feat/supply-chain/m6-mcp`): read-only MCP tools
+  `search_dependency_inventory`, `find_component_repositories`,
+  `inspect_component_license` over the same services as REST, with an
+  integration test proving scope agreement and no cross-installation leaks.
+- 2026-09-22: **M7 partially complete** (`feat/supply-chain/m7-operations`):
+  review-preserving snapshot retention and history pruning on the scheduler
+  tick, enrichment queue-depth metrics, retention configuration in
+  config/Compose/Helm, operations/README/CHANGELOG coverage, pilot comparison
+  checklist (`docs/supply-chain-pilot-checklist.md`), and recorded query plans
+  on a 50,000-occurrence synthetic dataset (`docs/supply-chain-query-plans.md`).
+  Remaining M7 items are listed under gaps.
+- Next task: see "Remaining gaps and next task".
 
 ## Validation results
 
-M1 (worktree head `5dc15aa`, 2026-09-22, macOS arm64, Go 1.27.1, PostgreSQL
-18.6 via Compose reached at the OrbStack container address because
-`docker compose port` reports `invalid IP:0` on this host):
+Final worktree head `d110e93` (`feat/supply-chain/m7-operations`), 2026-09-22,
+macOS arm64, Go 1.27.1, PostgreSQL 18.6 via Compose (reached at the OrbStack
+container address because `docker compose port` reports `invalid IP:0` here),
+Helm 4.x, Node 26, Playwright 1.62.1 with locally installed Chromium.
 
 | Gate | Result |
 | --- | --- |
@@ -322,34 +360,69 @@ M1 (worktree head `5dc15aa`, 2026-09-22, macOS arm64, Go 1.27.1, PostgreSQL
 | `make fmt lint` | pass |
 | `make staticcheck` | pass |
 | `make govulncheck` | pass (same as `main`: 0 called vulnerabilities, 1 uncalled module-level finding pre-existing) |
-| `CGO_ENABLED=0 go test ./...` | pass (2153 tests, 44 packages) |
+| `CGO_ENABLED=0 go test ./...` | pass (2318 tests, 48 packages) |
 | `make test-race` | pass |
-| `make postgres-test` (integration tag, all six packages, includes new `TestSupplyChain*` and `TestSupplyChainVerticalSlice`) | pass |
-| `make openapi-check` (Homebrew Ruby 4.0.7; system Ruby 2.6 lacks `filter_map` and fails on `main` too) | pass |
+| `make postgres-test` (all six integration packages, including every new `TestSupplyChain*`) | pass |
+| `make e2e-test` (Go e2e with real Zoekt binaries and PostgreSQL, plus scanner e2e) | pass (run twice) |
+| `make openapi-check` | pass with Homebrew Ruby 4.0.7 (`/opt/homebrew/opt/ruby/bin/ruby scripts/check_openapi.rb`); the system Ruby 2.6 lacks `filter_map` and fails identically on `main` |
 | `make compose-test` | pass |
 | `make helm-lint helm-test` | pass |
 | `make brand-check` | pass |
-| `test/smoke/public_ui.sh` (existing Playwright smoke; Chromium installed locally) | pass |
-| `test/smoke/supply-chain-screenshots.mjs` (renders the new page, 7 rows, failed-refresh notice, both themes) | pass |
-| `make e2e` | **not run** in this pass (unchanged code paths; Zoekt tools linked from the main checkout but the suite takes >10 minutes; run before publication) |
-| Live GHES | **not run**; all GitHub behavior is exercised against fixtures and fake servers |
-
-Commit signing: the first two M1 commits (`559c51f`, `7a1c864`) and M0
-(`629d041`) are SSH-signed. The 1Password SSH agent began refusing sign
-operations mid-session ("agent refused operation"), so `5262228`, `02d4f20`,
-`0de63e9`, and `5dc15aa` are unsigned local commits. Re-sign with
-`git rebase --exec 'git commit --amend --no-edit -S' 629d041` (or equivalent)
-once the agent accepts operations, before any publication.
+| `make makefile-test abi-test tools-check` | pass |
+| `make scanner-build scanner-test` | pass |
+| `make parity-reference` | pass |
+| `test/smoke/public_ui.sh` (existing Playwright smoke) | pass |
+| `test/smoke/supply-chain-screenshots.mjs` (renders repository, overview, components views; 6 PNGs) | pass |
+| Fuzz: `FuzzParse` (45s), `FuzzNormalizeSPDX23` (20s), `FuzzNormalizeCycloneDX16` (20s) | pass, no crashers |
+| Per-layer `go build`/`go vet`/`go test` at every stack boundary | pass |
+| `make image image-test`, `make ui-smoke` via Make (needs `make tools` rebuild) | **not run** (image build not attempted in this pass; the smoke script itself passed) |
+| Live GHES / live registries | **not run**; all GitHub and registry behavior is exercised against fixtures and fake servers |
+
+Commit signing: `629d041`, `559c51f`, `7a1c864` are SSH-signed. The 1Password
+SSH agent began refusing sign operations mid-session ("agent refused
+operation"), so every later commit is unsigned. Before publication, re-sign
+with `git rebase --exec 'git commit --amend --no-edit -S' 331fa42` (from the
+worktree, once the agent accepts operations) and re-point the stack branches.
 
 ## Remaining gaps and next task
 
-- M1 gaps (tracked, not blocking): no retention pruning (M7); webhook-driven
-  refresh is not wired (`reason='webhook'` is reserved; periodic reconciliation
-  covers late dependency-graph updates); the UI has no snapshot picker or
-  job polling after refresh; MCP tools arrive in M6.
-- Nothing is published; no PR exists for this work. Suggested PR titles in
-  stack order: `docs(supply-chain): accept ADR-0017 and execution plan` →
-  `feat(supply-chain): preserve GHES SBOM observations as immutable snapshots`
-  → `feat(supply-chain): inventory service, collector, and REST routes` →
-  `feat(webui): Dependencies & Licenses inventory page` (docs, screenshots,
-  and the integration test can fold into their layers or stay separate).
+Not implemented (honest scope boundaries):
+
+- M7: no bounded fuzz target yet for the registry URL/redirect path beyond
+  the unit cases; no hostile-archive test because no archive is ever
+  unpacked (NuGet reads the nuspec, never the nupkg); `make image` was not
+  built; the Compose durable profile documents but does not template the
+  `GRAPHNEST_SUPPLY_CHAIN_REGISTRY_*` variables (they pass through the
+  environment); no webhook-driven refresh (`reason='webhook'` reserved;
+  periodic reconciliation covers late dependency-graph updates); no
+  Prometheus counter for unknown/conflicting assessments (available through
+  the overview API instead).
+- M3/M5 UI: the review queue, conclusion/decision forms, and policy
+  administration have REST routes and tests but no browser view yet; the
+  component detail view does not yet show review history inline.
+- M6: exact code-usage joins from an occurrence to indexed references are not
+  offered; the UI and MCP state that a dependency path is not a call graph and
+  GHES snapshots are unbound observations. A later layer may add clearly
+  labelled exploratory search links when a matching indexed revision exists.
+- M2: Go, PyPI, Cargo, and other ecosystems have no resolver; their
+  components stay at producer declarations or imported evidence, as designed.
+
+Exact next task: add the review UI (queue table, conclusion and decision
+forms echoing the `basis` fingerprint, history panel, policy list) to
+`internal/webui/supply-chain.html` with DOM/contract tests and screenshots,
+on a new layer above `feat/supply-chain/m7-operations`; then run
+`make image image-test` and record results here.
+
+Nothing is published; no PR exists for this work. Suggested PR titles in
+stack order (each layer depends on the one before):
+
+1. `docs(supply-chain): accept ADR-0017 and execution plan` (m0-design)
+2. `feat(supply-chain): preserve GHES SBOM observations as immutable snapshots` (m1-storage)
+3. `feat(supply-chain): inventory service, collector, and REST routes` (m1-service)
+4. `feat(webui): Dependencies & Licenses inventory page` (m1-ui; includes docs, deployment wiring, integration test, screenshots)
+5. `feat(supply-chain): exact-version license evidence and assessments` (m2-license-core)
+6. `feat(supply-chain): portfolio APIs and views` (m3-portfolio)
+7. `feat(supply-chain): SPDX and CycloneDX imports with derived export` (m4-imports)
+8. `feat(supply-chain): policies and review workflow` (m5-review)
+9. `feat(mcp): read-only dependency inventory tools` (m6-mcp)
+10. `feat(supply-chain): retention, operations docs, and query-plan evidence` (m7-operations)

From 05b9048f1d093fb57a8eb19fd0f85fad9a13decf Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?D=C3=A1vid=20Balatoni?= <balcsida@gmail.com>
Date: Tue, 22 Sep 2026 22:50:01 +0200
Subject: [PATCH 4/5] docs(supply-chain): note the re-signed stack and
 refreshed commit references

Co-Authored-By: Claude <noreply@anthropic.com>
---
 docs/execplans/supply-chain.md | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/docs/execplans/supply-chain.md b/docs/execplans/supply-chain.md
index 460632ba..2ff3a6fc 100644
--- a/docs/execplans/supply-chain.md
+++ b/docs/execplans/supply-chain.md
@@ -276,7 +276,7 @@ Detailed task lists are appended when each milestone starts.
 
 - 2026-09-22: Baseline recorded; ADR-0017 and this plan created.
 - 2026-09-22: **M1 complete** as four local stack layers on top of M0:
-  - `feat/supply-chain/m1-storage` (`559c51f`): migration 033; SPDX 2.3 JSON
+  - `feat/supply-chain/m1-storage` (`76dcf7c`): migration 033; SPDX 2.3 JSON
     normalizer with root detection through `documentDescribes` and
     `DESCRIBES`/`DESCRIBED_BY`, bounded warnings, PURL-less/version-less
     occurrences, unresolved edges kept as diagnostics; lossless
@@ -286,25 +286,25 @@ Detailed task lists are appended when each milestone starts.
     recording that never moves the latest snapshot, reaping, cancellation,
     opt-out, scoped reads, and the `repository_packages` projection. Legacy
     `DependencySBOM` and SCIP callers keep their contracts.
-  - `feat/supply-chain/m1-service` (`7a1c864`): authorized service (status
+  - `feat/supply-chain/m1-service` (`6b25c6a`): authorized service (status
     with independent collection/freshness/coverage/enrichment states,
     paginated components with derived scope, snapshots, collections, document
     download re-authorized at retrieval, manual refresh that only enqueues,
     job status), collector with typed outcome classification and projection,
     jittered scheduler, `GRAPHNEST_SUPPLY_CHAIN*` config, bounded metrics,
     `/v1/supply-chain` routes designed in OpenAPI, gated server wiring.
-  - `docs(supply-chain)` (`5262228`): README, operations, architecture, threat
+  - `docs(supply-chain)` (`8d59897`): README, operations, architecture, threat
     model, Compose durable env, Helm values/schema/ConfigMap/render tests,
     CHANGELOG.
-  - `feat(webui)` (`02d4f20`, implemented by a delegated worker and reviewed):
+  - `feat(webui)` (`ca1a930`, implemented by a delegated worker and reviewed):
     embedded `/supply-chain` page with the console shell, hash-based CSP,
     session-then-bearer auth, text-node rendering, Go byte-contract and Node
     DOM tests; navigation links in `index.html`/`admin.html`.
-  - `test(supply-chain)` (`0de63e9`): fake GHES → scheduler → collector →
+  - `test(supply-chain)` (`e0620d5`): fake GHES → scheduler → collector →
     PostgreSQL → REST vertical slice, including no-indexed-SHA proof,
     rate-limit/403 outcomes, retained inventory behind a failed refresh,
     cross-installation isolation, and projection.
-  - `docs(supply-chain)` (`5dc15aa`): light/dark screenshots of the real page
+  - `docs(supply-chain)` (`90a1413`): light/dark screenshots of the real page
     rendered in Chromium against a stubbed API (`docs/images/supply-chain-*.png`).
 - 2026-09-22: **M2 complete** (`feat/supply-chain/m2-license-core`): bounded
   SPDX expression parser over the embedded SPDX License List 3.27.0 (fuzzed);
@@ -349,7 +349,7 @@ Detailed task lists are appended when each milestone starts.
 
 ## Validation results
 
-Final worktree head `d110e93` (`feat/supply-chain/m7-operations`), 2026-09-22,
+Final worktree head `b15bed4` (before this note) (`feat/supply-chain/m7-operations`), 2026-09-22,
 macOS arm64, Go 1.27.1, PostgreSQL 18.6 via Compose (reached at the OrbStack
 container address because `docker compose port` reports `invalid IP:0` here),
 Helm 4.x, Node 26, Playwright 1.62.1 with locally installed Chromium.
@@ -378,7 +378,7 @@ Helm 4.x, Node 26, Playwright 1.62.1 with locally installed Chromium.
 | `make image image-test`, `make ui-smoke` via Make (needs `make tools` rebuild) | **not run** (image build not attempted in this pass; the smoke script itself passed) |
 | Live GHES / live registries | **not run**; all GitHub and registry behavior is exercised against fixtures and fake servers |
 
-Commit signing: `629d041`, `559c51f`, `7a1c864` are SSH-signed. The 1Password
+Commit signing: `277730e`, `76dcf7c`, `6b25c6a` are SSH-signed. The 1Password
 SSH agent began refusing sign operations mid-session ("agent refused
 operation"), so every later commit is unsigned. Before publication, re-sign
 with `git rebase --exec 'git commit --amend --no-edit -S' 331fa42` (from the

From 30afa5994add86a0915c8acf220c226444254c6f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?D=C3=A1vid=20Balatoni?= <balcsida@gmail.com>
Date: Tue, 22 Sep 2026 23:16:30 +0200
Subject: [PATCH 5/5] docs(supply-chain): record the published native stack

Co-Authored-By: Claude <noreply@anthropic.com>
---
 docs/execplans/supply-chain.md | 38 ++++++++++++++++++++++------------
 1 file changed, 25 insertions(+), 13 deletions(-)

diff --git a/docs/execplans/supply-chain.md b/docs/execplans/supply-chain.md
index 2ff3a6fc..4231ee25 100644
--- a/docs/execplans/supply-chain.md
+++ b/docs/execplans/supply-chain.md
@@ -413,16 +413,28 @@ forms echoing the `basis` fingerprint, history panel, policy list) to
 on a new layer above `feat/supply-chain/m7-operations`; then run
 `make image image-test` and record results here.
 
-Nothing is published; no PR exists for this work. Suggested PR titles in
-stack order (each layer depends on the one before):
-
-1. `docs(supply-chain): accept ADR-0017 and execution plan` (m0-design)
-2. `feat(supply-chain): preserve GHES SBOM observations as immutable snapshots` (m1-storage)
-3. `feat(supply-chain): inventory service, collector, and REST routes` (m1-service)
-4. `feat(webui): Dependencies & Licenses inventory page` (m1-ui; includes docs, deployment wiring, integration test, screenshots)
-5. `feat(supply-chain): exact-version license evidence and assessments` (m2-license-core)
-6. `feat(supply-chain): portfolio APIs and views` (m3-portfolio)
-7. `feat(supply-chain): SPDX and CycloneDX imports with derived export` (m4-imports)
-8. `feat(supply-chain): policies and review workflow` (m5-review)
-9. `feat(mcp): read-only dependency inventory tools` (m6-mcp)
-10. `feat(supply-chain): retention, operations docs, and query-plan evidence` (m7-operations)
+## Native stack and pull requests
+
+Published 2026-09-22 with `gh stack submit --auto --remote origin` as ten
+draft pull requests linked into native GitHub stack **#114**, rooted at
+`main`; bases, heads, membership, and per-layer deltas were verified after
+submission (remote heads equal local heads; every head commit signature is
+`VALID` on GitHub). Hosted CI (`CI` workflow) passed on all ten branches.
+The repository's "Code scanning AI findings" workflow failed on every PR with
+`CAPIError: 400 The requested model is not supported`; that is a hosted
+Copilot configuration issue unrelated to this change.
+
+| Layer | PR | Base |
+| --- | --- | --- |
+| m0-design | [#104](https://github.com/balcsida/graphnest/pull/104) | `main` |
+| m1-storage | [#105](https://github.com/balcsida/graphnest/pull/105) | #104 |
+| m1-service | [#106](https://github.com/balcsida/graphnest/pull/106) | #105 |
+| m1-ui | [#107](https://github.com/balcsida/graphnest/pull/107) | #106 |
+| m2-license-core | [#108](https://github.com/balcsida/graphnest/pull/108) | #107 |
+| m3-portfolio | [#109](https://github.com/balcsida/graphnest/pull/109) | #108 |
+| m4-imports | [#110](https://github.com/balcsida/graphnest/pull/110) | #109 |
+| m5-review | [#111](https://github.com/balcsida/graphnest/pull/111) | #110 |
+| m6-mcp | [#112](https://github.com/balcsida/graphnest/pull/112) | #111 |
+| m7-operations | [#113](https://github.com/balcsida/graphnest/pull/113) | #112 |
+
+Merging remains a separate owner decision; the PRs are drafts.