…de/adopt-sdk-0.9.5

Test on this PR fails on a collision inherited from main, not on anything
this branch changed: #436's module-boundary guard reports #437's
presentation guard, which has to spell packageurl-go in order to forbid
it. #444 fixes it. Merging that branch in so this PR's CI reflects its own
changes; the merge collapses when #444 lands on main.

Co-Authored-By: Claude Opus 5 <[email protected]>

main is red: #436 tightened TestNoDirectPackageURLUse while #437 added
internal/output/registry_lookup_guard_test.go, whose own forbidden-string
literal names the module the other guard forbids, so the two guards report
each other. The failure is inherited by every branch cut from main,
including this one, and is unrelated to the digest vocabulary change here.

#444 fixes it and is green. Merging that branch rather
than writing a second fix: it is the same commit, so when #444 lands on
main this history dedupes with no conflict, and #443 never carries a
competing version of the same fix. It touches only
internal/detectors/guards_test.go, which this PR does not.

Co-Authored-By: Claude Opus 5 <[email protected]>

* feat(sbom): adopt SDK v0.9.5 and close the five limitations it unblocks

Five gaps in the SBOM preservation work were documented in code and in
docs/SBOM.md with an SDK issue attached to each, because the fix belonged
in the shared model rather than here (ADR-0040). SDK v0.9.5 ships all
five, so this consumes them and removes the notes.

