docs(data-model): say what provenance means when there is no annotation - #91
Merged
Conversation
Phase E found a genuine gap in the two-value provenance domain decided on 2026-08-05. Both table rows describe an annotation that EXISTS - upstream-authored and maintainer-overlay - but annotation-absent is the dominant real-corpus case: zero of 156 community-plugins descriptor files carry the annotation. Neither row was literally true of such an entity, and this section did not say what provenance meant for one. The fix is not a third value. provenance is a declaration about the SOURCE, made as part of the generation request and carried onto every entity derived from it. For an annotation-absent entity it 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. Code branching on provenance alone is reading a claim that may not have been made. An entity asserts third-party adoption only when its ownership state is explicit-paths or explicit-empty AND its provenance is upstream-authored. The declaration is required and exhaustive, with no default in either direction. Defaulting to upstream-authored would silently convert an omission into a third-party adoption claim, which is exactly what ADR-0020 clause 5 and ADR-0014's honesty rules exist to prevent. Defaulting to maintainer-overlay would be safer but would still fabricate a declaration nobody made. Phase E reached the same shape independently and did not invent a third value, adding isAdoptionClaim(ownershipState, provenance) instead. This records the reasoning in the contract so the next reader does not have to re-derive it. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Clarifies provenance semantics for entities without ownership annotations.
Changes:
- Defines provenance as a required source-level declaration.
- Clarifies adoption claims require both ownership state and provenance.
- Documents why provenance has no default.
Comment on lines
+459
to
+460
| 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 |
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.
Phase E found a genuine gap in the two-value
provenancedomain decided on 2026-08-05 — a flaw in the decision, not in the implementation.The gap
Both values describe an annotation that exists:
upstream-authoredmaintainer-overlayBut
annotation-absentis the dominant real-corpus case — zero of 156community-pluginsdescriptor files carryadrkit.io/owned-paths. Neither row was literally true of such an entity, and §10 did not say what the field meant for one.The fix is not a third value
provenanceis a declaration about the source, made as part of the generation request and carried onto every entity derived from it. For anannotation-absententity it 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. Code branching onprovenancealone is reading a claim that may not have been made. An entity asserts third-party adoption only when its ownership state isexplicit-pathsorexplicit-emptyand its provenance isupstream-authored.The declaration is required and exhaustive, with no default. Defaulting to
upstream-authoredwould silently convert an omission into a third-party adoption claim — exactly what ADR-0020 clause 5 and ADR-0014's honesty rules exist to prevent. Defaulting tomaintainer-overlaywould be safer but would still fabricate a declaration nobody made. An absent declaration is invalid input.Why this shape
Phase E reached it independently and did not invent a third value, adding
isAdoptionClaim(ownershipState, provenance)instead. This records the reasoning in the contract so the next reader does not have to re-derive it from the implementation.It also preserves the property that made the two-value domain worth having: since every corpus today is
maintainer-overlay,upstream-authoredonly becomes reachable if real adoption occurs — the field stays a live adoption signal rather than dead metadata.adr lint20 records, 0 errors. Specs only; no code.