@namewta/speculo 1.0.5 → 1.0.7

package/template/workflows/ops/common/rules/recovery.md

@@ -0,0 +1,15 @@
+# 失败、未知、文档补交与回退
+
+所有运行保存 immutable plan.json、approval.json、execution.json、journal.jsonl 和目标 receipts。新代码/schema 会改变 engine_digest，旧未执行批准失效；不要先升级执行器再尝试用旧批准继续。
+
+apply 不能执行第二次；resume 只跳过已有成功终态回执，对 started-without-terminal 保持 unknown，不盲目再调用。同一终态 failed 动作必须编制新恢复计划。目标锁被未知运行占用时，inspect-run 核对步骤与实际服务/数据，不能直接删锁继续。
+
+控制端目录锁可以使用 recover-controller-lock，但要求显式确认并证明记录 PID 已结束；目标 active-call 或 started-only 不提供假定成功的“强制修复”快捷键。必须由管理员检查进程、服务与具体副作用，再在保留原证据的前提下实施对应恢复。原 unknown 记录不应被擦除。
+
+远端写文件失败产生终态 failed 回执；docs-sync 能恢复传输中断但目标已有成功回执的文档写入。对于真实终态文档写入失败（如权限/内容漂移），修复后用新的文档维护计划重新采集前置条件，不覆盖旧回执。docs-sync 不重跑任何业务动作。
+
+回滚是一个新计划，可使用旧构件和旧 env 版本；原发布 run 保持不变。源码、镜像摘要、配置、默认版本、健康门和双边文档同样需要校验。数据库 schema/data 回退必须项目专用，不能仅换 image 或 service 就声称数据恢复。
+
+迁移与接管需单独的 verified adoption。adopt_existing/allow_adopt_roots 只承认经过用户批准的既有目录，不意味未知数据库/凭据可被覆盖。写入前保留旧文件在 host_root/_host/runs/run-id/before/，但这些副本不是数据库一致性备份。
+
+清理分两步：有限 cache/log 的同卷 quarantine；另一次批准后 purge-quarantine 精确 run/item。purge 是不可逆删除，只接受成功隔离证据和内容清单匹配，不能把数据、env、备份或 release 目录当成垃圾。

package/template/workflows/ops/common/rules/shared-services.md

@@ -0,0 +1,13 @@
+# 公共服务生命周期
+
+Project.kind 为 app 或 shared-service；mysql-main/minio-main/redis-main 与 APP 同级。Allocation 是 provider 内的逻辑资源及 owner/data_group/environment/application credential；Binding 是某部署对该 allocation 的端点/网络/凭据引用。
+
+同 APP 的多机副本可引用同一 allocation；不同 APP 默认不同数据库、桶、ACL 和账号。跨 owner 必须 shared_owners 显式批准；跨环境不靠相同账号自动打通。数字 Redis DB/key prefix 不是独立恢复或资源隔离的证明。
+
+内置 MySQL/Redis 分配针对受管 Compose provider：管理员与应用账号必须不同，账号名必须与明文账本一致；MySQL 只授本库权限，Redis 只授被批准 key 范围并验证 ACL SAVE。MinIO 使用指定 mc 版本客户端；其创建用户命令短暂暴露应用密码给特权本机进程查看者，必须显式 allow_secret_argv，不隐瞒该风险。需要避开此风险时采用外部已分配并验证的资源。
+
+已经存在的未知数据库/用户/桶不自动接管；existing 需要真实授权范围与实际探测。计划记录具体版本和端点；任何密码轮换都不复用原 allocation 创建批准。未知产品不猜安装/备份命令。
+
+更新 APP 不升级 provider；退役 APP 不删除 provider、数据、逻辑资源、账号或网络。provider 有 active 消费者时不能退役。维护 provider 必须列全受影响消费者并获确认；控制端和相关服务器文档同步。
+
+单 APP 数据恢复与公共实例恢复分开。备份能力不足即阻塞该承诺；不能用共享实例快照覆盖其他 APP 的新数据。迁移单独定义复制、追平、切换、验证和保留旧端点；工作流不假装原子跨主机提交。

package/template/workflows/ops/common/schemas/allocation.schema.json

