@namewta/speculo 1.0.16 → 1.0.18

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

@@ -0,0 +1,313 @@
+/** One user-authorized task, frozen specifications, legacy digest-bound plans, no automatic retry. */
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { isAbsolute, join, relative as pathRelative, resolve } from "node:path";
+import { atomicWrite, digest, exact, identifier, noSymlinks, now, OpsError, redact, withLock, writeJson } from "./core.mjs";
+import { fileDigest, ids, readBoundedJson, readRegistry, route, statePath, targetDigest, containedPath } from "./workspace.mjs";
+
+const DESTRUCTIVE_ACK = "I-APPROVE-THIS-EXACT-DESTRUCTIVE-TASK";
+const MAX_INPUT_BYTES = 256 * 1024 * 1024;
+const fields = new Set(["schema_version", "task_id", "title", "plan", "valid_for_hours", "scope", "input_paths", "steps"]);
+const scopeFields = new Set(["scope", "server_ids", "project_ids", "related_project_ids", "allow_policy_changes", "allow_public_ingress", "allow_destructive"]);
+
+async function runtime() {
+  const [model, planner, execution] = await Promise.all([import("./model.mjs"), import("./planner.mjs"), import("./execution.mjs")]);
+  return { ...model, compilePlan: planner.compilePlan, engineDigest: execution.engineDigest, approval: execution.approval, apply: execution.apply };
+}
+function taskFolder(state, taskId) { return join(statePath(state), "records", "tasks", identifier(taskId, "task_id")); }
+function active(task, at = Date.now()) {
+  if (!Number.isFinite(Date.parse(task.expires_at)) || at >= Date.parse(task.expires_at)) throw new OpsError("task authorization expired; form a new bounded task");
+}
+export { targetDigest } from "./workspace.mjs";
+function allowedProjects(scope) { return new Set([...scope.project_ids, ...scope.related_project_ids]); }
+
+export function validateRequest(request, registry) {
+  exact(request, fields, fields, "task request");
+  if (request.schema_version !== 1) throw new OpsError("task request schema_version must be 1");
+  identifier(request.task_id, "task_id");
+  if (typeof request.title !== "string" || request.title.trim().length < 3 || request.title.length > 200) throw new OpsError("task needs a meaningful title (3..200 characters)");
+  if (typeof request.plan !== "string" || request.plan.trim().length < 40 || request.plan.length > 32000) throw new OpsError("task needs a detailed, already-disclosed Plan Mode description (40..32000 characters)");
+  if (!Number.isInteger(request.valid_for_hours) || request.valid_for_hours < 1 || request.valid_for_hours > 24) throw new OpsError("valid_for_hours must be 1..24");
+  const s = request.scope;
+  exact(s, scopeFields, scopeFields, "task scope");
+  if (!["server", "project"].includes(s.scope)) throw new OpsError("task execution covers H/D only; controller initialization and SSH enrollment retain their own entry");
+  ids(s.server_ids, "server_ids");
+  // A task may sequence several H steps and include explicitly named impact hosts;
+  // the standalone H routing command still selects one primary server.
+  route(registry, { scope: s.scope, server_ids: s.scope === "server" ? s.server_ids.slice(0, 1) : s.server_ids, project_ids: s.project_ids });
+  for (const id of s.server_ids) if (!Object.hasOwn(registry.hosts, id)) throw new OpsError(`unknown task server: ${id}`);
+  ids(s.related_project_ids, "related_project_ids");
+  for (const id of s.related_project_ids) if (!Object.hasOwn(registry.projects, id) || s.project_ids.includes(id)) throw new OpsError("related projects must be distinct registered impact/dependency IDs");
+  for (const key of ["allow_policy_changes", "allow_public_ingress", "allow_destructive"]) if (typeof s[key] !== "boolean") throw new OpsError(`${key} must be explicit boolean`);
+  if (!Array.isArray(request.input_paths) || new Set(request.input_paths).size !== request.input_paths.length) throw new OpsError("input_paths must be distinct absolute files/directories");
+  if (!Array.isArray(request.steps) || request.steps.length < 1 || request.steps.length > 20) throw new OpsError("task must contain 1..20 ordered steps");
+  const seen = new Set();
+  for (const step of request.steps) {
+    exact(step, new Set(["id", "title", "spec"]), new Set(["id", "title", "spec"]), "task step");
+    identifier(step.id, "step.id");
+    if (seen.has(step.id)) throw new OpsError("duplicate task step ID");
+    seen.add(step.id);
+    if (typeof step.title !== "string" || !step.title.trim() || step.title.length > 200) throw new OpsError("step title must be 1..200 characters");
+    assertSpecScope(step.spec, s, registry);
+  }
+  return request;
+}
+
+function inScopeDeployment(dep, scope, label) {
+  if (!dep || !scope.server_ids.includes(dep.host_id) || !allowedProjects(scope).has(dep.project_id)) throw new OpsError(`deployment/consumer outside task scope: ${label}`);
+}
+export function assertSpecScope(spec, scope, registry) {
+  if (!spec || typeof spec !== "object" || !["H", "D"].includes(spec.worker)) throw new OpsError("task step must use the existing H or D spec contract");
+  if (spec.worker === "H" && (["deployments", "allocations", "bindings", "provision", "retire_deployments", "retire_bindings"].some((k) => (spec[k] || []).length) || (spec.resource_updates?.projects || []).length)) throw new OpsError("H cannot create or retire project resources; use a separate D step");
+  if (spec.worker === "D" && ((spec.host_actions || []).length || (spec.resource_updates?.hosts || []).length || spec.public_ingress !== undefined)) throw new OpsError("D cannot configure server-level resources; use a separate H prerequisite step");
+  if (scope.scope === "server" && spec.worker !== "H") throw new OpsError("server task cannot silently become project deployment; select D explicitly");
+  if ((["migrate", "uninstall"].includes(spec.operation) || (spec.retire_deployments || []).length || (spec.host_actions || []).some((a) => a.kind === "purge-quarantine")) && !scope.allow_destructive) {
+    throw new OpsError("destructive/migration scope not authorized");
+  }
+  if (spec.plaintext_documentation !== undefined && spec.plaintext_documentation !== registry.policies.plaintext_documentation && !scope.allow_policy_changes) throw new OpsError("policy change outside task scope");
+  if (spec.public_ingress !== undefined && digest(spec.public_ingress) !== digest(registry.public_ingress ?? null) && !scope.allow_public_ingress) throw new OpsError("public ingress change outside task scope");
+  const projects = allowedProjects(scope);
+  const deployments = { ...registry.deployments, ...Object.fromEntries((spec.deployments || []).map((d) => [d.deployment_id, d])) };
+  const checkHost = (id) => { if (!scope.server_ids.includes(id)) throw new OpsError(`server outside task scope: ${id}`); };
+  for (const id of spec.hosts || []) checkHost(id);
+  for (const h of spec.resource_updates?.hosts || []) {
+    checkHost(h.host_id);
+    if (targetDigest(h) !== targetDigest(registry.hosts[h.host_id])) throw new OpsError("connection/identity/root changes belong to a new S task, not delegated H/D approval");
+  }
+  for (const action of spec.host_actions || []) checkHost(action.host_id);
+  for (const d of spec.deployments || []) inScopeDeployment(d, scope, d.deployment_id);
+  for (const p of spec.resource_updates?.projects || []) if (!projects.has(p.project_id)) throw new OpsError(`project outside task scope: ${p.project_id}`);
+  for (const id of [...(spec.retire_deployments || []), ...(spec.acknowledged_consumers || [])]) inScopeDeployment(deployments[id], scope, id);
+  // Inspect resource references, not arbitrary project JSON/env keys named host_id.
+  const ingressHosts = (v) => {
+    if (Array.isArray(v)) for (const x of v) ingressHosts(x);
+    else if (v && typeof v === "object") for (const [key, x] of Object.entries(v)) {
+      if ((key === "host_id" || key.endsWith("_host_id")) && typeof x === "string") checkHost(x);
+      else ingressHosts(x);
+    }
+  };
+  ingressHosts(spec.public_ingress);
+  const allocations = { ...registry.allocations, ...Object.fromEntries((spec.allocations || []).map((a) => [a.allocation_id, a])) };
+  const bindings = { ...registry.bindings, ...Object.fromEntries((spec.bindings || []).map((b) => [b.binding_id, b])) };
+  const allocation = (id) => {
+    const a = allocations[id];
+    if (!a || !projects.has(a.owner_project_id) || (a.shared_owners || []).some((p) => !projects.has(p))) throw new OpsError(`allocation owner outside task scope: ${id}`);
+    inScopeDeployment(deployments[a.provider_deployment_id], scope, a.provider_deployment_id);
+  };
+  const binding = (id) => {
+    const b = bindings[id];
+    if (!b) throw new OpsError(`unknown binding: ${id}`);
+    inScopeDeployment(deployments[b.consumer_deployment_id], scope, b.consumer_deployment_id);
+    if (b.provider_deployment_id) inScopeDeployment(deployments[b.provider_deployment_id], scope, b.provider_deployment_id);
+    if (b.allocation_id) allocation(b.allocation_id);
+  };
+  for (const a of spec.allocations || []) allocation(a.allocation_id);
+  for (const p of spec.provision || []) allocation(p.allocation_id);
+  for (const b of spec.bindings || []) binding(b.binding_id);
+  for (const id of spec.retire_bindings || []) binding(id);
+  // Include known dependency/impact closure before the planner performs remote reads.
+  const touched = new Set([...(spec.deployments || []).map((d) => d.deployment_id), ...(spec.retire_deployments || [])]);
+  const hostActions = new Set((spec.host_actions || []).map((a) => a.host_id));
+  for (const d of Object.values(registry.deployments)) if (hostActions.has(d.host_id) && d.status !== "retired") touched.add(d.deployment_id);
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const b of Object.values({ ...registry.bindings, ...Object.fromEntries((spec.bindings || []).map((b) => [b.binding_id, b])) })) {
+      if (b.status === "retired" || (!touched.has(b.consumer_deployment_id) && !touched.has(b.provider_deployment_id))) continue;
+      for (const id of [b.consumer_deployment_id, b.provider_deployment_id].filter(Boolean)) if (!touched.has(id)) { touched.add(id); changed = true; }
+    }
+  }
+  for (const id of touched) inScopeDeployment(deployments[id], scope, id);
+}
+
+export function pinInputs(paths) {
+  const files = {};
+  let bytes = 0;
+  const walk = (p) => {
+    noSymlinks(p, { allowMissing: false });
+    const st = statSync(p);
+    if (st.isDirectory()) {
+      for (const name of readdirSync(p).sort()) walk(join(p, name));
+    } else if (st.isFile()) {
+      if (Object.hasOwn(files, p)) return;
+      bytes += st.size;
+      if (Object.keys(files).length >= 10000 || bytes > MAX_INPUT_BYTES) throw new OpsError("task inputs exceed 10000 files/256 MiB; use a reviewed bounded artifact tree");
+      files[p] = fileDigest(p);
+    } else throw new OpsError("task input must be a regular file or directory");
+  };
+  for (const p of paths) {
+    if (typeof p !== "string" || !isAbsolute(p) || p.split(/[\\/]/).includes("..")) throw new OpsError("task input paths must be absolute without traversal");
+    walk(resolve(p));
+  }
+  return files;
+}
+
+function markdown(task) {
+  return `# ${redact(task.request.title, [])}\n\n` +
+    `任务：\`${task.request.task_id}\`；控制端：\`${task.controller_id}\`；有效期：${task.expires_at}。\n\n` +
+    `范围：${task.request.scope.scope}；服务器：${task.request.scope.server_ids.join(", ")}；项目：${task.request.scope.project_ids.join(", ") || "无"}；影响/依赖项目：${task.request.scope.related_project_ids.join(", ") || "无"}。\n\n` +
+    `## Plan Mode\n\n${redact(task.request.plan, [])}\n\n` +
+    `## 固定顺序与精确规格\n\n` + task.request.steps.map((s, i) =>
+      `${i + 1}. ${redact(s.title, [])} — worker=${s.spec.worker}，operation=${s.spec.operation}，spec SHA256=${digest(s.spec)}；[受限规格](specs/${s.id}.json)。`
+    ).join("\n") + `\n\n## 授权边界\n\n此文件不是授权。明确实施请求且已展示上述计划后，入口可记录一次原始任务确认，不逐步骤再问。运行器只为这些冻结规格产生的范围内计划写入关联任务的机械批准；不声称用户逐一确认了未来的计划摘要。\n\n` +
+    `策略变更：${task.request.scope.allow_policy_changes}；公网映射：${task.request.scope.allow_public_ingress}；破坏性/迁移：${task.request.scope.allow_destructive}。\n\n` +
+    `输入文件：${Object.keys(task.input_digests).length}；执行器 SHA256：${task.engine_digest}。连接、凭据账本、输入文件、执行器漂移或过期即停止。\n\n` +
+    `失败/unknown/docs_pending 不自动重试、不自动迁移回滚。原 plan/approval/journal/双边回执仍是执行事实源。\n`;
+}
+
+export async function prepareTask(state, request, adapter = null) {
+  statePath(state);
+  adapter ??= await runtime();
+  const registry = adapter.load(state);
+  readRegistry(state);
+  validateRequest(request, registry);
+  for (const step of request.steps) adapter.validate(step.spec, "spec");
+  const task = {
+    schema_version: 1, artifact: "ops-task", controller_id: registry.controller.controller_id,
+    created_at: now(), expires_at: new Date(Date.now() + request.valid_for_hours * 3600000).toISOString(),
+    registry_revision: registry.revision, request: structuredClone(request),
+    engine_digest: adapter.engineDigest(), ledger_digest: digest(adapter.ledgerLoad(state)),
+    targets: Object.fromEntries(request.scope.server_ids.map((id) => [id, targetDigest(registry.hosts[id])])),
+    input_digests: pinInputs(request.input_paths),
+  };
+  const folder = taskFolder(state, request.task_id);
+  return withLock(join(state, "records", ".locks", "task-" + request.task_id), { operation: "task-plan" }, () => {
+    if (existsSync(folder)) throw new OpsError("task ID already exists; never overwrite task evidence");
+    for (const step of request.steps) writeJson(join(folder, "specs", step.id + ".json"), step.spec, { exclusive: true });
+    atomicWrite(join(folder, "PLAN.md"), markdown(task), 0o600, { exclusive: true });
+    writeJson(join(folder, "summary.json"), { schema_version: 1, artifact: "ops-task-summary", task_id: request.task_id,
+      scope: request.scope.scope, server_ids: request.scope.server_ids, project_ids: request.scope.project_ids,
+      related_project_ids: request.scope.related_project_ids, step_ids: request.steps.map((s) => s.id), created_at: task.created_at }, { exclusive: true });
+    // Commit marker written last. A crashed preparation is preserved, never auto-repaired.
+    writeJson(join(folder, "task.json"), task, { exclusive: true });
+    return { status: "prepared-not-authorized", task_id: request.task_id, task_digest: digest(task), plan: join(folder, "PLAN.md"), steps: request.steps.length };
+  });
+}
+
+export function authorizeTask(state, taskId, expected, by, statement, ackDestructive = null) {
+  const folder = taskFolder(state, taskId);
+  const task = readBoundedJson(join(folder, "task.json"));
+  if (digest(task) !== expected) throw new OpsError("task digest mismatch; reread the disclosed task plan");
+  active(task);
+  validateRequest(task.request, readRegistry(state));
+  if (typeof by !== "string" || !by.trim() || typeof statement !== "string" || statement.trim().length < 8) throw new OpsError("identified approver and explicit original task confirmation are required");
+  if (task.request.scope.allow_destructive && ackDestructive !== DESTRUCTIVE_ACK) throw new OpsError("destructive task requires an independently explicit exact-task acknowledgement");
+  const value = { schema_version: 1, artifact: "ops-task-authorization", task_id: taskId, task_digest: expected,
+    approved_by: by, statement, approved_at: now(), decision: "approved", destructive_ack: ackDestructive };
+  return withLock(join(state, "records", ".locks", "task-" + taskId), { operation: "task-authorize" }, () => {
+    writeJson(join(folder, "authorization.json"), value, { exclusive: true });
+    return { status: "authorized", task_id: taskId, task_digest: expected, note: "No per-step conversational re-confirmation inside this frozen task" };
+  });
+}
+
+export function assertPlanScope(plan, task, registry) {
+  const s = task.request.scope, projects = allowedProjects(s);
+  if (plan.controller_id !== task.controller_id || plan.engine_digest !== task.engine_digest) throw new OpsError("compiled plan controller/engine differs from authorized task");
+  for (const [id, h] of Object.entries(plan.hosts || {})) if (!s.server_ids.includes(id) || targetDigest(h) !== task.targets[id]) throw new OpsError(`compiled plan target outside authorization: ${id}`);
+  const scope = plan.registry_scope;
+  if (!scope) throw new OpsError("compiled plan has no registry scope");
+  for (const id of scope.hosts || []) if (!s.server_ids.includes(id)) throw new OpsError(`catalog server outside task: ${id}`);
+  for (const id of scope.projects || []) if (!projects.has(id)) throw new OpsError(`catalog project outside task: ${id}`);
+  for (const id of [...(scope.deployments || []), ...(plan.document_targets || []), ...(plan.affected_consumers || [])]) {
+    inScopeDeployment(plan.registry_after.deployments[id] || registry.deployments[id], s, id);
+  }
+  for (const id of scope.allocations || []) {
+    const a = plan.registry_after.allocations?.[id] || registry.allocations[id];
+    if (!a || !projects.has(a.owner_project_id) || (a.shared_owners || []).some((p) => !projects.has(p))) throw new OpsError("compiled allocation owner outside task");
+    inScopeDeployment(plan.registry_after.deployments[a.provider_deployment_id] || registry.deployments[a.provider_deployment_id], s, a.provider_deployment_id);
+  }
+  for (const id of scope.bindings || []) {
+    const b = plan.registry_after.bindings?.[id] || registry.bindings[id];
+    if (!b) throw new OpsError("compiled binding not found");
+    for (const did of [b.consumer_deployment_id, b.provider_deployment_id].filter(Boolean)) inScopeDeployment(plan.registry_after.deployments[did] || registry.deployments[did], s, did);
+  }
+  // A compiler omission must not hide an unrelated catalog mutation.
+  for (const group of ["hosts", "projects", "deployments", "allocations", "bindings"]) {
+    for (const id of new Set([...Object.keys(registry[group]), ...Object.keys(plan.registry_after[group] || {})])) {
+      if (digest(registry[group][id] ?? null) !== digest(plan.registry_after[group]?.[id] ?? null) && !(scope[group] || []).includes(id)) throw new OpsError(`unscoped compiled catalog change: ${group}/${id}`);
+    }
+  }
+  if ((scope.policies || digest(registry.policies) !== digest(plan.registry_after.policies)) && !s.allow_policy_changes) throw new OpsError("compiled plan changes unauthorized policies");
+  if ((scope.public_ingress || digest(registry.public_ingress ?? null) !== digest(plan.registry_after.public_ingress ?? null)) && !s.allow_public_ingress) throw new OpsError("compiled plan changes unauthorized public ingress");
+  for (const op of plan.operations || []) {
+    if (!s.server_ids.includes(op.host_id)) throw new OpsError("operation target outside task");
+    if (op.deployment_id) inScopeDeployment(plan.registry_after.deployments[op.deployment_id], s, op.deployment_id);
+    if (op.kind === "purge-quarantine" && !s.allow_destructive) throw new OpsError("unauthorized purge operation");
+  }
+  for (const [p, d] of Object.entries(plan.source_digests || {})) if (task.input_digests[resolve(p)] !== d) throw new OpsError(`unreviewed or changed local source input: ${p}; pin it in input_paths before authorization`);
+}
+
+function preflight(state, task, adapter, first = false) {
+  active(task);
+  const registry = adapter.load(state);
+  if (registry.controller.controller_id !== task.controller_id) throw new OpsError("task controller mismatch");
+  if (first && registry.revision !== task.registry_revision) throw new OpsError("catalog changed after task preparation; form a new disclosed task");
+  if (adapter.engineDigest() !== task.engine_digest) throw new OpsError("task executor drifted");
+  if (digest(adapter.ledgerLoad(state)) !== task.ledger_digest) throw new OpsError("credential ledger drifted after task authorization");
+  for (const [id, expected] of Object.entries(task.targets)) if (!registry.hosts[id] || targetDigest(registry.hosts[id]) !== expected) throw new OpsError(`task connection/identity drift: ${id}`);
+  if (digest(pinInputs(task.request.input_paths)) !== digest(task.input_digests)) throw new OpsError("task input files changed, disappeared or were added");
+  return registry;
+}
+
+export async function runTask(state, taskId, adapter = null) {
+  const folder = taskFolder(state, taskId);
+  adapter ??= await runtime();
+  const task = readBoundedJson(join(folder, "task.json"));
+  const auth = readBoundedJson(join(folder, "authorization.json"));
+  if (auth.artifact !== "ops-task-authorization" || auth.decision !== "approved" || auth.task_id !== taskId || auth.task_digest !== digest(task)) throw new OpsError("missing or mismatched task authorization");
+  if (task.request.task_id !== taskId) throw new OpsError("task path/identity mismatch");
+  return withLock(join(state, "records", ".locks", "task-" + taskId), { operation: "task-run", task_id: taskId }, () => {
+    if (existsSync(join(folder, "started.json"))) throw new OpsError("task already started; inspect its progress and original run receipts, never automatically replay it");
+    const initial = preflight(state, task, adapter, true);
+    validateRequest(task.request, initial);
+    writeJson(join(folder, "started.json"), { task_digest: digest(task), at: now() }, { exclusive: true });
+    const progress = { schema_version: 1, artifact: "ops-task-result", task_id: taskId, status: "running", steps: [], started_at: now(), updated_at: now() };
+    let phase = "planning";
+    try {
+      for (const step of task.request.steps) {
+        phase = "planning";
+        const registry = preflight(state, task, adapter);
+        assertSpecScope(step.spec, task.request.scope, registry);
+        const path = join(folder, "specs", step.id + ".json");
+        if (digest(readBoundedJson(path)) !== digest(step.spec)) throw new OpsError("frozen step specification drifted");
+        const compiled = adapter.compilePlan(state, path);
+        containedPath(state, compiled.plan_path);
+        const plan = readBoundedJson(compiled.plan_path);
+        identifier(compiled.run_id, "run_id");
+        if (compiled.run_id !== plan.run_id || plan.worker !== step.spec.worker || plan.operation !== step.spec.operation) throw new OpsError("compiled run identity/worker/operation mismatch");
+        if (digest(plan) !== compiled.plan_digest) throw new OpsError("compiled plan digest mismatch");
+        const row = { step_id: step.id, run_id: compiled.run_id, plan_digest: compiled.plan_digest,
+          plan_path: pathRelative(state, compiled.plan_path).replaceAll("\\", "/"), status: "planned-not-authorized" };
+        progress.steps.push(row);
+        progress.updated_at = now();
+        writeJson(join(folder, "progress.json"), progress);
+        assertPlanScope(plan, task, registry);
+        // Check inputs again after compilation and before delegating any approval.
+        preflight(state, task, adapter);
+        adapter.approval(state, compiled.run_id, compiled.plan_digest, "task:" + taskId,
+          `Delegated exact-spec authorization from task ${taskId}, digest ${auth.task_digest}; original approver ${auth.approved_by}.`);
+        row.status = "executing";
+        writeJson(join(folder, "progress.json"), progress);
+        preflight(state, task, adapter);
+        phase = "applying";
+        const result = adapter.apply(state, compiled.run_id);
+        row.status = result.status;
+        progress.updated_at = now();
+        writeJson(join(folder, "progress.json"), progress);
+        phase = "between-steps";
+        if (result.status !== "completed") {
+          progress.status = ["failed", "unknown", "docs_pending", "partial", "blocked"].includes(result.status) ? result.status : "blocked";
+          break;
+        }
+      }
+      if (progress.status === "running") progress.status = "completed";
+    } catch (error) {
+      progress.status = phase === "applying" ? "unknown" : "blocked";
+      progress.error = redact(error.message || String(error), []).slice(0, 2000);
+    }
+    progress.updated_at = now();
+    progress.recovery = progress.status === "completed" ? "none" : "Inspect progress and the original run with inspect-run; no automatic resume, docs-sync or migration retry. New actions need a new bounded task.";
+    writeJson(join(folder, "progress.json"), progress);
+    writeJson(join(folder, "result.json"), progress, { exclusive: true });
+    return { ...progress, record: folder };
+  });
+}

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

