dsh-vet 0.2.6 → 0.3.0

package/README.md

@@ -6,10 +6,12 @@ Security vetting for DeepSeek Harness (DSH) plugins: permission & supply-chain
 audits before install, graded via the open [`dsh-vet/v1`](docs/dsh-vet-v1.md)
 report standard.
 
-> **Status: v0.1 shipped.** [`dsh-vet@0.1.0` is live on npm](https://www.npmjs.com/package/dsh-vet) —
-> reference scanner, 15 calibrated rules, public rule rationales, and an
-> 11-package ecosystem sweep record. v0.2 (author-side CI + badges) is next
-> on the [roadmap](ROADMAP.md).
+> **Status: v0.3 underway.** v0.2 shipped the author side — reference
+> scanner ([npm](https://www.npmjs.com/package/dsh-vet), 16 calibrated rules
+> with public rationales), CI Action, and auditable grade badges live in two
+> repos. v0.3 is the ecosystem round: report validation for consumers, the
+> verified-emitter program, and marketplace adoption before the contract's
+> formal freeze ([roadmap](ROADMAP.md)).
 
 ## Install
 
@@ -31,6 +33,7 @@ npx dsh-vet <specifier>          # npm package, git URL, or local path
 npx dsh-vet --json <specifier>   # dsh-vet/v1 report on stdout
 npx dsh-vet --strict <specifier> # exit 1 on findings >= high (confidence >= medium)
 npx dsh-vet --rules dep.install-scripts <specifier>
+npx dsh-vet validate <report.json> # check a report against the contract
 ```
 
 Any completed report exits `0` — grades describe findings, they do not gate.
@@ -104,8 +107,12 @@ The differentiating piece is not another scanner — it is
 deterministic JSON report contract (findings with severity **and confidence**,
 derived A–F grades) that any scanner may emit and any marketplace, CI job, or
 UI may consume, in the spirit of the community's `dsh-doctor/v1` contract.
-The TypeScript reference types ship from this package; third-party emitters
-are welcome and listed here once verified.
+The TypeScript reference types and the reference markdown renderer ship from
+this package; `dsh-vet validate` checks any report against the contract —
+including the derived grade, so a report from an emitter you don't know can't
+forge one. Third-party emitters are welcome and
+[listed once verified](docs/emitters.md); marketplaces can start from
+[docs/adopt-marketplace.md](docs/adopt-marketplace.md).
 
 ## How it differs
 
@@ -127,12 +134,13 @@ rules get re-examined and the rule set gets corrected in public.
 
 ## Roadmap
 
-- **v0.1** — contract frozen; reference CLI (`dsh vet <pkg>`) with the four
-  check families above
+- **v0.1** — contract shipped (stable, additive-only since 0.1.0) + reference
+  CLI (`dsh-vet <pkg>`) with the four check families above
 - **v0.2** — GitHub Action + badge so plugin authors self-audit and publish
   their grade
-- **v0.3** — marketplace integrations render `dsh-vet/v1` reports; contract
-  adopted by at least one third-party emitter
+- **v0.3** — ecosystem round: `dsh-vet validate` + the verified-emitter
+  program, marketplace integrations rendering `dsh-vet/v1` reports, and the
+  contract's formal freeze after the feedback round
 
 The detailed, trackable plan — task breakdowns, recorded decisions,
 definitions of done, risks, and kill criteria — lives in

package/docs/adopt-marketplace.md

@@ -0,0 +1,75 @@
+# Rendering `dsh-vet/v1` reports in your marketplace
+
+A one-pager for marketplace and catalog maintainers. Short version: your
+users currently judge DSH plugins by vibes at install time; a committed
+`dsh-vet/v1` report gives you a grade, a findings table, and filters from
+one JSON file — with zero servers to run and no endorsement implied.
+
+## Why render reports
+
+- **Demand already exists.** The community's most-upvoted feature request
+  ([deepseek-harness#1115](https://github.com/deepseek-ai/deepseek-harness/discussions/1115))
+  asks for marketplace standards and review mechanisms. The official
+  marketplace will take time.
+- **Authors publish reports already.** The
+  [GitHub Action](https://github.com/rogerdigital/dsh-vet/tree/main/action)
+  audits a plugin on every push and publishes the report + badge to a
+  `dsh-vet/report` branch, so for adopting repos the data is a raw-file URL
+  away — nothing for you to run.
+- **Zero lock-in.** The contract is additive-only, consumers must ignore
+  unknown fields, and the grade ships inside the report — you render it, you
+  never recompute it. Dropping the integration later loses a column, not
+  your site.
+- **Display is not endorsement.** Reports are signals, not verdicts; the
+  spec says so, and the badge says so. You surface what the audit found.
+
+## Three integration paths
+
+**1. The badge (minutes).** Render a shields.io badge from a report:
+
+```sh
+npx dsh-vet badge <report.json>   # → shields endpoint JSON
+```
+
+**2. The findings table (an hour).** Import the reference renderer — the
+same one the GitHub Action uses for PR comments:
+
+```ts
+import { renderMarkdown, validateReport } from 'dsh-vet'
+
+const report = await fetch(reportUrl).then((r) => r.json())
+const { ok } = validateReport(report)      // never trust an unverified emitter
+if (ok) page.add(renderMarkdown(report, { runUrl: reportUrl }))
+```
+
+**3. Ingestion-time validation (for pipelines).** Reject malformed or
+forged reports before they reach your UI — the validator recomputes the
+grade from the findings, so an emitter cannot assert a grade its evidence
+does not support:
+
+```sh
+npx dsh-vet validate report.json && echo trustworthy-shape
+```
+
+## Consumer rules (from the spec)
+
+- **Ignore unknown fields** — emitters may add `x-`-prefixed extras; tolerate
+  them.
+- **Read `summary.grade`; never recompute it.** Grades are derived at emit
+  time by contract.
+- **Never present grade `X`** as a plugin's grade — it marks an incomplete
+  scan.
+- **List findings, don't re-score them.** Severity and confidence are part
+  of the data; a low-confidence finding never lowers a grade, by contract.
+
+## Where reports come from
+
+Plugin authors commit them via the [Action](https://github.com/rogerdigital/dsh-vet/tree/main/action)
+(`dsh-vet/report` branch in their repo), or you can run the scanner yourself
+on any npm-installable plugin: `npx dsh-vet --json <specifier>`. Emitters
+you didn't write must pass `dsh-vet validate` first; verified emitters are
+listed in [emitters.md](emitters.md).
+
+The contract itself: [dsh-vet-v1.md](dsh-vet-v1.md) — stable, additive-only
+since 0.1.0, freezing after this adoption round. Feedback on it is exactly
+what the freeze round is for: [discussions](https://github.com/rogerdigital/dsh-vet/discussions).

package/docs/dsh-vet-v1.md

@@ -1,7 +1,11 @@
 # The `dsh-vet/v1` report contract
 
-Status: **draft** — open for community input before v0.1 freezes it.
+Status: **stable — additive-only since v0.1.0.** Every report the 0.1.0
+reference scanner emitted still validates today. The formal freeze is
+announced with v0.3, after the marketplace-feedback round; until then,
+changes are limited to new optional fields and new rule ids.
 Reference TypeScript types: `src/contract.ts` (shipped from this package).
+Conformance checking: `dsh-vet validate <report.json>`.
 
 `dsh-vet/v1` defines a machine-readable audit report for a DeepSeek Harness
 (DSH) plugin. It is implementation-agnostic: any scanner may emit it, and any
@@ -152,8 +156,9 @@ confidence ≥ `medium` exist, for CI gating.
 
 ## Versioning
 
-`/v1` freezes at the v0.1 release of this package. Backward-compatible
-additions (new optional fields, new rule ids) stay in `/v1`; semantic changes
-get `/v2` with a migration note. Discussion happens in
+`/v1` has been additive-only since the v0.1 release of this package — new
+optional fields and new rule ids stay in `/v1`; semantic changes get `/v2`
+with a migration note. The formal freeze follows the v0.3 marketplace-feedback
+round: afterwards even additive changes land only after public discussion in
 [GitHub Discussions](https://github.com/rogerdigital/dsh-vet/discussions)
 and the [dsh-plugin topic](https://github.com/topics/dsh-plugin).

package/docs/emitters.md

@@ -0,0 +1,55 @@
+# Verified emitters of `dsh-vet/v1`
+
+An **emitter** is any tool that produces `dsh-vet/v1` reports — a scanner
+like this one, a CI integration, a marketplace's own analysis pipeline. The
+contract is only useful if consumers can trust reports from emitters they
+did not write, so this page defines what *verified* means and lists the
+emitters that made it.
+
+## The checklist
+
+An emitter is listed as verified when it meets every item below. The list is
+deliberately short: the contract carries the structure, this carries the
+honesty.
+
+1. **Structure.** Reports are built through `createReport()` from this
+   package, or — for non-TypeScript emitters — every published report passes
+   `dsh-vet validate` (`npx dsh-vet validate <report.json>`). Either path
+   guarantees the derived summary, the deterministic sort, and well-formed
+   rule ids; an emitter that hand-assembles reports and skips validation is
+   not verified.
+2. **Determinism.** Two runs over the same artifact with the same emitter
+   version produce identical reports, `scanner.ranAt` aside.
+3. **Conservative severity.** Findings follow the severity ladder in the
+   [spec](dsh-vet-v1.md#severity-definitions); anything that depends on
+   runtime values is emitted at `low` confidence (or reduced severity), never
+   the reverse. The cost of a false positive is paid by a plugin author.
+4. **Evidence.** Every finding carries at least one evidence item (`file`,
+   and `line` when the emitter has it); snippets are minimal and never
+   include secrets.
+5. **Vendor-prefixed, documented rules.** Third-party rule ids start with
+   the vendor's own segment (`acme.eval-detect`) and each rule has a public
+   rationale page — a rule nobody can dispute in public is a rule nobody
+   should trust.
+6. **A public dispute channel.** A place authors can contest findings, with
+   a visible record of corrections.
+7. **Honest `scanner` fields.** `name` and `version` identify the emitting
+   tool as it actually ran.
+
+## Verification process
+
+1. The emitter's maintainer opens an issue here linking to the emitter and
+   2–3 sample reports against real plugins.
+2. We run `dsh-vet validate` on the samples and read the vendor rule docs,
+   checking severity calibration against the spec ladder (item 3).
+3. Both sides record the verified version range; listings link to the
+   emitter's repo and rule docs. Breaking the checklist later removes the
+   listing, with the reason stated in the issue.
+
+## Registry
+
+| Emitter | Verified versions | Rules | Notes |
+|---|---|---|---|
+| [`dsh-vet`](https://github.com/rogerdigital/dsh-vet) | 0.1.0 – | [`docs/rules/`](rules/) | the reference emitter; self-audited in [`examples/`](../examples/) |
+
+Third-party emitters: none yet — the slot is open.

package/docs/outreach/README.md

@@ -0,0 +1,12 @@
+# Outreach drafts
+
+Ready-to-send drafts for the v0.3 announcement round. Each file names its
+destination. None are sent yet — send from the maintainer's account, then
+record the thread link in ROADMAP.md v0.3 so feedback has a traceable home.
+
+| File | Destination | Depends on |
+|---|---|---|
+| [deepseek-harness-1115-reply.md](deepseek-harness-1115-reply.md) | reply in [deepseek-harness#1115](https://github.com/deepseek-ai/deepseek-harness/discussions/1115) | npm 0.3.0 published |
+| [show-your-plugins-post.md](show-your-plugins-post.md) | community "Show Your Plugins" thread | 0.3.0 published |
+| [awesome-list-pr.md](awesome-list-pr.md) | PR against a dsh/agent awesome-list | — |
+| [dsh-plugin-audit-collab.md](dsh-plugin-audit-collab.md) | issue/DM to dsh-plugin-audit maintainers | — |

package/docs/outreach/awesome-list-pr.md

@@ -0,0 +1,39 @@
+<!-- Destination: PR against a dsh / agent-skills / security-tools awesome list.
+     Swap in the list's entry format (table vs bullet) and category. -->
+
+PR title: `Add dsh-vet — pre-install security audits for DSH plugins`
+
+## What
+
+[dsh-vet](https://github.com/rogerdigital/dsh-vet) — static security vetting
+for DeepSeek Harness plugins, built around an open report contract:
+
+```markdown
+- [dsh-vet](https://github.com/rogerdigital/dsh-vet) — pre-install permission & supply-chain audits
+  for DSH plugins; emits the open `dsh-vet/v1` report (severity + confidence, derived grades),
+  ships a CI Action + auditable badge, and validates/renders reports from any conforming emitter.
+```
+
+or, for table-format lists:
+
+```markdown
+| [dsh-vet](https://github.com/rogerdigital/dsh-vet) | CLI · library · CI Action | Pre-install static audits for DSH plugins; emits and verifies the open `dsh-vet/v1` report |
+```
+
+## Why it fits
+
+- Solves a live pain: the community's top feature request is marketplace
+  review standards (deepseek-harness#1115); incidents like the Full Access
+  home-directory wipe (#461) show the stakes.
+- Not another closed tool: the differentiating artifact is the
+  implementation-agnostic report contract — any scanner may emit it, any
+  marketplace/UI may consume it, `dsh-vet validate` verifies conformance.
+- Maintained in the open: public per-rule rationales, public
+  false-positive dispute process, calibration record against 11 real
+  plugins, self-audited with its own scanner, MIT.
+
+## Checks
+
+- [ ] MIT licensed, docs and tests present, CI green
+- [x] Installable via npm (`dsh-vet`), runs via `npx`, zero runtime deps
+      beyond the parser

package/docs/outreach/deepseek-harness-1115-reply.md

@@ -0,0 +1,38 @@
+<!-- Destination: reply in deepseek-ai/deepseek-harness discussion #1115
+     (marketplace standards / review mechanisms). Send after 0.3.0 is on npm. -->
+
+Sharing what we built against exactly this problem, in case it's useful
+before an official marketplace lands.
+
+The core idea: "should I install this plugin?" needs a **shared,
+machine-readable answer**, not per-tool vibes. So the contract came first —
+[`dsh-vet/v1`](https://github.com/rogerdigital/dsh-vet/blob/main/docs/dsh-vet-v1.md),
+an implementation-agnostic audit report (findings with severity *and*
+confidence, derived A–F grades), following the pattern `dsh-doctor/v1`
+proved: freeze a small boring contract, compete on implementations.
+
+On top of it:
+
+- **A reference scanner** ([dsh-vet on npm](https://www.npmjs.com/package/dsh-vet)) —
+  static, deterministic, never installs or transmits the audited plugin.
+  16 rules across capability seams, supply chain, obfuscation, and data
+  egress; every rule has a public rationale page and a public dispute
+  template. Calibrated against 11 real ecosystem plugins
+  ([sweep record](https://github.com/rogerdigital/dsh-vet/blob/main/docs/calibration-v0.1.md)).
+- **Author-side CI** — a GitHub Action that audits on every push and
+  publishes the report + grade badge from the plugin's own repo (zero
+  server; the badge value is auditable through git history). Live in two
+  repos already, including the scanner's own self-audit.
+- **A consumer story** — `dsh-vet validate` checks any report against the
+  contract (grade is recomputed from findings, so an emitter can't forge
+  one), and `renderMarkdown` gives marketplaces/UIs the same rendering the
+  Action uses: [adopting it](https://github.com/rogerdigital/dsh-vet/blob/main/docs/adopt-marketplace.md).
+
+The contract has been additive-only since 0.1.0 — every report the first
+release emitted still validates today. **We're actively seeking feedback
+from marketplace and tool maintainers before formally freezing `/v1`.** If
+you're building a catalog or review layer, this round is exactly for you:
+what would you need the report to carry?
+
+Happy to go deeper on any piece — severity calibration, false-positive
+handling, or the freeze criteria.

package/docs/outreach/dsh-plugin-audit-collab.md

@@ -0,0 +1,37 @@
+<!-- Destination: issue on dsh-plugin-audit's repo (or DM to its maintainers).
+     Tone: peer-to-peer, one concrete ask (a conversation), no commitment demanded. -->
+
+Hi — maintainer of [dsh-vet](https://github.com/rogerdigital/dsh-vet) here.
+Your runtime-sentinel work is in our README's comparison table as the
+complementary half of this problem, and I'd like to make that explicit
+instead of just documented on our side.
+
+The shape of it:
+
+- **dsh-vet** answers *"what does this plugin do?"* **before install** —
+  static analysis, emitted as the open
+  [`dsh-vet/v1`](https://github.com/rogerdigital/dsh-vet/blob/main/docs/dsh-vet-v1.md)
+  report (findings with severity + confidence, derived grades, evidence per
+  finding).
+- **dsh-plugin-audit** answers *"what is it doing right now?"* at runtime —
+  permission profiling and sentinels.
+
+Static-before-install and runtime-during-use cover different failure modes
+(obfuscated payloads vs. behavior that only emerges live), which is why we
+list you as complementary rather than competing — and why we'd rather
+coordinate than FUD.
+
+Two things that might be cheap and useful, if you're interested:
+
+1. **Shared vocabulary.** Our report contract deliberately leaves rule ids
+   open-ended (`acme.eval-detect` style vendor prefixes). If your runtime
+   findings ever want a common shape — severity/confidence semantics,
+   evidence, dispute channels — the contract is additive-only and open for
+   feedback before its formal freeze. You'd be the most natural co-author
+   of whatever `/v1` learns from runtime auditing.
+2. **Cross-linking.** We already point to you as the runtime half; a link
+   back from your side (if you find the pre-install half useful) would let
+   users find the full stack.
+
+No ask beyond a conversation — if either half sounds useful, I'm happy to
+open a discussion with concrete details.

package/docs/outreach/show-your-plugins-post.md

@@ -0,0 +1,41 @@
+<!-- Destination: a community "Show Your Plugins" / project showcase thread.
+     Adjust the opening line to the thread's framing. Send after 0.3.0 is on npm. -->
+
+**dsh-vet** — know what a plugin does *before* you install it.
+
+DSH's everything-is-a-plugin model is its superpower and its attack surface:
+an installed plugin can touch your filesystem, spawn processes, and open
+network connections. After the incident where a Full Access session wiped a
+user's home directory, "should I install this?" deserved better than vibes.
+
+dsh-vet audits any npm-installable DSH plugin — statically, locally, without
+installing or executing it — and emits an open, deterministic
+[`dsh-vet/v1`](https://github.com/rogerdigital/dsh-vet/blob/main/docs/dsh-vet-v1.md)
+report: findings with severity **and** confidence, and a derived A–F grade
+where a low-confidence finding never counts against you.
+
+```sh
+npx dsh-vet <plugin>        # human summary
+npx dsh-vet --json <plugin> # full dsh-vet/v1 report
+```
+
+What makes it defensible rather than noisy:
+
+- **Every rule has a public rationale** and a public false-positive dispute
+  template; disputed rules get corrected in the open (it has happened, and
+  the changelog shows it).
+- **Calibrated on real plugins** — an 11-package sweep record is published,
+  including grades and the two tunings the sweep forced.
+- **It audits itself** — the repo's own grade badge is generated from the
+  exact tarball that ships to npm, and every signal the scanner finds in
+  itself is in the published report.
+
+For plugin authors: a [GitHub Action](https://github.com/rogerdigital/dsh-vet/tree/main/action)
+audits on every push and publishes your grade badge from your own repo —
+no badge service, the value is auditable through your git history. For
+catalog/UI builders: [`dsh-vet validate`](https://github.com/rogerdigital/dsh-vet/blob/main/docs/adopt-marketplace.md)
+ingests and verifies reports from any conforming emitter.
+
+The contract is additive-only since 0.1.0 and open for feedback before the
+formal freeze. Repo: [rogerdigital/dsh-vet](https://github.com/rogerdigital/dsh-vet) —
+criticism on severity calibration is genuinely welcome.

package/lib/index.d.mts

@@ -88,6 +88,8 @@ interface VetReport {
   readonly summary: VetSummary;
   readonly findings: readonly VetFinding[];
 }
+/** Sort rank per severity, worst first; the contract's deterministic order. */
+declare const SEVERITY_RANK: Record<VetSeverity, number>;
 /**
  * Rule ids are two or more dot-separated lowercase segments
  * (`perm.broad-fs-write`, `acme.eval-detect`). Deliberately open-ended about
@@ -271,7 +273,7 @@ declare function runRules(analysis: Analysis, only?: string[]): VetFinding[];
 //#endregion
 //#region src/scanner.d.ts
 /** Kept in lockstep with package.json; a test asserts they match. */
-declare const SCANNER_VERSION = "0.2.6";
+declare const SCANNER_VERSION = "0.3.0";
 interface ScanOptions extends ResolveOptions {
   /** Injectable clock for deterministic tests/reports. */
   now?: () => string;
@@ -291,6 +293,43 @@ interface ShieldsEndpointBadge {
 }
 declare function renderBadge(report: VetReport): ShieldsEndpointBadge;
 //#endregion
+//#region src/render.d.ts
+interface RenderMarkdownOptions {
+  /** Link to the CI run or page hosting the full report. */
+  runUrl: string;
+}
+declare function renderMarkdown(report: VetReport, options: RenderMarkdownOptions): string;
+//#endregion
+//#region src/validate.d.ts
+/**
+ * Structural validation for `dsh-vet/v1` reports (ROADMAP v0.3).
+ *
+ * Marketplaces and CI jobs receive reports from scanners they did not write.
+ * This module checks a report against the contract without trusting the
+ * emitter: every normative statement in `docs/dsh-vet-v1.md` is enforced —
+ * field types, enums, rule-id shape, evidence presence, the derived summary,
+ * and the deterministic sort order. Unknown fields are ignored (design
+ * rule 4). The derived-summary check is the load-bearing one: an emitter
+ * cannot assert a flattering grade that its findings do not support.
+ *
+ * @module dsh-vet/validate
+ */
+interface ValidationIssue {
+  /** Dotted path into the report, e.g. `findings[2].evidence[0].line`. */
+  path: string;
+  message: string;
+}
+interface ValidationResult {
+  ok: boolean;
+  issues: ValidationIssue[];
+}
+/**
+ * Validate a parsed report against the `dsh-vet/v1` contract. Collects every
+ * issue instead of failing on the first, so an emitter sees its full repair
+ * list in one pass.
+ */
+declare function validateReport(report: unknown): ValidationResult;
+//#endregion
 //#region src/cli.d.ts
 /**
  * CLI (ROADMAP T4). Exit semantics per the dsh-vet/v1 spec: `0` for any
@@ -304,4 +343,4 @@ interface CliIo {
 /** Parse and run; returns the process exit code. */
 declare function runCli(argv: string[], io: CliIo): Promise<number>;
 //#endregion
-export { type Analysis, type Capability, type CapabilityUse, type CharcodeCall, type CliIo, type CreateReportInput, type DynamicImportUse, type EncodedLiteral, type EvalUse, type FindingInit, type ImportRef, type NetUse, type PkgJson, RULES, RULE_ID_PATTERN, type ResolveOptions, type ResolvedTarget, type Rule, type RuleContext, SCANNER_VERSION, SCHEMA_ID, type ScanOptions, type ShieldsEndpointBadge, type SourceFile, type SpecifierKind, type VetConfidence, VetError, type VetEvidence, type VetFinding, type VetGrade, type VetReport, type VetScanner, type VetSeverity, type VetSummary, type VetSummaryCounts, type VetTarget, type VetTargetKind, analyze, classifySpecifier, countFindings, createReport, gradeFor, isGraded, parseNpmSpecifier, reachableFrom, renderBadge, resolveTarget, ruleIds, runCli, runRules, scan, scanDirectory };
+export { type Analysis, type Capability, type CapabilityUse, type CharcodeCall, type CliIo, type CreateReportInput, type DynamicImportUse, type EncodedLiteral, type EvalUse, type FindingInit, type ImportRef, type NetUse, type PkgJson, RULES, RULE_ID_PATTERN, type RenderMarkdownOptions, type ResolveOptions, type ResolvedTarget, type Rule, type RuleContext, SCANNER_VERSION, SCHEMA_ID, SEVERITY_RANK, type ScanOptions, type ShieldsEndpointBadge, type SourceFile, type SpecifierKind, type ValidationIssue, type ValidationResult, type VetConfidence, VetError, type VetEvidence, type VetFinding, type VetGrade, type VetReport, type VetScanner, type VetSeverity, type VetSummary, type VetSummaryCounts, type VetTarget, type VetTargetKind, analyze, classifySpecifier, countFindings, createReport, gradeFor, isGraded, parseNpmSpecifier, reachableFrom, renderBadge, renderMarkdown, resolveTarget, ruleIds, runCli, runRules, scan, scanDirectory, validateReport };

package/lib/index.mjs

@@ -23,6 +23,7 @@ import { parseArgs } from "node:util";
 */
 /** Literal `schema` value every dsh-vet/v1 report carries. */
 const SCHEMA_ID = "dsh-vet/v1";
+/** Sort rank per severity, worst first; the contract's deterministic order. */
 const SEVERITY_RANK = {
 	critical: 0,
 	high: 1,
@@ -1603,7 +1604,7 @@ function runRules(analysis, only) {
 * over the same artifact with the same version are identical.
 */
 /** Kept in lockstep with package.json; a test asserts they match. */
-const SCANNER_VERSION = "0.2.6";
+const SCANNER_VERSION = "0.3.0";
 /**
 * A scan that audited zero JavaScript files must not read as a clean pass —
 * a TypeScript source tree scanned as a local path has no `.js` to analyze,
@@ -1681,6 +1682,218 @@ function renderBadge(report) {
 	};
 }
 //#endregion
+//#region src/render.ts
+function renderMarkdown(report, options) {
+	const c = report.summary.counts;
+	const lines = [
+		"<!-- dsh-vet:pr-comment -->",
+		"## dsh-vet report",
+		"",
+		`**Grade: ${report.summary.grade}** · audited \`${report.target.specifier}\` · [run](${options.runUrl}) · report uploaded as the \`dsh-vet-report\` artifact`,
+		"",
+		`| critical | high | medium | low | info |`,
+		`| --- | --- | --- | --- | --- |`,
+		`| ${c.critical} | ${c.high} | ${c.medium} | ${c.low} | ${c.info} |`,
+		""
+	];
+	const graded = report.findings.filter((f) => f.severity !== "info");
+	const info = report.findings.filter((f) => f.severity === "info");
+	if (report.findings.length === 0) lines.push("No findings.");
+	if (graded.length > 0) {
+		lines.push("### Findings", "");
+		for (const f of graded.slice(0, 10)) {
+			lines.push(`- **[${f.severity[0].toUpperCase()}] ${f.id}** — ${f.title} (\`${f.confidence}\` confidence)`);
+			for (const e of f.evidence.slice(0, 3)) {
+				const where = e.line ? `${e.file}:${e.line}` : e.file;
+				lines.push(`  - \`${where}\`${e.snippet ? ` — \`${e.snippet}\`` : ""}`);
+			}
+		}
+		if (graded.length > 10) lines.push(`- …and ${graded.length - 10} more in the report artifact`);
+		lines.push("");
+	}
+	if (info.length > 0) {
+		lines.push(`<details><summary>${info.length} info findings (never affect the grade)</summary>`, "");
+		for (const f of info.slice(0, 8)) lines.push(`- **${f.id}** — ${f.title}`);
+		if (info.length > 8) lines.push(`- …and ${info.length - 8} more`);
+		lines.push("</details>", "");
+	}
+	lines.push("---", "Findings are signals, not verdicts — a low-confidence finding never lowers a grade. A finding you believe is wrong? [Open a public dispute](https://github.com/rogerdigital/dsh-vet/issues/new?template=false-positive.md).");
+	return lines.join("\n");
+}
+//#endregion
+//#region src/validate.ts
+/**
+* Structural validation for `dsh-vet/v1` reports (ROADMAP v0.3).
+*
+* Marketplaces and CI jobs receive reports from scanners they did not write.
+* This module checks a report against the contract without trusting the
+* emitter: every normative statement in `docs/dsh-vet-v1.md` is enforced —
+* field types, enums, rule-id shape, evidence presence, the derived summary,
+* and the deterministic sort order. Unknown fields are ignored (design
+* rule 4). The derived-summary check is the load-bearing one: an emitter
+* cannot assert a flattering grade that its findings do not support.
+*
+* @module dsh-vet/validate
+*/
+const SEVERITIES = [
+	"critical",
+	"high",
+	"medium",
+	"low",
+	"info"
+];
+const CONFIDENCES = [
+	"high",
+	"medium",
+	"low"
+];
+const GRADES = [
+	"A",
+	"B",
+	"C",
+	"D",
+	"F",
+	"X"
+];
+const TARGET_KINDS = [
+	"npm-package",
+	"git-repo",
+	"local-path"
+];
+const RFC3339 = /^\d{4}-\d{2}-\d{2}[Tt]\d{2}:\d{2}:\d{2}(\.\d+)?([Zz]|[+-]\d{2}:\d{2})$/;
+function isObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function show(value) {
+	if (typeof value === "string") return JSON.stringify(value);
+	if (Array.isArray(value)) return "an array";
+	if (isObject(value)) return "an object";
+	return String(value);
+}
+function isInt(value) {
+	return typeof value === "number" && Number.isInteger(value);
+}
+/**
+* Validate a parsed report against the `dsh-vet/v1` contract. Collects every
+* issue instead of failing on the first, so an emitter sees its full repair
+* list in one pass.
+*/
+function validateReport(report) {
+	const issues = [];
+	const fail = (path, message) => {
+		issues.push({
+			path,
+			message
+		});
+	};
+	if (!isObject(report)) return {
+		ok: false,
+		issues: [{
+			path: "report",
+			message: `must be an object, got ${show(report)}`
+		}]
+	};
+	if (report.schema !== "dsh-vet/v1") fail("schema", `must be ${JSON.stringify(SCHEMA_ID)}, got ${show(report.schema)}`);
+	if (!isObject(report.target)) fail("target", `must be an object, got ${show(report.target)}`);
+	else {
+		const target = report.target;
+		if (!TARGET_KINDS.includes(target.kind)) fail("target.kind", `must be one of ${TARGET_KINDS.map((k) => JSON.stringify(k)).join(" | ")}, got ${show(target.kind)}`);
+		if (typeof target.specifier !== "string") fail("target.specifier", `must be a string, got ${show(target.specifier)}`);
+		if (target.resolved !== void 0) {
+			if (!isObject(target.resolved)) fail("target.resolved", `must be an object, got ${show(target.resolved)}`);
+			else for (const key of [
+				"version",
+				"commit",
+				"integrity"
+			]) {
+				const value = target.resolved[key];
+				if (value !== void 0 && typeof value !== "string") fail(`target.resolved.${key}`, `must be a string, got ${show(value)}`);
+			}
+		}
+	}
+	if (!isObject(report.scanner)) fail("scanner", `must be an object, got ${show(report.scanner)}`);
+	else {
+		const scanner = report.scanner;
+		if (typeof scanner.name !== "string") fail("scanner.name", `must be a string, got ${show(scanner.name)}`);
+		if (typeof scanner.version !== "string") fail("scanner.version", `must be a string, got ${show(scanner.version)}`);
+		if (typeof scanner.ranAt !== "string" || !RFC3339.test(scanner.ranAt) || Number.isNaN(Date.parse(scanner.ranAt))) fail("scanner.ranAt", `must be an RFC 3339 timestamp, got ${show(scanner.ranAt)}`);
+	}
+	let findingsShapeOk = false;
+	if (!Array.isArray(report.findings)) fail("findings", `must be an array, got ${show(report.findings)}`);
+	else {
+		findingsShapeOk = true;
+		report.findings.forEach((raw, i) => {
+			const at = `findings[${i}]`;
+			if (!isObject(raw)) {
+				fail(at, `must be an object, got ${show(raw)}`);
+				findingsShapeOk = false;
+				return;
+			}
+			const finding = raw;
+			if (typeof finding.id !== "string" || !RULE_ID_PATTERN.test(finding.id)) fail(`${at}.id`, `must match ${RULE_ID_PATTERN} (vendor rule sets prefix their own segment, e.g. acme.eval-detect), got ${show(finding.id)}`);
+			if (typeof finding.title !== "string") fail(`${at}.title`, `must be a string, got ${show(finding.title)}`);
+			if (!SEVERITIES.includes(finding.severity)) {
+				fail(`${at}.severity`, `must be one of ${SEVERITIES.map((s) => JSON.stringify(s)).join(" | ")}, got ${show(finding.severity)}`);
+				findingsShapeOk = false;
+			}
+			if (!CONFIDENCES.includes(finding.confidence)) {
+				fail(`${at}.confidence`, `must be one of ${CONFIDENCES.map((c) => JSON.stringify(c)).join(" | ")}, got ${show(finding.confidence)}`);
+				findingsShapeOk = false;
+			}
+			if (!Array.isArray(finding.evidence) || finding.evidence.length === 0) fail(`${at}.evidence`, "must be a non-empty array");
+			else finding.evidence.forEach((ev, j) => {
+				const evAt = `${at}.evidence[${j}]`;
+				if (!isObject(ev)) {
+					fail(evAt, `must be an object, got ${show(ev)}`);
+					return;
+				}
+				if (typeof ev.file !== "string") fail(`${evAt}.file`, `must be a string, got ${show(ev.file)}`);
+				if (ev.line !== void 0 && (!isInt(ev.line) || ev.line < 1)) fail(`${evAt}.line`, `must be a positive integer, got ${show(ev.line)}`);
+				if (ev.snippet !== void 0 && typeof ev.snippet !== "string") fail(`${evAt}.snippet`, `must be a string, got ${show(ev.snippet)}`);
+				if (ev.note !== void 0 && typeof ev.note !== "string") fail(`${evAt}.note`, `must be a string, got ${show(ev.note)}`);
+			});
+			if (finding.remediation !== void 0 && typeof finding.remediation !== "string") fail(`${at}.remediation`, `must be a string, got ${show(finding.remediation)}`);
+			if (finding.references !== void 0) {
+				if (!Array.isArray(finding.references) || finding.references.some((ref) => typeof ref !== "string")) fail(`${at}.references`, `must be an array of strings, got ${show(finding.references)}`);
+			}
+		});
+	}
+	if (!isObject(report.summary)) fail("summary", `must be an object, got ${show(report.summary)}`);
+	else {
+		const summary = report.summary;
+		if (!GRADES.includes(summary.grade)) fail("summary.grade", `must be one of ${GRADES.join(" | ")}, got ${show(summary.grade)}`);
+		if (!isObject(summary.counts)) fail("summary.counts", `must be an object, got ${show(summary.counts)}`);
+		else for (const severity of SEVERITIES) {
+			const count = summary.counts[severity];
+			if (!isInt(count) || count < 0) fail(`summary.counts.${severity}`, `must be a non-negative integer, got ${show(count)}`);
+		}
+	}
+	if (findingsShapeOk && Array.isArray(report.findings) && isObject(report.summary) && isObject(report.summary.counts)) {
+		const findings = report.findings;
+		const derivedCounts = countFindings(findings);
+		for (const severity of SEVERITIES) if (report.summary.counts[severity] !== derivedCounts[severity]) fail(`summary.counts.${severity}`, `must match the findings (${report.summary.counts[severity]} asserted, ${derivedCounts[severity]} derived) — the summary is always derived, never asserted`);
+		const grade = report.summary.grade;
+		if (grade !== "X") {
+			const derivedGrade = gradeFor(findings);
+			if (grade !== derivedGrade) fail("summary.grade", `${show(grade)} is asserted but the findings derive ${JSON.stringify(derivedGrade)} — the summary is always derived, never asserted`);
+		}
+		for (let i = 1; i < report.findings.length; i++) {
+			const prev = report.findings[i - 1];
+			const cur = report.findings[i];
+			const prevRank = SEVERITY_RANK[prev.severity];
+			const curRank = SEVERITY_RANK[cur.severity];
+			if (prevRank > curRank || prevRank === curRank && String(prev.id).localeCompare(String(cur.id)) > 0) {
+				fail("findings", `must be sorted worst severity first then id ascending; ${show(cur.id)} follows ${show(prev.id)}`);
+				break;
+			}
+		}
+	}
+	return {
+		ok: issues.length === 0,
+		issues
+	};
+}
+//#endregion
 //#region src/cli.ts
 /**
 * CLI (ROADMAP T4). Exit semantics per the dsh-vet/v1 spec: `0` for any
@@ -1689,6 +1902,7 @@ function renderBadge(report) {
 */
 const USAGE = `usage: dsh-vet <specifier> [options]
        dsh-vet badge <report.json>
+       dsh-vet validate <report.json> [<report.json> ...]
 
   specifier            npm package (name[@version]), git URL, or local path
 
@@ -1701,7 +1915,11 @@ const USAGE = `usage: dsh-vet <specifier> [options]
 
   badge                render a shields.io endpoint badge (JSON) from a
                        dsh-vet/v1 report file; used by CI to publish a grade
-                       badge whose value is the committed report`;
+                       badge whose value is the committed report
+
+  validate             check report file(s) against the dsh-vet/v1 contract;
+                       the entry point for marketplaces and CI jobs consuming
+                       reports from scanners they did not write`;
 const SEVERITY_ORDER = [
 	"critical",
 	"high",
@@ -1737,6 +1955,7 @@ function humanSummary(report) {
 /** Parse and run; returns the process exit code. */
 async function runCli(argv, io) {
 	if (argv[0] === "badge") return runBadge(argv.slice(1), io);
+	if (argv[0] === "validate") return runValidate(argv.slice(1), io);
 	let args;
 	try {
 		args = parseArgs({
@@ -1809,5 +2028,36 @@ function runBadge(argv, io) {
 	io.stdout(JSON.stringify(renderBadge(report)));
 	return 0;
 }
+/**
+* `dsh-vet validate <report.json> [...]` — check reports against the
+* contract. Exit 0 when every file is valid, 1 when any is invalid (the
+* issues are data, printed for repair), 2 on usage or unreadable files.
+*/
+function runValidate(argv, io) {
+	const paths = argv.filter((arg) => arg !== "--help");
+	if (paths.length === 0 || argv.includes("--help")) {
+		io.stderr(`usage: dsh-vet validate <report.json> [<report.json> ...]\n\nCheck report file(s) against the dsh-vet/v1 contract.`);
+		return 2;
+	}
+	let worst = 0;
+	for (const path of paths) {
+		let parsed;
+		try {
+			parsed = JSON.parse(readFileSync(path, "utf8"));
+		} catch (err) {
+			io.stderr(`dsh-vet validate: cannot read report: ${err.message}`);
+			return 2;
+		}
+		const { ok, issues } = validateReport(parsed);
+		if (ok) {
+			io.stdout(`ok      ${path}`);
+			continue;
+		}
+		worst = 1;
+		io.stdout(`invalid ${path}`);
+		for (const issue of issues) io.stdout(`  ${issue.path}: ${issue.message}`);
+	}
+	return worst;
+}
 //#endregion
-export { RULES, RULE_ID_PATTERN, SCANNER_VERSION, SCHEMA_ID, VetError, analyze, classifySpecifier, countFindings, createReport, gradeFor, isGraded, parseNpmSpecifier, reachableFrom, renderBadge, resolveTarget, ruleIds, runCli, runRules, scan, scanDirectory };
+export { RULES, RULE_ID_PATTERN, SCANNER_VERSION, SCHEMA_ID, SEVERITY_RANK, VetError, analyze, classifySpecifier, countFindings, createReport, gradeFor, isGraded, parseNpmSpecifier, reachableFrom, renderBadge, renderMarkdown, resolveTarget, ruleIds, runCli, runRules, scan, scanDirectory, validateReport };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-vet",
-  "version": "0.2.6",
+  "version": "0.3.0",
   "description": "Security vetting for DeepSeek Harness (DSH) plugins: permission & supply-chain audits before install, graded via the open dsh-vet/v1 report standard.",
   "dsh": {
     "seams": ["fs", "shell", "web"]