blun-king-cli 9.1.66 → 9.1.68

package/standard-skills/venture-flywheel/state/execution-event.cjs

@@ -0,0 +1,191 @@
+'use strict';
+
+const { createHash } = require('node:crypto');
+
+const EVENT_FIELDS = new Set([
+  'event_id',
+  'run_id',
+  'project_id',
+  'actor',
+  'event_type',
+  'occurred_at',
+  'payload',
+  'previous_event_hash',
+]);
+const ACTOR_FIELDS = new Set(['type', 'id', 'session_id']);
+const ACTOR_TYPES = new Set(['agent', 'user', 'system']);
+const SECRET_FIELDS = new Set([
+  'access_token',
+  'api_key',
+  'authorization',
+  'bot_token',
+  'client_secret',
+  'cookie',
+  'credential',
+  'password',
+  'passwd',
+  'private_key',
+  'refresh_token',
+  'secret',
+  'session_string',
+  'token',
+]);
+const HASH_PATTERN = /^sha256:[a-f0-9]{64}$/u;
+
+function uvfError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function requireText(value, field) {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw uvfError('UVF_INVALID_EVENT', `${field} must be a non-empty string`);
+  }
+  return value;
+}
+
+function assertKnownFields(value, allowed, label) {
+  const unknown = Object.keys(value).filter((field) => !allowed.has(field));
+  if (unknown.length > 0) {
+    throw uvfError('UVF_INVALID_EVENT', `unknown ${label} fields: ${unknown.sort().join(', ')}`);
+  }
+}
+
+function assertNoSecretFields(value, path = 'payload', seen = new Set()) {
+  if (value === null || typeof value !== 'object') return;
+  if (seen.has(value)) throw uvfError('UVF_INVALID_EVENT', `${path} contains a cycle`);
+  seen.add(value);
+  if (Array.isArray(value)) {
+    value.forEach((entry, index) => assertNoSecretFields(entry, `${path}[${index}]`, seen));
+  } else {
+    for (const [key, entry] of Object.entries(value)) {
+      const normalizedKey = key.toLowerCase().replaceAll('-', '_');
+      const secretLike = SECRET_FIELDS.has(normalizedKey)
+        || normalizedKey.endsWith('_token')
+        || /(?:^|_)(?:password|passwd|secret|authorization|cookie|credential)(?:_|$)/u.test(normalizedKey)
+        || /(?:^|_)(?:api_key|private_key|session_string)(?:_|$)/u.test(normalizedKey);
+      if (secretLike) {
+        throw uvfError('UVF_SECRET_FIELD_REJECTED', `${path}.${key} is not allowed in audit data`);
+      }
+      assertNoSecretFields(entry, `${path}.${key}`, seen);
+    }
+  }
+  seen.delete(value);
+}
+
+function canonicalize(value, path = 'event', seen = new Set()) {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return value;
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) throw uvfError('UVF_INVALID_EVENT', `${path} contains a non-finite number`);
+    return value;
+  }
+  if (typeof value !== 'object') {
+    throw uvfError('UVF_INVALID_EVENT', `${path} contains a non-JSON value`);
+  }
+  if (seen.has(value)) throw uvfError('UVF_INVALID_EVENT', `${path} contains a cycle`);
+  seen.add(value);
+  let result;
+  if (Array.isArray(value)) {
+    result = value.map((entry, index) => canonicalize(entry, `${path}[${index}]`, seen));
+  } else {
+    result = {};
+    for (const key of Object.keys(value).sort()) {
+      result[key] = canonicalize(value[key], `${path}.${key}`, seen);
+    }
+  }
+  seen.delete(value);
+  return result;
+}
+
+function eventDigest(eventWithoutHash) {
+  const canonical = JSON.stringify(canonicalize(eventWithoutHash));
+  return `sha256:${createHash('sha256').update(canonical, 'utf8').digest('hex')}`;
+}
+
+function validateEventInput(input) {
+  if (!isRecord(input)) throw uvfError('UVF_INVALID_EVENT', 'event must be an object');
+  assertKnownFields(input, EVENT_FIELDS, 'event');
+  requireText(input.event_id, 'event_id');
+  requireText(input.run_id, 'run_id');
+  requireText(input.project_id, 'project_id');
+  requireText(input.event_type, 'event_type');
+  if (!isRecord(input.actor)) throw uvfError('UVF_INVALID_EVENT', 'actor must be an object');
+  assertKnownFields(input.actor, ACTOR_FIELDS, 'actor');
+  if (!ACTOR_TYPES.has(input.actor.type)) {
+    throw uvfError('UVF_INVALID_EVENT', `unsupported actor type: ${String(input.actor.type)}`);
+  }
+  requireText(input.actor.id, 'actor.id');
+  requireText(input.actor.session_id, 'actor.session_id');
+  requireText(input.occurred_at, 'occurred_at');
+  const occurredAt = new Date(input.occurred_at);
+  if (Number.isNaN(occurredAt.getTime()) || occurredAt.toISOString() !== input.occurred_at) {
+    throw uvfError('UVF_INVALID_EVENT', 'occurred_at must be a canonical ISO timestamp');
+  }
+  if (!isRecord(input.payload)) throw uvfError('UVF_INVALID_EVENT', 'payload must be an object');
+  assertNoSecretFields(input.payload);
+  if (input.previous_event_hash !== undefined
+    && input.previous_event_hash !== null
+    && (typeof input.previous_event_hash !== 'string'
+      || !HASH_PATTERN.test(input.previous_event_hash))) {
+    throw uvfError('UVF_INVALID_EVENT', 'previous_event_hash must be a sha256 hash or null');
+  }
+}
+
+function deepFreeze(value) {
+  if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+    Object.freeze(value);
+    for (const child of Object.values(value)) deepFreeze(child);
+  }
+  return value;
+}
+
+function createExecutionEvent(input) {
+  validateEventInput(input);
+  const event = {
+    event_id: input.event_id,
+    run_id: input.run_id,
+    project_id: input.project_id,
+    actor: canonicalize(input.actor),
+    event_type: input.event_type,
+    occurred_at: input.occurred_at,
+    payload: canonicalize(input.payload),
+    previous_event_hash: input.previous_event_hash ?? null,
+  };
+  return deepFreeze({ ...event, event_hash: eventDigest(event) });
+}
+
+function verifyEventChain(events) {
+  if (!Array.isArray(events)) return { ok: false, index: -1, reason: 'invalid_chain' };
+  let previousHash = null;
+  for (let index = 0; index < events.length; index += 1) {
+    const event = events[index];
+    if (!isRecord(event) || !HASH_PATTERN.test(event.event_hash || '')) {
+      return { ok: false, index, reason: 'invalid_event' };
+    }
+    if ((event.previous_event_hash ?? null) !== previousHash) {
+      return { ok: false, index, reason: 'previous_event_hash_mismatch' };
+    }
+    const { event_hash: eventHash, ...input } = event;
+    let rebuilt;
+    try {
+      rebuilt = createExecutionEvent(input);
+    } catch {
+      return { ok: false, index, reason: 'invalid_event' };
+    }
+    if (rebuilt.event_hash !== eventHash) {
+      return { ok: false, index, reason: 'event_hash_mismatch' };
+    }
+    previousHash = eventHash;
+  }
+  return { ok: true };
+}
+
+module.exports = {
+  createExecutionEvent,
+  verifyEventChain,
+};

