dsh-standards 1.0.3 → 1.2.0

package/40-checker/src/sandbox-env.mjs

@@ -0,0 +1,78 @@
+/**
+ * Environment policy for child processes that may load third-party plugin code.
+ *
+ * A plugin boots on first import: anything it can read from `process.env` is
+ * already exfiltratable before a single check runs. `...process.env` therefore
+ * must never be forwarded to `dsh plugin add`, a host boot, or a runtime child.
+ * The policy is an allowlist (not a denylist) so a newly named credential does
+ * not silently leak; the secret-shaped name filter stays as a second gate in
+ * case an allowlisted name is ambiguous.
+ *
+ * Callers that need isolation (temporary HOME, DSH_HOME, TMPDIR) pass those as
+ * explicit overrides. Overrides are the caller's own values, never inherited.
+ */
+
+const ALLOWED = new Set([
+  // Portable process essentials.
+  'PATH', 'HOME', 'USERPROFILE', 'TMPDIR', 'TEMP', 'TMP', 'PWD', 'SHELL',
+  'USER', 'LOGNAME', 'LANG', 'LANGUAGE', 'LC_ALL', 'LC_CTYPE', 'LC_MESSAGES',
+  'TZ', 'TERM', 'NO_COLOR', 'FORCE_COLOR', 'COLORTERM',
+  // Windows needs these to locate node/npm/tmp; they carry no credentials.
+  'SYSTEMROOT', 'SYSTEMDRIVE', 'WINDIR', 'COMSPEC', 'PATHEXT', 'OS',
+  'NUMBER_OF_PROCESSORS', 'PROCESSOR_ARCHITECTURE', 'PROCESSOR_ARCHITEW6432',
+  'APPDATA', 'LOCALAPPDATA', 'PROGRAMDATA', 'PROGRAMFILES',
+  'PROGRAMFILES(X86)', 'COMMONPROGRAMFILES', 'HOMEDRIVE', 'HOMEPATH',
+])
+
+const SECRET_NAME = /(TOKEN|SECRET|PASSWORD|PASSWD|API_?KEY|PRIVATE_?KEY|CREDENTIAL|AUTH|COOKIE|SESSION|_KEY$)/i
+
+export function isSecretEnvName(name) {
+  return SECRET_NAME.test(String(name ?? ''))
+}
+
+export function isAllowedEnvName(name) {
+  return ALLOWED.has(String(name)) && !isSecretEnvName(name)
+}
+
+/**
+ * Build the child environment: inherited allowlisted keys + caller overrides.
+ * Overrides are trusted call values (paths the caller just created), not
+ * inherited state, so they are not filtered.
+ */
+export function sanitizedEnv(overrides = {}) {
+  const env = {}
+  for (const [key, value] of Object.entries(process.env)) {
+    if (value === undefined || !isAllowedEnvName(key)) continue
+    env[key] = value
+  }
+  for (const [key, value] of Object.entries(overrides)) {
+    if (value === undefined || value === null) continue
+    env[key] = String(value)
+  }
+  return env
+}
+
+/**
+ * In-process variant for scripts that boot a plugin in this very process
+ * (bundle smoke, runtime child). It deletes everything not allowlisted, so a
+ * direct `node script.mjs` invocation gets the same policy as a spawned one.
+ * Returns the removed key names (never values) for logging.
+ */
+export function scrubProcessEnv() {
+  const removed = []
+  for (const key of Object.keys(process.env)) {
+    if (isAllowedEnvName(key)) continue
+    removed.push(key)
+    delete process.env[key]
+  }
+  return removed
+}
+
+export function envPolicy() {
+  return {
+    mode: 'allowlist',
+    allow: [...ALLOWED].sort(),
+    denyNamePattern: SECRET_NAME.source,
+    note: 'tokens/keys/secrets/credentials are dropped even if a future allowlist entry matches',
+  }
+}

package/40-checker/test/checks.test.mjs

