@astrale-domains/services 0.4.7 → 0.4.8

package/README.md

@@ -30,7 +30,7 @@ protocols behind neutral SDK Integrations and stores only admitted lifecycle evi
   same Mutation: the Kernel deletes a Node only together with every incident Edge. Its lines stay
   registered with no holder and are refused to every organisation. A transfer is a root
   `createEdge` of `line_owned_by` from the line to the new organisation; a line has one holder at
-  most.
+  most ([Transfer a line](#transfer-a-line)).
 - secret values stay write-only at Cloudflare and never enter Astrale mutations or graph state.
 - schedules remain provider state; only the owner may read or replace them.
 - logs are remote evidence admitted by the Cloudflare Provider before a Workflow returns them.
@@ -123,7 +123,7 @@ the routing KV are shared. Any other Kernel finds hosting unavailable before any
 Only a runtime whose Environment vars set `SERVICES_DEPLOYMENT_HOST` (the deployments' routing
 domain) hosts deployments; every other runtime answers `hosting-unavailable`. Such a runtime refuses
 to boot without `SERVICES_DEPLOYMENT_KERNEL` (the Admin Kernel's issuer URL),
-`SERVICES_SECRET_DIGEST_KEY` (at least 32 characters, kept for the life of the environment: the
+`SERVICES_SECRET_DIGEST_KEY` (at least 32 UTF-8 bytes, kept for the life of the data plane: the
 recorded digests depend on it), the `SERVICE_DEPLOYMENTS` dispatch binding to the environment's
 deployments namespace, and `CLOUDFLARE_SCHEDULE_KV_ID`, the routing KV that activates a label, and
 refuses a `SERVICES_PLATFORM_OWNER` that is not an Identity id. Hosting is declared once, by the
@@ -189,7 +189,8 @@ release digest at the same URL. A `withdrawn` tombstone is never removed.
 `SERVICES_REGISTRY_ORIGIN` and `SERVICES_PREVIEW_EXPIRY` (`plan`, the default, or `enforce`) are
 Environment vars of a hosting runtime, refused in a secrets file and refused without
 `SERVICES_DEPLOYMENT_HOST`. Without a registry origin no caller is the registry, and `retain` and
-`expirePreviews` are refused. `admin-beta` names `admin.astrale.ai` and keeps expiry a plan.
+`expirePreviews` are refused. `admin` and the frozen `admin-beta` name `admin.astrale.ai` and keep
+expiry a plan.
 Reading last calls needs the API token's Account Analytics Read permission. `pnpm
 provider:deployment-audit` lists the deployments namespace read-only
 ([operator](providers/cloudflare/operator/README.md)).
@@ -206,6 +207,246 @@ applies `OwnService` to each one. Workflow addresses are `CloudflareWorker.*`; a
 keys are not executable. A future provider Class must supply its own concrete declarations and
 implementations. Properties and ownership relationships retain their inherited meaning.
 
+## Operating hosted deployments
+
+### Recorded choices
+
+The deployment model left four choices open (decisions D12, D13 and D16 of the deployment and
+versioning spec, and the rule for deployment secrets). Services implements them as follows.
+
+| Choice | Implemented here |
+| --- | --- |
+| How a line reads in a deployment URL | Only the platform organisation (`SERVICES_PLATFORM_OWNER`) registers or deploys readable lines, which read `<readable>-<fingerprint>`, such as `agencies-staging-svkrguuhpcvmxxas`. Every other line is its 16-character fingerprint alone, derived from the origin and environment, never a stored UUID. A line keeps the addressing it was registered with, whoever holds it later: a deploy with the other addressing is refused `address-mismatch`, and a readable deploy for any other organisation `invalid-deployment`. |
+| Which deployment runs a Domain's crons | None. A hosted deployment's frozen configuration has no trigger, a Workers for Platforms script cannot own one, and the dispatcher's minute fan-out reads only the `cron:` keys of Services, which no deployment has. The spec's recommendation, crons on the deployment of the version the author designates (by default the highest stable one), needs the registry and is not implemented by the foundation. |
+| Where deployments live | In the Admin instance's Services, on a line held by the publisher's organisation, outside every instance that installs them. Uninstalling a Domain, deleting an instance or deleting its Services never touches them. The organisation is an Identity of the Admin instance that the deploy request names; a request that names none deploys for the caller itself. |
+| Deployment secrets | A deploy binds the environment's current secrets to the new deployment only; every other deployment keeps its own. A secret rotates in place on one deployment, which keeps its script, URL, issuer and key: by `setSecret`, or by deploying the identical release again. The signing key never rotates. |
+
+### Rotate a deployment's secrets
+
+Rotating a secret never creates a deployment. Two calls write a new value in place on one
+deployment, and on no other:
+
+- deploying the identical release again (same build and configuration) with the new value in the
+  environment's secrets: it is the same label, `deploy` answers `reused`, and its `secrets.state` is
+  `updated` when a value changed;
+- `setSecret` on the deployment, for one name its frozen configuration declares.
+
+A deployment is called by the `id` that `list` returns. Every call below runs on the Admin instance
+(`--admin`, or `--admin=<bookmark>`), as an identity that acts for the organisation holding the line
+(`--as <identity>` when it is not the bookmark's default), with an `astrale` CLI whose `call` takes
+`--admin` and `-d @file`. Put `key=value` params before `--admin`.
+
+```sh
+astrale call /:services.astrale.ai:class.CloudflareDeployment:list \
+  origin=agencies.example.com environment=staging --admin --json
+```
+
+`list` answers `{ "deployments": [...] }` with each deployment's `id`, `label`, `url`, `state` and
+declared `record`.
+
+Never pass a secret value in argv, where `ps` and shell history keep it. Write the input to a file
+that only you can read (`umask 077`, then your editor), outside the repository:
+
+```json
+{ "name": "API_TOKEN", "value": "<the new value>" }
+```
+
+```sh
+astrale call "@$ID::services.astrale.ai:class.CloudflareDeployment.method.setSecret" \
+  --admin -d @rotate.json --json
+```
+
+or pipe it from your secret manager on stdin (`read-new-secret` stands for the command that prints
+only the new value):
+
+```sh
+read-new-secret | jq -Rs '{ name: "API_TOKEN", value: rtrimstr("\n") }' \
+  | astrale call "@$ID::services.astrale.ai:class.CloudflareDeployment.method.setSecret" \
+      --admin -d - --json
+```
+
+`secrets` lists the names a deployment binds, never a value:
+
+```sh
+astrale call "@$ID::services.astrale.ai:class.CloudflareDeployment.method.secrets" --admin --json
+```
+
+A refusal is the call's value (`"kind": "rejected"`); the two errors fail the call.
+
+| Reply | Meaning | Then |
+| --- | --- | --- |
+| `{ "name": "API_TOKEN" }` | The value is written, or was already the one served. Propagation is eventually consistent: the provider serves a new value about 4 s later. | Nothing. Calls in those seconds may still see the old value. |
+| `secret-undeclared` | The deployment's frozen configuration binds no such name. Nothing was written. | A new name is a new release: declare it and deploy. |
+| `service-unavailable` with `retryAfter` | The deployment is being created, another operation holds it, or the provider failed. | The same call again after `retryAfter`. A rerun converges, whatever an interrupted one wrote. |
+| `service-unavailable` without `retryAfter` | The deployment cannot be rotated in place: its creation failed, it is retiring or retired, or the script under its label is not the recorded one. `message` says which. | Deploy the release again after a failed creation. A retired deployment serves nothing. Ask the Services operator about a script that is not the recorded one. |
+| `DEPLOYMENT_NOT_FOUND` | The caller neither holds the deployment's line nor acts for its holder. Nothing was read. | Call as an identity of the organisation holding the line. |
+| `DEPLOYMENT_HOSTING_UNAVAILABLE` | The call reached a Kernel other than the Admin instance's, or the Services runtime there hosts no deployments (its Environment sets no `SERVICES_DEPLOYMENT_HOST`). | Call with `--admin`. If the Admin instance still answers it, ask the Services operator. |
+
+### A leaked secret
+
+A deploy never rewrites another deployment's secrets, so a leaked value stays bound to every
+deployment that still serves it until each one is rotated:
+
+1. Put the new value everywhere a deploy reads the environment's secrets from: the secrets file the
+   environment's adapter names (its `secrets` option, such as `.env.staging`) and every CI secret
+   store that deploys the environment. From then on, until step 5, no deploy may run with the old
+   value: an identical redeploy with it would write it back in place (`secrets.state: updated`).
+2. Rotate every deployment of that origin and environment that serves, with the input file above.
+   `list` shows a deployment only once it has served: a deployment still being created, or whose
+   creation failed, is not listed. The block reads the list on each run, so run it again until
+   every reply is `{ "name": ... }`. A deployment already rotated answers the same without writing
+   anything, and one that answered `service-unavailable` with `retryAfter` takes the rotation on a
+   later run.
+
+   ```sh
+   for ID in $(astrale call /:services.astrale.ai:class.CloudflareDeployment:list \
+     origin=agencies.example.com environment=staging --admin --json \
+     | jq -r '.deployments[] | select(.state == "active") | .id'); do
+     astrale call "@$ID::services.astrale.ai:class.CloudflareDeployment.method.setSecret" \
+       --admin -d @rotate.json --json
+   done
+   ```
+
+   An identical redeploy rotates only the deployment of the current release; older ones need
+   `setSecret`. Only `active` deployments rotate in place: a retiring or retired one answers
+   `service-unavailable` without `retryAfter`, so revoking the value at its source (step 5) is what
+   covers it. A deployment still being created, or whose creation failed, is step 3's.
+3. Take over every creation that a deploy started before step 1: that deploy may have read the old
+   value. Its deployment stays `deploying`, or `failed`, until a deploy records it active, so `list`
+   does not show it and `setSecret` refuses it; yet it serves as soon as its deploy has published
+   its record. Lease expiry alone does not stop that deploy. Activation checks only that the
+   deployment still holds the lease the deploy took, so a deploy that stalls past its lease, which
+   ends 10 minutes after it started, can still activate the deployment with the old value until
+   another deploy takes it over.
+
+   Find these deployments on the Admin instance (`ADMIN_INSTANCE` is its instance bookmark, as in
+   [Transfer a line](#transfer-a-line)). The query answers the deployments of the lines you hold or
+   act for, those still being created included. Keep the `label` of each one whose `state` is
+   `deploying` or `failed` and whose `record` names this origin and environment. When the answer
+   has a `page.next`, the same query with `--cursor <page.next>` reads the next page.
+
+   ```sh
+   astrale query --class /:services.astrale.ai:class.CloudflareDeployment --limit 100 --json \
+     -i "$ADMIN_INSTANCE"
+   ```
+
+   For each label, deploy its release again, identical (the same build and configuration; with
+   adapter-astrale, `astrale-domain deploy <environment>` from the same source), now that the
+   secrets file holds the new value. Repeat until it answers `deployed` for that label:
+   - while the stalled deploy's lease runs, it answers `service-unavailable` with `retryAfter`, the
+     end of that lease: deploy again then;
+   - once the lease has expired, it takes the deployment over, so the stalled deploy can no longer
+     activate it, and creates it with the current secrets, rewriting them on any script the stalled
+     deploy left;
+   - after a failed creation it retries with the current secrets; once the stalled deploy has
+     activated the deployment, it reuses it and rewrites its secrets in place
+     (`secrets.state: updated`).
+
+   A release that does not rebuild identically has another label and takes nothing over: the
+   stalled deployment keeps the value its deploy wrote until step 5 revokes it. Then run step 2's
+   block once more.
+4. Deployments in the platform dispatch namespace have no Services node, and neither `list` nor the
+   query shows them. They are the platform Domains deployed through adapter-cloudflare's namespace
+   mode: Shell, the Services runtime, Issues, ai-gateway, closing, grc, integrations and ui, each
+   once it has moved there. Rotate each one in place with the platform namespace's tooling, with
+   its operator file sourced
+   ([operator README](./providers/cloudflare/operator/README.md#operating-platform-deployments)): one
+   label and one declared name per run, the value read on stdin from a file that holds only the new
+   value, outside the repository and readable only by you.
+
+   ```sh
+   pnpm provider:platform-secret -- --label <label> --name API_TOKEN < new-value
+   ```
+
+   Or deploy its identical release again. A platform deploy that started before step 1 may have
+   read the old value too: once it has returned, rotate the deployment it made or reused. Admin is
+   not one of them: it runs on its own bootstrap Worker, and its secrets rotate through that
+   Worker's own deploy tooling. The Services runtime is one of them once the Admin instance runs on
+   a deployment of [`admin`](#admin-hosted-runtime); its identical redeploy is
+   `pnpm run deploy admin`, with the new value in `.env.admin`. Until that move it is the frozen
+   `admin-beta` Worker: put the new value in `.env.admin-beta` (and the same in `.env.admin`, which
+   keeps its values) and deploy it again with `pnpm run deploy admin-beta`, from the commit it was
+   last deployed from so that only its secrets change.
+5. Revoke the leaked value where it was issued once step 2's block answered `{ "name": ... }` for
+   every deployment and every redeploy of step 3 answered `deployed`, or at once when the leak
+   outweighs the failures of deployments not rotated yet.
+6. Delete `rotate.json` and `new-value`.
+
+### Transfer a line
+
+A line belongs to the first organisation that deploys on it. No Services Method moves it: an
+operator transfers it as the Admin instance's root, with one Mutation on its `line_owned_by` Edge.
+Its deployments stay on the line and keep serving. From that Mutation on, the new holder lists,
+rotates and deploys them, and the previous holder and its members no longer see them.
+
+1. Find the line and its holder on the Admin instance (`ADMIN_INSTANCE` is its bookmark,
+   `ADMIN_ROOT` its root identity, `LINE` the line's id):
+
+   ```sh
+   astrale query --class /:services.astrale.ai:class.DeploymentLine --limit 100 --json \
+     -i "$ADMIN_INSTANCE" --as "$ADMIN_ROOT"
+   astrale query "@$LINE" --edge /:services.astrale.ai:class.line_owned_by \
+     --direction outgoing --json -i "$ADMIN_INSTANCE" --as "$ADMIN_ROOT"
+   ```
+
+   Pick the line whose `origin` and `environment` are the ones to transfer. The first query reads
+   one page: when its answer has a `page.next`, more lines exist, and the same query with
+   `--cursor <page.next>` reads the next page.
+
+2. Write the Mutation. A held line moves in one atomic Mutation that deletes the current holder's
+   Edge and creates the new one; if the current holder is not the one named, nothing moves:
+
+   ```json
+   {
+     "preconditions": [],
+     "operations": [
+       {
+         "op": "edge.delete",
+         "edge": {
+           "class": "services.astrale.ai:class.line_owned_by",
+           "source": "@<line-id>",
+           "target": "@<current-holder-id>"
+         }
+       },
+       {
+         "op": "edge.create",
+         "class": "services.astrale.ai:class.line_owned_by",
+         "source": "@<line-id>",
+         "target": "@<new-organization-id>",
+         "props": {}
+       }
+     ]
+   }
+   ```
+
+   A line without a holder, after its organisation was deleted, takes the `edge.create` operation
+   alone. The Kernel refuses a second holder, so that form never moves a held line.
+
+3. Check the document offline, then apply it:
+
+   ```sh
+   astrale mutate --file transfer.json --dry
+   astrale mutate --file transfer.json -i "$ADMIN_INSTANCE" --as "$ADMIN_ROOT"
+   ```
+
+A readable line stays readable: give it only to the platform organisation, since any other one is
+refused on it. Changing `SERVICES_PLATFORM_OWNER` therefore means transferring every readable line
+to the new platform organisation. Deleting an organisation that holds lines leaves them without a
+holder (see [Model](#model)): their deployments keep serving, and nobody can list, rotate or deploy
+them until they are transferred.
+
+### Orphans
+
+A hosted deployment belongs to its line, never to the instances that install it: deleting or
+retiring an instance leaves it alone, and the orphan audit and reclaim of the
+[operator README](./providers/cloudflare/operator/README.md) never select it. What can be left over:
+
+| Situation | What holds | Then |
+| --- | --- | --- |
+| A deploy interrupted before activation | The graph keeps the deployment `deploying` under its lease, or `failed`, and `list` does not show it. An uploaded script serves nothing until its deploy publishes its record; one interrupted after that serves while the graph still says `deploying` or `failed`. Until another deploy takes it over, the interrupted deploy can still activate it, even after its lease expired. | Deploy the same release again. It resumes on the same label, takes over an expired lease, and adopts the uploaded script only if its tags name the same artifact, line, key and Admin Kernel, rewriting its secrets with the environment's current ones. |
+| A line whose organisation was deleted | No organisation holds it; every deploy on it is refused `line-owned-elsewhere`. Its deployments keep serving, and nobody can rotate them. | Transfer the line. |
+| A script under a label that is not the recorded one | `deploy` answers `deployment-conflict` and `setSecret` `service-unavailable` without `retryAfter`; nothing is written to it. | The operator compares its `astrale-artifact:`, `astrale-line:`, `astrale-key:` and `astrale-install:` tags with the deployment's record and key. |
+
 ## Shared public ingress
 
 New Services use the environment's proxied wildcard DNS, wildcard Worker route and wildcard
@@ -257,15 +498,15 @@ data.
 
 ## Admin-hosted runtime
 
-The `admin-beta` Environment is the Services runtime of the Admin instance, the one that hosts
-publishers' deployments outside the instances that install them. It is a Worker of its own,
-`services-domain-admin-beta` at `https://services-admin.beta.astrale.ai`, on the beta data plane the
-Admin instance's Services already manage. Its plain vars name the router Worker
-(`ASTRALE_ROUTER_WORKER`), the routing domain under which deployments are addressed
+The Admin-hosted runtime is the Services runtime of the Admin instance, the one that hosts
+publishers' deployments outside the instances that install them. Only the Admin instance installs
+it; consumer instances keep the Services they pin. It runs on the beta data plane the Admin
+instance's Services already manage. Its plain vars name the router Worker
+(`ASTRALE_ROUTER_WORKER`), the routing domain under which hosted deployments are addressed
 (`SERVICES_DEPLOYMENT_HOST`, served by the Services dispatcher), the Admin instance's Kernel, the
 only one it hosts deployments for (`SERVICES_DEPLOYMENT_KERNEL`, `https://admin.eu.beta.astrale.ai/api`),
 and the registry Domain (`SERVICES_REGISTRY_ORIGIN`). These vars are the only declaration of
-hosting: they also bind `SERVICE_DEPLOYMENTS`. `.env.admin-beta` must set
+hosting: they also bind `SERVICE_DEPLOYMENTS`. Its secrets file must set
 `SERVICES_SECRET_DIGEST_KEY`, the key of each hosted deployment's secret digest, and the dispatch
 namespace and routing KV the runtime boots with. The runtime keys HMAC-SHA256 with the UTF-8 bytes
 of the digest key as written, never base64-decoded, so the configuration refuses, before any
@@ -274,38 +515,56 @@ sets a hosting var. `SERVICES_PLATFORM_OWNER` is not set yet: until it names the
 organisation's Identity id on the Admin instance, every line is opaque and a readable deploy is
 refused.
 
-It retains the issuer `https://services.beta.astrale.ai` and its signing key, as services-v2 does.
-The Admin instance's Services are bound to that issuer, and the Kernel refuses an issuer change when
-it replaces an installed Domain (`issuer-changed`); neither the Admin Host's Kernel nor the CLI
-offers a consented issuer change yet. The cost: a Worker built from main holds the key that 1Pact's
-installations trust. Keep the key only in managed secret storage and in this Worker's
-`ASTRALE_SIGNING_IDENTITY` secret. The Admin instance moves to an issuer of its own when the
-canonical Admin-hosted runtime replaces this one through a consented issuer change; this Worker and
-its copy of the key are retired after that reinstall.
-
-Only the Admin instance installs this runtime; consumer instances keep the Services they pin.
-The operator sets it up once:
+Two Environments deploy it:
+
+- **`admin`**, the canonical one. Every `pnpm run deploy admin` makes one immutable deployment of
+  the release in the platform dispatch namespace (`astrale-platform`), on the readable line
+  `services-admin-6ze5tudscrzgbrbv`, at `https://<label>.platform.astrale.ai`. The deployment is
+  its own issuer, signs with a key generated for it, and binds its candidate namespace
+  (`SERVICE_CANDIDATES`) and the deployments namespace (`SERVICE_DEPLOYMENTS`) at its create-only
+  upload, both derived from `CLOUDFLARE_DISPATCH_NAMESPACE`. Nothing is ever replaced in place: a
+  new release is a new URL, which the Admin instance moves to by a consented install. Redeploying
+  the same release reuses its deployment and rewrites only that deployment's secrets in place. Its
+  secrets file is `.env.admin`.
+- **`admin-beta`**, frozen (`providers/cloudflare/operator/provision/legacy/admin-beta.ts`). It is
+  a Worker of its own, `services-domain-admin-beta` at `https://services-admin.beta.astrale.ai`,
+  that retains the issuer `https://services.beta.astrale.ai` and its signing key, as services-v2
+  does, so the Admin instance installs it without an issuer change (OPS-3). The cost: a Worker built
+  from main holds the key that 1Pact's installations trust. Keep the key only in managed secret
+  storage and in this Worker's `ASTRALE_SIGNING_IDENTITY` secret. It changes only for a same-Schema
+  fix the Admin instance needs before it moves; everything else goes to `admin`. It is deleted from
+  this repository by D19, once the Admin instance runs on `admin` and OPS-6 retired the Worker.
+
+### Set up the frozen admin-beta runtime (OPS-3)
+
+The operator sets it up once, from a commit of `main` that carries the Services CT16 adoption
+(`bindings.dispatchNamespaces` and `settings.durableOptions` in the deployment configuration, with
+the tenant refusal) and pins an SDK release that carries the CT16 extension (R6a' or later). An
+admin-beta built without that adoption refuses every deploy of an adapter-astrale that carries it
+with `1003 FUNCTION_INPUT_INVALID`, and the move to `admin` over the deployments such a runtime wrote
+is refused with `4001 DATA_MIGRATION_REQUIRED` (see [OPS-5](#move-the-admin-instance-to-admin-ops-5)).
 
 1. Read what the Admin instance's Services are bound to, read-only:
    `astrale introspect services.astrale.ai -i <admin-instance> --json`. Record `revision` and
    `publication.identity.issuer`, and the frozen runtime whose `/.well-known/astrale/domain.json`
    declares that revision: it is the rollback URL. Go on only if the issuer is
-   `https://services.beta.astrale.ai`; any other issuer makes step 6 an issuer change, which the
-   Kernel refuses. Check as well that the Admin instance's Kernel issuer is admin-beta's
-   `SERVICES_DEPLOYMENT_KERNEL`; otherwise every deploy answers `hosting-unavailable`. Before the
-   first readable deploy, read the platform organisation's Identity id there and set it as
-   admin-beta's `SERVICES_PLATFORM_OWNER` var in a reviewed change to `astrale.config.ts`.
+   `https://services.beta.astrale.ai`; any other issuer makes step 6 an issuer change, which this
+   runtime does not take (use the [move to `admin`](#move-the-admin-instance-to-admin-ops-5)
+   instead). Check as well that the Admin instance's Kernel issuer is the
+   `SERVICES_DEPLOYMENT_KERNEL` var; otherwise every deploy answers `hosting-unavailable`. Before
+   the first readable deploy, read the platform organisation's Identity id there and set it as the
+   `SERVICES_PLATFORM_OWNER` var in a reviewed change.
 2. Create `.env.admin-beta` (mode 600) from `.env.example` with the beta data-plane coordinates the
    Admin instance's Services manage today (account, token, dispatch namespace, routing domain
    `svc.eu.beta.astrale.ai`, schedule KV, dispatcher, zone, Admin target) and a new
-   `SERVICES_SECRET_DIGEST_KEY` that no other environment uses, e.g. `openssl rand -base64 32` (32
-   random bytes, kept as their 44-character base64 text).
+   `SERVICES_SECRET_DIGEST_KEY` that no other data plane uses, e.g. `openssl rand -base64 32` (32
+   random bytes, kept as their 44-character base64 text; the configuration refuses fewer than 32
+   UTF-8 bytes). It is generated once here, copied unchanged into `.env.admin` at OPS-5, and never
+   regenerated: the recorded secret digests of every hosted deployment depend on it.
 3. Restore the retained `https://services.beta.astrale.ai` signing identity, the one services-v2 was
    deployed with, from managed secret storage to `.astrale/services-beta-identity.json` (mode 600).
    Never generate a key for this runtime: the frozen R1 Worker publishes the issuer's keys, so a new
-   key would never verify. Never leave that key at `.astrale/identity.json`, the development
-   Environment's default identity: `pnpm dev` would bind it to development Workers. Check that the
-   issuer publishes the restored key:
+   key would never verify. Check that the issuer publishes the restored key:
 
    ```sh
    node --input-type=module -e '
@@ -329,14 +588,149 @@ The operator sets it up once:
    The install must succeed and the Service must stay manageable (list, secrets, logs). Then install
    the step 1 rollback URL there again: if the Kernel refuses it, step 6 is one-way, and that must be
    recorded before step 6 runs.
-6. Install on the Admin instance only, directly:
-   `astrale domain install https://services-admin.beta.astrale.ai --direct --allow-identity-override -i <admin-instance>`.
+6. Install on the Admin instance only:
+   `astrale domain install https://services-admin.beta.astrale.ai --allow-identity-override -i <admin-instance>`.
    The only consent is the identity override, because the origin `services.astrale.ai` differs from
    the serving host; the issuer does not change. On any refusal, stop: never uninstall Services on
    the Admin instance to get around it, which would drop the Service records it holds. Never repoint
    Admin's catalog entry for `services.astrale.ai` at this runtime: consumer flows, 1Pact's among
    them, install Services by origin through that entry.
 
+### Move the Admin instance to admin (OPS-5)
+
+OPS-5 is the production operation that moves the Admin instance's Services off the frozen
+`admin-beta` Worker onto a deployment of `admin`. Before acting, write a compatibility record and
+know the rollback path. Afterwards, verify the Admin instance and add an entry to the operations
+log. 1Pact's instances and every consumer instance are out of scope: they keep the Services they
+pin, and nothing here touches them.
+
+Preconditions:
+
+1. The Admin instance installs `admin-beta` (OPS-3), built with the Services CT16 adoption; its
+   rollback URL is `https://services-admin.beta.astrale.ai`.
+2. The Admin instance's Host runs a Kernel that lists installed releases and takes issuer consent
+   (astrale-os/kernel#1124, in a released Host image, OPS-4). An older Kernel refuses
+   `--allow-issuer-change` before any install, so the move waits.
+3. The operator's `astrale` CLI is a release with install by URL (astrale-os/cli#582) and issuer
+   consent (astrale-os/cli#583).
+4. This package pins an SDK release whose adapter-cloudflare deploys namespace mode with dispatch
+   namespace bindings and durable options (astrale-os/sdk#599, on the CT16 extension of
+   astrale-os/sdk#587), and the publishers' adapter-astrale passes `dispatchNamespaces: []`
+   (astrale-os/sdk#598).
+5. The platform namespace is provisioned (`pnpm provider:platform-bootstrap`, OPS-1) and the deploy
+   token may manage scripts in it.
+
+Steps:
+
+0. **Schema.** A move, and a rollback, is a Schema upgrade: the Kernel checks the data the Admin
+   instance stores against the Schema of the URL it installs. Read the installed `revision`
+   (`astrale introspect services.astrale.ai -i <admin-instance> --json`, as recorded at OPS-3
+   step 1) and, after step 2, the deployment's `schema.revision` in `services-admin.json`. Equal
+   revisions are the same Schema. Different revisions make the move a Schema upgrade: list what
+   changed in `services/schema/` between the OPS-3 commit and this one, and let the rehearsal
+   (step 3) decide. When admin-beta and `admin` are built from commits whose Services Schema is
+   the same (both with the CT16 adoption), only the compiled form can differ.
+1. **Secrets.** Create `.env.admin` (mode 600) as a copy of `.env.admin-beta`. The values must be
+   the same, the `SERVICES_SECRET_DIGEST_KEY` above all: the new deployment manages the same hosted
+   deployments, in the same dispatch namespace and routing KV, and their recorded secret digests
+   depend on that key. No signing identity file: the deploy generates the deployment's key.
+2. **Deploy.** From a clean checkout of `main`, with `CLOUDFLARE_ACCOUNT_ID` and
+   `CLOUDFLARE_API_TOKEN` of the platform account set, run
+   `pnpm run deploy admin --json > services-admin.json` (no `--`: pnpm passes it on literally and
+   `astrale-domain` refuses it as an unknown flag). Check that
+   `<url>/.well-known/astrale/release.json` serves the printed release digest and that
+   `<url>/.well-known/astrale/deployment.json` serves its record.
+3. **Rehearse** on a disposable instance whose Host runs the Admin Host's Kernel release, whose
+   Services pin `admin-beta`, with at least one Service and one hosted deployment: move it (step 4),
+   verify it (step 5), roll it back ([Rollback](#rollback-ops-5)) and move it forward again.
+4. **Move** the Admin instance:
+
+   ```sh
+   astrale domain install "$(jq -r .url services-admin.json)" \
+     --allow-issuer-change=services.astrale.ai -i <admin-instance> --json
+   ```
+
+   - The frozen Worker's issuer and the deployment's are not on one line, so consent names the
+     origin: a bare `--allow-issuer-change` covers only a new deployment of the same line, and the
+     install is refused without the origin.
+   - The replaced issuer keeps working while its in-flight work drains. Do not pass
+     `--revoke-previous`.
+   - If the Kernel refuses an installed dependent of Services, install Services together with a
+     compatible deployment of that dependent in one grouped command
+     (`astrale domain install <services-url> <dependent-url> …`); a refusal installs nothing.
+   - If the Kernel answers `4001 DATA_MIGRATION_REQUIRED` ("Schema change requires an explicit
+     data migration."), data the Admin instance stores does not fit the deployment's Schema, and
+     `reason.details.requirements` names each Class (an admin-beta built without the CT16 adoption
+     names `CloudflareDeployment` and `deployment_on_line`). The whole operation is refused: the
+     pin does not move, nothing activates and no data changes, although the deployment did receive
+     the install request. The Admin instance stays on admin-beta, which keeps answering. Fix
+     forward with an `admin` release whose Schema admits the stored data; this repository has no
+     data migration. `SCHEMA_UPGRADE_INCOMPATIBLE` (4002) and `SCHEMA_DEPENDENTS_INCOMPATIBLE`
+     have the same remedy.
+   - On any other refusal, stop. Never uninstall Services on the Admin instance.
+5. **Verify**, with reads only, then one hosted deploy:
+   - `astrale introspect services.astrale.ai -i <admin-instance> --json` names the new release,
+     pinned exactly, with the deployment URL as issuer;
+   - `astrale call /:services.astrale.ai:class.CloudflareDeployment:hosting -i <admin-instance> --json`
+     answers the hosting of `svc.eu.beta.astrale.ai`;
+   - the Services View lists the Admin instance's Services and their secrets names;
+   - a publisher's `astrale-domain deploy <environment>` of a Domain with the astrale adapter into
+     the Admin instance still makes, or reuses, its hosted deployment.
+6. **Point bootstrap discovery at the deployment.** Admin's bootstrap discovery for `services`
+   moves to this deployment's `release.json` (A11), and Admin is redeployed (OPS-7). Never repoint
+   Admin's catalog entry for `services.astrale.ai`: consumer flows install Services by origin
+   through it.
+
+A later release moves the same way: deploy `admin`, then install its URL, with the step 0 Schema
+check. Its issuer is another deployment URL on the same line, which the bare `--allow-issuer-change`
+covers by the consent rule (CT24); the host proof does not exercise that case, so pass
+`--allow-issuer-change=services.astrale.ai` if the CLI asks for the origin.
+
+#### Rollback (OPS-5)
+
+Reinstall the frozen Worker with consent. It still serves, because only OPS-6 retires it:
+
+```sh
+astrale domain install https://services-admin.beta.astrale.ai \
+  --allow-issuer-change=services.astrale.ai --allow-identity-override -i <admin-instance> --json
+```
+
+It serves only the legacy `domain.json`, and the origin it declares differs from its host, so the
+identity override applies as well. The Admin instance's Services records stay in its Kernel through
+a move and a rollback, and a rollback is a Schema upgrade too: it is admitted only while
+admin-beta's Schema admits the data written since the move. Once it does not, the Kernel refuses
+as in step 4 and the deployment stays installed; the remedy is then a new `admin` deployment that
+fixes forward, never a redeploy of admin-beta. If step 6 already repointed bootstrap discovery,
+repoint it back too.
+
+### Retire admin-beta (OPS-6)
+
+Once the Admin instance runs on `admin` and no installation on any Host pins
+`https://services-admin.beta.astrale.ai` (`astrale introspect services.astrale.ai` on each instance
+that installs Services), retire the `services-domain-admin-beta` Worker and its route
+`services-admin.beta.astrale.ai`, and delete its `ASTRALE_SIGNING_IDENTITY` secret, its copy of the
+services.beta key. Keep the issuer host `services.beta.astrale.ai` and the key itself: the frozen
+R1 and services-v2 Workers that 1Pact pins still sign with them. Then D19 deletes the frozen
+`admin-beta` Environment from this repository.
+
+### Before publishers deploy
+
+The Admin instance's graph is the registry of lines. Before the first publisher deploys:
+
+1. This runtime is installed on the Admin instance only, as above; that instance's Kernel issuer is
+   `SERVICES_DEPLOYMENT_KERNEL`; and `SERVICES_PLATFORM_OWNER` names the platform organisation before
+   its first readable deploy.
+2. Each publisher has an organisation on the Admin instance: an Identity, a Shell User for a single
+   publisher or a Shell Group otherwise. The first deploy of an origin in an environment gives that
+   line to the organisation it names, and only a [transfer](#transfer-a-line) moves it.
+3. Its members and CI identities are Identities of the Admin instance that act for it through
+   Kernel `extends_with`. A Shell Group's `assignMember` writes that Edge for each User or Group it
+   assigns. A caller that does not act for the organisation it names is refused before any write.
+4. The Admin instance's graph is backed up with the registry it holds: only it records who holds
+   each line, each deployment's record and its secret digests. A restore loses what happened after
+   its backup: lines registered since are free for the next organisation that deploys, and secret
+   digests may name values older than the ones served.
+
 ## Plain background Service starter
 
 The package also ships an isolated scaffolding binary (the root import remains Schema-only):
@@ -359,12 +753,13 @@ No tooling dependency is added to the Schema runtime or imported from the packag
 
 ## Domain development
 
-Copy `.env.example` to `.env.dev` and fill the Cloudflare values.
-
-`pnpm dev` watches and deploys the development Environment remotely. `pnpm run deploy admin-beta`
-deploys the [Admin-hosted runtime](#admin-hosted-runtime) once. These bootstrap Environments
-are deliberately deploy-only: install the resulting URL on the intended Kernel explicitly.
-Stopping development leaves the remote Worker available. No local Worker or tunnel is started.
+Services has no development Environment: the [Admin-hosted runtime](#admin-hosted-runtime) is the
+only one it hosts, and Services itself is developed against its tests (the fake Cloudflare account
+and the [real-Kernel suite](tests/kernel/README.md)). `pnpm run deploy admin` makes an immutable
+deployment of this release on the `admin` line of the platform namespace. Deploying never
+installs: installation is always a separate, explicit `astrale domain install <url> -i <instance>`
+on the intended Kernel. There is no watch mode: `astrale-domain dev` serves only direct-mode
+Environments.
 
 To validate without deploying:
 
@@ -407,12 +802,12 @@ candidate and the serving Worker. Those exact flags participate in the deploymen
 Services must not inject defaults after its computation. The Cloudflare adapter already includes
 public-fetch routing in the generated configuration before building the artifact and its digest.
 
-SDK-authored Applications should deploy through `@astrale-os/adapter-astrale`, which projects the
+SDK-authored Domains should deploy through `@astrale-os/adapter-astrale`, which projects the
 admitted Cloudflare artifact into the revisioned Services request and verifies the live Publication.
-Project tooling installs the exact Release only when that environment declares installation.
-Services never interprets or
-caches Application, Publication, Schema revision, issuer, or callable inventory. Manual callers may
-deploy provider compute first and then use the ordinary Domain installation command themselves.
+Installation is never part of a deploy: install the deployed URL with
+`astrale domain install <url> -i <instance>` as its own step. Services never interprets or caches
+a Domain definition, Publication, Schema revision, issuer, or callable inventory. Manual callers likewise
+deploy provider compute first and then install with the same command.
 
 Revisioned deployments may request `readiness: { paths: ['/health'] }`. Services executes these
 bounded local GET paths through its private candidate dispatch binding and requires HTTP 200 before

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-domains/services",
-  "version": "0.4.7",
+  "version": "0.4.8",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/astrale-os/domains.git",
@@ -31,11 +31,11 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@astrale-os/sdk": "0.6.0-beta.13",
+    "@astrale-os/sdk": "0.6.0-beta.14",
     "zod": "4.4.3"
   },
   "devDependencies": {
-    "@astrale-os/adapter-cloudflare": "0.5.0-beta.168",
+    "@astrale-os/adapter-cloudflare": "0.5.0-beta.169",
     "@astrale-os/ox": ">=0.1.4 <1.0.0",
     "@astrale-os/shell": "0.6.0-beta.8",
     "@astrale-os/shell-react": "0.5.0-beta.8",
@@ -71,7 +71,6 @@
     "workerd"
   ],
   "scripts": {
-    "dev": "astrale-domain dev",
     "deploy": "astrale-domain deploy",
     "build": "astrale-domain build",
     "lint": "astrale-domain lint",