@aipt/idp-deploy 0.1.4 → 0.1.5

package/docs/features/kubernetes-gitops-deployment-backend/IMPLEMENTATION-PLAN.md

@@ -0,0 +1,43 @@
+# Kubernetes GitOps 部署后端实施计划
+
+- 状态：执行中
+- 批次：`idp-deploy.kubernetes-gitops-deployment-backend@2`
+- 目标：以成熟 Kubernetes 控制器和独立 GitOps 仓实现应用 create/update/verify/remove 的同一事务内核，并完成本机轻量生产同构验收。
+
+## 冻结范围
+
+1. 消费 Bench `EnvironmentBinding`、应用 `ComponentContract` 与 `ReleaseCandidate`，生成带摘要的不可变 `DeploymentPlan`。
+2. Apply 前复验全部输入、Git HEAD 和目标路径 Preimage；冲突时 fail-closed。
+3. 确定性生成 `applications/<application>/base` 与 `overlays/<environment>`，镜像只允许 OCI digest。
+4. 保存仓库外 Preimage 和 Apply Evidence；移除只能来自显式 remove Plan。
+5. 提供 `foundation doctor/verify`，验证 kind/ACK、Argo CD、Argo Rollouts、External Secrets、cert-manager、ExternalDNS、OpenTelemetry 与观测端点。
+6. fixture 必须走正式 Plan、Apply、Verifier 与 Remove 链路，不复制旁路实现。
+
+## 不变量
+
+- 不写 Secret 值、云 Access Key、证书私钥或可变镜像 tag。
+- Bench 拥有环境能力事实；GitOps 仓拥有批准后的期望状态；Kubernetes/观测后端拥有运行事实。
+- `idp-deploy` 只拥有发布事务、Preimage、Repository State 引用和 Evidence。
+- 本地与阿里云 ACK 使用同一 manifests；差异只来自 EnvironmentBinding 和安装 profile。
+- 本地资源不足或云凭据缺失必须明确失败，不得把未部署状态报告为成功。
+
+## 验证矩阵
+
+| 场景 | 证据 |
+| --- | --- |
+| 合法 create/update | 固定输出、OCI digest、GitOps 路径与 Plan digest |
+| 人工并发修改 | Apply 因 HEAD 或 Preimage 摘要冲突而停止 |
+| 输入被替换 | Apply 因 Component/Binding/Candidate 摘要变化而停止 |
+| Secret 泄漏 | Renderer 拒绝敏感字段和值 |
+| verify | 控制器 Deployment/CRD 就绪，应用 Synced/Healthy |
+| remove | 显式 remove Plan、Preimage 可恢复、保留 Namespace/数据边界 |
+
+## 本机与云端决策
+
+- 本机 16GB、Docker 约 8GB：常驻轻量控制面（Argo CD、Rollouts、External Secrets、cert-manager、ExternalDNS dry-run、本地 OTel）和一个 fixture。
+- Prometheus/Grafana/Loki 可用严格限额的验收 profile 短时运行；长期生产优先 ACK + 阿里云日志服务/托管 Prometheus/Grafana。
+- 没有阿里云凭据时只生成和验证 ACK profile，不创建远程资源。
+
+## 清理
+
+应用通过正式 remove Plan 清理。独立本机验收集群使用固定名称 `idp-foundation`，仅可用 `kind delete cluster --name idp-foundation` 删除，不触碰其他 context 或 Compose 服务。

package/docs/features/kubernetes-gitops-deployment-backend/PREIMAGE.json

@@ -0,0 +1,18 @@
+{
+  "schemaVersion": "idp.preimage/v1",
+  "capturedAt": "2026-08-31T20:00:00.000+08:00",
+  "repositoryHead": "9a0c2a19da803f14deb833d298595f0f4a09d399",
+  "files": {
+    "README.md": "sha256:00bea309617aa5147ea29a10e753d68ce418e1f204a81bd450237f06fd996c4a",
+    "package.json": "sha256:d166bcccd526936d946275dfc1de836bf77f62d29345b399aa4bf3104f4d40a2",
+    "src/cli.mjs": "sha256:e0fa121b7fcb2678c023b1f9d04d36fceb02d034beb57d6fbf91471a641a2159",
+    "tests/cli.test.mjs": "sha256:79250c0799a03ab4a4043ffe742ab37a2edef911de01666a82f661fa7a40b3af",
+    "docs/features/kubernetes-gitops-deployment-backend/DESIGN.md": "sha256:b66b1cad7819aaa02960982b0ae6437460cd66ac5903ccba3b04c44f33e9af10",
+    "docs/features/kubernetes-gitops-deployment-backend/FOUNDATION-ARCHITECTURE.md": "sha256:c41f6dc6cdf47d086730ad9bb656e5ef5339a4b2612fd625b243eef3bd3c49b8",
+    "src/gitops.mjs": null,
+    "src/foundation.mjs": null,
+    "contracts/deployment-plan.schema.json": null,
+    "tests/gitops.test.mjs": null,
+    "tests/foundation.test.mjs": null
+  }
+}

package/docs/features/local-source-compose-deployment/DESIGN.md

