Add plain-language status doc and minimal decision store contract

plugins/reporting-governance/test/decision-store.test.mjs

@@ -0,0 +1,133 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import {
+  createDecisionRecordArtifact,
+  createDecisionRecordFileName,
+  createFileDecisionStore,
+  validateDecisionRecordArtifact,
+} from '../src/storage/index.mjs';
+import { planDecisionExecution } from '../src/core/decision-runner.mjs';
+
+const packageRoot = path.resolve(import.meta.dirname, '..');
+const repoRoot = path.resolve(packageRoot, '..', '..');
+
+const capabilityDescriptor = {
+  capabilities: {
+    enforcement: {
+      force_checkpoint: { supported: true, level: 'partial' },
+      escalate: { supported: true, level: 'full' }
+    },
+    notification_path: {
+      queue_items: { supported: true, level: 'full' },
+      spool_handoff: { supported: true, level: 'full' },
+      sender_binding: { supported: true, level: 'full' },
+      direct_send: { supported: false, level: 'none' },
+      truth_model: {
+        delivery_states: ['prepared', 'queued', 'dispatched', 'pending_external_send', 'acked', 'blocked'],
+        ack_requires_proven_send: true,
+        pending_external_send_supported: true
+      }
+    }
+  }
+};
+
+function createPlannedDecision() {
+  return planDecisionExecution({
+    decision: {
+      decision: 'force_checkpoint',
+      policy_id: 'no-silence.missed-checkpoint',
+      severity: 'high',
+      reason: 'checkpoint overdue',
+      required_actions: [
+        { action: 'notify_operator', target: 'operator_channel', mandatory: true },
+        { action: 'emit_event', target: 'event_stream', mandatory: true }
+      ],
+      operator_notice: {
+        required: true,
+        channel: 'telegram',
+        urgency: 'high',
+        message: 'Required update.',
+        deadline: '2026-01-01T00:00:00.000Z'
+      }
+    },
+    capabilityDescriptor,
+  });
+}
+
+test('decision artifact validates minimal package-owned contract', () => {
+  const planned = createPlannedDecision();
+  const artifact = createDecisionRecordArtifact({
+    decision: planned.decision,
+    receipt: planned.receipt,
+    recordedAt: '2026-05-08T04:00:00.000Z',
+    source: {
+      event_id: 'evt_watchdog_001',
+      task_id: 'task-reporting-governance',
+      correlation_id: 'corr-001',
+    },
+  });
+
+  assert.equal(artifact.kind, 'DecisionRecordArtifact');
+  assert.equal(artifact.apiVersion, 'reporting-governance/v1alpha1');
+  assert.equal(artifact.metadata.policy_id, 'no-silence.missed-checkpoint');
+  assert.equal(artifact.spec.receipt.delivery_state, 'pending_external_send');
+  assert.equal(validateDecisionRecordArtifact(artifact), artifact);
+});
+
+test('decision artifact filename is stable and readable', () => {
+  const planned = createPlannedDecision();
+  const artifact = createDecisionRecordArtifact({
+    decision: planned.decision,
+    receipt: planned.receipt,
+    recordedAt: '2026-05-08T04:00:00.000Z',
+  });
+
+  const fileName = createDecisionRecordFileName(artifact);
+  assert.match(fileName, /^2026-05-08T04-00-00-000Z-no-silence\.missed-checkpoint-force_checkpoint-dec_[a-f0-9-]+\.json$/);
+});
+
+test('file decision store writes and reloads a validated decision artifact inside repo root', async (t) => {
+  const sandbox = fs.mkdtempSync(path.join(os.tmpdir(), 'reporting-governance-decision-store-'));
+  t.after(() => fs.rmSync(sandbox, { recursive: true, force: true }));
+
+  const fakeRepoRoot = path.join(sandbox, 'repo');
+  fs.mkdirSync(fakeRepoRoot, { recursive: true });
+
+  const planned = createPlannedDecision();
+  const store = createFileDecisionStore({
+    decisionsDir: path.join(fakeRepoRoot, 'state', 'decisions'),
+    repoRootOverride: fakeRepoRoot,
+  });
+
+  const written = store.write({
+    decision: planned.decision,
+    receipt: planned.receipt,
+    recordedAt: '2026-05-08T04:00:00.000Z',
+    source: {
+      event_id: 'evt_watchdog_001',
+      task_id: 'task-reporting-governance',
+      correlation_id: 'corr-001',
+    },
+  });
+
+  assert.equal(fs.existsSync(written.artifactPath), true);
+  assert.match(path.basename(written.artifactPath), /^2026-05-08T04-00-00-000Z-no-silence\.missed-checkpoint-force_checkpoint-dec_[a-f0-9-]+\.json$/);
+
+  const loaded = store.load(written.artifactPath);
+  assert.equal(loaded.artifact.metadata.event_id, 'evt_watchdog_001');
+  assert.equal(loaded.artifact.spec.receipt.delivery_state, 'pending_external_send');
+});
+
+test('file decision store rejects decision directory escaping repo root', () => {
+  assert.throws(
+    () => createFileDecisionStore({
+      decisionsDir: path.resolve(repoRoot, '..', 'escape'),
+      repoRootOverride: repoRoot,
+    }),
+    /decision store decisionsDir must stay within repo root/
+  );
+});