@aipt/idp-deploy 0.1.2

package/contracts/deployment-evidence.schema.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://idp.internal/contracts/deployment-evidence.v1.schema.json",
+  "title": "IDP Deployment Evidence v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "planDigest", "releaseCandidateDigest", "runtime", "environmentRef", "repositoryState", "rollout", "resources", "checks", "observedAt", "digest"],
+  "properties": {
+    "schemaVersion": { "const": "idp.deployment-evidence/v1" },
+    "planDigest": { "$ref": "#/$defs/digest" },
+    "releaseCandidateDigest": { "$ref": "#/$defs/digest" },
+    "runtime": { "enum": ["compose", "kubernetes-gitops"] },
+    "environmentRef": { "$ref": "#/$defs/environmentRef" },
+    "repositoryState": {
+      "oneOf": [
+        { "type": "null" },
+        { "type": "object", "additionalProperties": false, "required": ["repository", "commit"], "properties": { "repository": { "type": "string", "minLength": 1 }, "commit": { "type": "string", "pattern": "^[0-9a-f]{40}$" } } }
+      ]
+    },
+    "rollout": {
+      "type": "object", "additionalProperties": false, "required": ["strategy", "status", "stableImageDigest"],
+      "properties": { "strategy": { "enum": ["rolling", "canary", "blue-green"] }, "status": { "enum": ["healthy", "degraded", "aborted"] }, "stableImageDigest": { "$ref": "#/$defs/digest" } }
+    },
+    "resources": {
+      "type": "array",
+      "items": {
+        "type": "object", "additionalProperties": false, "required": ["apiVersion", "kind", "namespace", "name", "uid", "imageDigest"],
+        "properties": { "apiVersion": { "type": "string", "minLength": 1 }, "kind": { "type": "string", "minLength": 1 }, "namespace": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "uid": { "type": "string", "minLength": 1 }, "imageDigest": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/digest" }] } }
+      }
+    },
+    "checks": {
+      "type": "array", "minItems": 1,
+      "items": { "type": "object", "additionalProperties": false, "required": ["name", "status", "evidenceDigest"], "properties": { "name": { "$ref": "#/$defs/name" }, "status": { "enum": ["passed", "failed"] }, "evidenceDigest": { "$ref": "#/$defs/digest" } } }
+    },
+    "observedAt": { "type": "string", "format": "date-time" },
+    "digest": { "$ref": "#/$defs/digest" }
+  },
+  "$defs": {
+    "digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+    "name": { "type": "string", "pattern": "^[a-z][a-z0-9-]{1,62}$" },
+    "environmentRef": { "type": "string", "pattern": "^environment:[a-z][a-z0-9-]*(?:\\.[a-z0-9-]+)*@v[1-9][0-9]*$" }
+  }
+}

package/contracts/deployment-plan.schema.json

@@ -0,0 +1,67 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://idp.company.invalid/contracts/deployment-plan-v1.schema.json",
+  "title": "IDP Kubernetes GitOps DeploymentPlan v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "operation", "application", "environment", "inputs", "repository", "renderedFiles", "createdAt", "digest"],
+  "properties": {
+    "schemaVersion": { "const": "idp.deployment-plan/v1" },
+    "operation": { "enum": ["create", "update", "remove"] },
+    "application": { "$ref": "#/$defs/name" },
+    "environment": { "$ref": "#/$defs/name" },
+    "inputs": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["component", "environmentBinding", "releaseCandidate"],
+      "properties": {
+        "component": { "$ref": "#/$defs/input" },
+        "environmentBinding": { "$ref": "#/$defs/input" },
+        "releaseCandidate": {
+          "allOf": [
+            { "$ref": "#/$defs/input" },
+            { "type": "object", "required": ["contractDigest"], "properties": { "contractDigest": { "$ref": "#/$defs/digest" } } }
+          ]
+        }
+      }
+    },
+    "repository": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["root", "expectedHead", "applicationPath", "preimageDigest"],
+      "properties": {
+        "root": { "type": "string", "pattern": "^/" },
+        "expectedHead": { "type": "string", "pattern": "^[0-9a-f]{40}$" },
+        "applicationPath": { "type": "string", "pattern": "^applications/[a-z][a-z0-9-]+$" },
+        "preimageDigest": { "$ref": "#/$defs/digest" }
+      }
+    },
+    "renderedFiles": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "digest", "content"],
+        "properties": {
+          "path": { "type": "string", "pattern": "^applications/[a-z][a-z0-9-]+/" },
+          "digest": { "$ref": "#/$defs/digest" },
+          "content": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "createdAt": { "type": "string", "format": "date-time" },
+    "digest": { "$ref": "#/$defs/digest" }
+  },
+  "$defs": {
+    "name": { "type": "string", "pattern": "^[a-z][a-z0-9-]{1,62}$" },
+    "digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+    "input": {
+      "type": "object",
+      "required": ["path", "digest"],
+      "properties": {
+        "path": { "type": "string", "pattern": "^/" },
+        "digest": { "$ref": "#/$defs/digest" }
+      }
+    }
+  }
+}

