@namewta/speculo 1.0.7 → 1.0.9

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

@@ -16,14 +16,20 @@ README 记录实际版本、来源、主机、时间、路径、依赖、启停
 旧环境默认值恢复和健康验证失败不得清理原环境。缓存隔离不等于释放空间；禁止把 data/env/backups 或数据库持久日志当成垃圾。
 
 计划 → 明确批准 → 执行 → 实际验证 → 双边文档回执完成。远程断线意味着结果未知，不能重跑迁移或重新生成密码。
+
+主机级入口（WireGuard、Nginx、探测单元）登记在 knowledge/host-services.json，不是假的 APP 部署。跨主机公网入口规范登记在 knowledge/public-ingress.json。主机/全域总册 = 服务一览表（含主机级入口）+ 特定服务规范；缺一不算完整主机手册。
 `;
 
-function htmlEscape(s) {
-  return String(s).replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;");
+export function code(value) {
+  const text = String(value ?? "");
+  if (!text.includes("`")) return "`" + text + "`";
+  const longest = Math.max(0, ...[...text.matchAll(/`+/g)].map((m) => m[0].length));
+  const ticks = "`".repeat(longest + 1);
+  return ticks + " " + text + " " + ticks;
 }
 
-export function code(value) {
-  return "<code>" + htmlEscape(value).replaceAll("\n", "<br>") + "</code>";
+function cell(value) {
+  return String(value ?? "").replaceAll("|", "\\|").replaceAll("\r", "").replaceAll("\n", " ");
 }
 
 export function block(value, language = "json") {
@@ -47,6 +53,20 @@ export function credentialRefs(status, dep) {
   return [...refs].sort();
 }
 
+function firstCredential(refs, ledger) {
+  for (const ref of refs) {
+    const [cid, v] = ref.split("@");
+    const item = ledger?.entries?.[cid]?.[v];
+    if (!item?.values) continue;
+    return {
+      ref,
+      username: item.values.username || item.values.user || item.values.access_key || "",
+      password: item.values.password || item.values.secret || item.values.secret_key || item.values.token || "",
+    };
+  }
+  return null;
+}
+
 export function credentialsText(refs, ledger) {
   const out = ["## 明文账号密码\n", "本文件是受限明文交付，不是脱敏报告。只向获授权管理员及对应运行账户开放。\n"];
   if (!refs.length) return [...out, "本部署没有登记密码凭据。密钥认证本身不存在登录密码；未知旧密码不能伪造。\n"].join("\n");
@@ -86,6 +106,130 @@ export function dependencies(status, dep) {
   return lines.join("\n");
 }
 
+function deploymentAccess(status, dep) {
+  const bindings = Object.values(status.bindings).filter((b) => b.consumer_deployment_id === dep.deployment_id && b.status === "active");
+  if (bindings.length) return bindings.map((b) => b.endpoint).filter(Boolean).join("；") || "—";
+  const providers = Object.values(status.bindings).filter((b) => b.provider_deployment_id === dep.deployment_id && b.status === "active");
+  if (providers.length) return providers.map((b) => b.endpoint).filter(Boolean).join("；") || dep.root;
+  return dep.root;
+}
+
+function persistenceCell(dep) {
+  if (!dep.storage?.length) return "无登记业务持久化";
+  return dep.storage.map((p) => `${p.component}/${p.purpose}: ${p.path}`).join("；");
+}
+
+function hostServiceAccess(svc) {
+  return svc.public_url || (svc.listen && svc.listen.length ? svc.listen.join("；") : "") || svc.tunnel_address || (svc.listen_port ? String(svc.listen_port) : "") || svc.config_path || svc.unit || "—";
+}
+
+function hostServicePersistence(svc) {
+  return [svc.config_path, svc.unit, svc.tunnel_address].filter(Boolean).join("；") || "主机级控制文件";
+}
+
+export function overviewRows(status, hid, { ledger = null, includeCredentials = false } = {}) {
+  const rows = [];
+  const host = status.hosts[hid];
+  for (const svc of host.host_services || []) {
+    rows.push({
+      host_id: hid,
+      service: svc.id + " / " + svc.kind,
+      access: hostServiceAccess(svc),
+      username: includeCredentials ? (svc.kind === "wireguard" ? "密钥认证" : "无登录口令") : "见控制端总册",
+      password: includeCredentials ? "无登录口令" : "不在服务端公开",
+      version: svc.unit || svc.kind,
+      updated: "主机级服务",
+      persistence: hostServicePersistence(svc),
+    });
+  }
+  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) {
+    const cred = includeCredentials ? firstCredential(credentialRefs(status, d), ledger) : null;
+    rows.push({
+      host_id: hid,
+      service: d.project_id + " / " + d.deployment_id,
+      access: deploymentAccess(status, d),
+      username: includeCredentials ? (cred?.username || "密钥认证/无登录口令") : "见 OPERATIONS",
+      password: includeCredentials ? (cred?.password || "无登录口令") : "不在服务端公开",
+      version: d.observed_version || d.version || "未验证",
+      updated: d.updated_at || "未验证",
+      persistence: persistenceCell(d),
+    });
+  }
+  return rows;
+}
+
+function renderOverviewTable(rows, { includeCredentials = false } = {}) {
+  const header = includeCredentials
+    ? "| 主机 | 服务 | 访问地址 | 账号 | 密码 | 版本 | 最近部署 | 持久化目录 |\n|---|---|---|---|---|---|---|---|"
+    : "| 主机 | 服务 | 访问地址 | 账号 | 版本 | 最近部署 | 持久化目录 |\n|---|---|---|---|---|---|---|";
+  const lines = [header];
+  for (const r of rows) {
+    if (includeCredentials) {
+      lines.push(`| ${cell(r.host_id)} | ${cell(r.service)} | ${cell(r.access)} | ${cell(r.username)} | ${cell(r.password)} | ${cell(r.version)} | ${cell(r.updated)} | ${cell(r.persistence)} |`);
+    } else {
+      lines.push(`| ${cell(r.host_id)} | ${cell(r.service)} | ${cell(r.access)} | ${cell(r.username)} | ${cell(r.version)} | ${cell(r.updated)} | ${cell(r.persistence)} |`);
+    }
+  }
+  if (!rows.length) {
+    lines.push(includeCredentials
+      ? "| — | 未登记 APP、公共服务或主机级入口 | — | — | — | — | — | — |"
+      : "| — | 未登记 APP、公共服务或主机级入口 | — | — | — | — | — |");
+  }
+  return lines.join("\n") + "\n";
+}
+
+export function ingressSection(status) {
+  const ing = status.public_ingress;
+  if (!ing) return "";
+  const out = [
+    "## 公网访问内网\n",
+    "入口（用户 → 公网 Nginx → 隧道 → 内网服务）与出口（内网客户端 TUN）不是同一条连接。" + (ing.not_the_same_as ? " " + ing.not_the_same_as : "") + "\n",
+    "| 公网 | 四层 | 路径 | 后端 |\n|---|---|---|---|",
+  ];
+  for (const m of ing.mappings || []) {
+    out.push(`| ${cell(m.public)} | ${cell(m.layer4 || "—")} | ${cell((m.via || []).join(" → ") || "—")} | ${cell(m.backend)} |`);
+  }
+  if (!(ing.mappings || []).length) out.push("| — | — | 未登记映射 | — |");
+  out.push("\n### 新开公网 HTTP 服务\n");
+  const steps = ing.open_http_checklist?.length
+    ? ing.open_http_checklist
+    : [
+      "在入口主机登记/更新 Nginx 站点与 listen 端口，写入 host_services。",
+      "确认 WireGuard 对端与 AllowedIPs，内网后端只绑隧道地址。",
+      "更新 knowledge/public-ingress.json 映射行后重新编制文档计划。",
+      "不要把数据库、SSH、Redis 管理口直接暴露到公网。",
+    ];
+  for (const s of steps) out.push("- " + s);
+  if (ing.forbidden_ports?.length) {
+    out.push("\n### 禁止暴露的端口\n");
+    out.push(ing.forbidden_ports.map((p) => "- " + p).join("\n"));
+  }
+  return out.join("\n") + "\n";
+}
+
+function hostNotes(status, hid) {
+  const host = status.hosts[hid];
+  const out = [`### 主机 ${hid} / ${host.display_name}\n`, `持久化根：${code(host.root)}。通用规范见 docs/standards/DEPLOYMENT-STANDARD.md。\n`];
+  for (const svc of host.host_services || []) {
+    out.push(`#### ${svc.id}（${svc.kind}）\n`);
+    if (svc.notes) out.push(svc.notes + "\n");
+    if (svc.unit) out.push("- 单元：" + code(svc.unit) + "\n");
+    if (svc.config_path) out.push("- 配置：" + code(svc.config_path) + "\n");
+    if (svc.tunnel_address) out.push("- 隧道地址：" + code(svc.tunnel_address) + "\n");
+    if (svc.listen_port) out.push("- ListenPort：" + String(svc.listen_port) + "\n");
+    if (svc.public_url) out.push("- 公网 URL：" + code(svc.public_url) + "\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}\n`);
+    out.push(`目录 ${code(d.root)}；启停与备份细节见项目 README。备份：${d.backup} 恢复：${d.recovery}\n`);
+    if (d.notes?.length) out.push(d.notes.join("\n\n") + "\n");
+  }
+  if (!(host.host_services || []).length && !deps.length) out.push("本机尚未登记 APP、公共服务或主机级入口。\n");
+  return out.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];
@@ -136,21 +280,49 @@ export function deploymentReadme(status, dep, runId, generatedAt, { ledger = nul
 
 export function hostReadme(status, hid, runId, at, { ledger = null, full = false, controller = false } = {}) {
   const host = status.hosts[hid];
+  const includeCredentials = Boolean(full && controller && ledger);
+  const rows = overviewRows(status, hid, { ledger, includeCredentials });
   const out = [
     `# 主机 ${host.display_name} / ${hid}\n`,
     `主机持久化根：${code(host.root)}；更新：${at}；运行：${runId}。\n`,
-    "APP 与公共服务同级。通用规范见 docs/standards/DEPLOYMENT-STANDARD.md。DEPLOYMENTS.md 为本机部署手册。\n",
-    "| APP / 服务 | 实例 | 版本（最近验证） | 目录 | 最近验证时间 |\n|---|---|---|---|---|",
+    "APP 与公共服务同级。主机级入口（WireGuard/Nginx/探测）登记为 host_services，不是假的 APP 目录。通用规范见 docs/standards/DEPLOYMENT-STANDARD.md。\n",
+    "## 服务一览\n",
+    renderOverviewTable(rows, { includeCredentials }),
   ];
-  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 }));
-  }
+  if (status.public_ingress) out.push("\n" + ingressSection(status));
+  out.push("\n## 说明\n", hostNotes(status, hid));
+  out.push("\n公共服务数据归提供者；其他主机使用的服务通过依赖绑定记录。未写入 host_services / 部署账本的入口不会在下次文档交付中出现。\n");
+  return out.join("\n") + "\n";
+}
+
+export function fleetDocument(status, hostIds, runId, at, { ledger = null, includeCredentials = false } = {}) {
+  const ids = [...hostIds].sort();
+  const rows = ids.flatMap((hid) => overviewRows(status, hid, { ledger, includeCredentials }));
+  const out = [
+    "# 全域部署总册（明文）\n",
+    `最近文档代次：${runId}；生成时间：${at}。本地账本和配置副本不等于远端业务数据备份。\n`,
+    "## 服务一览\n",
+    renderOverviewTable(rows, { includeCredentials }),
+  ];
+  if (status.public_ingress) out.push("\n" + ingressSection(status));
+  out.push("\n## 说明\n");
+  for (const hid of ids) out.push(hostNotes(status, hid));
   return out.join("\n") + "\n";
 }
 
+export function hostServicesDocument(host) {
+  return JSON.stringify({
+    schema_version: 1,
+    host_id: host.host_id,
+    services: host.host_services || [],
+  }, null, 2) + "\n";
+}
+
+export function publicIngressDocument(status) {
+  if (!status.public_ingress) return null;
+  return JSON.stringify(status.public_ingress, null, 2) + "\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");
@@ -188,6 +360,14 @@ export function planReport(plan) {
   return out.join("\n");
 }
 
+const KNOWLEDGE_INDEX = `# 共享知识索引
+
+通用规范见 ../docs/standards/DEPLOYMENT-STANDARD.md。
+主机级服务账本：host-services.json。
+跨主机公网入口：public-ingress.json。
+只收录经用户确认、带来源和最后验证时间的知识，不存密码。
+`;
+
 export function deliveryBundle(state, plan, status, ledger, verifiedIds) {
   const at = now();
   const rid = plan.run_id;
@@ -228,21 +408,25 @@ export function deliveryBundle(state, plan, status, ledger, verifiedIds) {
     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);
+    addRemote(hid, targetJoin(h, "knowledge/host-services.json"), hostServicesDocument(h));
+    const ingressJson = publicIngressDocument(status);
+    if (ingressJson) addRemote(hid, targetJoin(h, "knowledge/public-ingress.json"), ingressJson);
     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");
+      addRemote(hid, knowledgePath, KNOWLEDGE_INDEX);
     }
     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 });
+    local[`hosts/${hid}/knowledge/host-services.json`] = hostServicesDocument(h);
+    if (ingressJson) local[`hosts/${hid}/knowledge/public-ingress.json`] = ingressJson;
   }