@@ -3,7 +3,7 @@ import assert from 'node:assert/strict'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { runManifestChecks } from '../src/manifest.mjs'
-import { checkCapabilities, checkCredentials, checkLabels } from '../src/declarations.mjs'
+import { checkCapabilities, checkCredentials, checkImportTimeAdvisory, checkLabels } from '../src/declarations.mjs'
 import { readSources } from '../src/util.mjs'
 import { buildReport } from '../src/report.mjs'
 import { parseInstallSpec } from '../src/install-spec.mjs'
@@ -21,6 +21,14 @@ test('good fixture passes manifest and version checks', () => {
   assert.equal(result.checks[2].result, 'NA')
 })
 
+test('patch-only bundle reports C-1.2 as NA, not WARN', () => {
+  const result = runManifestChecks(path.join(here, '..', 'fixtures', 'bundle-patch-only'))
+  const dsc01 = result.checks.find((check) => check.id === 'DSC-01')
+  const entry = dsc01.details.find((detail) => detail.item === 'C-1.2')
+  assert.equal(entry.result, 'NA')
+  assert.match(entry.reason, /patch-only bundle/)
+})
+
 test('bad fixture fails version and warns licence', () => {
   const result = runManifestChecks(bad)
   assert.equal(result.checks[0].result, 'WARN')
@@ -170,3 +178,237 @@ test('entry: static claim recognizes without runtime', () => {
   assert.equal(report.conclusion.level, 'DSH-ENTRY recognized')
   assert.equal(report.conclusion.exitCode, 0)
 })
+
+test('DSC-10.4: flags a module-scope fs mutation in the entry module', () => {
+  const dir = path.join(here, '..', 'fixtures', 'import-side-effect')
+  const result = runManifestChecks(dir)
+  const check = checkImportTimeAdvisory(readSources(dir), result.entry?.relative)
+  assert.equal(check.result, 'WARN', check.reason)
+  assert.ok(check.details.some((detail) => /top-level fs mutation/.test(detail.reason)), JSON.stringify(check.details))
+})
+
+test('DSC-10.4: ignores a module-scope fs mutation outside the entry module', () => {
+  const dir = path.join(here, '..', 'fixtures', 'import-side-effect-nonentry')
+  const result = runManifestChecks(dir)
+  const check = checkImportTimeAdvisory(readSources(dir), result.entry?.relative)
+  assert.equal(check.result, 'PASS', check.reason)
+})
+
+test('DSC-10.4: a clean entry module still passes', () => {
+  const result = runManifestChecks(good)
+  const check = checkImportTimeAdvisory(readSources(good), result.entry?.relative)
+  assert.equal(check.result, 'PASS', check.reason)
+})
+
+test('DSC-10.1/2: the existing patterns are entry-scoped too', () => {
+  const dir = path.join(here, '..', 'fixtures', 'import-side-effect-nonentry')
+  const result = runManifestChecks(dir)
+  const check = checkImportTimeAdvisory(readSources(dir), result.entry?.relative)
+  assert.equal(check.result, 'PASS', check.reason)
+})
+
+test('DSC-10.4: a read-only openSync is not a write mutation', () => {
+  const dir = path.join(here, '..', 'fixtures', 'import-open-readonly')
+  const result = runManifestChecks(dir)
+  const check = checkImportTimeAdvisory(readSources(dir), result.entry?.relative)
+  assert.equal(check.result, 'PASS', check.reason)
+})
+
+test('DSC-10: no source files is NA, not WARN', () => {
+  const dir = path.join(here, '..', 'fixtures', 'no-source')
+  const check = checkImportTimeAdvisory(readSources(dir), 'index.mjs')
+  assert.equal(check.result, 'NA', check.reason)
+  assert.match(check.reason, /no source/)
+})
+
+test('DSC-10.2: flags an immediate module-scope void main()', () => {
+  const dir = path.join(here, '..', 'fixtures', 'import-void-main')
+  const result = runManifestChecks(dir)
+  const check = checkImportTimeAdvisory(readSources(dir), result.entry?.relative)
+  assert.equal(check.result, 'WARN', check.reason)
+  assert.ok(check.details.some((detail) => /immediate main/.test(detail.reason)), JSON.stringify(check.details))
+})
+
+test('DSC-10.1/2: AST catches top-level await, timer, process hooks and globals', () => {
+  const text = [
+    "await Promise.resolve()",
+    'for await (const item of []) {}',
+    "setInterval(() => {}, 1000)",
+    "process.on('SIGINT', () => {})",
+    "process.env.DSH_FIXTURE = '1'",
+    'globalThis.__dshFixture = true',
+  ].join('\n')
+  const check = checkImportTimeAdvisory([{ relative: 'index.mjs', text }], 'index.mjs')
+  assert.equal(check.result, 'WARN', check.reason)
+  assert.equal(check.details.filter((detail) => /top-level await/.test(detail.reason)).length, 2)
+  for (const pattern of ['top-level setInterval', 'top-level process.on', 'top-level process.env assignment', 'top-level globalThis assignment']) {
+    assert.ok(check.details.some((detail) => detail.reason.includes(pattern)), `${pattern}: ${JSON.stringify(check.details)}`)
+  }
+})
+
+test('DSC-10.4: member fs writes and module-scope control flow count', () => {
+  const text = [
+    "import * as fs from 'node:fs'",
+    'if (process.env.DSH_FIXTURE) {',
+    "  fs.writeFileSync('/tmp/dsh-fixture-member-write.txt', 'x')",
+    '}',
+  ].join('\n')
+  const check = checkImportTimeAdvisory([{ relative: 'index.mjs', text }], 'index.mjs')
+  assert.equal(check.result, 'WARN', check.reason)
+  assert.ok(check.details.some((detail) => /top-level fs mutation/.test(detail.reason)), JSON.stringify(check.details))
+})
+
+test('DSC-10: function, arrow and class-method bodies are not module-scope side effects', () => {
+  const text = [
+    "function a() { writeFileSync('/tmp/a', 'x') }",
+    "const b = () => spawnSync('cmd')",
+    "class C { m() { process.on('x', () => {}) } }",
+    'const d = { n() { setInterval(() => {}, 1) } }',
+  ].join('\n')
+  const check = checkImportTimeAdvisory([{ relative: 'index.mjs', text }], 'index.mjs')
+  assert.equal(check.result, 'PASS', check.reason)
+})
+
+test('DSC-12 C-12.4: ignores comment-only literals', () => {
+  const dir = path.join(here, '..', 'fixtures', 'c12-comment')
+  const check = checkCredentials({}, readSources(dir))
+  assert.equal(check.result, 'PASS', check.reason)
+})
+
+test('DSC-12 C-12.4: ignores equality comparisons', () => {
+  const dir = path.join(here, '..', 'fixtures', 'c12-compare')
+  const check = checkCredentials({}, readSources(dir))
+  assert.equal(check.result, 'PASS', check.reason)
+})
+
+test('DSC-12 C-12.4: still flags an actual set() grant', () => {
+  const dir = path.join(here, '..', 'fixtures', 'c12-grant')
+  const check = checkCredentials({}, readSources(dir))
+  assert.equal(check.result, 'WARN', check.reason)
+  assert.ok(check.details.some((detail) => detail.item === 'C-12.4'), JSON.stringify(check.details))
+})
+
+test('DSC-12 C-12.4: console-only documentation string is not a grant', () => {
+  const dir = path.join(here, '..', 'fixtures', 'c12-string')
+  const check = checkCredentials({}, readSources(dir))
+  assert.equal(check.result, 'PASS', check.reason)
+  assert.ok(!check.details.some((detail) => detail.item === 'C-12.4'), JSON.stringify(check.details))
+})
+
+test('DSC-12 C-12.4: console/desc documentation strings are not grants', () => {
+  const dir = path.join(here, '..', 'fixtures', 'c12-doc-string')
+  const check = checkCredentials({}, readSources(dir))
+  assert.equal(check.result, 'PASS', check.reason)
+  assert.ok(!check.details.some((detail) => detail.item === 'C-12.4'), JSON.stringify(check.details))
+})
+
+test('DSC-11 C-11.4: console/desc documentation strings are not danger literals', () => {
+  const dir = path.join(here, '..', 'fixtures', 'c12-doc-string')
+  const check = checkCapabilities({}, readSources(dir))
+  assert.ok(!check.details.some((detail) => detail.item === 'C-11.4'), JSON.stringify(check.details))
+})
+
+test('DSC-11 C-11.4: --add-dir alone is a C-12.4 concern, not C-11.4', () => {
+  const sources = [{ relative: 'index.mjs', text: "spawn('dsh', ['--add-dir', './docs'])\n" }]
+  const check = checkCapabilities({}, sources)
+  assert.ok(!check.details.some((detail) => detail.item === 'C-11.4'), JSON.stringify(check.details))
+})
+
+test('DSC-12 C-12.4: spawn args with --add-dir are a real command string', () => {
+  const dir = path.join(here, '..', 'fixtures', 'c12-command-arg')
+  const check = checkCredentials({}, readSources(dir))
+  assert.equal(check.result, 'WARN', check.reason)
+  assert.ok(check.details.some((detail) => detail.item === 'C-12.4'), JSON.stringify(check.details))
+})
+
+test('DSC-12 C-12.4: set/resolve/mode/switch contexts are real grants', () => {
+  const text = [
+    "svc.set(session, 'danger-full-access')",
+    "svc.resolve('danger-full-access')",
+    "const policy = { sandboxPolicy: { mode: 'danger-full-access' } }",
+    "switch (mode) { case 'danger-full-access': break }",
+  ].join('\n')
+  const check = checkCredentials({}, [{ relative: 'index.mjs', text }])
+  assert.equal(check.result, 'WARN', check.reason)
+  const detail = check.details.find((item) => item.item === 'C-12.4')
+  assert.ok(detail, JSON.stringify(check.details))
+  assert.match(detail.reason, /\b4\b/)
+})
+
+test('DSC-12 C-12.4: nested command properties outrank documentation keys', () => {
+  const check = checkCredentials({}, [{ relative: 'index.mjs', text: "const policy = { sandboxPolicy: { description: 'danger-full-access' } }\n" }])
+  assert.equal(check.result, 'WARN', check.reason)
+})
+
+test('DSC-12 C-12.4: an unknown context stays a conservative warning', () => {
+  const check = checkCredentials({}, [{ relative: 'index.mjs', text: "const mode = 'danger-full-access'\n" }])
+  assert.equal(check.result, 'WARN', check.reason)
+})
+
+test('DSC-12 C-12.4: an unparsable source is not-run, not PASS', () => {
+  const check = checkCredentials({}, [{ relative: 'index.mjs', text: 'const broken = {\n' }])
+  assert.equal(check.result, 'ERROR', check.reason)
+  assert.equal(check.coverage, 'not-run')
+  assert.ok(check.details.some((detail) => detail.item === 'C-12.4' && /not-run/.test(detail.reason)), JSON.stringify(check.details))
+})
+
+test('DSC-10.3: follows a local relative import and flags its top-level fs mutation', () => {
+  const dir = path.join(here, '..', 'fixtures', 'import-local-side-effect')
+  const result = runManifestChecks(dir)
+  const check = checkImportTimeAdvisory(readSources(dir), result.entry?.relative)
+  assert.equal(check.result, 'WARN', check.reason)
+  assert.ok(check.details.some((detail) => /top-level fs mutation/.test(detail.reason) && /side-effectful\.mjs/.test(detail.reason)), JSON.stringify(check.details))
+})
+
+test('DSC-10.3: a package-only entry is PASS with a C-10.3 not-run coverage note', () => {
+  const dir = path.join(here, '..', 'fixtures', 'import-package-only')
+  const result = runManifestChecks(dir)
+  const check = checkImportTimeAdvisory(readSources(dir), result.entry?.relative)
+  assert.equal(check.result, 'PASS', check.reason)
+  const note = check.details.find((detail) => detail.item === 'C-10.3')
+  assert.ok(note, JSON.stringify(check.details))
+  assert.match(note.reason, /not-run/)
+  assert.match(note.reason, /node:path/)
+})
+
+test('DSC-10.3: an unresolved local import records not-run without becoming a WARN', () => {
+  const sources = [{ relative: 'index.mjs', text: "import './missing-module.mjs'\n" }]
+  const check = checkImportTimeAdvisory(sources, 'index.mjs')
+  assert.equal(check.result, 'PASS', check.reason)
+  assert.ok(check.details.some((detail) => detail.item === 'C-10.3' && /not-run/.test(detail.reason)), JSON.stringify(check.details))
+})
+
+test('DSC-10.3: a require inside a function is not an import-time edge', () => {
+  const sources = [
+    { relative: 'index.mjs', text: "function load() { return require('./side-effectful.mjs') }\n" },
+    { relative: 'side-effectful.mjs', text: "writeFileSync('/tmp/x', 'x')\n" },
+  ]
+  const check = checkImportTimeAdvisory(sources, 'index.mjs')
+  assert.equal(check.result, 'PASS', check.reason)
+  assert.ok(!check.details.some((detail) => /side-effectful/.test(detail.reason)), JSON.stringify(check.details))
+})
+
+test('DSC-10: an unparsable entry is ERROR/not-run, not PASS', () => {
+  const dir = path.join(here, '..', 'fixtures', 'import-parse-error')
+  const result = runManifestChecks(dir)
+  const check = checkImportTimeAdvisory(readSources(dir), result.entry?.relative)
+  assert.equal(check.result, 'ERROR', check.reason)
+  assert.equal(check.coverage, 'not-run')
+})
+
+test('DSC-10/DSC-12: a broken .d.ts is skipped, not ERROR', () => {
+  const dir = path.join(here, '..', 'fixtures', 'declaration-file')
+  const result = runManifestChecks(dir)
+  const c10 = checkImportTimeAdvisory(readSources(dir), result.entry?.relative)
+  const c12 = checkCredentials({}, readSources(dir))
+  assert.equal(c10.result, 'PASS', c10.reason)
+  assert.equal(c12.result, 'PASS', c12.reason)
+})
+
+test('DSC-12 C-12.4: one unparsable non-entry file is partial, not ERROR', () => {
+  const dir = path.join(here, '..', 'fixtures', 'parse-error-nonentry')
+  const check = checkCredentials({}, readSources(dir))
+  assert.notEqual(check.result, 'ERROR', check.reason)
+  assert.equal(check.coverage, 'partial')
+  assert.ok(check.details.some((detail) => detail.item === 'C-12.4' && /not-run/.test(detail.reason)), JSON.stringify(check.details))
+})

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

@@ -0,0 +1,295 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import {
+  FLOW_IDS, evidenceHash, finalizeEvidence, journeyAggregate, treeSha256, validateFlowEvidence,
+} from '../src/flow-evidence.mjs'
+import { isSecretEnvName, sanitizedEnv } from '../src/sandbox-env.mjs'
+
+const HERE = path.dirname(fileURLToPath(import.meta.url))
+const STD = path.resolve(HERE, '..', '..')
+const AUDIT = path.join(STD, '40-checker', 'scripts', 'level-audit.mjs')
+const COLLECT = path.join(STD, '40-checker', 'bin', 'dsh-flow-collect.mjs')
+const GOOD = path.join(STD, '40-checker', 'fixtures', 'good')
+const TEMPLATE = path.join(STD, 'examples', 'plugin-template')
+const ISO = '2026-11-06T12:00:00.000Z'
+const HASH = `sha256:${'a'.repeat(64)}`
+
+function check(id, overrides = {}) {
+  return {
+    id,
+    kind: 'observed',
+    command: ['node', '-e', 'process.exit(0)'],
+    exitCode: 0,
+    startedAt: ISO,
+    endedAt: ISO,
+    stdout: { path: `logs/${id}.out.log`, sha256: HASH },
+    assertions: [{ claim: `${id} observed`, observed: true }],
+    ...overrides,
+  }
+}
+
+function evidenceDocument({ journeys = {}, subject, ...rest } = {}) {
+  const base = {
+    schema: 'dsh-flow-evidence/2',
+    generatedAt: ISO,
+    producer: { command: ['node', '40-checker/bin/dsh-flow-collect.mjs'], at: ISO, kind: 'local' },
+    subject: subject ?? {
+      name: '@dsh-fixtures/good-plugin',
+      version: '1.0.0',
+      integrity: null,
+      tarballSha256: HASH,
+      commit: null,
+      treeSha256: HASH,
+    },
+    host: { dsh: '0.2.1-rc.5', node: 'v24.22.1', platform: 'linux-x64' },
+    journeys: Object.fromEntries(FLOW_IDS.map((id) => [id, { status: 'pass', checks: [check(`${id}.run`)] }])),
+    claims: { claimLevel: 'self-attested', notClaimed: ['certification'] },
+    conclusion: 'flow-pass',
+    ...rest,
+  }
+  for (const [id, override] of Object.entries(journeys)) base.journeys[id] = override
+  return finalizeEvidence(base)
+}
+
+function writeTemp(name, value) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'dsh-flow-evidence-test-'))
+  const file = path.join(dir, name)
+  fs.writeFileSync(file, typeof value === 'string' ? value : `${JSON.stringify(value, null, 2)}\n`)
+  return { dir, file, cleanup: () => fs.rmSync(dir, { recursive: true, force: true }) }
+}
+
+function runAudit(flowFile) {
+  const run = spawnSync(process.execPath, [AUDIT, GOOD, '--format', 'json', '--flow-evidence', flowFile], {
+    encoding: 'utf8', timeout: 60_000,
+  })
+  assert.equal(run.status, 0, run.stderr)
+  return JSON.parse(run.stdout)
+}
+
+test('sandbox-env: inherited secrets are dropped and only allowlisted names survive', () => {
+  process.env.DSH_TEST_TOKEN = 'do-not-leak'
+  process.env.DSH_TEST_API_KEY = 'do-not-leak'
+  try {
+    const env = sanitizedEnv()
+    assert.equal(env.DSH_TEST_TOKEN, undefined)
+    assert.equal(env.DSH_TEST_API_KEY, undefined)
+    assert.equal(env.DSH_HOME, undefined)
+    assert.equal(env.PATH, process.env.PATH)
+    assert.equal(isSecretEnvName('GH_TOKEN'), true)
+    assert.equal(isSecretEnvName('DEEPSEEK_API_KEY'), true)
+    assert.equal(isSecretEnvName('PATH'), false)
+    assert.equal(sanitizedEnv({ DSH_HOME: '/tmp/isolated' }).DSH_HOME, '/tmp/isolated')
+  } finally {
+    delete process.env.DSH_TEST_TOKEN
+    delete process.env.DSH_TEST_API_KEY
+  }
+})
+
+test('flow-evidence: a well-formed v2 document validates and hashes consistently', () => {
+  const doc = evidenceDocument()
+  const verdict = validateFlowEvidence(doc)
+  assert.equal(verdict.kind, 'v2')
+  assert.equal(verdict.valid, true, verdict.errors.join('; '))
+  assert.equal(verdict.declaredHash, evidenceHash(doc))
+  assert.equal(verdict.journeys.J1.derived, 'pass')
+})
+
+test('level-audit: v1 journey/runtime schemas are deprecated and never a pass', () => {
+  const docs = [
+    { schema: 'dsh-flow-journey/1', package: '@dsh-fixtures/good-plugin', checks: [] },
+    { schema: 'dsh-flow-runtime/1', environment: {}, checks: [] },
+  ]
+  for (const doc of docs) {
+    const temp = writeTemp('v1.json', doc)
+    try {
+      const result = runAudit(temp.file)
+      assert.equal(result.levels.flow.state, 'deprecated')
+      assert.equal(result.levels.flow.deprecated, true)
+      assert.equal(result.levels.flow.passed, 0)
+      assert.notEqual(result.levels.flow.state, 'runtime')
+    } finally {
+      temp.cleanup()
+    }
+  }
+})
+
+test('level-audit: bare {Jx:{status:pass}} rows are deprecated and never a pass', () => {
+  const temp = writeTemp('bare.json', Object.fromEntries(FLOW_IDS.map(id => [id, { status: 'pass' }])))
+  try {
+    const result = runAudit(temp.file)
+    assert.equal(result.levels.flow.state, 'deprecated')
+    assert.equal(result.levels.flow.passed, 0)
+    assert.notEqual(result.levels.flow.state, 'runtime')
+  } finally {
+    temp.cleanup()
+  }
+})
+
+test('level-audit: v2 with all eight journeys passing is runtime', () => {
+  const temp = writeTemp('v2-pass.json', evidenceDocument())
+  try {
+    const result = runAudit(temp.file)
+    assert.equal(result.levels.flow.state, 'runtime')
+    assert.equal(result.levels.flow.passed, 8)
+    assert.equal(result.levels.flow.evidenceHash.ok, true)
+  } finally {
+    temp.cleanup()
+  }
+})
+
+test('level-audit: a forged v2 pass with a non-zero exitCode is not a pass', () => {
+  // Declared pass on every journey, but J4 carries exitCode 1: the aggregate
+  // contradicts the declaration, so the document must fail validation.
+  const doc = evidenceDocument({
+    journeys: { J4: { status: 'pass', checks: [check('J4.run', { exitCode: 1 })] } },
+  })
+  const temp = writeTemp('forged.json', doc)
+  try {
+    const result = runAudit(temp.file)
+    assert.notEqual(result.levels.flow.state, 'runtime')
+    assert.equal(result.levels.flow.passed, 0)
+    assert.equal(result.levels.flow.invalid, true)
+    assert.match(result.levels.flow.reason, /aggregate|exitCode|declares pass/i)
+  } finally {
+    temp.cleanup()
+  }
+})
+
+test('level-audit: an honest v2 with one failed journey is failed, not runtime', () => {
+  const doc = evidenceDocument({
+    journeys: { J4: { status: 'fail', checks: [check('J4.run', { exitCode: 1 })] } },
+    conclusion: 'flow-fail',
+  })
+  const temp = writeTemp('failed.json', doc)
+  try {
+    const result = runAudit(temp.file)
+    assert.equal(result.levels.flow.state, 'failed')
+    assert.equal(result.levels.flow.passed, 7)
+    assert.equal(result.levels.flow.journeys.J4.status, 'fail')
+  } finally {
+    temp.cleanup()
+  }
+})
+
+test('level-audit: a v2 journey without checks does not count as a pass', () => {
+  const doc = evidenceDocument({ journeys: { J5: { status: 'not-run', checks: [] } } })
+  const temp = writeTemp('empty.json', doc)
+  try {
+    const result = runAudit(temp.file)
+    assert.notEqual(result.levels.flow.state, 'runtime')
+    assert.equal(result.levels.flow.passed, 7)
+  } finally {
+    temp.cleanup()
+  }
+})
+
+test('level-audit: a tampered evidence hash is invalid, not runtime', () => {
+  const doc = evidenceDocument()
+  doc.chain.evidenceHash = HASH
+  const temp = writeTemp('tampered.json', doc)
+  try {
+    const result = runAudit(temp.file)
+    assert.equal(result.levels.flow.state, 'invalid')
+    assert.equal(result.levels.flow.passed, 0)
+    assert.match(result.levels.flow.reason, /evidenceHash/)
+  } finally {
+    temp.cleanup()
+  }
+})
+
+test('level-audit: a declared blocked journey is blocked, not failed', () => {
+  const doc = evidenceDocument({
+    journeys: { J6: { status: 'blocked', reason: 'no --previous package supplied', checks: [check('J6.upgrade', { exitCode: 1 })] } },
+    conclusion: 'flow-blocked',
+  })
+  const temp = writeTemp('blocked.json', doc)
+  try {
+    const result = runAudit(temp.file)
+    assert.equal(result.levels.flow.state, 'blocked')
+    assert.equal(result.levels.flow.passed, 7)
+  } finally {
+    temp.cleanup()
+  }
+})
+
+test('flow-collect: static output is v2, validates, and the audit can read it', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'dsh-flow-collect-test-'))
+  try {
+    const copy = path.join(dir, 'plugin')
+    fs.cpSync(TEMPLATE, copy, { recursive: true })
+    const out = path.join(dir, 'flow.json')
+    const run = spawnSync(process.execPath, [COLLECT, '--package', copy, '--static', '--out', out], {
+      encoding: 'utf8', timeout: 120_000,
+    })
+    assert.equal(run.status, 0, `${run.stderr}\n${run.stdout}`)
+    const doc = JSON.parse(fs.readFileSync(out, 'utf8'))
+    assert.equal(doc.schema, 'dsh-flow-evidence/2')
+    const verdict = validateFlowEvidence(doc)
+    assert.equal(verdict.valid, true, verdict.errors.join('; '))
+    assert.deepEqual(Object.keys(doc.journeys), FLOW_IDS)
+    assert.equal(doc.subject.treeStable, true)
+    assert.equal(doc.subject.treeSha256, treeSha256(TEMPLATE).hash)
+    assert.equal(doc.chain.evidenceHash, evidenceHash(doc))
+    assert.equal(journeyAggregate(doc.journeys.J1.checks), 'static')
+
+    // The audit consumes the collector output without upgrading it to runtime.
+    const audit = spawnSync(process.execPath, [AUDIT, copy, '--format', 'json', '--flow-evidence', out], {
+      encoding: 'utf8', timeout: 60_000,
+    })
+    assert.equal(audit.status, 0, audit.stderr)
+    const result = JSON.parse(audit.stdout)
+    assert.equal(result.levels.flow.schema, 'dsh-flow-evidence/2')
+    assert.notEqual(result.levels.flow.state, 'runtime')
+    assert.notEqual(result.levels.flow.state, 'invalid')
+    assert.notEqual(result.levels.flow.state, 'deprecated')
+    assert.equal(result.levels.flow.passed, 0)
+    assert.equal(result.levels.flow.evidenceHash.ok, true)
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true })
+  }
+})
+
+test('flow-collect: a failed journey exits 1 and prints the five-element hint', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'dsh-flow-collect-fail-'))
+  try {
+    const plugin = path.join(dir, 'plugin')
+    fs.mkdirSync(plugin)
+    fs.writeFileSync(path.join(plugin, 'package.json'), `${JSON.stringify({
+      name: 'dsh-flow-bad-fixture', version: '1.0.0', type: 'module', main: './index.mjs',
+      files: ['index.mjs'], dependencies: { 'workspace-only': 'workspace:*' },
+    }, null, 2)}\n`)
+    fs.writeFileSync(path.join(plugin, 'index.mjs'), 'export function apply() {}\n')
+    const out = path.join(dir, 'flow.json')
+    const run = spawnSync(process.execPath, [COLLECT, '--package', plugin, '--static', '--out', out], {
+      encoding: 'utf8', timeout: 120_000,
+    })
+    assert.equal(run.status, 1, `${run.stderr}\n${run.stdout}`)
+    for (const marker of ['FAIL J1.install.preflight', '1) 子检查:', '2) 命令:', '3) exitCode:', '4) stderr(末20行):', '5) 日志:', '条款锚: 32#R1']) {
+      assert.ok(run.stdout.includes(marker), `missing hint marker ${marker}\n${run.stdout}`)
+    }
+    const doc = JSON.parse(fs.readFileSync(out, 'utf8'))
+    assert.equal(doc.journeys.J1.status, 'fail')
+    assert.equal(doc.conclusion, 'flow-fail')
+    assert.equal(validateFlowEvidence(doc).valid, true)
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true })
+  }
+})
+
+test('flow-evidence: the published schema declares the validator contract', () => {
+  const schema = JSON.parse(fs.readFileSync(path.join(STD, 'spec', 'flow-evidence.schema.json'), 'utf8'))
+  assert.equal(schema.properties.schema.const, 'dsh-flow-evidence/2')
+  for (const key of ['schema', 'generatedAt', 'producer', 'subject', 'host', 'journeys', 'claims', 'chain']) {
+    assert.ok(schema.required.includes(key), `schema.required is missing ${key}`)
+  }
+  for (const id of FLOW_IDS) assert.ok(schema.properties.journeys.required.includes(id), `journeys.required is missing ${id}`)
+  for (const key of ['id', 'command', 'exitCode', 'startedAt', 'endedAt', 'stdout', 'assertions']) {
+    assert.ok(schema.$defs.check.required.includes(key), `check.required is missing ${key}`)
+  }
+  assert.ok(schema.$defs.journey.properties.checks)
+})