@@ -0,0 +1,92 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:speculo:ops:allocation:v1",
+  "type": "object",
+  "properties": {
+    "allocation_id": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+      "maxLength": 80
+    },
+    "provider_deployment_id": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+      "maxLength": 80
+    },
+    "owner_project_id": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+      "maxLength": 80
+    },
+    "environment": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+      "maxLength": 80
+    },
+    "data_group": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+      "maxLength": 80
+    },
+    "resource_kind": {
+      "enum": [
+        "database",
+        "bucket",
+        "redis-acl",
+        "generic"
+      ]
+    },
+    "resource_name": {
+      "type": "string",
+      "minLength": 1
+    },
+    "credential_ref": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*@[1-9][0-9]*$"
+    },
+    "shared_owners": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+        "maxLength": 80
+      },
+      "uniqueItems": true
+    },
+    "status": {
+      "enum": [
+        "planned",
+        "active",
+        "retained",
+        "retired"
+      ]
+    },
+    "recovery_scope": {
+      "enum": [
+        "logical",
+        "provider-wide",
+        "application-export",
+        "unverified"
+      ]
+    },
+    "notes": {
+      "type": "string",
+      "minLength": 1
+    }
+  },
+  "required": [
+    "allocation_id",
+    "provider_deployment_id",
+    "owner_project_id",
+    "environment",
+    "data_group",
+    "resource_kind",
+    "resource_name",
+    "credential_ref",
+    "shared_owners",
+    "status",
+    "recovery_scope",
+    "notes"
+  ],
+  "additionalProperties": false
+}

package/template/workflows/ops/common/schemas/approval.schema.json

@@ -1,28 +1,48 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "urn:speculo:ops:approval:v2",
-  "title": "Ops Plan Approval",
+  "$id": "urn:speculo:ops:approval:v1",
   "type": "object",
-  "required": ["schema_version", "artifact", "scope", "project_id", "approval_id", "change", "plan_path", "plan_digest", "source_revision", "target_fingerprint", "approved_batches", "excluded_batches", "confirmed_global_environment_keys", "conditions", "decision", "decision_summary", "decided_at", "expires_at"],
   "properties": {
-    "schema_version": {"const": 2},
-    "artifact": {"const": "ops-plan-approval"},
-    "scope": {"enum": ["global", "project"]},
-    "project_id": {"type": ["string", "null"], "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"},
-    "approval_id": {"type": "string", "pattern": "^APPROVAL-[0-9]{3}$"},
-    "change": {"type": "string"},
-    "plan_path": {"type": "string", "pattern": "^plan/plan-[0-9]{3}\\.json$"},
-    "plan_digest": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
-    "source_revision": {"type": "string", "minLength": 1},
-    "target_fingerprint": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
-    "approved_batches": {"type": "array", "items": {"type": "string", "pattern": "^B[0-9]{2}$"}, "minItems": 1, "uniqueItems": true},
-    "excluded_batches": {"type": "array", "items": {"type": "string", "pattern": "^B[0-9]{2}$"}, "uniqueItems": true},
-    "confirmed_global_environment_keys": {"type": "array", "items": {"type": "string"}, "uniqueItems": true},
-    "conditions": {"type": "array", "items": {"type": "string"}, "uniqueItems": true},
-    "decision": {"const": "approved"},
-    "decision_summary": {"type": "string", "minLength": 1},
-    "decided_at": {"type": "string", "format": "date-time"},
-    "expires_at": {"type": "string", "format": "date-time"}
+    "schema_version": {
+      "const": 1
+    },
+    "artifact": {
+      "const": "ops-plan-approval"
+    },
+    "run_id": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+      "maxLength": 80
+    },
+    "plan_digest": {
+      "type": "string",
+      "minLength": 1
+    },
+    "approved_by": {
+      "type": "string",
+      "minLength": 1
+    },
+    "approved_at": {
+      "type": "string",
+      "minLength": 1
+    },
+    "decision": {
+      "const": "approved"
+    },
+    "statement": {
+      "type": "string",
+      "minLength": 1
+    }
   },
+  "required": [
+    "schema_version",
+    "artifact",
+    "run_id",
+    "plan_digest",
+    "approved_by",
+    "approved_at",
+    "decision",
+    "statement"
+  ],
   "additionalProperties": false
 }

package/template/workflows/ops/common/schemas/binding.schema.json

@@ -0,0 +1,73 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:speculo:ops:binding:v1",
+  "type": "object",
+  "properties": {
+    "binding_id": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+      "maxLength": 80
+    },
+    "consumer_deployment_id": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+      "maxLength": 80
+    },
+    "mode": {
+      "enum": [
+        "dedicated",
+        "shared",
+        "external"
+      ]
+    },
+    "provider_deployment_id": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "allocation_id": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "endpoint": {
+      "type": "string",
+      "minLength": 1
+    },
+    "credential_ref": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*@[1-9][0-9]*$"
+    },
+    "status": {
+      "enum": [
+        "planned",
+        "active",
+        "retired"
+      ]
+    },
+    "component": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+      "maxLength": 80
+    },
+    "network": {
+      "type": "string",
+      "minLength": 1
+    }
+  },
+  "required": [
+    "binding_id",
+    "consumer_deployment_id",
+    "mode",
+    "provider_deployment_id",
+    "allocation_id",
+    "endpoint",
+    "credential_ref",
+    "status",
+    "component",
+    "network"
+  ],
+  "additionalProperties": false
+}

