feat: partial OSV snapshot release v3.1.0

CHANGELOG.md

@@ -13,14 +13,14 @@ All notable changes to `coderisktools-scanner` are documented here.
 - added bounded public feed adapters and explicit provenance/quality reports without claiming full-feed coverage;
 - added a real partial `seed` snapshot with 187 advisories, 378 affected-package rows and seven represented OSV ecosystems;
 - added signed, pinned seed bootstrap and a separate explicit `--profile seed --apply` activation command.
-- added a streamed, signed global OSV SQLite ZIP bootstrap that installs and activates the pinned database on first default vulnerability scan;
+- added a streamed, signed partial OSV-prefix SQLite ZIP bootstrap that installs and activates the pinned database on first default vulnerability scan; the manifest discloses included and available source counts;
 - added `vuln-db bootstrap-global` and `vuln scan --no-bootstrap` controls.
 
 ### Fixed
 
 - directory self-scan now skips SQLite database artifacts, preventing the real seed from tripping the scanner byte cap in CI;
 - bootstrap now verifies the detached Ed25519 manifest envelope, exact database SHA-256, SQLite integrity, foreign keys, snapshot identity and manifest counts before atomic installation.
-- global ZIP bootstrap verifies the compressed asset digest, one-member extraction contract, expanded database digest, compact provenance manifest and staged snapshot before local activation.
+- partial OSV ZIP bootstrap verifies the compressed asset digest, one-member extraction contract, expanded database digest, compact provenance manifest and staged snapshot before local activation; it remains explicitly non-complete.
 
 ### Seed boundary
 

README.md

@@ -245,9 +245,13 @@ secret-scanner vuln inventory \
 The sidecar schema is `coderisktools.vulnerability.external-evidence-provenance` v1 and includes `source_id`, `source_format`, `source_sha256`, timezone-aware `collected_at`, `collector` and `tool_version`. The source digest and tool identity must match the evidence report. Tampered or mismatched sidecars fail closed. The adapter also validates tool version, bounded arrays, package identity, PURL and aliases. It does not run OSV-Scanner.
 
 
-## 4. Local vulnerability scanning
+## 4. Local vulnerability scanning — a real database from the first run
 