@@ -0,0 +1,74 @@
+# 本地源码 Compose 受控部署设计
+
+- 状态：approved
+- Feature：`idp.local-source-compose-deployment/v1`
+- 批准依据：用户明确批准“本地项目跳过 Buildx/ACR，直接使用项目 Docker Compose 完整实现”。
+
+## 目标
+
+为 `development/local` 提供不依赖远程 OCI、Kubernetes 或 GitOps 的快速部署闭环，同时保留 IDP 的 Config Dir、不可变 Plan、Preimage、Apply、Verify、Evidence 和用户修改保护。
+
+## 所有权
+
+- Dyyto 生成并验证项目工程事实与 `ApplicationConfigContract`，不操作 Docker。
+- 项目拥有 `Dockerfile` 与 `deploy/compose.local.yaml`，不得保存真实 Secret。
+- idp-deploy 物化仓库外应用配置，生成并执行 Local DeploymentPlan，验证精确 Compose Project 运行态。
+- 未来 `idp` CLI 只委托本 Kernel，不复制规则。
+
+## 公共入口
+
+```text
+idpctl app config-init --project <绝对目录>
+idpctl local app plan --project <绝对目录> --compose-file <绝对文件> --output <Config Dir内文件>
+idpctl local app apply --plan <绝对文件>
+idpctl local app verify --plan <绝对文件>
+idpctl local app stop --plan <绝对文件>
+idpctl local app remove --plan <绝对文件> --confirm <application-id>
+```
+
+## 合同与事实
+
+输入：
+
+- `project-capabilities.json`；
+- `config/application-config.json`；
+- 项目 Compose 文件；
+- 仓库外应用 `.env` 和 `*_FILE`；
+- Docker Compose 只读规范化输出。
+
+Plan 固定项目 realpath、三个项目输入摘要、应用配置快照摘要、Compose project name、允许执行的命令和创建时刻。Apply 前重新核验全部摘要；任何变化均 fail-closed。
+
+运行事实写入 `$IDP_CONFIG_DIR/runtime/local-applications/<application-id>.json`，回执写入 `$IDP_CONFIG_DIR/evidence/local-applications/`。项目仓库不保存运行状态或 Secret。
+
+## 配置物化
+
+`app config-init` 只消费 Dyyto `ApplicationConfigContract`：
+
+- 创建 `$IDP_CONFIG_DIR/applications/<application-id>`、`secrets/`、`certs/`；
+- `.env` 只写 value 与相对 `*_FILE` 引用；
+- 文件 Binding 创建为 `0600` 空普通文件；
+- 已有值和文件不覆盖；新增键前保存 Preimage；
+- required 空文件导致 plan/apply 失败；外部系统签发的 Token 不伪造。
+
+## Compose 安全门禁
+
+在任何构建前使用 `docker compose config --format json` 验证：
+
+- 禁止 privileged、host network、Docker socket、设备直通和额外 capability；
+- 禁止 Compose 内联 Secret 字段与敏感 environment literal；
+- published port 必须绑定回环地址；
+- 禁止未受控的绝对宿主 bind mount；
+- 不允许显式 container_name；
+- 至少一个服务具有 healthcheck。
+
+本模式允许 `build`，但不允许 `push`。它生成 `local-source` Evidence，明确 `promotable: false`；测试和生产必须重新从可追溯 Git revision 生成双架构 OCI digest。
+
+## Apply、恢复和移除
+
+Apply 固定执行同一 Compose project：先保存运行态 Preimage，再执行 `build` 和 `up -d --wait`。规范化 Compose 可能含环境投影，只在内存中校验和摘要，绝不落盘。失败时，如果旧运行态及其 Plan 输入仍通过 CAS 复验，则用旧 Plan 恢复；首次部署失败执行 `down --remove-orphans`，不删除 volume。
+
+`stop` 只停止容器；`remove` 要求 application-id 精确确认，只执行 `down --remove-orphans`，默认不带 `--volumes`。用户修改 Compose、配置或运行态后必须重新 Plan。
+
+## 脚手架与验收
+
+正式 fixture 进入 `.examples/local-source-compose`，通过同一 Kernel 生成配置与 Plan。自动测试覆盖：配置不覆盖、required Secret、输入漂移、危险 Compose、Apply 失败、Verify、Stop 和 Remove。真实 Docker 人工验收命令写入 README；没有 Docker 时合同测试仍须运行。

package/docs/features/local-source-compose-deployment/IMPLEMENTATION-PLAN.md

@@ -0,0 +1,13 @@
+# 本地源码 Compose 受控部署实施计划
+
+- 状态：approved
+- 对应 DESIGN：`idp.local-source-compose-deployment/v1`
+- Plan：本文件内容批准后不可变；范围变化必须新增 Addendum。
+
+1. 增加 ApplicationConfigContract 读取、身份核对和安全物化。
+2. 增加 Compose 规范化、安全策略与 Local DeploymentPlan。
+3. 增加 Apply、Verify、Stop、Remove、Preimage、运行态和 Evidence。
+4. 将公共入口接入 `idpctl`，所有用户可见输出使用简体中文。
+5. 增加 fixture consumer、负向合同测试和 README 新项目操作手册。
+6. 运行定向测试、`npm run check`；有 Docker 时运行真实示例，否则明确保留人工验收步骤。
+

package/docs/features/smartgo-managed-business-profile/DESIGN-ADDENDUM-01-HOST-OCI-LAYOUT-ORAS-FALLBACK.md