@@ -0,0 +1,107 @@
+/** Explicit controller/server/project routing and bounded workspace paths. */
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, isAbsolute, join, relative as pathRelative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { digest, exact, identifier, noSymlinks, OpsError, readJson } from "./core.mjs";
+
+export const WORKS = Object.freeze({
+  controller: "I-initialize", access: "S-server-connect", server: "H-host-manage",
+  project: "D-project-deploy", inventory: "V-inventory-view",
+});
+const WORKFLOW = resolve(dirname(fileURLToPath(import.meta.url)), "../../..");
+export const MAX_JSON_BYTES = 16 * 1024 * 1024;
+
+export function statePath(value) {
+  if (typeof value !== "string" || !isAbsolute(value) || value.includes("\0") || value.split(/[\\/]/).includes("..")) {
+    throw new OpsError("--state must be an explicit absolute path without traversal; never inferred from cwd");
+  }
+  const state = resolve(value);
+  const rel = pathRelative(WORKFLOW, state);
+  if (dirname(state) === state || rel === "" || (rel !== ".." && !rel.startsWith(".." + sep) && !isAbsolute(rel))) {
+    throw new OpsError("state must be a dedicated runtime directory outside static workflow assets");
+  }
+  noSymlinks(state, { allowMissing: false });
+  if (!statSync(state).isDirectory()) throw new OpsError("state is not a directory");
+  return state;
+}
+
+export function readBoundedJson(path) {
+  noSymlinks(path, { allowMissing: false });
+  const st = statSync(path);
+  if (!st.isFile() || st.size > MAX_JSON_BYTES) throw new OpsError("JSON file is not regular or exceeds 16 MiB");
+  return readJson(path);
+}
+
+export function readRegistry(state) {
+  statePath(state);
+  const value = readBoundedJson(join(state, "status.json"));
+  if (value.schema_version !== 3 || value.workflow !== "ops" || !Number.isSafeInteger(value.revision) || value.revision < 0) {
+    throw new OpsError("workspace requires OPS status schema v3; legacy state must be imported, not overwritten");
+  }
+  if (!value.controller || !value.controller.controller_id) throw new OpsError("initialize the controller first");
+  identifier(value.controller.controller_id, "controller_id");
+  if (typeof value.controller.state_root !== "string" || resolve(value.controller.state_root) !== resolve(state)) throw new OpsError("controller state_root mismatch; do not silently adopt another workspace");
+  for (const key of ["hosts", "projects", "deployments", "bindings", "allocations", "releases"]) {
+    if (!value[key] || typeof value[key] !== "object" || Array.isArray(value[key])) throw new OpsError(`invalid registry map: ${key}`);
+    if (Object.keys(value[key]).length > 10000) throw new OpsError(`registry map exceeds workspace bound: ${key}`);
+    for (const id of Object.keys(value[key])) identifier(id, key);
+  }
+  for (const [id, h] of Object.entries(value.hosts)) {
+    if (!h || h.host_id !== id || !["local", "ssh"].includes(h.transport)) throw new OpsError(`invalid host record: ${id}`);
+  }
+  for (const [id, p] of Object.entries(value.projects)) {
+    if (!p || p.project_id !== id) throw new OpsError(`invalid project record: ${id}`);
+  }
+  for (const [id, d] of Object.entries(value.deployments)) {
+    if (!d || d.deployment_id !== id || !Object.hasOwn(value.hosts, d.host_id) || !Object.hasOwn(value.projects, d.project_id)) {
+      throw new OpsError(`orphan or invalid deployment: ${id}`);
+    }
+  }
+  return value;
+}
+
+export function ids(value, label) {
+  if (!Array.isArray(value) || new Set(value).size !== value.length) throw new OpsError(`${label} must be an array of distinct IDs`);
+  return value.map((id) => identifier(id, label));
+}
+
+export function route(registry, context) {
+  exact(context, new Set(["scope", "server_ids", "project_ids"]), new Set(["scope", "server_ids", "project_ids"]), "context");
+  if (!Object.hasOwn(WORKS, context.scope)) throw new OpsError("scope must be controller, access, server, project or inventory");
+  const servers = ids(context.server_ids, "server_ids");
+  const projects = ids(context.project_ids, "project_ids");
+  if (context.scope === "controller" && (servers.length || projects.length)) throw new OpsError("controller scope cannot target a server or project; use S/H/D");
+  if (["access", "server"].includes(context.scope) && (servers.length !== 1 || projects.length)) throw new OpsError("S/H require exactly one explicit server and no project");
+  if (context.scope === "project" && (!servers.length || projects.length !== 1)) throw new OpsError("D requires explicit server(s) and exactly one project; no last-used/cwd fallback");
+  for (const id of servers) if (context.scope !== "access" && !Object.hasOwn(registry.hosts, id)) throw new OpsError(`unknown server: ${id}; enroll via S first`);
+  for (const id of projects) if (!Object.hasOwn(registry.projects, id)) throw new OpsError(`unknown project: ${id}; explicitly register the project first`);
+  return { scope: context.scope, work: WORKS[context.scope], controller_id: registry.controller.controller_id,
+    server_ids: servers, project_ids: projects, host_ids: servers, registration_required: servers.filter((id) => !Object.hasOwn(registry.hosts, id)), note: "server maps to Host.host_id; controller is never an implicit local server" };
+}
+
+export function catalogUnlocked(state) {
+  noSymlinks(join(state, ".locks", "catalog"));
+  if (existsSync(join(state, ".locks", "catalog"))) throw new OpsError("catalog lock held; inspect the owner before generating a new snapshot");
+}
+
+export function fileDigest(path) {
+  noSymlinks(path, { allowMissing: false });
+  if (!statSync(path).isFile() || statSync(path).size > MAX_JSON_BYTES) throw new OpsError("file exceeds snapshot bound");
+  return digest(readFileSync(path));
+}
+
+/** Pin identity and transport, not changeable host_services annotations. */
+export function targetDigest(host) {
+  if (!host) throw new OpsError("missing target host");
+  const { host_id, root, identity, platform, transport, connection } = host;
+  const known_hosts_digest = transport === "ssh" ? fileDigest(connection.known_hosts) : null;
+  return digest({ host_id, root, identity, platform, transport, connection, known_hosts_digest });
+}
+
+export function containedPath(root, path) {
+  if (typeof path !== "string" || !isAbsolute(path) || path.split(/[\\/]/).includes("..")) throw new OpsError("expected an absolute contained artifact path");
+  const rel = pathRelative(resolve(root), resolve(path));
+  if (!rel || rel === ".." || rel.startsWith(".." + sep) || isAbsolute(rel)) throw new OpsError("artifact path outside workspace");
+  noSymlinks(path, { allowMissing: false });
+  return resolve(path);
+}

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

