Skip to content

docs(data-model): say what provenance means when there is no annotation #91

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mbeacom merged 1 commit into from
Aug 5, 2026
Merged

docs(data-model): say what provenance means when there is no annotation #91

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions specs/010-catalog-backstage/data-model.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -449,6 +449,31 @@ upstream" would be true always and would distinguish nothing.
| `upstream-authored` | The `adrkit.io/owned-paths` annotation was already present in the real upstream descriptor as found. |
| `maintainer-overlay` | The annotation was authored by us and overlaid onto an otherwise-unmodified upstream descriptor. |

**It is a declaration about the SOURCE, not a per-entity derivation — and this is what
makes `annotation-absent` entities representable.** Both rows above describe an annotation
that *exists*, yet `annotation-absent` is the overwhelmingly common real-corpus case: of
156 `community-plugins` descriptor files, **zero** carry the annotation. Neither row is
literally true of such an entity, and an earlier revision of this section did not say what
`provenance` meant for one.

It is not a third value. `provenance` is **declared for the source** as part of the
generation request and carried onto every entity derived from it. For an entity whose
Comment on lines +459 to +460
ownership state is `annotation-absent`, the declaration is carried but **vacuous**: there
is no annotation for it to describe, and the entity makes **no adoption claim** in either
direction.

**Only the pair `(ownershipState, provenance)` is unambiguous.** `provenance` alone is
not, and code that branches on it without the ownership state is reading a claim that may
not have been made. An entity asserts third-party adoption of the annotation **only** when
its ownership state is `explicit-paths` or `explicit-empty` *and* its provenance is
`upstream-authored`.

**The declaration is required and exhaustive; there is no default.** Defaulting to
`upstream-authored` would silently convert an omission into a third-party adoption claim —
exactly the claim ADR-0020 clause 5 and ADR-0014's honesty rules exist to keep honest.
Defaulting to `maintainer-overlay` would be safer but would still fabricate a declaration
nobody made. An absent declaration is invalid input.

That is what makes **FR-043** satisfiable: clause 5's "only the corpus data is
third-party, never the validation" boundary becomes legible from the artifact itself.

Expand Down