@openclaw/plugin-inspector 0.0.0 → 0.1.0

package/src/config.js

@@ -0,0 +1,182 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+export const npmPackagePayloadDir = ".crabpot-package";
+export const defaultPluginRootConfigFiles = ["plugin-inspector.config.json", ".plugin-inspector.json"];
+
+export async function loadInspectorConfig(configPath, options = {}) {
+  if (!configPath) {
+    throw new Error("--config is required");
+  }
+  const resolvedPath = path.resolve(options.cwd ?? process.cwd(), configPath);
+  const config = JSON.parse(await readFile(resolvedPath, "utf8"));
+  const rootDir = path.resolve(options.cwd ?? process.cwd(), options.rootDir ?? path.dirname(resolvedPath));
+  const normalizedConfig = await normalizeInspectorConfig(config, { rootDir });
+  validateInspectorConfig(normalizedConfig);
+  return {
+    ...normalizedConfig,
+    rootDir,
+    configPath: resolvedPath,
+  };
+}
+
+export async function loadPluginRootConfig(configPath = null, options = {}) {
+  const rootDir = path.resolve(options.cwd ?? process.cwd());
+  const resolvedPath = configPath ? path.resolve(rootDir, configPath) : findPluginRootConfigPath(rootDir);
+  if (!resolvedPath && !existsSync(path.join(rootDir, "package.json")) && !existsSync(path.join(rootDir, "openclaw.plugin.json"))) {
+    throw new Error("run from a plugin root with package.json/openclaw.plugin.json, or pass --config");
+  }
+  const config = resolvedPath ? JSON.parse(await readFile(resolvedPath, "utf8")) : { version: 1 };
+  const normalizedConfig = await normalizePluginRootConfig(config, { rootDir });
+  validateInspectorConfig(normalizedConfig);
+  return {
+    ...normalizedConfig,
+    rootDir,
+    configPath: resolvedPath,
+  };
+}
+
+export function validateInspectorConfig(config) {
+  const errors = [];
+
+  if (config.version !== 1) {
+    errors.push("config.version must be 1");
+  }
+
+  if (!config.submoduleRoot || typeof config.submoduleRoot !== "string") {
+    errors.push("config.submoduleRoot must be set");
+  }
+
+  if (!Array.isArray(config.fixtures) || config.fixtures.length === 0) {
+    errors.push("config.fixtures must be a non-empty array");
+  }
+
+  const ids = new Set();
+  const paths = new Set();
+  for (const fixture of config.fixtures ?? []) {
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(fixture.id ?? "")) {
+      errors.push(`invalid fixture id: ${fixture.id}`);
+    }
+    if (ids.has(fixture.id)) {
+      errors.push(`duplicate fixture id: ${fixture.id}`);
+    }
+    ids.add(fixture.id);
+
+    if (typeof fixture.path !== "string" || fixture.path.length === 0) {
+      errors.push(`${fixture.id}: path must be set`);
+    }
+    if (paths.has(fixture.path)) {
+      errors.push(`duplicate fixture path: ${fixture.path}`);
+    }
+    paths.add(fixture.path);
+
+    const hasRepo = typeof fixture.repo === "string";
+    const hasPackage = fixture.package && typeof fixture.package === "object";
+    if (hasRepo === hasPackage) {
+      errors.push(`${fixture.id}: fixture must declare exactly one of repo or package`);
+    }
+    if (!["high", "medium", "low"].includes(fixture.priority)) {
+      errors.push(`${fixture.id}: priority must be high, medium, or low`);
+    }
+    if (!Array.isArray(fixture.seams) || fixture.seams.length === 0) {
+      errors.push(`${fixture.id}: seams must be non-empty`);
+    }
+    for (const key of ["hooks", "registrations", "manifestContracts"]) {
+      const values = fixture.expect?.[key];
+      if (values !== undefined && (!Array.isArray(values) || values.length === 0)) {
+        errors.push(`${fixture.id}: expect.${key} must be a non-empty array when present`);
+      }
+    }
+  }
+
+  if (errors.length > 0) {
+    throw new Error(errors.join("\n"));
+  }
+}
+
+export function fixtureCheckoutPath(config, fixture) {
+  return path.resolve(config.rootDir ?? process.cwd(), fixture.path);
+}
+
+export function fixtureSourceRoot(config, fixture) {
+  const checkoutPath = fixtureCheckoutPath(config, fixture);
+  if (fixture.subdir) {
+    return path.join(checkoutPath, fixture.subdir);
+  }
+  if (fixture.package) {
+    return path.join(checkoutPath, npmPackagePayloadDir);
+  }
+  return checkoutPath;
+}
+
+export async function normalizePluginRootConfig(config, options = {}) {
+  const rootDir = path.resolve(options.rootDir ?? process.cwd());
+  const plugin = config.plugin ?? {};
+  const packageJson = await readJsonIfExists(path.join(rootDir, "package.json"));
+  const pluginManifest = await readJsonIfExists(path.join(rootDir, "openclaw.plugin.json"));
+  const sourceRoot = plugin.sourceRoot ?? config.sourceRoot ?? ".";
+  const fixture = {
+    id: plugin.id ?? pluginManifest?.id ?? packageId(packageJson?.name) ?? "plugin",
+    name: plugin.name ?? pluginManifest?.name ?? packageJson?.name ?? "Plugin",
+    path: ".",
+    repo: "local",
+    priority: plugin.priority ?? config.priority ?? "high",
+    seams: plugin.seams ?? config.seams ?? inferPluginSeams(pluginManifest, packageJson),
+    why: plugin.why ?? config.why ?? "local OpenClaw plugin root",
+    expect: plugin.expect ?? config.expect,
+  };
+
+  if (sourceRoot !== ".") {
+    fixture.subdir = sourceRoot;
+  }
+
+  return {
+    version: 1,
+    submoduleRoot: ".",
+    openclaw: config.openclaw,
+    fixtures: [fixture],
+  };
+}
+
+export async function normalizeInspectorConfig(config, options = {}) {
+  if (Array.isArray(config.fixtures)) {
+    return config;
+  }
+  return normalizePluginRootConfig(config, options);
+}
+
+function findPluginRootConfigPath(rootDir) {
+  return defaultPluginRootConfigFiles.map((file) => path.join(rootDir, file)).find(existsSync) ?? null;
+}
+
+async function readJsonIfExists(filePath) {
+  if (!existsSync(filePath)) {
+    return null;
+  }
+  return JSON.parse(await readFile(filePath, "utf8"));
+}
+
+function packageId(packageName) {
+  if (!packageName) {
+    return null;
+  }
+  return packageName
+    .split("/")
+    .pop()
+    .replace(/^openclaw-/, "")
+    .replace(/[^a-zA-Z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .toLowerCase();
+}
+
+function inferPluginSeams(pluginManifest, packageJson) {
+  const contracts = Object.keys(pluginManifest?.contracts ?? {});
+  if (contracts.includes("tools")) {
+    return ["dynamic-tool"];
+  }
+  if (packageJson?.openclaw?.extensions || packageJson?.openclaw?.runtimeExtensions) {
+    return ["plugin-runtime"];
+  }
+  return ["plugin-metadata"];
+}

package/src/contract-capture.js

@@ -0,0 +1,288 @@
+import { renderPaddedMarkdownTable, writeJsonMarkdownArtifacts } from "./artifacts.js";
+import { slugForArtifact } from "./path-utils.js";
+import {
+  defaultSyntheticHookContexts,
+  defaultSyntheticHookEvents,
+  defaultSyntheticRegistrationArguments,
+} from "./synthetic-probes.js";
+
+export const defaultRegistrationAssertions = {
+  defineChannelPluginEntry: ["channel id is stable", "setup/config schema can be read", "message envelope metadata is preserved"],
+  definePluginEntry: ["entrypoint register function is callable", "entrypoint metadata is preserved"],
+  registerChannel: ["channel id is stable", "inbound/outbound envelope shape is captured", "sender metadata is preserved"],
+  registerCli: ["command name is stable", "argument schema is captured"],
+  registerCommand: ["command id is stable", "interactive command payload is captured"],
+  registerContextEngine: ["context engine id is stable", "factory metadata is captured"],
+  registerGatewayMethod: ["method name is stable", "request and response schema are captured"],
+  registerHttpRoute: ["route method and path are captured", "auth policy metadata is captured"],
+  registerInteractiveHandler: ["handler id is stable", "interaction payload and response shape are captured"],
+  registerHook: ["legacy hook name is stable", "handler metadata is captured"],
+  registerMemoryPromptSection: ["memory prompt section id is stable", "render metadata is captured"],
+  registerMemoryRuntime: ["memory runtime id is stable", "runtime factory metadata is captured"],
+  registerService: ["service id is stable", "start/stop lifecycle handlers are captured"],
+  registerSpeechProvider: ["provider id is stable", "speech request overrides are captured"],
+  registerTool: ["tool name is stable", "input schema is captured", "result shape metadata is captured"],
+};
+
+export const defaultRegistrationArguments = defaultSyntheticRegistrationArguments;
+
+export const defaultHookAssertions = {
+  agent_end: ["final conversation payload is redacted as expected", "agent id and run metadata are present"],
+  before_agent_start: ["legacy startup hook payload is accepted", "migration metadata can map to prompt/model hooks"],
+  before_prompt_build: ["prompt mutation result is preserved", "agent and conversation metadata are present"],
+  before_tool_call: ["block/allow return shapes are preserved", "terminal and approval metadata are present"],
+  inbound_claim: ["claim payload preserves channel/source identity", "routing metadata is present"],
+  llm_input: ["model input payload is redacted as expected", "model and agent metadata are present"],
+  llm_output: ["model output payload is redacted as expected", "model and agent metadata are present"],
+  subagent_delivery_target: ["target routing result is preserved", "parent/subagent metadata are present"],
+  subagent_ended: ["subagent completion payload is preserved", "status metadata is present"],
+  subagent_spawned: ["spawn payload is preserved", "parent/subagent metadata are present"],
+};
+
+export const defaultHookEvents = defaultSyntheticHookEvents;
+
+export const defaultHookContexts = defaultSyntheticHookContexts;
+
+export function buildContractCapture(options = {}) {
+  const report = options.report;
+  if (!report) {
+    throw new TypeError("buildContractCapture requires a compatibility report");
+  }
+
+  const registrationAssertions = options.registrationAssertions ?? defaultRegistrationAssertions;
+  const registrationArguments = options.registrationArguments ?? defaultRegistrationArguments;
+  const hookAssertions = options.hookAssertions ?? defaultHookAssertions;
+  const hookEvents = options.hookEvents ?? defaultHookEvents;
+  const hookContexts = options.hookContexts ?? defaultHookContexts;
+  const capturedRegistrars = new Set(report.targetOpenClaw.capturedRegistrars ?? []);
+  const sdkExports = new Set(report.targetOpenClaw.sdkExports ?? []);
+
+  const fixtures = report.fixtures.map((fixture) => ({
+    id: fixture.id,
+    priority: fixture.priority,
+    registrations: fixture.registrationDetails.map((registration) => ({
+      id: `registration.${registration.name}:${fixture.id}:${slugForArtifact(registration.ref)}`,
+      fixture: fixture.id,
+      registrar: registration.name,
+      ref: registration.ref,
+      support: capturedRegistrars.has(registration.name) ? "target-captured" : "inspector-shim-required",
+      assertions: registrationAssertions[registration.name] ?? ["registration arguments are captured"],
+      syntheticArguments: registrationArguments[registration.name] ?? [{}],
+    })),
+    hooks: fixture.hookDetails.map((hook) => ({
+      id: `hook.${hook.name}:${fixture.id}:${slugForArtifact(hook.ref)}`,
+      fixture: fixture.id,
+      hook: hook.name,
+      ref: hook.ref,
+      support: "synthetic-event-required",
+      assertions: hookAssertions[hook.name] ?? ["hook payload and return value are captured"],
+      syntheticEvent: hookEvents[hook.name] ?? { hook: hook.name, fixture: fixture.id },
+      syntheticContext: hookContexts[hook.name] ?? { hook: hook.name, fixture: fixture.id },
+    })),
+    sdkImports: fixture.sdkImportDetails.map((sdkImport) => ({
+      id: `sdk.${sdkImport.specifier}:${fixture.id}:${slugForArtifact(sdkImport.ref)}`,
+      fixture: fixture.id,
+      specifier: sdkImport.specifier,
+      ref: sdkImport.ref,
+      support: sdkExports.has(sdkImport.specifier) ? "target-exported" : "compat-alias-required",
+      assertions: ["package export exists", "cold import resolves without plugin credentials"],
+    })),
+    packageEntrypoints: packageEntrypoints(fixture),
+  }));
+
+  const issueProbes = report.contractProbes.map((probe) => ({
+    id: probe.id,
+    fixture: probe.fixture,
+    priority: probe.priority,
+    target: probe.target,
+    evidence: probe.evidence,
+    assertions: assertionsForProbeTarget(probe.target),
+  }));
+
+  const allRegistrations = fixtures.flatMap((fixture) => fixture.registrations);
+  const allHooks = fixtures.flatMap((fixture) => fixture.hooks);
+  const allSdkImports = fixtures.flatMap((fixture) => fixture.sdkImports);
+  const allPackageEntrypoints = fixtures.flatMap((fixture) => fixture.packageEntrypoints);
+
+  return {
+    generatedAt: report.generatedAt,
+    targetOpenClaw: {
+      status: report.targetOpenClaw.status,
+      configuredPath: report.targetOpenClaw.configuredPath,
+      capturedRegistrarCount: report.targetOpenClaw.capturedRegistrarCount ?? 0,
+      sdkExportCount: report.targetOpenClaw.sdkExportCount ?? 0,
+    },
+    summary: {
+      fixtureCount: fixtures.length,
+      registrationCount: allRegistrations.length,
+      hookCount: allHooks.length,
+      sdkImportCount: allSdkImports.length,
+      packageEntrypointCount: allPackageEntrypoints.length,
+      issueProbeCount: issueProbes.length,
+      inspectorShimRequiredCount: allRegistrations.filter((item) => item.support === "inspector-shim-required").length,
+      compatAliasRequiredCount: allSdkImports.filter((item) => item.support === "compat-alias-required").length,
+    },
+    fixtures,
+    issueProbes,
+  };
+}
+
+export function validateContractCapture(capture) {
+  const errors = [];
+
+  for (const fixture of capture.fixtures) {
+    for (const section of ["registrations", "hooks", "sdkImports", "packageEntrypoints"]) {
+      for (const item of fixture[section]) {
+        if (!item.ref && section !== "packageEntrypoints") {
+          errors.push(`${item.id}: missing source reference`);
+        }
+        if (!Array.isArray(item.assertions) || item.assertions.length === 0) {
+          errors.push(`${item.id}: missing capture assertions`);
+        }
+        if (section === "registrations" && !Array.isArray(item.syntheticArguments)) {
+          errors.push(`${item.id}: missing synthetic registration arguments`);
+        }
+        if (section === "hooks" && (!item.syntheticEvent || typeof item.syntheticEvent !== "object")) {
+          errors.push(`${item.id}: missing synthetic hook event`);
+        }
+        if (section === "hooks" && (!item.syntheticContext || typeof item.syntheticContext !== "object")) {
+          errors.push(`${item.id}: missing synthetic hook context`);
+        }
+      }
+    }
+  }
+
+  for (const probe of capture.issueProbes) {
+    if (!Array.isArray(probe.evidence) || probe.evidence.length === 0) {
+      errors.push(`${probe.id}: missing probe evidence`);
+    }
+    if (!Array.isArray(probe.assertions) || probe.assertions.length === 0) {
+      errors.push(`${probe.id}: missing probe assertions`);
+    }
+  }
+
+  return errors;
+}
+
+export async function writeContractCapture(capture, options = {}) {
+  return writeJsonMarkdownArtifacts({
+    jsonPath: options.jsonPath,
+    markdownPath: options.markdownPath,
+    json: capture,
+    markdown: renderContractCaptureMarkdown(capture, options),
+  });
+}
+
+export function renderContractCaptureMarkdown(capture, options = {}) {
+  return [
+    `# ${options.title ?? "Plugin Inspector Contract Capture"}`,
+    "",
+    `Generated: ${capture.generatedAt}`,
+    "",
+    "## Summary",
+    "",
+    markdownTable(
+      [
+        ["Fixtures", capture.summary.fixtureCount],
+        ["Registrations", capture.summary.registrationCount],
+        ["Hooks", capture.summary.hookCount],
+        ["SDK imports", capture.summary.sdkImportCount],
+        ["Package entrypoints", capture.summary.packageEntrypointCount],
+        ["Issue probes", capture.summary.issueProbeCount],
+        ["Inspector shim required", capture.summary.inspectorShimRequiredCount],
+        ["Compat aliases required", capture.summary.compatAliasRequiredCount],
+      ],
+      ["Metric", "Value"],
+    ),
+    "",
+    "## Registration Capture",
+    "",
+    markdownTable(
+      capture.fixtures.flatMap((fixture) =>
+        fixture.registrations.map((item) => [
+          fixture.id,
+          item.registrar,
+          item.support,
+          item.ref,
+          item.assertions.join("; "),
+        ]),
+      ),
+      ["Fixture", "Registrar", "Support", "Evidence", "Assertions"],
+    ),
+    "",
+    "## Hook Probes",
+    "",
+    markdownTable(
+      capture.fixtures.flatMap((fixture) =>
+        fixture.hooks.map((item) => [
+          fixture.id,
+          item.hook,
+          item.support,
+          item.ref,
+          item.assertions.join("; "),
+        ]),
+      ),
+      ["Fixture", "Hook", "Support", "Evidence", "Assertions"],
+    ),
+    "",
+    "## SDK Import Probes",
+    "",
+    markdownTable(
+      capture.fixtures.flatMap((fixture) =>
+        fixture.sdkImports.map((item) => [
+          fixture.id,
+          item.specifier,
+          item.support,
+          item.ref,
+          item.assertions.join("; "),
+        ]),
+      ),
+      ["Fixture", "Specifier", "Support", "Evidence", "Assertions"],
+    ),
+    "",
+    "## Issue Probe Backlog",
+    "",
+    markdownTable(
+      capture.issueProbes.map((probe) => [
+        probe.id,
+        probe.priority,
+        probe.fixture,
+        probe.target,
+        probe.assertions.join("; "),
+        probe.evidence.join(", "),
+      ]),
+      ["ID", "Priority", "Fixture", "Target", "Assertions", "Evidence"],
+    ),
+  ].join("\n");
+}
+
+function packageEntrypoints(fixture) {
+  return fixture.packages.flatMap((packageSummary) =>
+    (packageSummary.openclaw?.entrypoints ?? []).map((entrypoint) => ({
+      id: `package.${entrypoint.kind}:${fixture.id}:${slugForArtifact(entrypoint.relativePath)}`,
+      fixture: fixture.id,
+      kind: entrypoint.kind,
+      specifier: entrypoint.specifier,
+      ref: entrypoint.relativePath,
+      support: entrypoint.exists ? "source-present" : entrypoint.requiresBuild ? "build-required" : "missing",
+      assertions: ["entrypoint path resolves", "entrypoint can be cold-imported after required build step"],
+    })),
+  );
+}
+
+function assertionsForProbeTarget(target) {
+  const assertions = {
+    "channel-runtime": ["message envelope is stable", "sender/config metadata is preserved"],
+    "hook-runner": ["synthetic event payload is accepted", "return semantics are preserved"],
+    "inspector-capture-api": ["registration arguments are recorded", "registered handler metadata is retained"],
+    "manifest-loader": ["metadata key is accepted", "migration or compatibility mapping is visible"],
+    "package-loader": ["entrypoint metadata resolves", "cold import failure mode is classified"],
+    "sdk-alias": ["package export exists", "migration metadata is visible when alias is missing"],
+    "tool-runtime": ["tool schema is captured", "tool result metadata is retained"],
+  };
+  return assertions[target] ?? ["probe has fixture evidence and a target contract"];
+}
+
+function markdownTable(rows, headers) {
+  return renderPaddedMarkdownTable(rows, headers);
+}

package/src/contract-coverage.js

@@ -0,0 +1,167 @@
+import { knownIssueCodes } from "./issues.js";
+
+export const knownIssueClasses = new Set([
+  "compat-gap",
+  "deprecation-warning",
+  "fixture-regression",
+  "inspector-gap",
+  "live-issue",
+  "upstream-metadata",
+]);
+
+export function validateContractCoverage(report, options = {}) {
+  const errors = [];
+  const issueCodes = options.knownIssueCodes ?? knownIssueCodes;
+  const issueClasses = options.knownIssueClasses ?? knownIssueClasses;
+
+  if (report.breakages.length > 0) {
+    for (const breakage of report.breakages) {
+      errors.push(`hard breakage: ${breakage.fixture} ${breakage.code}: ${breakage.message}`);
+    }
+  }
+
+  requireUniqueIssueIds(report, errors);
+  requireKnownIssueCodes(report, errors, issueCodes);
+  requireKnownIssueClasses(report, errors, issueClasses);
+  requireIssueEvidence(report, errors);
+  requireP1ProbeCoverage(report, errors);
+  requireFixtureEvidence(report, errors);
+  requireTargetHookRegistry(report, errors);
+  requireTargetApiBuilder(report, errors);
+  requireTargetCapturedRegistration(report, errors);
+  requireTargetSdkExports(report, errors);
+  requireTargetManifestTypes(report, errors);
+  requireCompatRecordReconciliation(report, errors);
+
+  return errors;
+}
+
+function requireTargetHookRegistry(report, errors) {
+  if (report.targetOpenClaw.status === "ok" && report.targetOpenClaw.hookNames.length === 0) {
+    errors.push("target OpenClaw hook registry was found but no hook names were parsed");
+  }
+}
+
+function requireTargetApiBuilder(report, errors) {
+  if (report.targetOpenClaw.status === "ok" && report.targetOpenClaw.apiRegistrars.length === 0) {
+    errors.push("target OpenClaw API builder was found but no api.register* names were parsed");
+  }
+}
+
+function requireTargetCapturedRegistration(report, errors) {
+  if (report.targetOpenClaw.status === "ok" && report.targetOpenClaw.capturedRegistrars.length === 0) {
+    errors.push("target OpenClaw captured-registration helper was found but no api.register* names were parsed");
+  }
+}
+
+function requireTargetSdkExports(report, errors) {
+  if (report.targetOpenClaw.status === "ok" && report.targetOpenClaw.sdkExports.length === 0) {
+    errors.push("target OpenClaw package metadata was found but no plugin SDK exports were parsed");
+  }
+}
+
+function requireTargetManifestTypes(report, errors) {
+  if (report.targetOpenClaw.status !== "ok") {
+    return;
+  }
+  if (report.targetOpenClaw.manifestFields.length === 0) {
+    errors.push("target OpenClaw manifest types were found but no PluginManifest fields were parsed");
+  }
+  if (report.targetOpenClaw.manifestContractFields.length === 0) {
+    errors.push("target OpenClaw manifest types were found but no PluginManifestContracts fields were parsed");
+  }
+}
+
+function requireUniqueIssueIds(report, errors) {
+  const seen = new Set();
+  for (const issue of report.issues) {
+    if (seen.has(issue.id)) {
+      errors.push(`duplicate issue id: ${issue.id}`);
+    }
+    seen.add(issue.id);
+  }
+}
+
+function requireKnownIssueCodes(report, errors, issueCodes) {
+  for (const issue of report.issues) {
+    if (!issueCodes.has(issue.code)) {
+      errors.push(`${issue.id}: unknown issue code ${issue.code}`);
+    }
+  }
+}
+
+function requireKnownIssueClasses(report, errors, issueClasses) {
+  for (const issue of report.issues) {
+    if (!issueClasses.has(issue.issueClass)) {
+      errors.push(`${issue.id}: unknown issue class ${issue.issueClass}`);
+    }
+  }
+}
+
+function requireIssueEvidence(report, errors) {
+  for (const issue of report.issues) {
+    if (!Array.isArray(issue.evidence) || issue.evidence.length === 0) {
+      errors.push(`${issue.id}: missing evidence`);
+    }
+  }
+}
+
+function requireP1ProbeCoverage(report, errors) {
+  const probesByFixture = new Map();
+  for (const probe of report.contractProbes) {
+    const probes = probesByFixture.get(probe.fixture) ?? [];
+    probes.push(probe);
+    probesByFixture.set(probe.fixture, probes);
+  }
+
+  for (const issue of report.issues.filter((item) => item.severity === "P1")) {
+    const probes = probesByFixture.get(issue.fixture) ?? [];
+    if (probes.length === 0) {
+      errors.push(`${issue.id}: P1 issue has no contract probe for ${issue.fixture}`);
+    }
+  }
+}
+
+function requireFixtureEvidence(report, errors) {
+  for (const fixture of report.fixtures) {
+    for (const hook of fixture.hooks) {
+      if (!fixture.hookDetails.some((detail) => detail.name === hook)) {
+        errors.push(`${fixture.id}: hook ${hook} has no source evidence`);
+      }
+    }
+    for (const registration of fixture.registrations) {
+      if (!fixture.registrationDetails.some((detail) => detail.name === registration)) {
+        errors.push(`${fixture.id}: registration ${registration} has no source evidence`);
+      }
+    }
+    for (const contract of fixture.manifestContracts) {
+      if (contract !== "invalidManifest" && fixture.manifestFiles.length === 0) {
+        errors.push(`${fixture.id}: manifest contract ${contract} has no manifest evidence`);
+      }
+    }
+  }
+}
+
+function requireCompatRecordReconciliation(report, errors) {
+  if (report.targetOpenClaw.status !== "ok") {
+    return;
+  }
+
+  const presentRecords = new Set(
+    report.logs
+      .filter((finding) => finding.code === "compat-record-present")
+      .map((finding) => `${finding.fixture}:${finding.compatRecord}`),
+  );
+  const missingRecords = new Set(
+    report.suggestions
+      .filter((finding) => finding.code === "missing-compat-record")
+      .map((finding) => `${finding.fixture}:${finding.compatRecord}`),
+  );
+
+  for (const finding of [...report.warnings, ...report.suggestions].filter((item) => item.compatRecord)) {
+    const key = `${finding.fixture}:${finding.compatRecord}`;
+    if (!presentRecords.has(key) && !missingRecords.has(key)) {
+      errors.push(`${finding.fixture}: compat record ${finding.compatRecord} was not reconciled`);
+    }
+  }
+}