@astrale-domains/services 0.5.1 → 0.6.0

package/README.md

@@ -1,25 +1,35 @@
 # Services
 
-`services.astrale.ai` hosts Services: provider-backed compute an Identity owns. A Service is the
-stable identity of one origin in one environment. Every deploy adds an immutable deployment of it,
-and the Service's URL serves the one it currently points at, like a project and its deployments.
+`services.astrale.ai` hosts Services: Cloudflare Workers an Identity owns. A Service is the stable
+identity of one project in one environment. Every deploy adds an immutable deployment of it, and
+the Service's URL serves the one it currently points at, like a project and its deployments.
+
+Services is agnostic of what it hosts. An Astrale Domain release (`astrale-domain deploy` with
+`@astrale-os/adapter-astrale`) and a generic Worker (a cron job, an API, a
+[`create-astrale-service`](#generic-services) project) are the same thing to it: a Worker build,
+the configuration it freezes, the secrets it binds and, when it publishes one, an opaque record.
+Every Domain fact (origin, release, Schema revision, Publication, issuer) is the deployer's.
 Provider protocols stay behind a neutral SDK Integration, and the graph keeps only admitted
 lifecycle evidence.
 
 ## Model
 
-- **`Service` / `CloudflareService`**: one `(origin, environment)`. Its `name` is the opaque
-  16-character fingerprint the SDK derives from them (`deploymentLine({ addressing: 'opaque' })`);
-  it is unique among Services and is the DNS label of `url`, `https://<name>.<routing domain>`.
-  `state` is `active`, or `deleting` while its deletion retires its deployments.
+- **`Service` / `CloudflareService`**: one `(project, environment)`. A project is any name
+  (`PROJECT_NAME` of `@astrale-os/sdk/deployment/worker`); a Domain deployer names its Domain's
+  origin. Its `name` is the opaque 16-character `serviceName(project, environment)`, unique among
+  Services, the DNS label of `url`, `https://<name>.<routing domain>`. `state` is `active`, or
+  `deleting` while its deletion retires its deployments.
 - **`service_owned_by`**: every Service has exactly one owner, an Identity: a user, a group or a
   service account. It is chosen once, when the first deploy creates the Service, and changes only
   by `transfer`.
-- **`Deployment` / `CloudflareDeployment`**: one immutable release of a Service: one build with
-  its frozen configuration, served by one Workers for Platforms script at its own URL,
-  `https://<label>.<routing domain>`, where `label` is `<name>-<content16>`. It never changes code:
-  a new release is a new deployment. Its lifecycle is `deploying` → `active` → `retiring` →
-  `retired`, or `failed`; a retired deployment is never served again.
+- **`Deployment` / `CloudflareDeployment`**: one immutable release of a Service, served by one
+  Workers for Platforms script at its own URL, `https://<label>.<routing domain>`, where `label` is
+  `<name>-<content16>` and the content covers the build digest and the configuration digest. It
+  keeps generic facts only: `buildDigest`, its `configuration` (`WorkerConfigurationV1`) and
+  `configurationDigest`, the `record` it publishes if any (opaque bytes and their media type), its
+  key id when it asked for a signing identity, the script's code hash, the keyed digests of its
+  secrets, and its lifecycle: `deploying` → `active` → `retiring` → `retired`, or `failed`. A
+  retired deployment is never served again.
 - **`deployment_of`**: the Service a deployment is a version of. A deployment has no owner of its
   own: it belongs to whoever owns its Service.
 - **`current_deployment`**: the deployment the Service's URL serves and its crons run on. Promoting
@@ -42,13 +52,13 @@ caller in three groups also reaches the Services of each.
   Service of the group, deletion included.
 - `OwnDeployment` gives a deployment to the owner of its Service.
 
-Every Method is `authenticated`: a deployer's identities on the Admin instance hold no `can_use` on
-Services' Functions, which an `authorized` Method requires of every non-Root caller. Each handler
-asks the Kernel `Identity.can` for the caller on its own session before it reads anything: a caller
-who does not own the Service finds none (`SERVICE_NOT_FOUND`, `DEPLOYMENT_NOT_FOUND`), and a deploy
-of another owner's Service is refused `service-owned-elsewhere`. The day the Admin instance grants
-deployers `can_use` on these Methods, they become `authorized` with the Policy and the handler
-checks go.
+Every Method but `migrate` is `authenticated`: a deployer's identities on the Admin instance hold
+no `can_use` on Services' Functions, which an `authorized` Method requires of every non-Root caller.
+Each handler asks the Kernel `Identity.can` for the caller on its own session before it reads
+anything: a caller who does not own the Service finds none (`SERVICE_NOT_FOUND`,
+`DEPLOYMENT_NOT_FOUND`), and a deploy of another owner's Service is refused
+`service-owned-elsewhere`. The day the Admin instance grants deployers `can_use` on these Methods,
+they become `authorized` with the Policy and the handler checks go.
 
 `list` reads Services under the Services Domain credential and keeps those the Kernel answers
 `OwnService` for, in batches: a caller-mode read does not reach the Identity end of
@@ -57,39 +67,48 @@ checks go.
 
 ## Methods
 
-Call them on the Admin instance (`astrale call ... --admin`).
+Call them on the Admin instance (`astrale call ... --admin`). Their wire contract is
+`@astrale-os/sdk/deployment/worker`'s.
 
 | Method | On | What it does |
 | --- | --- | --- |
-| `deploy` | `CloudflareService` (static) | Hosts one release (`DeploymentRequestV1`) as a deployment of the Service of its origin and environment, creating the Service on its first deploy, and by default (`promote` absent or `true`) makes the Service serve it. |
-| `hosting` | `CloudflareService` (static) | The routing domain Services and deployments are addressed under; names are always opaque. |
-| `list` | `CloudflareService` (static) | The deployments of the Services the caller owns, narrowed to an origin and environment when given, each with `current`. |
+| `deploy` | `CloudflareService` (static) | Hosts one Worker release (`WorkerDeploymentRequestV1`) as a deployment of the Service of its project and environment, creating the Service on its first deploy, and by default (`promote` absent or `true`) makes the Service serve it. Answers `WorkerDeploymentResponseV1`. |
+| `hosting` | `CloudflareService` (static) | The routing domain Services and deployments are addressed under (`WorkerHostingV1`); names are always opaque. |
+| `list` | `CloudflareService` (static) | The deployments of the Services the caller owns (`WorkerDeploymentSummaryV1`), narrowed to a `project` and an `environment` when given, each with `current` and the record it publishes. |
 | `promote` | `CloudflareService` | Points the Service at one of its active deployments, named by its label. |
 | `transfer` | `CloudflareService` | Gives the Service to another owner the caller is or acts as. |
 | `setSecret`, `secrets` | `CloudflareService` | Rewrites one declared secret of the current deployment in place; lists the names it binds, never a value. |
 | `setSchedule`, `schedules` | `CloudflareService` | Replaces or reads the Service's UTC cron set; each cron fires on the current deployment. |
 | `logs` | `CloudflareService` | Recent logs of the current deployment, or of one deployment named by `label`. |
 | `delete` | `CloudflareService` | Stops routing the Service, retires every deployment of it, then deletes it and frees its name. |
+| `migrate` | `CloudflareService` (static, Root) | Once, after this revision is installed: rewrites the Services and deployments stored before Services hosted any Worker (see [Migration](#migration-to-the-agnostic-model)). |
 | `retire` | `CloudflareDeployment` | Withdraws one deployment for good. The current deployment is never retired alone. |
 
 ## Deploying
 
-`astrale-domain deploy <environment>` with the Astrale adapter calls `CloudflareService.deploy`.
-`deploy` is a non-durable Action: its input holds the environment's secrets, and no Execution, step
-result or journal entry keeps them.
-
-1. Before any read it recomputes the label from the Service name, the build digest and the frozen
-   configuration, recomputes the build digest from the uploaded bytes, admits the record with the
-   SDK, and refuses a service binding, a dispatch namespace, a router other than the logical
-   `admin-router`, a reserved binding name, or secrets other than exactly the declared ones.
-2. It reads the Service of the fingerprint under the Services Domain credential and proves the
-   caller's authority on the caller's own session: `OwnService` on an existing Service, `ActAs` on
-   the owner it names for a new one.
-3. A new label is created under a graph lease. The provider uploads it create-only with
-   `ASTRALE_BUILD_DIGEST`, `ASTRALE_SETTINGS`, a signing key generated for this deployment alone,
-   and the request's secrets; checks that the uploaded version serves its readiness paths; then
-   activates it through the routing KV `record:<label>`. The graph records it active with its key
-   id, script etag and keyed HMAC-SHA256 digests of its secrets.
+`deploy` is a non-durable Action: its input holds the secrets, and no Execution, step result or
+journal entry keeps them.
+
+1. Before any read, the SDK's `decodeWorkerDeploymentRequest` admits the request: every file
+   decoded within its bounds, the configuration canonical, a record exactly when the configuration
+   asks for one, the secrets exactly the names it declares. It recomputes the build digest from
+   the uploaded bytes (`build-mismatch`) and the label from the Service name, the build and the
+   configuration (`address-mismatch`); anything else is `invalid-deployment`. A configuration that
+   asks for the router where this environment has none is `hosting-unavailable`.
+2. It reads the Service of the name under the Services Domain credential and proves the caller's
+   authority on the caller's own session: `OwnService` on an existing Service, `ActAs` on the owner
+   it names for a new one.
+3. A new label is created under a graph lease. The provider uploads it create-only with the host
+   bindings (its URL as `WORKER_URL`, the recomputed `ASTRALE_BUILD_DIGEST`, the version
+   metadata `ASTRALE_VERSION_METADATA`), the configuration's variables, a signing key generated
+   for this deployment alone (`ASTRALE_SIGNING_IDENTITY`) only when it asks `signingIdentity`, the
+   router (`ROUTER`) only when it asks `router`, and the request's secrets. When the request names
+   readiness paths, each must answer 200 from the uploaded version (`x-astrale-worker-version`);
+   none skips the probe. The label is then activated through the routing KV `record:<label>` with
+   the record the deployment publishes, served byte for byte with its media type at
+   `/.well-known/astrale/deployment.json`, or a placeholder when it publishes none. The graph
+   records it active with its code hash, its key id when it has one, and keyed HMAC-SHA256 digests
+   of its secrets.
 4. The same release again is the same label: `deploy` answers `reused`. Its secrets are compared
    with the recorded digests: `unchanged`, or rewritten in place on that deployment alone,
    `updated`.
@@ -97,28 +116,49 @@ result or journal entry keeps them.
    served, and the routing KV `current:<name>` names its label. A routing write that failed is
    answered `service-unavailable`; deploying or promoting again converges.
 
-`WORKER_URL` and `ASTRALE_BUILD_DIGEST` are bound by the host, never by the author: Services refuses
-them as caller variables or secrets.
+The names the host binds itself (`WORKER_HOST_BINDINGS`: `WORKER_URL`, `ASTRALE_BUILD_DIGEST`,
+`ASTRALE_VERSION_METADATA`, `ASTRALE_SIGNING_IDENTITY`, `ROUTER`, `ASSETS`) are never a variable
+or a secret of the request.
+
+- **A Domain** is deployed by `astrale-domain deploy <environment>` with `astrale()` of
+  `@astrale-os/adapter-astrale`: its project is the Domain's origin, its build manifest members are
+  the Domain's (so `ASTRALE_BUILD_DIGEST` is the sealed release's), its execution settings travel
+  as the `ASTRALE_SETTINGS` variable, it publishes its `DeploymentRecordV1` and asks for a signing
+  identity, and readiness probes the release's documents. The adapter, not Services, verifies the
+  release served and installs it deliberately.
+- **Any other Worker** is deployed with `@astrale-os/adapter-astrale/services`
+  (`readWorkerDirectory`, `deployWorker`, `callService`), as the projects
+  [`create-astrale-service`](#generic-services) generates do.
 
 ## Routing and crons
 
-The Services dispatcher serves one routing domain:
+The Services dispatcher is the hosting kit's dispatcher (`@astrale-os/adapter-cloudflare/hosting`),
+extended only with the frozen legacy tenant routing of `providers/cloudflare/legacy` (removal: D20).
+It serves one routing domain:
 
 - `https://<label>.<routing domain>` serves that deployment: `record:<label>` activates it, and
-  `retirement:<label>` answers `DEPLOYMENT_RETIRED` (`410`).
+  `retirement:<label>` answers `DEPLOYMENT_RETIRED` (`410`). It answers the deployment's record at
+  `/.well-known/astrale/deployment.json` itself; a deployment that publishes none answers that path.
 - `https://<name>.<routing domain>` serves the deployment `current:<name>` names, through the same
   path, so a retired deployment is never served through its Service either.
 - Every minute the dispatcher reads the `cron:<name>` keys and posts each due cron to the current
-  deployment of that Service, at `https://cron.internal/__scheduled`.
+  deployment of that Service: `POST https://cron.internal/__scheduled` with the expression in
+  `x-astrale-cron` and the minute it fired for, in epoch milliseconds, in
+  `x-astrale-scheduled-time`, within a 10-second deadline. A non-2xx answer is logged. The public
+  never reaches `/__scheduled`: the dispatcher refuses it in every spelling (case, repeated or
+  trailing slashes, percent-encoding) before any lookup. A run is not exactly-once: a job must be
+  safe to repeat.
+- A legacy tenant Worker with a `service:<name>` entry keeps its routing and crons ahead of all of
+  this, until D20 removes them.
 
 ## Secrets
 
 Services never keeps a value. A deploy binds the request's secrets to the new deployment only;
-every other deployment keeps its own. `setSecret` rewrites one name the current deployment's frozen
+every other deployment keeps its own. `setSecret` rewrites one name the current deployment's
 configuration declares, in place, under the deployment's graph lease: it compares the keyed
 digests, writes only changed values, forgets the digests of the names it writes first and records
 the new ones once every write succeeded. The provider serves a new value a few seconds later. A
-new name, or removing one, is a new release; the signing key never rotates.
+new name, or removing one, is a new release; a signing key never rotates.
 
 Never pass a secret value in argv. Write the input to a file only you can read, outside the
 repository:
@@ -139,7 +179,7 @@ carries.
 
 ```sh
 astrale call /:services.astrale.ai:class.CloudflareService:list \
-  origin=agencies.example.com environment=production --admin --json
+  project=agencies.example.com environment=production --admin --json
 astrale call "@$SERVICE::services.astrale.ai:class.CloudflareService.method.promote" \
   label=$PREVIOUS_LABEL --admin --json
 ```
@@ -158,6 +198,62 @@ deployment. It answers `deleting` with `retryAfterMs` until the last one is reti
 the Service with its deployments in one Mutation and answers `deleted`. The name is then free
 again.
 
+## Generic Services
+
+The package ships an isolated scaffolding binary (the root import remains Schema-only):
+
+```sh
+npm exec --package @astrale-domains/services -- create-astrale-service nightly-report
+cd nightly-report
+npm install
+# Edit service.json and src/job.js; put the secret values in .env.production.
+npm run deploy -- production
+```
+
+The generator creates local source only and refuses an existing destination: a plain Worker
+(`src/index.js` answering `GET /health` and running `src/job.js` on `POST /__scheduled`), an
+optional ES256 account session to call an Astrale Kernel (`src/account.js`), `service.json` (the
+project, the Workers runtime, the variables, the secret names, readiness paths and crons) and its
+build (esbuild) and deploy scripts. `npm run deploy -- <environment>` builds it, deploys it through
+`@astrale-os/adapter-astrale/services` as one immutable deployment promoted by default
+(`--no-promote` deploys beside the current one), then replaces the Service's crons with
+`service.json`'s. It installs, registers, grants and schedules nothing else. The generated README
+explains promotion and rollback, secrets, crons, logs and deletion. The scaffold lives in
+[`tooling/scaffold`](tooling/scaffold); `pnpm package` copies it to `dist/scaffold`.
+
+## Migration to the agnostic model
+
+The Kernel installs no Schema revision that existing data does not satisfy
+(`DATA_MIGRATION_REQUIRED`), and the SDK has no install-time migration: a Service stored before
+Services hosted any Worker names its project `origin`, and its deployments store the Domain's
+`FrozenConfigurationV1` and `DeploymentRecordV1`. The transition is expand, migrate, contract:
+
+1. **Expand** — this revision admits both forms. Every reader reads a legacy node as the Worker
+   deployment it is (`convertLegacyDeployment`): its build digest is its record's; its
+   configuration binds what the runtime that uploaded it bound (the compatibility date and flags,
+   the author's variables, `ASTRALE_SETTINGS` encoded from the frozen settings as that runtime
+   encoded it, the secret names, `record: true`, `signingIdentity: true`, `router` as it was); its
+   record is the RFC 8785 JSON its activation published, with the Astrale record media type. Its
+   label stays: a stored label is never derived again. Every writer writes the agnostic form only.
+2. **Migrate** — the Kernel's Root calls `CloudflareService.migrate` once. Each legacy Service and
+   deployment is rewritten by its own fenced Mutation (`origin` becomes `project`; a deployment
+   stores its reading), nothing is written at Cloudflare, and a rerun rewrites nothing more. It
+   answers how many it rewrote and names any deployment it could not read (`unconverted`, empty
+   when everything converted).
+3. **Contract** — the next revision drops the legacy shapes and `migrate`; the Kernel installs it
+   only once no legacy value remains.
+
+Call it as the Admin Kernel's Root, with a short-lived root credential file (`--creds`) removed
+once the call answers:
+
+```sh
+astrale call "/:services.astrale.ai:class.CloudflareService:migrate" --admin --json \
+  --creds "$ROOT_CREDENTIAL_FILE"
+```
+
+It answers `{ "services": <n>, "deployments": <n>, "unconverted": [] }`; a second call answers
+zeros.
+
 ## Admin-hosted runtime
 
 Services are hosted for the Admin instance's Kernel alone: its graph is the registry of Service
@@ -173,14 +269,16 @@ hosting var.
 
 `pnpm run deploy admin` makes one immutable deployment of this release in the platform dispatch
 namespace. Deploying never installs: install the deployed URL with
-`astrale domain install <url> -i <instance>`. Operator tooling (platform namespace bootstrap,
-dispatcher, routing, audits) is described in
+`astrale domain install <url> -i <instance>`. The Cloudflare Provider and its operator tooling
+are built on the hosting kit: provisioning both dispatchers (the Services environment's and the
+platform namespace's), audits, platform retirement and secret rotation are described in
 [`providers/cloudflare/operator/README.md`](providers/cloudflare/operator/README.md).
 
 ## Domain development
 
-Services is developed against its tests: the fake Cloudflare account and the
-[real-Kernel suite](tests/kernel/README.md).
+Services is developed against its tests: the hosting kit's fake Cloudflare account
+(`@astrale-os/adapter-cloudflare/hosting/testing`, running the dispatchers as uploaded, and the
+scaffolded Worker itself) and the [real-Kernel suite](tests/kernel/README.md).
 
 ```sh
 pnpm typecheck

package/dist/scaffold/create-service.mjs

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+import { cp, mkdir, readdir, readFile, rename, writeFile } from 'node:fs/promises'
+import { basename, resolve } from 'node:path'
+
+const USAGE = 'Usage: create-astrale-service <new-directory>'
+/** A project name Services admits (`PROJECT_NAME`), kept to a directory-friendly subset. */
+const PROJECT = /^[a-z][a-z0-9-]{0,62}$/u
+/** The packages a generated Service depends on, at the versions this package was released with. */
+const PINNED = ['@astrale-os/sdk', '@astrale-os/adapter-astrale', 'esbuild', 'jose']
+
+const [directory, ...extra] = process.argv.slice(2)
+if (directory === '--help' || directory === '-h') {
+  console.log(
+    `${USAGE}\nCreates the local source of a Cloudflare Worker that Admin's Services hosts: an HTTP` +
+      ' entry, a cron job and its build and deploy scripts. It installs, registers, deploys and' +
+      ' schedules nothing.',
+  )
+} else {
+  try {
+    if (!directory || directory.startsWith('-') || extra.length > 0) throw new Error(USAGE)
+    const destination = resolve(directory)
+    const name = basename(destination)
+    if (!PROJECT.test(name)) {
+      throw new Error(
+        'Use a lower-case project name beginning with a letter (letters, digits and dashes, at most 63 characters).',
+      )
+    }
+    const versions = await pinnedVersions()
+    // Exclusive creation keeps an existing project and refuses a symbolic link.
+    await mkdir(destination)
+    const template = new URL('./template/', import.meta.url)
+    for (const entry of await readdir(template)) {
+      await cp(new URL(entry, template), resolve(destination, entry), {
+        recursive: true,
+        force: false,
+        errorOnExist: true,
+      })
+    }
+    await rename(resolve(destination, 'gitignore'), resolve(destination, '.gitignore'))
+    await writeJson(resolve(destination, 'package.json'), {
+      name,
+      version: '0.0.0',
+      private: true,
+      type: 'module',
+      scripts: {
+        build: 'node scripts/build.mjs',
+        deploy: 'node scripts/deploy.mjs',
+      },
+      dependencies: {
+        '@astrale-os/sdk': versions['@astrale-os/sdk'],
+        jose: versions.jose,
+      },
+      devDependencies: {
+        '@astrale-os/adapter-astrale': versions['@astrale-os/adapter-astrale'],
+        esbuild: versions.esbuild,
+      },
+      engines: { node: '>=22.13' },
+    })
+    await writeJson(resolve(destination, 'service.json'), {
+      project: name,
+      compatibilityDate: '2026-09-01',
+      compatibilityFlags: ['nodejs_compat'],
+      vars: { KERNEL: '', TARGET: '' },
+      secrets: ['ACCOUNT_PRIVATE_JWK'],
+      readiness: ['/health'],
+      crons: [],
+    })
+    console.log(
+      `Created ${destination}\nInstall its dependencies, edit service.json and src/job.js, then deploy:` +
+        ' npm run deploy -- <environment>. Its README explains each step.',
+    )
+  } catch (error) {
+    console.error(
+      error.code === 'EEXIST' ? 'Destination already exists; no file was written.' : error.message,
+    )
+    process.exitCode = 1
+  }
+}
+
+/** The versions of `PINNED` this package declares, in its dependencies or devDependencies. */
+async function pinnedVersions() {
+  const owner = JSON.parse(await readFile(new URL('../../package.json', import.meta.url), 'utf8'))
+  const declared = { ...owner.devDependencies, ...owner.dependencies }
+  return Object.fromEntries(
+    PINNED.map((name) => {
+      if (typeof declared[name] !== 'string') throw new Error(`No version of ${name} is pinned.`)
+      return [name, declared[name]]
+    }),
+  )
+}
+
+async function writeJson(path, value) {
+  await writeFile(path, `${JSON.stringify(value, null, 2)}\n`, { flag: 'wx' })
+}

package/dist/scaffold/template/.env.example

@@ -0,0 +1,4 @@
+# The secrets service.json declares, for one environment: copy to .env.<environment> (ignored by
+# git). `npm run deploy -- <environment>` reads them and binds them to the new deployment; they are
+# never stored by Services. One value per line, as NAME=value.
+ACCOUNT_PRIVATE_JWK=

package/dist/scaffold/template/README.md

@@ -0,0 +1,75 @@
+# Astrale Service
+
+A plain Cloudflare Worker that Admin's Services hosts (`services.astrale.ai`): an HTTP entry and a
+cron job, with no Cloudflare account of your own. It is not an Astrale Domain: it publishes no
+Schema and installs nothing. Services knows nothing of what it serves either: it runs the Worker
+you build, at its own URL, under your Identity.
+
+- `src/index.js` answers `GET /health` and runs `src/job.js` on `POST /__scheduled`; every other
+  path answers 404. Add your routes there.
+- `src/job.js` calls one callable of an Astrale Kernel as this Service's own account
+  (`src/account.js`, an ES256 key registered on a dedicated Identity). Replace it with your job.
+- `service.json` is what every deployment freezes beside its code: the project (with an environment,
+  it names the Service), the Workers compatibility date and flags, plain variables, the names of its
+  secrets, the readiness paths probed before a deployment is activated, and the Service's crons.
+
+## Deploy
+
+Install the dependencies (Node 22.13+) and the Astrale CLI, and sign in: `astrale auth login`.
+Services is called on the Admin instance as the CLI's identity.
+
+```sh
+npm install
+cp .env.example .env.production   # then fill in the secret values; git ignores it
+npm run deploy -- production      # --admin <bookmark>, --as <identity>, --no-promote
+```
+
+`deploy` builds `.dist/worker.mjs`, then calls `CloudflareService.deploy` through
+`@astrale-os/adapter-astrale/services` (`readWorkerDirectory`, `deployWorker`). The first deploy of
+a project and an environment creates their Service, owned by you, or by the Identity you act as with
+`--as`. Each deploy is one immutable deployment at `https://<label>.<routing domain>`; the Service's
+URL, `https://<service>.<routing domain>`, serves the one last promoted, by default the new one. The
+same code and configuration reuse their deployment and rewrite its secrets in place when their
+values changed; any other change is a new deployment. Secret values come from `.env.<environment>`
+(or the process environment) and are never stored by Services, nor printed.
+
+`deploy` answers the deployment's `label`, `url` and the `serviceId` every Service Method is called
+on, then replaces the Service's crons with `service.json`'s `crons`.
+
+## Operate
+
+Call the Service's Methods on the Admin instance with its id, as its owner:
+
+```sh
+SERVICE=@<serviceId>::services.astrale.ai:class.CloudflareService
+astrale call "$SERVICE.method.promote" label=<label> --admin --json        # roll back or forward
+astrale call "$SERVICE.method.setSchedule" --admin -d '{"crons":["*/5 * * * *"]}' --json
+astrale call "$SERVICE.method.schedules" --admin --json
+astrale call "$SERVICE.method.logs" --admin -d '{"tail":50}' --json
+astrale call "$SERVICE.method.setSecret" --admin -d @secret.json --json   # { "name", "value" }
+astrale call "$SERVICE.method.secrets" --admin --json                      # names only
+astrale call "$SERVICE.method.delete" --admin --json
+astrale call /:services.astrale.ai:class.CloudflareService:list \
+  project=<project> environment=production --admin --json
+```
+
+- **Promote, roll back**: `promote` points the Service's URL at one of its active deployments.
+- **Retire**: `astrale call "@<deploymentId>::services.astrale.ai:class.CloudflareDeployment.method.retire" --admin`
+  withdraws one deployment for good, in two calls about 65 seconds apart. The current deployment is
+  never retired alone: promote another one first, or delete the Service.
+- **Secrets**: `setSecret` rewrites one declared secret of the current deployment in place; write
+  its input to a file only you can read, never in argv. A new secret name is a new deployment: add
+  it to `service.json` and deploy. Put the new value in `.env.<environment>` too: the next deploy
+  binds the values it carries.
+- **Crons**: five-field UTC expressions. Each due cron is posted by the Services dispatcher to the
+  deployment the Service serves, as `POST https://cron.internal/__scheduled` with `x-astrale-cron`
+  (the expression) and `x-astrale-scheduled-time` (the minute it fired for, in epoch ms), within a
+  10 s deadline. The public never reaches `/__scheduled`, in any spelling, and a run is at most once
+  per minute but not exactly once: make the job safe to repeat.
+- **Logs**: `logs` reads the recent logs of the current deployment, or of one by `label`.
+- **Delete**: `delete` stops routing the Service and its crons, retires every deployment, then
+  deletes the Service and frees its name; call it again after `retryAfterMs` until it answers
+  `deleted`.
+
+`/health` proves the Worker runs, not that its account is registered or authorized: check the job's
+real call once, then add its cron.

package/dist/scaffold/template/gitignore

@@ -0,0 +1,6 @@
+node_modules/
+.dist/
+.env
+.env.*
+!.env.example
+*.private.jwk

package/dist/scaffold/template/scripts/build.mjs

@@ -0,0 +1,20 @@
+import { build } from 'esbuild'
+import { resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+/** Bundle the Worker into one ES module, `.dist/worker.mjs`, as Workers loads it. */
+export async function buildWorker(directory = process.cwd()) {
+  await build({
+    absWorkingDir: resolve(directory),
+    entryPoints: ['src/index.js'],
+    outfile: '.dist/worker.mjs',
+    bundle: true,
+    platform: 'browser',
+    conditions: ['workerd', 'worker', 'browser'],
+    format: 'esm',
+    target: 'es2022',
+    logLevel: 'warning',
+  })
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) await buildWorker()

package/dist/scaffold/template/scripts/deploy.mjs

@@ -0,0 +1,65 @@
+import {
+  callService,
+  deployWorker,
+  readWorkerDirectory,
+} from '@astrale-os/adapter-astrale/services'
+import { parseArgs } from 'node:util'
+
+import { buildWorker } from './build.mjs'
+import { readSecrets, readService, serviceDeployment } from './service.mjs'
+
+const USAGE =
+  'Usage: npm run deploy -- <environment> [--admin <bookmark>] [--as <identity>] [--no-promote]'
+
+const { positionals, values } = parseArgs({
+  args: process.argv.slice(2).filter((argument) => argument !== '--'),
+  allowPositionals: true,
+  options: {
+    admin: { type: 'string' },
+    as: { type: 'string' },
+    'no-promote': { type: 'boolean', default: false },
+  },
+})
+const [environment, ...extra] = positionals
+if (environment === undefined || extra.length > 0) throw new Error(USAGE)
+
+const directory = process.cwd()
+const service = await readService(directory)
+const secrets = await readSecrets(directory, environment, service.secrets ?? [])
+await buildWorker(directory)
+const worker = await readWorkerDirectory('.dist', { mainModule: 'worker.mjs' })
+const options = {
+  ...(values.admin === undefined ? {} : { admin: values.admin }),
+  ...(values.as === undefined ? {} : { identity: values.as }),
+}
+const promote = !values['no-promote']
+// One immutable deployment: the same code and configuration reuse their deployment, and the
+// Service's URL serves it once it is active unless --no-promote.
+const {
+  state,
+  secrets: bound,
+  deployment,
+} = await deployWorker(
+  serviceDeployment({ service, environment, worker, secrets, promote }),
+  options,
+)
+// The Service's crons are service.json's, fired on the deployment its URL serves.
+const crons =
+  promote && service.crons !== undefined
+    ? await callService(deployment.serviceId, 'setSchedule', { crons: service.crons }, options)
+    : undefined
+if (crons?.kind === 'rejected') process.exitCode = 1
+console.log(
+  JSON.stringify(
+    {
+      state,
+      secrets: bound.state,
+      serviceId: deployment.serviceId,
+      deployment: { id: deployment.id, label: deployment.label, url: deployment.url },
+      current: deployment.current,
+      ...(crons === undefined ? {} : { schedules: crons }),
+    },
+    null,
+    2,
+  ),
+)

package/dist/scaffold/template/scripts/service.mjs

@@ -0,0 +1,69 @@
+import { workerConfiguration } from '@astrale-os/sdk/deployment/worker'
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+/**
+ * `service.json`: what every deployment of this Service freezes beside its code. Its project and
+ * an environment name the Service; a changed variable, flag or secret name is a new deployment.
+ */
+export async function readService(directory) {
+  const service = JSON.parse(await readFile(join(directory, 'service.json'), 'utf8'))
+  for (const member of ['project', 'compatibilityDate']) {
+    if (typeof service[member] !== 'string') throw new TypeError(`service.json needs ${member}.`)
+  }
+  return service
+}
+
+/**
+ * The value of each secret `service.json` declares, for one environment: from
+ * `.env.<environment>` when it exists, else from the process environment. A missing one refuses
+ * the deploy before anything is called; values are never printed.
+ */
+export async function readSecrets(directory, environment, declared, variables = process.env) {
+  const file = await readFile(join(directory, `.env.${environment}`), 'utf8').catch((error) => {
+    if (error.code === 'ENOENT') return undefined
+    throw error
+  })
+  const values = file === undefined ? variables : parseEnv(file)
+  const missing = declared.filter((name) => typeof values[name] !== 'string' || values[name] === '')
+  if (missing.length > 0) {
+    throw new Error(
+      `Set ${missing.join(', ')} in .env.${environment} or in the environment before deploying.`,
+    )
+  }
+  return Object.fromEntries(declared.map((name) => [name, values[name]]))
+}
+
+/**
+ * The deployment of one built Worker in one environment, as `deployWorker`
+ * (`@astrale-os/adapter-astrale/services`) sends it: no record, no signing identity, no router,
+ * the readiness paths `service.json` names.
+ */
+export function serviceDeployment({ service, environment, worker, secrets, promote = true }) {
+  return {
+    project: service.project,
+    environment,
+    worker,
+    configuration: workerConfiguration({
+      compatibilityDate: service.compatibilityDate,
+      compatibilityFlags: service.compatibilityFlags ?? [],
+      vars: service.vars ?? {},
+      secrets: Object.keys(secrets),
+    }),
+    secrets,
+    ...(service.readiness === undefined ? {} : { readiness: service.readiness }),
+    promote,
+  }
+}
+
+/** `NAME=value` lines; blank lines and `#` comments are skipped, a value is taken as written. */
+function parseEnv(text) {
+  const values = {}
+  for (const line of text.split(/\r?\n/u)) {
+    if (line.trim() === '' || line.trimStart().startsWith('#')) continue
+    const separator = line.indexOf('=')
+    if (separator <= 0) throw new Error('A .env line is not NAME=value.')
+    values[line.slice(0, separator).trim()] = line.slice(separator + 1)
+  }
+  return values
+}