package/standard-skills/venture-flywheel/state/task-state-machine.cjs

@@ -0,0 +1,190 @@
+'use strict';
+
+const RUN_STATES = Object.freeze([
+  'discovered',
+  'profiled',
+  'configured',
+  'baseline_measured',
+  'observing',
+  'evidence_ready',
+  'proposal_created',
+  'selected_by_strategic_authority',
+  'approved_for_local_execution',
+  'executing_local',
+  'verifying',
+  'blocked',
+  'aborted',
+  'no_action',
+  'locally_verified',
+  'completed_local',
+  'waiting_approval',
+  'denied',
+  'expired',
+  'approved_exact_state',
+  'deploying',
+  'post_deploy_observation',
+  'attribution_pending',
+  'completed',
+  'rolled_back',
+  'inconclusive',
+]);
+
+const TRANSITIONS = Object.freeze({
+  discovered: Object.freeze(['profiled']),
+  profiled: Object.freeze(['configured']),
+  configured: Object.freeze(['baseline_measured']),
+  baseline_measured: Object.freeze(['observing']),
+  observing: Object.freeze(['evidence_ready', 'no_action', 'blocked', 'aborted']),
+  evidence_ready: Object.freeze(['proposal_created', 'no_action', 'blocked', 'aborted']),
+  proposal_created: Object.freeze(['selected_by_strategic_authority', 'no_action', 'blocked', 'aborted']),
+  selected_by_strategic_authority: Object.freeze(['approved_for_local_execution', 'no_action', 'blocked', 'aborted']),
+  approved_for_local_execution: Object.freeze(['executing_local', 'blocked', 'aborted']),
+  executing_local: Object.freeze(['verifying', 'blocked', 'aborted']),
+  verifying: Object.freeze(['locally_verified', 'blocked', 'aborted', 'no_action']),
+  locally_verified: Object.freeze(['completed_local', 'waiting_approval', 'verifying']),
+  waiting_approval: Object.freeze(['approved_exact_state', 'denied', 'expired', 'aborted']),
+  approved_exact_state: Object.freeze(['deploying', 'verifying', 'aborted']),
+  deploying: Object.freeze(['post_deploy_observation', 'blocked', 'aborted']),
+  post_deploy_observation: Object.freeze(['attribution_pending', 'blocked', 'aborted']),
+  attribution_pending: Object.freeze(['completed', 'rolled_back', 'inconclusive', 'blocked', 'aborted']),
+});
+
+const TERMINAL_STATE_VALUES = Object.freeze([
+  'blocked',
+  'aborted',
+  'no_action',
+  'completed_local',
+  'denied',
+  'expired',
+  'completed',
+  'rolled_back',
+  'inconclusive',
+]);
+const TERMINAL_STATE_LOOKUP = new Set(TERMINAL_STATE_VALUES);
+const TERMINAL_STATES = Object.freeze({
+  get size() {
+    return TERMINAL_STATE_VALUES.length;
+  },
+  has(state) {
+    return TERMINAL_STATE_LOOKUP.has(state);
+  },
+  values() {
+    return TERMINAL_STATE_VALUES.values();
+  },
+  [Symbol.iterator]() {
+    return TERMINAL_STATE_VALUES[Symbol.iterator]();
+  },
+});
+
+const REQUEST_FIELDS = new Set([
+  'event_id',
+  'expected_version',
+  'from_state',
+  'to_state',
+  'evidence',
+]);
+
+function uvfError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function requireText(value, field) {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw uvfError('UVF_INVALID_TRANSITION_REQUEST', `${field} must be a non-empty string`);
+  }
+  return value;
+}
+
+function validateRun(run) {
+  if (!isRecord(run)) throw uvfError('UVF_INVALID_RUN', 'run must be an object');
+  requireText(run.run_id, 'run_id');
+  if (!RUN_STATES.includes(run.state)) {
+    throw uvfError('UVF_INVALID_RUN_STATE', `unknown run state: ${String(run.state)}`);
+  }
+  if (!Number.isSafeInteger(run.version) || run.version < 0) {
+    throw uvfError('UVF_INVALID_RUN_VERSION', 'run version must be a non-negative integer');
+  }
+}
+
+function validateRequest(request) {
+  if (!isRecord(request)) {
+    throw uvfError('UVF_INVALID_TRANSITION_REQUEST', 'transition request must be an object');
+  }
+  const unknownFields = Object.keys(request).filter((field) => !REQUEST_FIELDS.has(field));
+  if (unknownFields.length > 0) {
+    throw uvfError(
+      'UVF_INVALID_TRANSITION_REQUEST',
+      `unknown transition fields: ${unknownFields.sort().join(', ')}`,
+    );
+  }
+  requireText(request.event_id, 'event_id');
+  requireText(request.from_state, 'from_state');
+  requireText(request.to_state, 'to_state');
+  if (!Number.isSafeInteger(request.expected_version) || request.expected_version < 0) {
+    throw uvfError('UVF_INVALID_TRANSITION_REQUEST', 'expected_version must be a non-negative integer');
+  }
+  if (request.evidence !== undefined && !isRecord(request.evidence)) {
+    throw uvfError('UVF_INVALID_TRANSITION_REQUEST', 'evidence must be an object');
+  }
+}
+
+function requireEvidence(request, field, code) {
+  if (typeof request.evidence?.[field] !== 'string'
+    || request.evidence[field].trim().length === 0) {
+    throw uvfError(code, `${request.to_state} requires ${field}`);
+  }
+}
+
+function transitionRun(run, request) {
+  validateRun(run);
+  validateRequest(request);
+
+  if (request.expected_version !== run.version) {
+    throw uvfError(
+      'UVF_VERSION_CONFLICT',
+      `expected version ${request.expected_version}, current version ${run.version}`,
+    );
+  }
+  if (request.from_state !== run.state) {
+    throw uvfError(
+      'UVF_STATE_CONFLICT',
+      `expected state ${request.from_state}, current state ${run.state}`,
+    );
+  }
+  if (!RUN_STATES.includes(request.to_state)) {
+    throw uvfError('UVF_INVALID_RUN_STATE', `unknown target state: ${request.to_state}`);
+  }
+  const allowed = TRANSITIONS[run.state] || [];
+  if (!allowed.includes(request.to_state)) {
+    throw uvfError(
+      'UVF_INVALID_TRANSITION',
+      `transition ${run.state} -> ${request.to_state} is not allowed`,
+    );
+  }
+  if (request.to_state === 'completed') {
+    requireEvidence(request, 'final_evidence_id', 'UVF_FINAL_EVIDENCE_REQUIRED');
+  }
+  if (request.to_state === 'rolled_back') {
+    requireEvidence(request, 'rollback_evidence_id', 'UVF_ROLLBACK_EVIDENCE_REQUIRED');
+  }
+
+  return Object.freeze({
+    ...run,
+    state: request.to_state,
+    version: run.version + 1,
+    last_event_id: request.event_id,
+  });
+}
+
+module.exports = {
+  RUN_STATES,
+  TERMINAL_STATES,
+  TRANSITIONS,
+  transitionRun,
+};