Emit ReferrerObserved graph events; add referrer/deletion event model (#199) - #201
Merged
Conversation
Adds the supply-chain-graph vocabulary and ingest for per-artifact observability (#199), and wires the copy-side emission. Model: - New event kinds ReferrerObserved and ArtifactDeleted (schemas + examples, validated). - build-graph-event learns both kinds (content ids match cssc_graph). - cssc_graph ingest: ReferrerObserved -> REFERS_TO(referrer->subject) edge; ArtifactDeleted -> deletion tombstone (deletedAt/deleteReason on the occurrence). Schema DDL adds the REFERS_TO rel table and the Occurrence delete columns. Emission (copy side): - New stage-referrer-events action discovers a subject's referrer closure (index + child manifests, recursively) and stages one ReferrerObserved per (subject, referrer) edge with artifactType. - Wired into _mirror-image and all three promote workflows after the copy; the existing graph-events upload + collector handle the rest. ArtifactDeleted emission (delete path) follows in a companion PR. Refs #199
Contributor
There was a problem hiding this comment.
Pull request overview
Adds end-to-end support for recording referrer relationships (referrer → subject) in the supply-chain graph and introduces a deletion event model/tombstone fields so the indexer/schema won’t break once producers start emitting deletion events.
Changes:
- Introduces new event kinds
ReferrerObservedandArtifactDeletedwith schemas and example records. - Adds graph schema DDL for
REFERS_TOrelationships and Occurrence deletion tombstone fields; extends the Python indexer to ingest the new kinds. - Adds a new
stage-referrer-eventscomposite action and wires it into mirror/promote workflows; extendsbuild-graph-eventto build both new kinds.
Reviewed changes
Copilot reviewed 13 out of 13 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| supply-chain-graph/schema/referrer-observed.schema.json | Adds JSON schema for ReferrerObserved records. |
| supply-chain-graph/schema/artifact-deleted.schema.json | Adds JSON schema for ArtifactDeleted records. |
| supply-chain-graph/examples/referrer-observed.yaml | Adds a validated example ReferrerObserved record. |
| supply-chain-graph/examples/artifact-deleted.yaml | Adds a validated example ArtifactDeleted record. |
| docs/architecture/observability/supply-chain-graph.md | Documents ReferrerObserved as emitted by mirror/promote workflows. |
| apps/python-app/libs/cssc_graph/cssc_graph/indexer.py | Adds ingestion for ReferrerObserved and ArtifactDeleted. |
| apps/python-app/libs/cssc_graph/cssc_graph/graph.py | Adds REFERS_TO rel table and Occurrence deletion columns to schema DDL. |
| .github/workflows/_promote-override.yml | Stages referrer events after promotion and uploads them. |
| .github/workflows/_promote-from-quarantine.yml | Stages referrer events after promotion and uploads them. |
| .github/workflows/_promote-from-quarantine-sbom.yml | Stages referrer events after promotion and uploads them. |
| .github/workflows/_mirror-image.yml | Stages referrer events after mirroring and uploads them. |
| .github/actions/stage-referrer-events/action.yml | New composite action to discover recursive referrer closure and stage ReferrerObserved events. |
| .github/actions/build-graph-event/action.yml | Extends event builder to support ReferrerObserved and ArtifactDeleted. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
- REFERS_TO now keys the merge on observedAt too (append-only, like POINTED_TO) so re-observations aren't collapsed; set only artifactType on the referrer Artifact to avoid clobbering a known mediaType. - ArtifactDeleted uses strict record[...] access for the schema-required deletedAt/reason, matching the other indexers. - Add indexer tests: ReferrerObserved creates a REFERS_TO edge with artifactType; ArtifactDeleted sets the occurrence tombstone.
This was referenced Aug 14, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
First slice of #199 (companion to the merged #200 registry lifecycle).
What
Makes the supply-chain-graph record each referrer artifact, not just the subject image, and lands the data model + ingest for artifact deletions.
Event model (both kinds)
ReferrerObservedandArtifactDeleted: schemas + examples (validated bycssc_graph.validate).build-graph-eventlearns both kinds; content ids matchcssc_graph.identity.content_id(verified end-to-end).cssc_graphingest:ReferrerObserved→REFERS_TO(referrer → subject) edge withartifactType;ArtifactDeleted→ deletion tombstone (deletedAt/deleteReasonon the occurrence). Schema DDL adds theREFERS_TOrel table +Occurrencedelete columns. Adding these now prevents the indexer from breaking when the new events reach the data branch.Emission — copy side (this PR)
stage-referrer-eventsaction discovers a subject's referrer closure (image index + child manifests, recursively — referrers-of-referrers) and stages oneReferrerObservedper (subject, referrer) edge, carryingartifactType; the subject tag is recorded on the index only._mirror-imageand all three promote workflows after the copy. The existinggraph-eventsupload + the genericrecord-graph-eventscollector commit them unchanged.Validation
cssc_graphsuite: 40 passed;graph-service: 16 passed.stage-referrer-events+build-graph-eventscripts: shellcheck clean; recursion/subject/tag logic unit-tested with mocked crane/oras.actionlintclean for the new steps.Follow-up (companion PR, still #199)
ArtifactDeletedemission: extend the delete path to stage a deletion event per removed artifact (image + referrers). Schema/ingest already land here; only the producer wiring remains.Refs #199