-The vulnerability path uses a local SQLite database with an active snapshot. If `--database` is omitted and the default database is absent, the first run downloads, verifies, extracts and activates the pinned signed global OSV snapshot:
+CodeRiskTools starts with a real, signed OSV database rather than invented fixtures. Release `v3.1.0` bootstraps an explicitly partial snapshot containing approximately **243,000 real OSV records** (the signed release manifest is authoritative for the exact count). This gives dependency scanning useful coverage immediately after installation without placing a gigabyte-scale SQLite file in Git history.
+
+The database is designed to grow. `secret-scanner vuln-db update --full` can build a larger snapshot from configured sources, and `--database FILE` can select an independently supplied, verified database. Future signed release snapshots can therefore expand to substantially larger record counts without changing the matching format. Every UI and report must retain the profile, completeness and source counts: absence of a match in a partial snapshot is never proof that a dependency is safe.
+
+If `--database` is omitted and the default database is absent, the first run downloads, verifies, extracts and activates the pinned signed partial OSV snapshot:
 
 ```bash
 secret-scanner vuln scan \
@@ -271,15 +275,15 @@ secret-scanner vuln scan \
 Options:
 
 - `--root DIR` — local repository root;
-- `--database FILE` — local regular SQLite database; defaults to `~/.local/share/coderisktools/vuln-db/global-osv.sqlite`;
+- `--database FILE` — local regular SQLite database; defaults to `~/.local/share/coderisktools/vuln-db/osv-partial.sqlite`;
 - `--no-bootstrap` — reject a missing default database instead of downloading it;
 - `--format {json,sarif,markdown,html,csv}`;
 - `--output FILE` — write the report atomically;
 - `--baseline FILE` — JSON format emits new/existing/resolved delta;
 - `--vex FILE` — local OpenVEX or CycloneDX VEX;
 - `--suppressions FILE` — strict local suppression document.
 
-After first-use bootstrap, matching is offline, active-snapshot-only and read-only. The database path cannot be a symlink, URL or non-regular file. Manual installation is available as `secret-scanner vuln-db bootstrap-global`.
+After first-use bootstrap, matching is offline, active-snapshot-only and read-only. The pinned `v3.1.0` default is explicitly labeled `osv-partial` / `partial-osv-prefix`; an unmatched dependency is not proof of safety or complete OSV coverage. The database path cannot be a symlink, URL or non-regular file. Manual installation is available as `secret-scanner vuln-db bootstrap-global`.
 
 ## 5. OSV feed import
 

docs/GLOBAL-OSV-SNAPSHOT.md

@@ -1,16 +1,17 @@
-# Global OSV SQLite snapshot
+# OSV SQLite snapshots
 
-The global OSV builder imports the pinned OSV `all.zip` directly into a temporary SQLite database without extracting the archive to disk.
+The scanner supports both a complete import of a pinned OSV source archive and an explicitly partial, verified filename-sorted prefix. Release `v3.1.0` ships the latter to keep bootstrap size and build requirements bounded.
 
 ## Scope and naming
 
-A successful artifact is labeled:
+The shipped artifact is labeled:
 
-- `profile: global-osv`
-- `completeness: full-osv-source`
+- `profile: osv-partial`
+- `completeness: partial-osv-prefix`
 - `production_full_database: false`
+- source status: `bounded-prefix`
 
-`full-osv-source` means that every accepted JSON member from the pinned global OSV archive was processed. It does **not** mean complete Core coverage, complete vulnerability coverage, or proof that an unmatched component is safe. GHSA, KEV, EPSS, NVD, distro feeds, and other enrichments have separate provenance and completeness requirements.
+Its manifest records both the exact included record count and `available_records` from the pinned archive. This snapshot must **not** be interpreted as Full, Core, Complete, or proof that an unmatched component is safe. The separate complete-import builder retains `profile: global-osv` / `completeness: full-osv-source`, but that larger artifact is not the `v3.1.0` default. GHSA, KEV, EPSS, NVD, distro feeds, and other enrichments have separate provenance and completeness requirements.
 
 ## Space-efficient evidence mode
 
@@ -36,24 +37,28 @@ python scripts/build_global_osv_vulndb.py \
   --snapshot-id global-osv-YYYY-MM-DD
 ```
 
-The builder:
+The complete-source builder imports bounded batches and requires every member. To finalize a previously interrupted but internally consistent prefix as the partial profile, use the dedicated command. It re-hashes the full pinned archive, verifies every included `id + canonical JSON SHA-256`, then stages an isolated private copy; the interrupted input database is never modified:
 
-1. rejects symlinks, unsafe paths, duplicate members, encrypted files, non-JSON payloads, oversized members, and oversized expanded archives;
-2. verifies the pinned archive SHA-256 before import;
-3. imports bounded batches with no archive extraction;
-4. rejects the build if the configured import-error threshold is exceeded;
-5. checks SQLite integrity and foreign keys;
-6. generates a bounded-memory `compact-v1` content digest;
-7. publishes manifest and checksum first and the SQLite readiness artifact last with no-overwrite hard links;
-8. leaves the embedded snapshot **staged**, never active.
+```bash
+python scripts/finalize_partial_osv_vulndb.py \
+  --archive /path/to/all.zip \
+  --source-manifest /path/to/manifest.json \
+  --partial-database /path/to/interrupted.sqlite \
+  --output /path/to/coderisktools-vulndb-osv-partial.sqlite \
+  --manifest-output /path/to/coderisktools-vulndb-osv-partial.manifest.json \
+  --sha256-output /path/to/coderisktools-vulndb-osv-partial.sqlite.sha256 \
+  --snapshot-id osv-partial-YYYY-MM-DD
+```
+
+Both paths verify the pinned archive SHA-256, validate ZIP member safety and provenance counts, check SQLite integrity and foreign keys, generate a `compact-v1` content digest, publish through no-overwrite links with a readiness marker last, and leave the embedded snapshot **staged**. The complete-source builder imports bounded batches and requires the whole source. The partial finalizer requires an existing 230,000–400,000-record prefix, verifies every included source-record digest against filename-sorted archive members, independently re-imports that prefix into a disposable SQLite database, and requires an identical normalized `compact-v1` projection with zero import errors before publication.
 
 ## GitHub Release ZIP and first-run installation
 
 The repository never stores the multi-gigabyte database in Git history. Release `v3.1.0` publishes:
 