@@ -0,0 +1,78 @@
+# 宿主机 OCI Layout + ORAS 单并发发布回退 DESIGN Addendum 01
+
+- 状态：APPROVED
+- Feature：`smartgo-managed-business-profile`
+- 批准来源：用户要求在不降低现有发布门禁的前提下，解决 Docker Desktop BuildKit 经宿主代理推送大 Layer 超时的问题，并明确授权实现正式回退链路。
+- 适用仓库：仅 `idp-deploy`
+
+## 1. 问题与目标
+
+默认发布仍使用 Buildx 双架构直接 `--push`。只有该构建/推送进程失败、远程 tag 在构建前不存在、且发布事务尚未进入镜像配置 Apply、备份、Profile 切换或 Binding 发布时，才允许启用宿主机回退：Buildx 以完全相同的平台、基础镜像、Build Arg、Secret、SBOM、Provenance、发布标签和源码/Plan 摘要重新导出 OCI Image Layout；随后由预先置于外部 Config Dir、版本和 SHA-256 均已固定验证的 ORAS，通过宿主网络以单并发复制到同一远端 tag。
+
+回退只改变“从 BuildKit 到 OCI Registry 的传输路径”，不得改变构建事实、OCI Index、发布身份或后续验证、锁定和部署事务。
+
+## 2. 显式启用与工具信任
+
+根 `.env` 增加以下非敏感配置：
+
+```dotenv
+IDP_OCI_LAYOUT_ORAS_FALLBACK_ENABLED=false
+IDP_ORAS_BINARY_PATH=tools/oras/oras
+IDP_ORAS_VERSION=UNCONFIGURED
+IDP_ORAS_SHA256=UNCONFIGURED
+```
+
+- 默认关闭，关闭时保持既有 Buildx push 快路径，且不要求 ORAS 文件存在。
+- 开启时，`IDP_ORAS_BINARY_PATH` 必须是 Config Dir 内相对路径，路径各级不得是符号链接；目标必须是单硬链接、仅部署用户可访问且具备 owner execute 的普通文件。
+- `IDP_ORAS_VERSION` 必须是精确 SemVer；`IDP_ORAS_SHA256` 必须是精确 `sha256:<64 hex>`。
+- 发布器先计算文件摘要，再执行 `<oras> version` 并核对精确版本。任一事实不一致都在默认 Buildx push 前 fail-closed。
+- `config init` 只创建受保护的 `tools/oras` 目录和配置键，不下载、不生成、不替换 ORAS，也不读取 Docker 凭据。
+
+## 3. 回退状态机
+
+```text
+远端 tag 不存在
+  -> 校验源码 CAS、Plan、Dockerfile/Prebuild、ORAS 固定事实
+  -> Buildx 双架构 --push（默认快路径）
+       成功 -> 读取 metadata -> 远端验证
+       失败 -> Buildx 双架构 OCI Layout 导出
+                  -> 校验本地 metadata digest
+                  -> oras cp --from-oci-layout <layout>:<releaseTag>
+                             <remoteTag> --concurrency 1
+                  -> 远端 inspect / Index digest / 双平台 labels 验证
+  -> 源码 CAS 再验证
+  -> Config CAS 再验证
+  -> 备份/恢复演练
+  -> 保存配置 Preimage并 Apply
+```
+
+回退不得在下列情况启动：Prebuild/合同失败、Secret staging 失败、metadata 安全校验失败、远端 tag 在构建前已存在、源码/Config 漂移、已经进入 Apply/切换，或 ORAS 未显式启用并固定。
+
+## 4. OCI Layout 与发布证据
+
+- Layout 只允许创建在仓库外 `IDP_RUNTIME_DIR/tmp` 下的本次随机私有目录；禁止复用既有目录、跟随链接或写入仓库/Config Dir。
+- OCI 导出继续固定 `linux/amd64,linux/arm64`、`--provenance=mode=max`、同一固定 SBOM generator、同一 Dockerfile/context、Build Args、BuildKit Secret、SmartGo host aliases 和四个发布标签。
+- ORAS 命令固定使用 `cp --from-oci-layout ... --concurrency 1`；不得传用户名、密码、Token、Docker config 路径或其他网络降级参数。认证只由 ORAS 的标准宿主凭据发现完成，发布器不读取或复制凭据。
+- ORAS 成功后必须沿用远端 OCI Index inspect、Index digest 与双平台发布标签验证。远端 Index digest 必须与 OCI Layout metadata digest 一致；因为该 digest 覆盖 Buildx 生成的双平台 Manifest 与证明 Manifest，任何传输丢失都会失败。
+- Artifact v2 新增 `host-oci-layout-oras` evidence，仅记录 layout Index digest、ORAS 版本、ORAS 二进制摘要和平台 labels；不得记录宿主路径、命令输出、Secret 或凭据位置。
+- 成功、失败或异常时都删除 metadata、临时 npmrc 投影和 OCI Layout；清理失败不得伪装成成功。
+
+## 5. 错误与恢复语义
+
+- 默认 Buildx push 失败且回退未配置时，保留原错误并且不修改 `.env`、`images.lock.json`、运行态或 Binding。
+- 回退构建、ORAS copy、layout metadata、远端 digest/labels 任一步失败时，不生成 Artifact、不进入配置 Apply。
+- 默认 push 的错误不得把 stderr 或 Secret 写入 Artifact、Plan、receipt 或用户可见回退说明；只保留安全错误码和阶段。
+- 远端 tag 不可变策略、登录授权、双平台和发布标签门禁不变；回退不是绕过 Registry 策略的通道。
+
+## 6. 验收
+
+自动测试必须证明：
+
+1. 默认关闭时只有原始 Buildx `--push`，失败后不调用 ORAS、不导出 Layout且配置不变。
+2. 开启时在默认 push 失败后，第二次 Buildx 使用相同构建事实并输出 OCI Layout，ORAS 命令精确单并发，之后仍执行远端 digest/labels 验证。
+3. ORAS 缺失、符号/硬链接、权限过宽、不可执行、摘要不符、版本不符、非 Config Dir 路径均在默认 push 前失败。
+4. Layout digest 与远端 digest 不同、ORAS 失败、回退后的源码或 Config 漂移均不 Apply。
+5. Artifact 不含 Config Dir、Runtime Dir、ORAS 路径、npmrc 路径、Token 或命令 stderr；Layout 和 staging 无残留。
+6. 既有正常发布、Registry 收养、双架构、SBOM/Provenance、SmartGo Secret/CAS、备份恢复和回滚测试全部保持通过。
+
+本 Addendum 不授权真实镜像发布、外部 Config Dir 修改、远程资源写入或任何其他仓库修改。

package/docs/features/smartgo-managed-business-profile/DESIGN-ADDENDUM-02-SMARTGO-BACKUP-RECOVERY-HEALTH.md

