Adopt bomly-sdk v0.14 and emit the scan record

dev-docs/adr/0046-the-scan-output-is-the-sdk-scan-record.md

@@ -0,0 +1,58 @@
+# ADR-0046: The scan output is the SDK's scan record
+
+- **Date:** 2026-09-24
+- **Status:** Accepted
+
+## Context
+
+`bomly scan --format json` emitted a document defined in `internal/output`:
+three collections -- manifests, packages, findings -- joined by package URL
+(ADR-0006, ADR-0011), each a CLI-local projection of an SDK type with its own
+JSON tags, builders and tests. The document carried nothing about the run
+that produced it: no subject, no timestamp, no tool version, no verdict; the
+verdict lived only in the process exit code.
+
+A second consumer of that document now exists in the SDK's own `scan`
+package, which defines it as `scan.Record` under the schema `bomly.scan.v1`
+with the envelope the CLI never wrote. Under ADR-0040 a shape two consumers
+share belongs in the SDK, and a projection maintained beside it would have
+to be kept equal to it by hand -- the drift ADR-0045 ended for the SBOM
+codec.
+
+## Decision
+
+`bomly scan` emits `scan.Record`. The CLI builds it from the pipeline's
+consolidated manifests, registry and findings, fills `subject` from the
+execution target (repository, ref, and the commit the ref resolved to --
+never a local path), `run` from the invocation, and `verdict` from the same
+count the exit code uses, and writes it through `scan.Encode`, so what is
+written is the canonical, digested form.
+
+The projection types are gone. A manifest and its dependencies are
+`scan.Manifest` and `scan.Dependency`; a package is `model.Package` as the
+registry holds it; a finding is `model.Finding`, referencing its package by
+`package_ref`; a license is `model.PackageLicense` and a location
+`model.PackageLocation`. The `diff` and `explain` documents keep their own
+`schema_version` and adopt the same finding and package shapes. The one
+projection the old types did that a type cannot -- backfilling a finding's
+severity from its advisory -- is a function, `output.FindingsWithSeverity`,
+applied wherever findings enter a document. A package's presentation
+identity (`@scope/name` from `org` and `name`) is derived by the renderers,
+not written into the document.
+
+## Consequences
+
+- `findings[].package` (an identity block) becomes `findings[].package_ref`
+  (the package URL); `packages[].name` and `org` are coordinates, not a
+  display name; empty collections are omitted rather than written empty. The
+  goldens and generated schemas were regenerated once.
+- `subject`, `run`, `verdict`, `policy`, `waivers` and per-section `digests`
+  are new optional keys; `findings[].decision` records which resolver settled
+  a policy status. Local `--path` scans inside a repository record the
+  working tree's HEAD.
+- `internal/output` no longer defines the scan document's shape; its guards
+  live in the SDK (`scan/record_test.go`). The CLI keeps the builders that
+  need pipeline context -- manifest paths relative to the subproject, the
+  `Matched` flag from the registry -- and the renderers.
+- The scan JSON is stable across runs of the same content: `scan.Encode`
+  orders every collection, so a digest over it identifies what was found.

dev-docs/adr/README.md

@@ -66,3 +66,4 @@ status to `Superseded by [ADR-NNNN](NNNN-slug.md)`; do not rewrite history
 | ADR-0043 | 2026-09-06 | [A scope filter selects on assertions; absence is not one](0043-a-scope-filter-selects-on-assertions.md) | Accepted |
 | ADR-0044 | 2026-09-12 | [A guard must be able to fail, and must know what it covers](0044-a-guard-must-be-able-to-fail-and-know-its-reach.md) | Accepted |
 | ADR-0045 | 2026-09-13 | [The SDK owns the SBOM codec](0045-the-sdk-owns-the-sbom-codec.md) | Accepted |