**The description gate is idempotent again (sdk#54).** A gate that repairs
invalid UTF-8 and then bounds the result can push a value past its own
bound, so the next pass empties it: a description survived one conversion
and vanished on the next. `internal/sbom/graph.go` carried a local
normalize-until-it-settles loop for exactly that, with an instruction to
delete it when the fix shipped. It is gone; the ingest path calls the SDK
gates directly, and a regression test pins the fixed-point property with
the input that found the defect.

**A merged SPDX document names its sources (sdk#55).** SPDX links a
document through externalDocumentRefs, and section 6.6 requires a checksum
over that document's bytes on every entry -- so ADR-0042 shipped the
CycloneDX half and left the SPDX half open. `DocumentAssertions` now
carries a document version and a source checksum, and ingest computes that
checksum where the original bytes are: once, in the codec entry point, for
every format including one added later. It cannot be recovered from the
parsed model afterwards, which is why it has to be captured there.

**A source document's own scope word survives (sdk#57).** A component a
CycloneDX document marked `optional` imported as runtime and re-exported as
`required` -- a claim about shipping code that the source deliberately had
not made -- because the model had nowhere to keep a source-asserted scope
beside the derived set. `DependencyNode.SourceScope` is that slot, and
`CycloneDXScopeForExport` decides when the word is re-emitted and when the
projection is. That decision stays the SDK's: it is the same mapping that
read the word in, and a second copy here is how the two directions came to
disagree before.

**Source links are read back (sdk#61).** They were write-only: an export
wrote them and ingest read nothing, so converting a merged document again
produced one that claimed to be built from nothing.
`DocumentAssertions.Sources` gives them a home, both codecs read and
re-emit them, and each source contributes its own link tuple plus the
tuples it recorded -- the SDK's declared merge class for the set, not a
rule re-decided here. The CycloneDX `bom` reference now carries the
checksum too, so a merged CycloneDX document converted to SPDX can still
name every source.

**An unreadable scope token no longer unscopes a component (sdk#64).** The
strict decode was a forward-compatibility trap: one token a newer Bomly
wrote made an older one drop the whole assertion, and SPDX has no native
scalar to fall back on, so the loss there was total. The lenient read keeps
the scopes this build knows and reports the rest; the SBOM detector turns
them into a warning naming the file, which is the channel the ingest path
has -- the codec has no logger and the SDK deliberately does not log.

Delegation check: every rule here is the SDK's or a pinned library's --
the scope vocabulary and carrier, the link tuple and its gates, folding and
bounding, the BOM-Link grammar (cyclonedx-go), the digest registry and its
SPDX spelling, and tools-golang's `DocumentRef-` prefixing. One decline is
recorded in the code: nothing mints an SPDX idstring from a document
identity, so the reference id reuses this package's existing package-id
rule with its collision suffix.

Co-Authored-By: Claude Opus 5 <[email protected]>

* fix(sbom): the SPDX digest spelling comes from the registry, not a local switch

A hand-written switch here knew nine algorithms against the SDK registry's
nineteen, so a document carrying BLAKE2b, BLAKE3, MD2, MD4, MD6, ADLER32 or
Streebog had that checksum silently dropped on export. Correct the day it
was written, quietly lossy once the vocabulary grew.

This is the failure the delegation rule exists to prevent, and Streebog is
the example it cites -- the registry now contains exactly those two
constants, and this table did not. Adopting v0.9.5 left the package with
two mappings for one vocabulary, which is the moment to delete the older
one rather than note it.

The guard is differential rather than another list: it walks
sdk.DigestAlgorithms() and requires every algorithm SPDX defines a spelling
for to render as that spelling. Referencing constants would make a rename a
compile error and do nothing about an addition, which is how the gap opened.
An algorithm SPDX does not define still renders empty; that is the format's
limit, not a gap in the mapping.

Co-Authored-By: Claude Opus 5 <[email protected]>

* feat(sbom): move to SDK v0.9.7 and settle the scope contract

v0.9.6 and v0.9.7 close three more of the issues this work filed, and one
of them resolves a disagreement this repo had recorded as open.

The scope one is a contract change, not a bump. ADR-0037 said a bare
CycloneDX `optional` means development; the SDK read it as runtime, and
the conflict was written into that ADR rather than settled in passing.
It is settled now in the ADR's favour, so the test that pinned the SDK's
old reading flips and the clarification note records the resolution.

The objection that made it a real question was answered rather than
overruled, which is worth keeping in view: what risked hiding a shipped
dependency was never `optional` but the *unasserted* case, and that now
reads as runtime explicitly. A component nobody classified is no longer
the one that disappears from `--scope runtime`.

TestSourceScopeYieldsToTheProjectionWhenTheSetChanges needed its premise
repaired rather than its expectation. It added development to a set the
word "optional" now already describes, so nothing changed and the word
was rightly re-emitted -- it adds runtime now, which is a set the word
genuinely no longer describes.

Also in: a single-segment Go module mints pkg:golang instead of
pkg:generic, so go4.org and its like stop missing golang advisories.
No goldens move -- no smoke fixture depends on such a module, which is
precisely why a self-scan found it and the suite did not.

Co-Authored-By: Claude Opus 5 <[email protected]>

* refactor(sbom): the purl-type to ecosystem join is the SDK's

v0.9.7 exports EcosystemForPURLType, which closes the decline recorded
when three drifted copies of this mapping were consolidated into one:
the SDK answered the question already and kept it unexported, so the CLI
could hold one copy instead of three but not zero.

What stood here was not a table but a reassembly -- purlkit calls plus a
fallback of this package's own -- which is the same drift in a thinner
disguise. The SDK had grown a second lookup for manager-name aliases and
this had not, so "swiftpm" resolved to unknown here and to swift there.
A differential run over thirty-nine inputs found that one difference and
nothing else, which is why delegating is an improvement rather than a
behavior change made on purpose.

Co-Authored-By: Claude Opus 5 <[email protected]>

* fix(sbom): the CycloneDX digest spelling comes from the registry too

The mirror of the SPDX fix earlier in this branch, and the same defect in
two shapes one file apart.

A hand-written switch knew eight algorithms against the registry's
nineteen, so a component carrying BLAKE2b, BLAKE3 or Streebog had its
checksum silently dropped. And the external-reference path cast the SDK
token straight into CycloneDX's enum, writing "sha256" where the schema
says "SHA-256" -- invalid for every algorithm, not only the ones the
format has no name for. That cast predates this branch.

Both render through DigestAlgorithm.CycloneDXName() now, and an algorithm
CycloneDX does not define is omitted rather than written in a spelling the
schema rejects: MD2, MD4, MD6 and ADLER32 are SPDX spellings with no
CycloneDX equivalent.

The guard is differential, walking sdk.DigestAlgorithms(), so an algorithm
added upstream fails a test instead of vanishing -- the same shape as the
SPDX guard, which is what made this one easy to see.

Also corrects the scope line in docs/SBOM.md: optional and excluded both
read as development, per the resolution recorded in ADR-0037.

Co-Authored-By: Claude Opus 5 <[email protected]>

* test(smoke): refresh the swiftpm golden for an upstream release

swift-http-types moved 1.7.0 -> 1.8.0 upstream. Unrelated to this branch
and the drift #425 tracks; committed only so the suite is green, and kept
as its own commit so it reads as what it is.

Nothing else moved. The digest change in this branch touched no golden at
all, which says no smoke fixture carries an external-reference hash --
worth a fixture, since that is the path the cast was corrupting.

Co-Authored-By: Claude Opus 5 <[email protected]>

* fix(test): a guard file may name the module it forbids

main is red. #436 and #437 each added a guard and merged independently:
the presentation-layer guard has to spell packageurl-go in order to ban
it, and the module-boundary guard reports any file under internal/ that
names it. Two rules doing their job, one flagging the other.

The exemption is a set of canonical paths now. Not a name -- exempting
anything called guards_test.go was the earlier bug in this same line, and
it hid a forbidden import in a second guard file. Not one hard-coded path
either, which is what made the guards collide the moment a second one
existed.

Adding a guard costs one line in that set, deliberately: a new exemption
should be an edit somebody reviews, not a pattern that widens on its own.

The predicate is extracted so the property can be pinned rather than
described. TestGuardExemptionIsByPathNotByName fails if a file becomes
exempt for being *named* like a guard, and if an entry names a file that
no longer exists -- a dead exemption is a rule nobody is applying. The
first mutation I ran against the old shape passed, which is how the
missing test surfaced.

Co-Authored-By: Claude Opus 5 <[email protected]>

---------

Co-authored-by: Claude Opus 5 <[email protected]>

…les (#443)

* fix(sbom): the digest vocabulary is the SDK registry's, not local tables

Both SBOM formats close their hash enumeration, so an algorithm Bomly
cannot name in the target format cannot be published at all -- which makes
the mapping, not the encoder, the thing that decides whether a digest
survives export. This package had three transcriptions of that mapping and
a fourth site that skipped it, and between them they dropped or corrupted
every algorithm registered after the switches were written.

bomly-sdk v0.9.5 owns the vocabulary in digest.go: ParseDigestAlgorithm
resolves any spelling to the canonical token, SPDXName and CycloneDXName
render each format's, and the registry references spdx/tools-golang's and
cyclonedx-go's own constants rather than copying them -- guarded upstream
by digest_registry_test.go, so a member added to either specification
fails a build instead of disappearing at runtime.

  - spdxChecksums delegated; spdxChecksumAlgorithm deleted. It omitted
    BLAKE2b-256/384/512, BLAKE3, MD2, MD4, MD6, and ADLER32, all of which
    SPDX 2.3 defines, so a document carrying one lost its checksum.
  - cycloneDXHashes delegated; cycloneDXHashAlgorithm deleted. Same shape,
    same omissions, plus Streebog -- the pair this defect class already
    cost once. It now also drops the SPDX-only members (SHA224, MD2, MD4,
    MD6, ADLER32) that an ingested SPDX document can carry, rather than
    writing an algorithm CycloneDX does not define.
  - cycloneDXEmittedHashes wrote the SDK's canonical token straight into
    cdx.Hash.Algorithm, so reference hashes exported as "sha256" where the
    schema says "SHA-256" and an ingested document changed on its second
    export. This is the ExternalReferenceCategory.SPDXName defect in the
    digest vocabulary; it now renders through CycloneDXName.
  - digestHexSizes is keyed by the canonical token instead of listing a row
    per spelling. The lengths stay local -- the SDK deliberately records no
    per-algorithm value length, because ecosystems publish digests in hex,
    in base64, and over subjects that are not files -- but the spellings
    were a fourth copy of the vocabulary.

publishableDigest gives the rule one home: resolve the algorithm, render it
in this format, or omit the digest. Both encoders pass a method expression,
so they ask the same registry the same question and only the rendering
differs.

TestExportProjectsEveryRegisteredDigestAlgorithm is the guard. Referencing
constants makes a rename a compile error but says nothing about an
addition, and an addition is how Streebog was lost: the test enumerates
sdk.DigestAlgorithms() and asserts each member either exports in its
format's spelling or is absent from that format, so a switch written back
in by hand fails here rather than in a user's document.

The three defect tests were confirmed to fail against the pre-change code.
No golden moves: the goldens carry only sha1/sha256/sha512, whose spellings
are unchanged, and the three SBOM smoke tests pass against them.

Co-Authored-By: Claude Opus 5 <[email protected]>

* fix(test): a guard file may name the module it forbids

main is red. #436 and #437 each added a guard and merged independently:
the presentation-layer guard has to spell packageurl-go in order to ban
it, and the module-boundary guard reports any file under internal/ that
names it. Two rules doing their job, one flagging the other.

The exemption is a set of canonical paths now. Not a name -- exempting
anything called guards_test.go was the earlier bug in this same line, and
it hid a forbidden import in a second guard file. Not one hard-coded path
either, which is what made the guards collide the moment a second one
existed.

Adding a guard costs one line in that set, deliberately: a new exemption
should be an edit somebody reviews, not a pattern that widens on its own.

The predicate is extracted so the property can be pinned rather than
described. TestGuardExemptionIsByPathNotByName fails if a file becomes
exempt for being *named* like a guard, and if an entry names a file that
no longer exists -- a dead exemption is a rule nobody is applying. The
first mutation I ran against the old shape passed, which is how the
missing test surfaced.

Co-Authored-By: Claude Opus 5 <[email protected]>

* fix(sbom): put export digests through the SDK's gate, not a weaker one

publishableDigest checked the algorithm and a non-empty value, which is a
weaker gate than the one ingest clears in ingestedDigests. Component digests
can be built in memory by a detector or a plugin without ever passing
through the SDK's JSON hooks, so a value carrying a control character, an
interior Unicode space, or invalid UTF-8 reached the encoders intact. That
matters most for the algorithms this branch newly admits, which were
previously dropped for want of a mapping. encoding/json rewrites invalid
UTF-8 as U+FFFD, so such a digest changes as it is serialized -- a digest
that changes when written is worse than no digest.

Digest.Normalized is now the gate, so ingest and export clear the same one.
What it deliberately does not check is length per algorithm: ecosystems
publish digests in hex, in base64 (npm SRI), and over subjects that are not
files (a Go module "h1:" dirhash), so a per-algorithm hex length would
reject values that are correct for their ecosystem. The new test asserts
both directions -- malformed values dropped, a base64 SRI value published.

Also pins where CycloneDX spec-version scoping lives. Streebog is a 1.7
addition, so a 1.6 document naming it carries a value outside a closed
enumeration -- but cyclonedx-go already owns that conversion: EncodeVersion
converts through SpecVersion.supportsHashAlgorithm and strips a hash the
requested version cannot name. Verified against the encoder's actual output
across all four targets rather than argued from the mapping's shape. A
version table in publishableDigest would be a second copy of the library's,
wrong the day CycloneDX adds an algorithm -- the defect this whole change
removes.

Co-Authored-By: Claude Opus 5 <[email protected]>

---------

Co-authored-by: Claude Opus 5 <[email protected]>

* fix(test): a guard file may name the module it forbids

main is red. #436 and #437 each added a guard and merged independently:
the presentation-layer guard has to spell packageurl-go in order to ban
it, and the module-boundary guard reports any file under internal/ that
names it. Two rules doing their job, one flagging the other.

The exemption is a set of canonical paths now. Not a name -- exempting
anything called guards_test.go was the earlier bug in this same line, and
it hid a forbidden import in a second guard file. Not one hard-coded path
either, which is what made the guards collide the moment a second one
existed.

Adding a guard costs one line in that set, deliberately: a new exemption
should be an edit somebody reviews, not a pattern that widens on its own.

The predicate is extracted so the property can be pinned rather than
described. TestGuardExemptionIsByPathNotByName fails if a file becomes
exempt for being *named* like a guard, and if an entry names a file that
no longer exists -- a dead exemption is a rule nobody is applying. The
first mutation I ran against the old shape passed, which is how the
missing test surfaced.

Co-Authored-By: Claude Opus 5 <[email protected]>

* fix(test): a guard names the module it forbids, not every module

Codex found the hole and it reproduced: the path-keyed exemption excused a
guard file from *every* module rule, not from the one it states. The
presentation-layer guard must spell packageurl-go, and was thereby also
free to name go-spdx and the deprecated anchore fork with nothing
reporting it. Appending both to that file left all guards green.

The table maps a guard to the modules it is entitled to name, and
guardMayName takes the module under test. internal/output's guard forbids
one module, so it may name one. This file states every rule, so it names
every module. The three module paths are constants now, shared by the
forbidding rule and the exemption -- spelled twice, a typo would have
opened a hole in the passing direction.

TestGuardExemptionIsByPathAndPerModule replaces the by-path-not-by-name
test and keeps that half. It also fails if a guard is entitled to a module
it never names: an unused entitlement is a dead rule, the same way a path
that no longer exists is.

Mutations: the original probe now fails both module rules; a predicate
ignoring the module fails; a predicate matching the base name fails.

Co-Authored-By: Claude Opus 5 <[email protected]>

* fix(test): an entitlement covers naming a module, not importing it

Codex again, and it reproduced again. Adding a real import of
packageurl-go to the entitled guard file left every guard green: this
rule skipped the file for that module, and internal/output's own guard
skips _test.go, so nothing was looking at the one file allowed to say the
name.

Naming and importing are different acts. A guard spells the module in a
string so it can forbid it; an import is the hazard the rule exists to
prevent. The entitlement now covers only the first.

go/parser answers what a file imports. A textual scan cannot tell the two
apart -- it reads this file's own const block as an import, which is the
distinction the whole fix rests on. The prefix match carries its
separator because a module path is not always the import path: go-spdx is
reached as go-spdx/v2/spdxexp.

TestNamingAModuleIsNotImportingIt pins the predicate on fixtures rather
than on the repository, in four directions: a const and a comment are not
an import, a blank import is, a subpackage import reaches the module, and
a neighbour sharing the path prefix does not. The live guard files are
asserted not to import what they are entitled to name.

Mutations: the original probe now fails both the walker and the
assertion; an entitlement ignoring imports fails; a prefix match without
its separator fails.

Co-Authored-By: Claude Opus 5 <[email protected]>

* fix(test): one declaration of what is forbidden, read from three sides

CodeRabbit caught both halves of a drift I introduced. The last change
hoisted the module paths into constants and said the rule and the
exemption now shared them -- and then left TestNoDirectPackageURLUse
scanning its own duplicated literals. The table used the constants, the
rule used the strings, and nothing compared them.

The other half made it invisible. The entitlement check asked whether the
guard file's text contained the module, and this file declares all three
constants, so the check passed no matter which modules any rule actually
scanned. A guard that guards nothing, for the fifth time in this file.

forbiddenModules maps each module to the rule that forbids it. Both rules
take their lists from it, guardFiles grants exemptions against its keys,
and the entitlement test validates against them: an entitlement for a
module no rule forbids is a licence to import something nothing bans.

What it still does not prove is that each named rule exists and runs. Go
cannot ask that without depending on test ordering, which breaks under
-run, so the comment says so rather than implying more.

Mutations: dropping the fork's entry leaves its constant declared -- a
text scan passes -- while the rule stops catching a probe that names it,
and the entitlement check reports the orphan. A bogus entitlement for an
unforbidden module fails.

Co-Authored-By: Claude Opus 5 <[email protected]>

* fix(test): the registry is keyed by the rule, so an owner cannot be mistyped

Codex found the fifth hole in this file, and it is the same shape as the
other four: a field that can be wrong in the direction that passes. A
module carrying an owner string of "TestNoDirectPurlUse" belonged to no
rule, was scanned by nothing, and still satisfied an entitlement, because
the check asked whether the module was a map key rather than whether any
live rule forbade it.

Validating the owner against a list of known rules would have closed it.
Inverting the registry removes the field instead: forbiddenModules is
keyed by rule now, so there is no owner to mistype -- only a key, and a
key that is not a rule is caught from both sides.
TestRuleRegistryCoversEveryRule fails when a key names no rule that runs
and when a rule that runs has no key.

modulesForRule takes t and fails on an empty or missing list rather than
returning nothing. A rule scanning no modules reports no offenders
however many exist, which is indistinguishable from a rule that passed --
the failure mode this whole file exists to prevent, one level up.

Mutations: Codex's mistyped key fails twice over, once in the registry
test and once in the rule that would have scanned nothing. An emptied
list fails. A modulesForRule that returns silently still fails the
registry test.

Co-Authored-By: Claude Opus 5 <[email protected]>

---------

Co-authored-by: Claude Opus 5 <[email protected]>