@@ -0,0 +1,57 @@
+# SmartGo 备份后运行态有界恢复 DESIGN Addendum 02
+
+- 状态：APPROVED
+- Feature：`smartgo-managed-business-profile`
+- 批准来源：用户已明确要求保证 SmartGo 按 `idp-deploy` 规范可部署，并授权并行完整实现；本 Addendum 修复真实 `core-smartgo backup create` 暴露的运行态恢复缺陷。
+- 适用仓库：仅 `idp-deploy`
+
+## 1. 已证实的问题
+
+SmartGo 协调备份会先停止六个写入服务，再暂停对象存储，生成 PostgreSQL 与对象归档，随后解除对象存储暂停并执行 Compose `up --wait`。真实运行中 MinIO 刚解除暂停时健康状态尚未恢复，第一次 `up --wait` 即失败；既有补偿再次只启动六个 SmartGo writer，仍可能落在同一短暂不健康窗口，最终抛出 `IDP_SMARTGO_BACKUP_RECOVERY_FAILED`，并把 SmartGo 业务容器留在 stopped。人工稍后执行完整 Profile `up` 才恢复十三个服务。
+
+缺陷不在数据归档或健康检查标准，而在恢复状态机只有单次尝试、只覆盖 writer 子集，也没有把“对象存储恢复健康”和“原 Profile 全量恢复健康”拆成可验证阶段。
+
+## 2. 目标与不变量
+
+1. 备份正常收尾和异常补偿共用同一个恢复内核，不允许两套时序漂移。
+2. 解除对象存储暂停后，先用 Compose 原生 `--wait` 与固定 `--wait-timeout` 等待对象存储健康，再恢复并验证 `resolveProfileServices(profile)` 返回的完整原 Profile。
+3. 每一健康阶段最多三次尝试，尝试之间固定等待两秒；不得无限重试、不得移除 `--wait`、不得放宽 Compose 健康检查。
+4. 如果对象存储独立等待阶段暂时失败，仍必须尝试完整 Profile 恢复；只有完整 Profile `up --wait` 成功才算运行态恢复完成。
+5. 真实备份、归档或校验错误在运行态恢复成功后必须原样重新抛出；不得用一次恢复成功掩盖数据错误。
+6. 完整 Profile 无法在有界窗口内恢复时，必须抛出 `IDP_SMARTGO_BACKUP_RECOVERY_FAILED`，并在仓库外失败代次中保存原始安全错误码、恢复阶段、精确尝试次数和完整服务集合；不得记录 stderr、Secret 或绝对 Config Dir。
+7. 正常成功路径只有在对象归档已验证且完整 Profile 已重新健康后，才能原子发布备份代次。
+
+## 3. 恢复状态机
+
+```text
+停止 SmartGo writers
+  -> 暂停对象存储
+  -> pg_dump + 对象归档 + 归档安全校验
+  -> 解除对象存储暂停（单次命令；失败不提前终止恢复）
+  -> 对象存储 Compose up --wait --wait-timeout 30（最多 3 次）
+  -> 完整原 Profile Compose up --wait --wait-timeout 60（最多 3 次）
+       成功 -> 运行态恢复已证明 -> 正常路径可发布代次 / 异常路径重抛原始错误
+       失败 -> 写失败证据 -> IDP_SMARTGO_BACKUP_RECOVERY_FAILED
+```
+
+完整 Profile 恢复必须使用 Profile 的服务事实源，`core-smartgo` 包含 PostgreSQL、Registry、Tech、Flow、Portal、SmartGo 对象存储、六个 SmartGo 长期服务和 Edge；`business-smartgo` 包含其九服务闭包。不得手写第二份服务清单。
+
+## 4. 错误与证据语义
+
+- 正常收尾中的瞬时 Compose 失败只作为有界尝试事实；后续完整 Profile 健康时备份可继续。
+- 数据阶段失败时，恢复内核只负责恢复运行态；恢复成功后仍抛原始错误对象。
+- 运行态恢复失败时，错误详情只携带安全的 `originalErrorCode`、`recoveryErrorCode`、失败阶段与失败证据目录，不携带进程 stderr。
+- `backup-failure.json` 升级为 `idp.smartgo-backup-failure/v2`，记录 `unpause`、`objectStoreHealth`、`profile` 三段结果和各自尝试次数。
+
+## 5. 验收
+
+自动测试必须证明：
+
+1. MinIO 解除暂停后的第一次对象存储健康等待失败、第二次成功时，完整 Profile 恢复并正常发布备份。
+2. 完整 Profile 前两次失败、第三次成功时，不误报恢复失败，且每次都保留严格 `--wait --wait-timeout`。
+3. 三次均失败时停止重试，完整服务集合每次都被恢复，失败证据包含精确次数与原始错误码。
+4. 数据归档/校验失败但运行态恢复成功时，仍抛原始数据错误。
+5. 对象存储独立等待三次失败后仍尝试完整 Profile；完整 Profile 成功即可证明包括 MinIO 在内的全 Profile 健康。
+6. 非 SmartGo Profile 行为不变；相关测试、全量 `npm run check`、语法检查和 `git diff --check` 全部通过。
+
+本 Addendum 不授权执行真实备份、修改外部 Config Dir、重启真实容器、发布镜像或修改其他仓库。

package/docs/features/smartgo-managed-business-profile/DESIGN-ADDENDUM-03-OCI-CAPABLE-BUILDER.md

@@ -0,0 +1,35 @@
+# OCI Layout 回退的显式 Builder DESIGN Addendum 03
+
+- 状态：APPROVED
+- 关联 DESIGN：`DESIGN-ADDENDUM-01-HOST-OCI-LAYOUT-ORAS-FALLBACK.md`
+- 批准依据：主任务明确同意补齐显式固定 OCI-capable Builder 配置与 inspect 门禁。
+- 技术依据：Docker 官方 OCI exporter 页面明确把 `docker-container` 等非 `docker` driver 作为可移植基线。当前宿主的 `desktop-linux` + `docker` driver 在新版 containerd image store 上已有真实 OCI Layout 导出成功证据，但这是实现特性而不是可跨 Docker 版本、context 和 image store 复现的正式合同，因此不被发布门禁采用。
+
+## 1. 必要修正
+
+仅配置 ORAS 不足以让回退具备可移植运行合同：Docker Desktop 默认 `desktop-linux` Builder 使用 `docker` driver，其 OCI exporter 行为受 Docker/BuildKit 版本与 image store 实现影响，不能仅凭当前宿主的一次成功就当作企业部署合同。因此启用回退时必须同时指定一个由企业预先供应的 OCI-capable Buildx Builder：
+
+```dotenv
+IDP_OCI_LAYOUT_BUILDER=UNCONFIGURED
+```
+
+- 回退关闭时不要求 Builder，不调用 `buildx inspect`，不改变原有默认 Builder 快路径。
+- 回退开启时 Builder 名称必须是受限的非敏感标识，不得使用 `UNCONFIGURED`。
+- 发布器只执行无 `--bootstrap` 的 `docker buildx inspect <builder>`，只接受 `docker-container`、`kubernetes` 和 `remote`，并要求运行节点联集同时声明 `linux/amd64` 与 `linux/arm64`。`docker` 与其他 driver 全部拒绝，避免 Builder endpoint 与当前 Docker context/image store 证据错配。
+- inspect 失败、Builder 未运行、driver 不支持或平台缺失时，在任何构建前 fail-closed，且错误不保存 inspect stdout/stderr。
+
+## 2. 同一构建事实
+
+默认 direct push 与失败后 OCI Layout 导出必须都显式传入同一 `--builder <name>`。这保证两次构建共享同一 Builder 实例、driver 和 cache 边界；回退仍只改变 exporter 与 metadata staging。
+
+## 3. 供应边界
+
+`idp-deploy` 不执行 `buildx create`、`buildx use`、`buildx inspect --bootstrap` 或任何 BuildKit 镜像下载。Builder 必须由宿主供应流程提前创建和启动，且 `docker-container` driver 的 BuildKit 镜像应使用企业批准的 digest 固定引用。
+
+## 4. 验收
+
+1. 默认关闭不 inspect Builder、不增加 `--builder`。
+2. 开启时缺少 Builder 配置在 Docker 前失败。
+3. `docker` driver、stopped Builder、缺失 amd64/arm64 任一情况在 Docker build 前失败；平台名后的 Buildx 手工声明 `*` 只作标记而不改变平台身份。
+4. inspect 命令不含 `--bootstrap`，direct push 与 Layout 导出携带同一 Builder。
+5. 不自动创建、切换、启动或下载 Builder；全部原有 ORAS、OCI digest、双架构、labels、SBOM/Provenance 和 CAS 门禁保持不变。

