@starci/skills 1.1.0

package/operators/platform-operate/operator.md

@@ -0,0 +1,162 @@
+# platform.operate
+
+## Job
+
+Operate one bounded shared observability, Sonar, or tunnel service from exact evidence: inventory it,
+converge only the approved delta, prove every check the bound knowledge requires, and stop at the
+smallest owning gap instead of taking product deployment ownership.
+
+## Shared infrastructure, not product
+
+This operator serves shared infrastructure and never takes product deployment ownership. That
+boundary is not advice: a resource can only be changed if the bound inventory lists it under the same
+service kind, and a product deployment target is never an observability, Sonar, or tunnel resource. A
+plan that reaches for one is invalid input rather than a judgement call at execution time, and a
+request to restart a product service to make room for a shared one leaves through a
+`PRODUCT_DEPLOYMENT_DECLINED` finding rather than through a mutation.
+
+## One job, three branches
+
+The service kind the inventory records selects the branch, and the three are branches of one job
+rather than three operators.
+Each branch publishes three closed sets, and each is enforced. Observability applies `update-config`,
+`restart-service`, `upsert-dashboard` and `update-remote-write`, proves `service-health`,
+`target-boundary`, `label-boundary`, `remote-write-delivery`, `sample-ordering`, `retry-backoff` and
+`sensitive-data-filter`, and needs `metrics:remote-write`. Sonar applies `create-project`,
+`assign-profile`, `assign-gate` and `enforce-setting`, proves `service-available`, `project-exists`,
+`source-revision`, `profile-assigned`, `gate-assigned` and `enforcement-active`, and needs
+`sonar:project-admin`. Tunnel applies `create-tunnel`, `update-tunnel-route` and `upsert-proxied-dns`,
+proves `dns-target`, `tunnel-route`, `tls` and `public-https`, and needs `tunnel:write` and
+`dns:write`. An effect or a check filed under the wrong branch is invalid input rather than a
+warning, because a cross-filed effect is how an unapproved change acquires the appearance of
+authority. The required proof set is the whole set the branch publishes: the caller cannot ask for
+less, because a green dashboard alone never proved delivery, ordering, or redaction.
+
+## Inventory before change
+
+A shared service is inventoried before it is changed. The inventory is bound by fingerprint, so the
+receipt states exactly what the service was when the decision was made, and a concurrent revision
+becomes visible as `INVENTORY_DRIFT` rather than being silently overwritten. The recheck happens
+before any mutation, so a differing revision stops the invocation while nothing has changed yet.
+Anything mutated appears in the inventory echo, so a change to a resource nobody looked at first
+cannot be reported as an operation at all. An already-converged service is a proved no-op with no
+mutation, not a failure and not a rewrite, and a converged operation that reports no mutation is
+refused because one of its two statements is false. Application touches only effects inside the
+approved set, one resource at a time, recording the before and after revision of each; a partial
+application is reported as `PARTIAL_MUTATION` with exact revisions and is never hidden behind a
+generic blocker.
+
+## A port in use is a coordination finding
+
+A port already bound by another process is a fact about a shared machine, not permission to reclaim
+it. The operation records `PORT_COORDINATION_REQUIRED` naming both the port and the process that
+holds it, returns `PORT_CONFLICT`, and stops. It does not stop, kill, restart, or reconfigure the
+holder, and no mutation may target a process observed holding a claimed port. Coordination is the
+required next step and it belongs to the two owners, not to this invocation; `PORT_CONFLICT` is the
+expected outcome on a busy shared machine, not a defect in the plan.
+
+## Credentials are resolved, never recorded
+
+A capability is a handle and its custody evidence. The credential behind it is resolved for use at
+the moment of the call and is never logged, echoed into evidence, or persisted. The receipt refuses
+the handle as well as the value, because a receipt is durable and a durable record of a capability is
+a leaked credential with a delay; a string carrying credential material anywhere in the request or
+the response is refused as malformed.
+
+## The desired state is one approved declaration
+
+`desiredState` is the whole of what the person asks for: the approved plan hash, the service kind the
+plan was written against, the resources to converge, the effects to apply, and the two scope sets that
+say which resources may change and which may only be observed. Keeping it as one declaration is what
+makes the approval mean something: `approval` covers that declaration, hash and all, so a field
+edited afterwards no longer matches the hash the approval named. `approval` has no default because
+this is a runtime other sessions and other people share, and changing what a shared service does is
+never something an agent decides alone. `portClaims` defaults to the empty list, because most
+operations need no port at all and a claim nobody made cannot collide with anybody.
+
+## Boundary
+
+Context is read-only apart from the approved delta. The operator applies only the approved effect
+delta on the inventoried shared service, under an exclusive lease on
+`@worktrees/sessions/central-runtime`, and writes only `response/` of its own branch:
+`data/delta.json`, `data/checks.json`, `response.md` and `response.json`. It does not deploy,
+restart, migrate, or otherwise take ownership of a product service; does not mutate a resource the
+bound inventory does not list; does not emit an effect or a check the bound service kind does not
+publish; does not free a port by stopping, killing, or reconfiguring the process that already holds
+it; does not record a credential value, capability handle, or secret-shaped token anywhere in the
+output; does not edit knowledge or grant its own approval; and does not claim an operated outcome
+while any required check is absent or failed, nor any product readiness, release approval, or UAT
+proof.
+
+## Context
+
+| Alias | Bind | Required |
+| --- | --- | --- |
+| `@worktrees/sessions/central-runtime` | the shared runtime owner: inventory, generation and health, bound by fingerprint and generation, written only under an exclusive lease | yes |
+| `@workspaces/ports/<project>` | the port projection the runtime binds to | yes |
+| `@workspaces/device-state` | capability handles by name and their custody; values never appear | yes |
+| `@workspaces/projects/<project>/<role>` | which projects the shared services serve | no |
+
+## Inputs
+
+| Kind | From | Required |
+| --- | --- | --- |
+
+## Requirements
+
+| Field | Type | Default | Ask |
+| --- | --- | --- | --- |
+| `service` | id | — | The one shared service being operated |
+| `desiredState` | `{planSha256, serviceKind, resourceRefs, effects, mutableResourceRefs, observationOnlyResourceRefs}` | — | The approved declaration: which plan, which branch, which resources, which effects, and what may change against what may only be observed |
+| `portClaims` | list of `{port, resourceRef}` | [] | Which ports the desired state needs, and for which owned resource |
+| `approval` | id | — | The approval that covers this desired state; changing a shared runtime always needs a person |
+| `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 and resume | `resume` | `request/request.json`, @worktrees/sessions/central-runtime at the frozen generation | — | `INVALID_INPUT`, `SOURCE_DRIFT`, `NO_PROGRESS` |
+| 2 | Bind the authority: the runtime, the device state, the projects and the approval | `service`, `approval` | @worktrees/sessions/central-runtime for the inventory fingerprint and generation, @workspaces/device-state for each capability handle with its custody evidence, @workspaces/projects/<project>/<role>, @tools/secrets | — | `AUTHORITY_DRIFT`, `CAPABILITY_MISSING` |
+| 3 | Recheck the inventory once before anything changes | — | @worktrees/sessions/central-runtime, the declared resources re-observed once, @tools/git | — | `INVENTORY_DRIFT` |
+| 4 | Resolve the port claims | `portClaims` | @workspaces/ports/<project> for the claimed ports, @worktrees/sessions/central-runtime for their observed holders | — | `PORT_CONFLICT` |
+| 5 | Derive the delta between what is observed and what is desired | `desiredState` | @worktrees/sessions/central-runtime for the observed state, `request/request.json` for the desired state | `response/data/delta.json` | — |
+| 6 | Apply the approved delta, one resource at a time, under an exclusive lease | — | @worktrees/sessions/central-runtime, @workspaces/device-state for the handles by name | @worktrees/sessions/central-runtime, `response/data/delta.json`, @tools/container, @tools/shell | `EFFECT_UNAUTHORIZED`, `SERVICE_UNAVAILABLE` |
+| 7 | Prove every required check | — | @worktrees/sessions/central-runtime re-read against the branch's complete proof set, @tools/http | `response/data/checks.json` | `PROOF_FAILED` |
+| 8 | Write the receipt and emit | — | everything above | `response/response.md`, `response/response.json` | — |
+
+A resume begins again at validation, reuses only unchanged fingerprinted observations, and consumes
+the exact delta; a resume that adds no authority, inventory, desired-state or scope change is
+`NO_PROGRESS`, and a re-observed inventory must arrive as a new fingerprint because the same
+fingerprint cannot yield a different answer.
+
+## Outputs
+
+| Kind | File | Type | Required |
+| --- | --- | --- | --- |
+| `platform-operation-receipt` | `response/response.md` | md | yes |
+| `delta` | `response/data/delta.json` | data | yes |
+| `checks` | `response/data/checks.json` | data | yes |
+
+## Stops
+
+| Code | Disposition |
+| --- | --- |
+| `INVALID_INPUT` | terminate |
+| `SOURCE_DRIFT` | terminate |
+| `NO_PROGRESS` | terminate |
+| `AUTHORITY_DRIFT` | terminate |
+| `CAPABILITY_MISSING` | terminate |
+| `INVENTORY_DRIFT` | terminate |
+| `PORT_CONFLICT` | terminate |
+| `EFFECT_UNAUTHORIZED` | terminate |
+| `SERVICE_UNAVAILABLE` | terminate |
+| `PROOF_FAILED` | terminate |
+
+## Next
+
+| When | Operator |
+| --- | --- |
+| the routed checkout or its head no longer matches the frozen binding | `workspace.bind` |
+| the runtime a frontend surface must be audited against is now serving | `frontend.surface.audit` |
+| the shared service is operated and the release that waited on it may continue | `release.deploy` |

package/operators/platform-operate/operator.vi.md

@@ -0,0 +1,160 @@
+# platform.operate
+
+## Việc
+
+Vận hành một dịch vụ dùng chung có ranh giới, thuộc observability, Sonar hay tunnel, từ bằng chứng
+chính xác: kiểm kê nó, hội tụ đúng phần delta đã duyệt, chứng minh mọi phép kiểm mà tri thức đã ràng
+đòi hỏi, và dừng ở khoảng trống sở hữu nhỏ nhất thay vì nhận lấy quyền deploy sản phẩm.
+
+## Hạ tầng dùng chung, không phải sản phẩm
+
+Operator này phục vụ hạ tầng dùng chung và không bao giờ nhận quyền deploy sản phẩm. Ranh giới đó
+không phải lời khuyên: một tài nguyên chỉ đổi được nếu inventory đã ràng liệt kê nó dưới cùng một
+service kind, và một đích deploy sản phẩm thì không bao giờ là tài nguyên observability, Sonar hay
+tunnel. Một kế hoạch với tay sang đó là đầu vào không hợp lệ chứ không phải chuyện cân nhắc lúc chạy,
+và yêu cầu restart một dịch vụ sản phẩm để dọn chỗ cho một dịch vụ dùng chung sẽ đi ra bằng phát hiện
+`PRODUCT_DEPLOYMENT_DECLINED` chứ không bằng một lần mutate.
+
+## Một việc, ba nhánh
+
+Kiểu dịch vụ mà inventory ghi lại chọn nhánh, và ba nhánh là ba nhánh của cùng một việc chứ không phải ba operator. Mỗi
+nhánh công bố ba tập đóng, và cả ba đều được thi hành. Observability áp `update-config`,
+`restart-service`, `upsert-dashboard` và `update-remote-write`, chứng minh `service-health`,
+`target-boundary`, `label-boundary`, `remote-write-delivery`, `sample-ordering`, `retry-backoff` và
+`sensitive-data-filter`, và cần `metrics:remote-write`. Sonar áp `create-project`, `assign-profile`,
+`assign-gate` và `enforce-setting`, chứng minh `service-available`, `project-exists`,
+`source-revision`, `profile-assigned`, `gate-assigned` và `enforcement-active`, và cần
+`sonar:project-admin`. Tunnel áp `create-tunnel`, `update-tunnel-route` và `upsert-proxied-dns`,
+chứng minh `dns-target`, `tunnel-route`, `tls` và `public-https`, và cần `tunnel:write` cùng
+`dns:write`. Một effect hay một check nộp nhầm nhánh là đầu vào không hợp lệ chứ không phải cảnh báo,
+vì effect nộp chéo chính là cách một thay đổi chưa duyệt khoác lên mình vẻ ngoài của thẩm quyền. Tập
+chứng minh bắt buộc là trọn tập mà nhánh công bố: người gọi không được xin ít hơn, vì một dashboard
+xanh tự nó chưa bao giờ chứng minh được delivery, ordering hay redaction.
+
+## Kiểm kê trước khi đổi
+
+Một dịch vụ dùng chung được kiểm kê trước khi bị đổi. Inventory được ràng bằng fingerprint, nên biên
+bản nói đúng dịch vụ là gì tại lúc quyết định, và một revision chạy song song hiện ra thành
+`INVENTORY_DRIFT` thay vì bị ghi đè lặng lẽ. Lần kiểm lại xảy ra trước mọi mutation, nên một revision
+khác đi sẽ dừng lượt chạy khi chưa có gì thay đổi. Mọi thứ bị mutate đều xuất hiện trong phần vọng
+lại của inventory, nên một thay đổi lên tài nguyên chẳng ai nhìn trước thì không thể báo là một lần
+vận hành. Một dịch vụ đã hội tụ sẵn là một no-op đã được chứng minh, không mutation nào, không phải
+lỗi và cũng không phải viết lại; còn một lần vận hành báo là đã hội tụ mà không có mutation nào thì
+bị từ chối vì một trong hai phát biểu của nó là sai. Việc áp chỉ chạm các effect nằm trong tập đã
+duyệt, mỗi lần một tài nguyên, ghi lại revision trước và sau của từng cái; áp một phần được báo là
+`PARTIAL_MUTATION` kèm đúng hai revision và không bao giờ bị giấu sau một mã chặn chung chung.
+
+## Một cổng đang bận là phát hiện cần phối hợp
+
+Một cổng đã bị tiến trình khác chiếm là một sự thật về máy dùng chung, không phải giấy phép giành lại
+nó. Lần vận hành ghi `PORT_COORDINATION_REQUIRED` nêu cả cổng lẫn tiến trình đang giữ nó, trả
+`PORT_CONFLICT`, rồi dừng. Nó không dừng, không giết, không restart và không cấu hình lại kẻ đang
+giữ, và không mutation nào được nhắm vào một tiến trình đã quan sát thấy đang giữ một cổng được
+claim. Phối hợp là bước kế bắt buộc và nó thuộc về hai người chủ, không thuộc lượt chạy này;
+`PORT_CONFLICT` là kết quả bình thường trên một máy dùng chung bận, không phải khiếm khuyết của kế
+hoạch.
+
+## Credential được phân giải, không bao giờ được ghi lại
+
+Một capability là một handle cùng bằng chứng custody của nó. Credential đứng sau nó được phân giải để
+dùng đúng lúc gọi và không bao giờ được log, vọng vào evidence hay lưu lại. Biên bản từ chối cả cái
+handle chứ không riêng giá trị, vì biên bản là thứ bền, và một bản ghi bền của một capability là một
+credential rò rỉ có độ trễ; một chuỗi mang vật liệu credential ở bất cứ đâu trong request hay
+response đều bị từ chối như dữ liệu sai dạng.
+
+## Trạng thái mong muốn là một khai báo đã duyệt
+
+`desiredState` là toàn bộ những gì người ta xin: hash của kế hoạch đã duyệt, kiểu dịch vụ mà kế hoạch
+được viết cho, các resource cần đưa về đúng trạng thái, các effect cần áp, và hai tập phạm vi nói
+resource nào được đổi và resource nào chỉ được quan sát. Giữ nó thành một khai báo duy nhất chính là
+thứ làm cho phê duyệt có nghĩa: `approval` phủ lên đúng khai báo đó, kèm cả hash, nên một field sửa
+sau đó không còn khớp cái hash mà phê duyệt đã gọi tên. `approval` không có mặc định vì đây là một
+runtime mà phiên khác và người khác dùng chung, và đổi việc một dịch vụ dùng chung đang làm không bao
+giờ là chuyện một agent tự quyết. `portClaims` mặc định là danh sách rỗng, vì phần lớn thao tác không
+cần cổng nào, và một claim không ai đặt thì không thể đụng ai.
+
+## Ranh giới ghi
+
+Context chỉ đọc, trừ phần delta đã duyệt. Operator chỉ áp delta effect đã duyệt lên dịch vụ dùng chung
+đã kiểm kê, dưới một lease độc quyền trên `@worktrees/sessions/central-runtime`, và chỉ ghi
+`response/` của nhánh mình: `data/delta.json`, `data/checks.json`, `response.md` và `response.json`.
+Nó không deploy, restart, migrate hay theo cách nào khác nhận quyền sở hữu một dịch vụ sản phẩm; không
+làm đổi một resource mà inventory đã ràng không liệt kê; không phát một effect hay một check mà nhánh
+dịch vụ đã ràng không công bố; không giải phóng một cổng bằng cách dừng, giết hay cấu hình lại tiến
+trình đang giữ nó; không ghi giá trị credential, handle capability hay token dạng bí mật ở bất kỳ đâu
+trong đầu ra; không sửa knowledge hay tự cấp phê duyệt cho mình; và không tuyên bố một kết quả đã vận
+hành khi còn một check bắt buộc vắng mặt hay hỏng, cũng không tuyên bố readiness sản phẩm, phê duyệt
+release hay bằng chứng UAT nào.
+
+## Context
+
+| Alias | Bind | Bắt buộc |
+| --- | --- | --- |
+| `@worktrees/sessions/central-runtime` | chủ sở hữu runtime dùng chung: inventory, generation và health, ràng theo fingerprint và generation, chỉ ghi dưới một lease độc quyền | có |
+| `@workspaces/ports/<project>` | phép chiếu cổng mà runtime ràng vào | có |
+| `@workspaces/device-state` | handle capability theo tên và custody của chúng; giá trị không bao giờ xuất hiện | có |
+| `@workspaces/projects/<project>/<role>` | những project mà các dịch vụ dùng chung phục vụ | không |
+
+## Đầu vào
+
+| Kind | Từ đâu | Bắt buộc |
+| --- | --- | --- |
+
+## Yêu cầu
+
+| Field | Kiểu | Mặc định | Hỏi |
+| --- | --- | --- | --- |
+| `service` | id | — | Đúng một dịch vụ dùng chung đang được vận hành |
+| `desiredState` | `{planSha256, serviceKind, resourceRefs, effects, mutableResourceRefs, observationOnlyResourceRefs}` | — | Khai báo đã duyệt: kế hoạch nào, nhánh nào, resource nào, effect nào, và cái gì được đổi so với cái gì chỉ được quan sát |
+| `portClaims` | list of `{port, resourceRef}` | [] | Trạng thái mong muốn cần những cổng nào, và cho resource sở hữu nào |
+| `approval` | id | — | Phê duyệt phủ lên trạng thái mong muốn này; đổi một runtime dùng chung luôn cần một con người |
+| `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 và resume | `resume` | `request/request.json`, @worktrees/sessions/central-runtime tại generation đã đóng băng | — | `INVALID_INPUT`, `SOURCE_DRIFT`, `NO_PROGRESS` |
+| 2 | Ràng thẩm quyền: runtime, device-state, projects và phê duyệt | `service`, `approval` | @worktrees/sessions/central-runtime cho fingerprint và generation của inventory, @workspaces/device-state cho từng handle capability kèm bằng chứng custody, @workspaces/projects/<project>/<role>, @tools/secrets | — | `AUTHORITY_DRIFT`, `CAPABILITY_MISSING` |
+| 3 | Kiểm lại inventory một lần trước khi có gì thay đổi | — | @worktrees/sessions/central-runtime, các resource đã khai được quan sát lại một lần, @tools/git | — | `INVENTORY_DRIFT` |
+| 4 | Phân giải các port claim | `portClaims` | @workspaces/ports/<project> cho các cổng được claim, @worktrees/sessions/central-runtime cho chủ giữ quan sát được của chúng | — | `PORT_CONFLICT` |
+| 5 | Suy ra delta giữa cái quan sát được và cái mong muốn | `desiredState` | @worktrees/sessions/central-runtime cho trạng thái quan sát được, `request/request.json` cho trạng thái mong muốn | `response/data/delta.json` | — |
+| 6 | Áp delta đã duyệt, từng resource một, dưới một lease độc quyền | — | @worktrees/sessions/central-runtime, @workspaces/device-state cho các handle theo tên | @worktrees/sessions/central-runtime, `response/data/delta.json`, @tools/container, @tools/shell | `EFFECT_UNAUTHORIZED`, `SERVICE_UNAVAILABLE` |
+| 7 | Chứng minh mọi check bắt buộc | — | @worktrees/sessions/central-runtime đọc lại theo bộ chứng minh đầy đủ của nhánh, @tools/http | `response/data/checks.json` | `PROOF_FAILED` |
+| 8 | Viết biên bản và phát | — | mọi thứ ở trên | `response/response.md`, `response/response.json` | — |
+
+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à tiêu thụ
+đúng phần delta; một lần resume không thêm thẩm quyền, inventory, trạng thái mong muốn hay phạm vi nào
+là `NO_PROGRESS`, và một inventory quan sát lại phải tới dưới dạng một fingerprint mới vì cùng một
+fingerprint không thể cho một câu trả lời khác.
+
+## Đầu ra
+
+| Kind | File | Kiểu | Bắt buộc |
+| --- | --- | --- | --- |
+| `platform-operation-receipt` | `response/response.md` | md | có |
+| `delta` | `response/data/delta.json` | data | có |
+| `checks` | `response/data/checks.json` | data | có |
+
+## Dừng
+
+| Code | Xử lý |
+| --- | --- |
+| `INVALID_INPUT` | terminate |
+| `SOURCE_DRIFT` | terminate |
+| `NO_PROGRESS` | terminate |
+| `AUTHORITY_DRIFT` | terminate |
+| `CAPABILITY_MISSING` | terminate |
+| `INVENTORY_DRIFT` | terminate |
+| `PORT_CONFLICT` | terminate |
+| `EFFECT_UNAUTHORIZED` | terminate |
+| `SERVICE_UNAVAILABLE` | terminate |
+| `PROOF_FAILED` | terminate |
+
+## Kế tiếp
+
+| Khi | Operator |
+| --- | --- |
+| checkout đã route hay head của nó không còn khớp ràng buộc đã đóng băng | `workspace.bind` |
+| runtime mà một bề mặt frontend phải được audit trên đó nay đã phục vụ | `frontend.surface.audit` |
+| dịch vụ dùng chung đã vận hành xong và release đang chờ nó có thể chạy tiếp | `release.deploy` |

