dsh-standards 1.2.2 → 1.3.0

package/40-checker/src/author-cli.mjs

@@ -0,0 +1,139 @@
+/**
+ * `dsh-standards check [dir]` — the author-facing entry point.
+ *
+ * It shells out to the existing checker in JSON mode and only changes how the
+ * same report is presented: Markdown by default, `--json` for the raw
+ * `dsh-conformance/1` document, `--html <file>` for a single self-contained
+ * file. Exit codes are the checker's, never rewritten here.
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { renderHtml, renderMarkdown } from './author-report.mjs'
+
+const HERE = path.dirname(fileURLToPath(import.meta.url))
+const CHECKER = path.resolve(HERE, '..', 'bin', 'dsh-plugin-verify.mjs')
+const MAX_BUFFER = 64 * 1024 * 1024
+
+/** Checker flags that take a value, so `check --scope entry` is not read as a directory. */
+const VALUE_FLAGS = new Set([
+  '--scope', '--profile', '--runtime', '--runtime-version', '--cordis-version', '--commit',
+  '--install-spec', '--market-index', '--plugin-name', '--timeout', '--host', '--base',
+  '--web', '--bare', '--entry-runtime', '--entry-claim',
+])
+
+export function checkUsage() {
+  return `dsh-standards check — author-facing standards report
+
+Usage:
+  dsh-standards check [dir] [options]
+
+  dir defaults to the current directory. Output defaults to Markdown.
+
+Options:
+  --json                 print the raw dsh-conformance/1 report
+  --html <file>          write a single-file HTML report (inline CSS, no assets)
+  --help                 show this help
+
+Any other flag is forwarded to the checker, e.g.:
+  --scope entry --entry-claim static --no-exec
+  --runtime-version 0.2.2-rc.1
+  --market-index index.json --plugin-name @scope/name
+
+Exit codes (same as the checker):
+  0  completed, no FAIL (PASS or WARN)
+  1  completed, at least one FAIL
+  2  incomplete: a mandatory check did not run
+  3  usage error
+`
+}
+
+export function parseCheckArgs(argv = []) {
+  const options = { dir: null, json: false, html: null, help: false, passthrough: [] }
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index]
+    if (arg === '--help' || arg === '-h') { options.help = true; continue }
+    if (arg === '--json') { options.json = true; continue }
+    if (arg === '--html' || arg.startsWith('--html=')) {
+      const inline = arg.startsWith('--html=') ? arg.slice('--html='.length) : undefined
+      if (inline !== undefined) {
+        if (inline.trim() === '') throw new Error('--html needs a file path')
+        options.html = inline
+      } else {
+        const next = argv[index + 1]
+        if (next === undefined || next.startsWith('--')) throw new Error('--html needs a file path')
+        options.html = next
+        index += 1
+      }
+      continue
+    }
+    if (arg === '--format' || arg.startsWith('--format=')) throw new Error('`check` owns the output format; use --json or --html <file>')
+    if (arg === '--out' || arg.startsWith('--out=')) throw new Error('`check` writes to stdout or --html <file>; --out is not forwarded')
+    if (arg.startsWith('-')) {
+      options.passthrough.push(arg)
+      if (arg.includes('=')) continue
+      if (VALUE_FLAGS.has(arg)) {
+        const next = argv[index + 1]
+        if (next === undefined) throw new Error(`${arg} needs a value`)
+        options.passthrough.push(next)
+        index += 1
+      }
+      continue
+    }
+    if (options.dir !== null) throw new Error(`unexpected positional argument: ${arg}`)
+    options.dir = arg
+  }
+  if (options.json && options.html) throw new Error('--json and --html are mutually exclusive')
+  if (options.dir === null) options.dir = '.'
+  options.dir = path.resolve(options.dir)
+  return options
+}
+
+function invokeChecker(options) {
+  const args = [CHECKER, options.dir, '--format', 'json', ...options.passthrough]
+  const run = spawnSync(process.execPath, args, { encoding: 'utf8', timeout: 600_000, maxBuffer: MAX_BUFFER })
+  if (run.error) throw new Error(`could not run the checker: ${run.error.message}`)
+  let report
+  try {
+    report = JSON.parse(run.stdout)
+  } catch {
+    throw new Error(`checker produced no JSON (exit ${run.status}): ${String(run.stderr ?? '').slice(0, 400)}`)
+  }
+  return { report, status: run.status }
+}
+
+export function runCheck(argv = process.argv.slice(2)) {
+  let options
+  try {
+    options = parseCheckArgs(argv)
+  } catch (error) {
+    process.stderr.write(`dsh-standards check: ${error.message}\n`)
+    process.stderr.write(checkUsage())
+    return 3
+  }
+  if (options.help) {
+    process.stdout.write(checkUsage())
+    return 0
+  }
+  let result
+  try {
+    result = invokeChecker(options)
+  } catch (error) {
+    process.stderr.write(`dsh-standards check: ${error.message}\n`)
+    return 3
+  }
+  const { report, status } = result
+  const exitCode = Number.isInteger(report?.conclusion?.exitCode) ? report.conclusion.exitCode : (status ?? 3)
+  if (options.html) {
+    const out = path.resolve(options.html)
+    fs.mkdirSync(path.dirname(out), { recursive: true })
+    fs.writeFileSync(out, renderHtml(report))
+    process.stdout.write(`wrote ${out}\n`)
+  } else if (options.json) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`)
+  } else {
+    process.stdout.write(renderMarkdown(report))
+  }
+  return exitCode
+}

package/40-checker/src/author-report.mjs

@@ -0,0 +1,260 @@
+/**
+ * Author-facing renderers for a `dsh-conformance/1` report.
+ *
+ * Markdown is the default `dsh-standards check` output; HTML is a single
+ * self-contained file with inline CSS, no scripts, no external assets, and
+ * every dynamic value escaped. Both read the same report object the checker
+ * already produced, so the verdict and exit code never change here.
+ */
+
+const DISCLAIMER =
+  'Non-official report. This is not a certification, security audit, endorsement, or ranking. '
+  + 'Hygiene warnings are not a clean pass; items under "Not checked" were not inspected.'
+
+function text(value) {
+  return String(value ?? '').replace(/\s+/g, ' ').trim()
+}
+
+function mdCell(value) {
+  return text(value).replace(/\|/g, '\\|')
+}
+
+export function escapeHtml(value) {
+  return String(value ?? '').replace(/[&<>"']/g, character => ({
+    '&': '&amp;',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&#39;',
+  }[character]))
+}
+
+function headlineOf(report) {
+  return text(report?.conclusion?.headline) || text(report?.conclusion?.reason) || 'no conclusion'
+}
+
+export function priorityFixes(report, limit = 3) {
+  const advice = Array.isArray(report?.advice) ? report.advice : []
+  const seen = new Set()
+  const fixes = []
+  for (const item of advice) {
+    const key = item?.key ?? item?.title
+    if (key === undefined || seen.has(key)) continue
+    seen.add(key)
+    fixes.push(item)
+    if (fixes.length >= limit) break
+  }
+  if (fixes.length > 0) return fixes
+  // Advice may be disabled; fall back to the FAIL/WARN rows themselves.
+  const rows = [...(report?.buckets?.blocking ?? []), ...(report?.buckets?.hygiene ?? [])]
+  for (const row of rows) {
+    if (fixes.length >= limit) break
+    fixes.push({ key: row.id, gate: row.result, severity: row.result, source: row.id, fix: row.reason, why: null, docsUrl: null })
+  }
+  return fixes
+}
+
+function passedIds(report) {
+  return (report?.checks ?? []).filter(item => item.result === 'PASS').map(item => item.id)
+}
+
+function adviceRows(report) {
+  return Array.isArray(report?.advice) ? report.advice : []
+}
+
+const BUCKETS = [
+  { key: 'blocking', title: 'Blocking (FAIL)' },
+  { key: 'hygiene', title: 'Hygiene (WARN)' },
+  { key: 'notChecked', title: 'Not checked (NA / not-run / ERROR)' },
+]
+
+function bucketRows(report, key) {
+  return Array.isArray(report?.buckets?.[key]) ? report.buckets[key] : []
+}
+
+export function renderMarkdown(report) {
+  const subject = report?.subject ?? {}
+  const conclusion = report?.conclusion ?? {}
+  const coverage = report?.coverage ?? {}
+  const metrics = report?.metrics ?? {}
+  const anchor = report?.anchor ?? {}
+  const lines = []
+  lines.push(`# DSH standards check — ${text(subject.name) || '<unknown>'}@${text(subject.version) || '?'}`)
+  lines.push('')
+  lines.push(`**Conclusion:** ${headlineOf(report)}`)
+  lines.push('')
+  lines.push(`- Status: **${text(conclusion.status) || 'unknown'}** (exit ${conclusion.exitCode ?? '?'})`)
+  if (conclusion.level) lines.push(`- Level: ${text(conclusion.level)}`)
+  lines.push(`- Anchor: dsh=${text(anchor.dsh) || '?'}${anchor.runtimeSource ? ` (source=${anchor.runtimeSource}${anchor.suspect ? ', suspect=true' : ''})` : ''}`)
+  lines.push(`- Coverage: ${metrics.checked ?? coverage.checked ?? 0}/${metrics.total ?? coverage.total ?? (report?.checks ?? []).length} checks evaluated · declared fields ${metrics.declaredFields ?? 0}/5`)
+  lines.push('')
+
+  lines.push('## Priority fixes (up to 3)')
+  lines.push('')
+  const fixes = priorityFixes(report)
+  if (fixes.length === 0) {
+    lines.push('_None: no FAIL or WARN finding produced advice._')
+  } else {
+    fixes.forEach((item, index) => {
+      lines.push(`${index + 1}. **${text(item.severity ?? item.gate ?? 'WARN')} ${text(item.key) || text(item.title)}** (${text(item.source)}) — ${text(item.fix ?? item.title ?? item.reason)}`)
+      if (item.why) lines.push(`   - Why: ${text(item.why)}`)
+      if (item.docsUrl) lines.push(`   - Docs: ${text(item.docsUrl)}`)
+    })
+  }
+  lines.push('')
+
+  for (const bucket of BUCKETS) {
+    const rows = bucketRows(report, bucket.key)
+    lines.push(`## ${bucket.title} — ${rows.length}`)
+    lines.push('')
+    if (rows.length === 0) {
+      lines.push('_None._')
+    } else {
+      lines.push('| id | clause | result | coverage | reason |')
+      lines.push('|---|---|---|---|---|')
+      for (const row of rows) {
+        const tags = [row.declaration ? 'declaration' : null, row.advisory ? 'advisory' : null].filter(Boolean)
+        const reason = tags.length > 0 ? `${text(row.reason)} [${tags.join(',')}]` : text(row.reason)
+        lines.push(`| ${mdCell(row.id)} | ${mdCell(row.clause ?? '-')} | ${mdCell(row.result)} | ${mdCell(row.coverage ?? '-')} | ${mdCell(reason)} |`)
+      }
+    }
+    lines.push('')
+  }
+
+  const passed = passedIds(report)
+  lines.push(`## Passed — ${passed.length}`)
+  lines.push('')
+  lines.push(passed.length > 0 ? passed.join(', ') : '_None._')
+  lines.push('')
+
+  const advice = adviceRows(report)
+  lines.push(`## Advice (non-blocking) — ${advice.length}`)
+  lines.push('')
+  if (advice.length === 0) {
+    lines.push('_None._')
+  } else {
+    for (const item of advice) {
+      const missing = item.ruleMissing ? ' [ruleMissing]' : ''
+      lines.push(`- ${text(item.severity)} ${text(item.key)} (${text(item.source)}${missing}): ${text(item.fix ?? item.title ?? '')}`)
+      if (item.docsUrl) lines.push(`  ${text(item.docsUrl)}`)
+    }
+  }
+  lines.push('')
+
+  const notChecked = bucketRows(report, 'notChecked')
+  lines.push('## What this report does not check')
+  lines.push('')
+  if (notChecked.length === 0) {
+    lines.push('- No check was skipped in this run.')
+  } else {
+    for (const row of notChecked) {
+      lines.push(`- ${text(row.id)}${row.clause ? ` (${text(row.clause)})` : ''}: ${text(row.reason) || 'not checked'}`)
+    }
+  }
+  lines.push(`- Runtime execution beyond the checks listed above is not observed by this report${anchor.suspect ? '; the anchor differs from the host and is flagged suspect' : ''}.`)
+  lines.push('- It does not certify, rank, audit security, or endorse the package.')
+  lines.push('')
+  lines.push('---')
+  lines.push('')
+  lines.push(DISCLAIMER)
+  lines.push('')
+  return `${lines.join('\n')}\n`
+}
+
+export function renderHtml(report) {
+  const subject = report?.subject ?? {}
+  const conclusion = report?.conclusion ?? {}
+  const metrics = report?.metrics ?? {}
+  const anchor = report?.anchor ?? {}
+  const title = `DSH standards check — ${text(subject.name) || '<unknown>'}@${text(subject.version) || '?'}`
+  const fixes = priorityFixes(report)
+  const advice = adviceRows(report)
+  const passed = passedIds(report)
+  const notChecked = bucketRows(report, 'notChecked')
+
+  const table = (key) => {
+    const rows = bucketRows(report, key)
+    if (rows.length === 0) return '<p class="none">None.</p>'
+    const body = rows.map(row => {
+      const tags = [row.declaration ? 'declaration' : null, row.advisory ? 'advisory' : null].filter(Boolean)
+      const reason = tags.length > 0 ? `${text(row.reason)} [${tags.join(',')}]` : text(row.reason)
+      return `<tr><td>${escapeHtml(row.id)}</td><td>${escapeHtml(row.clause ?? '-')}</td><td class="result ${escapeHtml(String(row.result).toLowerCase())}">${escapeHtml(row.result)}</td><td>${escapeHtml(row.coverage ?? '-')}</td><td>${escapeHtml(reason)}</td></tr>`
+    }).join('\n')
+    return `<table><thead><tr><th>id</th><th>clause</th><th>result</th><th>coverage</th><th>reason</th></tr></thead><tbody>\n${body}\n</tbody></table>`
+  }
+
+  const fixList = fixes.length === 0
+    ? '<p class="none">None: no FAIL or WARN finding produced advice.</p>'
+    : `<ol>${fixes.map(item => {
+      const why = item.why ? `<br><span class="muted">Why: ${escapeHtml(text(item.why))}</span>` : ''
+      const docs = item.docsUrl ? `<br><span class="muted">Docs: ${link(item.docsUrl)}</span>` : ''
+      return `<li><strong>${escapeHtml(text(item.severity ?? item.gate ?? 'WARN'))} ${escapeHtml(text(item.key) || text(item.title))}</strong> (${escapeHtml(text(item.source))}) — ${escapeHtml(text(item.fix ?? item.title ?? item.reason))}${why}${docs}</li>`
+    }).join('\n')}</ol>`
+
+  const adviceList = advice.length === 0
+    ? '<p class="none">None.</p>'
+    : `<ul>${advice.map(item => `<li><strong>${escapeHtml(text(item.severity))} ${escapeHtml(text(item.key))}</strong> (${escapeHtml(text(item.source))}${item.ruleMissing ? ' [ruleMissing]' : ''}): ${escapeHtml(text(item.fix ?? item.title ?? ''))}${item.docsUrl ? ` ${link(item.docsUrl)}` : ''}</li>`).join('\n')}</ul>`
+
+  const notCheckedList = notChecked.length === 0
+    ? '<li>No check was skipped in this run.</li>'
+    : notChecked.map(row => `<li><strong>${escapeHtml(text(row.id))}</strong>${row.clause ? ` (${escapeHtml(text(row.clause))})` : ''}: ${escapeHtml(text(row.reason) || 'not checked')}</li>`).join('\n')
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(title)}</title>
+<style>
+:root{color-scheme:light dark}
+body{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,"PingFang SC","Microsoft YaHei",sans-serif;max-width:980px;margin:2rem auto;padding:0 1rem;line-height:1.55;color:#1f2328;background:#fff}
+h1{font-size:1.45rem;margin:0 0 .35rem}
+h2{font-size:1.1rem;margin:1.8rem 0 .5rem;border-bottom:1px solid #d0d7de;padding-bottom:.25rem}
+.headline{font-size:1.05rem;font-weight:600;background:#f6f8fa;border:1px solid #d0d7de;border-radius:6px;padding:.65rem .8rem}
+.meta{margin:.6rem 0 0;padding-left:1.1rem;color:#57606a}
+.muted{color:#57606a;font-size:.9rem}
+table{border-collapse:collapse;width:100%;margin:.4rem 0 1rem;font-size:.9rem}
+th,td{border:1px solid #d0d7de;padding:.3rem .5rem;text-align:left;vertical-align:top}
+th{background:#f6f8fa}
+td.result{font-weight:600;white-space:nowrap}
+td.result.fail{color:#b42318}
+td.result.warn{color:#9a6700}
+td.result.na,td.result.error,td.result.not-run{color:#57606a}
+.none{color:#57606a}
+footer{margin-top:2rem;padding-top:.8rem;border-top:1px solid #d0d7de;color:#57606a;font-size:.9rem}
+code{font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace}
+@media (prefers-color-scheme:dark){body{background:#0d1117;color:#e6edf3}h2,.headline,th,td,footer{border-color:#30363d}.headline,th{background:#161b22}.meta,.muted,.none,footer{color:#8b949e}td.result.fail{color:#ff7b72}td.result.warn{color:#d29922}}
+</style>
+</head>
+<body>
+<h1>${escapeHtml(title)}</h1>
+<p class="headline">${escapeHtml(headlineOf(report))}</p>
+<ul class="meta">
+<li>Status: <strong>${escapeHtml(text(conclusion.status) || 'unknown')}</strong> (exit ${escapeHtml(conclusion.exitCode ?? '?')})${conclusion.level ? ` · Level: ${escapeHtml(text(conclusion.level))}` : ''}</li>
+<li>Anchor: dsh=${escapeHtml(text(anchor.dsh) || '?')}${anchor.runtimeSource ? ` (source=${escapeHtml(anchor.runtimeSource)}${anchor.suspect ? ', suspect=true' : ''})` : ''}</li>
+<li>Coverage: ${escapeHtml(metrics.checked ?? 0)}/${escapeHtml(metrics.total ?? (report?.checks ?? []).length)} checks evaluated · declared fields ${escapeHtml(metrics.declaredFields ?? 0)}/5</li>
+</ul>
+<h2>Priority fixes (up to 3)</h2>
+${fixList}
+${BUCKETS.map(bucket => `<h2>${escapeHtml(bucket.title)} — ${bucketRows(report, bucket.key).length}</h2>\n${table(bucket.key)}`).join('\n')}
+<h2>Passed — ${passed.length}</h2>
+<p>${passed.length > 0 ? passed.map(escapeHtml).join(', ') : '<span class="none">None.</span>'}</p>
+<h2>Advice (non-blocking) — ${advice.length}</h2>
+${adviceList}
+<h2>What this report does not check</h2>
+<ul>
+${notCheckedList}
+<li>Runtime execution beyond the checks listed above is not observed by this report${anchor.suspect ? '; the anchor differs from the host and is flagged suspect' : ''}.</li>
+<li>It does not certify, rank, audit security, or endorse the package.</li>
+</ul>
+<footer>${escapeHtml(DISCLAIMER)}</footer>
+</body>
+</html>
+`
+}
+
+function link(url) {
+  const value = text(url)
+  if (!/^https:\/\//i.test(value)) return escapeHtml(value)
+  return `<a href="${escapeHtml(value)}" rel="noreferrer noopener">${escapeHtml(value)}</a>`
+}

package/40-checker/src/cli.mjs

@@ -12,19 +12,28 @@ import { buildReport, writeReport } from './report.mjs'
 const VERSION = '0.1.0'
 const DEFAULT_COMMIT = 'ce7073d51254c26cd63b22a60835b8f948deb447'
 const DEFAULT_CORDIS = '4.0.6-alpha.1'
+const HOST_RUNTIME_TIMEOUT_MS = 5000
+
+function binName() {
+  const brand = process.env.DSH_CHECKER_BRAND
+  if (typeof brand === 'string' && brand.trim() !== '') return brand.trim().split(/\s+/)[0]
+  return 'dsh-plugin-verify'
+}
 
 function usage() {
+  const bin = binName()
   return `${process.env.DSH_CHECKER_BRAND || 'dsh-plugin-verify ' + VERSION} — DS-C conformance checker (MVP)
 
 Usage:
-  dsh-plugin-verify <package-dir> [options]
+  ${bin} check [dir] [--json] [--html <file>]  author-facing report (Markdown by default)
+  ${bin} <package-dir> [options]                raw conformance report
 
 Options:
   --format text|json|sarif   output format (default: text)
   --scope mvp|ds-c|entry     mvp = 8 MVP ids; ds-c = full claim (default); entry = compatibility gate
   --profile package|listing|both  evaluation profile (default: package; listing if --market-index is set)
   --runtime <path>           path to a built @deepseek-ai/cordis lib/index.js; enables L1-L3
-  --runtime-version <v>      dsh runtime version used for C-2 (default: ${DEFAULT_RUNTIME_VERSION})
+  --runtime-version <v>      dsh runtime version used for C-2 (default: host via \`dsh --version\`, else ${DEFAULT_RUNTIME_VERSION})
   --cordis-version <v>       cordis version recorded in the anchor (default: ${DEFAULT_CORDIS})
   --commit <sha>             harness commit recorded in the anchor (default: ${DEFAULT_COMMIT.slice(0, 12)})
   --install-spec <spec>      recommended install spec for C-3 (listing/install check)
@@ -61,7 +70,7 @@ function parseArgs(argv) {
     scope: 'ds-c',
     profile: null,
     runtime: null,
-    runtimeVersion: DEFAULT_RUNTIME_VERSION,
+    runtimeVersion: null,
     cordisVersion: DEFAULT_CORDIS,
     commit: DEFAULT_COMMIT,
     installSpec: null,
@@ -223,14 +232,66 @@ async function entryRunCheck(kind, runtimeChecks, options, dir) {
   return { ...base, result: 'ERROR', coverage: 'not-run', reason: c4?.reason || 'no runtime evidence' }
 }
 
-function anchorOf(options, runtime) {
+/**
+ * Read the runtime version the host actually runs. The anchor used to be a
+ * hard-coded `0.2.2-alpha.2`, which manufactured dozens of C-2.2 failures on a
+ * host that had already moved on. Detection is best-effort: when `dsh` is not
+ * usable the anchor falls back to the checked-in constant and says so.
+ */
+export function detectHostRuntime({ bin = process.env.DSH_BIN || (process.platform === 'win32' ? 'dsh.cmd' : 'dsh'), timeoutMs = HOST_RUNTIME_TIMEOUT_MS } = {}) {
+  const run = spawnSync(bin, ['--version'], { encoding: 'utf8', timeout: timeoutMs })
+  if (run.error || run.status !== 0) return { version: null, bin, error: run.error?.message ?? `exit ${run.status}` }
+  const text = `${run.stdout ?? ''}\n${run.stderr ?? ''}`
+  const match = /(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?)/.exec(text)
+  if (!match) return { version: null, bin, error: 'no semver in `dsh --version` output' }
+  return { version: match[1], bin, error: null }
+}
+
+/**
+ * Resolve what `anchor.dsh` means:
+ *   cli       the caller passed --runtime-version; suspect when it differs from the host
+ *   host      no flag: the host version is the anchor, so it cannot be suspect
+ *   fallback  dsh unavailable: keep the constant, flagged as not host-derived
+ */
+export function resolveRuntimeAnchor(requestedVersion = null, hostVersion = null) {
+  if (typeof requestedVersion === 'string' && requestedVersion.trim() !== '') {
+    const requested = requestedVersion.trim()
+    return {
+      dsh: requested,
+      runtimeSource: 'cli',
+      hostVersion: hostVersion ?? null,
+      suspect: typeof hostVersion === 'string' && hostVersion !== '' && hostVersion !== requested,
+    }
+  }
+  if (typeof hostVersion === 'string' && hostVersion !== '') {
+    return { dsh: hostVersion, runtimeSource: 'host', hostVersion, suspect: false }
+  }
+  return { dsh: DEFAULT_RUNTIME_VERSION, runtimeSource: 'fallback', hostVersion: null, suspect: false }
+}
+
+/** The five optional declaration surfaces, counted but never scored. */
+export function declarationsOf(manifest) {
+  const dsh = manifest?.dsh ?? {}
+  const present = []
+  if (Array.isArray(dsh.capabilities) && dsh.capabilities.length > 0) present.push('capabilities')
+  if (Array.isArray(dsh.labels) && dsh.labels.length > 0) present.push('labels')
+  if (dsh.commitments && typeof dsh.commitments === 'object' && !Array.isArray(dsh.commitments)) present.push('commitments')
+  if (dsh.disclosure && typeof dsh.disclosure === 'object' && !Array.isArray(dsh.disclosure)) present.push('disclosure')
+  if (typeof manifest?.engines?.dsh === 'string' && manifest.engines.dsh.trim() !== '') present.push('engines.dsh')
+  return { total: 5, present }
+}
+
+function anchorOf(options, runtimeInfo, runtimePath) {
   return {
     repo: 'deepseek-ai/deepseek-harness',
     commit: options.commit,
     scanner: `dsh-plugin-verify@${VERSION}`,
-    dsh: options.runtimeVersion,
+    dsh: runtimeInfo.dsh,
     cordis: options.cordisVersion,
-    runtime: runtime ? path.resolve(runtime) : null,
+    runtime: runtimePath ? path.resolve(runtimePath) : null,
+    runtimeSource: runtimeInfo.runtimeSource,
+    hostVersion: runtimeInfo.hostVersion,
+    suspect: runtimeInfo.suspect,
   }
 }
 
@@ -261,8 +322,11 @@ export async function main(argv = process.argv.slice(2)) {
     return 3
   }
 
+  const host = detectHostRuntime()
+  const runtimeInfo = resolveRuntimeAnchor(options.runtimeVersion, host.version)
+
   const { manifest, kind, kindInferred, entry, patch, g4, checks: manifestChecks } = runManifestChecks(dir, {
-    runtimeVersion: options.runtimeVersion,
+    runtimeVersion: runtimeInfo.dsh,
     installSpec: options.installSpec,
     marketIndex: options.marketIndex,
     pluginName: options.pluginName,
@@ -341,7 +405,7 @@ export async function main(argv = process.argv.slice(2)) {
   }
   const report = buildReport({
     subject,
-    anchor: anchorOf(options, options.runtime),
+    anchor: anchorOf(options, runtimeInfo, options.runtime),
     checks,
     g4,
     scope: options.scope,
@@ -351,6 +415,7 @@ export async function main(argv = process.argv.slice(2)) {
     entryRuntime: options.entryRuntime,
     entryClaim: options.entryClaim,
     advice: options.advice,
+    declarations: declarationsOf(manifest),
   })
   const output = writeReport(report, options.format)
   if (options.out) {

package/40-checker/src/flow-evidence.mjs

@@ -25,7 +25,9 @@
  */
 import crypto from 'node:crypto'
 import fs from 'node:fs'
+import os from 'node:os'
 import path from 'node:path'
+import { spawnSync } from 'node:child_process'
 
 export const FLOW_IDS = ['J1', 'J2', 'J3', 'J4', 'J5', 'J6', 'J7', 'J8']
 export const FLOW_EVIDENCE_SCHEMA = 'dsh-flow-evidence/2'
@@ -144,6 +146,103 @@ export function treeSha256(dir, { exclude = [] } = {}) {
   return { hash: sha256Value(rows.join('\n')), files: rows.length, bytes }
 }
 
+const NPM = process.platform === 'win32' ? 'npm.cmd' : 'npm'
+
+function subjectFields(subject) {
+  if (!isPlainObject(subject)) return null
+  return {
+    name: subject.name ?? null,
+    version: subject.version ?? null,
+    integrity: subject.integrity ?? null,
+    tarballSha256: subject.tarballSha256 ?? null,
+    treeSha256: subject.treeSha256 ?? null,
+    commit: subject.commit ?? null,
+  }
+}
+
+/**
+ * Recompute the subject binding from a package directory: package.json
+ * name/version, the deterministic tree hash, and the npm-pack tarball hash +
+ * integrity. npm packs the same tree byte-identically, so this is the same
+ * binding `dsh-flow-collect` recorded.
+ */
+export function recomputeSubject(dir, { exclude = [], timeoutMs = 120_000 } = {}) {
+  const root = path.resolve(dir)
+  const manifest = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'))
+  const tree = treeSha256(root, { exclude })
+  const destination = fs.mkdtempSync(path.join(os.tmpdir(), 'dsh-subject-'))
+  try {
+    const run = spawnSync(NPM, ['pack', '--ignore-scripts', '--json', '--pack-destination', destination], {
+      cwd: root, encoding: 'utf8', timeout: timeoutMs, maxBuffer: 16 * 1024 * 1024,
+    })
+    if (run.error) throw new Error(`npm pack failed to start: ${run.error.message}`)
+    if (run.status !== 0) throw new Error(`npm pack failed (exit ${run.status}): ${String(run.stderr ?? '').replace(/\s+/g, ' ').slice(0, 300)}`)
+    let parsed
+    try { parsed = JSON.parse(run.stdout) } catch { throw new Error('npm pack did not print JSON') }
+    const info = Array.isArray(parsed) ? parsed[0] : parsed
+    if (!info?.filename) throw new Error('npm pack did not report a tarball filename')
+    return {
+      name: typeof manifest.name === 'string' ? manifest.name : null,
+      version: typeof manifest.version === 'string' ? manifest.version : null,
+      treeSha256: tree.hash,
+      tarballSha256: sha256File(path.join(destination, info.filename)),
+      integrity: typeof info.integrity === 'string' ? info.integrity : null,
+    }
+  } finally {
+    fs.rmSync(destination, { recursive: true, force: true })
+  }
+}
+
+/**
+ * Bind a flow-evidence document to a package directory. Any mismatch in
+ * name/version/treeSha256/tarballSha256 (or a declared integrity) is a hard
+ * failure: the audit must not accept evidence for a different subject.
+ */
+export function bindEvidenceSubject(document, dir, options = {}) {
+  const declared = isPlainObject(document?.subject) ? document.subject : null
+  const base = { dir: path.resolve(dir), declared: subjectFields(declared), recomputed: null, mismatches: [], errors: [] }
+  if (!declared) return { ...base, ok: false, errors: ['subject is missing'] }
+  let recomputed
+  try {
+    recomputed = recomputeSubject(dir, {
+      exclude: Array.isArray(declared.treeExclude) ? declared.treeExclude : [],
+      timeoutMs: options.timeoutMs,
+    })
+  } catch (error) {
+    return { ...base, ok: false, errors: [error.message] }
+  }
+  const mismatches = []
+  for (const key of ['name', 'version', 'treeSha256', 'tarballSha256']) {
+    if (declared[key] !== recomputed[key]) {
+      mismatches.push(`${key}: declared ${declared[key] ?? 'null'} != recomputed ${recomputed[key] ?? 'null'}`)
+    }
+  }
+  if (typeof declared.integrity === 'string' && recomputed.integrity !== null && declared.integrity !== recomputed.integrity) {
+    mismatches.push('integrity: declared value != recomputed value')
+  }
+  return { ...base, ok: mismatches.length === 0, recomputed, mismatches }
+}
+
+/**
+ * Plain CI attribution for display. These fields are read from the runner
+ * environment and are self-declared: CI attribution is not proof.
+ */
+export function ciAttribution(env = process.env) {
+  const read = key => (typeof env?.[key] === 'string' ? env[key].trim() : '')
+  const runId = read('GITHUB_RUN_ID')
+  const repository = read('GITHUB_REPOSITORY')
+  const commit = read('GITHUB_SHA')
+  if (!runId && !repository && !commit) return null
+  const server = (read('GITHUB_SERVER_URL') || 'https://github.com').replace(/\/+$/, '')
+  return {
+    provider: 'github-actions',
+    runId: runId || null,
+    repository: repository || null,
+    commit: commit || null,
+    runUrl: runId && repository ? `${server}/${repository}/actions/runs/${runId}` : null,
+  }
+}
+
 export function isIsoTimestamp(value) {
   return typeof value === 'string' && ISO_RE.test(value) && Number.isFinite(Date.parse(value))
 }
@@ -279,9 +378,15 @@ function validateV2(document) {
     if ('kind' in document.producer && document.producer.kind !== null && !['local', 'ci', 'sandbox', 'sandbox-degraded'].includes(document.producer.kind)) {
       errors.push('producer.kind must be local, ci, sandbox, or sandbox-degraded')
     }
-    for (const key of ['runner', 'actor', 'runUrl']) {
+    for (const key of ['runner', 'actor', 'runUrl', 'provider', 'runId', 'repository', 'commit']) {
       if (key in document.producer && document.producer[key] !== null) requireString(document.producer[key], `producer.${key}`)
     }
+    if (typeof document.producer.commit === 'string' && !COMMIT_RE.test(document.producer.commit)) {
+      errors.push('producer.commit must be a 40-hex commit')
+    }
+    if (typeof document.producer.runUrl === 'string' && !/^https:\/\//.test(document.producer.runUrl)) {
+      errors.push('producer.runUrl must be an https URL')
+    }
   }
 
   if (requireObject(document.subject, 'subject')) {