package/docs/features/smartgo-managed-business-profile/DESIGN.md

@@ -0,0 +1,131 @@
+# SmartGo 受管业务 Profile DESIGN
+
+- 状态：APPROVED
+- 批准来源：用户于 2026-08-31 明确要求保证 SmartGo 可按 idp-deploy 规范部署，并与 SmartGo 业务开发并行推进。
+- 适用仓库：仅 `idp-deploy`
+- Feature ID：`smartgo-managed-business-profile`
+
+## 1. 目标
+
+在不把 SmartGo 加入默认 IDP Core、也不读取业务源码运行的前提下，为 SmartGo 提供一个可独立选择的 `business-smartgo` Profile。该 Profile 必须复用 idp-deploy 已有的外部 Config Dir、不可变 OCI 镜像、运行时投影、Profile 切换、健康验证、备份和隔离恢复语义，使 SmartGo 团队能够并行开发业务，而部署者只消费已发布镜像。
+
+## 2. 边界与事实所有权
+
+- SmartGo 拥有业务代码、数据库 Schema、Migration、应用健康端点与业务恢复校验命令。
+- idp-deploy 只拥有 Compose 编排、外部配置合同、镜像锁、运行时最小投影、数据库物理备份恢复和运维证据。
+- 本 Feature 不修改 SmartGo、Dyyto、Tech、Bench 或 Aura；尤其禁止读取、修改或集成 Aura。
+- `business-smartgo` 不加入 `foundation`、`core` 或 `full`，避免业务系统成为 IDP 控制面的启动依赖。
+- 容器不得挂载 SmartGo 源码、整个 `IDP_CONFIG_DIR` 或其他组件配置；只挂载内容寻址代次中的 SmartGo 专属只读投影。
+
+## 3. Profile 模型修订
+
+现有 Profile 将“配置组件/Compose 片段”和“长期运行服务集合”视为同一集合，无法准确表达一个业务组件包含多个进程的事实。本 Feature 将保持 `resolveProfile()` 的组件语义，并新增长期运行服务投影：
+
+```text
+business-smartgo
+  components: postgresql, smartgo, edge
+  services:   postgresql, smartgo-api, smartgo-agent-runtime,
+              smartgo-worker, smartgo-gotology, smartgo-operations, edge
+```
+
+一次性 `postgresql-bootstrap` 与 `smartgo-migrate` 不进入长期服务集合；Compose `up --wait` 仍必须等待它们成功，Verifier 只要求长期服务运行且健康。
+
+## 4. 配置与安全合同
+
+根 Config Dir 只增加非敏感镜像事实：
+
+```dotenv
+IDP_SMARTGO_IMAGE=UNCONFIGURED
+```
+
+SmartGo 的全部业务配置位于：
+
+```text
+$IDP_CONFIG_DIR/components/smartgo/
+├── .env
+├── secrets/
+│   ├── database-url
+│   ├── postgresql-password
+│   ├── identity-service-token
+│   ├── identity-client-secret
+│   ├── renderer-callback-token
+│   ├── object-store-access-key-id
+│   ├── object-store-access-key-secret
+│   └── npmrc
+└── trust/
+```
+
+规则：
+
+- `.env` 不得内联密码、Token、访问密钥、数据库 URL 或 npm 凭据，敏感值只用相对 `*_FILE` 引用。
+- `SMARTGO_AUTH_MODE=local-open` 是首批唯一允许的身份模式；它不要求 OIDC，但只允许宿主回环暴露。
+- 容器内固定绑定 `0.0.0.0`，所有宿主暴露由 Edge 的 `127.0.0.1` 绑定控制。
+- 数据库和对象存储 Secret 必须在启动前非空；未启用的可选外部能力可以保留空文件，但不得把占位值解释为有效凭据。
+- SmartGo 服务只接收 `/run/idp-config`，且该目录仅包含 `components/smartgo` 声明的文件。
+- SmartGo 镜像必须以 OCI Index digest 固定，并同时证明 `linux/amd64` 与 `linux/arm64`。
+
+## 5. Compose 合同
+
+新增独立 `compose/smartgo.yaml`，包含：
+
+- `smartgo-migrate`：一次性执行正式 Migration；成功后 API 才能启动。
+- `smartgo-api`：内部端口 `3200`，健康端点 `/ready`。
+- `smartgo-agent-runtime`：内部端口 `3400`，健康端点 `/ready`。
+- `smartgo-worker`：内部端口 `3300`，健康端点 `/ready`。
+- `smartgo-gotology`：内部端口 `3000`，健康端点 `/api/health`。
+- `smartgo-operations`：内部端口 `3101`，健康端点 `/api/health`。
+
+所有服务使用同一已锁定 SmartGo OCI 镜像，不发布宿主端口、不挂载业务源码、以非 root 用户运行、只读根文件系统、丢弃 Linux capabilities，并只加入内部后端网络和必要的受控 egress 网络。Edge 提供 `/smartgo/` 入口，默认仍仅监听回环。
+
+## 6. 发布、镜像锁与 BOM
+
+- `IDP_SMARTGO_IMAGE` 纳入 `images.lock.json` v2，平台证据必须含 `linux/arm64`。
+- Release defaults 为 SmartGo 声明独立构建合同和 OCI repository suffix `/smartgo`。
+- SmartGo 构建只能通过 `$IDP_CONFIG_DIR/components/smartgo/.env` 中的 `SMARTGO_NPMRC_FILE` 取得 BuildKit `npmrc` Secret；不得回退到仓库、`HOME` 或命令行明文 Token。
+- `release deploy business-smartgo` 的 OCI Plan、Artifact、Deployment Plan 和最终 receipt 构成 SmartGo 部署 BOM；均记录精确镜像 digest、双平台证据、源码摘要和 Plan digest。
+- 本批只执行本地合同测试，不推送远程 OCI 资源。
+
+## 7. 数据、备份与恢复
+
+P0 数据边界为 idp-deploy 管理的 PostgreSQL `smartgo` 数据库。SmartGo 二进制对象存储保持外部 S3-compatible/OSS 所有权，不伪装成已被数据库备份覆盖。
+
+- `backup create business-smartgo` 创建 PostgreSQL custom dump，记录摘要和 Profile 数据集。
+- `backup verify` 校验不可变 Generation。
+- `restore test` 在隔离数据库中执行恢复与通用数据库验证。
+- `restore apply/verify/promote` 复用单数据库逻辑切换，保留 Preimage，失败自动切回。
+- 在 SmartGo 提供版本化 `backup-boundary`/`restore-verify` 业务命令之前，idp-deploy 只证明数据库物理与通用 SQL 边界，不宣称对象存储或领域不变量已恢复；该门禁必须在回执和运维文档中明确。
+
+## 8. 验收
+
+自动证据：
+
+1. Config init 幂等创建 SmartGo 目录、`.env` 与全部引用文件，升级时先保存 Preimage。
+2. Doctor 拒绝内联 Secret、非 `local-open`、空必需 Secret、非 digest 镜像、缺少 arm64 镜像证据和非回环暴露。
+3. Renderer 只投影 SmartGo 专属配置，不包含其他组件 Secret 或整个 Config Dir。
+4. Compose config 证明片段独立、无源码挂载、无宿主直出端口、最小权限与健康检查。
+5. pull/switch/up/verify 通过自动化 runner 证明 Profile、服务集合和 Edge Probe。
+6. backup/restore 单数据库路径包含 `postgresql:smartgo` 并受现有摘要、Preimage、隔离恢复合同约束。
+7. 外部临时 Config Dir smoke 在不写仓库的情况下完成 `config init`、Secret 准备、双平台镜像锁校验、`doctor --require-configured`、Runtime Render 和 Compose config。
+
+人工验收在 SmartGo 镜像正式发布后执行：
+
+```bash
+export IDP_CONFIG_DIR=/absolute/external/idp
+node bin/idpctl.mjs config init
+node bin/idpctl.mjs config generate-secrets
+node bin/idpctl.mjs pull business-smartgo
+node bin/idpctl.mjs switch business-smartgo
+node bin/idpctl.mjs verify business-smartgo
+node bin/idpctl.mjs backup create business-smartgo
+```
+
+预期：所有用户可见输出为简体中文；`http://127.0.0.1:8080/smartgo/` 可访问；配置、Secret、数据、备份和运行态均不写入仓库。
+
+## 9. 明确不做
+
+- 不部署 Keycloak，不实现 OIDC。
+- 不把 SmartGo 纳入默认 Core。
+- 不创建对象存储的虚假备份证明。
+- 不在 idp-deploy 中复制 SmartGo 业务配置解析或 Migration 逻辑。
+- 不触碰 Aura。
+

