ai-delivery-workflow 0.2.2 → 0.4.0

package/lib/workflow-manager-transaction.mjs

@@ -0,0 +1,397 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+const RECEIPTS_ROOT = ".workflow/control/receipts";
+const EVENTS_FILE = ".workflow/control/events/workflow-manager-events.jsonl";
+const OUTBOX_ROOT = ".workflow/control/outbox";
+
+export function stableWorkflowManagerValue(value) {
+  if (Array.isArray(value)) return value.map(stableWorkflowManagerValue);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.keys(value).sort()
+      .map((key) => [key, stableWorkflowManagerValue(value[key])]));
+  }
+  return value;
+}
+
+export function workflowManagerChecksum(value) {
+  const bytes = Buffer.isBuffer(value) || typeof value === "string"
+    ? value
+    : JSON.stringify(stableWorkflowManagerValue(value));
+  return crypto.createHash("sha256").update(bytes).digest("hex");
+}
+
+function contained(root, relative, label) {
+  const absolute = path.resolve(root, ...String(relative).replaceAll("\\", "/").split("/"));
+  const relation = path.relative(root, absolute);
+  if (!relation || relation.startsWith("..") || path.isAbsolute(relation)) {
+    throw new Error(`${label} escapes the project`);
+  }
+  return absolute;
+}
+
+function receiptFiles(root) {
+  const directory = contained(root, RECEIPTS_ROOT, "Workflow Manager receipt directory");
+  if (!fs.existsSync(directory)) return [];
+  return fs.readdirSync(directory, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+    .map((entry) => path.join(directory, entry.name))
+    .sort();
+}
+
+export function workflowManagerRequestChecksum(action, input, subject = null) {
+  return workflowManagerChecksum({ action, subject, input });
+}
+
+export function preflightWorkflowManagerAction(projectRoot, { action, input, subject = null }) {
+  const root = path.resolve(projectRoot);
+  if (!input?.idempotency_key) return null;
+  const expected = workflowManagerRequestChecksum(action, input, subject);
+  for (const file of receiptFiles(root)) {
+    let receipt;
+    try { receipt = JSON.parse(fs.readFileSync(file, "utf8")); } catch { continue; }
+    if (receipt.idempotency_key !== input.idempotency_key) continue;
+    if (receipt.action !== action || (receipt.subject ?? null) !== subject
+        || receipt.request_checksum !== expected) {
+      throw new Error("Idempotency key was already used for a different request");
+    }
+    return receipt;
+  }
+  return null;
+}
+
+function atomicWriteSet(entries, hooks = {}) {
+  const unique = new Set();
+  for (const entry of entries) {
+    if (unique.has(entry.file)) throw new Error(`Workflow Manager transaction has duplicate target: ${entry.file}`);
+    unique.add(entry.file);
+  }
+  const snapshots = entries.map((entry) => ({
+    file: entry.file,
+    existed: fs.existsSync(entry.file),
+    content: fs.existsSync(entry.file) ? fs.readFileSync(entry.file) : null,
+  }));
+  const temporary = [];
+  try {
+    for (const entry of entries) {
+      fs.mkdirSync(path.dirname(entry.file), { recursive: true });
+      const temp = `${entry.file}.${process.pid}.${crypto.randomUUID()}.tmp`;
+      fs.writeFileSync(temp, entry.content, { flag: "wx" });
+      temporary.push({ file: entry.file, temp });
+    }
+    for (const [index, entry] of temporary.entries()) {
+      hooks.beforeRename?.({ index, file: entry.file, temporary: entry.temp });
+      fs.renameSync(entry.temp, entry.file);
+      hooks.afterRename?.({ index, file: entry.file });
+    }
+  } catch (error) {
+    for (const entry of temporary) fs.rmSync(entry.temp, { force: true });
+    for (const snapshot of snapshots.reverse()) {
+      if (snapshot.existed) {
+        fs.mkdirSync(path.dirname(snapshot.file), { recursive: true });
+        fs.writeFileSync(snapshot.file, snapshot.content);
+      } else {
+        fs.rmSync(snapshot.file, { force: true });
+      }
+    }
+    throw error;
+  }
+}
+
+export function commitWorkflowManagerAction(projectRoot, {
+  action,
+  input,
+  subject = null,
+  result = null,
+  detail = {},
+  writes = [],
+  receiptPrefix = "WM",
+  eventType = `workflow-manager.${action}`,
+  eventDetail = {},
+  timestamp = new Date().toISOString(),
+  transactionHooks = {},
+}) {
+  const root = path.resolve(projectRoot);
+  const replay = preflightWorkflowManagerAction(root, { action, input, subject });
+  if (replay) return { outcome: "idempotent-replay", receipt: replay, result: replay.result };
+  const receipt = {
+    schema_version: 1,
+    receipt_id: `${receiptPrefix}-${crypto.randomUUID()}`,
+    action,
+    subject,
+    actor: input.actor,
+    idempotency_key: input.idempotency_key || null,
+    request_checksum: workflowManagerRequestChecksum(action, input, subject),
+    outcome: "applied",
+    result,
+    applied_at: timestamp,
+    ...detail,
+  };
+  receipt.receipt_checksum = workflowManagerChecksum(receipt);
+  const event = {
+    schema_version: 1,
+    event_id: `WME-${crypto.randomUUID()}`,
+    type: eventType,
+    occurred_at: timestamp,
+    receipt_id: receipt.receipt_id,
+    subject,
+    ...eventDetail,
+  };
+  const eventFile = contained(root, EVENTS_FILE, "Workflow Manager event file");
+  const previousEvents = fs.existsSync(eventFile) ? fs.readFileSync(eventFile, "utf8") : "";
+  const receiptFile = contained(root, `${RECEIPTS_ROOT}/${receipt.receipt_id}.json`, "Workflow Manager receipt");
+  const governedWrites = writes.map((entry) => {
+    const file = path.resolve(entry.file);
+    const relative = path.relative(root, file);
+    if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+      throw new Error("Workflow Manager transaction target escapes the project");
+    }
+    return { file, content: entry.content };
+  });
+  atomicWriteSet([
+    ...governedWrites,
+    { file: receiptFile, content: `${JSON.stringify(receipt, null, 2)}\n` },
+    { file: eventFile, content: `${previousEvents}${JSON.stringify(event)}\n` },
+  ], transactionHooks);
+  return { outcome: "applied", result, receipt, event };
+}
+
+export function prepareWorkflowManagerFormalTransaction(projectRoot, {
+  action,
+  input,
+  subject = null,
+  resultFactory,
+  detailFactory = () => ({}),
+  receiptPrefix = "WM",
+  eventType = `workflow-manager.${action}`,
+  eventDetail = {},
+  timestamp = new Date().toISOString(),
+}) {
+  const root = path.resolve(projectRoot);
+  if (typeof resultFactory !== "function") {
+    throw new Error("Formal Workflow Manager transaction requires a result factory");
+  }
+  let prepared = null;
+  const factory = (formalContext) => {
+    if (prepared) throw new Error("Formal Workflow Manager transaction factory may only run once");
+    const result = resultFactory(formalContext);
+    const detail = detailFactory(formalContext, result) || {};
+    const receipt = {
+      schema_version: 1,
+      receipt_id: `${receiptPrefix}-${crypto.randomUUID()}`,
+      action,
+      subject,
+      actor: input.actor,
+      idempotency_key: input.idempotency_key || null,
+      request_checksum: workflowManagerRequestChecksum(action, input, subject),
+      outcome: "applied",
+      result,
+      applied_at: timestamp,
+      ...detail,
+    };
+    receipt.receipt_checksum = workflowManagerChecksum(receipt);
+    const event = {
+      schema_version: 1,
+      event_id: `WME-${crypto.randomUUID()}`,
+      type: eventType,
+      occurred_at: timestamp,
+      receipt_id: receipt.receipt_id,
+      subject,
+      ...eventDetail,
+    };
+    const eventFile = contained(root, EVENTS_FILE, "Workflow Manager event file");
+    const previousEvents = fs.existsSync(eventFile) ? fs.readFileSync(eventFile, "utf8") : "";
+    const receiptFile = contained(root, `${RECEIPTS_ROOT}/${receipt.receipt_id}.json`, "Workflow Manager receipt");
+    prepared = { outcome: "applied", result, receipt, event };
+    return [
+      { file: receiptFile, content: `${JSON.stringify(receipt, null, 2)}\n` },
+      { file: eventFile, content: `${previousEvents}${JSON.stringify(event)}\n` },
+    ];
+  };
+  return {
+    factory,
+    result() {
+      if (!prepared) throw new Error("Formal Workflow Manager transaction did not prepare its Receipt/Event");
+      return prepared;
+    },
+  };
+}
+
+export function prepareWorkflowManagerTaskTransactionWrites(projectRoot, descriptor, taskResult, timestamp = new Date().toISOString()) {
+  const root = path.resolve(projectRoot);
+  if (!descriptor || descriptor.schema_version !== 1 || descriptor.action !== "task-apply") {
+    throw new Error("Task Writer Manager transaction descriptor is invalid");
+  }
+  const input = descriptor.input;
+  const subject = descriptor.subject;
+  if (!input || typeof input !== "object" || Array.isArray(input)
+      || subject !== input.task_id || taskResult?.task_id !== subject) {
+    throw new Error("Task Writer Manager transaction identity is invalid");
+  }
+  if (!/^(human|agent):[A-Za-z0-9._@/-]+$/.test(String(input.actor || ""))
+      || !String(input.idempotency_key || "").trim()) {
+    throw new Error("Task Writer Manager transaction actor or idempotency key is invalid");
+  }
+  if (!Number.isInteger(input.expected_shared_revision) || input.expected_shared_revision < 0
+      || taskResult.shared_revision !== input.expected_shared_revision + 1) {
+    throw new Error("Task Writer shared revision mismatch");
+  }
+  const result = { task: structuredClone(taskResult) };
+  const receipt = {
+    schema_version: 1,
+    receipt_id: `WM-TASK-${crypto.randomUUID()}`,
+    action: "task-apply",
+    subject,
+    actor: input.actor,
+    idempotency_key: input.idempotency_key,
+    request_checksum: workflowManagerRequestChecksum("task-apply", input, subject),
+    outcome: "applied",
+    result,
+    input_revision: input.expected_shared_revision,
+    output_revision: taskResult.shared_revision,
+    affected_identities: [subject],
+    delegated_writer: "task-state.mjs",
+    applied_at: timestamp,
+  };
+  receipt.receipt_checksum = workflowManagerChecksum(receipt);
+  const event = {
+    schema_version: 1,
+    event_id: `WME-${crypto.randomUUID()}`,
+    type: "workflow-manager.task-apply",
+    occurred_at: timestamp,
+    receipt_id: receipt.receipt_id,
+    subject,
+  };
+  const eventFile = contained(root, EVENTS_FILE, "Workflow Manager event file");
+  const previousEvents = fs.existsSync(eventFile) ? fs.readFileSync(eventFile, "utf8") : "";
+  const receiptFile = contained(root, `${RECEIPTS_ROOT}/${receipt.receipt_id}.json`, "Workflow Manager receipt");
+  return {
+    outcome: "applied",
+    result,
+    receipt,
+    event,
+    writes: [
+      { file: receiptFile, content: `${JSON.stringify(receipt, null, 2)}\n` },
+      { file: eventFile, content: `${previousEvents}${JSON.stringify(event)}\n` },
+    ],
+  };
+}
+
+function externalEffectOutboxFile(root, action, idempotencyKey) {
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(String(action || ""))
+      || !String(idempotencyKey || "").trim()) {
+    throw new Error("External effect outbox requires a safe action and idempotency key");
+  }
+  const identity = workflowManagerChecksum(`${action}:${idempotencyKey}`);
+  return contained(root, `${OUTBOX_ROOT}/${action}/${identity}.json`, "Workflow Manager outbox file");
+}
+
+function writeOutbox(file, record) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temporary = `${file}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  fs.writeFileSync(temporary, `${JSON.stringify(record, null, 2)}\n`, { encoding: "utf8", flag: "wx" });
+  try { fs.renameSync(temporary, file); } finally { fs.rmSync(temporary, { force: true }); }
+}
+
+function readExternalEffectOutbox(root, action, input, subject, planChecksum) {
+  const file = externalEffectOutboxFile(root, action, input.idempotency_key);
+  if (!fs.existsSync(file)) return null;
+  let record;
+  try { record = JSON.parse(fs.readFileSync(file, "utf8")); } catch (error) {
+    throw new Error(`Workflow Manager external effect outbox is invalid: ${error.message}`);
+  }
+  const expectedRequest = workflowManagerRequestChecksum(action, input, subject);
+  if (record.action !== action || record.subject !== subject
+      || record.idempotency_key !== input.idempotency_key
+      || record.request_checksum !== expectedRequest
+      || record.plan_checksum !== planChecksum) {
+    throw new Error("External effect idempotency key was already used for a different request or plan");
+  }
+  return { file, record };
+}
+
+export function beginWorkflowManagerExternalEffect(projectRoot, {
+  action, subject = null, input, planChecksum,
+}) {
+  const root = path.resolve(projectRoot);
+  const existing = readExternalEffectOutbox(root, action, input, subject, planChecksum);
+  if (existing) return existing;
+  const file = externalEffectOutboxFile(root, action, input.idempotency_key);
+  const record = {
+    schema_version: 1,
+    action,
+    subject,
+    actor: input.actor,
+    idempotency_key: input.idempotency_key,
+    request_checksum: workflowManagerRequestChecksum(action, input, subject),
+    plan_checksum: planChecksum,
+    status: "prepared",
+    prepared_at: new Date().toISOString(),
+  };
+  writeOutbox(file, record);
+  return { file, record };
+}
+
+export function abortWorkflowManagerExternalEffect(prepared) {
+  if (prepared?.record?.status === "prepared" && prepared.file) fs.rmSync(prepared.file, { force: true });
+}
+
+export function completeWorkflowManagerExternalEffect(prepared, {
+  result,
+  detail = {},
+  receiptPrefix = "WM",
+  eventType,
+}) {
+  if (!prepared?.file || prepared.record?.status !== "prepared") {
+    throw new Error("Workflow Manager external effect is not prepared");
+  }
+  const record = {
+    ...prepared.record,
+    status: "succeeded",
+    result,
+    detail,
+    receipt_prefix: receiptPrefix,
+    event_type: eventType || `workflow-manager.${prepared.record.action}`,
+    succeeded_at: new Date().toISOString(),
+  };
+  writeOutbox(prepared.file, record);
+  return { file: prepared.file, record };
+}
+
+export function publishWorkflowManagerExternalEffect(projectRoot, {
+  action,
+  subject = null,
+  input,
+  planChecksum,
+  transactionHooks = {},
+  recovered = false,
+}) {
+  const root = path.resolve(projectRoot);
+  const pending = readExternalEffectOutbox(root, action, input, subject, planChecksum);
+  if (!pending) return null;
+  if (pending.record.status === "prepared") {
+    throw new Error("External effect outcome is unknown; inspect the external system before retrying");
+  }
+  if (pending.record.status !== "succeeded" && pending.record.status !== "delivered") {
+    throw new Error(`Unsupported external effect outbox status: ${pending.record.status}`);
+  }
+  if (pending.record.status === "delivered") {
+    const replay = preflightWorkflowManagerAction(root, { action, input, subject });
+    if (!replay) throw new Error("Delivered external effect is missing its Manager Receipt");
+    return { outcome: "idempotent-replay", result: replay.result, receipt: replay };
+  }
+  const delivered = { ...pending.record, status: "delivered", delivered_at: new Date().toISOString() };
+  const recorded = commitWorkflowManagerAction(root, {
+    action,
+    subject,
+    input,
+    result: pending.record.result,
+    detail: { ...pending.record.detail, plan_checksum: planChecksum },
+    writes: [{ file: pending.file, content: `${JSON.stringify(delivered, null, 2)}\n` }],
+    receiptPrefix: pending.record.receipt_prefix,
+    eventType: pending.record.event_type,
+    transactionHooks,
+  });
+  return { ...recorded, outcome: recovered ? "recovered" : recorded.outcome };
+}