docs: address review — qualifiers are identity, gaps stay distinct, suffixes hash the origin

Three reviewer-directed corrections. Qualifiers stay in published IDs —
the PURL spec defines them as qualifying data and container scans carry
one package/version under two architectures — with only the spec's
URL-valued evidence keys (repository_url, download_url, vcs_url) stripped
to Origin behind the ADR-0033 gates. An unknown origin is its own
occurrence, never a gap consolidation fills (manufacturing provenance);
ecosystem detectors may fill gaps at detection time where their semantics
justify it. Occurrence suffixes derive from a short hash of the
occurrence's own normalized origin, stable under occurrence-set changes
where positional ordinals would renumber published bom-refs; run-local
ordinals remain only for the rare raw-evidence-only contradictions, with
the run-scoped caveat stated.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: bomly-guy

dev-docs/SDK_MATURITY_PLAN.md

@@ -104,10 +104,12 @@ One sentence per decision; the ADRs carry the detail.
 
 - **Identity** (ADR-0041): a sealed typed node union — manifest, module,
   and dependency nodes — where a dependency node's identity is its
-  canonical PURL (valid by the PURL specification's own rules, missing
-  versions warned), the occurrence qualifier is the normalized origin, and
-  comparison is a kind-scoped equals/key pair with ADR-0033 gap-filling;
-  IDs and ordinals minted only by SDK entry points; no content address.
+  canonical PURL with qualifiers (valid by the PURL specification's own
+  rules, missing versions warned, URL-valued evidence qualifiers redirected
+  to Origin), the occurrence qualifier is the normalized origin (unknown
+  origin is its own occurrence; gap-filling is a detector decision), and
+  comparison is a kind-scoped equals/key pair; origin-hash suffixes and
+  ordinals minted only by SDK entry points; no content address.
 - **Model** (ADR-0037): every preserved SBOM assertion is a typed,
   `omitempty`, boundary-validated field with a declared merge class; typed
   edges; a per-entry document-assertions carrier on `GraphEntry`; `Metadata`
@@ -144,7 +146,7 @@ Breaking in-process changes are allowed (v0 policy); the wire stays additive
 |---|---|---|
 | 1.1 | `purlkit`: qualifiers/subpath-capable build/parse/canonicalize; the single purl-type ↔ ecosystem table (hex non-mapping recorded); `SplitEcosystemName`; canonical-ID rewrite entry point; import-boundary guard | v0.5.0 |
 | 1.2 | `spdxkit`: absorb `internal/licenseexpr` semantics (panic guards, `Valid`/`ValidateAll`/`Identifier`/`Compose`/`Satisfies`/`Extract`); deprecated-ID canonicalization via the audited replacement map relocated from `internal/sbom/transform.go` (the list marks deprecation; the map owns replacements); classification-by-validation; deterministic `LicenseRef-*` minting + extracted-text pairing; fix `matcherkit.NormalizeLicenseSet` to classify on write | v0.5.0 |