package/docs/features/smartgo-managed-business-profile/IMPLEMENTATION-PLAN-ADDENDUM-01.md

@@ -0,0 +1,25 @@
+# SmartGo 本地对象存储与多进程合同 Plan Addendum 01
+
+- 状态：APPROVED / IMMUTABLE
+- 关联 Plan：`2026-08-31-smartgo-managed-business-profile-v1`
+- 批准依据：主任务在 Apply 前明确要求本机验收默认使用 idp-deploy PostgreSQL 与本地 S3/MinIO；SmartGo Owner 同步了已批准的多进程容器合同。
+
+## 新增不可变事实
+
+- 长期服务集合增加 `smartgo-studio`。
+- `compose/smartgo.yaml` 同时提供 `smartgo-object-store` 与一次性 `smartgo-object-store-init`；SmartGo 仓库的 standalone overlay 不进入受管 Profile。
+- MinIO Server 与 Client 镜像都进入双平台 OCI Image Lock/BOM。
+- 对象数据位于仓库外 `$IDP_DATA_DIR/smartgo/object-store`；`business-smartgo` Backup Generation 同时包含 `postgresql:smartgo` 与 `smartgo-object-store:objects`。
+- 备份先停止 SmartGo 写入服务，再暂停 MinIO、归档对象和创建数据库 custom dump；失败必须恢复被停服务。
+- Restore test 校验数据库与对象归档；Apply 在隔离 Candidate 中恢复两者。由于这是数据库与对象的组合数据集，P0 生产 promote 必须 fail-closed，直到实现带对象目录 Preimage 的组合原子切换；不能把只切数据库描述为完整恢复。
+- SmartGo 镜像命令以 Owner 合同中的 `/workspace/deploy/container-entrypoint.mjs --` 入口为准；idp-deploy 只声明各服务 argv，不复制入口实现。
+
+## 新增允许文件
+
+- `compose/smartgo.yaml`
+- `src/acceptance.mjs`
+- `tests/acceptance.test.mjs`
+- 与对象归档/恢复直接相关的 `src/operations.mjs` 和测试。
+
+本 Addendum 不改变原 Plan 的仓库边界和禁止事项。
+

package/docs/features/smartgo-managed-business-profile/IMPLEMENTATION-PLAN-ADDENDUM-02.md

