@starci/skills 1.1.0

package/operators/release-deploy/operator.md

@@ -0,0 +1,183 @@
+# release.deploy
+
+## Job
+
+Deploy one immutable release to one declared target under its declared authorization and prove the
+steady state it reached, taking the recovery or rollback branch inside the same pass rather than
+assuming the rollout succeeded.
+
+## Recovery and rollback are branches of this job
+
+A rollout that does not stabilize is still this operator's problem. The run ends on one of three
+terminals and never in the middle: the release is deployed, the previous release is restored, or the
+work is blocked with an exact reason. A restored release is its own terminal outcome; it must never
+be read as successful delivery of the release it rejected.
+
+## The release is immutable and exact
+
+A release is identified by its `sha256:` digest, not by a tag, a branch, or a build number. The
+artifact is never rebuilt, retagged, or substituted inside this pass; if the digest cannot be
+resolved the run blocks rather than building a replacement and calling it the same release. The
+manifest must have been validated against exactly this release, because a manifest pinned to another
+release is how an unreviewed image reaches a reviewed target.
+
+## Authorization is declared, never implied
+
+Deployment requires its own declared grant covering this project, this environment, this target and
+the `deploy` action, still valid at the moment the target was observed. No ordinary task, no
+precedent from a sibling project and no urgency implies it, and an unauthorized deployment does not
+become authorized by being useful. Destructive loss, a credential rotation, or a new host, domain,
+tenant or project leaves this operator's authority entirely and returns `APPROVAL_REQUIRED`.
+
+## Credentials are names, never values
+
+Handles are resolved through existing custody at the moment they are needed. A resolved value never
+enters the plan, the manifest, the receipt, a log line, a command argument, or a message. The receipt
+records which handles were resolved and nothing more, and no field in the contract can hold a value
+even if someone tried: a token written where a `secret-ref://` handle belongs is rejected as
+malformed rather than quietly carried into an argument list.
+
+## Every effect is a compare-and-set
+
+A step either mutates a boundary or it does not. The mutating steps are `host-prepare`,
+`artifact-publish`, `migrate`, `domain-reconcile`, `rollout`, `recover` and `rollback`, and each
+records the observed revision of its own boundary before and after. A desired state that already
+matches is a proved idempotent no-op and is recorded as one; claiming an application without moving
+a revision is refused, and a reading step that reports a revision has invented a fact about a
+boundary it never touched. The execution root is ignored and rebuildable.
+
+## Monitoring distinguishes progressing from failing
+
+On this project a push to `main` triggers the workflow and boot takes roughly eight to nine minutes,
+so `progressing` is the expected condition for most of the window and is never treated as a failure,
+and a monitoring deadline shorter than the window it must contain produces a guaranteed false
+failure. One transient probe never becomes recovery: a failing condition has to persist across at
+least two observations. A release that is neither this release nor the one it replaces stops the run
+as `CONCURRENT_DRIFT` and forces a replan; it is never recovered or rolled back as though it
+belonged here. Recovery repeats only approved reversible actions, numbers its attempts contiguously
+from one, preserves the same release identity, and cannot end in a deployment once exhausted.
+Rollback is valid only when the exact safe release still exists, the current data and schema state
+remain compatible with it, and the revision actually moved.
+
+## Steady state is proved, not assumed
+
+A rollout that returned without an error is not a deployment. Steady means the immutable digest is
+active, every declared target is available, no superseded target remains active unless the strategy
+permits it, the window elapsed in full, and every declared probe passed across the whole of it. That
+is what turns three silent failures into detectable ones: the workflow finished while the old digest
+is still serving traffic; one of two targets never came back and the other absorbed the load; the
+readiness probe passed once, at the one moment it happened to be asked. At least one declared probe
+is public, because a run observing only container health proves nothing a user could see; here the
+GraphQL typename probe returning `200` is the readiness signal.
+
+## The two fallbacks are ordered, and the rest terminate
+
+A failed rollout is not the end of the run, it is the entry to the first fallback: `ROLLOUT_FAILED`
+takes the recovery branch, which repeats only approved reversible actions against the same release
+identity. When those run out, `RECOVERY_EXHAUSTED` takes the second fallback: rollback to
+`rollbackIdentity` by its exact digest. Both are recorded under `## Fallbacks taken`, because a
+branch taken silently is a branch nobody can audit. After that there is nothing left to try, so
+`ROLLBACK_IDENTITY_MISSING`, `STEADY_STATE_UNPROVEN` and `CONCURRENT_DRIFT` terminate: a rollback
+without its safe release, a window that never closed, and a foreign release that appeared mid-run are
+each a state this operator must not act further on.
+
+## Deadlines and probes have defaults, approval does not
+
+`steadyDeadline` defaults to 600 seconds because that is the boot time this project actually shows,
+and `probes` default to the set the validated manifest declares, so a person who names neither is
+still measured against something real. `approval` has no default at all: changing what production
+serves is always something a person said yes to.
+
+## Boundary
+
+Context is read-only apart from the declared mutations. The operator applies only the declared host,
+migration, domain and rollout mutations against the frozen release identity, restores the exact
+declared rollback release when that branch is taken, and writes only `response/` of its own branch:
+`data/probes.json`, `response.md` and `response.json`. It does not log, persist, echo, or return a
+resolved credential value; does not deploy a release the declared authorization does not cover; does
+not rebuild, retag, or otherwise alter the immutable artifact identified by the frozen digest; does
+not edit the intent or revalidate the manifest into something else; does not recover or roll back a
+release that appeared during execution and does not belong to this run; does not report a rolled-back
+run as successful delivery of the rejected release; and does not declare steady state from a single
+probe observation or from an assumed rollout.
+
+## Context
+
+| Alias | Bind | Required |
+| --- | --- | --- |
+| `@remote/ghcr/<image>` | the immutable image by digest; a tag is never a binding | yes |
+| `@workspaces/device-state` | credential handles by name and their custody; values never appear | yes |
+| `@remote/github-actions/<runId>` | CI evidence of the build and the rollout, read only | no |
+
+## Inputs
+
+| Kind | From | Required |
+| --- | --- | --- |
+| `quality-verification` | `quality.verify`; verification precedes an immutable build, and it is the authorization this run stands on | yes |
+
+## Requirements
+
+| Field | Type | Default | Ask |
+| --- | --- | --- | --- |
+| `release` | id | — | The immutable release identity being deployed, with the `sha256:` digest that identifies it |
+| `target` | id | — | The one target this deployment may change, and the environment it sits in |
+| `approval` | id | — | The declared deploy grant covering this project, environment and target; changing what production serves always needs a person |
+| `probes` | list of `{probeId, kind, endpointRef, expectStatus}` | the probes the validated manifest declares | What steady state is measured by; at least one probe is public |
+| `steadyDeadline` | number | 600 | The bounded monitoring deadline in seconds, measured against the boot time this project shows |
+| `rollbackIdentity` | `{releaseId, artifactRef, digest, dataCompatible}` | — | The exact safe release the rollback fallback restores, by digest |
+| `resume` | token | null | The blocked branch's token when re-entering after a stop |
+
+## Steps
+
+| # | Step | Params | Reads | Writes | Stops with |
+| --- | --- | --- | --- | --- | --- |
+| 1 | Validate the gate, the authorization the input carries, and the resume | `resume` | `request/request.json`, input `quality-verification` as the authorization this run stands on | — | `INVALID_INPUT`, `AUTHORIZATION_MISSING`, `NO_PROGRESS` |
+| 2 | Bind the release and compile the plan | `release`, `target`, `approval` | @remote/ghcr/<image> at the frozen digest, @remote/github-actions/<runId> for the observed state, @tools/git, @tools/ci | — | `MANIFEST_INVALID`, `APPROVAL_REQUIRED` |
+| 3 | Initialize the execution root and resolve the credentials by name | — | @workspaces/device-state for the declared handles and their custody, @tools/secrets | — | `CREDENTIAL_UNAVAILABLE` |
+| 4 | Prepare the host, publish the artifact by digest, migrate and reconcile the domain | — | @remote/ghcr/<image> for the artifact by digest, @remote/github-actions/<runId> for each boundary's revision before and after | @tools/shell | `HOST_UNAVAILABLE`, `ARTIFACT_MISSING`, `MIGRATION_BLOCKED`, `DOMAIN_UNRECONCILED` |
+| 5 | Roll out | — | @remote/ghcr/<image> for the target revision before and after | @tools/container | `ROLLOUT_FAILED` |
+| 6 | Monitor within the deadline, with backoff | `steadyDeadline`, `probes` | @remote/github-actions/<runId> for the probe observations across the window, @tools/http | `response/data/probes.json` | — |
+| 7 | Detect concurrent drift before acting | — | `response/data/probes.json`, @remote/ghcr/<image> for the active release by digest | — | `CONCURRENT_DRIFT` |
+| 8 | Take the recovery branch when the failure persists | — | `response/data/probes.json`, @remote/ghcr/<image> at the same release identity | @tools/container | `RECOVERY_EXHAUSTED` |
+| 9 | Take the rollback branch when recovery cannot hold | `rollbackIdentity` | @remote/ghcr/<image> at the exact safe digest | @tools/container | `ROLLBACK_IDENTITY_MISSING` |
+| 10 | Prove the steady state, write the receipt and emit | — | everything above | `response/response.md`, `response/response.json` | `STEADY_STATE_UNPROVEN` |
+
+Steps 8 and 9 are the two fallbacks in order, not a sequence every run walks: a run enters step 8
+only under `ROLLOUT_FAILED` and step 9 only under `RECOVERY_EXHAUSTED`, and a run that took neither
+records the branch as `none`. A resume begins again at validation, reuses only unchanged fingerprinted
+observations, and keeps the same release identity, because a different release is a different
+deployment; a resume that adds no authorization, manifest, credential or observation change is
+`NO_PROGRESS`.
+
+## Outputs
+
+| Kind | File | Type | Required |
+| --- | --- | --- | --- |
+| `release-deployment` | `response/response.md` | md | yes |
+| `probes` | `response/data/probes.json` | data | yes |
+
+## Stops
+
+| Code | Disposition |
+| --- | --- |
+| `INVALID_INPUT` | terminate |
+| `NO_PROGRESS` | terminate |
+| `AUTHORIZATION_MISSING` | terminate |
+| `MANIFEST_INVALID` | terminate |
+| `APPROVAL_REQUIRED` | terminate |
+| `CREDENTIAL_UNAVAILABLE` | terminate |
+| `HOST_UNAVAILABLE` | terminate |
+| `ARTIFACT_MISSING` | terminate |
+| `MIGRATION_BLOCKED` | terminate |
+| `DOMAIN_UNRECONCILED` | terminate |
+| `ROLLOUT_FAILED` | fallback |
+| `RECOVERY_EXHAUSTED` | fallback |
+| `CONCURRENT_DRIFT` | terminate |
+| `ROLLBACK_IDENTITY_MISSING` | terminate |
+| `STEADY_STATE_UNPROVEN` | terminate |
+
+## Next
+
+| When | Operator |
+| --- | --- |
+| the host, the artifact registry, the credential custody or the safe release needs a shared runtime change | `platform.operate` |