package/contracts/release-candidate.schema.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://idp.internal/contracts/release-candidate.v1.schema.json",
+  "title": "IDP Release Candidate v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "application", "version", "source", "componentContractDigest", "image", "configReleaseDigest", "acceptanceEvidenceDigests", "targetEnvironmentRef", "rolloutStrategy", "createdAt", "digest"],
+  "properties": {
+    "schemaVersion": { "const": "idp.release-candidate/v1" },
+    "application": { "$ref": "#/$defs/name" },
+    "version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?$" },
+    "source": {
+      "type": "object", "additionalProperties": false, "required": ["repository", "commit", "digest"],
+      "properties": { "repository": { "type": "string", "minLength": 1 }, "commit": { "type": "string", "pattern": "^[0-9a-f]{40}$" }, "digest": { "$ref": "#/$defs/digest" } }
+    },
+    "componentContractDigest": { "$ref": "#/$defs/digest" },
+    "image": {
+      "type": "object", "additionalProperties": false, "required": ["ref", "digest", "platforms"],
+      "properties": { "ref": { "type": "string", "pattern": "^\\S+@sha256:[0-9a-f]{64}$" }, "digest": { "$ref": "#/$defs/digest" }, "platforms": { "const": ["linux/amd64", "linux/arm64"] } }
+    },
+    "configReleaseDigest": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/digest" }] },
+    "acceptanceEvidenceDigests": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/$defs/digest" } },
+    "targetEnvironmentRef": { "$ref": "#/$defs/environmentRef" },
+    "rolloutStrategy": { "enum": ["rolling", "canary", "blue-green"] },
+    "createdAt": { "type": "string", "format": "date-time" },
+    "digest": { "$ref": "#/$defs/digest" }
+  },
+  "$defs": {
+    "digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+    "name": { "type": "string", "pattern": "^[a-z][a-z0-9-]{1,62}$" },
+    "environmentRef": { "type": "string", "pattern": "^environment:[a-z][a-z0-9-]*(?:\\.[a-z0-9-]+)*@v[1-9][0-9]*$" }
+  }
+}

package/contracts/release-defaults.schema.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://idp.internal/contracts/release-defaults.v1.schema.json",
+  "title": "IDP Release Defaults v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "releaseVersion", "ociRepositoryRoot", "platforms", "thirdPartyImages", "buildImages"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "releaseVersion": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+(?:-[a-z0-9][a-z0-9.-]*)?$" },
+    "ociRepositoryRoot": { "type": "string", "pattern": "^[a-z0-9]+(?:[._-][a-z0-9]+)*(?::[1-9][0-9]{0,4})?(?:/[a-z0-9]+(?:[._-][a-z0-9]+)*)+$" },
+    "platforms": {
+      "const": ["linux/amd64", "linux/arm64"]
+    },
+    "thirdPartyImages": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["IDP_POSTGRES_IMAGE", "IDP_CADDY_IMAGE", "IDP_REGISTRY_IMAGE"],
+      "properties": {
+        "IDP_POSTGRES_IMAGE": { "$ref": "#/$defs/pinnedImage" },
+        "IDP_CADDY_IMAGE": { "$ref": "#/$defs/pinnedImage" },
+        "IDP_REGISTRY_IMAGE": { "$ref": "#/$defs/pinnedImage" }
+      }
+    },
+    "buildImages": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["tech", "flow", "portal"],
+      "properties": {
+        "tech": { "$ref": "#/$defs/buildImage" },
+        "flow": { "$ref": "#/$defs/buildImage" },
+        "portal": { "$ref": "#/$defs/buildImage" }
+      }
+    }
+  },
+  "$defs": {
+    "pinnedImage": { "type": "string", "pattern": "^\\S+@sha256:[0-9a-f]{64}$" },
+    "buildImage": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["environmentKey", "sourceDirectory", "context", "dockerfile", "repositorySuffix", "buildArgs", "prebuildContract"],
+      "properties": {
+        "environmentKey": { "enum": ["IDP_TECH_IMAGE", "IDP_FLOW_IMAGE", "IDP_PORTAL_IMAGE"] },
+        "sourceDirectory": { "enum": ["tech", "flow", "portal"] },
+        "context": { "const": "." },
+        "dockerfile": { "type": "string", "pattern": "^[A-Za-z0-9._/-]+$" },
+        "repositorySuffix": { "enum": ["", "/flow", "/portal"] },
+        "buildArgs": {
+          "type": "object",
+          "additionalProperties": { "type": "string", "minLength": 1 }
+        },
+        "prebuildContract": { "enum": ["none", "portal-backstage-v1"] }
+      }
+    }
+  }
+}