@@ -0,0 +1,14 @@
+# SmartGo 多站点与组合 Profile Plan Addendum 02
+
+- 状态：APPROVED / IMMUTABLE
+- 关联 Plan：`2026-08-31-smartgo-managed-business-profile-v1`
+- 批准依据：主任务在 Apply 期间发现并明确修正两个部署可用性前置事实。
+
+## 新增不可变事实
+
+1. Gotology、Operations 与 Studio 当前都没有 Next.js `basePath/assetPrefix` 合同，不能通过同一 Origin 的路径前缀发布。受管 Edge 必须把三站点分别发布到回环端口 `13000`、`13101`、`13002` 的根路径；默认 `8080` 只承担 API、对象和控制面路径。Verifier 除健康端点外必须抓取每个首页并至少验证一个页面引用的 `/_next/` 静态资源可读。
+2. 单活动 Profile 是 idp-deploy 的有意不变量。`switch business-smartgo` 会替换现有 Core，因此新增显式 opt-in `core-smartgo`，组件为默认 Core 加 SmartGo，长期服务集合为 Core 服务加 SmartGo 全部长期服务。SmartGo 仍不得加入默认 `core`、`full` 或 `foundation`。
+3. 从 `core` 切换到 `core-smartgo` 必须保留并重新验证 PostgreSQL、Registry、Tech、Flow、Portal 和 Edge；自动测试必须使用长期服务投影而不是配置组件集合判断服务集合。
+
+本 Addendum 不授权修改业务 App，不放宽回环和 Secret 约束。
+

package/docs/features/smartgo-managed-business-profile/IMPLEMENTATION-PLAN-ADDENDUM-03.md

@@ -0,0 +1,16 @@
+# SmartGo 非 Git 本机源码证据 Plan Addendum 03
+
+- 状态：APPROVED / IMMUTABLE
+- 关联 Plan：`2026-08-31-smartgo-managed-business-profile-v1`
+- 批准依据：主任务在 Release Apply 前确认当前 SmartGo 工作区不是 Git 仓库，同时禁止通过 `git init` 伪造发布身份。
+
+## 新增不可变事实
+
+- `IDP_ALLOW_NON_GIT_SMARTGO_SOURCE=true` 只允许 `private/development` 本机验证；`production` 必须 fail-closed。
+- 非 Git 模式必须读取并绑定 `.dockerignore`，确定性清点 Docker build context；硬拒绝链接、Secret、`.env`、`.git`、`.dyyto`、`node_modules`、`dist`、`.next`、`.artifacts`、coverage 与测试产物。
+- OCI Plan 必须记录 `sourceMode=dockerignore-development` 与清单摘要。
+- Build 完成后必须重新清点并对比文件数、摘要和 source mode；并行业务修改会使 Apply 停止，不能推送错误源码事实。
+- 该模式不等于企业 Release provenance。正式企业发布仍要求 Git revision；切换到生产前必须把开关设为 `false`。
+
+本 Addendum 不授权初始化或修改 SmartGo Git 元数据。
+

package/docs/features/smartgo-managed-business-profile/IMPLEMENTATION-PLAN-ADDENDUM-04.md

@@ -0,0 +1,24 @@
+# SmartGo Next 运行时缓存边界 Plan Addendum 04
+
+- 状态：APPROVED / IMMUTABLE
+- 关联 Plan：`2026-08-31-smartgo-managed-business-profile-v1`
+- 批准依据：主任务在受管运行验收前明确要求补齐三个 Next standalone 进程在只读根文件系统下的最小可写缓存，并确认镜像中的真实工作目录。
+
+## 新增不可变事实
+
+1. Gotology、Operations 与 Studio 的 `server.js` 分别位于并切换工作目录到 `/workspace/apps/{gotology,operations,studio-poc}/.artifacts/standalone`。
+2. 三个服务只能增加各自工作目录下的 `.next/cache` tmpfs，精确路径为：
+   - `/workspace/apps/gotology/.artifacts/standalone/.next/cache`
+   - `/workspace/apps/operations/.artifacts/standalone/.next/cache`
+   - `/workspace/apps/studio-poc/.artifacts/standalone/.next/cache`
+3. 每个缓存 tmpfs 必须显式绑定 `IDP_CONTAINER_UID`、`IDP_CONTAINER_GID` 与 `mode=0700`；Gotology/Operations 上限为 `128m`，Studio 上限为 `256m`。
+4. 三个服务继续使用 `read_only: true`，保留通用 `/tmp` tmpfs；API、Agent Runtime、Worker、Migration 和其他服务不得获得这些 Next 缓存写边界。
+5. 独立 Compose 中旧的 `/workspace/apps/*/.next/cache` 不是镜像真实写入路径，不得复制到受管 Compose。
+
+## Apply 与验证
+
+1. 复验 `PREIMAGE-ADDENDUM-02.json` 后只修改 `compose/smartgo.yaml` 与对应契约测试。
+2. 测试必须证明三个服务各自只有一个精确 Next 缓存 tmpfs、UID/GID/mode/容量正确、旧路径不存在，且只读根文件系统不被放宽。
+3. 执行定向 Compose 契约测试、Compose config smoke 与完整 `npm run check`。
+
+本 Addendum 不授权修改 SmartGo 或其他仓库，也不改变镜像、配置、网络、Secret、数据或备份边界。

package/docs/features/smartgo-managed-business-profile/IMPLEMENTATION-PLAN-ADDENDUM-05.md

