@shidesheng0218/dsh-plugin-lint 0.1.0 → 0.4.0

package/src/mask.js

@@ -1,156 +1 @@
-/**
- * Comment- and string-aware scanner.
- *
- * Rules must never match text inside a comment (real plugins document the very
- * patterns we look for, e.g. "this listener returns next()"). Two views:
- *
- *   masked     comments blanked, string literals INTACT — for matching quoted
- *              event names and reading literal values with exact line numbers.
- *   structural masked AND string interiors blanked — for brace-depth analysis.
- */
-
-const BACKTICK = '\u0060';
-
-/** @returns {{ masked: string, structural: string, strings: Array<{value:string,start:number,end:number,line:number}>, lineStarts: number[] }} */
-export function maskSource(text) {
-  const maskedChars = text.split('');
-  const structuralChars = text.slice().split('');
-  const strings = [];
-  const lineStarts = [0];
-  for (let k = 0; k < text.length; k++) if (text[k] === '\n') lineStarts.push(k + 1);
-
-  const NL = '\n';
-  const SP = ' ';
-  const blank = (from, to, chars) => {
-    for (let k = from; k < to; k++) if (chars[k] !== NL) chars[k] = SP;
-  };
-  // A '/' starts a regex only where a value may begin; otherwise it is division.
-  const regexAllowed = (prev) => prev === '' || '(,=:[!&|?{};+-*%<>~^'.indexOf(prev) >= 0;
-  const lastMeaningful = (idx) => {
-    for (let k = idx - 1; k >= 0; k--) {
-      const c = maskedChars[k];
-      if (c === SP || c === NL || c === '\t') continue;
-      return c;
-    }
-    return '';
-  };
-
-  let i = 0;
-  const n = text.length;
-  while (i < n) {
-    const c = text[i];
-    const next = text[i + 1];
-
-    if (c === '/' && next === '/') {
-      const from = i;
-      while (i < n && text[i] !== NL) i++;
-      blank(from, i, maskedChars);
-      blank(from, i, structuralChars);
-      continue;
-    }
-    if (c === '/' && next === '*') {
-      const from = i;
-      i += 2;
-      while (i < n && !(text[i] === '*' && text[i + 1] === '/')) i++;
-      i = Math.min(n, i + 2);
-      blank(from, i, maskedChars);
-      blank(from, i, structuralChars);
-      continue;
-    }
-
-    // The literal delimiter itself, not a boolean: the closing delimiter must
-    // compare equal to it.
-    const quote = c === '"' ? '"' : c === "'" ? "'" : c === BACKTICK ? BACKTICK : undefined;
-    if (quote !== undefined) {
-      const from = i;
-      i += 1;
-      const contentFrom = i;
-      while (i < n) {
-        if (text[i] === '\\') { i += 2; continue; }
-        if (text[i] === quote) break;
-        if (text[i] === NL && quote !== BACKTICK) break; // unterminated literal
-        i += 1;
-      }
-      const contentTo = Math.min(i, n);
-      const end = Math.min(i + 1, n);
-      strings.push({ value: text.slice(contentFrom, contentTo), start: from, end, line: lineOfIndex(lineStarts, from) });
-      blank(contentFrom, contentTo, structuralChars);
-      i = end;
-      continue;
-    }
-
-    if (c === '/' && regexAllowed(lastMeaningful(i))) {
-      i += 1;
-      let inClass = false;
-      while (i < n) {
-        if (text[i] === '\\') { i += 2; continue; }
-        if (text[i] === '[') inClass = true;
-        else if (text[i] === ']') inClass = false;
-        else if (text[i] === '/' && !inClass) { i += 1; break; }
-        else if (text[i] === NL) break;
-        i += 1;
-      }
-      continue;
-    }
-    i += 1;
-  }
-  return { masked: maskedChars.join(''), structural: structuralChars.join(''), strings, lineStarts };
-}
-
-export function lineOfIndex(lineStarts, index) {
-  let lo = 0;
-  let hi = lineStarts.length - 1;
-  while (lo < hi) {
-    const mid = (lo + hi + 1) >> 1;
-    if (lineStarts[mid] <= index) lo = mid;
-    else hi = mid - 1;
-  }
-  return lo + 1;
-}
-
-/** The first string literal starting at or after \`from\` within \`window\` characters. */
-export function stringAfter(strings, from, window) {
-  for (const s of strings) {
-    if (s.start >= from) return s.start - from <= window ? s : undefined;
-  }
-  return undefined;
-}
-
-/** Literal types passed to session.append("type", data) call sites. */
-export function appendCallSites(masked, strings) {
-  const out = [];
-  const re = /\.append\(\s*/g;
-  let m;
-  while ((m = re.exec(masked)) !== null) {
-    const s = stringAfter(strings, m.index + m[0].length, 32);
-    if (s) out.push({ type: s.value, index: s.start, line: s.line });
-  }
-  return out;
-}
-
-/** The balanced brace block that starts at or after `index`, on the structural view. */
-export function blockAfter(structural, index) {
-  const open = structural.indexOf('{', index);
-  if (open < 0) return undefined;
-  let depth = 0;
-  for (let i = open; i < structural.length; i++) {
-    const c = structural[i];
-    if (c === '{') depth += 1;
-    else if (c === '}') {
-      depth -= 1;
-      if (depth === 0) return { start: open, end: i + 1, body: structural.slice(open + 1, i) };
-    }
-  }
-  return undefined;
-}
-
-/** Brace depth at a character index, computed on the structural view. */
-export function braceDepthAt(structural, index) {
-  let depth = 0;
-  for (let k = 0; k < index && k < structural.length; k++) {
-    const c = structural[k];
-    if (c === '{' || c === '(' || c === '[') depth += 1;
-    else if (c === '}' || c === ')' || c === ']') depth -= 1;
-  }
-  return depth;
-}
+export * from './core/mask.js';

package/src/matrix/cache.js

@@ -0,0 +1,19 @@
+import { stableStringify, sha256 } from '../shared/hash.js';
+import { ToolError } from '../shared/errors.js';
+import { CELL_SCHEMA_VERSION } from '../shared/version.js';
+
+export function cacheKeyFor({ artifact, dshVersion, composition, probeVersion, schemaVersion = CELL_SCHEMA_VERSION }) {
+  const integrityOrSourceDigest = artifact?.integrity ?? artifact?.sourceDigest;
+  if (!artifact?.name || !artifact?.resolvedVersion || !integrityOrSourceDigest || !dshVersion || !composition || !probeVersion) {
+    throw new ToolError('CACHE_INPUT_INVALID', 'A reproducible cache key needs artifact, DSH, composition, probe, and integrity inputs.');
+  }
+  return sha256(stableStringify({
+    name: artifact.name,
+    resolvedVersion: artifact.resolvedVersion,
+    integrityOrSourceDigest,
+    dshVersion,
+    composition,
+    probeVersion,
+    cellSchemaVersion: schemaVersion,
+  }));
+}

package/src/matrix/cell.js

@@ -0,0 +1,79 @@
+import { CELL_SCHEMA_VERSION, PROBE_VERSION } from '../shared/version.js';
+import { ToolError } from '../shared/errors.js';
+import { cacheKeyFor } from './cache.js';
+import { validateCell } from './schema.js';
+
+export function createCell(input) {
+  const { artifact, dsh, observation } = input;
+  const composition = input.composition || dsh.composition || observation.composition;
+  const probeVersion = input.probeVersion || PROBE_VERSION;
+  const cacheKey = cacheKeyFor({ artifact, dshVersion: dsh.version, composition, probeVersion });
+  const cell = {
+    schemaVersion: CELL_SCHEMA_VERSION,
+    cacheKey,
+    plugin: {
+      name: artifact.name,
+      requestedVersion: artifact.requestedVersion,
+      resolvedVersion: artifact.resolvedVersion,
+      loadedVersion: observation.loadedVersion,
+      integrity: artifact.integrity,
+      local: artifact.local === true,
+      sourceDigest: artifact.sourceDigest,
+      path: artifact.path,
+      tarballUrl: artifact.tarballUrl,
+    },
+    dsh: { version: dsh.version, source: dsh.source || dsh.kind || 'npm', composition },
+    probe: {
+      version: probeVersion,
+      isolation: input.isolation || observation.isolation || 'unknown',
+      host: input.host || observation.host || { os: process.platform + '-' + process.arch, node: process.version },
+    },
+    run: {
+      outcome: observation.outcome,
+      at: input.at || new Date().toISOString(),
+      durationMs: observation.durationMs,
+      trust: input.trust || 'self-reported',
+    },
+    reproduce: observation.reproduce,
+  };
+  if (input.verification) cell.run.verification = input.verification;
+  if (input.dispute) cell.run.dispute = input.dispute;
+  if (observation.outcome === 'error') {
+    // Infrastructure errors can arrive with a numeric exec code; the cell
+    // schema requires non-empty strings.
+    cell.run.error = {
+      code: String(observation.error?.code || 'PROBE_FAILED'),
+      message: String(observation.error?.message || 'The probe could not complete.'),
+    };
+  } else {
+    cell.result = observation.result;
+    cell.evidence = { note: observation.note || '', outputSha256: observation.outputSha256 };
+  }
+  const validation = validateCell(cell);
+  if (!validation.ok) throw new ToolError('CELL_INVALID', validation.errors.join('; '));
+  return cell;
+}
+
+export function selectCells(cells, { dshVersion, composition } = {}) {
+  const selected = cells.filter((cell) => dshVersion === undefined || cell.dsh.version === dshVersion);
+  if (composition !== undefined) {
+    const exact = selected.filter((cell) => cell.dsh.composition === composition);
+    return { kind: exact.length > 0 ? 'cells' : 'untested', cells: exact };
+  }
+  if (selected.length === 0) return { kind: 'untested', cells: [] };
+  const compositions = new Set(selected.map((cell) => cell.dsh.composition));
+  return { kind: compositions.size > 1 ? 'mixed' : 'unknown', cells: selected };
+}
+
+export function recommendationEligible(cell, { now = Date.now(), maxAgeDays = 30 } = {}) {
+  if (cell?.recommendationEligible === false || cell?.migration) return false;
+  if (!validateCell(cell).ok) return false;
+  if (cell.plugin.local !== false || typeof cell.plugin.integrity !== 'string') return false;
+  if (cell.plugin.resolvedVersion !== cell.plugin.loadedVersion) return false;
+  if (cell.run.outcome !== 'completed' || cell.run.trust !== 'verified') return false;
+  if (!cell.run.verification || cell.run.verification.probeVersion !== cell.probe.version) return false;
+  if (cell.result.status !== 'active') return false;
+  const at = Date.parse(cell.run.at);
+  const age = now - at;
+  return Number.isFinite(at) && age >= 0 && age <= maxAgeDays * 24 * 60 * 60 * 1000;
+}

package/src/matrix/cells.js

@@ -0,0 +1,58 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { ToolError } from '../shared/errors.js';
+import { readCellAny } from './migrate.js';
+import { validateCell } from './schema.js';
+
+function segment(value) {
+  return String(value).replace(/^@/, '').replace(/[^A-Za-z0-9._-]/g, '_');
+}
+
+export function cellFilePath(outDir, cell) {
+  return join(
+    outDir,
+    segment(cell.plugin.name),
+    segment(cell.plugin.resolvedVersion),
+    `${segment(cell.dsh.version)}+${segment(cell.dsh.composition)}.${cell.cacheKey.slice(0, 16)}.json`,
+  );
+}
+
+export function writeCell(outDir, cell) {
+  if (cell.schemaVersion !== 2) throw new ToolError('CELL_SCHEMA_UNSUPPORTED', 'Only v2 cells can be written by the matrix runner.');
+  if (cell.run.outcome === 'completed') {
+    const validation = validateCell(cell);
+    if (!validation.ok) throw new ToolError('CELL_INVALID', validation.errors.join('; '));
+  }
+  const path = cellFilePath(outDir, cell);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(cell, null, 2) + '\n');
+  return path;
+}
+
+export function readCells(dir) {
+  if (!existsSync(dir)) throw new ToolError('CELL_READ_FAILED', `The cells directory does not exist: ${dir}`);
+  const results = [];
+  function walk(current) {
+    for (const entry of readdirSync(current, { withFileTypes: true })) {
+      const path = join(current, entry.name);
+      if (entry.isDirectory()) {
+        walk(path);
+        continue;
+      }
+      if (!entry.isFile() || !entry.name.endsWith('.json')) continue;
+      try {
+        const value = JSON.parse(readFileSync(path, 'utf8'));
+        if (entry.name === 'run-manifest.json') {
+          results.push({ ok: true, path, kind: 'run-manifest', manifest: value });
+          continue;
+        }
+        const { kind, cell } = readCellAny(value);
+        results.push({ ok: true, path, kind, cell });
+      } catch (error) {
+        results.push({ ok: false, path, error: { code: error.code || 'CELL_INVALID', message: error.message } });
+      }
+    }
+  }
+  walk(dir);
+  return results.sort((a, b) => a.path.localeCompare(b.path));
+}