package/contracts/restore-candidate.schema.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://idp.internal/contracts/restore-candidate.v1.schema.json",
+  "title": "IDP Restore Candidate v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "candidateId", "generationId", "profile", "status", "preimage", "creationEvidenceDigest", "configDigest", "dataDigest", "results", "createdAt", "digest"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "candidateId": { "type": "string", "minLength": 1 },
+    "generationId": { "type": "string", "pattern": "^[0-9TZ-]+-[0-9a-f]{12}$" },
+    "profile": { "enum": ["tech-only", "foundation", "core", "portal", "flow", "registry", "full"] },
+    "status": { "const": "ready-for-cutover" },
+    "preimage": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["targetExisted", "productionDataUntouched"],
+      "properties": {
+        "targetExisted": { "const": false },
+        "productionDataUntouched": { "const": true }
+      }
+    },
+    "creationEvidenceDigest": { "$ref": "#/$defs/digest" },
+    "configDigest": { "$ref": "#/$defs/digest" },
+    "dataDigest": { "$ref": "#/$defs/digest" },
+    "results": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "oneOf": [
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["dataset", "database", "tableCount", "ownedCount", "canConnect", "status"],
+            "properties": {
+              "dataset": { "enum": ["postgresql:tech", "postgresql:backstage"] },
+              "database": { "enum": ["tech", "backstage"] },
+              "tableCount": { "type": "integer", "minimum": 1 },
+              "ownedCount": { "type": "integer", "minimum": 1 },
+              "canConnect": { "const": true },
+              "status": { "const": "restored" }
+            }
+          },
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["dataset", "entries", "status"],
+            "properties": {
+              "dataset": { "const": "registry:packages" },
+              "entries": { "type": "integer", "minimum": 1 },
+              "status": { "const": "restored" }
+            }
+          }
+        ]
+      }
+    },
+    "createdAt": { "type": "string", "format": "date-time" },
+    "digest": { "$ref": "#/$defs/digest" }
+  },
+  "$defs": {
+    "digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }
+  }
+}

package/contracts/smartgo-component-config.schema.json

