dsh-xray 0.10.2 → 0.11.0

package/README.md

@@ -79,19 +79,20 @@ The same data flows through three surfaces: the **X-Ray tab** (native GUI), the
 
 ```sh
 npx dsh-xray attribute   # which layer introduced each row, and who patched it since
-npx dsh-xray conflicts   # rows whose fields have multiple writers, and who wins
+npx dsh-xray conflicts   # contested fields with per-writer evidence: file:line, value, winner
 npx dsh-xray diff        # declared (static layers) vs actual (dump-config) tree
-npx dsh-xray snapshot    # content-addressed lockfile of the effective composition
-npx dsh-xray deps [svc]  # service dependency graph: providers, consumers, disable-cascade
+npx dsh-xray snapshot    # content-addressed lockfile; --against <lock> reports drift, exits 1
+npx dsh-xray deps [svc]  # service dependency graph: providers, consumers, transitive disable-cascade
 npx dsh-xray health      # plugin lifecycle health: failed fibers, pending injects, transitions
 npx dsh-xray cost        # context cost: prompt sections + tool schemas, estimated tokens
 npx dsh-xray shadow      # services provided by multiple plugins
+npx dsh-xray verify      # declared (static) rows ↔ runtime registry, exits 1 on mismatch
 npx dsh-xray audit       # static scan of out-of-tree plugins for sensitive touchpoints
 ```
 
 ![dsh-xray demo](./docs/demo.svg)
 
-`attribute`, `conflicts`, and `snapshot` are fully static — they work even when dsh cannot boot. All commands take `--profile <name>` (default `web`) and `--json`; `diff` and `health` exit `1` on drift/unhealth, so they slot into CI.
+`attribute`, `conflicts`, and `snapshot` are fully static — they work even when dsh cannot boot. All commands take `--profile <name>` (default `web`) and `--json`; every JSON payload carries a versioned `schema` field (`dsh-xray/<view>@1`) so machine consumers detect shape changes instead of guessing. Exit codes slot into CI: `diff` (trees disagree), `health` (unhealthy plugin), `snapshot --against <lock>` (composition drifted), `shadow` (multi-provider service) and `verify` (declared ↔ runtime mismatch) all exit `1`.
 
 ---
 
@@ -113,13 +114,20 @@ Installed-but-inactive, uninstalled-but-lingering patch rows — including patch
 Plugins patching the same config row, and which one silently wins.
 
 ### 📸 Composition Snapshot
-Export the effective composition as a lockfile; reproduce it elsewhere, diff against it later.
+Export the effective composition as a lockfile; `snapshot --against <lock>` reports drift — bundle version / patch content / package changes — and exits `1`.
 
 </td>
 <td width="50%">
 
 ### 🌐 Service Dependency Graph
-Who provides and consumes each service — and the **disable-cascade**: exactly which dependents go down if you disable X.
+Who provides and consumes each service — and the full **transitive** disable-cascade: not just direct consumers, but everything downstream of the services they re-provide.
+
+```console
+$ npx dsh-xray deps
+# disable-cascade (transitive consumers of each provider):
+  Loader → 5 plugin(s): AgentPresets, ClientModuleRegistry, Hmr, …
+  TimerService → 1 plugin(s): Hmr
+```
 
 ### 💊 Runtime Health
 Per-plugin fiber lifecycle state, startup failures, pending injects, transition history.
@@ -140,7 +148,7 @@ Heuristic static scan of out-of-tree plugins: network egress, shell, filesystem,
   <img src="./assets/section-agent.svg" width="100%" alt="Agent Tool">
 </p>
 
-Mounted in the tree, dsh-xray registers an `xray_composition` tool (`view: summary | deps | health | cost | shadow`), so an agent can answer:
+Mounted in the tree, dsh-xray registers an `xray_composition` tool (`view: summary | deps | health | cost | shadow | skills | requests`), so an agent can answer:
 
 > *"What capabilities do I have?" / "What plugin provides X?" / "Why is Y unavailable?"*
 