+| ADR-0046 | 2026-09-24 | [The scan output is the SDK's scan record](0046-the-scan-output-is-the-sdk-scan-record.md) | Accepted |

docs/OUTPUT_FORMATS.md

@@ -72,13 +72,16 @@ The shape every Bomly subcommand emits. Each command has its own schema:
 | `bomly explain` | [explain.md](schemas/explain.md) |
 | `bomly diff` | [diff.md](schemas/diff.md) |
 
-`bomly scan` surfaces the three-collection model (see [Architecture → Domain model](ARCHITECTURE.md#domain-model)):
+`bomly scan` emits the scan record (schema `bomly.scan.v1`) and surfaces the
+three-collection model (see [Architecture → Domain model](ARCHITECTURE.md#domain-model)):
 `manifests[].dependencies` are lean detection-stage nodes (identity, `scopes`,
 `depends_on`, `package_ref`); `packages` is the deduplicated matching-stage
 registry (licenses, vulnerabilities, scorecard, EOL, CPEs, digests) keyed by
 PURL; and `findings` is the reference-style audit output. Resolve a finding or a
-dependency to its enrichment by matching `package_ref`/`package.purl` into
-`packages`.
+dependency to its enrichment by matching its `package_ref` into
+`packages[].purl`. Above the collections, `subject` says what was scanned
+(repository, ref, resolved commit), `run` says when and by which version, and
+`verdict` says what policy concluded.
 
 For remediation suggestions, `affected_dependency_refs` names occurrences of
 the vulnerable package. `suggested_action_dependency_ref` names the dependency or

docs/SBOM.md

@@ -407,14 +407,27 @@ identifiers are fixed.
 
 Some information necessarily becomes less specific during conversion:
 
-- Vulnerabilities are written but never read back. A CycloneDX export carries
-  ratings, CWEs, affected component references, descriptions, and advisory
-  URLs; an SPDX 2.3 export carries each vulnerability as a package security
-  advisory reference. Neither format's importer builds vulnerability records,
-  so converting a document does not carry its vulnerabilities across — Bomly
-  re-derives them by scanning with `--enrich`. What does survive an SPDX round
-  trip is the advisory reference itself, because it is preserved as an
-  ordinary external reference like any other the source stated.
+- Vulnerabilities survive a CycloneDX round trip and are lost across SPDX.
+  A CycloneDX export carries ratings, CWEs, affected component references,
+  descriptions, advisory URLs, and the VEX `analysis` block — state,
+  justification, responses, detail — and ingest reads all of them back into
+  the package registry, so a document that says a package is `not_affected`
+  because the code is not reachable yields a scan that says so too. An SPDX
+  2.3 export carries each vulnerability as a package security advisory
+  reference and nothing more, because the format has no slot for a rating or
+  an analysis; what survives an SPDX round trip is the advisory reference
+  itself, preserved as an ordinary external reference like any other the
+  source stated. End-of-life records survive both formats (see the `bomly:eol*`
+  properties and the SPDX package comment above).
+- SPDX `licenseDeclared` and `licenseConcluded` are read as the two claims
+  they are and written back to the field each came from; a document that
+  concluded a license re-exports it as concluded, not restated as declared.
+  Bomly concludes nothing itself, so `licenseConcluded` is `NOASSERTION`
+  exactly when no source concluded anything.
+- The format and specification version a document was decoded as is
+  recorded on its assertions (`format`, for example `cyclonedx-1.6+json`)
+  and reaches the scan document; a conversion never re-emits it, since the
+  output format's own header says what the output is.
 - Scope is a set in Bomly and a single value in both formats. A package
   reachable from both a runtime and a development root carries both scopes, so
   each format gets Bomly's projection in its native field — runtime wins a

docs/SCHEMAS.md

@@ -30,11 +30,21 @@ bomly scan . --format json --output scan.json
 
 ## Output shape
 
-Every document carries a `schema_version` and a `command`, then the three top-level collections:
+The scan document is the SDK's scan record (`github.com/bomly-dev/bomly-sdk/scan`,
+schema `bomly.scan.v1`). Every document carries a `schema_version` and a
+`command`, then the three top-level collections, and the scan document adds
+what a run says about itself:
+
+- **`subject`** — what was scanned: `kind`, `repository_url`, `ref`, and the `commit_sha` the ref resolved to (or the working tree's HEAD for a local path inside a repository). Never a local path.
+- **`run`** — the execution: `id`, `started_at`, `completed_at`, `tool` (`bomly` and its version), and `options` (`enrich`, `analyze`, `audit`, `fail_on`).
+- **`verdict`** — `pass`, `warn` or `fail`, the same outcome the exit code reports, present when `--audit` ran.
+- **`digests`** — a `sha256:` digest over each of `manifests`, `packages` and `findings`, so a reader can tell which section changed between two documents without comparing them.
+
+The collections:
 
 - **`manifests[]`** — detection-stage results, one entry per discovered project, each holding lean `dependencies[]` (identity, `scopes`, `depends_on`, and a `package_ref` into `packages`).
-- **`packages[]`** — matching-stage artifacts, deduplicated by PURL, carrying the enrichment: `licenses`, `vulnerabilities` (OSV-aligned, with CVSS/EPSS/reachability), `remediation`, `scorecard`, and `eol`. `remediation` contains vulnerability fix status, a recommended version when the evidence is complete, and occurrence-specific suggestions. In each suggestion, `affected_dependency_refs` identifies occurrences of the vulnerable package. `suggested_action_dependency_ref` identifies the direct dependency or manifest anchor the action targets. These references and the manifest path keep workspaces and repeated packages distinct. Suggestions are read-only guidance, not commands that Bomly runs.
-- **`findings[]`** — reference-style audit results that point back at the other collections rather than copying data inline: `package` is an identity-only ref (join `packages` by `purl`), `vulnerability_id` names the advisory inside `packages[].vulnerabilities`, and `dependency_refs` lists the introducing `manifests[].dependencies` ids.
+- **`packages[]`** — matching-stage artifacts, deduplicated by PURL, carrying the enrichment: `licenses`, `vulnerabilities` (OSV-aligned, with CVSS/EPSS/reachability and, when a source document stated one, the VEX `analysis`), `remediation`, `scorecard`, and `eol`. Each entry is the SDK package as the registry holds it: `name` and `org` are its coordinates (`@scope/name` on npm is `org: scope`, `name: name`), and every optional field is omitted when empty. `remediation` contains vulnerability fix status, a recommended version when the evidence is complete, and occurrence-specific suggestions. In each suggestion, `affected_dependency_refs` identifies occurrences of the vulnerable package. `suggested_action_dependency_ref` identifies the direct dependency or manifest anchor the action targets. These references and the manifest path keep workspaces and repeated packages distinct. Suggestions are read-only guidance, not commands that Bomly runs.
+- **`findings[]`** — reference-style audit results that point back at the other collections rather than copying data inline: `package_ref` is the package URL (join `packages` by `purl`), `vulnerability_id` names the advisory inside `packages[].vulnerabilities`, `dependency_refs` lists the introducing `manifests[].dependencies` ids, and `decision`, when a resolver such as a baseline settled the `policy_status`, says which one and why.
 
 Remediation status values are compact machine labels: `complete` means a
 complete fix is available for every known vulnerability on the package;
@@ -47,7 +57,9 @@ Enrichment lives once, in `packages`, and is resolved by PURL — so a CVE that
 
 ## Stability
 
-- `schema_version` follows semantic versioning. Additive, backward-compatible changes (new optional fields) bump the minor version; a breaking change bumps the major. Pin your consumers to the major version and tolerate unknown fields.
+- The scan document's `schema_version` is `bomly.scan.v1`, the SDK's scan record schema: additive within v1 (new optional keys only), so tolerate unknown keys. Empty collections and unset fields are omitted rather than written empty; a missing `depends_on` is a leaf, a missing `findings` is a run with none.
+- `diff` and `explain` keep the CLI's own `schema_version`, `1.0`. Their finding and package shapes follow the scan document's (`findings[].package_ref`, packages as SDK packages), which changed the shape of both without a version bump: the output had no external consumers at the time and the version now marks the schema families rather than promising the old field set.
+- Additive, backward-compatible changes (new optional fields) bump a minor version; a breaking change bumps the major. Pin your consumers to the major version and tolerate unknown fields.
 - The schema reference pages are regenerated by `make generate`, so they always match the binary you are running.
 
 ## Limitations