package/src/matrix/conflicts.js

@@ -0,0 +1,210 @@
+import { execFile } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { detectConflicts } from '../experimental/conflicts.js';
+import { loadPackage } from '../core/load.js';
+import { ToolError } from '../shared/errors.js';
+import { downloadArtifact, resolveArtifact } from '../probe/artifact-resolver.js';
+import { createProbeEnvironment } from '../probe/environment.js';
+import { resolveDsh, safeEnv } from '../probe/dsh-adapter.js';
+import { readInstalledArtifact } from '../probe/installed-artifact.js';
+import { classify } from '../probe/classify.js';
+import { parseInactive, payloadOf } from '../probe/probe.js';
+
+const execFileAsync = promisify(execFile);
+
+function safeName(value) {
+  return String(value).replace(/^@/, '').replace(/[^A-Za-z0-9._-]/g, '_');
+}
+
+function artifactFromCell(cell) {
+  return {
+    name: cell.plugin.name,
+    requestedVersion: cell.plugin.resolvedVersion,
+    resolvedVersion: cell.plugin.resolvedVersion,
+    integrity: cell.plugin.integrity,
+    sourceDigest: cell.plugin.sourceDigest,
+    local: cell.plugin.local,
+    path: cell.plugin.path,
+    tarballUrl: cell.plugin.tarballUrl,
+    installTarget: `${cell.plugin.name}@${cell.plugin.resolvedVersion}`,
+  };
+}
+
+function uniqueArtifacts(cells) {
+  const artifacts = new Map();
+  for (const cell of cells) {
+    const artifact = artifactFromCell(cell);
+    const key = `${artifact.name}@${artifact.resolvedVersion}@${artifact.integrity || artifact.sourceDigest}`;
+    if (!artifacts.has(key)) artifacts.set(key, { artifact, cells: [] });
+    artifacts.get(key).cells.push(cell);
+  }
+  return [...artifacts.values()];
+}
+
+function assertSafeTarEntry(path) {
+  if (path.startsWith('/') || path === '..' || path.startsWith('../') || path.includes('/../') || path.includes('\0')) {
+    throw new ToolError('ARTIFACT_SPEC_UNSUPPORTED', 'The artifact contains an unsafe archive path.');
+  }
+}
+
+function assertNoSymlinks(dir) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isSymbolicLink()) throw new ToolError('ARTIFACT_SPEC_UNSUPPORTED', 'The artifact contains a symbolic link.');
+    if (entry.isDirectory()) assertNoSymlinks(join(dir, entry.name));
+  }
+}
+
+export function createPinnedMaterializer({ cacheRoot }) {
+  return async (artifact) => {
+    if (artifact.local && artifact.path) return artifact.path;
+    const pinned = await resolveArtifact({ name: artifact.name, version: artifact.resolvedVersion, integrity: artifact.integrity });
+    const downloaded = await downloadArtifact(pinned);
+    const destination = join(cacheRoot, 'pkgs', safeName(artifact.name), safeName(artifact.resolvedVersion));
+    if (existsSync(join(destination, 'package.json'))) return destination;
+    mkdirSync(cacheRoot, { recursive: true });
+    const listing = await execFileAsync('tar', ['-tzf', downloaded.tarballPath], { env: safeEnv(), maxBuffer: 16 * 1024 * 1024 });
+    for (const path of listing.stdout.split('\n').filter(Boolean)) assertSafeTarEntry(path);
+    const temporary = mkdtempSync(join(cacheRoot, 'extract-'));
+    try {
+      await execFileAsync('tar', ['-xzf', downloaded.tarballPath, '-C', temporary, '--strip-components=1', '--no-same-owner', '--no-same-permissions'], { env: safeEnv(), maxBuffer: 16 * 1024 * 1024 });
+      assertNoSymlinks(temporary);
+      if (!existsSync(join(temporary, 'package.json'))) throw new ToolError('ARTIFACT_MISSING', 'The extracted artifact has no package.json.');
+      rmSync(destination, { recursive: true, force: true });
+      mkdirSync(join(destination, '..'), { recursive: true });
+      renameSync(temporary, destination);
+    } catch (error) {
+      rmSync(temporary, { recursive: true, force: true });
+      throw error;
+    }
+    return destination;
+  };
+}
+
+async function verifyPinnedCombo({ artifacts, directories, dshVersion }) {
+  const environment = await createProbeEnvironment({ backend: 'auto' });
+  let stub;
+  try {
+    const dsh = await resolveDsh(dshVersion, environment.dshDir, { environment });
+    stub = await environment.startStub();
+    const patchPath = environment.isolation === 'docker' ? '/profile/probe-patch.yml' : join(environment.profileDir, 'probe-patch.yml');
+    writeFileSync(join(environment.profileDir, 'probe-patch.yml'), [
+      '- id: llm-deepseek',
+      '  name: "@deepseek-ai/dsh-llm-deepseek-api-key"',
+      '  config:',
+      `    baseURL: ${stub.baseURL}`,
+      '    apiKeyEnv: PROBE_API_KEY',
+      '',
+    ].join('\n'));
+    const bootInput = {
+      dsh,
+      args: ['--profile', 'headless', '--patch', patchPath, 'probe'],
+      env: { PROBE_API_KEY: 'probe' },
+      network: stub.network,
+    };
+    await environment.boot(bootInput);
+    await stub.sync();
+    const before = payloadOf(stub.seen.splice(0));
+    for (const artifact of artifacts) {
+      const directory = directories.get(artifact.name);
+      const materialized = await environment.materialize({ ...artifact, local: true, path: directory });
+      await environment.install({ dsh, target: materialized, profile: 'headless', env: { PROBE_API_KEY: 'probe' } });
+      const installed = readInstalledArtifact(join(environment.profileDir, 'profiles', 'headless'), artifact.name);
+      if (installed.version !== artifact.resolvedVersion) throw new ToolError('VERSION_MISMATCH', 'A combination installed a different artifact version.');
+    }
+    const booted = await environment.boot(bootInput);
+    await stub.sync();
+    const after = payloadOf(stub.seen.splice(0));
+    const entries = parseInactive(booted.out);
+    const beforeNames = new Set(before?.tools?.map((tool) => tool.name) || []);
+    const afterNames = new Set(after?.tools?.map((tool) => tool.name) || []);
+    return {
+      status: classify(booted.out, entries, Boolean(after)),
+      trust: 'self-reported',
+      entries,
+      dropped: [...beforeNames].filter((name) => !afterNames.has(name)),
+      beforeCount: beforeNames.size,
+      afterCount: afterNames.size,
+    };
+  } finally {
+    if (stub?.server) stub.server.close();
+    await environment.destroy();
+  }
+}
+
+function candidateTools(cells) {
+  const owners = new Map();
+  for (const cell of cells) {
+    for (const tool of cell.result.tools?.added || []) {
+      if (!owners.has(tool)) owners.set(tool, new Map());
+      owners.get(tool).set(`${cell.plugin.name}@${cell.plugin.resolvedVersion}`, cell);
+    }
+  }
+  return [...owners.entries()].filter(([, byPlugin]) => byPlugin.size > 1).map(([resource, byPlugin]) => {
+    const claims = [...byPlugin.values()];
+    return {
+      resource,
+      plugins: claims.map((cell) => cell.plugin.name),
+      cells: claims,
+      status: 'candidate',
+    };
+  });
+}
+
+export async function scanConflicts({ cells, materialize, verify = false, verifyCombo = verifyPinnedCombo, limit = Number.POSITIVE_INFINITY }) {
+  const errors = [];
+  const unique = uniqueArtifacts(cells);
+  const packages = [];
+  const directories = new Map();
+  const pluginsScanned = [];
+  for (const entry of unique) {
+    try {
+      const directory = await materialize(entry.artifact);
+      directories.set(entry.artifact.name, directory);
+      packages.push(loadPackage(directory));
+      pluginsScanned.push(entry.artifact.name);
+    } catch (error) {
+      errors.push({ code: error.code || 'ARTIFACT_MATERIALIZE_FAILED', plugin: entry.artifact.name, message: error.message });
+    }
+  }
+  const staticReport = detectConflicts(packages);
+  const tools = candidateTools(cells);
+  const slots = staticReport.slots.map((entry) => ({ ...entry, status: 'candidate' }));
+  const routes = staticReport.routes.map((entry) => ({ ...entry, status: 'candidate' }));
+  const verified = { tools: [], slots: [], routes: [] };
+  if (verify) {
+    for (const [kind, candidates] of [['tools', tools], ['slots', slots], ['routes', routes]]) {
+      for (const candidate of candidates.slice(0, limit)) {
+        try {
+          const names = new Set(candidate.plugins);
+          const artifacts = unique.filter((entry) => names.has(entry.artifact.name)).map((entry) => entry.artifact);
+          const relatedCells = candidate.cells || unique.filter((entry) => names.has(entry.artifact.name)).flatMap((entry) => entry.cells);
+          const result = await verifyCombo({
+            kind,
+            candidate,
+            artifacts,
+            directories,
+            dshVersion: relatedCells[0]?.dsh.version,
+            composition: relatedCells[0]?.dsh.composition,
+          });
+          verified[kind].push({ resource: candidate.resource, plugins: candidate.plugins, ...result });
+        } catch (error) {
+          errors.push({ code: error.code || 'CONFLICT_VERIFICATION_FAILED', resource: candidate.resource, message: error.message });
+        }
+      }
+    }
+  }
+  return {
+    schemaVersion: 2,
+    generatedAt: new Date().toISOString(),
+    cells: cells.length,
+    pluginsScanned,
+    tools,
+    slots,
+    routes,
+    unknownRoutes: staticReport.unknownRoutes,
+    verified,
+    errors,
+  };
+}

