dsh-standards 0.0.2 → 1.0.0

package/40-checker/scripts/level-audit.mjs

@@ -0,0 +1,336 @@
+#!/usr/bin/env node
+/**
+ * level-audit.mjs — one-command self-check against the three DSH adoption levels.
+ *
+ * What it does:
+ *   ENTRY  runs the existing ENTRY checker (static by default; real G0-G3 boot
+ *          when --host is supplied) and maps its conclusion to an evidence state.
+ *   FLOW   reads an optional J1-J8 evidence file; with no file it reports the
+ *          checklist as `not-run` and never invents a pass.
+ *   BOOST  reads an optional LEV evidence file; with no file it reports
+ *          `not-measured`. It does not run benchmarks for you.
+ *
+ * The machine source of truth is `spec/levels.json`; this tool only reads it.
+ * Zero dependencies: it shells out to the checker already in this repo.
+ *
+ * Usage:
+ *   node 40-checker/scripts/level-audit.mjs <plugin-dir>
+ *   node 40-checker/scripts/level-audit.mjs <bundle-dir> --host <app-boot/lib/index.js> \
+ *     --base <dsh-base/cordis.patch.yml> --bare <farm> [--timeout 150000]
+ *   node 40-checker/scripts/level-audit.mjs <dir> --flow-evidence flow.json \
+ *     --boost-evidence boost.json --format json --out audit.json
+ *
+ * Exit codes: 0 ENTRY recognized/runtime; 2 ENTRY failed; 3 audit could not run.
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+
+const HERE = path.dirname(fileURLToPath(import.meta.url))
+const STD = path.resolve(HERE, '..', '..')
+const LEVELS_PATH = path.join(STD, 'spec', 'levels.json')
+const CHECKER = path.join(STD, '40-checker', 'bin', 'dsh-plugin-verify.mjs')
+
+function usage() {
+  console.log(`level-audit — DSH-ENTRY / FLOW / BOOST self-check
+
+Usage:
+  node 40-checker/scripts/level-audit.mjs <plugin-dir> [options]
+
+Options:
+  --host <file>            app-boot lib/index.js; enables real ENTRY G0-G3
+  --base <file>            dsh-base cordis.patch.yml
+  --bare <dir>             bare-module farm for the bundle smoke
+  --no-runtime             force static ENTRY even when --host is given
+  --flow-evidence <file>   JSON: { "J1": { "status": "pass|fail|not-run", "evidence": "..." }, ... }
+  --boost-evidence <file>  JSON: { "LEV-3": { "status": "measured|not-measured|failed", "evidenceCard": { ... } }, ... }
+                            measured requires a valid evidence card; a status-only row is downgraded to not-measured
+  --timeout <ms>           checker timeout, default 150000
+  --format text|json       default text
+  --out <file>             write the JSON result
+  --help                   show this help
+
+The tool never upgrades a skip to a pass. FLOW and BOOST without evidence files
+are reported as not-run / not-measured.`)
+}
+
+function parseArgs(argv) {
+  const options = {
+    dir: null, host: null, base: null, bare: null, runtime: true,
+    flowEvidence: null, boostEvidence: null, timeout: 150_000,
+    format: 'text', out: null,
+  }
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]
+    const next = () => {
+      const value = argv[i + 1]
+      if (value === undefined) throw new Error(`${arg} needs a value`)
+      i += 1
+      return value
+    }
+    if (arg === '--host') options.host = next()
+    else if (arg === '--base') options.base = next()
+    else if (arg === '--bare') options.bare = next()
+    else if (arg === '--no-runtime') options.runtime = false
+    else if (arg === '--flow-evidence') options.flowEvidence = next()
+    else if (arg === '--boost-evidence') options.boostEvidence = next()
+    else if (arg === '--timeout') options.timeout = Number(next())
+    else if (arg === '--format') options.format = next()
+    else if (arg === '--out') options.out = next()
+    else if (arg === '--help' || arg === '-h') { usage(); process.exit(0) }
+    else if (arg.startsWith('-')) throw new Error(`unknown option: ${arg}`)
+    else if (options.dir === null) options.dir = arg
+    else throw new Error(`unexpected argument: ${arg}`)
+  }
+  if (!options.dir) throw new Error('a plugin directory is required')
+  if (!['text', 'json'].includes(options.format)) throw new Error('--format must be text or json')
+  if (!Number.isFinite(options.timeout) || options.timeout < 1000) throw new Error('--timeout must be >= 1000')
+  options.dir = path.resolve(options.dir)
+  if (!fs.existsSync(path.join(options.dir, 'package.json'))) throw new Error(`not a package directory: ${options.dir}`)
+  return options
+}
+
+function readJson(file, label) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'))
+  } catch (error) {
+    throw new Error(`${label} is not valid JSON: ${error.message}`)
+  }
+}
+
+function runChecker(options) {
+  const args = [CHECKER, options.dir, '--scope', 'entry', '--format', 'json']
+  const canRun = options.runtime && options.host !== null
+  args.push('--entry-claim', canRun ? 'runtime' : 'static')
+  if (canRun) args.push('--host', options.host)
+  if (options.base) args.push('--base', options.base)
+  if (options.bare) args.push('--bare', options.bare)
+  const run = spawnSync(process.execPath, args, {
+    encoding: 'utf8',
+    timeout: options.timeout,
+    maxBuffer: 64 * 1024 * 1024,
+  })
+  let report = null
+  try {
+    report = JSON.parse(run.stdout)
+  } catch {
+    throw new Error(`checker did not emit JSON (exit ${run.status}): ${(run.stderr || '').slice(-500)}`)
+  }
+  return {
+    invoked: canRun ? 'runtime' : 'static',
+    exit: run.status,
+    report,
+  }
+}
+
+function checkById(report, id) {
+  return (report.checks ?? []).find(check => check.id === id)
+}
+
+function classifyEntry(report, invoked) {
+  const conclusion = report.conclusion ?? {}
+  const status = conclusion.status
+  const failed = (report.checks ?? []).filter(check => check.result === 'FAIL')
+  const warnings = (report.checks ?? []).filter(check => check.result === 'WARN')
+  const dsc14 = checkById(report, 'DSC-14')
+  let state
+  if (status === 'fail' || failed.length > 0) state = 'failed'
+  else if (status === 'pass' || status === 'warn') state = invoked === 'runtime' && dsc14?.result === 'PASS' ? 'runtime' : 'recognized'
+  else state = 'not-run'
+  return {
+    state,
+    claim: invoked,
+    checkerStatus: status ?? 'unknown',
+    checkerLevel: conclusion.level ?? null,
+    failed: failed.map(check => ({ id: check.id, reason: check.reason })),
+    warnings: warnings.map(check => ({ id: check.id, reason: check.reason })),
+    runtimeEvidence: dsc14 ? { result: dsc14.result, reason: dsc14.reason } : null,
+    g4: report.g4 ?? null,
+  }
+}
+
+function classifyFlow(evidence) {
+  const ids = ['J1', 'J2', 'J3', 'J4', 'J5', 'J6', 'J7', 'J8']
+  if (!evidence) {
+    return {
+      state: 'not-run',
+      reason: 'no --flow-evidence file; run the J1-J8 journeys and record pass/fail/not-run',
+      journeys: Object.fromEntries(ids.map(id => [id, { status: 'not-run' }])),
+    }
+  }
+  const journeys = {}
+  for (const id of ids) {
+    const row = evidence[id] ?? evidence[id.toLowerCase()]
+    const status = row?.status
+    journeys[id] = {
+      status: ['pass', 'fail', 'not-run', 'manual'].includes(status) ? status : 'not-run',
+      evidence: row?.evidence ?? null,
+    }
+  }
+  const failed = ids.filter(id => journeys[id].status === 'fail')
+  const passed = ids.filter(id => journeys[id].status === 'pass')
+  return {
+    state: failed.length > 0 ? 'failed' : passed.length === ids.length ? 'runtime' : 'not-run',
+    reason: failed.length > 0
+      ? `failed journeys: ${failed.join(', ')}`
+      : passed.length === ids.length
+        ? 'all J1-J8 have pass evidence'
+        : `${passed.length}/8 journeys have pass evidence`,
+    journeys,
+  }
+}
+
+const BOOST_CARD_FIELDS = [
+  'subject', 'host', 'method', 'scope', 'command', 'result', 'negativeControl',
+  'generatedAt', 'expiresAt', 'recordHash', 'claimLevel', 'issuer', 'selfAssessed',
+]
+const BOOST_CLAIM_LEVELS = new Set(['self-reported', 'self-assessed', 'host-reviewed', 'independent', 'reference'])
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/
+const HASH_RE = /^sha256:[0-9a-f]{64}$/
+
+function validateEvidenceCard(card) {
+  if (!card || typeof card !== 'object' || Array.isArray(card)) {
+    return { valid: false, missing: ['evidenceCard'], reason: 'missing evidence card' }
+  }
+  const missing = []
+  for (const field of BOOST_CARD_FIELDS) {
+    if (card[field] === undefined || card[field] === null || card[field] === '') missing.push(field)
+  }
+  if (!DATE_RE.test(String(card.generatedAt ?? ''))) missing.push('generatedAt(date)')
+  if (!DATE_RE.test(String(card.expiresAt ?? ''))) missing.push('expiresAt(date)')
+  if (!HASH_RE.test(String(card.recordHash ?? ''))) missing.push('recordHash(sha256)')
+  if (!BOOST_CLAIM_LEVELS.has(String(card.claimLevel ?? ''))) missing.push('claimLevel')
+  if (typeof card.selfAssessed !== 'boolean') missing.push('selfAssessed(boolean)')
+  if (missing.length > 0) {
+    return { valid: false, missing, reason: `evidence card missing/invalid: ${missing.join(', ')}` }
+  }
+  const generated = Date.parse(`${card.generatedAt}T00:00:00Z`)
+  const expires = Date.parse(`${card.expiresAt}T00:00:00Z`)
+  if (!Number.isFinite(generated) || !Number.isFinite(expires) || expires < generated) {
+    return { valid: false, missing: ['validity'], reason: 'evidence card has invalid generatedAt/expiresAt' }
+  }
+  return { valid: true, missing: [], reason: null }
+}
+
+function classifyBoost(evidence) {
+  const ids = ['LEV-1', 'LEV-2', 'LEV-3', 'LEV-4', 'LEV-5', 'LEV-6', 'LEV-7', 'LEV-8']
+  if (!evidence) {
+    return {
+      state: 'not-measured',
+      reason: 'no --boost-evidence file; benchmarks/evidence cards are not run by this tool',
+      practices: Object.fromEntries(ids.map(id => [id, { status: 'not-measured' }])),
+    }
+  }
+  const practices = {}
+  for (const id of ids) {
+    const row = evidence[id] ?? evidence[id.toLowerCase()]
+    const declared = row?.status
+    const card = row?.evidenceCard ?? (row?.evidence && typeof row.evidence === 'object' ? row.evidence : null)
+    const cardCheck = validateEvidenceCard(card)
+    let status = 'not-measured'
+    if (declared === 'failed') status = 'failed'
+    else if (declared === 'measured' && cardCheck.valid) status = 'measured'
+    practices[id] = {
+      status,
+      declared: ['measured', 'not-measured', 'failed'].includes(declared) ? declared : 'not-measured',
+      evidence: typeof row?.evidence === 'string' ? row.evidence : null,
+      evidenceCard: card,
+      card: cardCheck,
+    }
+  }
+  const failed = ids.filter(id => practices[id].status === 'failed')
+  const measured = ids.filter(id => practices[id].status === 'measured')
+  const today = new Date().toISOString().slice(0, 10)
+  const stale = measured.filter(id => String(practices[id].evidenceCard.expiresAt) < today)
+  const invalid = ids.filter(id => practices[id].declared === 'measured' && !practices[id].card.valid)
+  let state = 'not-measured'
+  if (failed.length > 0) state = 'failed'
+  else if (stale.length > 0) state = 'stale'
+  else if (measured.length === ids.length) state = 'measured'
+  const reasons = []
+  if (failed.length > 0) reasons.push(`failed practices: ${failed.join(', ')}`)
+  if (stale.length > 0) reasons.push(`stale evidence cards: ${stale.join(', ')}`)
+  if (invalid.length > 0) reasons.push(`measured without a valid evidence card: ${invalid.join(', ')}`)
+  if (failed.length === 0 && stale.length === 0 && measured.length !== ids.length) {
+    reasons.push(`${measured.length}/8 practices have valid measured evidence cards`)
+  }
+  return {
+    state,
+    reason: reasons.join('; '),
+    practices,
+    validCards: measured.length,
+    invalidCards: invalid.length,
+  }
+}
+
+function nextActions(entry, flow, boost) {
+  const actions = []
+  for (const failure of entry.failed) actions.push(`ENTRY: fix ${failure.id} — ${failure.reason}`)
+  if (entry.g4 && entry.g4.hasClient && entry.g4.ok === false) actions.push(`ENTRY: fix G4 — ${entry.g4.reason}`)
+  for (const warning of entry.warnings) actions.push(`ENTRY: consider ${warning.id} — ${warning.reason}`)
+  if (entry.state === 'recognized') actions.push('ENTRY: run with --host to replace static recognition with a real G0-G3 boot')
+  if (flow.state === 'not-run') actions.push('FLOW: record J1-J8 in a flow-evidence JSON; do not claim FLOW until they run')
+  if (boost.state === 'not-measured') actions.push('BOOST: attach LEV evidence cards (subject/host/method/scope/command/result/negativeControl/generatedAt/expiresAt/recordHash/claimLevel/issuer/selfAssessed); a status alone is not measured')
+  if (boost.state === 'stale') actions.push('BOOST: refresh stale evidence cards before claiming measured')
+  return actions
+}
+
+function render(result) {
+  const lines = [
+    `DSH level audit — ${result.target.dir}`,
+    `  ENTRY : ${result.levels.entry.state.padEnd(12)} (${result.levels.entry.checkerLevel ?? 'no level'})`,
+    `  FLOW  : ${result.levels.flow.state.padEnd(12)} ${result.levels.flow.reason}`,
+    `  BOOST : ${result.levels.boost.state.padEnd(12)} ${result.levels.boost.reason}`,
+  ]
+  if (result.nextActions.length > 0) {
+    lines.push('Next:')
+    for (const action of result.nextActions) lines.push(`  - ${action}`)
+  }
+  lines.push('Claims: not official, not a certification, not a security audit; static is not runtime.')
+  return lines.join('\n')
+}
+
+function main() {
+  const options = parseArgs(process.argv.slice(2))
+  const levels = JSON.parse(fs.readFileSync(LEVELS_PATH, 'utf8'))
+  const flowEvidence = options.flowEvidence ? readJson(options.flowEvidence, '--flow-evidence') : null
+  const boostEvidence = options.boostEvidence ? readJson(options.boostEvidence, '--boost-evidence') : null
+
+  const checker = runChecker(options)
+  const entry = classifyEntry(checker.report, checker.invoked)
+  const flow = classifyFlow(flowEvidence)
+  const boost = classifyBoost(boostEvidence)
+
+  const result = {
+    schema: 'dsh-level-audit/1',
+    generatedAt: new Date().toISOString(),
+    target: { dir: options.dir },
+    levelsSpec: { schema: levels.schema, version: levels.version, status: levels.status },
+    levels: { entry, flow, boost },
+    nextActions: nextActions(entry, flow, boost),
+    notClaimed: ['official standard', 'certification', 'security audit', 'ranking', 'production baseline'],
+    checker: {
+      invoked: checker.invoked,
+      exit: checker.exit,
+      schema: checker.report.schema,
+      anchor: checker.report.anchor,
+      coverage: checker.report.coverage,
+    },
+  }
+
+  const output = options.format === 'json' ? JSON.stringify(result, null, 2) : render(result)
+  if (options.out) {
+    fs.mkdirSync(path.dirname(path.resolve(options.out)), { recursive: true })
+    fs.writeFileSync(options.out, `${output}\n`)
+  }
+  process.stdout.write(`${output}\n`)
+  process.exit(entry.state === 'failed' ? 2 : entry.state === 'not-run' ? 3 : 0)
+}
+
+try {
+  main()
+} catch (error) {
+  console.error(`level-audit: ${error.message}`)
+  process.exit(3)
+}

package/40-checker/scripts/m1-sidecar.mjs

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+/**
+ * Generate a levels.json sidecar for a format-1 market index.
+ *
+ * Tier A (index-only): every entry gets index-field validation
+ *   (exact SemVer, npm/git source pinned, engines.dsh presence).
+ *   No package is downloaded or executed; level is null.
+ * Tier B (static-only): optional pilot JSON files from
+ *   `dsh-plugin-verify --static-only` are merged in by name@version.
+ *
+ * Usage:
+ *   node scripts/m1-sidecar.mjs \
+ *     --index /tmp/dsh-catalog/index.json \
+ *     --pilot results/m1 \
+ *     --out results/m1/levels.json
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+
+const EXACT = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/
+const COMMIT = /^[0-9a-f]{40}$/
+
+function parseArgs(argv) {
+  const options = { index: null, out: null, pilot: null, indexUrl: 'https://awesome-dsh-plugin.com/index.json' }
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]
+    if (arg === '--index') options.index = argv[++i]
+    else if (arg === '--out') options.out = argv[++i]
+    else if (arg === '--pilot') options.pilot = argv[++i]
+    else if (arg === '--index-url') options.indexUrl = argv[++i]
+    else if (arg === '--help' || arg === '-h') { console.log('usage: node scripts/m1-sidecar.mjs --index <format-1.json> [--pilot <dir>] --out <levels.json>'); process.exit(0) }
+    else throw new Error(`unknown option: ${arg}`)
+  }
+  if (!options.index) throw new Error('--index is required')
+  if (!options.out) throw new Error('--out is required')
+  return options
+}
+
+function readPilots(directory) {
+  const map = new Map()
+  if (!directory || !fs.existsSync(directory)) return map
+  for (const entry of fs.readdirSync(directory)) {
+    if (!entry.endsWith('.json')) continue
+    const file = path.join(directory, entry)
+    let report
+    try { report = JSON.parse(fs.readFileSync(file, 'utf8')) } catch { continue }
+    if (report?.schema !== 'dsh-conformance/1' || !report.subject?.name || !report.subject?.version) continue
+    map.set(`${report.subject.name}@${report.subject.version}`, { file, report })
+  }
+  return map
+}
+
+function pilotLevel(report, file) {
+  const status = { pass: 'static-only', warn: 'static-only-warn', fail: 'failed', incomplete: 'inconclusive' }[report.conclusion?.status] ?? 'inconclusive'
+  return {
+    standard: 'DS-C',
+    standardVersion: report.standard?.version ?? '1.0.0',
+    profile: 'listing',
+    status,
+    coverage: report.coverage,
+    anchor: report.anchor,
+    checkedAt: new Date().toISOString().slice(0, 10),
+    expiresAt: new Date(Date.now() + 90 * 86400_000).toISOString().slice(0, 10),
+    evidenceUrl: `file://${path.resolve(file)}`,
+  }
+}
+
+function main() {
+  const options = parseArgs(process.argv.slice(2))
+  const index = JSON.parse(fs.readFileSync(options.index, 'utf8'))
+  if (index.format !== 1 || !Array.isArray(index.plugins)) throw new Error('not a format-1 index')
+  const pilots = readPilots(options.pilot)
+  const levels = {}
+  const summary = { total: 0, indexOnly: 0, staticOnly: 0, staticOnlyWarn: 0, failed: 0, inconclusive: 0, withEnginesDsh: 0, npm: 0, git: 0 }
+  for (const plugin of [...index.plugins].sort((a, b) => String(a.name).localeCompare(String(b.name)))) {
+    const versions = Array.isArray(plugin.versions) ? [...plugin.versions].sort((a, b) => String(a.version).localeCompare(String(b.version))) : []
+    for (const version of versions) {
+      summary.total += 1
+      const source = version.source ?? {}
+      const sourcePinned = source.type === 'npm' || (source.type === 'git' && COMMIT.test(source.commit ?? ''))
+      const enginesDsh = typeof version.engines?.dsh === 'string' && version.engines.dsh !== ''
+      if (enginesDsh) summary.withEnginesDsh += 1
+      if (source.type === 'npm') summary.npm += 1
+      if (source.type === 'git') summary.git += 1
+      const key = `${plugin.name}@${version.version}`
+      const pilot = pilots.get(key)
+      const base = {
+        plugin: plugin.name,
+        version: version.version,
+        status: 'index-only',
+        index: {
+          versionExact: EXACT.test(version.version ?? ''),
+          sourceType: source.type ?? null,
+          sourcePinned,
+          enginesDsh,
+          hasUpstream: plugin.upstream !== undefined,
+        },
+        reason: 'package tarball not fetched; only index fields were checked',
+        anchor: { indexUrl: options.indexUrl, parser: 'm1-sidecar/1', checkedAt: new Date().toISOString().slice(0, 10) },
+      }
+      if (pilot) {
+        const level = pilotLevel(pilot.report, pilot.file)
+        levels[key] = { ...base, status: level.status, reason: '', level }
+        if (level.status === 'static-only-warn') summary.staticOnlyWarn += 1
+        else if (level.status === 'failed') summary.failed += 1
+        else if (level.status === 'inconclusive') summary.inconclusive += 1
+        else summary.staticOnly += 1
+      } else {
+        levels[key] = base
+        summary.indexOnly += 1
+      }
+    }
+  }
+  const output = {
+    schema: 'dsh-levels/1',
+    indexUrl: options.indexUrl,
+    generatedAt: new Date().toISOString(),
+    summary,
+    levels,
+  }
+  fs.mkdirSync(path.dirname(path.resolve(options.out)), { recursive: true })
+  fs.writeFileSync(options.out, JSON.stringify(output, null, 2))
+  console.log(JSON.stringify({ out: path.resolve(options.out), summary }, null, 2))
+}
+
+try { main() } catch (error) { console.error(`m1-sidecar: ${error.message}`); process.exitCode = 3 }

package/40-checker/scripts/m2-runner.mjs

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+/**
+ * M2 runner (MVP): execute one package's L1-L3 in an isolated child process.
+ *
+ * This is NOT a security sandbox. It isolates the checker from the developer's
+ * real DSH_HOME/profile and kills the process tree on timeout; it does not
+ * restrict the child's filesystem or network. The standard's M2 contract
+ * (50 §5) still needs a container/image for untrusted packages.
+ *
+ * Usage:
+ *   node scripts/m2-runner.mjs \
+ *     --package /tmp/dsh-host/plugins/ci-diet \
+ *     --runtime <dsh-checkout>/vendor/cordis/lib/index.js \
+ *     --runtime-version 0.2.2-alpha.2 \
+ *     --out results/m2/ci-diet.json
+ */
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { spawn, spawnSync } from 'node:child_process'
+
+function parse(argv) {
+  const options = {
+    package: null, runtime: null, runtimeVersion: '0.2.2-alpha.2', cordisVersion: '4.0.6-alpha.1',
+    timeoutMs: 60_000, out: null, keep: false, json: false, modules: null, backend: 'process', image: null,
+  }
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]
+    if (arg === '--package') options.package = argv[++i]
+    else if (arg === '--runtime') options.runtime = argv[++i]
+    else if (arg === '--runtime-version') options.runtimeVersion = argv[++i]
+    else if (arg === '--cordis-version') options.cordisVersion = argv[++i]
+    else if (arg === '--timeout') options.timeoutMs = Number(argv[++i])
+    else if (arg === '--out') options.out = argv[++i]
+    else if (arg === '--keep') options.keep = true
+    else if (arg === '--modules') options.modules = argv[++i]
+    else if (arg === '--backend') options.backend = argv[++i]
+    else if (arg === '--image') options.image = argv[++i]
+    else if (arg === '--json') options.json = true
+    else if (arg === '--help' || arg === '-h') { console.log('usage: node scripts/m2-runner.mjs --package <dir> --runtime <cordis-lib> [--backend process|unshare|landlock|unshare-landlock] [--image ref@sha256:<64hex>] [--out level.json]'); process.exit(0) }
+    else throw new Error(`unknown option: ${arg}`)
+  }
+  if (!options.package) throw new Error('--package is required')
+  if (!options.runtime) throw new Error('--runtime is required')
+  if (!Number.isFinite(options.timeoutMs) || options.timeoutMs < 1000) throw new Error('--timeout must be >= 1000 ms')
+  if (!['process', 'unshare', 'landlock', 'unshare-landlock'].includes(options.backend)) throw new Error('--backend must be process, unshare, landlock, or unshare-landlock')
+  if (options.image && !/^[^@\s]+@sha256:[0-9a-f]{64}$/.test(options.image)) throw new Error('--image must be ref@sha256:<64 hex>')
+  return options
+}
+
+function killTree(child, signal = 'SIGKILL') {
+  if (!child.pid) return
+  if (process.platform === 'win32') {
+    spawnSync('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore' })
+    return
+  }
+  try { process.kill(-child.pid, signal) } catch { try { child.kill(signal) } catch { /* gone */ } }
+}
+
+function runChecker(command, args, cwd, env, timeoutMs) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, { cwd, env, detached: process.platform !== 'win32', stdio: ['ignore', 'pipe', 'pipe'] })
+    let stdout = ''
+    let stderr = ''
+    let killed = false
+    const timer = setTimeout(() => { killed = true; killTree(child) }, timeoutMs)
+    child.stdout.on('data', chunk => { stdout += chunk })
+    child.stderr.on('data', chunk => { stderr += chunk })
+    child.on('error', error => { clearTimeout(timer); resolve({ code: null, stdout, stderr: `${stderr}${error.message}`, killed }) })
+    child.on('close', code => { clearTimeout(timer); resolve({ code, stdout, stderr, killed }) })
+  })
+}
+
+function linkModules(pkg, modules) {
+  if (!modules) return 0
+  const source = path.resolve(modules)
+  if (!fs.existsSync(source)) throw new Error(`--modules not found: ${source}`)
+  const target = path.join(pkg, 'node_modules')
+  fs.mkdirSync(target, { recursive: true })
+  let linked = 0
+  for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
+    const from = path.join(source, entry.name)
+    const to = path.join(target, entry.name)
+    if (entry.isDirectory() && entry.name.startsWith('@')) {
+      fs.mkdirSync(to, { recursive: true })
+      for (const child of fs.readdirSync(from, { withFileTypes: true })) {
+        const dest = path.join(to, child.name)
+        if (fs.existsSync(dest)) continue
+        try { fs.symlinkSync(path.join(from, child.name), dest, process.platform === 'win32' ? 'junction' : 'dir'); linked += 1 } catch { /* skip */ }
+      }
+    } else if (!fs.existsSync(to)) {
+      try { fs.symlinkSync(from, to, process.platform === 'win32' ? 'junction' : 'dir'); linked += 1 } catch { /* skip */ }
+    }
+  }
+  return linked
+}
+
+function ensureLandlock() {
+  const source = path.resolve(path.dirname(new URL(import.meta.url).pathname), 'landlock-exec.c')
+  const binary = path.join(os.tmpdir(), 'dsh-landlock-exec')
+  try {
+    const sourceStat = fs.statSync(source)
+    const binaryStat = fs.statSync(binary, { throwIfNoEntry: false })
+    if (binaryStat && binaryStat.mtimeMs >= sourceStat.mtimeMs) return binary
+  } catch { /* compile below */ }
+  const result = spawnSync('cc', ['-O2', source, '-o', binary], { stdio: 'inherit' })
+  if (result.error || result.status !== 0) throw new Error('cannot build landlock-exec (need a C compiler)')
+  return binary
+}
+
+function mapStatus(report) {
+  const status = report?.conclusion?.status
+  if (status === 'pass') return 'verified'
+  if (status === 'warn') return 'verified-warn'
+  if (status === 'fail') return 'failed'
+  return 'inconclusive'
+}
+
+async function main() {
+  const options = parse(process.argv.slice(2))
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'dsh-m2-'))
+  const home = path.join(root, 'home')
+  const work = path.join(root, 'work')
+  const pkg = path.join(root, 'package')
+  fs.mkdirSync(home, { recursive: true })
+  fs.mkdirSync(work, { recursive: true })
+  fs.cpSync(path.resolve(options.package), pkg, { recursive: true, dereference: false, filter: source => !source.includes(`${path.sep}.git${path.sep}`) })
+  const linkedModules = linkModules(pkg, options.modules)
+  const reportPath = path.join(work, 'report.json')
+  const cli = path.resolve(path.dirname(new URL(import.meta.url).pathname), '..', 'bin', 'dsh-plugin-verify.mjs')
+  const args = [cli, pkg, '--format', 'json', '--treat-as-plugin', '--runtime', path.resolve(options.runtime), '--runtime-version', options.runtimeVersion, '--cordis-version', options.cordisVersion, '--out', reportPath]
+  const env = {
+    ...process.env,
+    DSH_HOME: home,
+    HOME: home,
+    USERPROFILE: home,
+    TMPDIR: path.join(root, 'tmp'),
+    TEMP: path.join(root, 'tmp'),
+    TMP: path.join(root, 'tmp'),
+  }
+  fs.mkdirSync(env.TMPDIR, { recursive: true })
+  const started = Date.now()
+  const needsLandlock = options.backend === 'landlock' || options.backend === 'unshare-landlock'
+  const needsUnshare = options.backend === 'unshare' || options.backend === 'unshare-landlock'
+  const landlock = needsLandlock ? ensureLandlock() : null
+  const command = needsUnshare ? 'unshare' : needsLandlock ? landlock : process.execPath
+  const commandArgs = []
+  if (needsUnshare) {
+    commandArgs.push('-Urn', '--fork', '--pid', '--mount-proc')
+    if (needsLandlock) commandArgs.push(landlock)
+  }
+  if (needsLandlock) commandArgs.push('--rw', home, '--rw', work, '--rw', env.TMPDIR, '--')
+  commandArgs.push(process.execPath, ...args)
+  const result = await runChecker(command, commandArgs, work, env, options.timeoutMs)
+  const elapsedMs = Date.now() - started
+  let report = null
+  try { report = JSON.parse(fs.readFileSync(reportPath, 'utf8')) } catch { /* report missing */ }
+  const imageUnverified = Boolean(options.image)
+  const status = result.killed || imageUnverified ? 'inconclusive' : mapStatus(report)
+  const level = {
+    schema: 'dsh-m2-level/1',
+    status,
+    standard: report?.standard ?? { id: 'DS-C', version: '1.0.0' },
+    subject: report?.subject ?? { name: null, version: null, path: path.resolve(options.package) },
+    anchor: report?.anchor ?? null,
+    coverage: report?.coverage ?? null,
+    conclusion: report?.conclusion ?? null,
+    m1: { coverage: report?.coverage ?? null, conclusion: report?.conclusion ?? null },
+    reason: imageUnverified ? 'image metadata is unverified; M2 cannot assert verified' : undefined,
+    sandbox: {
+      runner: 'm2-runner/1',
+      node: process.version,
+      timeoutMs: options.timeoutMs,
+      elapsedMs,
+      killed: result.killed,
+      exitCode: result.code,
+      isolatedHome: true,
+      backend: options.backend,
+      networkNamespace: needsUnshare,
+      fsWriteRestricted: needsLandlock,
+      securityBoundary: false,
+      containment: options.backend === 'unshare-landlock'
+        ? 'landlock-fs+network-namespace+process'
+        : options.backend === 'landlock'
+          ? 'landlock-fs+process'
+          : options.backend === 'unshare'
+            ? 'network-namespace+process'
+            : 'none',
+      linkedModules,
+      image: options.image ? { reference: options.image.split('@')[0], digest: `sha256:${options.image.split('@sha256:')[1]}`, verified: false, assertion: 'unverified-metadata', reason: 'OCI/Docker backend not enabled; metadata only; cannot yield verified' } : null,
+      note: needsLandlock
+        ? 'Landlock restricts writes to HOME/TMP/cwd; read is allowed everywhere. Network isolation only with unshare-landlock.'
+        : needsUnshare
+          ? 'user+network namespace + process isolation; no filesystem write restriction'
+          : 'process isolation only; no filesystem/network restriction',
+    },
+    checks: report?.checks ?? [],
+    stderr: result.stderr.slice(0, 4000),
+    ranAt: new Date().toISOString(),
+  }
+  if (!options.keep) fs.rmSync(root, { recursive: true, force: true })
+  const output = JSON.stringify(level, null, 2)
+  if (options.out) {
+    const out = path.resolve(options.out)
+    fs.mkdirSync(path.dirname(out), { recursive: true })
+    fs.writeFileSync(out, output)
+  }
+  if (options.json || !options.out) process.stdout.write(`${output}\n`)
+  const exit = status === 'verified' || status === 'verified-warn' ? 0 : status === 'failed' ? 1 : 2
+  process.exitCode = exit
+}
+
+main().catch(error => { console.error(`m2-runner: ${error.message}`); process.exitCode = 3 })