feat: add reporting governance preflight contract

plugins/reporting-governance/test/compatibility-preflight.test.mjs

@@ -0,0 +1,113 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { runCompatibilityPreflight } from '../src/core/compatibility-preflight.mjs';
+import capabilityDescriptor from '../capabilities/openclaw-watchdog-reference.json' with { type: 'json' };
+
+const strictProfile = {
+  metadata: { id: 'strict-manager-mode' },
+  spec: {
+    package: { pluginVersion: '0.1.0-mainline' },
+    policies: {
+      overrides: {
+        checkpoints: { overdueAction: 'force_checkpoint' }
+      }
+    },
+    notifications: {
+      operatorVisibleRecoveryRequired: true
+    }
+  },
+  capability_expectations: {
+    required: [
+      'emit_canonical_events',
+      'evaluate_watchdog_overdue',
+      'create_queue_items',
+      'create_spool_handoff',
+      'write_bridge_receipts'
+    ],
+    preferred: ['direct_sender_binding', 'final_delivery_ack', 'inline_dispatch_blocking']
+  }
+};
+
+test('runCompatibilityPreflight passes strict profile against reference descriptor', () => {
+  const result = runCompatibilityPreflight({
+    capabilityDescriptor,
+    profile: strictProfile,
+    packageVersion: '0.1.0-mainline'
+  });
+
+  assert.equal(result.status, 'pass');
+  assert.equal(result.compatibility.version_ok, true);
+  assert.ok(result.compatibility.schema_checks.every((entry) => entry.ok));
+  assert.ok(result.compatibility.required_expectations.every((entry) => entry.supported));
+  assert.equal(result.errors.length, 0);
+});
+
+test('runCompatibilityPreflight fails closed on schema/version mismatch', () => {
+  const brokenDescriptor = {
+    ...capabilityDescriptor,
+    compatibility: {
+      ...capabilityDescriptor.compatibility,
+      plugin_spec_versions: ['9.9.9'],
+      decision_schema: 'schemas/reporting-governance/not-the-canonical-decision.schema.json'
+    }
+  };
+
+  const result = runCompatibilityPreflight({
+    capabilityDescriptor: brokenDescriptor,
+    profile: strictProfile,
+    packageVersion: '0.1.0-mainline'
+  });
+
+  assert.equal(result.status, 'fail_closed');
+  assert.equal(result.compatibility.version_ok, false);
+  assert.match(result.errors.join('\n'), /schema mismatch: decision_schema/);
+  assert.match(result.errors.join('\n'), /plugin version 0.1.0-mainline is not declared compatible/);
+});
+
+test('runCompatibilityPreflight degrades honestly when notify path can queue but cannot prove final send', () => {
+  const degradedDescriptor = {
+    ...capabilityDescriptor,
+    capabilities: {
+      ...capabilityDescriptor.capabilities,
+      notification_path: {
+        ...capabilityDescriptor.capabilities.notification_path,
+        sender_binding: { supported: false, level: 'none' },
+        direct_send: { supported: false, level: 'none' }
+      }
+    }
+  };
+
+  const result = runCompatibilityPreflight({
+    capabilityDescriptor: degradedDescriptor,
+    profile: strictProfile,
+    packageVersion: '0.1.0-mainline'
+  });
+
+  assert.equal(result.status, 'degraded');
+  assert.equal(result.errors.length, 0);
+  assert.ok(result.warnings.some((warning) => warning.includes('notify_operator')));
+  assert.ok(result.notes.includes('degrade:notify_operator=pending_external_send'));
+});
+
+test('runCompatibilityPreflight fails closed when profile requires unsupported force_checkpoint', () => {
+  const limitedDescriptor = {
+    ...capabilityDescriptor,
+    capabilities: {
+      ...capabilityDescriptor.capabilities,
+      enforcement: {
+        ...capabilityDescriptor.capabilities.enforcement,
+        force_checkpoint: { supported: false, level: 'none' }
+      }
+    }
+  };
+
+  const result = runCompatibilityPreflight({
+    capabilityDescriptor: limitedDescriptor,
+    profile: strictProfile,
+    packageVersion: '0.1.0-mainline'
+  });
+
+  assert.equal(result.status, 'fail_closed');
+  assert.match(result.errors.join('\n'), /required action is not supportable by runtime: force_checkpoint/);
+});