@@ -160,6 +168,18 @@ Mounted in the tree, dsh-xray registers an `xray_composition` tool (`view: summa
 - The entry endpoint returns composition-layer text only, **never session messages**
 - See [SECURITY.md](./SECURITY.md)
 
+## Analysis modes
+
+Every result names its trust boundary:
+
+| Mode | Commands | Boundary |
+| --- | --- | --- |
+| **Static** | `attribute`, `conflicts`, `snapshot` | Exact replay of the on-disk layer stack; works even when dsh cannot boot. Cannot observe runtime behavior. |
+| **Static + spawn** | `diff` | Replays the layers, then spawns `dsh --dump-config` to compare declared vs. actual. |
+| **Static + runtime** | `verify` | Joins both sides: declared rows that never mounted, disabled rows still running, runtime-only plugins, snapshot staleness. |
+| **Runtime** | `deps`, `health`, `cost`, `shadow`, tab, `/xray` panel, agent tool | Observed from the running composition (`$DSH_HOME/xray/runtime.json`); valid for the current session only. Token counts are estimates (~4 chars/token) unless you open the entry text and count. |
+| **Heuristic** | `audit` | Pattern scan over source text; false positives and negatives are expected. A flag means "this pattern appears", never "this plugin is malicious". |
+
 ---
 
 <p align="center">
@@ -192,12 +212,13 @@ npx dsh-xray health                               # reads the runtime snapshot
 
 Uninstall: `dsh plugin --profile web remove dsh-xray`.
 
-| Command | Behavior |
+| Command | Exit code |
 | --- | --- |
-| `diff` | Exits `1` when the trees disagree |
-| `health` | Exits `1` when any plugin is unhealthy |
-| `attribute`, `conflicts`, `snapshot` | Fully static — work even when dsh cannot start |
-| `deps`, `health` | Read runtime snapshot at `$DSH_HOME/xray/runtime.json` |
+| `diff` | `1` when the trees disagree |
+| `health` | `1` when any plugin is unhealthy |
+| `snapshot --against <lock>` | `1` when the composition drifted |
+| `shadow` | `1` when any service has multiple providers |
+| `verify` | `1` on any declared ↔ runtime mismatch |
 
 ---
 
@@ -216,6 +237,7 @@ Diagnostic imaging for a running composition — complementary to [dsh-doctor](h
 | Declared vs. actual diff | 🔍 Inspection |
 | Conflict detection | 🔍 Inspection |
 | Composition snapshot | 📦 Export |
+| Static ↔ runtime verification | 🔍 Inspection |
 | Service dependency graph | 🌐 Runtime |
 | Runtime health | 🌐 Runtime |
 | Service shadowing | 🌐 Runtime |

package/bin/xray.js

@@ -58,13 +58,24 @@ function cmdConflicts(args) {
   const data = collectStatic(args.profile);
   const result = model.conflicts(data);
   if (args.json) return console.log(JSON.stringify(result, null, 2));
-  if (!result.length) return console.log('no contested rows: every field has a single writer');
-  for (const c of result) {
+  if (!result.conflicts.length)
+    return console.log('no contested rows: every field has a single writer');
+  const path = require('node:path');
+  const show = (v) => {
+    const s = JSON.stringify(v) ?? '(unset)';
+    return s.length > 48 ? `${s.slice(0, 45)}…` : s;
+  };
+  for (const c of result.conflicts) {
     console.log(`${c.id}`);
     for (const f of c.fields) {
-      console.log(
-        `  .${f.field}: ${f.writers.map((w) => w.layer).join(' → ')}  (winner: ${f.winner})`,
-      );
+      console.log(`  .${f.field} — winner: ${f.winner} (last writer wins)`);
+      for (const w of f.writers) {
+        const loc = w.file
+          ? `  ${path.relative(data.home, w.file)}${w.line ? `:${w.line}` : ''}`
+          : '';
+        console.log(`    ${pad(w.layer, 24)} ${pad(w.action, 9)} ${pad(show(w.value), 48)}${loc}`);
+      }
+      console.log(`    effective: ${show(f.effective)}`);
     }
   }
 }
@@ -268,6 +279,52 @@ function cmdShadow(args) {
   panelHint(args);
 }
 
+function cmdVerify(args) {
+  const data = collectStatic(args.profile);
+  const snap = readRuntimeSnapshot();
+  const fs = require('node:fs');
+  let staticMtimeMs = null;
+  for (const l of data.layers) {
+    try {
+      staticMtimeMs = Math.max(staticMtimeMs ?? 0, fs.statSync(l.file).mtimeMs);
+    } catch {
+      /* unreadable layer file: leave staleness unknown for it */
+    }
+  }
+  const result = model.verify(data, snap, { staticMtimeMs });
+  if (args.json) return console.log(JSON.stringify(result, null, 2));
+
+  const declared = result.matched.length + result.declaredNotRunning.length;
+  console.log(`runtime snapshot captured ${result.capturedAt}`);
+  if (result.stale) {
+    console.log(
+      '! static layers changed after this snapshot — restart dsh or wait for the next refresh',
+    );
+  }
+  const mark = result.declaredNotRunning.length ? '⚠' : '✓';
+  console.log(
+    `${mark} declared enabled plugins observed at runtime: ${result.matched.length}/${declared}`,
+  );
+  for (const r of result.declaredNotRunning) console.log(`  missing: ${r.id} (${r.name})`);
+  if (result.disabledButRunning.length) {
+    console.log(`✗ disabled but running (${result.disabledButRunning.length}):`);
+    for (const r of result.disabledButRunning) {
+      console.log(`  ${r.id} (${r.name}) — runtime: ${r.runtime}`);
+    }
+  }
+  if (result.undeclaredRuntime.length) {
+    console.log(
+      `+ ${result.undeclaredRuntime.length} runtime-only plugin(s) (programmatic subplugins are normal): ${result.undeclaredRuntime.slice(0, 6).join(', ')}${result.undeclaredRuntime.length > 6 ? ', …' : ''}`,
+    );
+  }
+  if (result.unsatisfied.length) {
+    console.log(`! ${result.unsatisfied.length} unsatisfied inject(s):`);
+    for (const u of result.unsatisfied) console.log(`  ${u.plugin} wants ${u.service}`);
+  }
+  if (result.declaredNotRunning.length || result.disabledButRunning.length) process.exitCode = 1;
+  panelHint(args);
+}
+
 function cmdAudit(args) {
   const { collectAudit } = require('../lib/collect/audit.js');
   const data = collectStatic(args.profile);
@@ -298,6 +355,7 @@ const commands = {
   health: cmdHealth,
   cost: cmdCost,
   shadow: cmdShadow,
+  verify: cmdVerify,
   audit: cmdAudit,
 };
 
@@ -317,9 +375,10 @@ Commands:
   health      plugin lifecycle health from the live runtime snapshot
   cost        estimated context-token cost of each model-facing tool schema
   shadow      services provided by multiple plugins, and per-plugin registrations
+  verify      declared (static) rows reconciled against the runtime registry
   audit       static scan of out-of-tree plugins for sensitive touchpoints
 
-deps/health/cost/shadow need the plugin mounted: dsh plugin --profile web add dsh-xray`);
+deps/health/cost/shadow/verify need the plugin mounted: dsh plugin --profile web add dsh-xray`);
   process.exit(args._[0] ? 2 : 0);
 }
 try {

package/docs/README.zh.md

@@ -78,19 +78,20 @@ cost 视图回答一个别的工具都不问的问题:**这段上下文是谁放
 
 ```sh
 npx dsh-xray attribute   # 每一行由哪层引入、之后被谁 patch 过