@@ -0,0 +1,79 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://idp.example.internal/contracts/smartgo-component-config.schema.json",
+  "title": "SmartGo idp-managed component configuration",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "NODE_ENV",
+    "SMARTGO_DEPLOYMENT_MODE",
+    "SMARTGO_AUTH_MODE",
+    "SMARTGO_BIND_HOST",
+    "SMARTGO_STUDIO_STATE_MODE",
+    "SMARTGO_STUDIO_DATA_DIRECTORY",
+    "MEDIA_ASSET_REPOSITORY",
+    "GOTOLOGY_PUBLIC_URL",
+    "OPERATIONS_PUBLIC_URL",
+    "STUDIO_PUBLIC_URL",
+    "SMARTGO_ARTIFACT_STORE_PROVIDER",
+    "SMARTGO_MINIO_BUCKET",
+    "SMARTGO_MINIO_INTERNAL_ENDPOINT",
+    "SMARTGO_MINIO_PUBLIC_ENDPOINT",
+    "SIGNED_OBJECT_URL_TTL_SECONDS",
+    "DATABASE_URL_FILE",
+    "DIRECT_DATABASE_URL_FILE",
+    "SMARTGO_OPERATOR_TOKEN_FILE",
+    "PLATFORM_IDENTITY_SERVICE_TOKEN_FILE",
+    "PLATFORM_IDENTITY_ACTIVATION_TOKEN_FILE",
+    "PLATFORM_IDENTITY_CLIENT_SECRET_FILE",
+    "ARTIFACT_RENDERER_CALLBACK_TOKEN_FILE",
+    "ALIYUN_OSS_ACCESS_KEY_ID_FILE",
+    "ALIYUN_OSS_ACCESS_KEY_SECRET_FILE",
+    "ARTIFACT_DELIVERY_S3_ACCESS_KEY_ID_FILE",
+    "ARTIFACT_DELIVERY_S3_ACCESS_KEY_SECRET_FILE",
+    "WORKER_ARTIFACT_S3_ACCESS_KEY_ID_FILE",
+    "WORKER_ARTIFACT_S3_ACCESS_KEY_SECRET_FILE",
+    "SMARTGO_MINIO_ROOT_USER_FILE",
+    "SMARTGO_MINIO_ROOT_PASSWORD_FILE",
+    "SMARTGO_NPMRC_FILE"
+  ],
+  "properties": {
+    "NODE_ENV": { "const": "development" },
+    "SMARTGO_DEPLOYMENT_MODE": { "const": "idp-managed" },
+    "SMARTGO_AUTH_MODE": { "const": "local-open" },
+    "SMARTGO_BIND_HOST": { "enum": ["127.0.0.1", "::1"] },
+    "SMARTGO_STUDIO_STATE_MODE": { "const": "ephemeral-fixture" },
+    "SMARTGO_STUDIO_DATA_DIRECTORY": { "const": "/run/smartgo/studio" },
+    "MEDIA_ASSET_REPOSITORY": { "const": "minio" },
+    "GOTOLOGY_PUBLIC_URL": { "type": "string", "format": "uri", "pattern": "^https?://" },
+    "OPERATIONS_PUBLIC_URL": { "type": "string", "format": "uri", "pattern": "^https?://" },
+    "STUDIO_PUBLIC_URL": { "type": "string", "format": "uri", "pattern": "^https?://" },
+    "SMARTGO_ARTIFACT_STORE_PROVIDER": { "const": "s3" },
+    "SMARTGO_MINIO_BUCKET": { "const": "smartgo-artifacts" },
+    "SMARTGO_MINIO_INTERNAL_ENDPOINT": { "type": "string", "format": "uri", "pattern": "^http://smartgo-object-store:9000/?$" },
+    "SMARTGO_MINIO_PUBLIC_ENDPOINT": { "type": "string", "format": "uri", "pattern": "^https?://" },
+    "SIGNED_OBJECT_URL_TTL_SECONDS": { "type": "string", "pattern": "^[1-9][0-9]{0,4}$" },
+    "DATABASE_URL_FILE": { "$ref": "#/$defs/secretFile" },
+    "DIRECT_DATABASE_URL_FILE": { "$ref": "#/$defs/secretFile" },
+    "SMARTGO_OPERATOR_TOKEN_FILE": { "$ref": "#/$defs/secretFile" },
+    "PLATFORM_IDENTITY_SERVICE_TOKEN_FILE": { "$ref": "#/$defs/secretFile" },
+    "PLATFORM_IDENTITY_ACTIVATION_TOKEN_FILE": { "$ref": "#/$defs/secretFile" },
+    "PLATFORM_IDENTITY_CLIENT_SECRET_FILE": { "$ref": "#/$defs/secretFile" },
+    "ARTIFACT_RENDERER_CALLBACK_TOKEN_FILE": { "$ref": "#/$defs/secretFile" },
+    "ALIYUN_OSS_ACCESS_KEY_ID_FILE": { "$ref": "#/$defs/secretFile" },
+    "ALIYUN_OSS_ACCESS_KEY_SECRET_FILE": { "$ref": "#/$defs/secretFile" },
+    "ARTIFACT_DELIVERY_S3_ACCESS_KEY_ID_FILE": { "$ref": "#/$defs/secretFile" },
+    "ARTIFACT_DELIVERY_S3_ACCESS_KEY_SECRET_FILE": { "$ref": "#/$defs/secretFile" },
+    "WORKER_ARTIFACT_S3_ACCESS_KEY_ID_FILE": { "$ref": "#/$defs/secretFile" },
+    "WORKER_ARTIFACT_S3_ACCESS_KEY_SECRET_FILE": { "$ref": "#/$defs/secretFile" },
+    "SMARTGO_MINIO_ROOT_USER_FILE": { "$ref": "#/$defs/secretFile" },
+    "SMARTGO_MINIO_ROOT_PASSWORD_FILE": { "$ref": "#/$defs/secretFile" },
+    "SMARTGO_NPMRC_FILE": { "$ref": "#/$defs/secretFile" }
+  },
+  "$defs": {
+    "secretFile": {
+      "type": "string",
+      "pattern": "^secrets/[A-Za-z0-9][A-Za-z0-9._/-]{0,199}$"
+    }
+  }
+}

