docs: address review — normative parameters for identity, scopes, references, projections

ADR-0036: fallback tuples enter identity only post-normalization with
idempotence as the guarded invariant; ordinal ordering is stated
(lexicographic by contradiction key, ties by manifest path then
location); readable-ID parameters fixed (space delimiter, 6-byte sha256
hex suffix, o-decimal ordinals, percent-escaping, last-unescaped-space
decode); the address encoding is byte-fixed (UTF-8, 4-byte big-endian
lengths, tag/identity/occurrence order, zero-length absents, 16-byte
truncation) with golden vectors as a 1.3 deliverable; addresses are
post-consolidation only; silent shortening is prohibited. ADR-0037:
ExternalReference gains Category to round-trip the SPDX triple, hashes
ride the bomly: comment channel in SPDX; complete scope-carrier rules
(sorted deduped list, carrier-beats-scalar, unknown-drop-with-warning,
scalar ingest mapping); the usage join key is (module root, declaration
site) with no cross-site mixing; the merged-document projection is
defined per format (SPDX DESCRIBES-per-root + externalDocumentRef with
checksum, CycloneDX BOM-Link urn:cdx:serial/version) with checksums
captured for every ingested document. ADR-0039: the strict-ingest
guarantee is narrowed to exactly duplicate names and invalid UTF-8.

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

Author: bomly-guy

dev-docs/SDK_MATURITY_PLAN.md

@@ -140,7 +140,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-0036): facet definition, versioned content address, ecosystem-qualified `StableID` successor, `NewDependency` derivation; wire-compat fixtures extended | v0.6.0 |
+| 1.3 | Identity (ADR-0036): facet definition, versioned content address, ecosystem-qualified `StableID` successor, `NewDependency` derivation; the normative ID and address spec with golden test vectors; wire-compat fixtures extended | 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 — a conjunctive filter such as reachable ∧ runtime ∧ direct then joins evidence to locations within one module root, selecting one usage); 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 |
 
@@ -159,7 +159,7 @@ the golden refresh happens **once**:
 | 2.2 | Adopt `spdxkit`: delete `internal/licenseexpr`; the deprecated-ID replacement map relocates into the kit; export/import use kit classification | ADR-0035 stays behavioral truth, now SDK-enforced |
 | 2.3 | Adopt identity: node IDs SDK-derived end to end; regenerate schemas, goldens, smoke; release-notes callout for the one-time ID change | ADR-0036 |
 | 2.4 | **Close #410**: `LicenseRef-*` + `hasExtractedLicensingInfos` emission, mixed-validity composition, canonical ingest coordinates via `SplitEcosystemName`; round-trip asserts `Org`+`Name`+`EcosystemName()` together | Also removes ADR-0035's recorded limitation |
-| 2.5 | **Close #396** on the typed model: ingest populates typed fields through their gates; the export surface takes the prepared entries rather than the bare merged graph, so per-entry document assertions reach the codec; export projects them; merge follows the declared classes; fixed-point test (single-source export → ingest → export byte-stable for preserved fields; a merged export links source identities per ADR-0037); hostile-document fuzz coverage | Deferred #391 items stay deferred per ADR-0037 |
+| 2.5 | **Close #396** on the typed model: ingest populates typed fields through their gates; the export surface takes the prepared entries rather than the bare merged graph, so per-entry document assertions reach the codec; export projects them; merge follows the declared classes; fixed-point test (single-source export → ingest → export byte-stable for preserved fields; a merged export links source identities per ADR-0037, with merged fixtures for both formats validated through the codecs and the official format validators); hostile-document fuzz coverage | Deferred #391 items stay deferred per ADR-0037 |
 | 2.6 | Export full scope sets (fixes survey defect 2) and adopt json/v2 strict ingest with documented rejection behavior | ADR-0039 |
 | 2.7 | Registry-lookup and PURL-fallback helper consolidation across output/render/tui/mcp presentation layers | Survey §3 items 5–6 |
 | 2.8 | Usage-attribution adoption: native detectors record per-site scopes and relationship on locations; the four analyzer repos emit per-module-root reachability evidence (behavioral bumps, not mechanical); CLI filtering, rendering, and MCP join conjunctive filters through attribution; regression test for the workspace case where a package is direct-in-dev in one module and transitive-at-runtime in another | Without producer and consumer migration the 1.4 fields stay empty and the conjunction cannot work |

