@namewta/speculo 1.0.5 → 1.0.7

package/template/workflows/ops/common/tools/opslib/core.mjs

@@ -0,0 +1,393 @@
+/** OPS resource runtime primitives. Node standard library only. */
+import { createHash, randomBytes } from "node:crypto";
+import {
+  chmodSync, closeSync, existsSync, fsyncSync, linkSync, lstatSync, mkdirSync,
+  openSync, readFileSync, renameSync, rmSync, unlinkSync, writeSync,
+} from "node:fs";
+import { hostname } from "node:os";
+import { dirname, join, posix, win32 } from "node:path";
+import { spawnSync } from "node:child_process";
+
+export const VERSION = "2.2.0";
+const ID_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+export const SECRET_RE = /\{\{credential:([a-z0-9-]+)@([1-9][0-9]*):([A-Za-z_][A-Za-z0-9_]*)\}\}/g;
+
+export class OpsError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "OpsError";
+  }
+}
+
+export class UnknownResult extends OpsError {
+  constructor(message) {
+    super(message);
+    this.name = "UnknownResult";
+  }
+}
+
+export function now() {
+  return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+
+function sortKeys(value) {
+  if (Array.isArray(value)) return value.map(sortKeys);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.keys(value).sort().map((k) => [k, sortKeys(value[k])]));
+  }
+  return value;
+}
+
+export function assertJsonSafe(value) {
+  if (typeof value === "number" && !Number.isFinite(value)) {
+    throw new TypeError("Out of range float values are not JSON compliant");
+  }
+  if (Array.isArray(value)) value.forEach(assertJsonSafe);
+  else if (value && typeof value === "object") Object.values(value).forEach(assertJsonSafe);
+}
+
+export function canonical(value) {
+  assertJsonSafe(value);
+  return Buffer.from(JSON.stringify(sortKeys(value)), "utf8");
+}
+
+export function digest(value) {
+  const data = Buffer.isBuffer(value) ? value : canonical(value);
+  return createHash("sha256").update(data).digest("hex");
+}
+
+export function newId(prefix) {
+  const d = new Date();
+  const ts = [
+    d.getUTCFullYear(),
+    String(d.getUTCMonth() + 1).padStart(2, "0"),
+    String(d.getUTCDate()).padStart(2, "0"),
+    String(d.getUTCHours()).padStart(2, "0"),
+    String(d.getUTCMinutes()).padStart(2, "0"),
+    String(d.getUTCSeconds()).padStart(2, "0"),
+  ].join("");
+  return `${prefix}-${ts}-${randomBytes(4).toString("hex")}`;
+}
+
+export function identifier(value, label = "id") {
+  if (typeof value !== "string" || !ID_RE.test(value) || value.length > 80) {
+    throw new OpsError(`${label}: expected lowercase kebab id (1..80 characters)`);
+  }
+  if (/^(?:con|prn|aux|nul|com[0-9]|lpt[0-9])$/.test(value)) {
+    throw new OpsError(`${label}: Windows reserved name`);
+  }
+  return value;
+}
+
+function pyList(items) {
+  return `[${items.map((x) => `'${x}'`).join(", ")}]`;
+}
+
+export function exact(value, allowed, required, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new OpsError(`${label}: expected object`);
+  }
+  const unknown = Object.keys(value).filter((k) => !allowed.has(k)).sort();
+  if (unknown.length) throw new OpsError(`${label}: unknown fields: ${pyList(unknown)}`);
+  const missing = [...required].filter((k) => !(k in value)).sort();
+  if (missing.length) throw new OpsError(`${label}: missing fields: ${pyList(missing)}`);
+}
+
+function pyRepr(value) {
+  if (typeof value !== "string") return String(value);
+  return `'${value.replaceAll("\\", "\\\\").replaceAll("'", "\\'")}'`;
+}
+
+export function relative(value) {
+  if (typeof value !== "string" || !value || value.includes("\\") || value.includes("\x00") || value.includes(":")) {
+    throw new OpsError(`unsafe relative path: ${pyRepr(value)}`);
+  }
+  if (value.startsWith("/") || value.split("/").some((x) => x === "" || x === "." || x === "..")) {
+    throw new OpsError(`unsafe relative path: ${pyRepr(value)}`);
+  }
+  return value;
+}
+
+function adapter(platform) {
+  return platform === "windows" ? win32 : posix;
+}
+
+export function rootPath(value, platform) {
+  const p = adapter(platform);
+  if (typeof value !== "string" || value.includes("\x00") || !p.isAbsolute(value) || value.split(/[\\/]/).includes("..")) {
+    throw new OpsError("host root must be an absolute, non-traversing path");
+  }
+  const n = p.normalize(value);
+  if (platform === "windows") {
+    if (n.startsWith("\\\\") || p.parse(n).root === n || n.slice(2).includes(":")) {
+      throw new OpsError("UNC, drive root and ADS paths are not host roots");
+    }
+    const parts = n.split(/[\\/]/).filter(Boolean);
+    if (parts.length < 2) throw new OpsError("UNC, drive root and ADS paths are not host roots");
+    const lower = n.toLowerCase().replace(/\\+$/, "");
+    if (["c:\\windows", "c:\\program files", "c:\\users", "c:\\programdata"].includes(lower)) {
+      throw new OpsError("a system directory cannot be host_root");
+    }
+    return n;
+  }
+  if (["/", "/etc", "/usr", "/var", "/home", "/root", "/tmp", "/srv", "/opt", "/mnt"].includes(n)) {
+    throw new OpsError("host_root must be an OPS-specific child directory");
+  }
+  return n;
+}
+
+export function targetJoin(host, ...parts) {
+  const p = adapter(host.platform);
+  let cur = host.root;
+  for (const part of parts) cur = p.join(cur, ...relative(part).split("/"));
+  return cur;
+}
+
+export function within(path, root, platform) {
+  const p = adapter(platform);
+  if (!p.isAbsolute(path) || path.split(/[\\/]/).includes("..")) return false;
+  const rel = p.relative(root, path);
+  if (!rel || rel.startsWith("..") || p.isAbsolute(rel)) return false;
+  return true;
+}
+
+export function noSymlinks(path, { allowMissing = true } = {}) {
+  const chain = [];
+  let cur = path;
+  while (true) {
+    chain.unshift(cur);
+    const parent = dirname(cur);
+    if (parent === cur) break;
+    cur = parent;
+  }
+  for (const q of chain) {
+    let st;
+    try {
+      st = lstatSync(q);
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        if (allowMissing) continue;
+        throw new OpsError(`missing path: ${q}`);
+      }
+      throw error;
+    }
+    if (st.isSymbolicLink()) throw new OpsError(`symlink/reparse point rejected: ${q}`);
+  }
+}
+
+export function secure(path, directory = false) {
+  if (process.platform !== "win32") {
+    chmodSync(path, directory ? 0o700 : 0o600);
+    return;
+  }
+  const who = spawnSync("whoami", ["/user", "/fo", "csv", "/nh"], { encoding: "utf8" });
+  if (who.status !== 0) throw new Error(who.stderr);
+  const sid = who.stdout.trim().split(",").at(-1).replaceAll('"', "");
+  const flags = directory ? "(OI)(CI)F" : "F";
+  const ic = spawnSync("icacls", [path, "/inheritance:r", "/grant:r", `*${sid}:${flags}`, "*S-1-5-18:F"], { encoding: "utf8" });
+  if (ic.status !== 0) throw new Error(ic.stderr);
+}
+
+export function privateDir(path) {
+  noSymlinks(path);
+  const missing = [];
+  let p = path;
+  while (!existsSync(p)) {
+    missing.push(p);
+    const next = dirname(p);
+    if (next === p) break;
+    p = next;
+  }
+  for (const d of missing.reverse()) {
+    mkdirSync(d, { mode: 0o700 });
+    secure(d, true);
+  }
+  if (existsSync(path)) secure(path, true);
+}
+
+export function atomicWrite(path, data, mode = 0o600, { exclusive = false } = {}) {
+  const buf = Buffer.isBuffer(data) ? data : Buffer.from(String(data), "utf8");
+  noSymlinks(path);
+  privateDir(dirname(path));
+  if (exclusive && existsSync(path)) throw new OpsError(`immutable artifact already exists: ${path}`);
+  const tmp = join(dirname(path), `.ops-write-${randomBytes(6).toString("hex")}`);
+  const fd = openSync(tmp, "w");
+  try {
+    writeSync(fd, buf);
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+  try {
+    if (process.platform === "win32") secure(tmp);
+    else chmodSync(tmp, mode);
+    if (exclusive) {
+      try {
+        linkSync(tmp, path);
+      } catch (error) {
+        if (error.code === "EEXIST") throw new OpsError(`immutable artifact already exists: ${path}`);
+        throw error;
+      }
+      unlinkSync(tmp);
+    } else {
+      try {
+        renameSync(tmp, path);
+      } catch (error) {
+        if (process.platform === "win32" && (error.code === "EEXIST" || error.code === "EPERM" || error.code === "EACCES")) {
+          unlinkSync(path);
+          renameSync(tmp, path);
+        } else {
+          throw error;
+        }
+      }
+    }
+    if (process.platform !== "win32") chmodSync(path, mode);
+  } catch (error) {
+    try { unlinkSync(tmp); } catch {}
+    throw error;
+  }
+}
+
+export function writeJson(path, value, { exclusive = false } = {}) {
+  assertJsonSafe(value);
+  atomicWrite(path, `${JSON.stringify(value, null, 2)}\n`, 0o600, { exclusive });
+}
+
+function assertNoDuplicateKeys(text) {
+  let i = 0;
+  const n = text.length;
+  const skip = () => { while (i < n && /\s/.test(text[i])) i++; };
+  function parseString() {
+    i++;
+    while (i < n) {
+      if (text[i] === "\\") { i += 2; continue; }
+      if (text[i] === '"') { i++; return; }
+      i++;
+    }
+    throw new Error("Unterminated string");
+  }
+  function parseValue() {
+    skip();
+    const c = text[i];
+    if (c === "{") return parseObject();
+    if (c === "[") {
+      i++; skip();
+      if (text[i] === "]") { i++; return; }
+      while (true) {
+        parseValue(); skip();
+        if (text[i] === ",") { i++; continue; }
+        if (text[i] === "]") { i++; return; }
+        throw new Error("Invalid array");
+      }
+    }
+    if (c === '"') return parseString();
+    if (c === "t" || c === "f" || c === "n") { while (i < n && /[a-z]/.test(text[i])) i++; return; }
+    if (c === "-" || (c >= "0" && c <= "9")) { while (i < n && /[0-9eE+.\-]/.test(text[i])) i++; return; }
+    throw new Error("Invalid JSON");
+  }
+  function parseObject() {
+    i++; skip();
+    const seen = new Set();
+    if (text[i] === "}") { i++; return; }
+    while (true) {
+      skip();
+      if (text[i] !== '"') throw new Error("Expected key");
+      const start = i;
+      parseString();
+      const key = JSON.parse(text.slice(start, i));
+      if (seen.has(key)) throw new Error(`duplicate JSON key: ${key}`);
+      seen.add(key);
+      skip();
+      if (text[i] !== ":") throw new Error("Expected colon");
+      i++;
+      parseValue();
+      skip();
+      if (text[i] === ",") { i++; continue; }
+      if (text[i] === "}") { i++; return; }
+      throw new Error("Expected comma");
+    }
+  }
+  parseValue();
+}
+
+export function readJson(path) {
+  noSymlinks(path, { allowMissing: false });
+  const text = readFileSync(path, "utf8");
+  try {
+    if (/\bNaN\b|\bInfinity\b/.test(text.replace(/"(?:\\.|[^"\\])*"/g, '""'))) {
+      throw new Error("nonfinite");
+    }
+    assertNoDuplicateKeys(text);
+    return JSON.parse(text);
+  } catch (error) {
+    throw new OpsError(`invalid JSON: ${path}: ${error.message}`);
+  }
+}
+
+export function withLock(path, owner, fn) {
+  privateDir(dirname(path));
+  try {
+    mkdirSync(path, { mode: 0o700 });
+  } catch (error) {
+    if (error.code === "EEXIST") throw new OpsError(`lock-held: ${path}; inspect owner, never auto-break`);
+    throw error;
+  }
+  writeJson(join(path, "owner.json"), { ...owner, pid: process.pid, machine: hostname(), at: now() });
+  try {
+    return fn();
+  } finally {
+    try { unlinkSync(join(path, "owner.json")); } catch {}
+    try { rmSync(path, { recursive: true, force: true }); } catch {}
+  }
+}
+
+export function redact(text, secrets) {
+  for (const value of [...new Set(secrets)].sort((a, b) => b.length - a.length)) {
+    if (value) text = text.split(value).join("[REDACTED]");
+  }
+  return text.replace(/(password|passwd|token|secret|access_key)(\s*[=:]\s*)[^\s,;]+/gi, "$1$2[REDACTED]");
+}
+
+export function credentialsIn(value) {
+  const found = new Set();
+  const re = new RegExp(SECRET_RE.source, "g");
+  let m;
+  const blob = JSON.stringify(value);
+  while ((m = re.exec(blob))) found.add(`${m[1]}@${m[2]}`);
+  return found;
+}
+
+export function resolveSecrets(value, ledger) {
+  if (typeof value === "string") {
+    return value.replace(new RegExp(SECRET_RE.source, "g"), (_w, cid, version, field) => {
+      const result = ledger?.entries?.[cid]?.[version]?.values?.[field];
+      if (result === undefined) throw new OpsError(`missing credential: ${cid}@${version}:${field}`);
+      if (typeof result !== "string") throw new OpsError("credential values must be strings");
+      return result;
+    });
+  }
+  if (Array.isArray(value)) return value.map((v) => resolveSecrets(v, ledger));
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, resolveSecrets(v, ledger)]));
+  }
+  return value;
+}
+
+export function emptyStatus() {
+  return {
+    schema_version: 3,
+    workflow: "ops",
+    revision: 0,
+    controller: null,
+    hosts: {},
+    projects: {},
+    deployments: {},
+    allocations: {},
+    bindings: {},
+    releases: {},
+    policies: { server_readme_credentials: false, server_operations: true, strict_docker_root: true },
+    updated_at: null,
+  };
+}
+
+export { withLock as lock };