package/operators/release-deploy/operator.vi.md

@@ -0,0 +1,181 @@
+# release.deploy
+
+## Việc
+
+Deploy một release bất biến lên một target đã khai, dưới đúng thẩm quyền đã khai, rồi chứng minh
+trạng thái ổn định mà nó đạt tới, đi nhánh recovery hay rollback ngay trong cùng lượt chạy thay vì
+giả định rollout đã thành công.
+
+## Recovery và rollback là nhánh của chính việc này
+
+Một rollout không ổn định lại vẫn là vấn đề của operator này. Lượt chạy kết thúc ở đúng một trong ba
+điểm cuối và không bao giờ dừng giữa chừng: release được deploy, release trước được khôi phục, hoặc
+công việc bị chặn với một lý do chính xác. Một release được khôi phục là điểm cuối của riêng nó; nó
+không bao giờ được đọc thành việc giao thành công cái release mà nó vừa từ chối.
+
+## Release là bất biến và chính xác
+
+Một release được nhận diện bằng digest `sha256:` của nó, không phải bằng tag, nhánh hay số build.
+Artifact không bao giờ được build lại, gắn tag lại hay thay thế bên trong lượt này; nếu digest không
+phân giải được thì lượt chạy dừng, chứ không build một cái thay thế rồi gọi nó là cùng một release.
+Manifest phải đã được kiểm đúng với chính release này, vì manifest ghim vào một release khác chính là
+cách một image chưa duyệt tới được một target đã duyệt.
+
+## Thẩm quyền là được khai, không bao giờ được ngầm hiểu
+
+Deploy đòi hỏi một grant khai riêng, phủ đúng project này, môi trường này, target này và hành động
+`deploy`, và còn hiệu lực tại đúng lúc target được quan sát. Không nhiệm vụ thường nào, không tiền lệ
+từ một project anh em nào và không sự gấp gáp nào ngầm cấp nó, và một lần deploy không có thẩm quyền
+không trở thành có thẩm quyền chỉ vì nó hữu ích. Mất mát phá huỷ, xoay vòng credential, hay một host,
+domain, tenant hoặc project mới đều nằm hẳn ngoài thẩm quyền của operator này và trả `APPROVAL_REQUIRED`.
+
+## Credential là tên, không bao giờ là giá trị
+
+Handle được phân giải qua custody đang có, đúng lúc cần. Một giá trị đã phân giải không bao giờ đi
+vào plan, manifest, biên bản, một dòng log, một tham số lệnh hay một tin nhắn. Biên bản ghi lại
+những handle nào đã được phân giải và không gì hơn, và không trường nào trong hợp đồng chứa nổi một
+giá trị dù có ai cố: một token viết vào chỗ đáng lẽ là handle `secret-ref://` bị từ chối như đầu vào
+sai dạng, thay vì lặng lẽ trôi vào một danh sách tham số.
+
+## Mọi tác động đều là compare-and-set
+
+Một bước hoặc có làm đổi một boundary, hoặc không. Các bước có làm đổi là `host-prepare`,
+`artifact-publish`, `migrate`, `domain-reconcile`, `rollout`, `recover` và `rollback`, và mỗi bước
+ghi lại revision quan sát được của chính boundary mình trước và sau. Trạng thái mong muốn mà đã trùng
+sẵn là một no-op idempotent đã được chứng minh và được ghi đúng như vậy; tuyên bố đã áp dụng mà
+revision không dịch chuyển thì bị từ chối, còn một bước chỉ đọc mà báo revision là bịa ra một sự thật
+về boundary nó chưa hề chạm. Execution root là thứ bỏ đi được và dựng lại được.
+
+## Giám sát phân biệt đang tiến và đang hỏng
+
+Ở dự án này, push lên `main` kích hoạt workflow và boot mất khoảng tám tới chín phút, nên
+`progressing` là điều kiện bình thường trong phần lớn cửa sổ và không bao giờ bị coi là lỗi, và một
+deadline giám sát ngắn hơn cửa sổ mà nó phải chứa sẽ sinh ra một lỗi giả chắc chắn. Một lần probe
+chớp nhoáng không bao giờ thành recovery: điều kiện hỏng phải kéo dài qua ít nhất hai lần quan sát.
+Một release không phải release này và cũng không phải release nó thay thế sẽ dừng lượt chạy bằng
+`CONCURRENT_DRIFT` và buộc lập kế hoạch lại; nó không bao giờ được recover hay rollback như thể nó
+thuộc về đây. Recovery chỉ lặp lại những hành động đảo ngược được đã duyệt, đánh số các lần thử liền
+mạch từ một, giữ nguyên danh tính release, và một khi đã cạn thì không thể kết thúc bằng một lần
+deploy. Rollback chỉ hợp lệ khi release an toàn chính xác vẫn còn, trạng thái dữ liệu và schema hiện
+tại vẫn tương thích với nó, và revision thực sự đã dịch chuyển.
+
+## Trạng thái ổn định là được chứng minh, không phải được giả định
+
+Một rollout trả về không lỗi chưa phải một lần deploy. Ổn định nghĩa là digest bất biến đang active,
+mọi target đã khai đều sẵn sàng, không target bị thay thế nào còn active trừ khi chiến lược cho phép,
+cửa sổ đã trôi qua trọn vẹn, và mọi probe đã khai đều pass suốt cửa sổ đó. Đó là thứ biến ba lỗi
+im lặng thành ba lỗi phát hiện được: workflow chạy xong trong khi digest cũ vẫn đang phục vụ traffic;
+một trong hai target không bao giờ quay lại còn cái kia gánh hết tải; probe readiness pass đúng một
+lần, đúng khoảnh khắc nó tình cờ được hỏi. Ít nhất một probe đã khai phải là probe công khai, vì một
+lượt chạy chỉ quan sát sức khoẻ container thì chẳng chứng minh được gì mà người dùng thấy được; ở đây
+probe GraphQL typename trả `200` là tín hiệu readiness.
+
+## Hai fallback có thứ tự, phần còn lại thì terminate
+
+Một rollout hỏng không phải là hết lượt, nó là cửa vào fallback thứ nhất: `ROLLOUT_FAILED` đi nhánh
+phục hồi, nhánh chỉ lặp lại những hành động đảo ngược được đã duyệt trên cùng danh tính release. Khi
+chúng cạn, `RECOVERY_EXHAUSTED` đi fallback thứ hai: rollback về `rollbackIdentity` theo đúng digest
+của nó. Cả hai đều được ghi dưới `## Fallbacks taken`, vì một nhánh đi âm thầm là một nhánh không ai
+soát lại được. Sau đó không còn gì để thử nữa, nên `ROLLBACK_IDENTITY_MISSING`, `STEADY_STATE_UNPROVEN`
+và `CONCURRENT_DRIFT` terminate: một lần rollback không còn release an toàn, một cửa sổ không bao giờ
+khép, và một release lạ xuất hiện giữa lượt, mỗi thứ đều là trạng thái operator này không được hành
+động tiếp lên.
+
+## Deadline và probe có mặc định, phê duyệt thì không
+
+`steadyDeadline` mặc định 600 giây vì đó là thời gian boot mà dự án này thực sự cho thấy, còn `probes`
+mặc định lấy bộ mà manifest đã kiểm khai ra, nên người không nêu cái nào vẫn được đo theo một thứ có
+thật. `approval` thì hoàn toàn không có mặc định: đổi thứ mà production đang phục vụ luôn là việc có
+người nói đồng ý.
+
+## Ranh giới ghi
+
+Context chỉ đọc, trừ các mutation đã khai. Operator chỉ áp các mutation host, migration, domain và
+rollout đã khai lên đúng danh tính release đã đóng băng, khôi phục đúng release rollback đã khai khi
+đi nhánh đó, và chỉ ghi `response/` của nhánh mình: `data/probes.json`, `response.md` và
+`response.json`. Nó không log, lưu, in ra hay trả về một giá trị credential đã phân giải; không deploy
+một release mà thẩm quyền đã khai không phủ; không build lại, gắn tag lại hay thay đổi artifact bất
+biến mà digest đóng băng chỉ tới; không sửa intent hay kiểm lại manifest thành một thứ khác; không
+recover hay rollback một release xuất hiện giữa lượt và không thuộc về lượt này; không báo một lượt đã
+rollback là đã giao thành công cái release bị từ chối; và không tuyên bố trạng thái ổn định từ một lần
+quan sát probe duy nhất hay từ một rollout được giả định.
+
+## Context
+
+| Alias | Bind | Bắt buộc |
+| --- | --- | --- |
+| `@remote/ghcr/<image>` | image bất biến theo digest; một tag không bao giờ là ràng buộc | có |
+| `@workspaces/device-state` | handle credential theo tên và custody của chúng; giá trị không bao giờ xuất hiện | có |
+| `@remote/github-actions/<runId>` | bằng chứng CI của build và rollout, chỉ đọc | không |
+
+## Đầu vào
+
+| Kind | Từ đâu | Bắt buộc |
+| --- | --- | --- |
+| `quality-verification` | `quality.verify`; kiểm định đi trước một bản build bất biến, và nó là thẩm quyền mà lượt chạy này đứng lên | có |
+
+## Yêu cầu
+
+| Field | Kiểu | Mặc định | Hỏi |
+| --- | --- | --- | --- |
+| `release` | id | — | Danh tính release bất biến đang được deploy, kèm digest `sha256:` nhận diện nó |
+| `target` | id | — | Đúng một target mà lần deploy này được đổi, cùng môi trường nó nằm trong |
+| `approval` | id | — | Grant deploy đã khai phủ project, môi trường và target này; đổi thứ production đang phục vụ luôn cần một con người |
+| `probes` | list of `{probeId, kind, endpointRef, expectStatus}` | the probes the validated manifest declares | Trạng thái ổn định được đo bằng gì; ít nhất một probe là công khai |
+| `steadyDeadline` | number | 600 | Deadline giám sát có chặn trên, tính bằng giây, đo theo thời gian boot mà dự án này cho thấy |
+| `rollbackIdentity` | `{releaseId, artifactRef, digest, dataCompatible}` | — | Đúng release an toàn mà fallback rollback khôi phục, theo digest |
+| `resume` | token | null | Token của nhánh bị chặn khi vào lại sau một mã dừng |
+
+## Các bước
+
+| # | Bước | Tham số | Đọc | Ghi | Dừng với |
+| --- | --- | --- | --- | --- | --- |
+| 1 | Kiểm cổng vào, thẩm quyền mà Đầu vào mang, và resume | `resume` | `request/request.json`, Đầu vào `quality-verification` là thẩm quyền lượt chạy này đứng lên | — | `INVALID_INPUT`, `AUTHORIZATION_MISSING`, `NO_PROGRESS` |
+| 2 | Ràng release và biên dịch kế hoạch | `release`, `target`, `approval` | @remote/ghcr/<image> tại digest đã đóng băng, @remote/github-actions/<runId> cho trạng thái quan sát được, @tools/git, @tools/ci | — | `MANIFEST_INVALID`, `APPROVAL_REQUIRED` |
+| 3 | Khởi tạo execution root và phân giải credential theo tên | — | @workspaces/device-state cho các handle đã khai và custody của chúng, @tools/secrets | — | `CREDENTIAL_UNAVAILABLE` |
+| 4 | Chuẩn bị host, publish artifact theo digest, migrate và đối chiếu domain | — | @remote/ghcr/<image> cho artifact theo digest, @remote/github-actions/<runId> cho revision trước và sau của từng boundary | @tools/shell | `HOST_UNAVAILABLE`, `ARTIFACT_MISSING`, `MIGRATION_BLOCKED`, `DOMAIN_UNRECONCILED` |
+| 5 | Roll out | — | @remote/ghcr/<image> cho revision của target trước và sau | @tools/container | `ROLLOUT_FAILED` |
+| 6 | Theo dõi trong deadline, có backoff | `steadyDeadline`, `probes` | @remote/github-actions/<runId> cho các quan sát probe suốt cửa sổ, @tools/http | `response/data/probes.json` | — |
+| 7 | Phát hiện drift đồng thời trước khi hành động | — | `response/data/probes.json`, @remote/ghcr/<image> cho release đang active theo digest | — | `CONCURRENT_DRIFT` |
+| 8 | Đi nhánh phục hồi khi lỗi còn dai dẳng | — | `response/data/probes.json`, @remote/ghcr/<image> tại cùng danh tính release | @tools/container | `RECOVERY_EXHAUSTED` |
+| 9 | Đi nhánh rollback khi phục hồi không giữ được | `rollbackIdentity` | @remote/ghcr/<image> tại đúng digest an toàn | @tools/container | `ROLLBACK_IDENTITY_MISSING` |
+| 10 | Chứng minh trạng thái ổn định, viết biên bản và phát | — | mọi thứ ở trên | `response/response.md`, `response/response.json` | `STEADY_STATE_UNPROVEN` |
+
+Bước 8 và 9 là hai fallback theo thứ tự, không phải một chuỗi mà lượt chạy nào cũng đi qua: một lượt
+chỉ vào bước 8 dưới `ROLLOUT_FAILED` và chỉ vào bước 9 dưới `RECOVERY_EXHAUSTED`, còn lượt không đi
+cái nào thì ghi nhánh là `none`. Một lần resume bắt đầu lại từ cổng vào, chỉ dùng lại quan sát có
+fingerprint không đổi, và giữ nguyên danh tính release, vì một release khác là một lần deploy khác;
+một lần resume không thêm thẩm quyền, manifest, credential hay quan sát nào là `NO_PROGRESS`.
+
+## Đầu ra
+
+| Kind | File | Kiểu | Bắt buộc |
+| --- | --- | --- | --- |
+| `release-deployment` | `response/response.md` | md | có |
+| `probes` | `response/data/probes.json` | data | có |
+
+## Dừng
+
+| Code | Xử lý |
+| --- | --- |
+| `INVALID_INPUT` | terminate |
+| `NO_PROGRESS` | terminate |
+| `AUTHORIZATION_MISSING` | terminate |
+| `MANIFEST_INVALID` | terminate |
+| `APPROVAL_REQUIRED` | terminate |
+| `CREDENTIAL_UNAVAILABLE` | terminate |
+| `HOST_UNAVAILABLE` | terminate |
+| `ARTIFACT_MISSING` | terminate |
+| `MIGRATION_BLOCKED` | terminate |
+| `DOMAIN_UNRECONCILED` | terminate |
+| `ROLLOUT_FAILED` | fallback |
+| `RECOVERY_EXHAUSTED` | fallback |
+| `CONCURRENT_DRIFT` | terminate |
+| `ROLLBACK_IDENTITY_MISSING` | terminate |
+| `STEADY_STATE_UNPROVEN` | terminate |
+
+## Kế tiếp
+
+| Khi | Operator |
+| --- | --- |
+| host, registry artifact, custody credential hay release an toàn cần một thay đổi runtime dùng chung | `platform.operate` |