dev-docs/adr/0036-dependency-identity-is-content-addressable.md

@@ -48,7 +48,12 @@ identity-bearing keys, and URL-valued qualifiers pass the same
 credential/local-path gates as every published URL (ADR-0033), because an
 ingested PURL whose qualifier embeds a token must not become a published ID
 by canonicalization alone. When no PURL is derivable, package identity is
-the coordinate tuple `ecosystem, package manager, type, org, name, version`. The occurrence qualifier distinguishes contradicting
+the coordinate tuple `ecosystem, package manager, type, org, name, version` —
+taken only after `NormalizeDependencyIdentity` has run. The normalization
+pass owns the per-ecosystem case, separator, and format rules; identity adds
+no folding of its own beyond trimming surrounding whitespace, unnormalized
+records never reach identity derivation, and normalization idempotence is
+the stated invariant, guarded by test. The occurrence qualifier distinguishes contradicting
 resolutions of the same package per ADR-0033, but with a stricter admission
 rule than consolidation's current resolution key: only normalized,
 machine-independent, credential-free values enter the facet — the first-party
@@ -74,8 +79,11 @@ varies across machines and credential rotations for the same dependency, and
 hashing does not protect a low-entropy secret from offline guessing. A node
 whose resolution is distinguishable only by raw evidence still gets a
 distinct readable ID within the run, but its discriminator is ephemeral and
-content-free — a per-identity ordinal assigned deterministically during
-consolidation, never a hash of the evidence — because readable IDs are
+content-free — a per-identity ordinal assigned during consolidation in a
+stated order (the contradicting records sorted lexicographically by the
+resolution key that established the contradiction, ties broken by manifest
+path then location; never arrival or map-iteration order), never a hash of
+the evidence — because readable IDs are
 published in scan JSON and SBOMs, and a hash of a machine-specific path or
 low-entropy credential would carry the same instability and offline-guessing
 exposure into the published document. The persistent content address is
@@ -125,18 +133,34 @@ unescaped fallback base like `a@b 1` would be indistinguishable from base
 `a@b` plus suffix `1`. With both families escaping the delimiter, the
 suffix split is unambiguous by structure for every readable ID, and the
 delimiter change rides the same one-time ID change as the rest of this
-decision. What changes is who computes it: `NewDependency`
+decision. The decision-level parameters: the delimiter is a single ASCII
+space; the hash suffix is the first six bytes of the SHA-256 of the
+admitted occurrence facet, lowercase hex; the ordinal form is `o` followed
+by a decimal; fallback fields percent-encode space, percent, and control
+characters before joining; decoding splits on the last unescaped space
+before parsing the base. The full normative grammar, with examples covering
+subpaths, delimiter characters, and percent signs, ships as an SDK spec
+plus golden tests in the identity phase — the ADR fixes the parameters, the
+spec fixes every byte. What changes is who computes it: `NewDependency`
 and one SDK rewrite entry point derive it; detectors and the CLI stop minting
 IDs by string concatenation, and the three divergent rewrite sites collapse
 into one.
 
 **The content address.** The SDK additionally exposes a content address for
 each node: a SHA-256 digest over a versioned canonical encoding of the
