dsh-standards 1.1.2 → 1.2.0

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

@@ -0,0 +1,300 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import remediationSpec from '../../spec/remediation.json' with { type: 'json' }
+import packageJson from '../../package.json' with { type: 'json' }
+import { DOCS_BASE, joinAdvice } from '../src/remediation.mjs'
+import { buildReport } from '../src/report.mjs'
+import { runManifestChecks } from '../src/manifest.mjs'
+import { checkCapabilities, checkCredentials, checkImportTimeAdvisory, checkLabels } from '../src/declarations.mjs'
+import { readSources } from '../src/util.mjs'
+
+const here = path.dirname(fileURLToPath(import.meta.url))
+const srcDir = path.join(here, '..', 'src')
+const fixturesDir = path.join(here, '..', 'fixtures')
+const guideDocs = process.env.DSH_GUIDE_DOCS
+  ? path.resolve(process.env.DSH_GUIDE_DOCS)
+  : path.resolve(here, '..', '..', '..', 'dsh-plugin-guide', 'docs')
+const RULES = remediationSpec
+
+function slugify(text) {
+  return String(text)
+    .trim()
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}\s_-]/gu, '')
+    .replace(/\s+/g, '-')
+}
+
+function headingSlugs(text) {
+  const slugs = new Set()
+  let fence = null
+  for (const line of text.split(/\r?\n/)) {
+    const fenceMatch = /^\s*(```+|~~~+)/.exec(line)
+    if (fenceMatch) {
+      if (fence === null) fence = fenceMatch[1][0]
+      else if (fence === fenceMatch[1][0]) fence = null
+      continue
+    }
+    if (fence !== null) continue
+    // Explicit HTML anchors are valid targets too (older docs predate heading-only slugs).
+    const explicit = /<a\s+id="([^"]+)"/.exec(line)
+    if (explicit) slugs.add(explicit[1])
+    const match = /^(#{1,6})\s+(.+?)\s*#*\s*$/.exec(line)
+    if (match) slugs.add(slugify(match[2]))
+  }
+  return slugs
+}
+
+/** The key set the checker can emit: C-x[.y] literals, clause values, G0-G4. */
+function checkerUniverse() {
+  const keys = new Set()
+  for (const file of fs.readdirSync(srcDir).filter(name => name.endsWith('.mjs'))) {
+    const text = fs.readFileSync(path.join(srcDir, file), 'utf8')
+    for (const match of text.matchAll(/'((?:C-\d+)(?:\.\d+)*)'/g)) keys.add(match[1])
+    for (const match of text.matchAll(/item:\s*'(G[0-4])'/g)) keys.add(match[1])
+  }
+  for (const gate of ['G0', 'G1', 'G2', 'G3', 'G4']) keys.add(gate)
+  return keys
+}
+
+function runtimeNotRun() {
+  const meta = {
+    'DSC-04': ['C-4', 'L1'], 'DSC-05': ['C-5', 'L1'], 'DSC-06': ['C-6', 'L1+L2'],
+    'DSC-07': ['C-7', 'L2'], 'DSC-08': ['C-8', 'L3'], 'DSC-09': ['C-9', 'L1'],
+  }
+  return Object.entries(meta).map(([id, [clause, layer]]) => ({
+    id, clause, layer, method: 'M', advisory: false,
+    result: 'ERROR', coverage: 'not-run', reason: 'test: runtime not run', details: [], evidence: [],
+  }))
+}
+
+function staticReportFor(dir) {
+  const result = runManifestChecks(dir)
+  const sources = readSources(dir)
+  const declaration = result.manifest
+    ? [
+        checkCapabilities(result.manifest, sources, result.patch),
+        checkCredentials(result.manifest, sources),
+        checkLabels(result.manifest, sources),
+      ].map(item => (item.result === 'WARN' && ['DSC-11', 'DSC-13'].includes(item.id) ? { ...item, advisory: true } : item))
+    : [
+        { id: 'DSC-11', clause: 'C-11', layer: 'L0', method: 'M', advisory: false, result: 'ERROR', coverage: 'not-run', reason: 'manifest unavailable', details: [], evidence: [] },
+        { id: 'DSC-12', clause: 'C-12', layer: 'L0', method: 'M', advisory: false, result: 'ERROR', coverage: 'not-run', reason: 'manifest unavailable', details: [], evidence: [] },
+        { id: 'DSC-13', clause: 'C-13', layer: 'L0', method: 'M', advisory: false, result: 'ERROR', coverage: 'not-run', reason: 'manifest unavailable', details: [], evidence: [] },
+      ]
+  const checks = [
+    ...result.checks,
+    ...runtimeNotRun(),
+    { id: 'DSC-14', clause: 'C-14', layer: 'L1', method: 'M', advisory: false, result: 'ERROR', coverage: 'not-run', reason: 'test: runtime not run', details: [], evidence: [] },
+    checkImportTimeAdvisory(sources, result.entry?.relative),
+    ...declaration,
+  ]
+  if (result.g4?.result === 'FAIL') {
+    const dsc01 = checks.find(item => item.id === 'DSC-01')
+    if (dsc01 && dsc01.result !== 'FAIL') {
+      dsc01.result = 'FAIL'
+      dsc01.reason = dsc01.reason ? `${dsc01.reason}; ${result.g4.reason}` : result.g4.reason
+      dsc01.details = [...(dsc01.details ?? []), { item: 'G4', result: 'FAIL', reason: result.g4.reason }]
+    }
+  }
+  return buildReport({
+    subject: {
+      mode: 'package', profile: 'package', kind: result.kind, kindInferred: true,
+      name: result.manifest?.name ?? null, version: result.manifest?.version ?? null, path: dir,
+    },
+    anchor: { repo: 'test', commit: '0'.repeat(40), scanner: 'test', dsh: '0.2.2-alpha.2', cordis: '4.0.6-alpha.1', runtime: null },
+    checks,
+    g4: result.g4,
+    scope: 'ds-c',
+    profile: 'package',
+    kind: result.kind,
+  })
+}
+
+test('remediation table covers every checker key exactly', () => {
+  const universe = checkerUniverse()
+  const keys = new Set(Object.keys(RULES))
+  const missing = [...universe].filter(key => !keys.has(key)).sort()
+  const extra = [...keys].filter(key => !universe.has(key)).sort()
+  assert.deepEqual(missing, [], `missing remediation rules: ${missing.join(', ')}`)
+  assert.deepEqual(extra, [], `stale remediation rules: ${extra.join(', ')}`)
+  assert.ok(universe.size > 0)
+})
+
+test('remediation rules have the required shape', () => {
+  assert.equal(DOCS_BASE, 'https://github.com/PerryLink/dsh-plugin-guide/blob/v0.4.4/')
+  assert.equal(packageJson.version, '1.2.0')
+  assert.ok(Object.keys(RULES).length > 0)
+  for (const [key, rule] of Object.entries(RULES)) {
+    assert.match(key, /^(?:C-\d+(?:\.\d+)*|G[0-4])$/)
+    for (const field of ['title', 'why', 'fix']) {
+      assert.equal(typeof rule[field], 'string', `${key}.${field}`)
+      assert.ok(rule[field].trim().length > 0, `${key}.${field} is empty`)
+    }
+    assert.match(rule.docs, /^docs\/[a-z]+\.md#[a-z0-9-]+$/, `${key}.docs`)
+    assert.ok(['fail', 'warn', 'advisory'].includes(rule.severityHint), `${key}.severityHint`)
+  }
+})
+
+test('advice on every fixture has a rule (no ruleMissing)', () => {
+  const dirs = fs.readdirSync(fixturesDir, { withFileTypes: true })
+    .filter(entry => entry.isDirectory())
+    .map(entry => path.join(fixturesDir, entry.name))
+    .filter(dir => fs.existsSync(path.join(dir, 'package.json')))
+  assert.ok(dirs.length >= 20, `expected fixture packages, got ${dirs.length}`)
+  let total = 0
+  for (const dir of dirs) {
+    const report = staticReportFor(dir)
+    assert.ok(Array.isArray(report.advice), `${path.basename(dir)}: advice is not an array`)
+    const missing = report.advice.filter(item => item.ruleMissing)
+    assert.deepEqual(missing.map(item => `${item.source}:${item.key}`), [], `${path.basename(dir)}: ruleMissing`)
+    for (const item of report.advice) {
+      assert.ok(item.docsUrl, `${path.basename(dir)}: ${item.key} has no docsUrl`)
+      assert.equal(item.docsUrl, `${DOCS_BASE}${RULES[item.key].docs}`, `${path.basename(dir)}: ${item.key} docsUrl`)
+      assert.equal(item.version, packageJson.version)
+      assert.ok(['FAIL', 'WARN'].includes(item.severity))
+    }
+    total += report.advice.length
+  }
+  assert.ok(total > 0, 'fixtures produced no advice; the test would be vacuous')
+})
+
+test('runtime FAIL without details falls back to check.clause', () => {
+  const checks = [
+    {
+      id: 'DSC-04', clause: 'C-4', layer: 'L1', result: 'FAIL', coverage: 'full',
+      reason: 'load failed: boom', details: [], evidence: ['index.mjs:1'], method: 'M', advisory: false,
+    },
+    {
+      id: 'DSC-14', clause: 'C-14', layer: 'L1', result: 'FAIL', coverage: 'full',
+      reason: 'runtime failed', details: [], evidence: ['index.mjs:1'], method: 'M', advisory: false,
+    },
+  ]
+  const report = buildReport({
+    subject: { mode: 'package', profile: 'package', kind: 'plugin', kindInferred: false, name: 'x', version: '1.0.0', path: here },
+    anchor: { repo: 'x', commit: '0'.repeat(40), scanner: 'x', dsh: '0.2.2-alpha.2', cordis: '4.0.6-alpha.1', runtime: null },
+    checks,
+    scope: 'ds-c',
+    profile: 'package',
+    kind: 'plugin',
+  })
+  const c4 = report.advice.find(item => item.source === 'DSC-04')
+  const c14 = report.advice.find(item => item.source === 'DSC-14')
+  assert.equal(c4.key, 'C-4')
+  assert.equal(c4.severity, 'FAIL')
+  assert.equal(c4.version, '1.2.0')
+  assert.deepEqual(c4.evidence, ['index.mjs:1'])
+  assert.equal(c4.docsUrl, `${DOCS_BASE}docs/levels.md#entry`)
+  assert.equal(c14.key, 'C-14')
+  assert.equal(c14.docsUrl, `${DOCS_BASE}docs/entry.md#the-two-claims`)
+})
+
+test('advice uses detail severity even when the check was adjusted to WARN', () => {
+  const checks = [
+    { id: 'DSC-01', clause: 'C-1', layer: 'L0', result: 'PASS', coverage: 'full', reason: '', details: [], evidence: [] },
+    {
+      id: 'DSC-02', clause: 'C-2', layer: 'L0', result: 'FAIL', coverage: 'full', reason: '',
+      details: [{ item: 'C-2.1', result: 'FAIL', reason: 'no engines', evidence: ['package.json#engines'] }],
+      evidence: [], advisory: false,
+    },
+    { id: 'DSC-11', clause: 'C-11', layer: 'L0', result: 'PASS', coverage: 'full', reason: '', details: [], evidence: [] },
+    { id: 'DSC-12', clause: 'C-12', layer: 'L0', result: 'PASS', coverage: 'full', reason: '', details: [], evidence: [] },
+    { id: 'DSC-13', clause: 'C-13', layer: 'L0', result: 'PASS', coverage: 'full', reason: '', details: [], evidence: [] },
+    { id: 'DSC-14', clause: 'C-14', layer: 'L1', result: 'PASS', coverage: 'full', reason: '', details: [], evidence: [] },
+  ]
+  const report = buildReport({
+    subject: { mode: 'package', profile: 'package', kind: 'plugin', kindInferred: false, name: 'x', version: '1.0.0', path: here },
+    anchor: { repo: 'x', commit: '0'.repeat(40), scanner: 'x', dsh: '0.2.2-alpha.2', cordis: '4.0.6-alpha.1', runtime: null },
+    checks,
+    scope: 'entry',
+    profile: 'package',
+    kind: 'plugin',
+  })
+  assert.equal(report.checks.find(item => item.id === 'DSC-02').result, 'WARN')
+  const item = report.advice.find(entry => entry.key === 'C-2.1')
+  assert.equal(item.severity, 'FAIL')
+  assert.equal(item.source, 'DSC-02')
+  assert.match(item.reason, /no engines/)
+})
+
+test('duplicate details merge evidence and count once per check and key', () => {
+  const checks = [{
+    id: 'DSC-11', clause: 'C-11', layer: 'L0', result: 'WARN', coverage: 'full', reason: '',
+    details: [
+      { item: 'C-11.2', result: 'WARN', reason: 'trigger tools', evidence: ['a.mjs:1'] },
+      { item: 'C-11.1', result: 'WARN', reason: 'missing capabilities', evidence: ['package.json#dsh.capabilities'] },
+      { item: 'C-11.2', result: 'WARN', reason: 'trigger web', evidence: ['b.mjs:2'] },
+    ],
+    evidence: [], advisory: true,
+  }]
+  const report = buildReport({
+    subject: { mode: 'package', profile: 'package', kind: 'plugin', kindInferred: false, name: 'x', version: '1.0.0', path: here },
+    anchor: { repo: 'x', commit: '0'.repeat(40), scanner: 'x', dsh: '0.2.2-alpha.2', cordis: '4.0.6-alpha.1', runtime: null },
+    checks,
+    scope: 'ds-c',
+    profile: 'package',
+    kind: 'plugin',
+  })
+  const merged = report.advice.find(item => item.key === 'C-11.2')
+  assert.ok(merged)
+  assert.equal(merged.occurrences, 2)
+  assert.deepEqual(merged.evidence, ['a.mjs:1', 'b.mjs:2'])
+  assert.equal(merged.advisory, true)
+  assert.equal(report.advice.filter(item => item.source === 'DSC-11').length, 2)
+})
+
+test('buildReport includes advice by default and omits it on advice:false', () => {
+  const base = {
+    subject: { mode: 'package', profile: 'package', kind: 'plugin', kindInferred: false, name: 'x', version: '1.0.0', path: here },
+    anchor: { repo: 'x', commit: '0'.repeat(40), scanner: 'x', dsh: '0.2.2-alpha.2', cordis: '4.0.6-alpha.1', runtime: null },
+    checks: [],
+    scope: 'ds-c',
+    profile: 'package',
+    kind: 'plugin',
+  }
+  const on = buildReport(base)
+  const off = buildReport({ ...base, advice: false })
+  assert.ok(Array.isArray(on.advice))
+  assert.equal(on.advice.length, 0)
+  assert.equal(Object.hasOwn(off, 'advice'), false)
+})
+
+test('every rule docs anchor exists in the local guide repository', t => {
+  if (!fs.existsSync(guideDocs)) {
+    t.skip(`guide docs not checked out at ${guideDocs}`)
+    return
+  }
+  const cache = new Map()
+  for (const [key, rule] of Object.entries(RULES)) {
+    const hash = rule.docs.indexOf('#')
+    const file = rule.docs.slice(0, hash)
+    const anchor = rule.docs.slice(hash + 1)
+    assert.ok(hash > 0 && !anchor.includes('#'), `${key}: docs must be <file>#<anchor>`)
+    const relative = file.replace(/^docs\//, '')
+    const absolute = path.join(guideDocs, relative)
+    assert.ok(fs.existsSync(absolute), `${key}: missing guide file ${file}`)
+    if (!cache.has(file)) cache.set(file, headingSlugs(fs.readFileSync(absolute, 'utf8')))
+    assert.ok(cache.get(file).has(anchor), `${key}: missing anchor ${rule.docs}`)
+  }
+})
+
+test('joinAdvice is pure and leaves the report untouched', () => {
+  const checks = [{
+    id: 'DSC-04', clause: 'C-4', layer: 'L1', result: 'FAIL', coverage: 'full',
+    reason: 'load failed', details: [], evidence: ['index.mjs'], method: 'M', advisory: false,
+  }]
+  const report = {
+    checks,
+    standard: { id: 'DS-C', version: '1.0.0' },
+  }
+  const snapshot = JSON.stringify(report)
+  const advice = joinAdvice(report, remediationSpec, DOCS_BASE)
+  assert.equal(JSON.stringify(report), snapshot)
+  assert.equal(advice.length, 1)
+  assert.equal(advice[0].key, 'C-4')
+  // A flat rule map (no version metadata) still gets the package version.
+  const bare = joinAdvice(report, RULES, DOCS_BASE)
+  assert.equal(bare[0].version, packageJson.version)
+})

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## 未发布
+
+- **FLOW 证据链**：新增 `spec/flow-evidence.schema.json`（`dsh-flow-evidence/2`）与 `40-checker/src/flow-evidence.mjs`。`level-audit --flow-evidence` 只接受 v2；v1（`dsh-flow-journey/1`、`dsh-flow-runtime/1`）与裸 `{Jx:{status}}` 标 `deprecated`，不计 pass。每个 J 须有 `checks[]` 且全部 `exitCode === 0`、断言成立、至少一条非 `static` 观测检查才计 pass（`warn`/`blocked`/`na`/`static` 不计 8/8）。v2 的 `chain.evidenceHash` 由 audit 重算，改动一个字节即 `invalid`。
+- **collector**：新增 `40-checker/bin/dsh-flow-collect.mjs`（根入口 `bin/dsh-flow-collect.mjs`，并支持 `dsh-levels flow collect`）。只读副本 + 前后 `treeSha256` 一致、`npm pack --ignore-scripts` 的 integrity/tarballSha256、`git rev-parse` commit、临时 HOME/DSH_HOME、失败五要素提示（子检查/命令/exitCode/stderr 末 20 行/日志绝对路径 + 条款锚）；前置缺失记 `blocked` 且 exit 0，真失败 exit 1。
+- **安全**：新增 `40-checker/src/sandbox-env.mjs` 白名单 env。`src/cli.mjs` 的 runtime-child/bundle-smoke 子进程、`bundle-smoke.mjs`/`runtime-child.mjs` 进程内 boot、`m2-runner.mjs`、`journey-runtime.mjs`、`journey-config-observe.mjs`、`flow-sample-ci.mjs`、`host-farm.mjs`、`entry18-web.mjs` 不再把 `process.env` 透传给被检插件/宿主 boot。
+- 测试 137 → 149（新增 `40-checker/test/flow-evidence.test.mjs`：v1 不再 pass、v2 伪造 checks/exitCode 不 pass、篡改链路 invalid、blocked 不判 fail、collector 产物可被 audit 读取、失败五要素提示、env 白名单）。
+
+## 1.2.0 — 2026-11-06
+
+- 新增**建议管道**：`spec/remediation.json` 提供 68 条规则（`details[].item` ∪ `checks[].clause` ∪ G0–G4），`40-checker/src/remediation.mjs` 的纯函数 `joinAdvice(report, rules, docsBase)` 把 FAIL/WARN detail 连接成 `advice[]`；无 detail 的运行时 FAIL 用 `check.clause` 兜底（C-4/C-14）。
+- `buildReport()` 输出新增**加性** `advice[]`（key/severity/title/why/fix/docsUrl/source/version/evidence），不改任何 check 构造、不改判定与 exit code；CLI 新增 `--advice`（默认开）与 `--no-advice`。
+- 建议文档统一指向 `dsh-plugin-guide` 的 v0.4.3：`docsUrl = https://github.com/PerryLink/dsh-plugin-guide/blob/v0.4.3/ + docs`；规则表 `docs` 只存 `文件#锚点`。
+- 新增 `40-checker/test/remediation.test.mjs`：规则表覆盖全集、fixture 无 `ruleMissing`、本地 guide 锚点存在、severity/merge/兜底/纯函数回归。测试 128 → 137。
+
 ## 1.1.2 — 2026-11-04
 
 - 修复 1.1.1 的发布失败：vendored `@babel/parser` 的 `node_modules/` 被根 `.gitignore` 忽略，CI checkout 缺依赖导致 `npm test` 失败。现在 force-add 四个 vendored 包（约 2 MB），并加 1.1.2 的回归说明。
@@ -65,6 +79,12 @@
 
 # Changelog
 
+## 2026-11-04 — 0.2.2-alpha.3 baseline in the three-level docs
+
+- Add the 0.2.2-alpha.3 baseline table and six PR-review evidence gates to `35`.
+- Carry the baseline into `31` (ENTRY), `32` (FLOW R6) and the `33` BOOST card.
+- Fix the ENTRY checklist: Node `>=24.9.0`, `engines.dsh` precedence from 0.2.1-alpha.4, frozen lockfile / release-age evidence.
+
 ## 2026-11-03 — Node 24.9 baseline
 - Require Node >=24.9.0 to match DeepSeek Harness 0.2.2-alpha.3.
 

package/bin/dsh-flow-collect.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+// Public umbrella entry point for the FLOW evidence collector.
+// The implementation lives in 40-checker/.
+import '../40-checker/bin/dsh-flow-collect.mjs'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-standards",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "description": "DSH plugin standards and conformance checks: ENTRY/FLOW checks plus BOOST guidance. Non-official; no certification or ranking.",
   "type": "module",
   "main": "40-checker/src/index.mjs",

package/spec/README.md

@@ -14,7 +14,9 @@ Machine-readable:
 - [levels.json](levels.json) — levels, gates, evidence states, crosswalk.
 - [clauses.json](clauses.json) — stable clause IDs mapped to gates (`clause-map.mjs`).
 - [reference-suite.json](reference-suite.json) — versioned samples, anchors, change rules.
+- [remediation.json](remediation.json) — 68-key advice table for the additive `advice[]` report field (docs anchors + severity hints).
 - [schemas/evidence.schema.json](schemas/evidence.schema.json) — `dsh-levels/1` record.
+- [flow-evidence.schema.json](flow-evidence.schema.json) — `dsh-flow-evidence/2` FLOW chain (J1–J8 checks, subject/host binding, `evidenceHash`). v1 and bare `{Jx:{status}}` rows are deprecated and never count as a pass.
 - [schemas/attestation.schema.json](schemas/attestation.schema.json) — `dsh-attestation/1` quality record.
 - [schemas/report.schema.json](schemas/report.schema.json) — `dsh-report/1` inspection report (no grade).
 - [../40-checker/scripts/level-audit.mjs](../40-checker/scripts/level-audit.mjs) — one-command audit.

package/spec/flow/README.md

@@ -4,5 +4,26 @@ Usability surface: install, configure, first success, permissions, upgrade,
 uninstall, diagnostics, client/server states.
 
 - Normative text: [../../32-DSH-FLOW顺畅规范.md](../../32-DSH-FLOW顺畅规范.md)
-- Journeys: J1–J8; only J1 has a runtime harness (`40-checker/scripts/journey-runtime.mjs`).
-- Current: J1 6 PASS + 1 WARN; J2–J8 not-run.
+- Journeys: J1–J8 (R1–R8 in the normative text).
+- Runtime probe: `40-checker/scripts/journey-runtime.mjs` (J1/J2/J4/J6); J3/J5/J7/J8
+  are static preflight or manual and never count as a runtime pass.
+- Evidence: `dsh-flow-evidence/2` ([../flow-evidence.schema.json](../flow-evidence.schema.json)).
+  Collect it with `node 40-checker/bin/dsh-flow-collect.mjs --package <dir> --out flow-evidence.json`.
+
+## Evidence chain rules
+
+- `level-audit.mjs --flow-evidence` accepts only `dsh-flow-evidence/2`. v1
+  (`dsh-flow-journey/1`, `dsh-flow-runtime/1`) and bare `{ "J1": { "status": "pass" } }`
+  rows are reported `deprecated` and never count as a pass.
+- A journey counts as pass only when it has at least one `checks[]` element,
+  every check has `exitCode === 0`, every assertion holds, and at least one
+  check is an observed (non-`static`) command. `warn`, `blocked`, `na`,
+  `static` and `not-run` never count toward 8/8.
+- `static` preflight is not runtime: a static PASS is a preflight result only.
+- The collector copies the package to a temp dir, runs against the copy, and
+  records `subject.treeSha256` before/after; a changed tree fails the run.
+- Child environments are built from an allowlist; tokens/keys/secrets never
+  reach the inspected plugin.
+- `claims.claimLevel` is `self-attested` for a local collector run,
+  `ci-attested` with `--ci`. Neither is `verified`, a certification, or a
+  security audit; only a sandbox run may be described as runtime-attested.

package/spec/flow-evidence.schema.json

@@ -0,0 +1,217 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/PerryLink/dsh-standards/spec/flow-evidence.schema.json",
+  "title": "DSH FLOW evidence chain",
+  "description": "One collected FLOW result (J1-J8) bound to a package, a host, a timestamp, and a chain hash. Structural validation only: it does not prove the commands really ran. v1 (dsh-flow-journey/1, dsh-flow-runtime/1) and bare {Jx:{status}} documents are deprecated and never count as a pass. `level-audit.mjs --flow-evidence` accepts this document only.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "generatedAt",
+    "producer",
+    "subject",
+    "host",
+    "journeys",
+    "claims",
+    "chain"
+  ],
+  "properties": {
+    "schema": {
+      "const": "dsh-flow-evidence/2"
+    },
+    "evidenceId": {
+      "type": "string",
+      "minLength": 1
+    },
+    "generatedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "producer": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["command", "at"],
+      "properties": {
+        "command": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string" }
+        },
+        "at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "kind": {
+          "enum": ["local", "ci", "sandbox"]
+        },
+        "runner": { "type": "string" },
+        "actor": { "type": "string" },
+        "runUrl": { "type": "string" }
+      }
+    },
+    "subject": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "version", "integrity", "tarballSha256", "commit", "treeSha256"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "version": { "type": "string", "minLength": 1 },
+        "integrity": {
+          "oneOf": [
+            { "type": "string", "pattern": "^(sha512|sha256)-[A-Za-z0-9+/=]+$" },
+            { "type": "null" }
+          ]
+        },
+        "tarballSha256": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+        "commit": {
+          "oneOf": [
+            { "type": "string", "pattern": "^[0-9a-f]{40}$" },
+            { "type": "null" }
+          ]
+        },
+        "treeSha256": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+        "treeSha256After": {
+          "oneOf": [
+            { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+            { "type": "null" }
+          ]
+        },
+        "treeStable": { "type": "boolean" },
+        "treeExclude": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "source": { "type": "string" }
+      }
+    },
+    "host": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["dsh", "node", "platform"],
+      "properties": {
+        "dsh": {
+          "oneOf": [
+            { "type": "string", "minLength": 1 },
+            { "type": "null" }
+          ]
+        },
+        "dshCommit": {
+          "oneOf": [
+            { "type": "string", "pattern": "^[0-9a-f]{7,40}$" },
+            { "type": "null" }
+          ]
+        },
+        "cordis": { "type": "string" },
+        "node": { "type": "string", "minLength": 1 },
+        "platform": { "type": "string", "minLength": 1 }
+      }
+    },
+    "journeys": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["J1", "J2", "J3", "J4", "J5", "J6", "J7", "J8"],
+      "patternProperties": {
+        "^J[1-8]$": { "$ref": "#/$defs/journey" }
+      }
+    },
+    "claims": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["claimLevel"],
+      "properties": {
+        "claimLevel": {
+          "enum": ["self-attested", "ci-attested", "sandbox-attested"]
+        },
+        "notClaimed": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "method": { "type": "string" }
+      }
+    },
+    "chain": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["evidenceHash"],
+      "properties": {
+        "evidenceHash": { "$ref": "#/$defs/sha256" }
+      }
+    },
+    "conclusion": {
+      "enum": ["flow-pass", "flow-warn", "flow-blocked", "flow-fail"]
+    },
+    "signature": {
+      "oneOf": [{ "type": "object" }, { "type": "null" }]
+    }
+  },
+  "$defs": {
+    "sha256": {
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$"
+    },
+    "log": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "sha256"],
+      "properties": {
+        "path": { "type": "string", "minLength": 1 },
+        "sha256": { "$ref": "#/$defs/sha256" }
+      }
+    },
+    "assertion": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["claim", "observed"],
+      "properties": {
+        "claim": { "type": "string", "minLength": 1 },
+        "observed": { "type": "boolean" },
+        "detail": { "type": "string" }
+      }
+    },
+    "check": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "command", "exitCode", "startedAt", "endedAt", "stdout", "assertions"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^J[1-8](?:\\.[A-Za-z0-9._-]+)?$" },
+        "kind": { "enum": ["observed", "static", "manual"] },
+        "command": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string" }
+        },
+        "exitCode": { "type": "integer", "minimum": 0, "maximum": 255 },
+        "startedAt": { "type": "string", "format": "date-time" },
+        "endedAt": { "type": "string", "format": "date-time" },
+        "stdout": { "$ref": "#/$defs/log" },
+        "stderr": { "$ref": "#/$defs/log" },
+        "assertions": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/assertion" }
+        },
+        "durationMs": { "type": "number", "minimum": 0 }
+      }
+    },
+    "journey": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["checks"],
+      "properties": {
+        "status": {
+          "enum": ["pass", "fail", "warn", "blocked", "static", "na", "not-run"]
+        },
+        "reason": { "type": "string" },
+        "kind": { "type": "string" },
+        "limitations": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "checks": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/check" }
+        }
+      }
+    }
+  }
+}

package/spec/levels.json

@@ -156,6 +156,8 @@
       "machine": {
         "journey": "40-checker/scripts/journey.mjs",
         "journeyRuntime": "40-checker/scripts/journey-runtime.mjs",
+        "collector": "40-checker/bin/dsh-flow-collect.mjs",
+        "flowEvidence": "spec/flow-evidence.schema.json",
         "audit": "40-checker/scripts/level-audit.mjs"
       }
     },