@@ -0,0 +1,80 @@
+/** Additive workspace commands. Legacy CLI semantics remain owned by cli.mjs. */
+import { isAbsolute } from "node:path";
+import { OpsError } from "./core.mjs";
+import { readBoundedJson, readRegistry, route, statePath } from "./workspace.mjs";
+import { checkServer } from "./server_checks.mjs";
+import { generateFleet } from "./fleet.mjs";
+import { authorizeTask, prepareTask, runTask } from "./tasks.mjs";
+
+export const COMMANDS = Object.freeze(["workspace-help", "route", "server-check", "fleet", "task-plan", "task-authorize", "task-run"]);
+const options = {
+  route: ["scope", "server", "project"],
+  "server-check": ["server", "profile", "min-free-mib", "min-memory-mib"],
+  fleet: ["stale-hours"], "task-plan": ["file"],
+  "task-authorize": ["task", "digest", "by", "statement", "ack-destructive"], "task-run": ["task"], "workspace-help": [],
+};
+export function workspaceCommand(argv) {
+  const rest = [...argv];
+  for (let i = rest.length - 1; i >= 0; i--) if (rest[i] === "--state") rest.splice(i, 2);
+  return COMMANDS.includes(rest[0]) ? rest[0] : null;
+}
+export function parseWorkspaceArgs(argv) {
+  const command = workspaceCommand(argv);
+  if (!command) throw new OpsError("unknown workspace command");
+  const args = [...argv], out = { command };
+  args.splice(args.indexOf(command), 1);
+  const allowed = new Set(["state", ...options[command]]);
+  while (args.length) {
+    const flag = args.shift();
+    if (!flag.startsWith("--") || !allowed.has(flag.slice(2))) throw new OpsError(`unknown ${command} argument: ${flag}`);
+    const key = flag.slice(2);
+    if (Object.hasOwn(out, key)) throw new OpsError(`duplicate argument: ${flag}`);
+    const value = args.shift();
+    if (!value || value.startsWith("--")) throw new OpsError(`${flag} needs a value`);
+    out[key] = value;
+  }
+  if (command !== "workspace-help" && !out.state) throw new OpsError("--state is required and must be absolute");
+  return out;
+}
+const required = (args, key) => { if (!args[key]) throw new OpsError(`--${key} is required`); return args[key]; };
+const list = (v) => v ? v.split(",") : [];
+function integer(value, fallback) {
+  if (value === undefined) return fallback;
+  if (!/^[1-9][0-9]*$/.test(value) || !Number.isSafeInteger(Number(value))) throw new OpsError("threshold must be a positive integer");
+  return Number(value);
+}
+export async function main(argv = process.argv.slice(2)) {
+  try {
+    const args = parseWorkspaceArgs(argv);
+    if (args.command === "workspace-help") {
+      process.stdout.write(JSON.stringify({ commands: options, usage: "node ops.mjs --state ABSOLUTE_STATE COMMAND [options]",
+        workflow: "I controller; S server access; H server baseline; D project deployment; V local inventory",
+        task: "task-plan -> record existing explicit user authorization once via task-authorize -> task-run; no per-step reconfirmation; no automatic retry",
+        legacy: "All other commands retain the original plan/approve/apply contracts" }, null, 2) + "\n");
+      return 0;
+    }
+    const state = statePath(args.state);
+    // Keep the existing complete schema/semantic validator authoritative in the installed runtime.
+    const { load } = await import("./model.mjs");
+    load(state);
+    let result;
+    switch (args.command) {
+      case "route": result = route(readRegistry(state), { scope: required(args, "scope"), server_ids: list(args.server), project_ids: list(args.project) }); break;
+      case "server-check": result = await checkServer(state, required(args, "server"), { profile: args.profile ?? "base",
+        minFreeMiB: integer(args["min-free-mib"], 1024), minMemoryMiB: integer(args["min-memory-mib"], 256) }); break;
+      case "fleet": result = generateFleet(state, { staleHours: integer(args["stale-hours"], 24) }); break;
+      case "task-plan": {
+        const file = required(args, "file");
+        if (!isAbsolute(file)) throw new OpsError("--file must be an absolute task request path");
+        result = await prepareTask(state, readBoundedJson(file)); break;
+      }
+      case "task-authorize": result = authorizeTask(state, required(args, "task"), required(args, "digest"), required(args, "by"), required(args, "statement"), args["ack-destructive"] ?? null); break;
+      case "task-run": result = await runTask(state, required(args, "task")); break;
+    }
+    process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+    return ["blocked", "failed", "partial", "unknown", "stale", "docs_pending", "interrupted"].includes(result.status) ? 2 : 0;
+  } catch (error) {
+    process.stderr.write(JSON.stringify({ status: "blocked", error: error.message || String(error) }) + "\n");
+    return 2;
+  }
+}

