ai-delivery-workflow 0.2.2 → 0.4.0

package/lib/workflow-manager-public/fonts/OFL-1.1.txt

@@ -0,0 +1,90 @@
+IBM Plex Font Software
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+The license is copied below and is also available at:
+https://openfontlicense.org
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply to any
+document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may include
+source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components
+as distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical writer
+or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components, in
+Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or in
+the appropriate machine-readable metadata fields within text or binary
+files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name
+as presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any Modified
+Version, except to acknowledge the contribution(s) of the Copyright
+Holder(s) and the Author(s) or with their explicit written permission.
+
+5) The Font Software, modified or unmodified, in part or in whole, must be
+distributed entirely under this license, and must not be distributed under
+any other license. The requirement for fonts to remain under this license
+does not apply to any document created using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are not
+met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF
+COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM OTHER
+DEALINGS IN THE FONT SOFTWARE.

package/lib/workflow-manager-public/index.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="color-scheme" content="light" />
+    <title>工作流管理器</title>
+    <script type="module" crossorigin src="/assets/index-E-hGB5ZD.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-Chlg6r8f.css">
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>

package/lib/workflow-manager-systems.mjs

@@ -0,0 +1,519 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import {
+  abortWorkflowManagerExternalEffect,
+  beginWorkflowManagerExternalEffect,
+  commitWorkflowManagerAction,
+  completeWorkflowManagerExternalEffect,
+  preflightWorkflowManagerAction,
+  publishWorkflowManagerExternalEffect,
+} 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");
+
+export const WORKFLOW_MANAGER_SYSTEMS_SCHEMA_VERSION = "workflow-manager.systems.v1";
+const REGISTRY_RELATIVE = ".workflow/project-systems/registry.yaml";
+const EVENTS_RELATIVE = ".workflow/control/events/workflow-manager-events.jsonl";
+const RECEIPTS_RELATIVE = ".workflow/control/receipts";
+
+function sha256(value) {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+function atomicWrite(file, content) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temporary = `${file}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  try {
+    fs.writeFileSync(temporary, content, "utf8");
+    fs.renameSync(temporary, file);
+  } finally {
+    fs.rmSync(temporary, { force: true });
+  }
+}
+
+function canonical(value) {
+  return YAML.stringify(value, { lineWidth: 0 });
+}
+
+function registryChecksum(registry) {
+  const copy = structuredClone(registry);
+  delete copy.checksum;
+  return sha256(canonical(copy));
+}
+
+function rootPath(projectRoot) {
+  return path.resolve(projectRoot);
+}
+
+function inside(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function contained(root, relative, label) {
+  if (typeof relative !== "string" || !relative.trim() || relative.includes("\0")
+    || path.posix.isAbsolute(relative) || relative.includes("\\")
+    || path.posix.normalize(relative) !== relative) {
+    throw new Error(`${label} must be a normalized project-relative POSIX path`);
+  }
+  const absolute = path.resolve(root, ...relative.split("/"));
+  if (!inside(root, absolute)) throw new Error(`${label} escapes project root: ${relative}`);
+  return absolute;
+}
+
+function currentBranch(root) {
+  const result = spawnSync("git", ["branch", "--show-current"], {
+    cwd: root, encoding: "utf8", windowsHide: true,
+  });
+  return result.status === 0 ? result.stdout.trim() || null : null;
+}
+
+function registryFile(root) {
+  return contained(root, REGISTRY_RELATIVE, "Project System Registry path");
+}
+
+function readRegistry(root) {
+  const file = registryFile(root);
+  if (!fs.existsSync(file)) return null;
+  let registry;
+  try { registry = YAML.parse(fs.readFileSync(file, "utf8")); } catch (error) {
+    throw new Error(`Project System Registry is invalid YAML: ${error.message}`);
+  }
+  if (!registry || registry.schema_version !== 1 || typeof registry.registry_id !== "string"
+    || !Number.isInteger(registry.revision) || registry.revision < 0 || !Array.isArray(registry.systems)) {
+    throw new Error("Project System Registry must declare schema_version 1, registry_id, revision, and systems");
+  }
+  const checksum = registryChecksum(registry);
+  if (!/^[a-f0-9]{64}$/.test(String(registry.checksum || "")) || registry.checksum !== checksum) {
+    throw new Error("Project System Registry checksum is missing or does not match its content");
+  }
+  return { file, registry, checksum };
+}
+
+function systemPaths(root, system) {
+  const initialization = system.initialization || {};
+  const scriptsRoot = initialization.scripts_root || null;
+  const dockerFiles = Array.isArray(system.docker_files) ? system.docker_files : [];
+  if (scriptsRoot) contained(root, scriptsRoot, `${system.system_id} scripts_root`);
+  for (const file of dockerFiles) {
+    contained(root, file, `${system.system_id} docker file`);
+    const name = path.posix.basename(file).toLowerCase();
+    if (!(name === "dockerfile" || name.endsWith(".dockerfile")
+      || name.endsWith(".compose.yaml") || name.endsWith(".compose.yml")
+      || name === "compose.yaml" || name === "compose.yml")) {
+      throw new Error(`${system.system_id} docker file must be a registered Dockerfile or Compose YAML: ${file}`);
+    }
+  }
+  const startupSource = system.start?.source;
+  if (system.implementation_status === "implemented" && typeof startupSource === "string"
+    && startupSource.startsWith(".workflow/") && !dockerFiles.includes(startupSource)) {
+    throw new Error(`${system.system_id} Docker startup source must be listed in docker_files`);
+  }
+  for (const importRoot of initialization.import_roots || []) {
+    contained(root, importRoot, `${system.system_id} initialization import_root`);
+  }
+  for (const script of Array.isArray(initialization.scripts) ? initialization.scripts : []) {
+    if (script.path) {
+      const absolute = contained(root, script.path, `${system.system_id} initialization script`);
+      if (scriptsRoot && !inside(contained(root, scriptsRoot, "scripts_root"), absolute)) {
+        throw new Error(`${system.system_id} initialization script is outside scripts_root: ${script.path}`);
+      }
+    }
+  }
+}
+
+function branchControl(system, branch) {
+  const policy = system.branch_policy || "current-branch-only";
+  if (system.implementation_status !== "implemented") {
+    return { available: false, reason: "system-not-implemented" };
+  }
+  if (policy === "read-only") return { available: false, reason: "branch-read-only" };
+  if (policy === "current-branch-only" && system.registered_branch && branch !== system.registered_branch) {
+    return { available: false, reason: "different-branch" };
+  }
+  return { available: true, reason: null };
+}
+
+function preview(root, relative) {
+  const file = contained(root, relative, "Docker source");
+  if (!fs.existsSync(file) || !fs.statSync(file).isFile()) {
+    return { path: relative, exists: false, checksum: null, content: null };
+  }
+  const bytes = fs.readFileSync(file);
+  if (bytes.length > 2 * 1024 * 1024) return { path: relative, exists: true, too_large: true, checksum: sha256(bytes), content: null };
+  return { path: relative, exists: true, checksum: sha256(bytes), content: bytes.toString("utf8") };
+}
+
+export function inspectWorkflowManagerSystems(projectRoot, options = {}) {
+  const root = rootPath(projectRoot);
+  const loaded = readRegistry(root);
+  if (!loaded) return {
+    schema_version: WORKFLOW_MANAGER_SYSTEMS_SCHEMA_VERSION,
+    registration_status: "not-registered", registry: null, systems: [], current_branch: options.branch || currentBranch(root),
+  };
+  const branch = options.branch || currentBranch(root);
+  const systems = loaded.registry.systems.map((system) => {
+    if (!system || typeof system.system_id !== "string") throw new Error("Project System Registry system_id is required");
+    systemPaths(root, system);
+    const control = branchControl(system, branch);
+    const dockerSources = (Array.isArray(system.docker_files) ? system.docker_files : [])
+      .map((file) => preview(root, file));
+    const scripts = Array.isArray(system.initialization?.scripts) ? system.initialization.scripts.map((script) => ({
+      ...script,
+      checksum: script.path && fs.existsSync(contained(root, script.path, "script"))
+        ? sha256(fs.readFileSync(contained(root, script.path, "script"))) : script.checksum || null,
+      content: script.path && fs.existsSync(contained(root, script.path, "script"))
+        && fs.statSync(contained(root, script.path, "script")).size <= 2 * 1024 * 1024
+        ? fs.readFileSync(contained(root, script.path, "script"), "utf8") : null,
+      too_large: script.path && fs.existsSync(contained(root, script.path, "script"))
+        ? fs.statSync(contained(root, script.path, "script")).size > 2 * 1024 * 1024 : false,
+      mutability: control.available ? "editable-with-plan" : "derived-read-only",
+    })) : [];
+    return {
+      system_id: system.system_id, name: system.name || system.system_id, kind: system.kind || "system",
+      implementation_status: system.implementation_status || "planned", status: system.implementation_status || "planned",
+      branch_policy: system.branch_policy || "current-branch-only", registered_branch: system.registered_branch || null,
+      control, start: system.start || { method: "docker", source: "workflow-default" },
+      health: system.health || null, docker_sources: dockerSources,
+      initialization: { scripts_root: system.initialization?.scripts_root || null, scripts },
+      mutability: "derived-read-only",
+    };
+  });
+  return {
+    schema_version: WORKFLOW_MANAGER_SYSTEMS_SCHEMA_VERSION, registration_status: "registered", current_branch: branch,
+    registry: { schema_version: loaded.registry.schema_version, registry_id: loaded.registry.registry_id,
+      revision: loaded.registry.revision, checksum: loaded.checksum, path: REGISTRY_RELATIVE },
+    systems,
+  };
+}
+
+function lifecycleCommand(system, operation) {
+  const source = system.start?.source;
+  if ((system.start?.method || "docker") !== "docker" || typeof source !== "string"
+      || !/\.compose\.ya?ml$|(^|\/)compose\.ya?ml$/i.test(source)) {
+    throw new Error(`System ${system.system_id} lifecycle requires a registered Docker Compose source`);
+  }
+  const tails = {
+    start: ["up", "-d"],
+    stop: ["stop"],
+    restart: ["restart"],
+    status: ["ps", "--format", "json"],
+  };
+  if (!tails[operation]) throw new Error(`Unsupported Project System lifecycle operation: ${operation}`);
+  return { executable: "docker", args: ["compose", "-f", source, ...tails[operation]] };
+}
+
+function lifecycleRequestChecksum(systemId, input, command, registry) {
+  return sha256(JSON.stringify({
+    system_id: systemId,
+    operation: input.operation,
+    branch: input.branch,
+    expected_registry_revision: input.expected_registry_revision,
+    expected_registry_checksum: input.expected_registry_checksum || null,
+    idempotency_key: input.idempotency_key || null,
+    command,
+    registry_checksum: registry.checksum,
+  }));
+}
+
+export function planWorkflowManagerSystemLifecycle(projectRoot, systemId, input = {}) {
+  const root = rootPath(projectRoot);
+  const loaded = readRegistry(root);
+  if (!loaded) return {
+    schema_version: WORKFLOW_MANAGER_SYSTEMS_SCHEMA_VERSION,
+    action: "plan-system-lifecycle", outcome: "not-registered", registration_status: "not-registered",
+  };
+  const system = findSystem(loaded, systemId);
+  const branch = input.branch || currentBranch(root);
+  const control = branchControl(system, branch);
+  if (!control.available) throw new Error(`System ${systemId} is read-only: ${control.reason}`);
+  if (input.expected_registry_revision !== loaded.registry.revision) throw new Error("Project System Registry revision mismatch");
+  if (input.expected_registry_checksum && input.expected_registry_checksum !== loaded.checksum) {
+    throw new Error("Project System Registry checksum mismatch");
+  }
+  const command = lifecycleCommand(system, input.operation);
+  const composeFile = contained(root, system.start.source, "Docker Compose source");
+  if (!fs.existsSync(composeFile) || !fs.statSync(composeFile).isFile()) {
+    throw new Error(`Registered Docker Compose source is missing: ${system.start.source}`);
+  }
+  const composeChecksum = sha256(fs.readFileSync(composeFile));
+  const result = {
+    schema_version: WORKFLOW_MANAGER_SYSTEMS_SCHEMA_VERSION,
+    action: "plan-system-lifecycle",
+    outcome: "planned",
+    system_id: systemId,
+    operation: input.operation,
+    branch,
+    engine: "docker-compose",
+    command,
+    compose_source: system.start.source,
+    compose_checksum: composeChecksum,
+    expected_registry_revision: input.expected_registry_revision,
+    expected_registry_checksum: input.expected_registry_checksum || loaded.checksum,
+    idempotency_key: input.idempotency_key || null,
+    affected_identities: [{ system_id: systemId }],
+    mutability: "plan-only",
+  };
+  result.plan_checksum = sha256(JSON.stringify({
+    ...result,
+    plan_checksum: undefined,
+    request_checksum: lifecycleRequestChecksum(systemId, { ...input, branch }, command, loaded),
+  }));
+  return result;
+}
+
+function parseLifecycleStatus(stdout) {
+  const text = String(stdout || "").trim();
+  if (!text) return { running: false, healthy: false, services: [] };
+  const documents = text.startsWith("[") ? JSON.parse(text) : text.split(/\r?\n/).filter(Boolean).map((line) => JSON.parse(line));
+  const services = (Array.isArray(documents) ? documents : [documents]).map((item) => ({
+    service: item.Service || item.Name || item.service || null,
+    state: item.State || item.Status || item.state || null,
+    health: item.Health || item.health || null,
+  }));
+  const running = services.length > 0 && services.every((item) => /running|up/i.test(String(item.state || "")));
+  const healthy = running && services.every((item) => !item.health || /healthy/i.test(String(item.health)));
+  return { running, healthy, services };
+}
+
+export function applyWorkflowManagerSystemLifecycle(projectRoot, systemId, input = {}, options = {}) {
+  const root = rootPath(projectRoot);
+  const replay = existingReceipt(root, input.idempotency_key);
+  if (replay && new Set(["system-lifecycle", "system-lifecycle-apply"]).has(replay.action)) {
+    if (replay.plan_checksum !== input.expected_plan_checksum) {
+      throw new Error("Project System lifecycle idempotency key was already used for a different plan");
+    }
+    return { schema_version: WORKFLOW_MANAGER_SYSTEMS_SCHEMA_VERSION, outcome: "idempotent-replay", receipt: replay };
+  }
+  const plan = planWorkflowManagerSystemLifecycle(root, systemId, input);
+  if (!input.expected_plan_checksum || input.expected_plan_checksum !== plan.plan_checksum) {
+    throw new Error("Project System lifecycle plan checksum mismatch");
+  }
+  const action = "system-lifecycle-apply";
+  const pending = beginWorkflowManagerExternalEffect(root, {
+    action, subject: systemId, input, planChecksum: plan.plan_checksum,
+  });
+  if (pending.record.status === "succeeded" || pending.record.status === "delivered") {
+    const recovered = publishWorkflowManagerExternalEffect(root, {
+      action, subject: systemId, input, planChecksum: plan.plan_checksum,
+      transactionHooks: options.transactionHooks, recovered: pending.record.status === "succeeded",
+    });
+    return {
+      schema_version: WORKFLOW_MANAGER_SYSTEMS_SCHEMA_VERSION,
+      outcome: recovered.outcome,
+      plan,
+      result: recovered.result,
+      receipt: recovered.receipt,
+      event: recovered.event || null,
+    };
+  }
+  const runner = options.runner || ((executable, args, settings) => spawnSync(executable, args, {
+    ...settings, encoding: "utf8", windowsHide: true, shell: false,
+  }));
+  let executed;
+  try {
+    executed = runner(plan.command.executable, plan.command.args, { cwd: root });
+    if (executed.error) throw new Error(`Docker Compose lifecycle failed: ${executed.error.message}`);
+    if (executed.status !== 0) throw new Error(`Docker Compose lifecycle failed: ${String(executed.stderr || "").trim() || `exit ${executed.status}`}`);
+  } catch (error) {
+    abortWorkflowManagerExternalEffect(pending);
+    throw error;
+  }
+  const result = input.operation === "status"
+    ? parseLifecycleStatus(executed.stdout)
+    : { running: input.operation !== "stop", healthy: null, services: [], output: String(executed.stdout || "").trim() || null };
+  const completed = completeWorkflowManagerExternalEffect(pending, {
+    result,
+    detail: {
+      system_id: systemId,
+      operation: input.operation,
+      branch: plan.branch,
+      compose_checksum: plan.compose_checksum,
+      affected_identities: plan.affected_identities,
+    },
+    receiptPrefix: "WMS",
+    eventType: "workflow-manager.system-lifecycle-applied",
+  });
+  const recorded = publishWorkflowManagerExternalEffect(root, {
+    action, subject: systemId, input, planChecksum: plan.plan_checksum,
+    transactionHooks: options.transactionHooks,
+  });
+  return {
+    schema_version: WORKFLOW_MANAGER_SYSTEMS_SCHEMA_VERSION,
+    outcome: recorded.outcome,
+    plan,
+    result,
+    receipt: recorded.receipt,
+    event: recorded.event,
+    outbox_status: completed.record.status,
+  };
+}
+
+function findSystem(loaded, systemId) {
+  const system = loaded.registry.systems.find((item) => item?.system_id === systemId);
+  if (!system) throw new Error(`Project System is not registered: ${systemId}`);
+  systemPaths(path.dirname(path.dirname(path.dirname(loaded.file))), system);
+  return system;
+}
+
+function existingReceipt(root, idempotencyKey) {
+  if (!idempotencyKey || !fs.existsSync(path.join(root, RECEIPTS_RELATIVE))) return null;
+  for (const name of fs.readdirSync(path.join(root, RECEIPTS_RELATIVE))) {
+    if (!name.endsWith(".json")) continue;
+    try {
+      const receipt = JSON.parse(fs.readFileSync(path.join(root, RECEIPTS_RELATIVE, name), "utf8"));
+      if (receipt.idempotency_key === idempotencyKey) return receipt;
+    } catch { /* ignore unrelated receipts */ }
+  }
+  return null;
+}
+
+function scriptTarget(root, system, input) {
+  const scriptsRoot = system.initialization?.scripts_root;
+  if (!scriptsRoot) throw new Error(`System ${system.system_id} does not declare initialization scripts_root`);
+  const rootDir = contained(root, scriptsRoot, "initialization scripts_root");
+  const declared = (system.initialization?.scripts || []).find((script) => script.script_id === input.script_id);
+  const relative = input.path || declared?.path || `${scriptsRoot}/${input.script_id}.sql`;
+  const target = contained(root, relative, "initialization script path");
+  if (!inside(rootDir, target)) throw new Error("Initialization script path must remain inside the declared scripts root");
+  return { relative, target, declared };
+}
+
+function scriptContent(root, input) {
+  if (typeof input.content === "string") return input.content;
+  if (input.source_path) {
+    const source = contained(root, input.source_path, "initialization import source");
+    if (!fs.existsSync(source) || !fs.statSync(source).isFile()) throw new Error(`Initialization import source is missing: ${input.source_path}`);
+    return fs.readFileSync(source, "utf8");
+  }
+  throw new Error("Initialization script requires content or project-relative source_path");
+}
+
+function requireImportAllowed(root, system, sourcePath) {
+  if (!sourcePath) return;
+  const source = contained(root, sourcePath, "initialization import source");
+  const roots = (system.initialization?.import_roots || []).map((item) =>
+    contained(root, item, "initialization import_root"));
+  if (!roots.some((importRoot) => inside(importRoot, source))) {
+    throw new Error("Initialization import source must remain inside registry-declared import_roots");
+  }
+}
+
+function requestChecksum(systemId, input, pathRef, content) {
+  return sha256(JSON.stringify({ system_id: systemId, script_id: input.script_id,
+    path: pathRef, content, actor: input.actor || "agent:workflow-manager", branch: input.branch || null }));
+}
+
+export function planWorkflowManagerInitializationScript(projectRoot, systemId, input = {}) {
+  const root = rootPath(projectRoot); const loaded = readRegistry(root);
+  if (!loaded) return { schema_version: WORKFLOW_MANAGER_SYSTEMS_SCHEMA_VERSION, outcome: "not-registered", registration_status: "not-registered", action: "plan-initialization-script" };
+  const system = findSystem(loaded, systemId); const branch = input.branch || currentBranch(root); const control = branchControl(system, branch);
+  if (!control.available) throw new Error(`System ${systemId} is read-only: ${control.reason}`);
+  requireImportAllowed(root, system, input.source_path);
+  const target = scriptTarget(root, system, input); const content = scriptContent(root, input); const checksum = sha256(content);
+  const currentChecksum = fs.existsSync(target.target) ? sha256(fs.readFileSync(target.target)) : null;
+  return {
+    schema_version: WORKFLOW_MANAGER_SYSTEMS_SCHEMA_VERSION, action: "plan-initialization-script", system_id: systemId,
+    script_id: input.script_id, path: target.relative, branch, expected_registry_revision: input.expected_registry_revision,
+    current_registry_revision: loaded.registry.revision, expected_registry_checksum: input.expected_registry_checksum || loaded.checksum,
+    current_registry_checksum: loaded.checksum, expected_script_checksum: currentChecksum,
+    planned_script_checksum: checksum, idempotency_key: input.idempotency_key || null,
+    affected_identities: [{ system_id: systemId, script_id: input.script_id }],
+    content_bytes: Buffer.byteLength(content), mutability: "plan-only",
+  };
+}
+
+export function applyWorkflowManagerInitializationScript(projectRoot, systemId, input = {}, options = {}) {
+  const root = rootPath(projectRoot); const loaded = readRegistry(root);
+  if (!loaded) return { schema_version: WORKFLOW_MANAGER_SYSTEMS_SCHEMA_VERSION, outcome: "not-registered", registration_status: "not-registered", action: "apply-initialization-script" };
+  const system = findSystem(loaded, systemId); const branch = input.branch || currentBranch(root); const control = branchControl(system, branch);
+  if (!control.available) throw new Error(`System ${systemId} is read-only: ${control.reason}`);
+  requireImportAllowed(root, system, input.source_path);
+  const target = scriptTarget(root, system, input); const content = scriptContent(root, input); const checksum = sha256(content);
+  const request = requestChecksum(systemId, { ...input, branch }, target.relative, content);
+  const transactionInput = {
+    system_id: systemId,
+    script_id: input.script_id,
+    name: input.name || input.script_id,
+    path: target.relative,
+    source_path: input.source_path || null,
+    content,
+    actor: input.actor,
+    branch,
+    idempotency_key: input.idempotency_key,
+  };
+  const sharedReplay = preflightWorkflowManagerAction(root, {
+    action: "apply-initialization-script",
+    subject: `${systemId}:${input.script_id}`,
+    input: transactionInput,
+  });
+  if (sharedReplay) return { schema_version: WORKFLOW_MANAGER_SYSTEMS_SCHEMA_VERSION, outcome: "idempotent-replay", receipt: sharedReplay, result: sharedReplay.result };
+  const replay = existingReceipt(root, input.idempotency_key);
+  if (replay) {
+    if (replay.request_checksum !== request) throw new Error("Idempotency key was already used for a different request");
+    return { schema_version: WORKFLOW_MANAGER_SYSTEMS_SCHEMA_VERSION, outcome: "idempotent-replay", receipt: replay };
+  }
+  if (input.expected_registry_revision !== loaded.registry.revision) throw new Error("Project System Registry revision mismatch");
+  if (input.expected_registry_checksum && input.expected_registry_checksum !== loaded.checksum) throw new Error("Project System Registry checksum mismatch");
+  const actual = fs.existsSync(target.target) ? sha256(fs.readFileSync(target.target)) : null;
+  if (input.expected_script_checksum && input.expected_script_checksum !== actual) throw new Error("Initialization script checksum mismatch");
+  const next = structuredClone(loaded.registry); next.revision += 1; const entry = next.systems.find((item) => item.system_id === systemId);
+  entry.initialization ||= { scripts_root: system.initialization.scripts_root, scripts: [] }; entry.initialization.scripts ||= [];
+  const script = entry.initialization.scripts.find((item) => item.script_id === input.script_id) || { script_id: input.script_id, name: input.name || input.script_id, path: target.relative };
+  script.path = target.relative;
+  script.name = input.name || script.name || input.script_id;
+  script.checksum = checksum;
+  if (input.source_path) script.source_path = input.source_path;
+  else delete script.source_path;
+  if (!entry.initialization.scripts.includes(script)) entry.initialization.scripts.push(script);
+  delete next.checksum; next.checksum = registryChecksum(next);
+  const result = {
+    system_id: systemId,
+    script_id: input.script_id,
+    path: target.relative,
+    source_path: input.source_path || null,
+    script_checksum: checksum,
+    current_registry_revision: next.revision,
+    current_registry_checksum: next.checksum,
+  };
+  const recorded = commitWorkflowManagerAction(root, {
+    action: "apply-initialization-script",
+    subject: `${systemId}:${input.script_id}`,
+    input: transactionInput,
+    result,
+    detail: {
+      system_id: systemId,
+      script_id: input.script_id,
+      path: target.relative,
+      branch,
+      expected_registry_revision: loaded.registry.revision,
+      expected_registry_checksum: loaded.checksum,
+      current_registry_revision: next.revision,
+      current_registry_checksum: next.checksum,
+      script_checksum: checksum,
+      affected_identities: [{ system_id: systemId, script_id: input.script_id }],
+    },
+    writes: [
+      { file: target.target, content },
+      { file: loaded.file, content: canonical(next) },
+    ],
+    receiptPrefix: "WMS",
+    eventType: "workflow-manager.initialization-script-applied",
+    transactionHooks: options.transactionHooks,
+  });
+  return {
+    schema_version: WORKFLOW_MANAGER_SYSTEMS_SCHEMA_VERSION,
+    outcome: recorded.outcome,
+    action: "apply-initialization-script",
+    receipt: recorded.receipt,
+    event: recorded.event,
+    ...result,
+  };
+}