package/contracts/tech-backup-boundary.schema.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://idp.internal/contracts/tech-backup-boundary.v1.schema.json",
+  "title": "Tech Backup Boundary v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "generatedAt", "digest", "database", "knowledge", "objectStorage", "restoreVerification"],
+  "properties": {
+    "schemaVersion": { "const": "tech.backup-boundary.v1" },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "digest": { "$ref": "#/$defs/digest" },
+    "database": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["engine", "requiredFormat", "migrations", "counts"],
+      "properties": {
+        "engine": { "const": "postgresql" },
+        "requiredFormat": { "const": "pg_dump-custom" },
+        "migrations": {
+          "type": "array", "minItems": 1, "maxItems": 10000,
+          "items": {
+            "type": "object", "additionalProperties": false, "required": ["version", "checksum"],
+            "properties": { "version": { "type": "string", "minLength": 1, "maxLength": 256 }, "checksum": { "$ref": "#/$defs/digest" } }
+          }
+        },
+        "counts": {
+          "type": "object", "additionalProperties": false, "required": ["spaces", "sources", "references", "snapshots"],
+          "properties": {
+            "spaces": { "type": "integer", "minimum": 0 }, "sources": { "type": "integer", "minimum": 0 },
+            "references": { "type": "integer", "minimum": 0 }, "snapshots": { "type": "integer", "minimum": 0 }
+          }
+        }
+      }
+    },
+    "knowledge": {
+      "type": "object", "additionalProperties": false, "required": ["activeIndexRevision", "sourceRevisions"],
+      "properties": {
+        "activeIndexRevision": { "type": "string", "minLength": 1, "maxLength": 256 },
+        "sourceRevisions": {
+          "type": "array", "maxItems": 10000,
+          "items": {
+            "type": "object", "additionalProperties": false,
+            "required": ["sourceId", "identity", "repositoryUrl", "commit", "treeDigest"],
+            "properties": {
+              "sourceId": { "type": "string", "minLength": 1, "maxLength": 256 },
+              "identity": { "type": "string", "minLength": 1, "maxLength": 256 },
+              "repositoryUrl": { "type": "string", "minLength": 1, "maxLength": 4096 },
+              "commit": { "type": ["string", "null"] }, "treeDigest": { "oneOf": [{ "$ref": "#/$defs/digest" }, { "type": "null" }] }
+            }
+          }
+        }
+      }
+    },
+    "objectStorage": {
+      "type": "object", "additionalProperties": false, "required": ["mode", "ownedObjects"],
+      "properties": { "mode": { "const": "none" }, "ownedObjects": { "const": false } }
+    },
+    "restoreVerification": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1, "maxLength": 512 } }
+  },
+  "$defs": { "digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" } }
+}

package/contracts/tech-source-credentials.schema.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://idp.internal/contracts/tech-source-credentials.v1.schema.json",
+  "title": "Tech Source Credentials Manifest v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "files"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "files": {
+      "type": "array",
+      "maxItems": 200,
+      "uniqueItems": true,
+      "items": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$" }
+    }
+  }
+}

package/deploy.sh

@@ -0,0 +1,5 @@
+#!/bin/sh
+set -eu
+
+SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+exec node "$SCRIPT_DIR/bin/idpctl.mjs" release deploy "$@"

package/docs/restore-runbook.md

