@starci/skills 1.1.0

package/operators/workspace-bind/operator.md

@@ -0,0 +1,148 @@
+# workspace.bind
+
+## Job
+
+Resolve one project and role into a verified checkout identity, its exact source head, and the closed
+runtime binding it may consume, and return that as one typed route receipt.
+
+## Declaration is the only authority
+
+A route exists because a portable declaration in `@workspaces/projects/<project>/<role>` says so and a
+hydrated local route projects it onto this machine's disk. Four things routinely resemble a route and
+are none of it: a directory whose name matches the project, a sibling checkout that sits next to the
+Source, the current working directory, and the origin open in a browser. Those are hints, they carry
+no authority at all, and this operator has nowhere to put them: Requirements declares no hint field,
+so a request that carries one fails the gate with `INVALID_INPUT` at step 1 rather than being
+weighed. Refusing them at the gate is the point, because a hint that survives into the body of a run
+is a hint that gets followed the moment the declared route looks inconvenient. The two route halves
+must agree on project, role, Git repository, and branch; a `source` repository kind carries no
+directory and resolves to the Source root itself, a `sibling` kind carries a safe relative directory
+and resolves beside it, and a hydrated route that names another Source belongs to another machine and
+is refused.
+
+## Endpoint binding is a closed projection
+
+An endpoint is never a URL somebody chose. It is the `workspace-route-port-projection`: the verified
+frontend and backend routes, the project offset and slot step from `@workspaces/ports/<project>`, the
+application slot, and the routed backend's declared port services, folded into one fingerprint. The
+binding carries that fingerprint, and a stale one is refused rather than recomputed into agreement.
+Only origin-only `http://localhost:<canonical-port>` values are endpoints; a free URL, `127.0.0.1`, a
+remote host, an alternate application, an undeclared service, or a port that merely happens to be
+listening establishes nothing. Step 5 runs only when `runtimeNeed` is not `none`: a caller that binds
+no runtime binds no endpoints either, and a route that carries endpoints nobody asked for has
+consumed a shared resource on its own initiative.
+
+## The caller is a consumer, never an owner
+
+The shared local frontend, api, and identity processes belong to exactly one delegated owner task.
+This operator binds the caller to that owner's endpoints as a consumer. It does not start, stop,
+restart, replace, or kill a process, and it claims no port, no PID, and no runtime lifecycle. A
+registry that is missing, stale, or not ready yields a typed stop so the caller can raise one
+coordination request; it never authorises a replacement. An address already in use, an unexpected
+authenticated session, and a failing probe are all evidence to report, and none of them is permission.
+
+## Nothing is repaired here
+
+No credential is read, copied, or recorded; only the sealed roster reference is bound, and
+`IDENTITY_ROSTER_SEALED` states that. A declaration that does not exist is repaired by the workspace
+owner, never by this operator, so `ROUTE_UNDECLARED` and `ROUTE_UNHYDRATED` are expected outcomes of
+an unprepared workspace rather than defects in the request. `CHECKOUT_DIRTY` never falls back to
+anything: this operator does not stash, clean, or reset a working tree to make a binding possible.
+The businesses authority root is derived as `<git root>/.worktrees/businesses` when that worktree
+exists on a source checkout and is absent otherwise; it is never accepted from the person, because a
+typed authority root is how a second business tree is born. Provenance and freshness are not a step
+of their own: they are written inside the emit, next to the binding they describe.
+
+## Boundary
+
+Context is read-only apart from the machine-local hydrated route state, which Git ignores. The
+operator writes only `response/` of its own branch: `response.md`, `response/data/route.json` and
+`response.json`. It never accepts a similar name, a sibling directory, the working directory, or a
+browser URL as route authority, never accepts a chosen URL, a loopback alias, or a merely listening
+port as an endpoint, never starts, stops, restarts, replaces, or kills a shared runtime process, never
+claims a port, a PID, or a runtime lifecycle for a feature task, never creates or switches to a task,
+feature, or worktree branch under a forbidden worktree policy, never writes a credential, token,
+cookie, or password into the receipt or any evidence, and never repairs a missing route, initializes a
+workspace, or provisions an account. It makes no product decision and carries no verdict.
+
+## Context
+
+| Alias | Bind | Required |
+| --- | --- | --- |
+| `@workspaces/projects/<project>/<role>` | the portable route declaration, read by fingerprint; the only route authority | yes |
+| `@workspaces/local/routes/<project>/<role>` | the hydrated route this machine projects the declaration onto, and the checkout it resolves to | yes |
+| `@workspaces/device-state` | machine identity and the sealed credential roster, bound by name and never read | yes |
+| `@workspaces/ports/<project>` | the port projection, read only when the caller consumes the runtime | no |
+| `@worktrees/sessions/central-runtime` | the runtime owner registry, its generation and health evidence, bound only when the caller consumes | no |
+
+## Inputs
+
+| Kind | From | Required |
+| --- | --- | --- |
+| — | this operator opens the chain, so it consumes no earlier branch | no |
+
+## Requirements
+
+| Field | Type | Default | Ask |
+| --- | --- | --- | --- |
+| `project` | id | — | The project to bind |
+| `role` | choice | — | `fe` or `be`: the role of that project to bind |
+| `gitPolicy` | list of `{worktreeBranches, mutationBranch}` | the policy the route declaration carries | The branch law this binding is verified against; `forbidden` keeps every write on the mutation branch |
+| `declaredWriteRoots` | list | empty | The only paths later work may write; anything dirty outside them is `CHECKOUT_DIRTY` |
+| `runtimeNeed` | choice | none | `none` binds no runtime and skips step 5; `consume` binds the owner's endpoints as a consumer |
+| `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, and refuse every hint it carries | `resume` | `request/request.json`, its requirements and its frozen head | — | `INVALID_INPUT`, `SOURCE_DRIFT`, `NO_PROGRESS` |
+| 2 | Bind bootstrap and identity | — | @workspaces/device-state, the machine identity and the sealed credential roster, @tools/secrets | — | `IDENTITY_UNVERIFIED` |
+| 3 | Resolve the route | `project`, `role` | @workspaces/projects/<project>/<role> for exactly this project and role, @workspaces/local/routes/<project>/<role>, @tools/git | — | `ROUTE_UNDECLARED`, `ROUTE_UNHYDRATED`, `ROUTE_MISMATCH` |
+| 4 | Verify the checkout: branch policy, a clean tree, and the write roots | `gitPolicy`, `declaredWriteRoots` | @workspaces/local/routes/<project>/<role>, the resolved checkout, its branch, its head and its working tree, @tools/git, @tools/shell | — | `BRANCH_POLICY_VIOLATION`, `CHECKOUT_DIRTY` |
+| 5 | Bind the runtime the caller consumes, only when `runtimeNeed` is not none | `runtimeNeed` | @worktrees/sessions/central-runtime, the owner registry, its generation and health evidence, @workspaces/ports/<project>, @tools/http | — | `ENDPOINT_AUTHORITY_STALE`, `RUNTIME_NOT_READY` |
+| 6 | Bind provenance and freshness, then emit | — | everything above, @workspaces/device-state | `response/response.md`, `response/data/route.json`, `response/response.json` | — |
+
+Step 5 recomputes nothing: the endpoint fingerprint either matches the closed projection or the
+branch stops. Under `worktreeBranches` set to forbidden, a route binds only on the mutation branch and
+records `WORKTREE_BRANCH_FORBIDDEN`; under `session-only` it binds on the mutation branch or on a
+`session/<sessionId>` worktree branch, the only shape a source-writing operator may commit to; a redacted conversation head records `PROVENANCE_HEAD_BOUND`, and
+a cached receipt matching the same identity tuple and fingerprints records `CACHED_ROUTE_REUSED`. A
+resume begins again at step 1, reuses only unchanged fingerprinted observations, and consumes the
+exact delta; a republished route arrives as a new route fingerprint, because the same fingerprint
+cannot yield a different binding.
+
+## Outputs
+
+| Kind | File | Type | Required |
+| --- | --- | --- | --- |
+| `workspace-route-binding` | `response/response.md` | md | yes |
+| `route` | `response/data/route.json` | data | yes |
+
+## Stops
+
+| Code | Disposition |
+| --- | --- |
+| `INVALID_INPUT` | terminate |
+| `SOURCE_DRIFT` | terminate |
+| `NO_PROGRESS` | terminate |
+| `IDENTITY_UNVERIFIED` | terminate |
+| `ROUTE_UNDECLARED` | terminate |
+| `ROUTE_UNHYDRATED` | terminate |
+| `ROUTE_MISMATCH` | terminate |
+| `BRANCH_POLICY_VIOLATION` | terminate |
+| `CHECKOUT_DIRTY` | terminate |
+| `ENDPOINT_AUTHORITY_STALE` | terminate |
+| `RUNTIME_NOT_READY` | terminate |
+
+## Next
+
+| When | Operator |
+| --- | --- |
+| the route is bound and the checkout carries a publication to push | `git.publish` |
+| the route is bound and a promise must be decided against its source | `business.decide` |
+| the route is bound and a backend contract must be filled inside it | `backend.source.apply` |
+| the route is bound and a frontend surface must be written inside it | `frontend.source.apply` |
+| the runtime owner is missing or not ready and one coordination request must be raised | `platform.operate` |
+| the route is bound and a frontend surface must be decided inside it | `frontend.direction.decide` |
+| the route is bound and a published head must be verified before it ships | `quality.verify` |

package/operators/workspace-bind/operator.vi.md

@@ -0,0 +1,148 @@
+# workspace.bind
+
+## Việc
+
+Phân giải một project và một role thành định danh checkout đã kiểm, head source chính xác của nó, và
+ràng buộc runtime đóng mà nó được tiêu thụ, rồi trả về thành một biên nhận route có kiểu.
+
+## Khai báo là thẩm quyền duy nhất
+
+Một route tồn tại vì một khai báo portable trong `@workspaces/projects/<project>/<role>` nói vậy, và
+một route local đã hydrate chiếu nó xuống ổ đĩa của máy này. Bốn thứ thường trông giống route mà
+không phải: một thư mục trùng tên project, một checkout anh em nằm cạnh Source, thư mục làm việc hiện
+tại, và origin đang mở trong trình duyệt. Chúng là hint, không mang chút thẩm quyền nào, và operator
+này không có chỗ nào để chứa: bảng Yêu cầu không khai field hint nào, nên một request mang hint sẽ
+trượt gate với `INVALID_INPUT` ở bước 1 thay vì được cân nhắc. Từ chối ngay ở gate mới là điểm mấu
+chốt, vì một hint sống sót vào thân của lượt chạy là một hint sẽ được nghe theo ngay khi route đã
+khai trông bất tiện. Hai nửa của route phải khớp nhau về project, role, kho Git và nhánh; kiểu kho
+`source` không mang thư mục và phân giải về chính gốc Source, kiểu `sibling` mang một thư mục tương
+đối an toàn và phân giải bên cạnh nó, còn một route đã hydrate nêu tên một Source khác là của máy
+khác và bị từ chối.
+
+## Ràng endpoint là một phép chiếu đóng
+
+Một endpoint không bao giờ là URL ai đó chọn. Nó là `workspace-route-port-projection`: route frontend
+và backend đã kiểm, offset project và bước slot lấy từ `@workspaces/ports/<project>`, slot ứng dụng,
+và các port service đã khai của backend được route, gộp thành một fingerprint. Binding mang đúng
+fingerprint ấy, và một fingerprint cũ bị từ chối chứ không được tính lại cho khớp. Chỉ giá trị
+`http://localhost:<port chuẩn>` dạng chỉ-origin mới là endpoint; một URL tự do, `127.0.0.1`, một host
+từ xa, một ứng dụng khác, một service không khai, hay một port tình cờ đang lắng nghe đều không thiết
+lập gì cả. Bước 5 chỉ chạy khi `runtimeNeed` khác `none`: người gọi không ràng runtime thì cũng không
+ràng endpoint, và một route mang endpoint không ai xin là một route đã tiêu thụ tài nguyên chung theo
+ý riêng.
+
+## Người gọi là người tiêu thụ, không bao giờ là chủ
+
+Các tiến trình frontend, api và identity local dùng chung thuộc về đúng một task chủ được uỷ quyền.
+Operator này ràng người gọi vào endpoint của chủ ấy với vai người tiêu thụ. Nó không khởi động, dừng,
+khởi động lại, thay thế hay giết một tiến trình, và không đòi port, PID hay vòng đời runtime nào. Một
+registry thiếu, cũ hay chưa sẵn sàng sinh ra một mã dừng có kiểu để người gọi nêu một yêu cầu phối
+hợp; nó không bao giờ cho phép thay thế. Một địa chỉ đang bị chiếm, một phiên đã đăng nhập bất ngờ,
+và một probe hỏng đều là bằng chứng để báo cáo, và không cái nào là sự cho phép.
+
+## Không sửa chữa gì ở đây
+
+Không credential nào được đọc, chép hay ghi lại; chỉ tham chiếu roster đã niêm phong được ràng, và
+`IDENTITY_ROSTER_SEALED` nói đúng điều đó. Một khai báo không tồn tại thì do chủ workspace sửa, không
+bao giờ do operator này, nên `ROUTE_UNDECLARED` và `ROUTE_UNHYDRATED` là kết cục dự kiến của một
+workspace chưa chuẩn bị chứ không phải lỗi của request. `CHECKOUT_DIRTY` không bao giờ có fallback:
+operator này không stash, không clean, không reset cây làm việc để một binding trở nên khả thi. Gốc
+thẩm quyền businesses được suy ra là `<gốc git>/.worktrees/businesses` khi worktree ấy tồn tại trên
+một checkout source và vắng mặt nếu không; nó không bao giờ được nhận từ người, vì một gốc thẩm quyền
+do người gõ vào chính là cách cây business thứ hai ra đời. Provenance và độ tươi không phải một bước
+riêng: chúng được ghi ngay trong bước phát, cạnh binding mà chúng mô tả.
+
+## Ranh giới
+
+Context chỉ đọc, trừ trạng thái route đã hydrate cục bộ của máy, thứ mà Git bỏ qua. Operator chỉ ghi
+`response/` của nhánh mình: `response.md`, `response/data/route.json` và `response.json`. Nó không bao
+giờ nhận một cái tên na ná, một thư mục anh em, thư mục làm việc hay một URL trình duyệt làm thẩm
+quyền route, không bao giờ nhận một URL tự chọn, một bí danh loopback hay một port chỉ đang lắng nghe
+làm endpoint, không bao giờ khởi động, dừng, khởi động lại, thay thế hay giết một tiến trình runtime
+dùng chung, không bao giờ đòi port, PID hay vòng đời runtime cho một task feature, không bao giờ tạo
+hay chuyển sang nhánh task, feature hay worktree dưới một chính sách worktree cấm, không bao giờ ghi
+credential, token, cookie hay mật khẩu vào biên nhận hay bất kỳ bằng chứng nào, và không bao giờ sửa
+một route thiếu, khởi tạo một workspace hay cấp phát một tài khoản. Nó không ra quyết định sản phẩm
+và không mang phán quyết nào.
+
+## Context
+
+| Alias | Bind | Bắt buộc |
+| --- | --- | --- |
+| `@workspaces/projects/<project>/<role>` | khai báo route portable, đọc theo fingerprint; thẩm quyền route duy nhất | có |
+| `@workspaces/local/routes/<project>/<role>` | route đã hydrate mà máy này chiếu khai báo xuống, và checkout nó phân giải ra | có |
+| `@workspaces/device-state` | định danh máy và roster credential đã niêm phong, ràng theo tên và không bao giờ đọc | có |
+| `@workspaces/ports/<project>` | phép chiếu port, chỉ đọc khi người gọi tiêu thụ runtime | không |
+| `@worktrees/sessions/central-runtime` | registry chủ runtime, generation và bằng chứng sức khoẻ của nó, chỉ ràng khi người gọi tiêu thụ | không |
+
+## Đầu vào
+
+| Kind | Từ đâu | Bắt buộc |
+| --- | --- | --- |
+| — | operator này mở chuỗi, nên nó không tiêu thụ nhánh nào trước đó | không |
+
+## Yêu cầu
+
+| Field | Kiểu | Mặc định | Hỏi |
+| --- | --- | --- | --- |
+| `project` | id | — | Project cần ràng |
+| `role` | choice | — | `fe` hay `be`: vai của project ấy cần ràng |
+| `gitPolicy` | list `{worktreeBranches, mutationBranch}` | the policy the route declaration carries | Luật nhánh mà binding này được kiểm theo; `forbidden` giữ mọi lần ghi trên nhánh mutation |
+| `declaredWriteRoots` | list | empty | Những đường dẫn duy nhất mà việc sau được ghi; bẩn ngoài chúng là `CHECKOUT_DIRTY` |
+| `runtimeNeed` | choice | none | `none` không ràng runtime và bỏ qua bước 5; `consume` ràng endpoint của chủ với vai tiêu thụ |
+| `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 gate và chạy lại, và từ chối mọi hint nó mang | `resume` | `request/request.json`, phần requirements và head đóng băng của nó | — | `INVALID_INPUT`, `SOURCE_DRIFT`, `NO_PROGRESS` |
+| 2 | Ràng bootstrap và identity | — | @workspaces/device-state, định danh máy và roster credential đã niêm phong, @tools/secrets | — | `IDENTITY_UNVERIFIED` |
+| 3 | Phân giải route | `project`, `role` | @workspaces/projects/<project>/<role> đúng project và role này, @workspaces/local/routes/<project>/<role>, @tools/git | — | `ROUTE_UNDECLARED`, `ROUTE_UNHYDRATED`, `ROUTE_MISMATCH` |
+| 4 | Kiểm checkout: chính sách nhánh, cây sạch và các write root | `gitPolicy`, `declaredWriteRoots` | @workspaces/local/routes/<project>/<role>, checkout đã phân giải, nhánh, head và cây làm việc của nó, @tools/git, @tools/shell | — | `BRANCH_POLICY_VIOLATION`, `CHECKOUT_DIRTY` |
+| 5 | Ràng runtime mà người gọi tiêu thụ, chỉ khi `runtimeNeed` khác none | `runtimeNeed` | @worktrees/sessions/central-runtime, registry chủ, generation và bằng chứng sức khoẻ của nó, @workspaces/ports/<project>, @tools/http | — | `ENDPOINT_AUTHORITY_STALE`, `RUNTIME_NOT_READY` |
+| 6 | Ràng provenance và độ tươi, rồi phát | — | mọi thứ ở trên, @workspaces/device-state | `response/response.md`, `response/data/route.json`, `response/response.json` | — |
+
+Bước 5 không tính lại gì cả: fingerprint endpoint hoặc khớp phép chiếu đóng, hoặc nhánh dừng. Dưới
+`worktreeBranches` đặt là forbidden, một route chỉ ràng trên nhánh mutation và ghi
+`WORKTREE_BRANCH_FORBIDDEN`; một head hội thoại đã che ghi `PROVENANCE_HEAD_BOUND`, và một biên nhận Đặt là `session-only` thì route ràng trên nhánh mutation hoặc trên nhánh worktree
+`session/<sessionId>`, hình dạng duy nhất mà operator ghi source được commit lên;
+cache khớp cùng bộ định danh và fingerprint ghi `CACHED_ROUTE_REUSED`. Chạy lại thì bắt đầu lại từ
+bước 1, chỉ dùng lại quan sát có fingerprint không đổi, và tiêu thụ đúng phần delta; một route
+publish lại tới dưới dạng một fingerprint route mới, vì cùng một fingerprint không thể cho một ràng
+buộc khác.
+
+## Đầu ra
+
+| Kind | File | Kiểu | Bắt buộc |
+| --- | --- | --- | --- |
+| `workspace-route-binding` | `response/response.md` | md | có |
+| `route` | `response/data/route.json` | data | có |
+
+## Dừng
+
+| Code | Xử lý |
+| --- | --- |
+| `INVALID_INPUT` | terminate |
+| `SOURCE_DRIFT` | terminate |
+| `NO_PROGRESS` | terminate |
+| `IDENTITY_UNVERIFIED` | terminate |
+| `ROUTE_UNDECLARED` | terminate |
+| `ROUTE_UNHYDRATED` | terminate |
+| `ROUTE_MISMATCH` | terminate |
+| `BRANCH_POLICY_VIOLATION` | terminate |
+| `CHECKOUT_DIRTY` | terminate |
+| `ENDPOINT_AUTHORITY_STALE` | terminate |
+| `RUNTIME_NOT_READY` | terminate |
+
+## Kế tiếp
+
+| Khi | Operator |
+| --- | --- |
+| route đã ràng và checkout mang một bản publish cần đẩy | `git.publish` |
+| route đã ràng và một lời hứa phải được quyết dựa trên source của nó | `business.decide` |
+| route đã ràng và một contract backend phải được điền bên trong nó | `backend.source.apply` |
+| route đã ràng và một bề mặt frontend phải được viết bên trong nó | `frontend.source.apply` |
+| chủ runtime thiếu hoặc chưa sẵn sàng và cần nêu một yêu cầu phối hợp | `platform.operate` |
+| route đã ràng và một bề mặt frontend phải được quyết bên trong nó | `frontend.direction.decide` |
+| route đã ràng và một head đã publish phải được kiểm trước khi lên | `quality.verify` |

package/operators/workspace-bind/self-test.mjs

@@ -0,0 +1,205 @@
+// Proves validate.mjs on a synthetic session branch: one conforming bind of a source checkout with no
+// runtime, one bind that consumes the shared runtime, one branch blocked on a terminate code, 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 { validateWorkspaceStep } from './validate.mjs';
+
+const head = 'd'.repeat(40);
+const fp = (c) => `sha256:${c.repeat(64)}`;
+const SOURCE = 'D:/Repositories/starci-academy-backend';
+const PORTABLE = '.workspaces/projects/starci-academy/be.json';
+const HYDRATED = '.workspaces/local/routes/starci-academy/be/config.json';
+const OWNER = 'task-runtime-owner-1';
+
+const runtimeConsumption = (overrides = {}) => ({
+  ownerTaskId: OWNER,
+  generation: 3,
+  status: 'ready',
+  consumerRole: 'consumer',
+  endpointBinding: {
+    authority: 'workspace-route-port-projection',
+    project: 'starci-academy',
+    application: 'academy',
+    services: { frontend: 'web', api: 'api', identity: 'keycloak' },
+    authorityFingerprint: fp('b'),
+  },
+  endpoints: { frontend: 'http://localhost:3000', api: 'http://localhost:3001', identity: 'http://localhost:8089' },
+  ...overrides,
+});
+function routeBinding(overrides = {}) {
+  return {
+    project: 'starci-academy', role: 'be',
+    portableRouteRef: PORTABLE, hydratedRouteRef: HYDRATED,
+    routeFingerprint: fp('a'), identityFingerprint: fp('c'), sourceHead: head,
+    checkout: { diskPath: SOURCE, gitRoot: SOURCE, gitRepository: 'git@github.com:starci/academy-backend.git', branch: 'mtp', repositoryKind: 'source', directory: null, sourceHead: head },
+    gitPolicy: { worktreeBranches: 'forbidden', mutationBranch: 'mtp' },
+    mutationReadiness: 'ready',
+    writeRoots: ['src', 'test'],
+    authorityRoots: { businesses: `${SOURCE}/.worktrees/businesses` },
+    runtime: null,
+    provenanceHeadRef: null,
+    ...overrides,
+  };
+}
+
+function responseMd({ binding = routeBinding(), findings = null, runtimeRows = null } = {}) {
+  const defaultFindings = [
+    ['ROUTE_HYDRATED_FROM_PORTABLE', binding.hydratedRouteRef, 'the portable declaration resolved to this local route'],
+    ['IDENTITY_ROSTER_SEALED', 'the credential roster reference', 'the roster was bound by name and never read'],
+    ...(binding.gitPolicy.worktreeBranches === 'forbidden' ? [['WORKTREE_BRANCH_FORBIDDEN', binding.gitPolicy.mutationBranch, 'the routed policy forbids task and worktree branches']] : []),
+    ...(binding.provenanceHeadRef ? [['PROVENANCE_HEAD_BOUND', binding.provenanceHeadRef, 'a redacted conversation head was attached']] : []),
+    ...(binding.runtime ? [['RUNTIME_CONSUMED_NOT_OWNED', binding.runtime.ownerTaskId, 'the caller consumes the owner endpoints and owns no lifecycle']] : []),
+  ];
+  const rows = (findings ?? defaultFindings).map(([code, subject, statement]) => `| \`${code}\` | ${subject} | ${statement} |`).join('\n');
+  const runtime = runtimeRows ?? (binding.runtime
+    ? [['Owner task', binding.runtime.ownerTaskId], ['Status', binding.runtime.status], ['Consumer role', binding.runtime.consumerRole], ['Frontend', binding.runtime.endpoints.frontend], ['Api', binding.runtime.endpoints.api], ['Identity', binding.runtime.endpoints.identity]]
+    : []);
+  const runtimeTable = runtime.map(([k, v]) => `| ${k} | ${v} |`).join('\n');
+  const writeRootRows = binding.writeRoots.map((p) => `| ${p} | the only paths later work may write |`).join('\n');
+  return `# workspace-route-binding — ${binding.project}/${binding.role}
+
+The routed backend checkout of this project, bound at the frozen head with its declared write roots.
+
+## Binding
+
+| Field | Value |
+| --- | --- |
+| Project | ${binding.project} |
+| Role | ${binding.role} |
+| Portable route | ${binding.portableRouteRef} |
+| Hydrated route | ${binding.hydratedRouteRef} |
+| Source head | ${binding.sourceHead} |
+
+## Checkout
+
+| Field | Value |
+| --- | --- |
+| Disk path | ${binding.checkout.diskPath} |
+| Git root | ${binding.checkout.gitRoot} |
+| Git repository | ${binding.checkout.gitRepository} |
+| Branch | ${binding.checkout.branch} |
+| Repository kind | ${binding.checkout.repositoryKind} |
+| Directory | ${binding.checkout.directory ?? '—'} |
+| Source head | ${binding.checkout.sourceHead} |
+| Mutation readiness | ${binding.mutationReadiness} |
+| Businesses root | ${binding.authorityRoots.businesses ?? '—'} |
+
+## Policy
+
+| Field | Value |
+| --- | --- |
+| Worktree branches | ${binding.gitPolicy.worktreeBranches} |
+| Mutation branch | ${binding.gitPolicy.mutationBranch} |
+
+## Write roots
+
+| Path | Why |
+| --- | --- |
+${writeRootRows}
+
+## Runtime
+
+| Field | Value |
+| --- | --- |
+${runtimeTable}${runtimeTable ? '\n' : ''}
+## Findings
+
+| Code | Subject | Statement |
+| --- | --- | --- |
+${rows}
+`;
+}
+
+const requestJson = ({ runtimeNeed = 'none', extra = {} } = {}) => ({
+  schemaVersion: 9, operatorId: 'workspace.bind', step: 1, parallel: 1, sessionId: 's-test',
+  contexts: [{ alias: '@workspaces/projects/starci-academy/be', head: null }, { alias: '@workspaces/local/routes/starci-academy/be', head }, { alias: '@workspaces/device-state', head: null }],
+  requirements: { project: 'starci-academy', role: 'be', gitPolicy: { worktreeBranches: 'forbidden', mutationBranch: 'mtp' }, declaredWriteRoots: ['src', 'test'], runtimeNeed, resume: null, ...extra },
+  inputs: {}, resume: null,
+});
+function responseJson({ status = 'done', stop, fallbacks = [], fields = null, next = [] } = {}) {
+  return {
+    schemaVersion: 9, operatorId: 'workspace.bind', step: 1, parallel: 1, status, ...(stop ? { stop } : {}), fallbacks,
+    fields: fields ?? { 'workspace-route-binding': 'response/response.md', route: 'response/data/route.json' },
+    commits: [], next,
+  };
+}
+
+function writeBranch(files) {
+  const session = mkdtempSync(path.join(tmpdir(), 'workspace-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': 'workspace.bind' }, 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 = () => ({
+  'request/request.json': requestJson(),
+  'response/response.json': responseJson(),
+  'response/response.md': responseMd(),
+  'response/data/route.json': routeBinding(),
+});
+const withBinding = (binding, requestOverrides = {}) => ({
+  ...baseline(),
+  'request/request.json': requestJson(requestOverrides),
+  'response/data/route.json': binding,
+  'response/response.md': responseMd({ binding }),
+});
+
+async function expectValid(files, label) {
+  const { branch, session } = writeBranch(files);
+  const { errors } = await validateWorkspaceStep(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 validateWorkspaceStep(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)'}`);
+}
+
+const consuming = () => withBinding(routeBinding({ runtime: runtimeConsumption() }), { runtimeNeed: 'consume' });
+
+await expectValid(baseline(), 'a source checkout bound with no runtime');
+await expectValid(consuming(), 'a bind that consumes the shared runtime');
+await expectValid({ ...baseline(), 'response/response.json': responseJson({ status: 'blocked', stop: 'ROUTE_UNDECLARED', fields: {} }), 'response/response.md': null, 'response/data/route.json': null }, 'blocked on an undeclared route');
+
+await expectError({ ...baseline(), 'response/response.json': { ...responseJson(), stop: 'ROUTE_UNDECLARED' } }, 'only a blocked response carries a stop', 'done with a stop');
+await expectError({ ...baseline(), 'response/response.json': responseJson({ status: 'blocked', stop: 'MADE_UP_CODE', fields: {} }), 'response/response.md': null, 'response/data/route.json': null }, 'not a registered code', 'unknown stop code');
+await expectError({ ...baseline(), 'response/response.json': responseJson({ fallbacks: ['CHECKOUT_DIRTY'] }) }, 'has disposition terminate under these requirements; it cannot be taken as a fallback', 'fallback on a terminate code');
+await expectError({ ...baseline(), 'response/response.json': responseJson({ status: 'blocked', stop: 'ROUTE_MISMATCH' }) }, 'a blocked branch cannot carry a route', 'blocked while binding a route');
+await expectError({ ...baseline(), 'request/request.json': requestJson({ extra: { mystery: 1 } }) }, 'requirements.mystery is not a field', 'undeclared requirement');
+await expectError({ ...baseline(), 'request/request.json': requestJson({ extra: { project: '' } }) }, 'required field project has no value', 'missing required project');
+await expectError(withBinding(routeBinding({ checkout: { ...routeBinding().checkout, directory: 'academy' } })), 'a source checkout must report a null directory', 'a source checkout carrying a directory');
+await expectError(withBinding(routeBinding({ checkout: { ...routeBinding().checkout, repositoryKind: 'sibling' } })), 'a sibling checkout carries no business authority root', 'a sibling checkout claiming business authority');
+await expectError(withBinding(routeBinding({ authorityRoots: { businesses: '.worktrees/businesses' } })), 'must be derived from the checkout as', 'a typed businesses root');
+await expectError(withBinding(routeBinding({ checkout: { ...routeBinding().checkout, branch: 'feature/x' } })), 'a forbidden worktree policy cannot bind a route on another branch', 'a forbidden policy on a task branch');
+await expectError(withBinding(routeBinding({ gitPolicy: { worktreeBranches: 'allowed', mutationBranch: 'mtp' }, checkout: { ...routeBinding().checkout, branch: 'feature/x' } }), { extra: { gitPolicy: { worktreeBranches: 'allowed', mutationBranch: 'mtp' } } }), 'mutation is ready only on mtp, not on feature/x', 'mutation ready off the mutation branch');
+await expectError(withBinding(routeBinding({ checkout: { ...routeBinding().checkout, gitRoot: `${SOURCE}/api` } })), 'the checkout disk path and Git root must be the same checkout', 'the checkout and its Git root disagree');
+await expectError(withBinding(routeBinding({ sourceHead: 'e'.repeat(40) })), 'must name the same source head', 'the binding and the checkout disagree on the head');
+await expectError({ ...baseline(), 'request/request.json': requestJson({ runtimeNeed: 'consume' }) }, 'must bind the runtime owner', 'consuming with no runtime bound');
+await expectError(withBinding(routeBinding({ writeRoots: ['src'] })), 'which the binding does not carry', 'a declared write root the binding drops');
+await expectError(withBinding(routeBinding({ runtime: runtimeConsumption() })), 'runtimeNeed is none, so step 5 never ran and no runtime may be bound', 'a runtime bound without need');
+await expectError(withBinding(routeBinding({ runtime: runtimeConsumption({ status: 'starting' }) }), { runtimeNeed: 'consume' }), 'cannot bind a starting runtime owner for consumption', 'a runtime that is not ready');
+await expectError(withBinding(routeBinding({ runtime: runtimeConsumption({ endpoints: { frontend: 'http://127.0.0.1:3000', api: 'http://localhost:3001', identity: 'http://localhost:8089' } }) }), { runtimeNeed: 'consume' }), 'is not an origin-only localhost projection', 'a loopback alias as an endpoint');
+await expectError(withBinding(routeBinding({ runtime: runtimeConsumption({ endpoints: { frontend: 'http://localhost:3000', api: 'http://localhost:3000', identity: 'http://localhost:8089' } }) }), { runtimeNeed: 'consume' }), 'must resolve to distinct ports', 'two services on one port');
+await expectError(withBinding(routeBinding({ runtime: runtimeConsumption({ endpointBinding: { ...runtimeConsumption().endpointBinding, services: { frontend: 'web', api: 'web', identity: 'keycloak' } } }) }), { runtimeNeed: 'consume' }), 'service keys must be distinct', 'two services under one key');
+await expectError(withBinding(routeBinding({ runtime: runtimeConsumption({ endpointBinding: { ...runtimeConsumption().endpointBinding, project: 'other-project' } }) }), { runtimeNeed: 'consume' }), 'belongs to another project than the bound route', 'an endpoint binding from another project');
+await expectError({ ...consuming(), 'response/response.md': responseMd({ binding: routeBinding({ runtime: runtimeConsumption() }), findings: [['ROUTE_HYDRATED_FROM_PORTABLE', HYDRATED, 'resolved'], ['IDENTITY_ROSTER_SEALED', 'roster', 'sealed'], ['WORKTREE_BRANCH_FORBIDDEN', 'mtp', 'forbidden']] }) }, 'must record that the caller does not own it', 'a consumed runtime with no ownership finding');
+await expectError({ ...baseline(), 'response/response.md': responseMd({ findings: [['IDENTITY_ROSTER_SEALED', 'roster', 'sealed'], ['WORKTREE_BRANCH_FORBIDDEN', 'mtp', 'forbidden']] }) }, 'must record the hydrated route it resolved from', 'a bound route with no hydration finding');
+await expectError({ ...baseline(), 'response/response.md': responseMd({ findings: [['ROUTE_HYDRATED_FROM_PORTABLE', HYDRATED, 'resolved'], ['IDENTITY_ROSTER_SEALED', 'roster', 'sealed'], ['WORKTREE_BRANCH_FORBIDDEN', 'mtp', 'forbidden'], ['HINT_REJECTED', 'D:/Repositories/starci-academy', 'a similar directory name']] }) }, 'a hint is INVALID_INPUT at the gate', 'a receipt that weighs a hint');
+await expectError({ ...baseline(), 'response/response.md': responseMd({ findings: [['ROUTE_HYDRATED_FROM_PORTABLE', HYDRATED, 'resolved'], ['WORKTREE_BRANCH_FORBIDDEN', 'mtp', 'forbidden']] }) }, 'the credential roster was sealed and never read', 'no sealed roster finding');
+await expectError({ ...baseline(), 'response/response.md': responseMd({ findings: [['ROUTE_HYDRATED_FROM_PORTABLE', HYDRATED, 'resolved'], ['IDENTITY_ROSTER_SEALED', 'roster', 'sealed']] }) }, 'a forbidden worktree policy must be recorded', 'a forbidden policy that was never recorded');
+await expectError({ ...baseline(), 'response/response.md': responseMd({ findings: [['ROUTE_HYDRATED_FROM_PORTABLE', HYDRATED, 'resolved'], ['ROUTE_HYDRATED_FROM_PORTABLE', HYDRATED, 'resolved again'], ['IDENTITY_ROSTER_SEALED', 'roster', 'sealed'], ['WORKTREE_BRANCH_FORBIDDEN', 'mtp', 'forbidden']] }) }, 'repeats subject', 'a repeated finding subject');
+await expectError({ ...baseline(), 'response/response.md': responseMd().replace('## Policy', '## Git policy') }, 'missing section ^## Policy$', 'response section renamed');
+await expectError({ ...baseline(), 'response/response.md': responseMd().replace('| Branch | mtp |', '| Branch | feature/x |') }, 'differs from the route binding', 'the receipt and the binding disagree on the branch');
+await expectError({ ...baseline(), 'response/data/route.json': routeBinding({ sourceHead: 'not-a-head' }) }, 'sourceHead', 'route schema');
+await expectError({ ...baseline(), 'response/response.json': (() => { const o = responseJson(); delete o.fields.route; return o; })() }, 'required output route is not in fields', 'missing required output');
+
+process.stdout.write('workspace.bind self-test: 3 valid branches, 29 rejected mutations\n');