package/template/workflows/ops/common/schemas/deployment.schema.json

@@ -0,0 +1,244 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:speculo:ops:deployment:v1",
+  "type": "object",
+  "properties": {
+    "deployment_id": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+      "maxLength": 80
+    },
+    "project_id": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+      "maxLength": 80
+    },
+    "host_id": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+      "maxLength": 80
+    },
+    "environment": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+      "maxLength": 80
+    },
+    "instance": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+      "maxLength": 80
+    },
+    "layout": {
+      "enum": [
+        "flat",
+        "instances"
+      ]
+    },
+    "method": {
+      "enum": [
+        "compose",
+        "native"
+      ]
+    },
+    "version": {
+      "type": "string",
+      "minLength": 1
+    },
+    "observed_version": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "root": {
+      "type": "string",
+      "minLength": 1
+    },
+    "status": {
+      "enum": [
+        "planned",
+        "running",
+        "configured",
+        "docs_pending",
+        "completed",
+        "failed",
+        "unknown",
+        "retired"
+      ]
+    },
+    "installed_at": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "updated_at": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "run_id": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "compose_name": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "storage": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "component": {
+            "type": "string",
+            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+            "maxLength": 80
+          },
+          "purpose": {
+            "type": "string",
+            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+            "maxLength": 80
+          },
+          "path": {
+            "type": "string",
+            "minLength": 1
+          },
+          "owner": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "component",
+          "purpose",
+          "path"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "commands": {
+      "type": "object",
+      "properties": {
+        "start": {
+          "type": "array",
+          "items": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        },
+        "stop": {
+          "type": "array",
+          "items": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        },
+        "verify": {
+          "type": "array",
+          "items": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        }
+      },
+      "required": [
+        "start",
+        "stop",
+        "verify"
+      ],
+      "additionalProperties": false
+    },
+    "credential_refs": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*@[1-9][0-9]*$"
+      },
+      "uniqueItems": true
+    },
+    "backup": {
+      "type": "string",
+      "minLength": 1
+    },
+    "recovery": {
+      "type": "string",
+      "minLength": 1
+    },
+    "notes": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "source": {
+      "type": "object",
+      "properties": {
+        "type": {
+          "enum": [
+            "local",
+            "git",
+            "image",
+            "manual"
+          ]
+        },
+        "location": {
+          "type": "string",
+          "minLength": 1
+        },
+        "revision": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "required": [
+        "type",
+        "location",
+        "revision"
+      ],
+      "additionalProperties": false
+    },
+    "service": {
+      "type": "object"
+    }
+  },
+  "required": [
+    "deployment_id",
+    "project_id",
+    "host_id",
+    "environment",
+    "instance",
+    "layout",
+    "method",
+    "version",
+    "observed_version",
+    "root",
+    "status",
+    "installed_at",
+    "updated_at",
+    "run_id",
+    "compose_name",
+    "storage",
+    "commands",
+    "credential_refs",
+    "backup",
+    "recovery",
+    "notes",
+    "source",
+    "service"
+  ],
+  "additionalProperties": false
+}

package/template/workflows/ops/common/schemas/host.schema.json

@@ -0,0 +1,88 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:speculo:ops:host:v1",
+  "type": "object",
+  "properties": {
+    "host_id": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+      "maxLength": 80
+    },
+    "display_name": {
+      "type": "string",
+      "minLength": 1
+    },
+    "platform": {
+      "enum": [
+        "linux",
+        "windows",
+        "darwin"
+      ]
+    },
+    "transport": {
+      "enum": [
+        "local",
+        "ssh"
+      ]
+    },
+    "root": {
+      "type": "string",
+      "minLength": 1
+    },
+    "identity": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    },
+    "connection": {
+      "type": "object",
+      "properties": {
+        "hostname": {
+          "type": "string",
+          "minLength": 1
+        },
+        "username": {
+          "type": "string",
+          "minLength": 1
+        },
+        "port": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 65535
+        },
+        "known_hosts": {
+          "type": "string",
+          "minLength": 1
+        },
+        "identity_file": {
+          "type": "string",
+          "minLength": 1
+        },
+        "node": {
+          "type": "string",
+          "minLength": 1
+        },
+        "sudo": {
+          "type": "boolean"
+        },
+        "shell": {
+          "enum": [
+            "posix",
+            "powershell"
+          ]
+        }
+      },
+      "required": [],
+      "additionalProperties": false
+    }
+  },
+  "required": [
+    "host_id",
+    "display_name",
+    "platform",
+    "transport",
+    "root",
+    "identity",
+    "connection"
+  ],
+  "additionalProperties": false
+}