package/template/workflows/ops/common/tools/opslib/docs.mjs

@@ -0,0 +1,252 @@
+/** Deterministic server/controller documentation and protected plaintext delivery bundles. */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { digest, now, OpsError, targetJoin } from "./core.mjs";
+
+export const STANDARD = `# OPS 部署与持久化规范
+
+APP 和公共服务同级：host_root/project_id。明确启用多实例时使用 project_id/instances/environment/instance。
+
+每个项目的 compose 或 service、env、config、data、logs、backups、releases 和 README 聚合在该项目目录。业务数据必须位于 data/component/purpose；不能回退到临时目录、代码目录、用户默认目录、匿名卷或命名卷。Docker 全局 data-root 另登记在 host_root/_runtime/docker；既有引擎迁移必须单独审批。
+
+README 记录实际版本、来源、主机、时间、路径、依赖、启停和备份恢复。它默认不含密码。OPERATIONS.md 和部署机明文账本按策略保存真实账号密码，权限必须限制；不得进入 Git、镜像构建上下文、Web 静态目录或普通日志。
+
+共享服务拥有物理数据；APP 只拥有获批的逻辑数据库、桶、命名空间和应用账号。复制 APP 目录不是共享依赖完整备份。卸载 APP 不删除公共服务、共享网络、逻辑资源或任何数据。单 APP 回滚不允许恢复整个共享实例。
+
+旧环境默认值恢复和健康验证失败不得清理原环境。缓存隔离不等于释放空间；禁止把 data/env/backups 或数据库持久日志当成垃圾。
+
+计划 → 明确批准 → 执行 → 实际验证 → 双边文档回执完成。远程断线意味着结果未知，不能重跑迁移或重新生成密码。
+`;
+
+function htmlEscape(s) {
+  return String(s).replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;");
+}
+
+export function code(value) {
+  return "<code>" + htmlEscape(value).replaceAll("\n", "<br>") + "</code>";
+}
+
+export function block(value, language = "json") {
+  const text = typeof value === "string" ? value : JSON.stringify(value, null, 2);
+  const ticks = "`".repeat(Math.max(3, Math.max(0, ...(text.match(/`+/g) || []).map((x) => x.length)) + 1));
+  return ticks + language + "\n" + text + "\n" + ticks + "\n";
+}
+
+export function pathFor(status, dep, relativeName) {
+  return targetJoin({ ...status.hosts[dep.host_id], root: dep.root }, relativeName);
+}
+
+export function credentialRefs(status, dep) {
+  const refs = new Set(dep.credential_refs);
+  for (const b of Object.values(status.bindings)) {
+    if (b.status === "active" && b.consumer_deployment_id === dep.deployment_id) refs.add(b.credential_ref);
+  }
+  for (const a of Object.values(status.allocations)) {
+    if (a.provider_deployment_id === dep.deployment_id && a.status !== "retired") refs.add(a.credential_ref);
+  }
+  return [...refs].sort();
+}
+
+export function credentialsText(refs, ledger) {
+  const out = ["## 明文账号密码\n", "本文件是受限明文交付，不是脱敏报告。只向获授权管理员及对应运行账户开放。\n"];
+  if (!refs.length) return [...out, "本部署没有登记密码凭据。密钥认证本身不存在登录密码；未知旧密码不能伪造。\n"].join("\n");
+  for (const ref of refs) {
+    const [cid, v] = ref.split("@");
+    const item = ledger.entries?.[cid]?.[v];
+    if (!item) throw new OpsError("document delivery blocked by missing credential: " + ref);
+    out.push("### " + ref + "\n", code(item.purpose) + "\n");
+    for (const [key, value] of Object.entries(item.values)) out.push("**" + key + "**\n", block(value, "text"));
+  }
+  return out.join("\n");
+}
+
+export function dependencies(status, dep) {
+  const lines = ["## 依赖与数据归属\n"];
+  const bindings = Object.values(status.bindings).filter((b) => b.consumer_deployment_id === dep.deployment_id && b.status === "active");
+  if (!bindings.length) lines.push("未登记共享或外部服务依赖；专用组件的数据仍归本项目目录。\n");
+  for (const b of bindings) {
+    lines.push("### " + b.component + " / " + b.binding_id + "\n", `模式：${b.mode}；端点：${code(b.endpoint)}；网络：${code(b.network)}。\n`);
+    if (b.mode === "shared") {
+      const a = status.allocations[b.allocation_id];
+      const provider = status.deployments[b.provider_deployment_id];
+      lines.push(`提供者：${provider.project_id} / ${provider.deployment_id}，主机 ${provider.host_id}；服务目录 ${code(provider.root)}。\n`);
+      lines.push(`逻辑资源：${code(a.resource_name)}（${a.resource_kind}）；数据组 ${a.data_group}；账号版本 ${a.credential_ref}；恢复粒度 ${a.recovery_scope}。\n`);
+      for (const storage of provider.storage) lines.push(`提供者物理路径：${code(storage.path)}（${storage.component}/${storage.purpose}）。\n`);
+      lines.push("公共服务的物理数据不复制到 APP 目录；单 APP 恢复不得覆盖其他消费者。\n");
+    }
+  }
+  const consumers = Object.values(status.bindings).filter((b) => b.provider_deployment_id === dep.deployment_id && b.status === "active");
+  if (consumers.length) {
+    lines.push("## 公共服务消费者\n\n| APP 实例 | 所在主机 | 分配 | 凭据版本 |\n|---|---|---|---|\n");
+    for (const b of consumers) {
+      const consumer = status.deployments[b.consumer_deployment_id];
+      lines.push(`| ${consumer.deployment_id} | ${consumer.host_id} | ${b.allocation_id} | ${b.credential_ref} |\n`);
+    }
+  }
+  return lines.join("\n");
+}
+
+export function deploymentReadme(status, dep, runId, generatedAt, { ledger = null, includeCredentials = false, controller = false } = {}) {
+  const host = status.hosts[dep.host_id];
+  const project = status.projects[dep.project_id];
+  const out = [
+    `# ${project.display_name} — ${dep.deployment_id}\n`,
+    `文档代次：${runId}；生成时间（UTC）：${generatedAt}。部署验证与双边交付以部署机对应运行记录和 docs-receipt.json 为准。\n`,
+    "## 部署事实\n\n| 项目 | 值 |\n|---|---|",
+    `| 主机 / 账户 | ${host.host_id} / ${code(host.connection.username ?? "本机执行账户")} |`,
+    `| 连接 | ${code(host.connection.hostname ?? "local")}，SSH 端口 ${host.connection.port ?? "不适用"} |`,
+    `| 类型 / 方式 | ${project.kind} / ${dep.method} |`,
+    `| 生命周期状态 | ${dep.status} |`,
+    `| 环境 / 实例 | ${dep.environment} / ${dep.instance} |`,
+    `| 计划版本 | ${code(dep.version)} |`,
+    `| 最后运行验证版本 | ${code(dep.observed_version || "尚未验证")} |`,
+    `| 首次部署时间（UTC） | ${dep.installed_at || "尚未完成"} |`,
+    `| 最近部署验证时间（UTC） | ${dep.updated_at || "尚未验证"} |`,
+    `| 项目根目录 | ${code(dep.root)} |`,
+    `| 来源 | ${code(dep.source.location)} |`,
+    `| 固定来源版本 | ${code(dep.source.revision)} |\n`,
+    "## 目录与持久化\n",
+    `部署定义：${code(dep.method === "compose" ? pathFor(status, dep, "compose/compose.yaml") : pathFor(status, dep, "service"))}。\n`,
+    `环境文件：${code(pathFor(status, dep, "env"))}；配置：${code(pathFor(status, dep, "config"))}。\n`,
+    `日志：${code(pathFor(status, dep, "logs"))}；发布历史：${code(pathFor(status, dep, "releases"))}；备份：${code(pathFor(status, dep, "backups"))}。\n`,
+    "| 组件 | 用途 | 自有持久化路径 |\n|---|---|---|",
+  ];
+  for (const p of dep.storage) out.push(`| ${p.component} | ${p.purpose} | ${code(p.path)} |`);
+  if (!dep.storage.length) out.push("| — | 无登记的业务持久化内容 | 不应生成匿名数据路径 |");
+  out.push("\n" + dependencies(status, dep), "## 日常操作\n");
+  for (const [title, key] of [["启动/运行", "start"], ["停止（保留数据）", "stop"], ["查看与验证", "verify"]]) {
+    out.push("### " + title + "\n");
+    if (!dep.commands[key].length) out.push("不适用或由已批准运行计划执行。\n");
+    for (const argv of dep.commands[key]) out.push(block(argv));
+  }
+  out.push(
+    "## 更新步骤\n",
+    "先盘点主机与依赖；固定版本；检查备份及恢复能力；生成新计划并确认；分批执行；验证运行与数据；核对服务端和部署机文档回执。不得直接删除 data/env/backups，也不得用旧批准授权新迁移。\n",
+    "## 备份\n", dep.backup + "\n", "## 恢复与回滚\n", dep.recovery + "\n",
+    "切换旧代码不能自动恢复数据库结构。共享服务整实例恢复需要全部消费者维护审批。\n",
+  );
+  if (dep.notes.length) out.push("## 限制与备注\n", dep.notes.join("\n\n") + "\n");
+  const replicas = Object.values(status.deployments).filter((d) => d.project_id === dep.project_id);
+  out.push("## 同项目部署位置\n", replicas.sort((a, b) => a.deployment_id < b.deployment_id ? -1 : 1).map((d) => `- ${d.host_id} / ${d.deployment_id}：${code(d.root)}`).join("\n") + "\n");
+  if (controller) out.push("\n本目录是部署机的配置、凭据、运行证据和远端文档记录；不声称自动复制了远端业务数据。数据备份需要独立的备份策略和回执。\n");
+  if (includeCredentials) out.push(credentialsText(credentialRefs(status, dep), ledger));
+  else out.push("\n## 凭据记录\n\n本 README 默认不写密码。获授权管理员读取本项目 OPERATIONS.md（启用时）或部署机明文手册；密码未知时必须补齐，不能编造。\n");
+  return out.join("\n") + "\n";
+}
+
+export function hostReadme(status, hid, runId, at, { ledger = null, full = false, controller = false } = {}) {
+  const host = status.hosts[hid];
+  const out = [
+    `# 主机 ${host.display_name} / ${hid}\n`,
+    `主机持久化根：${code(host.root)}；更新：${at}；运行：${runId}。\n`,
+    "APP 与公共服务同级。通用规范见 docs/standards/DEPLOYMENT-STANDARD.md。DEPLOYMENTS.md 为本机部署手册。\n",
+    "| APP / 服务 | 实例 | 版本（最近验证） | 目录 | 最近验证时间 |\n|---|---|---|---|---|",
+  ];
+  const deps = Object.values(status.deployments).filter((d) => d.host_id === hid).sort((a, b) => a.deployment_id < b.deployment_id ? -1 : 1);
+  for (const d of deps) out.push(`| ${d.project_id} | ${d.deployment_id} | ${code(d.observed_version || "未验证")} | ${code(d.root)} | ${d.updated_at || "未验证"} |`);
+  out.push("\n公共服务数据归提供者；其他主机使用的服务通过依赖绑定记录，不在本机创建假的空服务目录。\n");
+  if (full) {
+    for (const d of deps) out.push(deploymentReadme(status, d, runId, at, { ledger, includeCredentials: controller || status.policies.server_operations }));
+  }
+  return out.join("\n") + "\n";
+}
+
+export function remotePaths(status, dep) {
+  const names = ["README.md", "project.yaml", "run/release-state.json"];
+  if (status.policies.server_operations) names.push("OPERATIONS.md");
+  if (status.projects[dep.project_id].kind === "shared-service") names.push("consumers.md");
+  if (dep.layout === "instances") {
+    return names.map((n) => pathFor(status, dep, n)).concat([targetJoin(status.hosts[dep.host_id], dep.project_id + "/README.md")]);
+  }
+  return names.map((n) => pathFor(status, dep, n));
+}
+
+export function planReport(plan) {
+  const out = [
+    `# OPS 执行计划 ${plan.run_id}\n`,
+    `Worker：${plan.worker}；操作：${plan.operation}；风险：${plan.risk}。\n`,
+    `计划摘要：\`${digest(plan)}\`\n\n创建：${plan.created_at}；批准有效截止：${plan.expires_at}。\n`,
+    "## 目标与理由\n", plan.reason + "\n",
+  ];
+  for (const [hid, h] of Object.entries(plan.hosts)) out.push(`主机 ${hid}：${h.transport} / ${h.platform} / 根 ${code(h.root)} / 身份 ${h.identity}。\n`);
+  out.push("## 受影响消费者\n", plan.affected_consumers.join(", ") || "没有登记的既有消费者受影响。", "\n## 完整动作集合\n");
+  for (const op of plan.operations) {
+    out.push(`### ${op.step_id} — ${op.host_id} / ${op.deployment_id || "host"} / ${op.kind}\n`);
+    const display = Object.fromEntries(Object.entries(op).filter(([k]) => k !== "content_b64"));
+    if ("content_b64" in op) display.payload_sha256 = digest(Buffer.from(op.content_b64, "base64"));
+    out.push(block(display));
+    if (op.secret_argv_acknowledged) out.push("**该 MinIO 管理动作的应用密码会短暂出现在受特权用户可见的 mc 子进程参数中。批准包含此风险。**\n");
+  }
+  out.push(
+    "## 明文文件与双边交付\n",
+    "服务器 README 默认不含密码；受限 OPERATIONS.md 和部署机手册按已批准策略写真实明文。env 和本地配置副本按 0600/受限 ACL 写入。目标与部署机文件均回读校验；缺一不可标记 completed。\n",
+    block({ document_targets: plan.document_targets, credential_versions: Object.keys(plan.credential_versions), policies: plan.registry_after.policies }),
+    "## 数据保护和恢复\n", plan.rollback_note + "\n",
+    "没有默认删除数据、逻辑资源、公共服务、卷或备份的动作。失败停止，断线标记 unknown；同一计划不能盲目重跑迁移。\n",
+    "## 批准\n", "必须由用户确认上述目标、完整写入集合、凭据版本、影响集合和恢复限制。approve 必须携带本报告对应的完整摘要；编辑计划会使旧批准失效。\n",
+  );
+  return out.join("\n");
+}
+
+export function deliveryBundle(state, plan, status, ledger, verifiedIds) {
+  const at = now();
+  const rid = plan.run_id;
+  const remote = new Map();
+  const local = {};
+  const addRemote = (hid, path, text) => {
+    const expected = plan.document_preconditions[hid]?.[path];
+    if (expected === undefined) throw new OpsError("document write not included in approved preconditions: " + path);
+    remote.set(hid + "\0" + path, { host_id: hid, path, content: text, sha256: digest(Buffer.from(text, "utf8")), expected });
+  };
+  for (const did of [...new Set(verifiedIds)].sort()) {
+    const d = status.deployments[did];
+    const hid = d.host_id;
+    const readme = deploymentReadme(status, d, rid, at, { ledger, includeCredentials: status.policies.server_readme_credentials });
+    addRemote(hid, pathFor(status, d, "README.md"), readme);
+    const operations = deploymentReadme(status, d, rid, at, { ledger, includeCredentials: true });
+    if (status.policies.server_operations) addRemote(hid, pathFor(status, d, "OPERATIONS.md"), operations);
+    addRemote(hid, pathFor(status, d, "project.yaml"), JSON.stringify(d, null, 2) + "\n");
+    addRemote(hid, pathFor(status, d, "run/release-state.json"), JSON.stringify({
+      run_id: rid, version: d.version, observed_version: d.observed_version, verified_at: d.updated_at, document_generation: at,
+    }, null, 2) + "\n");
+    if (status.projects[d.project_id].kind === "shared-service") addRemote(hid, pathFor(status, d, "consumers.md"), dependencies(status, d));
+    if (d.layout === "instances") {
+      const projectroot = targetJoin(status.hosts[hid], d.project_id);
+      const peers = Object.values(status.deployments).filter((x) => x.host_id === hid && x.project_id === d.project_id);
+      const text = "# " + d.project_id + " 实例索引\n\n" + peers.map((x) => `- ${x.environment}/${x.instance}：${code(x.root)}，版本 ${code(x.version)}`).join("\n") + "\n";
+      addRemote(hid, targetJoin({ ...status.hosts[hid], root: projectroot }, "README.md"), text);
+    }
+    const prefix = `hosts/${hid}/deployments/${did}`;
+    local[prefix + "/README.md"] = deploymentReadme(status, d, rid, at, { ledger, includeCredentials: true, controller: true });
+    local[prefix + "/OPERATIONS.md"] = operations;
+    local[prefix + "/deployment.json"] = JSON.stringify(d, null, 2) + "\n";
+    local[prefix + "/server/README.md"] = readme;
+  }
+  const touchedHosts = [...new Set([...verifiedIds.map((d) => status.deployments[d].host_id), ...Object.keys(plan.hosts)])].sort();
+  for (const hid of touchedHosts) {
+    const h = status.hosts[hid];
+    addRemote(hid, targetJoin(h, "README.md"), hostReadme(status, hid, rid, at));
+    addRemote(hid, targetJoin(h, "DEPLOYMENTS.md"), hostReadme(status, hid, rid, at, { ledger, full: true }));
+    addRemote(hid, targetJoin(h, "docs/standards/DEPLOYMENT-STANDARD.md"), STANDARD);
+    const knowledgePath = targetJoin(h, "knowledge/INDEX.md");
+    if ((plan.document_preconditions[hid]?.[knowledgePath] ?? { kind: "file" }).kind === "absent") {
+      addRemote(hid, knowledgePath, "# 共享知识索引\n\n通用规范见 ../docs/standards/DEPLOYMENT-STANDARD.md。只收录经用户确认、带来源和最后验证时间的知识，不存密码。\n");
+    }
+    local[`hosts/${hid}/README.md`] = hostReadme(status, hid, rid, at);
+    local[`hosts/${hid}/DEPLOYMENTS.md`] = hostReadme(status, hid, rid, at, { ledger, full: true, controller: true });
+  }
+  const globalText = ["# 全域部署总册（明文）\n", `最近文档代次：${rid}；生成时间：${at}。\n`, "本地账本和配置副本不等于远端业务数据备份。\n"];
+  for (const hid of Object.keys(status.hosts).sort()) globalText.push(hostReadme(status, hid, rid, at, { ledger, full: true, controller: true }));
+  local["FLEET-DEPLOYMENTS.md"] = globalText.join("\n");
+  local["README.md"] = "# OPS 控制端\n\n主机记录位于 hosts/<host_id>/；项目关联位于 status.json；项目部署记录位于 hosts/<host_id>/deployments/<deployment_id>/；完整明文总册位于 FLEET-DEPLOYMENTS.md；凭据账本位于 private/credentials.json；执行证据按 host runs / release 保存。\n\n不得清理此运行态目录来替换静态 workflow。双边文档完成由每次运行 docs-receipt.json 证明。\n";
+  local["docs/standards/DEPLOYMENT-STANDARD.md"] = STANDARD;
+  if (!existsSync(join(state, "knowledge", "INDEX.md"))) {
+    local["knowledge/INDEX.md"] = "# 共享知识索引\n\n只收录经用户批准、带来源与最后验证日期的通用知识。运行时环境和密码不自动提升为共享知识。\n";
+  }
+  return {
+    schema_version: 1, run_id: rid, plan_digest: digest(plan), generated_at: at,
+    remote: [...remote.values()],
+    local: Object.entries(local).map(([p, text]) => ({ path: p, content: text, sha256: digest(Buffer.from(text, "utf8")) })),
+    acks: {},
+  };
+}