package/operators/platform-operate/self-test.mjs

@@ -0,0 +1,202 @@
+// Proves validate.mjs on a synthetic session branch: one converged observability operation, one
+// already-converged no-op, one blocked on a port conflict, 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 { validatePlatformStep, KIND_CHECKS } from './validate.mjs';
+
+const PLAN = `sha256:${'0'.repeat(64)}`;
+const FP = `sha256:${'1'.repeat(64)}`;
+const SERVICE = 'prometheus/shared';
+const OWNER = 'platform-team';
+const APPROVAL = '@worktrees/debts/be.md#metrics-approval';
+const EFFECTS = ['update-config', 'update-remote-write'];
+const CAPABILITIES = [{ capability: 'metrics:remote-write', custodyEvidenceRef: 'custody/metrics.json' }];
+
+const resource = (ref = SERVICE, kind = 'observability', revision = 'r-14') => ({ resourceRef: ref, kind, revision, ownerRef: OWNER });
+const mutation = (effect, over = {}) => ({ effect, resourceRef: SERVICE, beforeRevision: 'r-14', afterRevision: 'r-15', ...over });
+const check = (name, status = 'passed') => ({ name, resourceRef: SERVICE, status, evidenceRef: `logs/${name}.txt` });
+const checkList = (names = KIND_CHECKS.observability, status = 'passed') => names.map((n) => check(n, status));
+
+function delta({
+  convergence = 'converged', mutations = EFFECTS.map((e) => mutation(e)), appliedEffects, allowedEffects = EFFECTS,
+  capabilities = CAPABILITIES, resources = [resource()], portHolders = [], portClaims = [], serviceKind = 'observability',
+  planSha256 = PLAN, approvalRef = APPROVAL, mutableResourceRefs = [SERVICE], serviceRef = SERVICE,
+} = {}) {
+  return {
+    serviceRef, serviceKind, ownerRef: OWNER, approvalRef, planSha256,
+    inventoryFingerprint: FP, generation: 7, observedAt: '2026-01-10T00:00:00.000Z',
+    inventoriedResources: resources, observedPortHolders: portHolders, portClaims,
+    mutableResourceRefs, observationOnlyResourceRefs: [],
+    allowedEffects, appliedEffects: appliedEffects ?? [...new Set(mutations.map((m) => m.effect))],
+    capabilities, convergence, mutations,
+  };
+}
+
+function checksJson({ serviceKind = 'observability', required = KIND_CHECKS.observability, list = checkList(), findings, serviceRef = SERVICE } = {}) {
+  return {
+    serviceRef, serviceKind, requiredCheckNames: required, checks: list,
+    findings: findings ?? [{ code: 'SHARED_SERVICE_INVENTORIED', resourceRef: SERVICE, port: null, holderRef: null, statement: 'the service was inventoried before anything changed' }],
+  };
+}
+
+function responseMd({ convergence = 'converged', mutations = EFFECTS.map((e) => mutation(e)), list = checkList(), findings = [['SHARED_SERVICE_INVENTORIED', SERVICE, '—', '—', 'the service was inventoried before anything changed']], service = SERVICE, kind = 'observability', plan = PLAN, approval = APPROVAL, resources = [resource()], portHolders = [] } = {}) {
+  return `# platform-operation-receipt — ${kind} ${service}
+
+The shared service was inventoried, the approved delta was applied, and the branch's complete proof
+set was proved on its own evidence.
+
+## Binding
+
+| Field | Value |
+| --- | --- |
+| Operator | \`platform.operate\` |
+| Step | \`step-1/parallel-1\` |
+| Project | \`starci-academy\` |
+| Service | ${service} |
+| Service kind | ${kind} |
+| Owner | \`${OWNER}\` |
+| Approval | ${approval} |
+| Desired state | \`${plan}\` |
+| Inventory fingerprint | \`${FP}\` |
+
+## Convergence
+
+| Field | Value |
+| --- | --- |
+| Convergence | ${convergence} |
+
+## Inventoried resources
+
+| Resource | Kind | Revision | Owner |
+| --- | --- | --- | --- |
+${resources.map((r) => `| \`${r.resourceRef}\` | ${r.kind} | ${r.revision} | \`${r.ownerRef}\` |`).join('\n')}
+
+## Port holders
+
+| Port | Holder | Evidence |
+| --- | --- | --- |
+${portHolders.map((h) => `| ${h.port} | \`${h.holderRef}\` | \`${h.evidenceRef}\` |`).join('\n')}
+
+## Mutations
+
+| Effect | Resource | Before | After |
+| --- | --- | --- | --- |
+${mutations.map((m) => `| \`${m.effect}\` | \`${m.resourceRef}\` | ${m.beforeRevision ?? '—'} | ${m.afterRevision} |`).join('\n')}
+
+## Checks
+
+| Check | Resource | Status | Evidence |
+| --- | --- | --- | --- |
+${list.map((c) => `| \`${c.name}\` | \`${c.resourceRef}\` | ${c.status} | \`${c.evidenceRef}\` |`).join('\n')}
+
+## Findings
+
+| Code | Resource | Port | Holder | Statement |
+| --- | --- | --- | --- | --- |
+${findings.map(([code, res, port, holder, statement]) => `| \`${code}\` | \`${res}\` | ${port} | ${holder} | ${statement} |`).join('\n')}
+`;
+}
+
+const requestJson = ({ kind = 'observability', effects = EFFECTS, resourceRefs = [SERVICE], mutableResourceRefs = [SERVICE], observationOnlyResourceRefs = [], portClaims = [], plan = PLAN, service = SERVICE, approval = APPROVAL, extra = {} } = {}) => ({
+  schemaVersion: 9, operatorId: 'platform.operate', step: 1, parallel: 1, sessionId: 's-test',
+  contexts: [{ alias: '@worktrees/sessions/central-runtime', head: null }],
+  requirements: {
+    service, approval, portClaims, resume: null,
+    desiredState: { planSha256: plan, serviceKind: kind, resourceRefs, effects, mutableResourceRefs, observationOnlyResourceRefs },
+    ...extra,
+  },
+  inputs: {}, resume: null,
+});
+
+const responseJson = ({ status = 'done', stop, next = ['release.deploy'] } = {}) => ({
+  schemaVersion: 9, operatorId: 'platform.operate', step: 1, parallel: 1, status, ...(stop ? { stop } : {}),
+  fallbacks: [],
+  fields: status === 'blocked' ? {} : { 'platform-operation-receipt': 'response/response.md', delta: 'response/data/delta.json', checks: 'response/data/checks.json' },
+  commits: [], next,
+});
+
+function writeBranch(files) {
+  const session = mkdtempSync(path.join(tmpdir(), 'platform-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': 'platform.operate' }, current: '1/1', status: 'running' }));
+  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/delta.json': delta(),
+  'response/data/checks.json': checksJson(),
+  ...over,
+});
+
+const alreadyConverged = () => baseline({
+  'request/request.json': requestJson({ effects: [] }),
+  'response/data/delta.json': delta({ convergence: 'already-converged', mutations: [] }),
+  'response/data/checks.json': checksJson({ findings: [{ code: 'ALREADY_CONVERGED', resourceRef: SERVICE, port: null, holderRef: null, statement: 'the service already matched the approved plan' }] }),
+  'response/response.md': responseMd({ convergence: 'already-converged', mutations: [], findings: [['ALREADY_CONVERGED', SERVICE, '—', '—', 'the service already matched the approved plan']] }),
+});
+
+async function expectValid(files, label) {
+  const { branch, session } = writeBranch(files);
+  const { errors } = await validatePlatformStep(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 validatePlatformStep(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 converged observability operation with the complete proof set');
+await expectValid(alreadyConverged(), 'an already-converged service as a proved no-op');
+await expectValid({
+  'request/request.json': requestJson(),
+  'response/response.json': responseJson({ status: 'blocked', stop: 'PORT_CONFLICT', next: [] }),
+  'response/response.md': null, 'response/data/delta.json': null, 'response/data/checks.json': null,
+}, 'blocked on a port conflict before anything changed');
+
+await expectError(baseline({ 'response/response.json': { ...responseJson(), stop: 'PROOF_FAILED' } }), 'only a blocked response carries a stop', 'done with a stop');
+await expectError(baseline({ 'response/response.json': responseJson({ status: 'blocked', stop: 'PORT_SEIZED', next: [] }) }), 'not a registered code', 'unknown stop code');
+await expectError(baseline({ 'request/request.json': requestJson({ extra: { credential: 'token: abcdefghijklmnop' } }) }), 'requirements.credential is not a field', 'a credential has nowhere to go in the request');
+await expectError(baseline({ 'request/request.json': requestJson({ approval: null }) }), 'required field approval has no value', 'a shared runtime change nobody approved');
+await expectError(baseline({ 'request/request.json': requestJson({ extra: { serviceKind: 'observability' } }) }), 'requirements.serviceKind is not a field', 'a field the operator no longer declares');
+await expectError(baseline({ 'request/request.json': requestJson({ effects: ['assign-gate'] }) }), 'does not belong to the observability service kind', 'a Sonar effect filed under observability');
+await expectError(baseline({ 'request/request.json': requestJson({ mutableResourceRefs: ['other/service'], resourceRefs: [SERVICE] }) }), 'must be inside desiredState.mutableResourceRefs', 'the service outside its own mutable ceiling');
+await expectError(baseline({ 'request/request.json': requestJson({ observationOnlyResourceRefs: [SERVICE] }) }), 'cannot be both mutable and observation-only', 'a resource in both scope sets');
+await expectError(baseline({ 'request/request.json': requestJson({ portClaims: [{ port: 9090, resourceRef: 'product/web' }] }) }), 'which this operation does not own', 'a port claimed for a foreign resource');
+await expectError(baseline({ 'request/request.json': requestJson({ portClaims: [{ port: 9090, resourceRef: SERVICE }, { port: 9090, resourceRef: SERVICE }] }) }), 'must not claim the same port twice', 'the same port claimed twice');
+await expectError(baseline({ 'response/data/delta.json': delta({ resources: [resource('other/service')] }) }), 'was not inventoried before the operation', 'the operated service never inventoried');
+await expectError(baseline({ 'response/data/delta.json': delta({ resources: [resource(SERVICE, 'sonar')] }) }), 'belongs to the sonar branch and is outside this observability operation', 'a resource from another branch');
+await expectError(baseline({ 'response/data/delta.json': delta({ planSha256: `sha256:${'9'.repeat(64)}` }) }), 'planSha256 must equal the approved plan hash', 'a plan hash nobody approved');
+await expectError(baseline({ 'response/data/delta.json': delta({ approvalRef: '@worktrees/debts/be.md#other' }) }), 'the bound approval is not the one the request declared', 'an approval borrowed from another plan');
+await expectError(baseline({ 'request/request.json': requestJson({ effects: ['update-config', 'restart-service'] }), 'response/data/delta.json': delta({ allowedEffects: EFFECTS }) }), 'is outside the approved effect set', 'an effect outside the approval');
+await expectError(baseline({ 'response/data/delta.json': delta({ capabilities: [] }) }), 'requires the metrics:remote-write capability', 'a branch running without its capability');
+await expectError(baseline({ 'response/data/checks.json': checksJson({ required: KIND_CHECKS.observability.slice(0, 3), list: checkList(KIND_CHECKS.observability.slice(0, 3)) }) }), 'must require the remote-write-delivery check', 'a narrowed proof set');
+await expectError(baseline({ 'response/data/checks.json': checksJson({ list: checkList(KIND_CHECKS.observability.slice(0, 6)) }), 'response/response.md': responseMd({ list: checkList(KIND_CHECKS.observability.slice(0, 6)) }) }), 'cannot be proved without the sensitive-data-filter check', 'an operated outcome missing a check');
+await expectError(baseline({ 'response/data/checks.json': checksJson({ list: checkList(KIND_CHECKS.observability, 'failed') }), 'response/response.md': responseMd({ list: checkList(KIND_CHECKS.observability, 'failed') }) }), 'so the operation cannot be reported as operated', 'an operated outcome over a failed check');
+await expectError(baseline({ 'response/data/delta.json': delta({ mutations: [mutation('update-config'), mutation('update-remote-write', { resourceRef: 'ghost/service' })] }) }), 'was mutated without being inventoried first', 'a mutation on a resource nobody inventoried');
+await expectError(baseline({ 'response/data/delta.json': delta({ portHolders: [{ port: 9090, holderRef: SERVICE, evidenceRef: 'ss.txt' }] }) }), 'holds a claimed port and must never be mutated to free it', 'a port freed by mutating its holder');
+await expectError(baseline({ 'response/data/delta.json': delta({ appliedEffects: [...EFFECTS, 'restart-service'] }) }), 'records no mutation', 'an applied effect with no mutation');
+await expectError(baseline({ 'response/data/delta.json': delta({ convergence: 'already-converged' }) }), 'already-converged operation cannot report a mutation', 'a no-op that mutated');
+await expectError(baseline({ 'response/data/delta.json': delta({ convergence: 'converged', mutations: [] }), 'response/response.md': responseMd({ mutations: [] }) }), 'converged operation must report the mutation that converged it', 'convergence with nothing applied');
+await expectError(baseline({ 'response/data/checks.json': checksJson({ findings: [{ code: 'PORT_COORDINATION_REQUIRED', resourceRef: SERVICE, port: 9090, holderRef: 'product/web', statement: 'the port is held elsewhere' }] }), 'response/response.md': responseMd({ findings: [['PORT_COORDINATION_REQUIRED', SERVICE, '9090', '`product/web`', 'the port is held elsewhere']] }) }), 'cannot end in an operated outcome', 'a port coordination finding on an operated receipt');
+await expectError(baseline({ 'response/data/checks.json': checksJson({ findings: [{ code: 'SHARED_SERVICE_INVENTORIED', resourceRef: 'ghost/service', port: null, holderRef: null, statement: 'x' }] }) }), 'names an uninventoried resource', 'a finding on a resource nobody inventoried');
+await expectError(baseline({ 'response/data/delta.json': delta({ capabilities: [{ capability: 'metrics:remote-write', custodyEvidenceRef: 'capability://metrics/remote-write' }] }) }), 'records a credential, which the receipt refuses', 'a capability handle inside the delta');
+await expectError(baseline({ 'response/response.md': responseMd({ service: 'other/service' }) }), 'Binding names a service the request did not operate', 'a receipt for another service');
+await expectError(baseline({ 'response/response.md': responseMd().replace('## Checks', '## Proofs') }), 'missing section ^## Checks$', 'receipt section renamed');
+await expectError(baseline({ 'response/data/delta.json': { ...delta(), inventoryFingerprint: 'nope' } }), 'inventoryFingerprint', 'delta schema');
+await expectError(baseline({ 'response/response.json': (() => { const o = responseJson(); delete o.fields.checks; return o; })() }), 'required output checks is not in fields', 'missing required output');
+
+process.stdout.write('platform.operate self-test: 3 valid branches, 28 rejected mutations\n');