ai-delivery-workflow 0.3.0 → 0.4.0

package/lib/workflow-manager-governance.mjs

@@ -0,0 +1,514 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import {
+  commitWorkflowManagerAction,
+  prepareWorkflowManagerFormalTransaction,
+  workflowManagerRequestChecksum,
+} from "./workflow-manager-transaction.mjs";
+
+const runtimeRoot = path.dirname(fileURLToPath(import.meta.url));
+const installedYaml = path.join(runtimeRoot, "..", "state", "vendor", "yaml", "dist", "index.js");
+const require = createRequire(import.meta.url);
+const YAML = require(fs.existsSync(installedYaml) ? installedYaml : "yaml");
+const installedState = path.join(runtimeRoot, "..", "state", "delivery-state.mjs");
+const packageState = path.join(runtimeRoot, "delivery-state.mjs");
+const { executeDeliveryStateCommand } = await import(pathToFileURL(
+  fs.existsSync(installedState) ? installedState : packageState,
+).href);
+
+export const WORKFLOW_MANAGER_GOVERNANCE_SCHEMA_VERSION = "workflow-manager.governance.v1";
+
+const RELATIONS_FILE = ".workflow/control/relations.yaml";
+const SETTINGS_FILE = ".workflow/config/manager-settings.json";
+const RECEIPTS_ROOT = ".workflow/control/receipts";
+const EVENTS_FILE = ".workflow/control/events/workflow-manager-events.jsonl";
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,191}$/;
+const SAFE_ENTITY_TYPE = /^[a-z][a-z0-9-]{0,63}$/;
+const RELATION_TYPES = new Set([
+  "implements", "implemented-by", "covers", "covered-by", "verifies", "verified-by",
+  "produces", "produced-by", "depends-on", "blocks", "sourced-from", "supersedes", "related-to",
+]);
+const DEVELOPMENT_NODES = new Set([
+  "00-bootstrap", "01-product-shaping", "02-solution-design", "03-delivery-readiness",
+  "04-implementation", "05-candidate-assurance", "06-version-closeout",
+]);
+
+function stable(value) {
+  if (Array.isArray(value)) return value.map(stable);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.keys(value).sort().map((key) => [key, stable(value[key])]));
+  }
+  return value;
+}
+
+function sha256(value) {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+function checksum(value) {
+  return sha256(JSON.stringify(stable(value)));
+}
+
+function contained(root, relative) {
+  const absolute = path.resolve(root, ...relative.split("/"));
+  const relation = path.relative(root, absolute);
+  if (relation.startsWith("..") || path.isAbsolute(relation)) throw new Error(`Governed path escapes project: ${relative}`);
+  return absolute;
+}
+
+function atomicWrite(file, content) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temporary = `${file}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  fs.writeFileSync(temporary, content, { encoding: "utf8", flag: "wx" });
+  try {
+    fs.renameSync(temporary, file);
+  } catch (error) {
+    fs.rmSync(temporary, { force: true });
+    throw error;
+  }
+}
+
+function requireHuman(actor) {
+  if (!/^human:[A-Za-z0-9._@/-]+$/.test(String(actor || ""))) {
+    throw new Error("Governed confirmation requires actor human:<identity>");
+  }
+}
+
+function requireAgent(actor) {
+  if (!/^agent:[A-Za-z0-9._@/-]+$/.test(String(actor || ""))) {
+    throw new Error("Relationship suggestion requires actor agent:<identity>");
+  }
+}
+
+function receiptFiles(root) {
+  const directory = contained(root, RECEIPTS_ROOT);
+  if (!fs.existsSync(directory)) return [];
+  return fs.readdirSync(directory).filter((name) => name.endsWith(".json")).sort()
+    .map((name) => path.join(directory, name));
+}
+
+function replay(root, action, input, subject = null) {
+  if (!input.idempotency_key) return null;
+  const legacyRequestChecksum = checksum({ action, input });
+  const governedRequestChecksum = workflowManagerRequestChecksum(action, input, subject);
+  for (const file of receiptFiles(root)) {
+    try {
+      const receipt = JSON.parse(fs.readFileSync(file, "utf8"));
+      if (receipt.action !== action || receipt.idempotency_key !== input.idempotency_key) continue;
+      const legacy = receipt.request_checksum === legacyRequestChecksum;
+      const governed = receipt.request_checksum === governedRequestChecksum
+        && (receipt.subject ?? null) === subject;
+      if (!legacy && !governed) {
+        throw new Error("Idempotency key was already used for a different request");
+      }
+      return receipt;
+    } catch (error) {
+      if (/Idempotency key/.test(error.message)) throw error;
+    }
+  }
+  return null;
+}
+
+function record(root, action, input, detail = {}) {
+  const timestamp = new Date().toISOString();
+  const receipt = {
+    schema_version: 1,
+    receipt_id: `WMG-${crypto.randomUUID()}`,
+    action,
+    actor: input.actor,
+    idempotency_key: input.idempotency_key || null,
+    request_checksum: checksum({ action, input }),
+    applied_at: timestamp,
+    ...detail,
+  };
+  receipt.receipt_checksum = checksum(receipt);
+  atomicWrite(contained(root, `${RECEIPTS_ROOT}/${receipt.receipt_id}.json`), `${JSON.stringify(receipt, null, 2)}\n`);
+  const event = {
+    schema_version: 1,
+    event_id: `WME-${crypto.randomUUID()}`,
+    type: `workflow-manager.${action}`,
+    occurred_at: timestamp,
+    receipt_id: receipt.receipt_id,
+    subject: detail.subject || null,
+  };
+  const eventFile = contained(root, EVENTS_FILE);
+  fs.mkdirSync(path.dirname(eventFile), { recursive: true });
+  fs.appendFileSync(eventFile, `${JSON.stringify(event)}\n`, "utf8");
+  return { receipt, event };
+}
+
+function relationsDocument(root) {
+  const file = contained(root, RELATIONS_FILE);
+  if (!fs.existsSync(file)) return { file, document: { schema_version: 1, revision: 0, relations: [] }, checksum: null };
+  const bytes = fs.readFileSync(file);
+  const document = YAML.parse(bytes.toString("utf8")) || {};
+  if (!Number.isInteger(document.revision) || !Array.isArray(document.relations)) {
+    throw new Error("Relationship registry must contain revision and relations");
+  }
+  return { file, document, checksum: sha256(bytes) };
+}
+
+function requireRelationRevision(loaded, input) {
+  if (input.expected_revision !== loaded.document.revision) throw new Error("Relationship registry revision mismatch");
+  if ((input.expected_checksum || null) !== loaded.checksum) throw new Error("Relationship registry checksum mismatch");
+}
+
+function relationResult(root, action, input, relation, loaded, next, options = {}) {
+  const content = YAML.stringify(next, { lineWidth: 0 });
+  const currentChecksum = sha256(content);
+  const result = {
+    relation,
+    current_revision: next.revision,
+    current_checksum: currentChecksum,
+  };
+  const recorded = commitWorkflowManagerAction(root, {
+    action,
+    subject: relation.relation_id,
+    input,
+    result,
+    detail: {
+      relation_id: relation.relation_id,
+      relation_state: relation.relation_state,
+      previous_revision: loaded.document.revision,
+      current_revision: next.revision,
+      current_checksum: currentChecksum,
+      affected_identities: [relation.from, relation.to, relation.relation_id],
+    },
+    writes: [{ file: loaded.file, content }],
+    receiptPrefix: "WMG",
+    eventType: `workflow-manager.${action}`,
+    transactionHooks: options.transactionHooks,
+  });
+  return {
+    schema_version: WORKFLOW_MANAGER_GOVERNANCE_SCHEMA_VERSION,
+    outcome: recorded.outcome,
+    ...result,
+    receipt: recorded.receipt,
+    event: recorded.event,
+  };
+}
+
+export function suggestWorkflowManagerRelationship(projectRoot, input = {}, options = {}) {
+  const root = path.resolve(projectRoot);
+  requireAgent(input.actor);
+  if (!SAFE_ID.test(String(input.from || "")) || !SAFE_ID.test(String(input.to || "")) || input.from === input.to) {
+    throw new Error("Relationship requires distinct stable from/to identities");
+  }
+  if (!SAFE_ENTITY_TYPE.test(String(input.from_entity_type || ""))
+      || !SAFE_ENTITY_TYPE.test(String(input.to_entity_type || ""))) {
+    throw new Error("Relationship requires stable from/to entity types");
+  }
+  if (!RELATION_TYPES.has(input.relation_type)) throw new Error(`Unsupported relationship type: ${input.relation_type}`);
+  if (!String(input.rationale || "").trim()) throw new Error("Relationship suggestion rationale is required");
+  const existing = replay(root, "relationship-suggested", input);
+  if (existing) return { outcome: "idempotent-replay", receipt: existing };
+  const loaded = relationsDocument(root);
+  requireRelationRevision(loaded, input);
+  const timestamp = new Date().toISOString();
+  const relation = {
+    relation_id: `REL-${crypto.randomUUID()}`,
+    from: input.from,
+    from_entity_type: input.from_entity_type,
+    to: input.to,
+    to_entity_type: input.to_entity_type,
+    relation_type: input.relation_type,
+    relation_state: "suggested",
+    revision: 1,
+    suggested_by: input.actor,
+    rationale: String(input.rationale).trim(),
+    created_at: timestamp,
+    updated_at: timestamp,
+    decision: null,
+  };
+  const next = structuredClone(loaded.document);
+  next.revision += 1;
+  next.relations.push(relation);
+  return relationResult(root, "relationship-suggested", input, relation, loaded, next, options);
+}
+
+export function decideWorkflowManagerRelationship(projectRoot, input = {}, options = {}) {
+  const root = path.resolve(projectRoot);
+  requireHuman(input.actor);
+  if (!new Set(["confirmed", "rejected"]).has(input.decision)) throw new Error("Relationship decision must be confirmed or rejected");
+  const existing = replay(root, "relationship-decided", input);
+  if (existing) return { outcome: "idempotent-replay", receipt: existing };
+  const loaded = relationsDocument(root);
+  requireRelationRevision(loaded, input);
+  const next = structuredClone(loaded.document);
+  const relation = next.relations.find((item) => item.relation_id === input.relation_id);
+  if (!relation) throw new Error(`Relationship does not exist: ${input.relation_id}`);
+  if (relation.relation_state !== "suggested") throw new Error("Only a suggested relationship may be decided");
+  relation.relation_state = input.decision;
+  relation.revision = Number(relation.revision || 1) + 1;
+  relation.updated_at = new Date().toISOString();
+  relation.decision = { actor: input.actor, comment: String(input.comment || "").trim() || null, decided_at: relation.updated_at };
+  next.revision += 1;
+  return relationResult(root, "relationship-decided", input, relation, loaded, next, options);
+}
+
+export function invalidateWorkflowManagerRelationship(projectRoot, input = {}, options = {}) {
+  const root = path.resolve(projectRoot);
+  requireHuman(input.actor);
+  if (!String(input.rationale || "").trim()) throw new Error("Relationship invalidation rationale is required");
+  const existing = replay(root, "relationship-invalidated", input);
+  if (existing) return { outcome: "idempotent-replay", receipt: existing };
+  const loaded = relationsDocument(root);
+  requireRelationRevision(loaded, input);
+  const next = structuredClone(loaded.document);
+  const relation = next.relations.find((item) => item.relation_id === input.relation_id);
+  if (!relation) throw new Error(`Relationship does not exist: ${input.relation_id}`);
+  if (relation.relation_state === "invalidated") throw new Error("Relationship is already invalidated");
+  relation.relation_state = "invalidated";
+  relation.revision = Number(relation.revision || 1) + 1;
+  relation.updated_at = new Date().toISOString();
+  relation.invalidation = { actor: input.actor, rationale: String(input.rationale).trim(), invalidated_at: relation.updated_at };
+  next.revision += 1;
+  return relationResult(root, "relationship-invalidated", input, relation, loaded, next, options);
+}
+
+function readSettings(root) {
+  const file = contained(root, SETTINGS_FILE);
+  if (!fs.existsSync(file)) return { file, value: { schema_version: 1, revision: 0, preferences: {} }, checksum: null };
+  const bytes = fs.readFileSync(file);
+  const value = JSON.parse(bytes.toString("utf8"));
+  if (!Number.isInteger(value.revision) || !value.preferences || typeof value.preferences !== "object") {
+    throw new Error("Workflow Manager settings are invalid");
+  }
+  return { file, value, checksum: sha256(bytes) };
+}
+
+export function inspectWorkflowManagerSettings(projectRoot) {
+  const root = path.resolve(projectRoot);
+  const loaded = readSettings(root);
+  return {
+    schema_version: "workflow-manager.settings.v1",
+    registration_status: fs.existsSync(loaded.file) ? "registered" : "not-registered",
+    revision: loaded.value.revision,
+    checksum: loaded.checksum,
+    preferences: loaded.value.preferences,
+    interface: {
+      language: "zh-CN", visual_standard: "Operational Carbon", icon_library: "Lucide",
+      minimum_width: 1180, mobile_supported: false,
+    },
+    security: {
+      bind_host: "127.0.0.1", arbitrary_shell: false, arbitrary_paths: false,
+      raw_yaml_editing: false, gate_bypass: false,
+    },
+    mutability: "governed",
+  };
+}
+
+function prepareSettingsUpdate(projectRoot, input = {}) {
+  const root = path.resolve(projectRoot);
+  requireHuman(input.actor);
+  const loaded = readSettings(root);
+  if (input.expected_revision !== loaded.value.revision) throw new Error("Workflow Manager settings revision mismatch");
+  if ((input.expected_checksum || null) !== loaded.checksum) throw new Error("Workflow Manager settings checksum mismatch");
+  const changes = input.changes;
+  if (!changes || typeof changes !== "object" || Array.isArray(changes)) throw new Error("Settings changes must be an object");
+  const allowed = new Set(["default_port", "system_health_timeout_ms"]);
+  for (const key of Object.keys(changes)) if (!allowed.has(key)) throw new Error(`Unsupported setting: ${key}`);
+  if (changes.default_port !== undefined
+      && (!Number.isInteger(changes.default_port) || changes.default_port < 1 || changes.default_port > 65535 || changes.default_port === 80)) {
+    throw new Error("default_port must be an integer from 1 to 65535 and cannot be 80");
+  }
+  if (changes.system_health_timeout_ms !== undefined
+      && (!Number.isInteger(changes.system_health_timeout_ms) || changes.system_health_timeout_ms < 100 || changes.system_health_timeout_ms > 60000)) {
+    throw new Error("system_health_timeout_ms must be an integer from 100 to 60000");
+  }
+  const next = { schema_version: 1, revision: loaded.value.revision + 1, preferences: { ...loaded.value.preferences, ...changes } };
+  const content = `${JSON.stringify(next, null, 2)}\n`;
+  const currentChecksum = sha256(content);
+  const plan = {
+    action: "settings-update",
+    expected_revision: loaded.value.revision,
+    expected_checksum: loaded.checksum,
+    changes: stable(changes),
+    current_revision: next.revision,
+    current_checksum: currentChecksum,
+    affected_identities: ["workflow-manager-settings"],
+  };
+  return { root, loaded, content, currentChecksum, plan, planChecksum: checksum(plan) };
+}
+
+export function planWorkflowManagerSettingsUpdate(projectRoot, input = {}) {
+  const prepared = prepareSettingsUpdate(projectRoot, input);
+  return {
+    schema_version: WORKFLOW_MANAGER_GOVERNANCE_SCHEMA_VERSION,
+    outcome: "planned",
+    mutability: "plan-only",
+    ...prepared.plan,
+    plan_checksum: prepared.planChecksum,
+  };
+}
+
+export function applyWorkflowManagerSettingsUpdate(projectRoot, input = {}, options = {}) {
+  const root = path.resolve(projectRoot);
+  requireHuman(input.actor);
+  const existing = replay(root, "settings-updated", input);
+  if (existing) return { outcome: "idempotent-replay", receipt: existing, result: existing.result };
+  const prepared = prepareSettingsUpdate(root, input);
+  if (input.expected_plan_checksum !== prepared.planChecksum) {
+    throw new Error("Workflow Manager settings plan checksum mismatch");
+  }
+  const result = {
+    current_revision: prepared.plan.current_revision,
+    current_checksum: prepared.currentChecksum,
+    plan_checksum: prepared.planChecksum,
+  };
+  const recorded = commitWorkflowManagerAction(root, {
+    action: "settings-updated",
+    subject: "workflow-manager-settings",
+    input,
+    result,
+    detail: {
+      previous_revision: prepared.loaded.value.revision,
+      current_revision: prepared.plan.current_revision,
+      current_checksum: prepared.currentChecksum,
+      plan_checksum: prepared.planChecksum,
+      affected_identities: ["workflow-manager-settings"],
+    },
+    writes: [{ file: prepared.loaded.file, content: prepared.content }],
+    receiptPrefix: "WMG",
+    eventType: "workflow-manager.settings-updated",
+    transactionHooks: options.transactionHooks,
+  });
+  return {
+    outcome: recorded.outcome,
+    ...result,
+    receipt: recorded.receipt,
+    event: recorded.event,
+  };
+}
+
+export function applyWorkflowManagerGateDecision(projectRoot, input = {}, options = {}) {
+  const root = path.resolve(projectRoot);
+  requireHuman(input.actor);
+  if (/^UX-(LF|VS|UI)$/.test(String(input.gate_id || ""))) {
+    throw new Error("UX decisions are completed in P11/P12 through Prototype review");
+  }
+  if (!new Set(["approved", "rejected"]).has(input.decision)) throw new Error("P06 decision must be approved or rejected");
+  if (!Number.isInteger(input.expected_scope_revision) || input.expected_scope_revision < 0) {
+    throw new Error("Gate decision requires expected_scope_revision");
+  }
+  const existing = replay(root, "gate-decision-applied", input, input.gate_id);
+  if (existing) return { outcome: "idempotent-replay", receipt: existing };
+  const comment = String(input.comment || "").trim() || null;
+  const args = [
+    "gate", "decide", "--project", root,
+    "--expected-scope-revision", String(input.expected_scope_revision),
+    "--gate-id", String(input.gate_id || ""),
+    "--decision", input.decision,
+    "--actor", input.actor,
+    "--rationale", comment || `Workflow Manager ${input.decision} decision for ${input.gate_id}.`,
+  ];
+  for (const evidence of input.evidence || []) args.push("--evidence", evidence);
+  const transaction = prepareWorkflowManagerFormalTransaction(root, {
+    action: "gate-decision-applied",
+    subject: input.gate_id,
+    input,
+    resultFactory: ({ mutations }) => {
+      const state = mutations.find((mutation) => mutation.stream === "workflow-state")?.value;
+      const scopes = [state?.development_state, state?.release_state].filter(Boolean);
+      const gate = scopes.flatMap((scope) => scope.gate_decisions || [])
+        .findLast((item) => item.gate_id === input.gate_id && item.decision === input.decision);
+      if (!gate) throw new Error("Formal state transaction did not record the expected Gate decision");
+      const scope = scopes.find((item) => (item.gate_decisions || []).includes(gate));
+      return { gate, scope_revision: scope?.revision ?? null, comment };
+    },
+    detailFactory: (_formalContext, result) => ({
+      gate_id: input.gate_id,
+      decision: input.decision,
+      comment,
+      expected_scope_revision: input.expected_scope_revision,
+      current_scope_revision: result.scope_revision,
+      affected_identities: [input.gate_id],
+      delegated_writer: "delivery-state.gate-decide",
+    }),
+    receiptPrefix: "WMG",
+  });
+  const formal = executeDeliveryStateCommand(args, {
+    yaml: { parse: YAML.parse, stringify: (value) => YAML.stringify(value, { lineWidth: 0 }) },
+    ...(options.stateOptions || {}),
+    managerTransactionWriteFactory: transaction.factory,
+  });
+  const recorded = transaction.result();
+  return {
+    schema_version: WORKFLOW_MANAGER_GOVERNANCE_SCHEMA_VERSION,
+    outcome: recorded.outcome,
+    formal,
+    receipt: recorded.receipt,
+    event: recorded.event,
+  };
+}
+
+export function applyWorkflowManagerTransition(projectRoot, input = {}, options = {}) {
+  const root = path.resolve(projectRoot);
+  requireHuman(input.actor);
+  if (!new Set(["node-started", "node-completed"]).has(input.event)) {
+    throw new Error("Workflow Manager transition event must be node-started or node-completed");
+  }
+  if (!DEVELOPMENT_NODES.has(input.node_id)) {
+    throw new Error("Workflow Manager transitions are limited to the formal seven-node development workflow");
+  }
+  if (!SAFE_ID.test(String(input.iteration_id || ""))) throw new Error("Workflow transition requires iteration_id");
+  if (!Number.isInteger(input.expected_scope_revision) || input.expected_scope_revision < 0) {
+    throw new Error("Workflow transition requires expected_scope_revision");
+  }
+  if (!Array.isArray(input.evidence)) throw new Error("Workflow transition evidence must be an array");
+  const existing = replay(root, "workflow-transition-applied", input, input.node_id);
+  if (existing) return { outcome: "idempotent-replay", receipt: existing };
+  const args = [
+    "transition", "--project", root,
+    "--expected-scope-revision", String(input.expected_scope_revision),
+    "--event", input.event,
+    "--iteration-id", input.iteration_id,
+    "--node", input.node_id,
+  ];
+  for (const evidence of input.evidence) args.push("--evidence", String(evidence));
+  const transaction = prepareWorkflowManagerFormalTransaction(root, {
+    action: "workflow-transition-applied",
+    subject: input.node_id,
+    input,
+    resultFactory: ({ mutations }) => {
+      const state = mutations.find((mutation) => mutation.stream === "workflow-state")?.value;
+      const scope = state?.development_state;
+      if (!scope || scope.revision !== input.expected_scope_revision + 1) {
+        throw new Error("Formal state transaction did not record the expected workflow transition");
+      }
+      const completion = (scope.node_completion_receipts || [])
+        .findLast((item) => item.node === input.node_id);
+      return {
+        node_id: input.node_id,
+        transition_event: input.event,
+        iteration_id: input.iteration_id,
+        scope_revision: scope.revision,
+        completion_receipt_id: completion?.receipt_id || null,
+      };
+    },
+    detailFactory: (_formalContext, result) => ({
+      ...result,
+      expected_scope_revision: input.expected_scope_revision,
+      current_scope_revision: result.scope_revision,
+      affected_identities: [input.node_id],
+      delegated_writer: "delivery-state.transition",
+    }),
+    receiptPrefix: "WMG",
+  });
+  const formal = executeDeliveryStateCommand(args, {
+    yaml: { parse: YAML.parse, stringify: (value) => YAML.stringify(value, { lineWidth: 0 }) },
+    ...(options.stateOptions || {}),
+    managerTransactionWriteFactory: transaction.factory,
+  });
+  const recorded = transaction.result();
+  return {
+    schema_version: WORKFLOW_MANAGER_GOVERNANCE_SCHEMA_VERSION,
+    outcome: recorded.outcome,
+    formal,
+    receipt: recorded.receipt,
+    event: recorded.event,
+  };
+}