@@ -0,0 +1,56 @@
+# IDP 灾难恢复与回切 Runbook
+
+本 Runbook 只操作 `idp-deploy` 拥有的 PostgreSQL 与私有 npm Registry。Tech 当前 P0 的完整可恢复边界还包括 Git Knowledge Release pins 和外部 Secret Manager，必须分别按其事实所有者恢复；不得拿数据库备份冒充完整知识资产备份。Tech 尚未启用对象正文/附件存储，未来启用 OSS/S3 前必须先增加版本化 Binding、对象清单与恢复适配器，本 Runbook 不会伪造该能力。
+
+## 进入条件
+
+1. `IDP_CONFIG_DIR` 可用，Secret 已从加密备份或 Secret Manager 恢复，权限仍为 `0700/0600`。
+2. `.env` 与 `images.lock.json` 已回到目标代次兼容版本，`doctor <profile> --require-configured` 通过；`restore apply` 后不得再修改该 Profile 配置，否则候选会因配置摘要漂移被拒绝，必须重新生成。
+3. 备份 generation 已复制到配置声明的 `IDP_BACKUP_DIR/generations`，运行回执摘要链可用。
+4. 操作窗口内不得并行执行 `images lock`、Compose、备份或恢复命令；`idpctl` 的实例锁会二次拒绝并发。
+
+## 验证备份并生成恢复候选
+
+```bash
+export IDP_CONFIG_DIR=/absolute/outside-git/idp-config
+node bin/idpctl.mjs backup verify <generation-id>
+node bin/idpctl.mjs restore test <generation-id>
+node bin/idpctl.mjs restore apply <generation-id>
+node bin/idpctl.mjs restore verify <candidate-id>
+```
+
+`restore apply` 只写全新的候选目录。任何摘要不一致、未声明文件、空数据集、不安全 tar 路径、数据库 Owner/权限错误或镜像证据漂移都会停止；失败候选移动到 `IDP_RESTORE_DIR/failed`，生产数据保持不变。包含 Tech 的 generation 还必须同时带有经过摘要绑定的 `tech-backup-boundary.json`；`restore test` 会由 Tech 镜像连接隔离恢复库，逐项重算 migration checksum、业务计数、active index 与 Source commit/treeDigest，事实摘要不相等即失败。
+
+`portal` 与 `tech-only` 生成的单数据库候选不会物理替换共享 PostgreSQL 集群。它们在 `promote` 时使用逻辑数据库恢复、验收和重命名切换，另一个数据库保持不变。需要整体物理切换 PostgreSQL 时必须选择同时包含 `tech` 与 `backstage` 的 `core`/`full` generation；`registry` generation 可以独立切换。
+
+活动 Profile 为 `foundation` 时，日常应分别执行 `backup create tech-only` 与 `backup create registry`，得到两个可实际切换的故障域。Tech 单库候选会借用当前活动 `foundation` 的 Compose 上下文停启 Tech/Edge，不会误停 Registry。`foundation` 联合 generation 只承诺验证与隔离恢复演练，不承诺跨数据库/目录的伪原子生产切换。
+
+## 生产切换
+
+在变更窗口中记录候选 ID，然后运行：
+
+```bash
+node bin/idpctl.mjs restore promote <candidate-id> --confirm <candidate-id>
+node bin/idpctl.mjs verify <profile>
+```
+
+`core/full/registry` 的物理顺序固定为：验证候选清单、创建回执与物理数据摘要及当前配置摘要 → 保存不可变 Plan → Compose down → 同盘复制完整生产数据并仅覆盖候选声明的数据目录 → 再验暂存摘要 → 原子重命名生产数据为 Preimage → 原子安装暂存副本 → 先启动 PostgreSQL + Tech 并复核 Tech 备份边界 → 再启动其余服务并等待健康。准备暂存副本失败会先重启原服务；安装后任何健康或边界失败都会停掉失败版本、恢复原生产目录并重新启动。
+
+`portal/tech-only` 的逻辑顺序固定为：把已验证 Dump 流式恢复到新数据库 → 验证非空表、Owner 和应用角色连接权限 → Tech 候选先复核备份边界 → 短暂停止对应应用及其本机消费者/Edge → 终止目标库连接 → 把原库重命名为 `idp_preimage_*` → 把新库重命名为正式库名 → Tech 先行启动并再次复核边界 → 恢复其他服务并等待健康。健康或边界失败时新库改名为 `idp_failed_*`，Preimage 自动改回正式库名并重启原服务。若回滚本身失败，命令输出 `IDP_LOGICAL_RESTORE_ROLLBACK_FAILED` 和准确数据库 Preimage，禁止继续手工覆盖。
+
+## 人工验收
+
+1. `verify` 中运行服务集合必须与活动 Profile 严格相等，且全部为 `running/healthy`；多余 Orphan 同样失败。
+2. Edge、Flow、Portal、Tech `/live`、Tech `/ready`（当前 Profile 包含时）和 Registry 端到端探针全部通过。
+3. 用只读开发者流程安装一个已知 npm 包；用发布账号完成一次临时包发布与撤销。
+4. 对 Portal/Flow 做一条只读查询和一条可回滚写入，确认应用角色权限。
+5. 核对恢复回执的 `candidateDigest`、`planDigest`、`preimage` 和 `status=promoted-and-healthy`。
+6. Tech 回执必须带有与 generation 相同的 `techBoundaryDigest`。`gitReleaseRefetch=external-evidence-required` 不是成功证明：还需在企业 Git 网络内按清单逐个重取 commit 并重算 treeDigest，证据归档后才算完整知识恢复演练。
+
+## 清理与保留
+
+- 成功切换后至少跨过一个完整备份周期并再次执行恢复演练，才能清理生产 Preimage。
+- 单数据库逻辑切换的 `idp_preimage_*` 与 `idp_failed_*` 也属于恢复证据，不得在同一次变更中自动删除。
+- 清理是独立的破坏性变更，本工具不会自动删除 Preimage、generation 或失败候选。
+- generation 必须继续复制到与数据盘故障域不同的位置；只有本机备份不满足灾难恢复要求。
+- 初始建议目标：每日备份（RPO 24 小时），演练恢复在 2 小时内完成（RTO 2 小时）；有更严格业务要求时应缩短周期并引入 PostgreSQL PITR。