package/template/workflows/ops/common/tools/validate-ops.mjs

@@ -5,10 +5,10 @@ import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawnSync } from "node:child_process";
 import { validateStatus } from "./opslib/model.mjs";
+import { WORKS } from "./opslib/workspace.mjs";
 
 const tools = dirname(fileURLToPath(import.meta.url));
 const root = resolve(tools, "../..");
-const expected = ["D-project-deploy", "H-host-manage", "I-initialize"];
 const args = process.argv.slice(2);
 
 try {
@@ -16,12 +16,17 @@ try {
     const works = readdirSync(root, { withFileTypes: true })
       .filter((x) => x.isDirectory() && !["common", "_state", "__pycache__"].includes(x.name))
       .map((x) => x.name).sort();
-    if (JSON.stringify(works) !== JSON.stringify(expected)) throw new Error("OPS must expose exactly three work directories");
+    const expected = Object.values(WORKS).sort();
+    if (JSON.stringify(works) !== JSON.stringify(expected)) throw new Error("OPS Work directories differ from explicit scope router");
+    const manifest = JSON.parse(readFileSync(join(root, "manifest.json"), "utf8"));
+    const stages = manifest.stages.map((s) => s.id).sort();
+    if (new Set(stages).size !== stages.length || JSON.stringify(stages) !== JSON.stringify(works.map((w) => w.slice(2)).sort())) throw new Error("manifest stages differ from Work entries");
+    for (const stage of manifest.stages) for (const id of stage.after) if (!stages.includes(id)) throw new Error("unknown manifest prerequisite " + id);
     for (const id of works) {
       const text = readFileSync(join(root, id, id + ".md"), "utf8");
-      if (!text.includes("type: workflow-entry") || !text.includes("读取范围")) throw new Error("invalid work " + id);
+      if (!text.includes("type: workflow-entry") || !text.includes("读取范围") || !text.includes("id: ops/" + id.slice(2))) throw new Error("invalid work " + id);
     }
-    for (const file of ["INDEX.md", "README.md", "manifest.json", "runtime-contract.json", "common/USAGE.md", "common/CAPABILITIES.md", "common/tools/opslib/execution.mjs"]) {
+    for (const file of ["INDEX.md", "README.md", "manifest.json", "runtime-contract.json", "common/USAGE.md", "common/WORKSPACE-USAGE.md", "common/CAPABILITIES.md", "common/templates/FLEET.html", "common/schemas/fleet-view.schema.json", "common/schemas/task-request.schema.json", "common/schemas/server-check.schema.json", "common/tools/opslib/execution.mjs", "common/tools/opslib/tasks.mjs", "common/tools/opslib/fleet.mjs"]) {
       if (!existsSync(join(root, file))) throw new Error("missing " + file);
     }
     for (const name of readdirSync(join(root, "common/schemas")).filter((x) => x.endsWith(".json"))) {
@@ -30,10 +35,8 @@ try {
     JSON.parse(readFileSync(join(root, "common/toolchains/volta-linux.json"), "utf8"));
     validateStatus(JSON.parse(readFileSync(join(root, "_state/status.json"), "utf8")));
     console.log("resource schema valid");
-    console.log(JSON.stringify({
-      valid: true, version: "2.2.0", workers: works, schema_version: 3,
-      scope: "static and empty-resource-schema check; not live target acceptance",
-    }, null, 2));
+    console.log(JSON.stringify({ valid: true, version: manifest.version, workers: works, schema_version: 3,
+      scope: "static and empty-resource-schema check; not live target acceptance" }, null, 2));
   } else if (args.length === 2 && ["--state-root", "--state"].includes(args[0])) {
     const p = spawnSync(process.execPath, [join(tools, "ops.mjs"), "--state", resolve(args[1]), "validate"], { encoding: "utf8", timeout: 30000 });
     if (p.status !== 0) throw new Error(p.stdout + p.stderr);

package/template/workflows/ops/manifest.json

@@ -22,31 +22,50 @@
       "risk": "local-reversible",
       "context_budget": 16000
     },
+    {
+      "id": "server-connect",
+      "after": [
+        "initialize"
+      ],
+      "inputs": [
+        "server",
+        "verified-host-key",
+        "key-or-agent"
+      ],
+      "outputs": [
+        "server-registration",
+        "inventory",
+        "server-checks"
+      ],
+      "risk": "production-critical",
+      "context_budget": 20000
+    },
     {
       "id": "host-manage",
       "after": [],
       "inputs": [
-        "host",
+        "server",
         "spec",
-        "approval"
+        "task-authorization-or-plan-approval"
       ],
       "outputs": [
         "host-run",
         "verification",
-        "dual-documents"
+        "dual-documents",
+        "server-checks"
       ],
       "risk": "production-critical",
-      "context_budget": 22000
+      "context_budget": 24000
     },
     {
       "id": "project-deploy",
       "after": [],
       "inputs": [
         "project",
-        "hosts",
+        "explicit-servers",
         "bindings",
         "spec",
-        "approval"
+        "task-authorization-or-plan-approval"
       ],
       "outputs": [
         "release",
@@ -54,7 +73,24 @@
         "dual-documents"
       ],
       "risk": "production-critical",
-      "context_budget": 28000
+      "context_budget": 30000
+    },
+    {
+      "id": "inventory-view",
+      "after": [],
+      "inputs": [
+        "resource-state",
+        "server-checks",
+        "task-summaries"
+      ],
+      "outputs": [
+        "fleet-markdown",
+        "fleet-json",
+        "fleet-html",
+        "view-receipt"
+      ],
+      "risk": "local-reversible",
+      "context_budget": 16000
     }
   ]
 }