openclaw/reporting-governance-plugin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: tighten decision record storage contract

Browse Source
This commit is contained in:
Eve
2026-05-08 13:30:17 +08:00
parent 30cb206438
commit a440187962
2 changed files with 216 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files

102
plugins/reporting-governance/src/storage/decision-artifact.mjs
View File

@@ -2,6 +2,16 @@ import crypto from 'node:crypto';
const EXPECTED_KIND = 'DecisionRecordArtifact';
const EXPECTED_API_VERSION = 'reporting-governance/v1alpha1';
const CANONICAL_TIMESTAMP_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
const SOURCE_EVENT_ID_PATTERN = /^(?:evt_[A-Za-z0-9._:-]+|\/?[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)+|[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})$/i;
const RECEIPT_DELIVERY_STATES = new Set(['prepared', 'queued', 'dispatched', 'pending_external_send', 'acked', 'blocked', 'failed', 'partial']);
const RECEIPT_STATUS_RULES = {
planned: ['prepared', 'queued', 'dispatched', 'pending_external_send', 'partial'],
acked: ['acked'],
blocked: ['blocked'],
degraded: ['partial', 'failed', 'blocked'],
failed: ['failed']
};
function assertNonEmptyString(value, label) {
if (typeof value !== 'string' || value.trim() === '') {
@@ -28,14 +38,71 @@ function sanitizeFileSegment(value, fallback) {
return normalized || fallback;
}
function assertIsoTimestamp(value, label) {
function assertCanonicalIsoTimestamp(value, label) {
const normalized = assertNonEmptyString(value, label);
if (Number.isNaN(Date.parse(normalized))) {
throw new Error(`${label} must be a valid ISO-8601 timestamp`);
if (!CANONICAL_TIMESTAMP_PATTERN.test(normalized) || Number.isNaN(Date.parse(normalized))) {
throw new Error(`${label} must be a canonical ISO-8601 UTC timestamp with millisecond precision`);
}
return normalized;
}
function assertSourceEventId(value, label) {
const normalized = assertNonEmptyString(value, label);
if (!SOURCE_EVENT_ID_PATTERN.test(normalized)) {
throw new Error(`${label} must be a stable event reference (evt_* | path-like artifact ref | UUID)`);
}
return normalized;
}
function validateReceiptContract(receipt) {
const deliveryState = assertNonEmptyString(receipt.delivery_state, 'decision record artifact spec.receipt.delivery_state');
if (!RECEIPT_DELIVERY_STATES.has(deliveryState)) {
throw new Error(`decision record artifact spec.receipt.delivery_state must be one of: ${Array.from(RECEIPT_DELIVERY_STATES).join(', ')}`);
}
const status = assertNonEmptyString(receipt.status, 'decision record artifact spec.receipt.status');
const allowedStates = RECEIPT_STATUS_RULES[status];
if (!allowedStates) {
throw new Error(`decision record artifact spec.receipt.status must be one of: ${Object.keys(RECEIPT_STATUS_RULES).join(', ')}`);
}
if (!allowedStates.includes(deliveryState)) {
throw new Error(`decision record artifact spec.receipt.status=${status} is incompatible with delivery_state=${deliveryState}`);
}
if (receipt.operator_notice_required != null && typeof receipt.operator_notice_required !== 'boolean') {
throw new Error('decision record artifact spec.receipt.operator_notice_required must be a boolean when present');
}
if (!Array.isArray(receipt.enforcement_intent)) {
throw new Error('decision record artifact spec.receipt.enforcement_intent must be an array');
}
if (!Array.isArray(receipt.blocked_actions)) {
throw new Error('decision record artifact spec.receipt.blocked_actions must be an array');
}
if (!Array.isArray(receipt.notes)) {
throw new Error('decision record artifact spec.receipt.notes must be an array');
}
if (status === 'failed') {
const failureReason = receipt.failure_reason == null
? null
: assertNonEmptyString(receipt.failure_reason, 'decision record artifact spec.receipt.failure_reason');
if (!failureReason) {
throw new Error('decision record artifact spec.receipt.failure_reason is required when status=failed');
}
}
if (deliveryState === 'partial') {
if (receipt.blocked_actions.length === 0) {
throw new Error('decision record artifact spec.receipt.blocked_actions must be non-empty when delivery_state=partial');
}
if (receipt.enforcement_intent.length === 0) {
throw new Error('decision record artifact spec.receipt.enforcement_intent must be non-empty when delivery_state=partial');
}
}
return { deliveryState, status };
}
export function validateDecisionRecordArtifact(artifact) {
if (!artifact || typeof artifact !== 'object' || Array.isArray(artifact)) {
throw new Error('decision record artifact must be an object');
@@ -53,12 +120,12 @@ export function validateDecisionRecordArtifact(artifact) {
const receipt = assertObjectRecord(spec.receipt, 'decision record artifact spec.receipt');
const source = spec.source == null ? null : assertObjectRecord(spec.source, 'decision record artifact spec.source');
const recordedAt = assertIsoTimestamp(metadata.recorded_at, 'decision record artifact metadata.recorded_at');
const recordedAt = assertCanonicalIsoTimestamp(metadata.recorded_at, 'decision record artifact metadata.recorded_at');
const metadataPolicyId = assertNonEmptyString(metadata.policy_id, 'decision record artifact metadata.policy_id');
const metadataDecision = assertNonEmptyString(metadata.decision, 'decision record artifact metadata.decision');
const decisionPolicyId = assertNonEmptyString(decision.policy_id, 'decision record artifact spec.decision.policy_id');
const decisionName = assertNonEmptyString(decision.decision, 'decision record artifact spec.decision.decision');
assertNonEmptyString(receipt.delivery_state, 'decision record artifact spec.receipt.delivery_state');
const { deliveryState, status } = validateReceiptContract(receipt);
if (metadataPolicyId !== decisionPolicyId) {
throw new Error('decision record artifact policy_id mismatch between metadata and spec.decision');
@@ -66,8 +133,17 @@ export function validateDecisionRecordArtifact(artifact) {
if (metadataDecision !== decisionName) {
throw new Error('decision record artifact decision mismatch between metadata and spec.decision');
}
if (source?.event_id != null) {
assertNonEmptyString(source.event_id, 'decision record artifact spec.source.event_id');
const metadataEventId = metadata.event_id == null ? null : assertSourceEventId(metadata.event_id, 'decision record artifact metadata.event_id');
const sourceEventId = source?.event_id == null ? null : assertSourceEventId(source.event_id, 'decision record artifact spec.source.event_id');
if ((metadataEventId == null) !== (sourceEventId == null)) {
throw new Error('decision record artifact event_id must be present in both metadata and spec.source when either side declares it');
}
if (metadataEventId != null && sourceEventId != null && metadataEventId !== sourceEventId) {
throw new Error('decision record artifact event_id mismatch between metadata and spec.source');
}
if (source != null && source.task_id == null && source.correlation_id == null && sourceEventId == null) {
throw new Error('decision record artifact spec.source must declare at least one linkage field');
}
if (source?.task_id != null) {
const sourceTaskId = assertNonEmptyString(source.task_id, 'decision record artifact spec.source.task_id');
@@ -85,8 +161,14 @@ export function validateDecisionRecordArtifact(artifact) {
metadata.recorded_at = recordedAt;
metadata.policy_id = metadataPolicyId;
metadata.decision = metadataDecision;
metadata.event_id = metadataEventId;
decision.policy_id = decisionPolicyId;
decision.decision = decisionName;
receipt.delivery_state = deliveryState;
receipt.status = status;
if (source != null) {
source.event_id = sourceEventId;
}
return artifact;
}
@@ -102,7 +184,7 @@ export function createDecisionRecordArtifact({ decision, receipt, recordedAt = n
apiVersion: EXPECTED_API_VERSION,
metadata: {
record_id: `dec_${crypto.randomUUID()}`,
recorded_at: assertNonEmptyString(recordedAt, 'recordedAt'),
recorded_at: assertCanonicalIsoTimestamp(recordedAt, 'recordedAt'),
policy_id: policyId,
decision: decisionName,
correlation_id: source.correlation_id ?? null,
@@ -135,4 +217,8 @@ export const __testables = {
EXPECTED_KIND,
EXPECTED_API_VERSION,
sanitizeFileSegment,
CANONICAL_TIMESTAMP_PATTERN,
SOURCE_EVENT_ID_PATTERN,
RECEIPT_DELIVERY_STATES,
RECEIPT_STATUS_RULES,
};