-| 1.3 | Identity (ADR-0041, superseding ADR-0036): sealed `GraphNode` union — manifest / module / dependency nodes (dependency nodes require a spec-valid canonical PURL, missing version warned; modules are the project's own artifacts; manifests structural, path-identified, never matched); kind-scoped identity equals/key over (canonical PURL, normalized origin) with ADR-0033 gap-filling; PURL identity-form readable IDs with per-PURL deterministic ordinals from 1 for coexisting occurrences; single insertion + finalization entry points; wire flat-node shape plus additive `kind` discriminator with frozen explicit/legacy/conflicting/unknown fixtures; no content address | v0.6.0 |
+| 1.3 | Identity (ADR-0041, superseding ADR-0036): sealed `GraphNode` union — manifest / module / dependency nodes (dependency nodes require a spec-valid canonical PURL, missing version warned; modules are the project's own artifacts; manifests structural, path-identified, never matched); kind-scoped identity equals/key over (canonical PURL, normalized origin) — unknown origin is a distinct occurrence, gap-filling is an ecosystem-detector decision; qualifier-carrying PURL readable IDs (URL-valued evidence qualifiers stripped to Origin) with stable origin-hash suffixes for coexisting occurrences and run-local ordinals only for raw-evidence-only contradictions; single insertion + finalization entry points; wire flat-node shape plus additive `kind` discriminator with frozen explicit/legacy/conflicting/unknown fixtures; no content address | v0.6.0 |
 | 1.4 | Model fields (ADR-0037): supplier/originator/description/homepage; `ExternalReference`; `PackageLicense` declared/concluded + extracted text; digest-algorithm registry; set-aware scope ↔ CycloneDX mapping with its scalar projection rule; typed `DependencyEdge.Kind` with a kind-preserving edge-copy/rename primitive for graph reconstruction sites; usage attribution (`PackageLocation` carries per-site scopes and relationship so the node-level union becomes derived; reachability becomes repeatable per-module-root evidence with the vulnerability annotation as derived summary, and evidence may carry optional `DependencyRefs` to the exact occurrence nodes where the analyzer can attribute — a conjunctive filter such as reachable ∧ runtime ∧ direct then joins evidence to locations within one module root, selecting one usage); a derived package → nodes reverse-index helper (the stored truth stays `Dependency.PackageRef`; the registry remains position-free); per-`GraphEntry` document assertions; per-field-class merge helpers; boundary validation codecs + fuzz targets for every new parser | v0.7.0 |
 | 1.5 | Metadata policy: document reserved `bomly.` prefix; deprecate `MetadataKeyDetectionLicenses` in favor of the typed license field | v0.7.0 |
 

dev-docs/adr/0041-identity-is-the-canonical-purl-on-typed-nodes.md

@@ -78,20 +78,29 @@ the same warning policy; a module that cannot mint a PURL falls back to
 path-based identity like a manifest, because it is the project's own
 record, not a registry lookup key.
 
-**The occurrence qualifier is the normalized origin, and comparison
-preserves the gap-fill rule.** The occurrence half of identity is the
+**The occurrence qualifier is the normalized origin, and an unknown origin
+is its own occurrence.** The occurrence half of identity is the
 ADR-0033-normalized `Origin` already on the node — no new storage, no
-facet renderings, no hashes — which makes comparison wire-stable by
-construction, since it uses exactly the view the JSON codec persists. The
-SDK exposes the Java-style pair — an identity-equality predicate and an
-identity key for map grouping — with a three-way origin relation rather
-than naive equality, so ADR-0033's folding semantics survive:
+facet renderings — which makes comparison wire-stable by construction,
+since it uses exactly the view the JSON codec persists. The SDK exposes
+the Java-style pair — an identity-equality predicate and an identity key
+for map grouping — with a three-way origin relation:
 
 - both records carry normalized origins and they are equal → the same
   occurrence; witnesses fold;
-- exactly one record carries an origin → a gap; the gap witness folds into
-  the origin-bearing record (ADR-0033's fill rule, unchanged);
-- both carry origins and they differ → distinct occurrences that coexist.
+- both carry origins and they differ → distinct occurrences that coexist;
+- exactly one record carries an origin → distinct occurrences. An absent
+  origin means "resolution unknown", which is a claim of its own, not a
+  gap for consolidation to fill: folding it into whichever origin-bearing
+  record appeared first would manufacture provenance the witness never
+  asserted. This deliberately narrows ADR-0033's consolidation-time
+  fill rule; where an ecosystem's semantics genuinely justify filling —
+  one lockfile entry split across records — that ecosystem's detector
+  fills the gap at detection time, before consolidation, where the
+  context to justify it exists. Two records that both lack origins fold
+  when nothing else distinguishes them, and stay distinct when raw
+  resolution evidence proves they differ (raw evidence is legal for
+  comparison, never for identity or publication).
 
 Comparison is kind-scoped: nodes of different kinds are never equal, so a
 module node and a dependency node sharing a PURL — or sharing the absence
@@ -102,24 +111,35 @@ Keys are in-process comparison values, kind-prefixed, and never appear in
 scan JSON, SBOMs, or any published document.
 
 **Readable IDs need no grammar of their own.** A dependency node's graph ID
-is its canonical PURL in identity form: qualifiers pass only through
-purlkit's identity-qualifier allowlist — empty today, so all are dropped —
-and the subpath is preserved. That gate exists because imported PURLs can
-carry resolution evidence and credentials in qualifiers
-(`repository_url=…`, signed download links), and node IDs are published as
-SBOM component identifiers; admitting the first allowlist key is a
-reviewed act that ships the ADR-0033 credential gates with it. When
-distinct occurrences of one canonical PURL must coexist, every one of them
-carries a deterministic run-local ordinal suffix — a single space and `o`
-plus a decimal. Numbering starts at 1, is scoped per canonical PURL, and
-is assigned in the sorted order of the occurrences' identity keys — never
-arrival order, never a hash of evidence; golden tests pin the assignment
-when the implementation lands. Raw resolution evidence (the verbatim
-`ResolvedURL`, tokenized URLs) never reaches an ID. Module and manifest
-nodes use their path-derived identities. The insertion entry point still
-parks contradicting records under an ephemeral in-process discriminator
-(NUL-marked, structurally disjoint from every readable ID) until
-consolidation finalizes them; the ephemeral form never reaches output.
+is its canonical PURL — qualifiers and subpath included, because the PURL
+specification defines qualifiers as qualifying data (`arch`, `distro`,
+`upstream`, `epoch`, `classifier`, …) and container scans genuinely carry
+one package/version under two architectures: dropping qualifiers would
+collide identities the spec keeps distinct. The exception is the
+specification's URL-valued evidence keys — `repository_url`,
+`download_url`, and `vcs_url` — whose values are resolution evidence that
+can embed credentials and signed links: identity normalization strips them
+from the PURL and their content belongs in `Origin`, behind the ADR-0033
+gates, so they shape the occurrence, never a published ID. When distinct
+occurrences of one canonical PURL must coexist, each origin-bearing
+occurrence carries a deterministic suffix — a single space and a short
+lowercase-hex hash of its kind-prefixed normalized origin. Deriving the
+suffix from the occurrence's own origin keeps IDs stable when the
+occurrence set changes: adding or removing a sibling never renumbers the
+others, which positional ordinals could not promise, and the normalized
+origin is already credential-free, so the hash publishes nothing the
+origin field does not. Occurrences distinguishable only by raw evidence
+have nothing publishable to hash; they carry run-local ordinal suffixes
+(`o1`, `o2`, … in sorted raw-key order) with the stated caveat that this
+rare class is run-scoped and not stable across evidence changes — never a
+hash of raw evidence, because raw resolution strings (the verbatim
+`ResolvedURL`, tokenized URLs) never reach an ID in any form. Module and
+manifest nodes use their path-derived identities. The insertion entry
+point still parks contradicting records under an ephemeral in-process
+discriminator (NUL-marked, structurally disjoint from every readable ID)
+until consolidation finalizes them; the ephemeral form never reaches
+output. Golden tests pin the suffix derivation and ordinal assignment when
+the implementation lands.
 
 **The wire stays inside `bomly.plugin.v1`, with a specified discriminator.**
 Nodes keep their flat JSON shape and gain one additive `omitempty` `kind`
@@ -154,10 +174,11 @@ not lost.
 - The review-hardened invariants from the closed first round survive as
   behavior and tests, not machinery: ownership survives folds (now by
   construction — kinds never cross-fold, and the cross-entry merge helper
-  must preserve module identity the same way), ordinals are never
-  recycled, identity comparison is stable across the plugin wire, raw
-  evidence is never provenance for a suffix, and discriminator
-  vocabularies fold before derivation.
+  must preserve module identity the same way), origin-derived suffixes are
+  stable under occurrence-set changes, identity comparison is stable
+  across the plugin wire, raw evidence is never provenance for a
+  published suffix, and discriminator vocabularies fold before
+  derivation.
 - ADR-0036 is superseded; the identity phase of `SDK_MATURITY_PLAN.md`
   (item 1.3) and every other identity reference in that plan are rescoped
   to this decision.