package/governance/asset-lifecycle.v1.json

@@ -0,0 +1,79 @@
+{
+  "schemaVersion": "idp-deploy.asset-lifecycle/v1",
+  "planId": "idp-deploy.bench-deployment-ownership-reception@1",
+  "version": 1,
+  "approvedAt": "2026-08-31",
+  "immutable": true,
+  "archiveRoot": "archive",
+  "activeComponents": ["postgresql", "registry", "tech", "flow", "portal", "edge"],
+  "receipts": [
+    {
+      "sourceProject": "bench",
+      "sourceAsset": "packages/ops",
+      "sourceEvidence": "sha256:b38d9c08a03a58d60aba0b2350efa478018e3c4852afb2c331318ec1d95f21af",
+      "decision": "accepted",
+      "targetCapability": "controlled-deployment-kernel",
+      "targetPaths": ["src/operations.mjs", "contracts/active-profile.schema.json", "contracts/backup-generation.schema.json", "contracts/restore-candidate.schema.json"],
+      "evidence": ["tests/operations.test.mjs", "tests/integration/runtime.test.mjs"],
+      "remainingGates": ["Bench 消费者全部停止导入 @acme/ops", "Bench 生成 packages/ops 的 ARCHIVE.json"]
+    },
+    {
+      "sourceProject": "bench",
+      "sourceAsset": "scripts/ops-agent.mjs",
+      "sourceEvidence": "sha256:b1d50c927cdfb41535dbcfe67e541ee8902ae284cbba4584fd57e788bdfc6920",
+      "decision": "replaced",
+      "targetCapability": "single-kernel-cli-ai-operations",
+      "targetPaths": ["bin/idpctl.mjs", "src/cli.mjs", "src/operations.mjs"],
+      "evidence": ["tests/cli.test.mjs", "tests/operations.test.mjs"],
+      "remainingGates": ["Portal 保持只读且不调用旧 Unix Socket", "Bench 生成 ops-agent ARCHIVE.json"]
+    },
+    {
+      "sourceProject": "bench",
+      "sourceAsset": "docker-compose.yml",
+      "sourceEvidence": "sha256:a2f2b5b16c78b3c968b08d8cfe9f02caf2de373893a0551efd89de6d010b5286",
+      "decision": "selectively-received",
+      "targetCapability": "independent-compose-fragments-and-minimal-profiles",
+      "targetPaths": ["src/profiles.mjs", "src/compose.mjs", "compose/postgresql.yaml", "compose/registry.yaml", "compose/tech.yaml", "compose/flow.yaml", "compose/portal.yaml", "compose/edge.yaml"],
+      "evidence": ["tests/compose.test.mjs", "tests/integration/runtime.test.mjs"],
+      "remainingGates": ["Bench 确认没有消费者调用旧 local:up", "未接收中间件逐项完成 Binding 与恢复评审", "Bench 生成 legacy Compose ARCHIVE.json"]
+    },
+    {
+      "sourceProject": "bench",
+      "sourceAsset": "local",
+      "sourceEvidence": "sha256:b38d9c08a03a58d60aba0b2350efa478018e3c4852afb2c331318ec1d95f21af",
+      "decision": "selectively-received",
+      "targetCapability": "verdaccio-and-postgresql-bootstrap-only",
+      "targetPaths": ["compose/registry.yaml", "compose/postgresql.yaml", "scripts/postgresql/010-create-databases.sh", "src/render.mjs"],
+      "evidence": ["tests/config.test.mjs", "tests/compose.test.mjs", "tests/render.test.mjs"],
+      "remainingGates": ["ClickHouse、Kafka/RocketMQ、Nacos、可观测栈分别出现真实 Binding", "每个新增服务具备独立 Profile、健康检查和备份恢复边界", "Bench 生成 local runtime ARCHIVE.json"]
+    },
+    {
+      "sourceProject": "bench",
+      "sourceAsset": "gitops",
+      "sourceEvidence": "sha256:b38d9c08a03a58d60aba0b2350efa478018e3c4852afb2c331318ec1d95f21af",
+      "decision": "deferred",
+      "targetCapability": "future-approved-gitops-environment",
+      "targetPaths": [],
+      "evidence": ["docs/features/bench-deployment-ownership-reception/DESIGN.md"],
+      "remainingGates": ["批准 Kubernetes 与 Argo CD 目标环境", "通过 server-side dry-run、回滚与 Secret 投影验证", "证明当前 Mac 单机部署不依赖该路径"]
+    },
+    {
+      "sourceProject": "bench",
+      "sourceAsset": "infra/terraform",
+      "sourceEvidence": "sha256:b38d9c08a03a58d60aba0b2350efa478018e3c4852afb2c331318ec1d95f21af",
+      "decision": "deferred",
+      "targetCapability": "future-approved-iac-environment",
+      "targetPaths": [],
+      "evidence": ["docs/features/bench-deployment-ownership-reception/DESIGN.md"],
+      "remainingGates": ["批准云 Provider、账户与状态后端", "完成 plan/apply/destroy 与外部资源 Preimage", "定义 Secret、成本和灾备合同"]
+    }
+  ],
+  "policy": {
+    "runtimeCrossRepositorySourceReads": false,
+    "archiveIncludedInRuntime": false,
+    "secretsOnlyFromExternalConfigDir": true,
+    "unapprovedRemoteResources": false,
+    "portalWriteProxy": false
+  },
+  "digest": "sha256:589462d761b7cfe3cacfbbf327fdd76e01aed01be82104dd82bcd62479a2b72e"
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@aipt/idp-deploy",
+  "version": "0.1.2",
+  "description": "IDP 私有化部署、外部配置、备份恢复与交付编排 CLI。",
+  "type": "module",
+  "bin": {
+    "idpctl": "./bin/idpctl.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "compose",
+    "contracts",
+    "release",
+    "governance",
+    "docs/restore-runbook.md",
+    "README.md",
+    "deploy.sh"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "yaml": "2.9.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "idpctl": "node bin/idpctl.mjs",
+    "deploy": "./deploy.sh",
+    "test": "node --test tests/*.test.mjs",
+    "test:integration": "node --test --test-timeout=240000 tests/integration/*.test.mjs",
+    "lifecycle:check": "node bin/idpctl.mjs lifecycle check",
+    "smoke:local": "node scripts/smoke-local.mjs",
+    "smoke:smartgo": "node scripts/smoke-smartgo.mjs",
+    "smoke:smartgo:object-store": "node scripts/smoke-smartgo.mjs --object-store-runtime",
+    "check": "node scripts/check-syntax.mjs && node bin/idpctl.mjs lifecycle check && node --test tests/*.test.mjs",
+    "example": "node examples/private-mac-m4/run.mjs",
+    "example:no-cluster": "node examples/no-cluster-delivery/run.mjs"
+  }
+}