-- `coderisktools-vulndb-global-osv-2026-07-23.sqlite.zip`;
-- `coderisktools-vulndb-global-osv-2026-07-23.manifest.json`;
-- `coderisktools-vulndb-global-osv-2026-07-23.manifest.sig.json`.
+- `coderisktools-vulndb-osv-partial-2026-07-23.sqlite.zip`;
+- `coderisktools-vulndb-osv-partial-2026-07-23.manifest.json`;
+- `coderisktools-vulndb-osv-partial-2026-07-23.manifest.sig.json`.
 
 The ZIP contains exactly one SQLite member. On the first `vuln scan` invocation, when the default database path does not exist, the scanner:
 
@@ -69,7 +74,7 @@ The ZIP contains exactly one SQLite member. On the first `vuln scan` invocation,
 Default location:
 
 ```text
-~/.local/share/coderisktools/vuln-db/global-osv.sqlite
+~/.local/share/coderisktools/vuln-db/osv-partial.sqlite
 ```
 
 Manual bootstrap:

docs/RELEASE-NOTES-3.1.0.md

@@ -1,6 +1,6 @@
 # CodeRiskTools Scanner 3.1.0 — release notes
 
-CodeRiskTools Scanner 3.1.0 adds a controlled, local-first vulnerability database workflow, a small verified **partial seed**, and a pinned signed global OSV SQLite ZIP for first-use installation.
+CodeRiskTools Scanner 3.1.0 adds a controlled, local-first vulnerability database workflow, a small verified **partial seed**, and a pinned, signed **partial OSV prefix** SQLite ZIP for first-use installation. The release database is not Full/Core/Complete; its manifest exposes included and available source counts.
 
 ## What is included
 
@@ -12,8 +12,8 @@ CodeRiskTools Scanner 3.1.0 adds a controlled, local-first vulnerability databas
 - signed pinned bootstrap that installs seed as staged only;
 - explicit `vuln-db activate --profile seed --apply` activation;
 - real lodash `4.17.15` end-to-end matching evidence with stable fingerprints.
-- streamed first-use global database bootstrap with ZIP/database SHA-256, Ed25519, SQLite integrity, foreign-key and compact-manifest verification;
-- automatic installation to `~/.local/share/coderisktools/vuln-db/global-osv.sqlite` when the default database is missing;
+- streamed first-use partial OSV database bootstrap with ZIP/database SHA-256, Ed25519, SQLite integrity, foreign-key and compact-manifest verification;
+- automatic installation to `~/.local/share/coderisktools/vuln-db/osv-partial.sqlite` when the default database is missing;
 - `vuln-db bootstrap-global` for an explicit installation and `vuln scan --no-bootstrap` to disable automatic network bootstrap.
 
 ## Release assets
@@ -24,7 +24,7 @@ CodeRiskTools Scanner 3.1.0 adds a controlled, local-first vulnerability databas
 - SHA-256 sidecar;
 - Ed25519 signed manifest envelope (`.sig` JSON);
 - public release keyring.
-- global OSV single-SQLite ZIP, detached manifest and Ed25519 signed manifest envelope.
+- partial OSV prefix single-SQLite ZIP, detached manifest and Ed25519 signed manifest envelope.
 
 ## Verified seed facts