package/operators/release-deploy/self-test.mjs

@@ -0,0 +1,235 @@
+// Proves validate.mjs on a synthetic session branch: one steady deployment, one that took the
+// recovery fallback, one that took both fallbacks and ended rolled back, one blocked on an unproven
+// steady state, and one mutation per law, each of which must fail with a line that names the defect.
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { validateReleaseStep } from './validate.mjs';
+
+const RELEASE = 'release:2026.01.10-1';
+const PREVIOUS = 'release:2026.01.03-2';
+const DIGEST = `sha256:${'1'.repeat(64)}`;
+const SAFE_DIGEST = `sha256:${'2'.repeat(64)}`;
+const TARGET = 'production/api';
+const APPROVAL = '@worktrees/businesses/features/release/model.json#deploy-grant';
+const MANIFEST = '.stacks/production/api.manifest.json';
+const ARTIFACT = '@remote/ghcr/starci/academy-api';
+const DEADLINE = 600;
+const PROBES = [
+  { probeId: 'public-graphql-typename', kind: 'public', endpointRef: 'https://api.example/graphql', expectStatus: 200 },
+];
+const ROLLBACK = { releaseId: PREVIOUS, artifactRef: ARTIFACT, digest: SAFE_DIGEST, dataCompatible: true };
+
+const observation = (at, condition, status = 'pass') => ({
+  observedAt: at, condition, activeReleaseIds: [RELEASE], activeDigest: DIGEST, availableTargets: 1,
+  probeResults: [{ probeId: 'public-graphql-typename', status, observedStatus: status === 'pass' ? 200 : 502, observedAt: at }],
+});
+
+const probesJson = ({ observations = [observation('2026-01-10T00:01:00.000Z', 'progressing'), observation('2026-01-10T00:07:00.000Z', 'steady')], finalCondition = 'steady', deadlineSeconds = DEADLINE, elapsedSeconds = 420, backoffSeconds = 30 } = {}) => ({
+  deadlineSeconds, elapsedSeconds, backoffSeconds, observations, finalCondition,
+});
+
+const NL = String.fromCharCode(10);
+const STEPS = [
+  ['`authorize`', 'applied', '—', '—', 'the declared grant covers this project, environment and target'],
+  ['`rollout`', 'applied', '4', '5', 'the target moved to the immutable digest'],
+  ['`monitor`', 'applied', '—', '—', 'the window was observed to its end'],
+];
+
+function responseMd({
+  release = RELEASE, digest = DIGEST, target = TARGET, approval = APPROVAL, deadline = DEADLINE,
+  rollbackId = PREVIOUS, outcome = 'deployed', branch = 'none', steps = STEPS,
+  monitoring = { Deadline: DEADLINE, Elapsed: 420, Backoff: 30, 'Final condition': 'steady' },
+  steady = { 'Active digest': DIGEST, 'Available targets': '1 of 1', 'Superseded active': '0', 'Window elapsed': '300' },
+  fallbacksTaken = [],
+} = {}) {
+  return `# release-deployment — ${release}
+
+The immutable release reached its declared target under the declared grant, and the steady state
+rests on the observed digest, the available targets and every declared probe across the window.
+
+## Binding
+
+| Field | Value |
+| --- | --- |
+| Operator | \`release.deploy\` |
+| Step | \`step-1/parallel-1\` |
+| Project | \`starci-academy\` |
+| Release | ${release} |
+| Artifact | \`${ARTIFACT}\` |
+| Digest | \`${digest}\` |
+| Target | ${target} |
+| Environment | production |
+| Replaced release | \`${PREVIOUS}\` |
+| Approval | ${approval} |
+| Manifest | \`${MANIFEST}\` |
+| Steady deadline | ${deadline} |
+| Rollback identity | ${rollbackId} |
+
+## Outcome
+
+| Field | Value |
+| --- | --- |
+| Outcome | ${outcome} |
+| Branch | ${branch} |
+
+## Steps
+
+| Step | State | Revision before | Revision after | Statement |
+| --- | --- | --- | --- | --- |
+${steps.map((s) => `| ${s[0]} | ${s[1]} | ${s[2]} | ${s[3]} | ${s[4]} |`).join('\n')}
+
+## Monitoring
+
+| Field | Value |
+| --- | --- |
+| Deadline | ${monitoring.Deadline} |
+| Elapsed | ${monitoring.Elapsed} |
+| Backoff | ${monitoring.Backoff} |
+| Final condition | ${monitoring['Final condition']} |
+
+## Steady state
+
+| Metric | Value |
+| --- | --- |
+${Object.entries(steady).map(([k, v]) => `| ${k} | ${/^sha256:/.test(String(v)) ? `\`${v}\`` : v} |`).join('\n')}
+
+## Findings
+
+| Code | Step | Statement |
+| --- | --- | --- |
+| \`IDEMPOTENT_NO_OP\` | \`host-prepare\` | the host already matched the declaration |
+
+## Fallbacks taken
+
+| Code | Action |
+| --- | --- |
+${fallbacksTaken.map((c) => `| \`${c}\` | the branch was taken and recorded |`).join(NL)}
+`;
+}
+
+const requestJson = ({ release = RELEASE, target = TARGET, approval = APPROVAL, probes = PROBES, deadline = DEADLINE, rollbackIdentity = ROLLBACK, extra = {} } = {}) => ({
+  schemaVersion: 9, operatorId: 'release.deploy', step: 1, parallel: 1, sessionId: 's-test',
+  contexts: [{ alias: '@remote/ghcr/starci/academy-api', head: null }],
+  requirements: { release, target, approval, probes, steadyDeadline: deadline, rollbackIdentity, resume: null, ...extra },
+  inputs: { 'quality-verification': 'step-1/parallel-1/response/quality.md' }, resume: null,
+});
+
+const responseJson = ({ status = 'done', stop, fallbacks = [], next = ['platform.operate'] } = {}) => ({
+  schemaVersion: 9, operatorId: 'release.deploy', step: 1, parallel: 1, status, ...(stop ? { stop } : {}),
+  fallbacks,
+  fields: status === 'blocked' ? {} : { 'release-deployment': 'response/response.md', probes: 'response/data/probes.json' },
+  commits: [], next,
+});
+
+function writeBranch(files) {
+  const session = mkdtempSync(path.join(tmpdir(), 'release-session-'));
+  const branch = path.join(session, 'step-1', 'parallel-1');
+  for (const d of ['request', 'response/data', 'response/artifacts']) mkdirSync(path.join(branch, d), { recursive: true });
+  writeFileSync(path.join(session, 'state.json'), JSON.stringify({ id: 's-test', chain: [['1/1']], steps: { '1/1': 'release.deploy' }, current: '1/1', status: 'running' }));
+  writeFileSync(path.join(branch, 'response', 'quality.md'), '# quality\n');
+  for (const [name, content] of Object.entries(files)) {
+    if (content === null) continue;
+    writeFileSync(path.join(branch, name), typeof content === 'string' ? content : JSON.stringify(content, null, 2));
+  }
+  return { branch, session };
+}
+
+const baseline = (over = {}) => ({
+  'request/request.json': requestJson(),
+  'response/response.json': responseJson(),
+  'response/response.md': responseMd(),
+  'response/data/probes.json': probesJson(),
+  ...over,
+});
+
+
+// The recovery fallback: two failing observations, then steady again on the same release.
+const recovered = () => baseline({
+  'response/response.json': responseJson({ fallbacks: ['ROLLOUT_FAILED'] }),
+  'response/data/probes.json': probesJson({
+    observations: [observation('2026-01-10T00:01:00.000Z', 'failing', 'fail'), observation('2026-01-10T00:03:00.000Z', 'failing', 'fail'), observation('2026-01-10T00:07:00.000Z', 'steady')],
+  }),
+  'response/response.md': responseMd({
+    branch: 'recover',
+    steps: [...STEPS, ['`recover`', 'applied', '5', '6', 'the approved reversible action restored the target']],
+    fallbacksTaken: ['ROLLOUT_FAILED'],
+  }),
+});
+
+// Both fallbacks in order: the recovery ran out and the safe release was restored by digest.
+const rolledBack = () => baseline({
+  'response/response.json': responseJson({ fallbacks: ['ROLLOUT_FAILED', 'RECOVERY_EXHAUSTED'] }),
+  'response/data/probes.json': probesJson({
+    observations: [observation('2026-01-10T00:01:00.000Z', 'failing', 'fail'), observation('2026-01-10T00:03:00.000Z', 'failing', 'fail'), observation('2026-01-10T00:09:00.000Z', 'steady')],
+  }),
+  'response/response.md': responseMd({
+    outcome: 'rolled-back', branch: 'rollback',
+    steps: [...STEPS, ['`recover`', 'applied', '5', '6', 'the approved actions ran out'], ['`rollback`', 'applied', '6', '7', 'the safe release was restored by digest']],
+    steady: { 'Active digest': SAFE_DIGEST, 'Available targets': '1 of 1', 'Superseded active': '0', 'Window elapsed': '300' },
+    fallbacksTaken: ['ROLLOUT_FAILED', 'RECOVERY_EXHAUSTED'],
+  }),
+});
+
+async function expectValid(files, label) {
+  const { branch, session } = writeBranch(files);
+  const { errors } = await validateReleaseStep(branch);
+  rmSync(session, { recursive: true, force: true });
+  assert.deepEqual(errors, [], `${label} should be valid`);
+}
+async function expectError(files, needle, label) {
+  const { branch, session } = writeBranch(files);
+  const { errors } = await validateReleaseStep(branch);
+  rmSync(session, { recursive: true, force: true });
+  assert.ok(errors.some((e) => e.includes(needle)), `${label}: expected an error containing "${needle}", got:\n${errors.join('\n') || '(none)'}`);
+}
+
+await expectValid(baseline(), 'a steady deployment of the immutable release');
+await expectValid(recovered(), 'the recovery fallback taken after a persistent failure');
+await expectValid(rolledBack(), 'both fallbacks in order, ending in a restored release');
+await expectValid({
+  'request/request.json': requestJson(),
+  'response/response.json': responseJson({ status: 'blocked', stop: 'STEADY_STATE_UNPROVEN', next: [] }),
+  'response/response.md': null, 'response/data/probes.json': null,
+}, 'blocked because the steady window never closed');
+
+await expectError(baseline({ 'response/response.json': { ...responseJson(), stop: 'ROLLOUT_FAILED' } }), 'only a blocked response carries a stop', 'done with a stop');
+await expectError(baseline({ 'response/response.json': responseJson({ status: 'blocked', stop: 'ROLLOUT_FAILED', next: [] }) }), 'has disposition fallback under these requirements', 'a fallback code used to block the branch');
+await expectError(baseline({ 'response/response.json': responseJson({ fallbacks: ['STEADY_STATE_UNPROVEN'] }) }), 'cannot be taken as a fallback', 'a terminate code taken as a fallback');
+await expectError(baseline({
+  'response/response.json': responseJson({ fallbacks: ['RECOVERY_EXHAUSTED'] }),
+  'response/response.md': responseMd({ outcome: 'rolled-back', branch: 'rollback', steps: [...STEPS, ['`rollback`', 'applied', '6', '7', 'restored']], steady: { 'Active digest': SAFE_DIGEST, 'Available targets': '1 of 1', 'Superseded active': '0', 'Window elapsed': '300' }, fallbacksTaken: ['RECOVERY_EXHAUSTED'] }),
+}), 'reached only through an exhausted recovery', 'a rollback that skipped the recovery branch');
+await expectError(baseline({ 'request/request.json': requestJson({ extra: { strategy: 'rolling' } }) }), 'requirements.strategy is not a field', 'a field the operator no longer declares');
+await expectError(baseline({ 'request/request.json': requestJson({ approval: null }) }), 'required field approval has no value', 'a production deploy nobody approved');
+await expectError(baseline({ 'request/request.json': requestJson({ probes: [{ probeId: 'container-health', kind: 'internal', endpointRef: 'unix:///health', expectStatus: 200 }] }), 'response/data/probes.json': probesJson({ observations: [{ ...observation('2026-01-10T00:01:00.000Z', 'progressing'), probeResults: [{ probeId: 'container-health', status: 'pass', observedStatus: 200, observedAt: '2026-01-10T00:01:00.000Z' }] }, { ...observation('2026-01-10T00:07:00.000Z', 'steady'), probeResults: [{ probeId: 'container-health', status: 'pass', observedStatus: 200, observedAt: '2026-01-10T00:07:00.000Z' }] }] }) }), 'at least one declared probe is public', 'a run proving only container health');
+await expectError(baseline({ 'request/request.json': requestJson({ rollbackIdentity: { ...ROLLBACK, digest: 'v1.4.0' } }) }), 'a rollback by tag restores whatever the tag now points at', 'a rollback identity named by tag');
+await expectError(baseline({ 'request/request.json': requestJson({ extra: { release: RELEASE }, target: TARGET, approval: 'ghp_abcdefghijklmnopqrstuvwxyz' }) }), 'looks like a resolved credential value', 'a token where a handle belongs');
+await expectError(baseline({ 'request/request.json': requestJson({ deadline: 120 }) }), 'but the request pinned 120s', 'monitoring measured against another deadline');
+await expectError(baseline({ 'response/data/probes.json': probesJson({ elapsedSeconds: 900 }) }), 'ran past its own bounded deadline', 'monitoring that outran its deadline');
+await expectError(baseline({ 'response/data/probes.json': probesJson({ backoffSeconds: 900 }) }), 'backoff cannot exceed the deadline', 'a backoff wider than the window');
+await expectError({
+  ...recovered(),
+  'response/data/probes.json': probesJson({ observations: [observation('2026-01-10T00:01:00.000Z', 'failing', 'fail'), observation('2026-01-10T00:07:00.000Z', 'steady')] }),
+}, 'one transient probe is not a persistent failure', 'recovery entered on a single failing probe');
+await expectError(baseline({ 'response/data/probes.json': probesJson({ finalCondition: 'deadline-exceeded' }) }), 'which is STEADY_STATE_UNPROVEN, not a deployment', 'a deployment over an exceeded deadline');
+await expectError(baseline({ 'response/response.md': responseMd({ release: 'release:someone-elses' }) }), 'but the request bound', 'a receipt for another release');
+await expectError(baseline({ 'response/response.md': responseMd({ digest: 'latest' }) }), 'identified by its digest, never by a tag', 'a release named by tag');
+await expectError(baseline({ 'response/response.md': responseMd({ approval: '`someone-elses-grant`' }) }), 'names an approval the request did not bind', 'a grant borrowed from another deployment');
+await expectError(baseline({ 'response/response.md': responseMd({ branch: 'recover' }) }), 'but the fallbacks taken say none', 'a branch the fallbacks never recorded');
+await expectError({
+  ...rolledBack(),
+  'response/response.md': responseMd({ outcome: 'deployed', branch: 'rollback', steps: [...STEPS, ['`recover`', 'applied', '5', '6', 'x'], ['`rollback`', 'applied', '6', '7', 'y']], fallbacksTaken: ['ROLLOUT_FAILED', 'RECOVERY_EXHAUSTED'] }),
+}, 'a restored release is its own terminal', 'a rollback reported as delivery');
+await expectError(baseline({ 'response/response.md': responseMd({ steps: [['`authorize`', 'applied', '—', '—', 'x'], ['`rollout`', 'applied', '4', '4', 'y'], ['`monitor`', 'applied', '—', '—', 'z']] }) }), 'claims it applied without moving a revision', 'an application that moved nothing');
+await expectError(baseline({ 'response/response.md': responseMd({ steps: [['`authorize`', 'applied', '2', '3', 'x'], ['`rollout`', 'applied', '4', '5', 'y'], ['`monitor`', 'applied', '—', '—', 'z']] }) }), 'reports a revision for a boundary it never touched', 'a reading step inventing a revision');
+await expectError(baseline({ 'response/response.md': responseMd({ steady: { 'Active digest': SAFE_DIGEST, 'Available targets': '1 of 1', 'Superseded active': '0', 'Window elapsed': '300' } }) }), 'while another digest is active', 'a deployment over the old digest');
+await expectError(baseline({ 'response/response.md': responseMd({ steady: { 'Active digest': DIGEST, 'Available targets': '1 of 2', 'Superseded active': '0', 'Window elapsed': '300' } }) }), 'a partly available target set is not steady state', 'one target absorbing the load for two');
+await expectError(baseline({ 'response/response.md': responseMd({ steady: { 'Active digest': DIGEST, 'Available targets': '1 of 1', 'Superseded active': '1', 'Window elapsed': '300' } }) }), 'still serving traffic', 'a superseded target left active');
+await expectError(baseline({ 'response/data/probes.json': probesJson({ observations: [observation('2026-01-10T00:07:00.000Z', 'steady')] }) }), 'claimed from a single observation', 'steady state read off one probe');
+await expectError(baseline({ 'response/response.md': responseMd({ monitoring: { Deadline: DEADLINE, Elapsed: 420, Backoff: 30, 'Final condition': 'progressing' } }) }), 'but the series ended steady', 'a receipt disagreeing with its own series');
+await expectError(baseline({ 'response/data/probes.json': { ...probesJson(), finalCondition: 'nope' } }), 'finalCondition', 'probes schema');
+await expectError(baseline({ 'response/response.md': responseMd().replace('## Steady state', '## Stable state') }), 'missing section ^## Steady state$', 'receipt section renamed');
+
+process.stdout.write('release.deploy self-test: 4 valid branches, 26 rejected mutations\n');