@@ -0,0 +1,27 @@
+# SmartGo 备份一致性窗口 Plan Addendum 05
+
+- 状态：APPROVED / IMMUTABLE
+- 关联 Plan：`2026-08-31-smartgo-managed-business-profile-v1`
+- 批准依据：主任务在部署前审计发现已签发对象上传 URL 可绕过已停止的 SmartGo writer，明确要求收紧数据库与对象存储的连续协调窗口。
+
+## 新增不可变事实
+
+1. 仅包含 SmartGo 的 Profile 才进入本协调窗口；其他 Profile 的停写、数据库 Dump、Registry 与恢复语义不得改变。
+2. 进入窗口前可完成其他数据集备份；窗口内的外部动作顺序必须连续为：
+   - 停止全部 SmartGo writer；
+   - 立即 pause `smartgo-object-store`，阻断已签发上传 URL；
+   - 创建并校验 `smartgo` PostgreSQL custom dump；
+   - 归档 SmartGo 对象目录，校验归档摘要、路径和节点类型；
+   - unpause `smartgo-object-store`；
+   - 恢复全部 SmartGo writer 并等待健康。
+3. Stop/Pause/Unpause/Restart 命令即使出现部分成功后报错，也必须进入补偿路径；补偿顺序固定为先 unpause 对象存储，再恢复 writer。
+4. 任何阶段失败都不得发布 Generation；部分文件和不含 Secret 的失败阶段、错误码、恢复结果必须移动到仓库外 `IDP_BACKUP_DIR/failed`。
+5. 自动恢复本身失败时必须返回显式恢复失败错误，不能吞掉错误并伪装成原运行态已恢复。
+
+## Apply 与验证
+
+1. 复验 `PREIMAGE-ADDENDUM-03.json` 后只修改 `src/operations.mjs` 与 `tests/operations.test.mjs`。
+2. 自动测试精确证明成功路径命令顺序、每个协调阶段的失败补偿、失败证据和非 SmartGo Profile 无 SmartGo 编排调用。
+3. 执行定向 Operations 测试与完整 `npm run check`。
+
+本 Addendum 不授权修改 SmartGo 或其他仓库，不改变恢复切换、镜像、配置、网络和 Secret 合同。

package/docs/features/smartgo-managed-business-profile/IMPLEMENTATION-PLAN-ADDENDUM-06.md

@@ -0,0 +1,22 @@
+# SmartGo Studio 临时状态边界 Plan Addendum 06
+
+- 状态：APPROVED / IMMUTABLE
+- 关联 Plan：`2026-08-31-smartgo-managed-business-profile-v1`
+- 批准依据：Workspace Owner 冻结 `local-open` Studio 状态合同为 `SMARTGO_STUDIO_STATE_MODE=ephemeral-fixture` 与 `SMARTGO_STUDIO_DATA_DIRECTORY=/run/smartgo/studio`，主任务明确要求部署前同步受管配置、Doctor 与最小可写目录。
+
+## 新增不可变事实
+
+1. SmartGo 受管 `local-open` 模式必须且只能使用 `SMARTGO_STUDIO_STATE_MODE=ephemeral-fixture`。
+2. Studio 数据目录必须是绝对固定路径 `/run/smartgo/studio`，不得指向 `/tmp`、业务源码、完整 Config Dir 或宿主持久数据根。
+3. 仅 `smartgo-studio` 容器获得 `/run/smartgo/studio:size=256m,uid=${IDP_CONTAINER_UID},gid=${IDP_CONTAINER_GID},mode=0700` tmpfs；其他三个 App、三个 Service、Migration 和对象存储均不得继承该路径。
+4. 该状态只用于回环 `local-open` fixture：容器重建即丢失，不进入 `profileDatasets()`、Backup Generation、Restore Candidate 或生产恢复承诺。
+5. SmartGo 的持久受管数据集仍严格只有 `postgresql:smartgo` 与 `smartgo-object-store:objects`。
+
+## Apply 与验证
+
+1. 复验 `PREIMAGE-ADDENDUM-04.json` 后修改 SmartGo 组件 env 模板、JSON Schema、Doctor、受管 Compose、契约测试和操作者文档。
+2. 配置测试必须证明缺失、错误模式和漂移路径均 fail-closed。
+3. Compose 测试必须证明只有 Studio 获得状态 tmpfs，路径、容量、UID/GID/mode 精确且不出现宿主持久挂载。
+4. 等 Workspace 业务合同落地后执行 Config/Compose 定向测试、外部临时 Config Dir smoke 与完整 `npm run check`。
+
+本 Addendum 不授权修改 SmartGo 或其他仓库，也不把临时 fixture 状态升级为持久业务事实。

package/docs/features/smartgo-managed-business-profile/IMPLEMENTATION-PLAN-ADDENDUM-07.md

@@ -0,0 +1,23 @@
+# SmartGo Next standalone 缓存路径纠正 Plan Addendum 07
+
+- 状态：APPROVED / IMMUTABLE
+- 关联 Plan：`2026-08-31-smartgo-managed-business-profile-v1`
+- 批准依据：SmartGo Workspace Owner 已冻结统一 standalone packager；最终产物保留完整 `.next/standalone` 根，由顶层 wrapper 导入 `apps/<app>/server.js`。主任务明确要求只在 `idp-deploy` 同步受管缓存写边界并完成全量门禁。
+
+## 新增不可变事实
+
+1. 三个容器仍从 `/workspace/apps/<app>/.artifacts/standalone/server.js` 启动，但实际 Next 进程工作目录位于该产物内的 `apps/<app>`。
+2. Addendum 04 中缓存路径的旧事实被本 Addendum 精确替代；三个服务唯一允许写入的 Next 缓存路径为：
+   - `/workspace/apps/gotology/.artifacts/standalone/apps/gotology/.next/cache`
+   - `/workspace/apps/operations/.artifacts/standalone/apps/operations/.next/cache`
+   - `/workspace/apps/studio-poc/.artifacts/standalone/apps/studio-poc/.next/cache`
+3. UID、GID、`mode=0700`、容量、只读根文件系统、通用 `/tmp` 与 Studio 临时状态边界均保持不变。
+4. 不得挂载 `.artifacts/standalone/.next/cache` 或 `/workspace/apps/<app>/.next/cache`；API、Agent Runtime、Worker、Migration 和对象存储不得继承任一 Next 缓存目录。
+
+## Apply 与验证
+
+1. 复验 `PREIMAGE-ADDENDUM-05.json` 后，只修改 `compose/smartgo.yaml` 与 `tests/compose.test.mjs`。
+2. 契约测试必须逐服务证明新路径唯一存在、两个历史错误路径族均不存在，并继续证明 `read_only`、UID/GID/mode/容量与 Studio 独占状态目录。
+3. 执行定向 Compose 契约测试与完整 `npm run check`。
+
+本 Addendum 不授权修改 SmartGo、其他仓库或外部 Config Dir，也不改变镜像、网络、Secret、数据和备份边界。