@shidesheng0218/dsh-plugin-lint 0.0.0-stage → 0.4.0

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 };
+}

package/src/matrix/index.js

@@ -0,0 +1,71 @@
+import { ToolError } from '../shared/errors.js';
+import { validateCell, validateIndex } from './schema.js';
+
+/**
+ * JSON has no `undefined`. A cell that was probed without the tool inventory or
+ * without a system prompt would otherwise put `undefined` into the index, and
+ * the canonical hash (stableStringify) throws on it — so the artifact could be
+ * written but never verified. Drop those keys instead of inventing a value.
+ */
+function compact(value) {
+  if (Array.isArray(value)) return value.map(compact);
+  if (value && typeof value === 'object') {
+    const out = {};
+    for (const [key, entry] of Object.entries(value)) {
+      if (entry !== undefined) out[key] = compact(entry);
+    }
+    return out;
+  }
+  return value;
+}
+
+export function buildIndex(cells, { generatedAt = new Date().toISOString(), source = {} } = {}) {
+  const grouped = new Map();
+  const dshVersions = new Set();
+  for (const cell of cells) {
+    if (cell.run?.outcome !== 'completed' || !validateCell(cell).ok) {
+      throw new ToolError('INDEX_INPUT_INVALID', 'Every input cell must be a complete, valid v2 observation.');
+    }
+    const name = cell.plugin.name;
+    const version = cell.plugin.resolvedVersion;
+    if (!grouped.has(name)) grouped.set(name, new Map());
+    const versions = grouped.get(name);
+    if (!versions.has(version)) versions.set(version, []);
+    versions.get(version).push(cell);
+    dshVersions.add(cell.dsh.version);
+  }
+  const plugins = [...grouped.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([name, versions]) => ({
+    name,
+    versions: [...versions.entries()].sort(([a], [b]) => a.localeCompare(b, undefined, { numeric: true })).map(([version, entries]) => ({
+      version,
+      integrity: entries[0].plugin.integrity,
+      cells: entries.map((cell) => ({
+        cacheKey: cell.cacheKey,
+        dsh: cell.dsh.version,
+        composition: cell.dsh.composition,
+        status: cell.result.status,
+        trust: cell.run.trust,
+        at: cell.run.at,
+        note: cell.evidence?.note,
+        awaitedServices: cell.result.awaitedServices,
+        toolsAdded: cell.result.tools?.added || [],
+        audit: cell.result.audit,
+        systemPromptChars: cell.result.systemPrompt?.chars,
+        clientHalf: cell.result.clientHalf,
+        reproduce: cell.reproduce.command,
+      })),
+    })),
+  }));
+  const index = {
+    schemaVersion: 2,
+    generatedAt,
+    source,
+    dshVersions: [...dshVersions].sort((a, b) => a.localeCompare(b, undefined, { numeric: true })),
+    plugins,
+    conflicts: source.conflicts || { tools: [], slots: [], routes: [] },
+  };
+  const clean = compact(index);
+  const validation = validateIndex(clean);
+  if (!validation.ok) throw new ToolError('INDEX_INPUT_INVALID', validation.errors.join('; '));
+  return clean;
+}

package/src/matrix/manifest.js

@@ -0,0 +1,17 @@
+import { stableStringify, sha256 } from '../shared/hash.js';
+import { ToolError } from '../shared/errors.js';
+import { validateManifest } from './schema.js';
+
+export function buildManifest({ runId, generatedAt = new Date().toISOString(), probeVersion, inputs, artifacts }) {
+  const manifest = {
+    schemaVersion: 2,
+    runId,
+    generatedAt,
+    probeVersion,
+    inputsSha256: sha256(stableStringify(inputs)),
+    artifacts: [...artifacts].sort((a, b) => a.path.localeCompare(b.path)),
+  };
+  const validation = validateManifest(manifest);
+  if (!validation.ok) throw new ToolError('MANIFEST_INVALID', validation.errors.join('; '));
+  return manifest;
+}

package/src/matrix/migrate.js

@@ -0,0 +1,41 @@
+import { ToolError } from '../shared/errors.js';
+import { TRUST } from '../shared/status.js';
+import { validateCell } from './schema.js';
+
+export function migrateCellV1(value) {
+  if (!value || value.schemaVersion !== 1 || typeof value.plugin?.name !== 'string' || typeof value.plugin?.version !== 'string' || typeof value.dsh?.version !== 'string' || typeof value.result?.status !== 'string') {
+    throw new ToolError('CELL_INVALID', 'The legacy cell is missing required v1 fields.');
+  }
+  const cell = structuredClone(value);
+  const originalTrust = cell.run?.trust;
+  cell.run = { ...(cell.run || {}), outcome: cell.run?.outcome || 'completed', trust: TRUST.LEGACY_UNPINNED };
+  cell.plugin = {
+    ...cell.plugin,
+    requestedVersion: cell.plugin.requestedVersion || 'legacy',
+    resolvedVersion: cell.plugin.version,
+  };
+  delete cell.plugin.loadedVersion;
+  cell.dsh = {
+    ...cell.dsh,
+    composition: cell.dsh.composition || cell.result.composition || cell.dsh.profile || cell.probe?.mode || 'unknown',
+  };
+  cell.probe = {
+    ...(cell.probe || {}),
+    version: cell.probe?.version || 'legacy',
+    isolation: cell.probe?.isolation || 'unknown',
+    host: cell.probe?.host || { os: cell.run.os || 'unknown', node: cell.run.node || 'unknown' },
+  };
+  cell.recommendationEligible = false;
+  cell.migration = { originalTrust };
+  return cell;
+}
+
+export function readCellAny(value) {
+  if (value?.schemaVersion === 2) {
+    const validation = validateCell(value);
+    if (!validation.ok) throw new ToolError('CELL_INVALID', validation.errors.join('; '));
+    return { kind: 'v2', cell: value };
+  }
+  if (value?.schemaVersion === 1) return { kind: 'legacy-v1', cell: migrateCellV1(value) };
+  throw new ToolError('CELL_SCHEMA_UNSUPPORTED', 'Only matrix cell schema v1 and v2 are supported.');
+}