-facets — the `bomly:node:v1` tag followed by each facet as a length-prefixed
-field, so the encoding stays injective even when untrusted input contains
-delimiter bytes (a NUL-joined tuple would let `("a\x00b", "c")` and
-`("a", "b\x00c")` collide) — truncated to 128 bits and hex-encoded. The
-version prefix means the facet set can evolve
+facets, and the encoding is fixed at the byte level: facets are UTF-8
+strings, each preceded by a four-byte big-endian length; the field order is
+the `bomly:node:v1` tag, the package identity, the occurrence facet; an
+absent facet is a zero-length field, still length-prefixed. Length prefixes
+keep the encoding injective even when untrusted input contains delimiter
+bytes (a NUL-joined tuple would let `("a\x00b", "c")` and `("a", "b\x00c")`
+collide). The digest is SHA-256 truncated to its first 16 bytes, rendered
+lowercase hex; golden test vectors covering representative and edge-case
+facet sets ship with the SDK implementation so independent implementations
+must agree. The address is defined only over finalized facets: computing it
+is a post-consolidation operation, the SDK exposes it on consolidated
+records, and anything that caches identity earlier must rekey after
+finalization. The version prefix means the facet set can evolve
 by bumping to `v2` without silently changing every stored address. The digest
 is deliberately derived, not stored as model state — it can always be
 recomputed from the facets, so persisting it is an optimization, never a
@@ -165,8 +189,10 @@ of `Dependency` is unchanged.
   address, so an address-keyed store must pair it with a store-local
   occurrence discriminator or persist those nodes at package granularity;
   the SDK documents the address as identifying the stable occurrence class,