-  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["FLEET-DEPLOYMENTS.md"] = fleetDocument(status, Object.keys(status.hosts), rid, at, { ledger, includeCredentials: true });
+  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 保存。主机级入口见 hosts/<id>/knowledge/host-services.json，跨主机公网入口见 knowledge/public-ingress.json。\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";
+    local["knowledge/INDEX.md"] = "# 共享知识索引\n\n只收录经用户批准、带来源与最后验证日期的通用知识。运行时环境和密码不自动提升为共享知识。跨主机入口规范见各主机 knowledge/public-ingress.json。\n";
   }
+  if (status.public_ingress) local["knowledge/public-ingress.json"] = publicIngressDocument(status);
   return {
     schema_version: 1, run_id: rid, plan_digest: digest(plan), generated_at: at,
     remote: [...remote.values()],

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

@@ -8,7 +8,7 @@ import {
   relative, resolveSecrets, secure, UnknownResult, withLock, writeJson,
 } from "./core.mjs";
 import { load, save, ledgerLoad, validate, validateStatus } from "./model.mjs";
-import { locatePlan, envFile } from "./planner.mjs";
+import { locatePlan, envFile, sliceDigest } from "./planner.mjs";
 import { call as transportCall, hostTransportDigest } from "./transport.mjs";
 import { deliveryBundle } from "./docs.mjs";
 
@@ -43,7 +43,7 @@ export function approval(state, run, expected, by, statement) {
   };
   validate(value, "approval");
   return withLock(join(state, ".locks", "catalog"), { operation: "approve", run_id: plan.run_id }, () => {
-    if (digest(load(state)) !== plan.registry_digest) throw new OpsError("catalog drift since plan; replan before approval");
+    if (sliceDigest(load(state), plan.registry_scope) !== plan.registry_slice_digest) throw new OpsError("touched catalog slice drifted since plan; replan before approval");
     writeJson(join(dirname(path), "approval.json"), value, { exclusive: true });
     return { run_id: plan.run_id, status: "approved", plan_digest: expected };
   });
@@ -124,15 +124,25 @@ export function commitObservations(state, current, plan, execution) {
   const result = structuredClone(current);
   const desired = plan.registry_after;
   const records = execution.steps;
-  result.policies = desired.policies;
-  result.hosts = structuredClone(desired.hosts);
-  result.projects = structuredClone(desired.projects);
-  for (const did of plan.document_targets) {
-    let proposed = structuredClone(desired.deployments[did]);
+  const scope = plan.registry_scope || {};
+  if (scope.policies) result.policies = structuredClone(desired.policies);
+  for (const hid of scope.hosts || []) {
+    if (desired.hosts?.[hid]) result.hosts[hid] = structuredClone(desired.hosts[hid]);
+    else delete result.hosts[hid];
+  }
+  for (const pid of scope.projects || []) {
+    if (desired.projects?.[pid]) result.projects[pid] = structuredClone(desired.projects[pid]);
+    else delete result.projects[pid];
+  }
+  if (scope.public_ingress) result.public_ingress = structuredClone(desired.public_ingress ?? null);
+  const deploymentIds = new Set([...(scope.deployments || []), ...plan.document_targets]);
+  for (const did of deploymentIds) {
+    let proposed = desired.deployments?.[did] ? structuredClone(desired.deployments[did]) : null;
     const old = current.deployments[did];
     const ops = plan.operations.filter((o) => o.deployment_id === did);
     const statuses = ops.map((o) => records[o.step_id]?.status ?? "not-started");
     const changing = ops.length > 0;
+    if (!proposed && !old) continue;
     if (changing && statuses.every((x) => x === "succeeded")) {
       proposed.status = proposed.status === "retired" ? "retired" : "docs_pending";
       proposed.observed_version = proposed.version;
@@ -146,7 +156,9 @@ export function commitObservations(state, current, plan, execution) {
     else { proposed.status = "planned"; proposed.observed_version = null; }
     result.deployments[did] = proposed;
   }
-  for (const [aid, a] of Object.entries(desired.allocations)) {
+  for (const aid of scope.allocations || []) {
+    const a = desired.allocations?.[aid];
+    if (!a) continue;
     if (aid in current.allocations && current.allocations[aid].status !== "planned") {
       result.allocations[aid] = structuredClone(current.allocations[aid]);
       continue;
@@ -156,11 +168,13 @@ export function commitObservations(state, current, plan, execution) {
     item.status = provisioning.length && provisioning.every((o) => records[o.step_id]?.status === "succeeded") ? "active" : "planned";
     result.allocations[aid] = item;
   }
-  for (const [bid, b] of Object.entries(desired.bindings)) {
+  for (const bid of scope.bindings || []) {
+    const b = desired.bindings?.[bid];
+    if (!b) continue;
     const item = structuredClone(b);
     const consumer = result.deployments[b.consumer_deployment_id];
     if (item.status === "active" && (!consumer || ["planned", "failed", "unknown"].includes(consumer.status))) item.status = "planned";
-    if (item.mode === "shared" && result.allocations[item.allocation_id].status !== "active" && item.status === "active") item.status = "planned";
+    if (item.mode === "shared" && result.allocations[item.allocation_id]?.status !== "active" && item.status === "active") item.status = "planned";
     result.bindings[bid] = item;
   }
   result.releases[plan.run_id] = {
@@ -171,6 +185,7 @@ export function commitObservations(state, current, plan, execution) {
   };
   save(state, result);
   execution.committed_registry_digest = digest(result);
+  execution.committed_slice_digest = sliceDigest(result, plan.registry_scope);
   return result;
 }
 
@@ -256,9 +271,10 @@ export function apply(state, run, { resume = false, docsOnly = false } = {}) {
     const ledger = ledgerLoad(state);
     const execution = existsSync(execPath)
       ? readJson(execPath)
-      : { schema_version: 1, run_id: plan.run_id, plan_path: path, status: "executing", started_at: now(), steps: {}, errors: [], committed_registry_digest: null };
-    const expected = execution.committed_registry_digest || plan.registry_digest;
-    if (digest(current) !== expected) throw new OpsError("controller registry changed since this approved run; compile a new plan");
+      : { schema_version: 1, run_id: plan.run_id, plan_path: path, status: "executing", started_at: now(), steps: {}, errors: [], committed_registry_digest: null, committed_slice_digest: null };
+    const expectedSlice = execution.committed_slice_digest || plan.registry_slice_digest;
+    if (!plan.registry_scope || !plan.registry_slice_digest) throw new OpsError("plan missing registry_scope; compile a new plan");
+    if (sliceDigest(current, plan.registry_scope) !== expectedSlice) throw new OpsError("controller registry changed since this approved run; compile a new plan");
     if (execution.status === "completed") return { run_id: plan.run_id, status: "completed", unchanged: true, report: join(folder, "RESULT.md") };
     verifyJournal(join(folder, "journal.jsonl"));
     for (const [hid, h] of Object.entries(plan.hosts)) {
@@ -319,6 +335,7 @@ export function apply(state, run, { resume = false, docsOnly = false } = {}) {
           current.releases[plan.run_id].updated_at = now();
           save(state, current);
           execution.committed_registry_digest = digest(current);
+          execution.committed_slice_digest = sliceDigest(current, plan.registry_scope);
         } catch (e) {
           if (!(e instanceof OpsError || e.code)) throw e;
           execution.status = "docs_pending";
@@ -364,6 +381,7 @@ export function apply(state, run, { resume = false, docsOnly = false } = {}) {
         current.releases[plan.run_id].status = execution.status;
         save(state, current);
         execution.committed_registry_digest = digest(current);
+        execution.committed_slice_digest = sliceDigest(current, plan.registry_scope);
       }
       writeJson(execPath, execution);
       journal(folder, { kind: "attempt-end", status: execution.status, errors: execution.errors.length });

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

@@ -12,6 +12,7 @@ import { allocationOperation } from "./services.mjs";
 import { credentialRefs, planReport, remotePaths } from "./docs.mjs";
 import { taskFiles } from "./native_windows.mjs";
 import { engineDigest } from "./execution.mjs";
+import { assertSafeControlPath, defaultFileMode, reservedHostDocumentPaths } from "./control_files.mjs";
 
 export const plannerHooks = { call: transportCall };
 
@@ -90,7 +91,7 @@ export function composeModel(spec, host, root, name, envs, ctx) {
   const mounts = [];
   const allowed = new Set(["image", "build", "command", "entrypoint", "environment", "env_file", "volumes", "ports", "healthcheck", "depends_on",
     "restart", "user", "read_only", "tmpfs", "labels", "networks", "cap_drop", "security_opt", "deploy", "init", "working_dir",
-    "mem_limit", "cpus", "stop_grace_period", "logging", "profiles"]);
+    "mem_limit", "cpus", "stop_grace_period", "logging", "profiles", "writable_root_justification"]);
   for (const [service, s] of Object.entries(model.services)) {
     identifier(service, "compose service");
     const unknown = Object.keys(s).filter((k) => !allowed.has(k));
@@ -108,8 +109,15 @@ export function composeModel(spec, host, root, name, envs, ctx) {
     }
     if (credentialsIn(s.environment || {}).size) throw new OpsError("credentials must be injected through env/ files, not inline Compose environment");
     if (s.restart === undefined) s.restart = "unless-stopped";
-    if (s.read_only === false) throw new OpsError("writable container rootfs hides undeclared persistence; declare bind/tmpfs paths instead");
-    s.read_only = true;
+    const justification = s.writable_root_justification;
+    delete s.writable_root_justification;
+    if (s.read_only === false) {
+      if (typeof justification !== "string" || justification.trim().length < 12) {
+        throw new OpsError("writable container rootfs hides undeclared persistence; declare bind/tmpfs paths instead");
+      }
+    } else {
+      s.read_only = true;
+    }
     if (s.tmpfs === undefined) s.tmpfs = ["/tmp", "/run"];
     const labels = s.labels && typeof s.labels === "object" && !Array.isArray(s.labels) ? s.labels : null;
     if (s.labels !== undefined && !labels) throw new OpsError("Compose labels must be a map");
@@ -155,6 +163,73 @@ export function composeModel(spec, host, root, name, envs, ctx) {
   return [dollars(model), mounts];
 }
 
+export function catalogSlice(status, scope) {
+  if (!scope || typeof scope !== "object") throw new OpsError("plan missing registry_scope; compile a new plan");
+  const pick = (group) => Object.fromEntries((scope[group] || []).map((id) => [id, status[group]?.[id] ?? null]));
+  const slice = {
+    hosts: pick("hosts"),
+    projects: pick("projects"),
+    deployments: pick("deployments"),
+    allocations: pick("allocations"),
+    bindings: pick("bindings"),
+  };
+  if (scope.policies) slice.policies = status.policies;
+  if (scope.public_ingress) slice.public_ingress = status.public_ingress ?? null;
+  return slice;
+}
+
+export function sliceDigest(status, scope) {
+  return digest(catalogSlice(status, scope));
+}
+
+export function computeRegistryScope(current, after, selected, ops, uniqueDocs) {
+  const hosts = new Set(Object.keys(selected || {}));
+  const deployments = new Set(uniqueDocs || []);
+  const allocations = new Set();
+  const bindings = new Set();
+  const projects = new Set();
+  for (const op of ops || []) {
+    if (op.host_id) hosts.add(op.host_id);
+    if (op.deployment_id) deployments.add(op.deployment_id);
+    if (op.allocation_id) allocations.add(op.allocation_id);
+  }
+  const catalog = after || current;
+  for (const did of [...deployments]) {
+    const d = catalog.deployments?.[did] || current.deployments?.[did];
+    if (d) { hosts.add(d.host_id); projects.add(d.project_id); }
+  }
+  for (const [bid, b] of Object.entries(catalog.bindings || {})) {
+    if (deployments.has(b.consumer_deployment_id) || deployments.has(b.provider_deployment_id)) {
+      bindings.add(bid);
+      if (b.allocation_id) allocations.add(b.allocation_id);
+      if (b.provider_deployment_id) deployments.add(b.provider_deployment_id);
+      const provider = catalog.deployments?.[b.provider_deployment_id];
+      if (provider) { hosts.add(provider.host_id); projects.add(provider.project_id); }
+      const consumer = catalog.deployments?.[b.consumer_deployment_id];
+      if (consumer) { hosts.add(consumer.host_id); projects.add(consumer.project_id); }
+    }
+  }
+  for (const [aid, a] of Object.entries(catalog.allocations || {})) {
+    if (allocations.has(aid) || deployments.has(a.provider_deployment_id)) {
+      allocations.add(aid);
+      if (a.provider_deployment_id) deployments.add(a.provider_deployment_id);
+    }
+  }
+  for (const did of deployments) {
+    const d = catalog.deployments?.[did] || current.deployments?.[did];
+    if (d) { hosts.add(d.host_id); projects.add(d.project_id); }
+  }
+  return {
+    hosts: [...hosts].sort(),
+    projects: [...projects].sort(),
+    deployments: [...deployments].sort(),
+    allocations: [...allocations].sort(),
+    bindings: [...bindings].sort(),
+    policies: digest(current.policies) !== digest(after.policies),
+    public_ingress: digest(current.public_ingress ?? null) !== digest(after.public_ingress ?? null),
+  };
+}
+
 export function compilePlan(state, specPath) {
   const spec = readJson(specPath);
   validate(spec, "spec");
@@ -173,6 +248,7 @@ export function compilePlan(state, specPath) {
         after[group][item[idkey]] = structuredClone(item);
       }
     }
+    if (spec.public_ingress !== undefined) after.public_ingress = structuredClone(spec.public_ingress);
     const rid = identifier(spec.run_id || newId("run"));
     if (rid in current.releases) throw new OpsError("run ID already exists");
     for (const [group, key] of [["allocations", "allocation_id"], ["bindings", "binding_id"]]) {
@@ -200,8 +276,8 @@ export function compilePlan(state, specPath) {
       ops.push(op);
       return op;
     };
-    const fileOp = (hostId, did, path, { content = undefined, binary = undefined, mode = 0o600 } = {}) => {
-      const data = { path, mode };
+    const fileOp = (hostId, did, path, { content = undefined, binary = undefined, mode = undefined } = {}) => {
+      const data = { path, mode: mode ?? defaultFileMode(path) };
       if (content !== undefined) data.content = content;
       else data.content_b64 = Buffer.from(binary).toString("base64");
       return add(hostId, did, "write", data);
@@ -270,23 +346,32 @@ export function compilePlan(state, specPath) {
       if (kind === "write-control" || kind === "write-file") {
         if (kind === "write-file") {
           const path = targetJoin(host, relative(item.path));
-          if ("content" in item) fileOp(hid, null, path, { content: item.content, mode: item.mode ?? 0o600 });
+          if (reservedHostDocumentPaths(host, targetJoin).includes(path)) {
+            throw new OpsError("generated host documentation cannot be supplied as a host write-file: " + path);
+          }
+          if ("content" in item) fileOp(hid, null, path, { content: item.content, mode: item.mode });
           else if ("source" in item) {
             const src = resolve(item.source);
             noSymlinks(src, { allowMissing: false });
             if (statSync(src).size > 16 * 1024 * 1024) throw new OpsError("host file exceeds 16 MiB");
             const data = readFileSync(src);
             sourceDigests[src] = digest(data);
-            fileOp(hid, null, path, { binary: data, mode: item.mode ?? 0o600 });
+            fileOp(hid, null, path, { binary: data, mode: item.mode });
           } else throw new OpsError("host write-file requires content/source");
           continue;
         }
         const path = item.path;
-        if (path !== "/etc/docker/daemon.json" && !/^\/etc\/systemd\/system\/ops-[a-z0-9-]+\.service$/.test(path)) {
-          throw new OpsError("unrecognized external control file; persistent data cannot be an exception");
+        const cls = assertSafeControlPath(path, { reason: item.reason, rollback: item.rollback || spec.rollback_note });
+        if (cls === "declared") {
+          if (!item.verification || !item.verification.length) {
+            throw new OpsError("declared control files require explicit post-verification");
+          }
         }
         (external[hid] ??= []).push(path);
-        fileOp(hid, null, path, { content: item.content });
+        fileOp(hid, null, path, { content: item.content, mode: item.mode ?? 0o644 });
+        if (item.verification) {
+          for (const h of item.verification) healthOp(hid, null, h, { root: hostroot, host_root: hostroot });
+        }
       } else if (kind === "mkdir") add(hid, null, "mkdir", { path: targetJoin(host, relative(item.path)), mode: item.mode ?? 0o750 });
       else if (kind === "quarantine" || kind === "purge-quarantine") {
         const path = item.path;
@@ -400,7 +485,7 @@ export function compilePlan(state, specPath) {
         }
         const dest = projectPath(host, root, rel);
         if (("content" in f) === ("source" in f)) throw new OpsError("file requires exactly one of content/source");
-        if ("content" in f) fileOp(hid, did, dest, { content: f.content, mode: f.mode ?? 0o600 });
+        if ("content" in f) fileOp(hid, did, dest, { content: f.content, mode: f.mode });
         else {
           let src = f.source;
           if (!isAbsolute(src)) src = join(dirname(specPath), src);
@@ -408,7 +493,7 @@ export function compilePlan(state, specPath) {
           if (!statSync(src).isFile() || statSync(src).size > 16 * 1024 * 1024) throw new OpsError("source must be a regular file <=16 MiB");
           const content = readFileSync(src);
           sourceDigests[resolve(src)] = digest(content);
-          fileOp(hid, did, dest, { binary: content, mode: f.mode ?? 0o600 });
+          fileOp(hid, did, dest, { binary: content, mode: f.mode });
         }
       }
       const envs = d.env || {};
@@ -581,7 +666,14 @@ export function compilePlan(state, specPath) {
       for (const did of uniqueDocs) {
         if (after.deployments[did].host_id === hid) for (const p of remotePaths(after, after.deployments[did])) paths.add(p);
       }
-      for (const p of [targetJoin(host, "knowledge/INDEX.md"), targetJoin(host, "README.md"), targetJoin(host, "DEPLOYMENTS.md"), targetJoin(host, "docs/standards/DEPLOYMENT-STANDARD.md")]) paths.add(p);
+      for (const p of [
+        targetJoin(host, "knowledge/INDEX.md"),
+        targetJoin(host, "knowledge/host-services.json"),
+        targetJoin(host, "knowledge/public-ingress.json"),
+        targetJoin(host, "README.md"),
+        targetJoin(host, "DEPLOYMENTS.md"),
+        targetJoin(host, "docs/standards/DEPLOYMENT-STANDARD.md"),
+      ]) paths.add(p);
       for (const did of Object.keys(specs)) {
         const dep = after.deployments[did];
         if (dep.host_id === hid) paths.add(dep.root);
@@ -663,9 +755,11 @@ export function compilePlan(state, specPath) {
     }
     const created = now();
     const expires = new Date(Date.now() + (spec.expires_hours ?? 24) * 3600 * 1000).toISOString().replace(/\.\d{3}Z$/, "Z");
+    const registry_scope = computeRegistryScope(current, after, selected, ops, uniqueDocs);
     const plan = {
       schema_version: 1, artifact: "ops-resource-plan", run_id: rid, worker: spec.worker, operation: spec.operation, reason: spec.reason,
-      created_at: created, expires_at: expires, controller_id: current.controller.controller_id, registry_digest: digest(current), registry_revision: current.revision,
+      created_at: created, expires_at: expires, controller_id: current.controller.controller_id,
+      registry_digest: digest(current), registry_slice_digest: sliceDigest(current, registry_scope), registry_scope, registry_revision: current.revision,
       hosts: selected, transport_digests: Object.fromEntries(Object.entries(selected).map(([hid, h]) => [hid, hostTransportDigest(h)])),
       inventories, operations: ops, registry_after: after, credential_versions: cv, document_targets: uniqueDocs, document_preconditions: docPreconditions,
       allow_adopt_roots: spec.allow_adopt_roots || [], external_files: external, affected_consumers: [...affected].sort(), rollback_note: spec.rollback_note,

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

@@ -83,7 +83,7 @@ export function call(host, request, { timeout = 1800 } = {}) {
   let p;
   try {
     p = transportHooks.spawnSync(argv[0], argv.slice(1), {
-      input: content,
+      input: Buffer.from(content, "utf8"),
       encoding: "buffer",
       timeout: timeout * 1000,
       maxBuffer: 64 * 1024 * 1024,