package/src/matrix/export.js

@@ -0,0 +1,155 @@
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { ToolError } from '../shared/errors.js';
+import { PROBE_VERSION } from '../shared/version.js';
+import { stableStringify, sha256 } from '../shared/hash.js';
+import { readCells, writeCell } from './cells.js';
+import { buildIndex } from './index.js';
+import { buildManifest } from './manifest.js';
+import { validateCell, validateIndex, validateManifest } from './schema.js';
+import { sanitizeCellForPublish, sanitizeForPublish } from './sanitize.js';
+
+function readJson(path) {
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+function writeJson(path, value) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(value, null, 2) + '\n');
+}
+
+function filesUnder(dir) {
+  const files = [];
+  function walk(current) {
+    for (const entry of readdirSync(current, { withFileTypes: true })) {
+      const path = join(current, entry.name);
+      if (entry.isDirectory()) walk(path);
+      else if (entry.isFile()) files.push(relative(dir, path).replace(/\\/g, '/'));
+    }
+  }
+  walk(dir);
+  return files.sort();
+}
+
+function buildAggregate(index, sourceRunId) {
+  const aggregate = {
+    schemaVersion: 2,
+    generatedAt: index.generatedAt,
+    sourceRunId,
+    dshVersions: index.dshVersions,
+    plugins: index.plugins.length,
+    versions: {},
+  };
+  for (const plugin of index.plugins) {
+    for (const version of plugin.versions) {
+      for (const cell of version.cells) {
+        if (!aggregate.versions[cell.dsh]) aggregate.versions[cell.dsh] = {};
+        aggregate.versions[cell.dsh][cell.status] = (aggregate.versions[cell.dsh][cell.status] || 0) + 1;
+      }
+    }
+  }
+  return aggregate;
+}
+
+export async function exportPublicArtifact({ cellsDir, conflictsPath, outDir, runId, generatedAt = new Date().toISOString(), expectedCells }) {
+  const reads = readCells(cellsDir);
+  const invalid = reads.filter((entry) => !entry.ok);
+  if (invalid.length > 0) throw new ToolError('EXPORT_INPUT_INVALID', `Cannot read ${invalid.length} cell file(s).`);
+  if (reads.some((entry) => entry.kind === 'legacy-v1')) throw new ToolError('EXPORT_INPUT_INVALID', 'Legacy cells cannot be republished as v2 evidence.');
+  const cells = reads.filter((entry) => entry.kind === 'v2').map((entry) => sanitizeCellForPublish(entry.cell));
+  if (expectedCells !== undefined && cells.length !== expectedCells) {
+    throw new ToolError('EXPORT_CELL_COUNT_MISMATCH', `Expected ${expectedCells} cells, found ${cells.length}.`);
+  }
+  if (!runId) throw new ToolError('EXPORT_INPUT_INVALID', 'runId is required.');
+  if (!existsSync(conflictsPath)) throw new ToolError('EXPORT_INPUT_INVALID', 'The computed conflicts artifact is required.');
+  const conflicts = sanitizeForPublish(readJson(conflictsPath));
+  if (conflicts.schemaVersion !== 2) throw new ToolError('EXPORT_INPUT_INVALID', 'Conflicts must use schema v2.');
+  const index = buildIndex(cells, { generatedAt, source: { runId, conflicts } });
+  const aggregate = buildAggregate(index, runId);
+  const sourceManifest = reads.find((entry) => entry.kind === 'run-manifest')?.manifest;
+  const parent = dirname(outDir);
+  mkdirSync(parent, { recursive: true });
+  const staging = mkdtempSync(join(parent, '.export-'));
+  try {
+    for (const cell of cells) writeCell(join(staging, 'cells'), cell);
+    writeJson(join(staging, 'index', 'latest.json'), index);
+    writeJson(join(staging, 'index', 'conflicts.json'), conflicts);
+    writeJson(join(staging, 'aggregate.json'), aggregate);
+    const artifacts = filesUnder(staging).map((path) => {
+      const bytes = readFileSync(join(staging, path));
+      return { path, bytes: bytes.length, sha256: sha256(bytes) };
+    });
+    const manifest = buildManifest({
+      runId,
+      generatedAt,
+      probeVersion: PROBE_VERSION,
+      inputs: { targetMode: sourceManifest?.targetMode || 'pinned', expectedCells: expectedCells ?? cells.length, inputs: sourceManifest?.inputs || index.plugins.map((plugin) => plugin.name) },
+      artifacts,
+    });
+    manifest.targetMode = sourceManifest?.targetMode || 'pinned';
+    manifest.inputs = sourceManifest?.inputs || index.plugins.map((plugin) => plugin.name);
+    manifest.cellCount = cells.length;
+    if (expectedCells !== undefined) manifest.expectedCells = expectedCells;
+    writeJson(join(staging, 'manifest.json'), manifest);
+    const verification = await verifyPublicArtifact({ dir: staging });
+    if (!verification.ok) throw new ToolError('EXPORT_INPUT_INVALID', verification.errors.join('; '));
+    const backup = `${outDir}.backup-${Date.now()}`;
+    if (existsSync(outDir)) renameSync(outDir, backup);
+    try {
+      renameSync(staging, outDir);
+      rmSync(backup, { recursive: true, force: true });
+    } catch (error) {
+      if (existsSync(backup)) renameSync(backup, outDir);
+      throw error;
+    }
+    return { manifest, filesWritten: artifacts.length + 1, cells: cells.length };
+  } catch (error) {
+    rmSync(staging, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+export async function verifyPublicArtifact({ dir }) {
+  const errors = [];
+  try {
+    const manifest = readJson(join(dir, 'manifest.json'));
+    const manifestValidation = validateManifest(manifest);
+    if (!manifestValidation.ok) errors.push(...manifestValidation.errors);
+    const declared = new Set(manifest.artifacts.map((artifact) => artifact.path));
+    const actual = new Set(filesUnder(dir).filter((path) => path !== 'manifest.json'));
+    for (const path of declared) {
+      if (!actual.has(path)) {
+        errors.push(`artifact is missing: ${path}`);
+        continue;
+      }
+      const expected = manifest.artifacts.find((artifact) => artifact.path === path);
+      const bytes = readFileSync(join(dir, path));
+      if (bytes.length !== expected.bytes || sha256(bytes) !== expected.sha256) errors.push(`artifact hash mismatch: ${path}`);
+    }
+    for (const path of actual) if (!declared.has(path)) errors.push(`undeclared artifact: ${path}`);
+
+    const index = readJson(join(dir, 'index', 'latest.json'));
+    const indexValidation = validateIndex(index);
+    if (!indexValidation.ok) errors.push(...indexValidation.errors);
+    const conflicts = readJson(join(dir, 'index', 'conflicts.json'));
+    if (conflicts.schemaVersion !== 2) errors.push('conflicts.schemaVersion must be 2');
+    const reads = readCells(join(dir, 'cells'));
+    const invalid = reads.filter((entry) => !entry.ok);
+    if (invalid.length > 0) errors.push(`${invalid.length} damaged public cell(s)`);
+    const cells = reads.filter((entry) => entry.kind === 'v2').map((entry) => entry.cell);
+    for (const cell of cells) {
+      const validation = validateCell(cell);
+      if (!validation.ok) errors.push(...validation.errors);
+    }
+    if (manifest.cellCount !== cells.length) errors.push(`cell count mismatch: manifest ${manifest.cellCount}, actual ${cells.length}`);
+    if (manifest.expectedCells !== undefined && manifest.expectedCells !== cells.length) errors.push(`expected cell count mismatch: ${manifest.expectedCells} vs ${cells.length}`);
+    const expectedIndex = buildIndex(cells, { generatedAt: index.generatedAt, source: index.source });
+    if (stableStringify(expectedIndex) !== stableStringify(index)) errors.push('index does not match the public cells');
+    const expectedAggregate = buildAggregate(index, manifest.runId);
+    const aggregate = readJson(join(dir, 'aggregate.json'));
+    if (stableStringify(expectedAggregate) !== stableStringify(aggregate)) errors.push('aggregate does not match the index');
+  } catch (error) {
+    errors.push(error.message);
+  }
+  return { ok: errors.length === 0, errors };
+}