-  never as a per-node primary key. Because it is versioned and truncatable,
-  the storage layer may shorten or re-derive it without a model change.
+  never as a per-node primary key. The full 128-bit address is the
+  canonical form everywhere: a store may re-derive it from the facets, but
+  never silently shorten it — a shortened rendering is presentation-only
+  and is never a comparison or storage key.
 - Two hashing choices are deliberately conservative: SHA-256 (already the
   digest of record in `filecache` and `OccurrenceID`), and no use of
   `hash/maphash` (its seeds are per-process, which is exactly what a

dev-docs/adr/0037-sbom-assertions-are-typed-sdk-model-fields.md

@@ -37,8 +37,14 @@ codecs are projections of it, not extensions to it.
 **Component-level fields.** `Dependency` and `Package` (or `Coordinates`
 where identity-adjacent) gain optional `omitempty` fields for supplier,
 originator, description, homepage, and a typed
-`ExternalReference{Type, Locator, Comment, Hashes}` list whose type
-vocabulary covers both formats' reference categories. The locator is typed
+`ExternalReference{Category, Type, Locator, Comment, Hashes}` list whose
+vocabulary covers both formats' reference categories — `Category` preserves
+SPDX's `referenceCategory` alongside the type, so the SPDX triple
+(category, type, locator) round-trips without re-derivation. Reference
+hashes round-trip natively in CycloneDX; SPDX 2.3 has no slot for them, so
+on SPDX export they ride the existing `bomly:` comment channel, and codec
+fixtures cover every supported category and reference hashes in both
+directions. The locator is typed
 by the reference category, not assumed to be a web URL: both formats carry
 non-URL locators — Bomly itself emits `pkg:` PURLs and `cpe:` values as
 SPDX external references today, and advisory references may be bare
@@ -55,11 +61,16 @@ exactly one place and is exercised in both directions — and it is defined
 for the scope *set*, not just a scalar. Both native fields hold one value
 (CycloneDX `scope` is a scalar, and the neutral component model mirrors it),
 so the SDK also defines the scalar projection rule for a multi-scope node
-(runtime presence wins) and the lossless side channel that carries the full
-set — a namespaced `bomly:scopes` CycloneDX property and the existing
-`bomly:scope` SPDX comment field, both read back on ingest — so the scope
-union PR #406 established survives the round trip instead of being
-flattened.
+and the lossless side channel that carries the full set — a namespaced
+`bomly:scopes` CycloneDX property and the existing `bomly:scope` SPDX
+comment field, both read back on ingest — so the scope union PR #406
+established survives the round trip instead of being flattened. The rules
+are complete, not illustrative: the scalar projection is any-runtime →
+`required`, otherwise `excluded`; the carrier is the lexicographically
+sorted, deduplicated, comma-joined list of SDK scope tokens; on ingest the
+carrier wins over the scalar when both are present, unknown tokens are
+dropped with a warning, and a bare scalar maps `required` → runtime and
+`optional`/`excluded` → development.
 
 **Usage facts carry their attribution.** Scope, relationship, and
 reachability answer questions about a *usage*, and filters compose them
@@ -78,10 +89,15 @@ summary of that list. A package present in several module roots is analyzed
 per root, so a singular annotation with one root field could retain at most
 one analysis after vulnerability consolidation; the evidence list keeps
 every record. The conjunctive join is evidence-to-location within the same
-module root — never the summary joined to every location. A conjunctive
-filter then selects usages, and the display shows the dependency path whose
-attribution satisfies every conjunct — instead of a node that satisfies
-each conjunct somewhere.
+module root — never the summary joined to every location. The join key is
+explicit: the usage unit is (module root, declaration site). Scope and
+relationship attach per site and are never combined across sites; a
+conjunctive filter must find its scope and relationship conjuncts on a
+single site, and its reachability on that site's module root — legitimate,
+because reachability is a fact about the module's own code and so covers
+every site within its root. A conjunctive filter then selects usages, and
+the display shows the dependency path whose attribution satisfies every
+conjunct — instead of a node that satisfies each conjunct somewhere.
 
 **Typed edges.** `DependencyEdge` gains an optional relationship kind
 (default depends-on; contains, describes, and the other members both formats
@@ -114,10 +130,20 @@ and one primary component, so a merged document *links* each source's
 identity rather than re-asserting it — SPDX `externalDocumentRefs`,
 CycloneDX an external reference of type `bom` carrying the source serial —
 while component-level assertions are preserved in full. The carrier retains
-what those link forms require, captured at ingest while the original bytes
-are still in hand: for SPDX, the source document namespace and a checksum
-over the original document (an `externalDocumentRef` is invalid without
-both); for CycloneDX, the source serial and version. The fixed-point
+what the link forms require, captured at ingest while the original bytes
+are still in hand — namespace or serial, document version, and a checksum
+over the original bytes, for every ingested document regardless of its
+format. The projection is then defined per output format. SPDX has no
+primary-component field, so the aggregate document `DESCRIBES` each root
+(the existing ADR-0032 mechanism, one relationship per root) and links each
+source via `externalDocumentRef` — the source's namespace, or its serial
+URN when the source was CycloneDX, plus the ingest-computed checksum, since
+the ref is invalid without both. CycloneDX links each source via an
+external reference of type `bom`: a BOM-Link `urn:cdx:<serial>/<version>`
+when the source has a serial (version captured at ingest, defaulting to 1),
+or the source namespace URI when it does not. Merged fixtures for both
+formats are validated through the codecs and the official format validators
+as part of the adoption phase. The fixed-point
 round-trip promise is correspondingly scoped to single-source flows: one
 ingested document re-exported reproduces its own assertions; a merged
 export preserves component assertions and references its sources.

dev-docs/adr/0039-both-modules-build-on-go-1-27.md

@@ -37,9 +37,12 @@ the CLI moves with it.
 **Strict parsing for untrusted documents.** Parsers of untrusted input —
 SBOM ingest first, baseline and plugin-manifest codecs as they are touched —
 move to `encoding/json/v2` with duplicate-name rejection and UTF-8 validity
-enforced. A document that two readers could disagree about is rejected with
-an actionable error, and the change is documented as deliberate behavior in
-`docs/SBOM.md`. The plugin wire (`bomly.plugin.v1`) keeps its current
+enforced. The guarantee is exactly those two ambiguity classes — a document
+with duplicate object names or invalid UTF-8 is rejected with an actionable
+error. Other reader-divergence classes (case-variant field matching, for
+one) are not covered by json/v2's defaults and are not claimed here; closing
+any of them would be its own validation with its own decision. The change is
+documented as deliberate behavior in `docs/SBOM.md`. The plugin wire (`bomly.plugin.v1`) keeps its current
 decoding semantics: its compatibility contract is frozen fixtures, not
 strictness, and tightening it is a protocol decision that would need its own
 ADR.