-npx dsh-xray conflicts   # 哪些行的字段有多个写者、最终谁赢
+npx dsh-xray conflicts   # 有争议的字段,带每个写者的证据:file:line、写入值、赢家
 npx dsh-xray diff        # 声明(静态层)vs 实际(dump-config)组合树
-npx dsh-xray snapshot    # 当前生效组合的内容寻址 lockfile
-npx dsh-xray deps [svc]  # 服务依赖图:提供者、消费者、停用级联
+npx dsh-xray snapshot    # 内容寻址 lockfile;--against <lock> 对比漂移,漂移时退出码 1
+npx dsh-xray deps [svc]  # 服务依赖图:提供者、消费者、传递性停用级联
 npx dsh-xray health      # 插件生命周期健康:失败 fiber、等待中的注入、状态迁移史
 npx dsh-xray cost        # 上下文成本:prompt sections + 工具 schema 的估算 token 占用
 npx dsh-xray shadow      # 被多个插件同时提供的服务
+npx dsh-xray verify      # 声明(静态)行 ↔ 运行时注册表对账,不一致退出码 1
 npx dsh-xray audit       # 对 out-of-tree 插件做敏感触点静态扫描
 ```
 
 ![dsh-xray 演示](./demo.svg)
 
-`attribute`、`conflicts`、`snapshot` 是纯静态的——dsh 起不来时照样能跑。所有命令支持 `--profile <name>`(默认 `web`)和 `--json`;`diff` 与 `health` 在漂移/不健康时退出码 `1`,可直接进 CI。
+`attribute`、`conflicts`、`snapshot` 是纯静态的——dsh 起不来时照样能跑。所有命令支持 `--profile <name>`(默认 `web`)和 `--json`;所有 JSON 输出都带版本化的 `schema` 字段(`dsh-xray/<view>@1`),机器消费方据此识别结构变化而不必猜。退出码可直接进 CI:`diff`(两树不一致)、`health`(有插件不健康)、`snapshot --against <lock>`(组合漂移)、`shadow`(服务被多方提供)、`verify`(声明与运行时不符)均返回 `1`。
 
 ---
 
@@ -112,13 +113,20 @@ npx dsh-xray audit       # 对 out-of-tree 插件做敏感触点静态扫描
 多个插件 patch 同一配置行时,谁静默赢了。
 
 ### 📸 组合快照
-把当前生效组合导出为 lockfile,异地复现、事后对比。
+把当前生效组合导出为 lockfile;`snapshot --against <lock>` 报告漂移——bundle 版本 / patch 内容 / 包变化——并退出码 `1`。
 
 </td>
 <td width="50%">
 
 ### 🌐 服务依赖图
-每个服务谁提供、谁消费——以及**停用级联**:停用 X 会连带瘫掉哪些依赖方。
+每个服务谁提供、谁消费——以及**传递性**停用级联:不只是直接消费者,还包括它们再提供的服务的所有下游。
+
+```console
+$ npx dsh-xray deps
+# disable-cascade (transitive consumers of each provider):
+  Loader → 5 plugin(s): AgentPresets, ClientModuleRegistry, Hmr, …
+  TimerService → 1 plugin(s): Hmr
+```
 
 ### 💊 运行时健康
 每个插件的 fiber 生命周期状态、启动失败、等待中的注入、状态迁移史。
@@ -139,7 +147,7 @@ npx dsh-xray audit       # 对 out-of-tree 插件做敏感触点静态扫描
   <img src="../assets/section-agent.svg" width="100%" alt="Agent 工具">
 </p>
 
-挂载进树后,dsh-xray 注册 `xray_composition` 工具(`view: summary | deps | health | cost | shadow`),agent 可以自答:
+挂载进树后,dsh-xray 注册 `xray_composition` 工具(`view: summary | deps | health | cost | shadow | skills | requests`),agent 可以自答:
 
 > *"我有哪些能力?" / "哪个插件提供 X?" / "为什么 Y 不可用?"*
 
@@ -159,6 +167,18 @@ npx dsh-xray audit       # 对 out-of-tree 插件做敏感触点静态扫描
 - entry 端点只返回组合层文本,**绝不返回会话消息**
 - 详见 [SECURITY.md](../SECURITY.md)
 
+## 分析模式
+
+每类结果都有明确的可信度边界:
+
+| 模式 | 命令 | 边界 |
+| --- | --- | --- |
+| **静态** | `attribute`、`conflicts`、`snapshot` | 对磁盘上层栈的精确重放;dsh 起不来也能跑。观测不到运行时行为。 |
+| **静态 + 外呼** | `diff` | 重放层栈后,再起一个 `dsh --dump-config` 对比声明与实际。 |
+| **静态 + 运行时** | `verify` | 两侧对账:声明了却没挂载的行、禁用了还在跑的行、只存在于运行时的插件、快照过期。 |
+| **运行时** | `deps`、`health`、`cost`、`shadow`、标签页、`/xray` 面板、agent 工具 | 观测自运行中的组合树(`$DSH_HOME/xray/runtime.json`),只对当前会话有效。token 为估算值(约 4 字符/token),除非你打开条目原文自己数。 |
+| **启发式** | `audit` | 对源码文本的模式扫描;可能误报漏报。命中只表示"该模式出现在代码里",绝不等于"该插件是恶意的"。 |
+
 ---
 
 <p align="center">
@@ -191,12 +211,13 @@ npx dsh-xray health                               # 读取运行时快照
 
 卸载:`dsh plugin --profile web remove dsh-xray`。
 
-| 命令 | 行为 |
+| 命令 | 退出码 |
 | --- | --- |
-| `diff` | 两棵树不一致时退出码 `1` |
-| `health` | 有插件不健康时退出码 `1` |
-| `attribute`、`conflicts`、`snapshot` | 纯静态——dsh 起不来时照样能跑 |
-| `deps`、`health` | 读取 `$DSH_HOME/xray/runtime.json` 运行时快照 |
+| `diff` | 两棵树不一致时 `1` |
+| `health` | 有插件不健康时 `1` |
+| `snapshot --against <lock>` | 组合漂移时 `1` |
+| `shadow` | 服务被多方提供时 `1` |
+| `verify` | 声明与运行时不符时 `1` |
 
 ---
 
@@ -215,6 +236,7 @@ npx dsh-xray health                               # 读取运行时快照
 | 声明 vs 实际 diff | 🔍 检视 |
 | 冲突检测 | 🔍 检视 |
 | 组合快照 | 📦 导出 |
+| 静态 ↔ 运行时对账 | 🔍 检视 |
 | 服务依赖图 | 🌐 运行时 |
 | 运行时健康 | 🌐 运行时 |
 | 服务遮蔽 | 🌐 运行时 |

package/lib/collect/static.js

@@ -16,9 +16,20 @@ const jsTag = {
 
 function parseYaml(text, file) {
   try {
-    return { value: YAML.parse(text, { customTags: [jsTag] }), error: null };
+    const lineCounter = new YAML.LineCounter();
+    const doc = YAML.parseDocument(text, { customTags: [jsTag], lineCounter });
+    if (doc.errors.length) {
+      return { value: null, lines: [], error: `${file}: ${doc.errors[0].message}` };
+    }
+    // One source line per top-level patch entry, for evidence output.
+    const lines = YAML.isSeq(doc.contents)
+      ? doc.contents.items.map((item) =>
+          item?.range ? lineCounter.linePos(item.range[0]).line : null,
+        )
+      : [];
+    return { value: doc.toJS(), lines, error: null };
   } catch (err) {
-    return { value: null, error: `${file}: ${err.message}` };
+    return { value: null, lines: [], error: `${file}: ${err.message}` };
   }
 }
 
@@ -79,7 +90,7 @@ function collectStatic(profileName) {
     }
     const file = path.join(dir, rel);
     const text = fs.readFileSync(file, 'utf8');
-    const { value, error } = parseYaml(text, file);
+    const { value, lines, error } = parseYaml(text, file);
     if (error) warnings.push(error);
     layers.push({
       kind: 'bundle',
@@ -87,6 +98,7 @@ function collectStatic(profileName) {
       version: pkg.version ?? null,
       file,
       entries: Array.isArray(value) ? value : [],
+      lines,
       text,
     });
   }
@@ -97,7 +109,7 @@ function collectStatic(profileName) {
   ]) {
     if (!fs.existsSync(file)) continue;
     const text = fs.readFileSync(file, 'utf8');
-    const { value, error } = parseYaml(text, file);
+    const { value, lines, error } = parseYaml(text, file);
     if (error) warnings.push(error);
     layers.push({
       kind,
@@ -105,6 +117,7 @@ function collectStatic(profileName) {
       version: null,
       file,
       entries: Array.isArray(value) ? value : [],
+      lines,
       text,
     });
   }
@@ -131,7 +144,7 @@ function collectStatic(profileName) {
         continue;
       }
       const text = fs.readFileSync(file, 'utf8');
-      const { value, error } = parseYaml(text, file);
+      const { value, lines, error } = parseYaml(text, file);
       if (error) warnings.push(error);
       layers.push({
         kind: 'repository',
@@ -139,6 +152,7 @@ function collectStatic(profileName) {
         version: pkg.version ?? null,
         file,
         entries: Array.isArray(value) ? value : [],
+        lines,
         text,
       });
     }

package/lib/compare.js

@@ -68,7 +68,13 @@ function compareSnapshots(saved, current) {
     !changes.patches.length &&
     !changes.packages.length &&
     !changes.composed;
-  return { identical, savedAt: saved.createdAt, profile: saved.profile, changes };
+  return {
+    schema: 'dsh-xray/snapshot-diff@1',
+    identical,
+    savedAt: saved.createdAt,
+    profile: saved.profile,
+    changes,
+  };
 }
 
 module.exports = { compareSnapshots };

package/lib/index.js

@@ -177,6 +177,7 @@ function apply(ctx) {
               summary: () => {
                 const snap = freshSnap();
                 return {
+                  schema: 'dsh-xray/summary@1',
                   plugins: snap.plugins.length,
                   unhealthy: health(snap).unhealthy.length,
                   services: Object.keys(serviceGraph(snap).services).length,
@@ -257,6 +258,7 @@ function apply(ctx) {
             if (args.view === 'skills') return skillCost(snap);
             if (args.view === 'requests') return requestLedger(snap);
             return {
+              schema: 'dsh-xray/summary@1',
               plugins: snap.plugins.length,
               unhealthy: health(snap).unhealthy.length,
               services: Object.keys(serviceGraph(snap).services).length,

package/lib/model.js

@@ -12,7 +12,7 @@ const crypto = require('node:crypto');
  *
  * @param layers output of collectStatic().layers
  * @returns {{rows: Map<id, row>, orphans: [], provenance: Map<id, [event]>}}
- *   event: {layer, kind, action: 'insert'|'override', file, fields}
+ *   event: {layer, kind, file, line, action: 'insert'|'override', fields, values, before?}
  */
 function replayLayers(layers) {
   const rows = new Map();
@@ -25,25 +25,39 @@ function replayLayers(layers) {
   };
 
   for (const layer of layers) {
-    const meta = { layer: layer.name, kind: layer.kind, file: layer.file };
-    for (const entry of layer.entries) {
+    layer.entries.forEach((entry, index) => {
+      const meta = {
+        layer: layer.name,
+        kind: layer.kind,
+        file: layer.file,
+        line: layer.lines?.[index] ?? null,
+      };
       if (entry && Array.isArray(entry.insert)) {
         for (const row of entry.insert) {
           const id = row.id ?? row.name;
           rows.set(id, { ...row, id });
-          record(id, { ...meta, action: 'insert', fields: Object.keys(row) });
+          record(id, { ...meta, action: 'insert', fields: Object.keys(row), values: { ...row } });
         }
       } else if (entry && entry.id !== undefined) {
         const { id, ...rest } = entry;
-        if (!rows.has(id)) {
+        const current = rows.get(id);
+        if (!current) {
           orphans.push({ ...meta, id, fields: Object.keys(rest) });
-          continue;
+          return;
         }
+        const before = {};
+        for (const f of Object.keys(rest)) before[f] = current[f];
         // Loader semantics: whole-config replacement, not deep merge.
-        rows.set(id, { ...rows.get(id), ...rest });
-        record(id, { ...meta, action: 'override', fields: Object.keys(rest) });
+        rows.set(id, { ...current, ...rest });
+        record(id, {
+          ...meta,
+          action: 'override',
+          fields: Object.keys(rest),
+          values: { ...rest },
+          before,
+        });
       }
-    }
+    });
   }
   return { rows, provenance, orphans };
 }
@@ -58,18 +72,26 @@ function attribute(staticData) {
       id: row.id,
       name: row.name ?? null,
       disabled: row.disabled === true,
-      origin: origin ? { layer: origin.layer, kind: origin.kind } : null,
+      origin: origin
+        ? { layer: origin.layer, kind: origin.kind, file: origin.file, line: origin.line }
+        : null,
       overrides: events
         .filter((e) => e.action === 'override')
-        .map((e) => ({ layer: e.layer, kind: e.kind, fields: e.fields })),
+        .map((e) => ({
+          layer: e.layer,
+          kind: e.kind,
+          file: e.file,
+          line: e.line,
+          fields: e.fields,
+        })),
     };
   });
-  return { rows: table, orphans, warnings: staticData.warnings };
+  return { schema: 'dsh-xray/attribute@1', rows: table, orphans, warnings: staticData.warnings };
 }
 
 /** F3: rows written by more than one layer, with the winning writer last. */
 function conflicts(staticData) {
-  const { provenance } = replayLayers(staticData.layers);
+  const { rows, provenance } = replayLayers(staticData.layers);
   const out = [];
   for (const [id, events] of provenance) {
     // A conflict needs two writers touching the same field set beyond the insert.
@@ -80,7 +102,14 @@ function conflicts(staticData) {
       for (const f of e.fields) {
         if (f === 'id') continue;
         if (!byField.has(f)) byField.set(f, []);
-        byField.get(f).push({ layer: e.layer, kind: e.kind, action: e.action });
+        byField.get(f).push({
+          layer: e.layer,
+          kind: e.kind,
+          action: e.action,
+          file: e.file,
+          line: e.line,
+          value: e.values?.[f],
+        });
       }
     }
     const contested = [...byField.entries()].filter(([, w]) => w.length > 1);
@@ -91,10 +120,15 @@ function conflicts(staticData) {
         field,
         writers,
         winner: writers[writers.length - 1].layer,
+        effective: rows.get(id)?.[field],
       })),
     });
   }
-  return out;
+  return {
+    schema: 'dsh-xray/conflicts@1',
+    semantics: 'per-field last-writer-wins, layers applied in load order',
+    conflicts: out,
+  };
 }
 
 /** F2: declared (static replay) vs actual (dump-config) diff. */
@@ -133,6 +167,7 @@ function diff(staticData, dumpData) {
     .map((p) => ({ name: p.name, version: p.version }));
 
   return {
+    schema: 'dsh-xray/diff@1',
     missingFromActual,
     missingFromDeclared,
     disabledMismatch,
@@ -214,7 +249,7 @@ function serviceGraph(snap) {
       }
     }
   }
-  return { services, cascade, unsatisfied };
+  return { schema: 'dsh-xray/deps@1', services, cascade, unsatisfied };
 }
 
 /** F5: unhealthy plugins from fiber states and transition history. */
@@ -237,6 +272,7 @@ function health(snap) {
     else healthy.push(entry);
   }
   return {
+    schema: 'dsh-xray/health@1',
     healthy: healthy.map((p) => p.name),
     waiting: waiting.map((p) => ({
       name: p.name,
@@ -253,7 +289,7 @@ function shadowing(snap) {
   // secondary source. Cordis rejects same-layer duplicate tools itself, so
   // what we surface is cross-source duplication: one service claimed by
   // multiple plugins (isolation scopes make this legal — and invisible).
-  const out = { services: [], registrars: [] };
+  const out = { schema: 'dsh-xray/shadow@1', services: [], registrars: [] };
   const providersByService = new Map();
   for (const s of snap.services ?? []) {
     if (!providersByService.has(s.name)) providersByService.set(s.name, []);
@@ -317,6 +353,7 @@ function contextCost(snap) {
     }));
 
   return {
+    schema: 'dsh-xray/cost@1',
     totalTokens: total,
     toolTokens,
     sectionTokens,
@@ -345,7 +382,10 @@ function contextCost(snap) {
  * ecosystem's skill managers: xray prices, it never toggles. */
 function skillCost(snap) {
   const observed = snap.skillCatalog;
-  if (!observed) return { available: false, skills: [], totals: null, capturedAt: snap.capturedAt };
+  const schema = 'dsh-xray/skills@1';
+  if (!observed) {
+    return { schema, available: false, skills: [], totals: null, capturedAt: snap.capturedAt };
+  }
   const rows = observed.skills
     .slice()
     .sort((a, b) => b.catalogTokens - a.catalogTokens)
@@ -360,6 +400,7 @@ function skillCost(snap) {
   const invocable = rows.filter((s) => s.modelInvocable);
   const catalogEntryTokens = invocable.reduce((sum, s) => sum + s.catalogTokens, 0);
   return {
+    schema,
     available: true,
     skills: rows,
     totals: {
@@ -382,8 +423,9 @@ function skillCost(snap) {
  * cost view lacks. */
 function requestLedger(snap) {
   const observed = snap.requestLedger;
+  const schema = 'dsh-xray/requests@1';
   if (!observed || Object.keys(observed).length === 0)
-    return { available: false, sessions: [], capturedAt: snap.capturedAt };
+    return { schema, available: false, sessions: [], capturedAt: snap.capturedAt };
   const sessions = Object.entries(observed)
     .map(([sessionId, entries]) => ({
       sessionId,
@@ -409,7 +451,57 @@ function requestLedger(snap) {
         })),
     }))
     .sort((a, b) => b.lastAt - a.lastAt);
-  return { available: true, sessions, capturedAt: snap.capturedAt };
+  return { schema, available: true, sessions, capturedAt: snap.capturedAt };
+}
+
+/** F12: reconcile the declared (static) composition against the runtime registry. */
+function verify(staticData, snap, { staticMtimeMs = null } = {}) {
+  const { rows } = replayLayers(staticData.layers);
+  const norm = (s) =>
+    String(s ?? '')
+      .toLowerCase()
+      .replace(/[^a-z0-9]/g, '');
+  // Registry names are plugin callback names (PluginTimer); rows carry the
+  // loader names (plugin-timer). Normalized comparison bridges the two — a
+  // heuristic, so runtime-only names are reported, never treated as errors.
+  const runtimeByNorm = new Map();
+  for (const p of snap.plugins) {
+    if (p.name) runtimeByNorm.set(norm(p.name), p.name);
+  }
+  const matchedNorms = new Set();
+  const matched = [];
+  const declaredNotRunning = [];
+  const disabledButRunning = [];
+  for (const row of rows.values()) {
+    const candidates = [norm(row.name), norm(row.id)].filter(Boolean);
+    const key = candidates.find((k) => runtimeByNorm.has(k)) ?? null;
+    if (key) matchedNorms.add(key);
+    const entry = { id: row.id, name: row.name ?? null };
+    if (row.disabled === true) {
+      if (key) disabledButRunning.push({ ...entry, runtime: runtimeByNorm.get(key) });
+    } else if (key) {
+      matched.push({ ...entry, runtime: runtimeByNorm.get(key) });
+    } else {
+      declaredNotRunning.push(entry);
+    }
+  }
+  const undeclaredRuntime = [...runtimeByNorm.entries()]
+    .filter(([k]) => !matchedNorms.has(k))
+    .map(([, name]) => name)
+    .sort();
+  const capturedMs = Date.parse(snap.capturedAt ?? '');
+  const stale =
+    staticMtimeMs != null && Number.isFinite(capturedMs) ? staticMtimeMs > capturedMs : null;
+  return {
+    schema: 'dsh-xray/verify@1',
+    capturedAt: snap.capturedAt ?? null,
+    stale,
+    matched,
+    declaredNotRunning,
+    disabledButRunning,
+    undeclaredRuntime,
+    unsatisfied: serviceGraph(snap).unsatisfied,
+  };
 }
 
 module.exports = {
@@ -424,4 +516,5 @@ module.exports = {
   contextCost,
   skillCost,
   requestLedger,
+  verify,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-xray",
-  "version": "0.10.2",
+  "version": "0.11.0",
   "description": "X-ray for your DeepSeek Harness — diagnostics for what's actually loaded, why, and what it costs: per-plugin context-tax attribution, per-request token ledger, skill catalog pricing, dependency cascades.",
   "repository": {
     "type": "git",
@@ -48,7 +48,7 @@
     "dependency-graph",
     "observability",
     "audit",
-    "security-scan",
+    "capability-scan",
     "token-cost",
     "lockfile",
     "troubleshooting",