@toa.io/operations 1.0.0-alpha.33 → 1.0.0-alpha.331

package/CHANGELOG.md

@@ -0,0 +1,378 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+# [1.0.0-alpha.331](https://github.com/toa-io/toa/compare/v1.0.0-alpha.330...v1.0.0-alpha.331) (2026-10-16)
+
+### Bug Fixes
+
+* **operations:** a deploy waited for is rolled back where it fails ([41ce1c5](https://github.com/toa-io/toa/commit/41ce1c5f462c5dcd78e138dba7c7cc4300e8e9fb))
+
+
+# [1.0.0-alpha.330](https://github.com/toa-io/toa/compare/v1.0.0-alpha.329...v1.0.0-alpha.330) (2026-10-15)
+
+**Note:** Version bump only for package @toa.io/operations
+
+
+
+
+
+# [1.0.0-alpha.329](https://github.com/toa-io/toa/compare/v1.0.0-alpha.328...v1.0.0-alpha.329) (2026-10-11)
+
+**Note:** Version bump only for package @toa.io/operations
+
+
+
+
+
+# [1.0.0-alpha.328](https://github.com/toa-io/toa/compare/v1.0.0-alpha.327...v1.0.0-alpha.328) (2026-10-10)
+
+**Note:** Version bump only for package @toa.io/operations
+
+
+
+
+
+# [1.0.0-alpha.327](https://github.com/toa-io/toa/compare/v1.0.0-alpha.326...v1.0.0-alpha.327) (2026-10-10)
+
+**Note:** Version bump only for package @toa.io/operations
+
+
+
+
+
+# [1.0.0-alpha.326](https://github.com/toa-io/toa/compare/v1.0.0-alpha.325...v1.0.0-alpha.326) (2026-10-06)
+
+**Note:** Version bump only for package @toa.io/operations
+
+
+
+
+
+# [1.0.0-alpha.325](https://github.com/toa-io/toa/compare/v1.0.0-alpha.324...v1.0.0-alpha.325) (2026-10-02)
+
+**Note:** Version bump only for package @toa.io/operations
+
+
+
+
+
+# [1.0.0-alpha.324](https://github.com/toa-io/toa/compare/v1.0.0-alpha.323...v1.0.0-alpha.324) (2026-10-02)
+
+**Note:** Version bump only for package @toa.io/operations
+
+
+
+
+
+# [1.0.0-alpha.323](https://github.com/toa-io/toa/compare/v1.0.0-alpha.322...v1.0.0-alpha.323) (2026-10-01)
+
+**Note:** Version bump only for package @toa.io/operations
+
+
+
+
+
+# [1.0.0-alpha.322](https://github.com/toa-io/toa/compare/v1.0.0-alpha.321...v1.0.0-alpha.322) (2026-09-29)
+
+**Note:** Version bump only for package @toa.io/operations
+
+
+
+
+
+# [1.0.0-alpha.321](https://github.com/toa-io/toa/compare/v1.0.0-alpha.320...v1.0.0-alpha.321) (2026-09-28)
+
+**Note:** Version bump only for package @toa.io/operations
+
+
+
+
+
+# [1.0.0-alpha.320](https://github.com/toa-io/toa/compare/v1.0.0-alpha.319...v1.0.0-alpha.320) (2026-09-28)
+
+**Note:** Version bump only for package @toa.io/operations
+
+
+
+
+
+# [1.0.0-alpha.319](https://github.com/toa-io/toa/compare/v1.0.0-alpha.318...v1.0.0-alpha.319) (2026-09-27)
+
+### Features
+
+* **operations:** refuse a deploy where the cluster does not hold a secret ([beb7ccf](https://github.com/toa-io/toa/commit/beb7ccf35619494ab9ad6659963969bb4f9603c8))
+
+
+# [1.0.0-alpha.318](https://github.com/toa-io/toa/compare/v1.0.0-alpha.317...v1.0.0-alpha.318) (2026-09-23)
+
+### Features
+
+* **deployment:** copy a component's linked sources as files ([1a1a8c1](https://github.com/toa-io/toa/commit/1a1a8c10684348dba02b475ab809a4083f86a601))
+
+
+# [1.0.0-alpha.317](https://github.com/toa-io/toa/compare/v1.0.0-alpha.316...v1.0.0-alpha.317) (2026-09-23)
+
+**Note:** Version bump only for package @toa.io/operations
+
+
+
+
+
+# [1.0.0-alpha.316](https://github.com/toa-io/toa/compare/v1.0.0-alpha.315...v1.0.0-alpha.316) (2026-09-23)
+
+**Note:** Version bump only for package @toa.io/operations
+
+
+
+
+
+# [1.0.0-alpha.315](https://github.com/toa-io/toa/compare/v1.0.0-alpha.314...v1.0.0-alpha.315) (2026-09-23)
+
+* feat(map)!: leave out of a contract what the runtime gives every component ([b81837a](https://github.com/toa-io/toa/commit/b81837a3bc4771d7ee1c10fe613c9a1d7501bf1a))
+
+### BREAKING CHANGES
+
+* the deployed component map is `/etc/toa/.map.json.gz`.
+
+
+# [1.0.0-alpha.314](https://github.com/toa-io/toa/compare/v1.0.0-alpha.313...v1.0.0-alpha.314) (2026-09-19)
+
+### Features
+
+* **core:** a reference may name a declaration its package claims ([8040f60](https://github.com/toa-io/toa/commit/8040f60976549ab90497675bb54e664261f5b6bb))
+
+
+# [1.0.0-alpha.313](https://github.com/toa-io/toa/compare/v1.0.0-alpha.312...v1.0.0-alpha.313) (2026-09-18)
+
+**Note:** Version bump only for package @toa.io/operations
+
+
+
+
+
+# [1.0.0-alpha.312](https://github.com/toa-io/toa/compare/v1.0.0-alpha.311...v1.0.0-alpha.312) (2026-09-18)
+
+### Features
+
+* **operations:** point a component's service at the port a streamed call is served on ([dbad630](https://github.com/toa-io/toa/commit/dbad630f765d5c1d50b3eda65768352905149c0c))
+* **operations:** refuse to render a chart for a context with no version ([d6cd083](https://github.com/toa-io/toa/commit/d6cd083bfe8d7da9f3d451c2c25d821eb41ce958))
+
+
+# [1.0.0-alpha.311](https://github.com/toa-io/toa/compare/v1.0.0-alpha.310...v1.0.0-alpha.311) (2026-09-17)
+
+**Note:** Version bump only for package @toa.io/operations
+
+
+
+
+
+# [1.0.0-alpha.310](https://github.com/toa-io/toa/compare/v1.0.0-alpha.309...v1.0.0-alpha.310) (2026-09-16)
+
+**Note:** Version bump only for package @toa.io/operations
+
+
+
+
+
+# [1.0.0-alpha.309](https://github.com/toa-io/toa/compare/v1.0.0-alpha.308...v1.0.0-alpha.309) (2026-09-16)
+
+**Note:** Version bump only for package @toa.io/operations
+
+
+
+
+
+# [1.0.0-alpha.308](https://github.com/toa-io/toa/compare/v1.0.0-alpha.307...v1.0.0-alpha.308) (2026-09-15)
+
+**Note:** Version bump only for package @toa.io/operations
+
+
+
+
+
+# [1.0.0-alpha.307](https://github.com/toa-io/toa/compare/v1.0.0-alpha.306...v1.0.0-alpha.307) (2026-09-15)
+
+**Note:** Version bump only for package @toa.io/operations
+
+
+
+
+
+# [1.0.0-alpha.306](https://github.com/toa-io/toa/compare/v1.0.0-alpha.305...v1.0.0-alpha.306) (2026-09-14)
+
+**Note:** Version bump only for package @toa.io/operations
+
+
+
+
+
+# [1.0.0-alpha.305](https://github.com/toa-io/toa/compare/v1.0.0-alpha.304...v1.0.0-alpha.305) (2026-09-13)
+
+**Note:** Version bump only for package @toa.io/operations
+
+
+
+
+
+# [1.0.0-alpha.304](https://github.com/toa-io/toa/compare/v1.0.0-alpha.303...v1.0.0-alpha.304) (2026-09-13)
+
+**Note:** Version bump only for package @toa.io/operations
+
+
+
+
+
+# [1.0.0-alpha.303](https://github.com/toa-io/toa/compare/v1.0.0-alpha.302...v1.0.0-alpha.303) (2026-09-12)
+
+### Features
+
+* **operations:** a composition states how many replicas it runs ([4466f5a](https://github.com/toa-io/toa/commit/4466f5abcc22c6dceb2994a0143b6bf9d5201d9d))
+
+
+# [1.0.0-alpha.302](https://github.com/toa-io/toa/compare/v1.0.0-alpha.301...v1.0.0-alpha.302) (2026-09-11)
+
+**Note:** Version bump only for package @toa.io/operations
+
+
+
+
+
+# [1.0.0-alpha.301](https://github.com/toa-io/toa/compare/v1.0.0-alpha.300...v1.0.0-alpha.301) (2026-09-11)
+
+### Bug Fixes
+
+* **operations:** a composition of evicted components asks for no resources ([a6a3ec7](https://github.com/toa-io/toa/commit/a6a3ec76781812f5a9bdd46c6de0fe7769174d57))
+
+### Features
+
+* **operations:** an evicted component is given its environment and configuration ([6cf7890](https://github.com/toa-io/toa/commit/6cf7890a632a2185d2b7d9790890a04187e5a897))
+
+
+# [1.0.0-alpha.300](https://github.com/toa-io/toa/compare/v1.0.0-alpha.299...v1.0.0-alpha.300) (2026-09-11)
+
+* feat(core)!: an operation may ask to run once ([dca616c](https://github.com/toa-io/toa/commit/dca616cb380a7a389e277875d3bd5ca55a6e4d45))
+
+### Features
+
+* **cli:** generate env for listed components and services ([b830613](https://github.com/toa-io/toa/commit/b830613ae2a0443bf8e72a353ffb6f2efaa72fb5))
+* **core:** a call may name the process it goes to, and wait for a set time ([7d8adb2](https://github.com/toa-io/toa/commit/7d8adb2772a95ff45ae5374efdedfb5a857fbbe9))
+* **norm:** a context says what it does not deploy ([135e6fd](https://github.com/toa-io/toa/commit/135e6fdfbc4270762028e9e5a0516766960ce59c))
+* **operations:** a rollout spreads the pods of its revision across nodes ([63be649](https://github.com/toa-io/toa/commit/63be649a73978a415f0c1e7ffb3837ffa7802da7))
+
+### BREAKING CHANGES
+
+* `Storage.store`, `.upsert` and `.ensure` take one more
+  argument, and `Storage` has two more members. A connector that ignores them
+  works exactly as it did; a component that asks it for `once` is refused at
+  boot. See migrations/299.md.
+
+
+# [1.0.0-alpha.299](https://github.com/toa-io/toa/compare/v1.0.0-alpha.298...v1.0.0-alpha.299) (2026-09-10)
+
+**Note:** Version bump only for package @toa.io/operations
+
+
+
+
+
+# [1.0.0-alpha.298](https://github.com/toa-io/toa/compare/v1.0.0-alpha.297...v1.0.0-alpha.298) (2026-09-08)
+
+### Features
+
+* **operations:** tag a deploy with the environment so registries can prune ([7247c35](https://github.com/toa-io/toa/commit/7247c35f33fb34dcfb3ffa04b196c14bfb3d5620))
+
+
+# [1.0.0-alpha.297](https://github.com/toa-io/toa/compare/v1.0.0-alpha.296...v1.0.0-alpha.297) (2026-09-08)
+
+**Note:** Version bump only for package @toa.io/operations
+
+
+
+
+
+# [1.0.0-alpha.296](https://github.com/toa-io/toa/compare/v1.0.0-alpha.295...v1.0.0-alpha.296) (2026-09-08)
+
+### Bug Fixes
+
+* **exposition:** the gateway's image carries every storage provider ([ab19d25](https://github.com/toa-io/toa/commit/ab19d2567764d5a3148b067f186819d7e646908f))
+
+
+# [1.0.0-alpha.295](https://github.com/toa-io/toa/compare/v1.0.0-alpha.294...v1.0.0-alpha.295) (2026-09-07)
+
+**Note:** Version bump only for package @toa.io/operations
+
+
+
+
+
+# [1.0.0-alpha.294](https://github.com/toa-io/toa/compare/v1.0.0-alpha.293...v1.0.0-alpha.294) (2026-09-07)
+
+**Note:** Version bump only for package @toa.io/operations
+
+
+
+
+
+# [1.0.0-alpha.293](https://github.com/toa-io/toa/compare/v1.0.0-alpha.292...v1.0.0-alpha.293) (2026-09-07)
+
+**Note:** Version bump only for package @toa.io/operations
+
+
+
+
+
+# [1.0.0-alpha.292](https://github.com/toa-io/toa/compare/v1.0.0-alpha.291...v1.0.0-alpha.292) (2026-09-07)
+
+### Features
+
+* **cli:** the deployment library is a peer, and the binary is the CLI's ([a923f81](https://github.com/toa-io/toa/commit/a923f8173a55ed1c091213a7c7db1863ca1d0ba6))
+* **norm:** a package's definition is read by one resolver ([bffd41c](https://github.com/toa-io/toa/commit/bffd41c8d18c42786b0bf321623088b9dabc4724))
+
+
+# [1.0.0-alpha.291](https://github.com/toa-io/toa/compare/v1.0.0-alpha.290...v1.0.0-alpha.291) (2026-09-07)
+
+**Note:** Version bump only for package @toa.io/operations
+
+
+
+
+
+# [1.0.0-alpha.290](https://github.com/toa-io/toa/compare/v1.0.0-alpha.289...v1.0.0-alpha.290) (2026-09-07)
+
+* fix(operations)!: an image starts as root again ([9eb0db7](https://github.com/toa-io/toa/commit/9eb0db75e3d02098fe75710280e8e15e63b73d57))
+* The runtime's environment is not a component's (#1070), closes [#1070](https://github.com/toa-io/toa/issues/1070)
+
+### BREAKING CHANGES
+
+* a component that read `process.env.TOA_*` reads `context` instead;
+  `echo(input)` no longer substitutes from the environment; a bash operation sees no
+  `TOA_*`; images no longer set `USER node` — see migrations/289.md.
+* an image built by alpha.289 runs its composition as `node` and
+  leaves the deployed environment readable under /proc; rebuild on 290. Nothing in
+  a context or a manifest changes.
+
+
+# [1.0.0-alpha.289](https://github.com/toa-io/toa/compare/v1.0.0-alpha.288...v1.0.0-alpha.289) (2026-09-07)
+
+* A deploy moves only what changed, and a component sees none of the runtime's environment (#1073) ([f38e3db](https://github.com/toa-io/toa/commit/f38e3db533f24db866c57bfa1ef294eff1eaf499)), closes [#1073](https://github.com/toa-io/toa/issues/1073) [#1064](https://github.com/toa-io/toa/issues/1064) [#1066](https://github.com/toa-io/toa/issues/1066) [#1067](https://github.com/toa-io/toa/issues/1067) [#1068](https://github.com/toa-io/toa/issues/1068) [#1069](https://github.com/toa-io/toa/issues/1069) [#1071](https://github.com/toa-io/toa/issues/1071) [#1070](https://github.com/toa-io/toa/issues/1070) [#1072](https://github.com/toa-io/toa/issues/1072)
+
+### BREAKING CHANGES
+
+* a component that read `process.env.TOA_*` reads `context` instead;
+  `echo(input)` no longer substitutes from the environment; a bash operation sees no
+  `TOA_*`; images no longer set `USER node` — see migrations/289.md.
+
+
+# [1.0.0-alpha.288](https://github.com/toa-io/toa/compare/v1.0.0-alpha.287...v1.0.0-alpha.288) (2026-09-06)
+
+**Note:** Version bump only for package @toa.io/operations
+
+
+
+
+
+# [1.0.0-alpha.287](https://github.com/toa-io/toa/compare/v1.0.0-alpha.286...v1.0.0-alpha.287) (2026-09-06)
+
+**Note:** Version bump only for package @toa.io/operations

package/image/runtime.Dockerfile

@@ -0,0 +1,20 @@
+FROM node:24.14.0-alpine3.22
+
+ARG VERSION
+
+# installed locally rather than globally: the binary is @toa.io/cli's, which the runtime depends
+# on, and npm links a dependency's binaries only into a local `node_modules/.bin`
+WORKDIR /toa
+
+# what the install scripts of Toa's own dependencies may do, stated where npm reads it — the
+# project Toa is installed into, which every later `npm i --prefix /toa` of an image built on
+# this one installs into too. npm runs no script nobody allowed and warns about each, and the
+# one there is, msgpackr-extract's, only looks for the binary its optional dependency provides
+RUN echo '{ "private": true, "allowScripts": { "msgpackr-extract": false } }' > package.json
+
+# mounted rather than written: npm's cache is a hundred megabytes, and a layer keeps whatever
+# the command left behind
+RUN --mount=type=cache,target=/root/.npm,sharing=locked \
+  npm i @toa.io/runtime@${VERSION} --omit=dev
+
+ENV PATH=/toa/node_modules/.bin:$PATH

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@toa.io/operations",
-  "version": "1.0.0-alpha.33",
+  "version": "1.0.0-alpha.331",
+  "type": "module",
   "description": "Toa Deployment",
   "homepage": "https://toa.io",
   "author": {
@@ -16,23 +17,22 @@
     "url": "https://github.com/toa-io/toa/issues"
   },
   "engines": {
-    "node": ">= 18.0.0"
+    "node": ">= 24.0.0"
   },
   "publishConfig": {
     "access": "public"
   },
   "main": "src/index.js",
-  "types": "types/index.d.ts",
+  "types": "types/index.ts",
   "scripts": {
     "test": "echo \"Error: run tests from root\" && exit 1"
   },
   "dependencies": {
-    "@toa.io/filesystem": "1.0.0-alpha.33",
-    "@toa.io/generic": "1.0.0-alpha.33",
-    "@toa.io/norm": "1.0.0-alpha.33",
-    "@toa.io/yaml": "1.0.0-alpha.33",
-    "execa": "5.1.1",
-    "fs-extra": "11.1.1"
+    "@toa.io/generic": "1.0.0-alpha.330",
+    "@toa.io/kubernetes": "1.0.0-alpha.301",
+    "@toa.io/norm": "1.0.0-alpha.331",
+    "oxc-parser": "0.153.0",
+    "paseto": "4.0.1"
   },
-  "gitHead": "ef81cea49d8f8b3b248adaba62d4548bbeb39f80"
+  "gitHead": "e7020d160910ca4f0c2ff9040b3cbb4fca8ea41f"
 }

package/readme.md

@@ -1,9 +1,188 @@
 # Toa Operations
 
+## Installing
+
+`toa deploy`, `toa build`, `toa push`, `toa env`, `toa export` and `toa conceal` need this package
+beside the CLI. The runtime does not depend on it, so an application that deploys lists it with the
+runtime:
+
+```shell
+$ npm i -D @toa.io/runtime @toa.io/operations
+```
+
+A machine that only deploys needs no runtime and no extension:
+
+```shell
+$ npm i @toa.io/cli @toa.io/operations
+$ npx toa deploy production -p application
+```
+
+What the extensions declare is read from `@toa.io/definitions`, which the CLI brings; what they run
+is not needed to render a chart. `registry.services: build` is the exception: it builds an
+extension's service image from the installed package, so it needs the runtime installed beside
+this one. `published` does not.
+
+## Compositions
+
+A composition is deployed as one pod. Beside its components it may run extension services,
+which are otherwise each deployed on their own:
+
+```yaml
+# context.toa.yaml
+
+compositions:
+  - name: edge
+    components:
+      - todos.tasks
+    services:
+      - exposition
+```
+
+See [compositions](../documentation/compositions.md).
+
+## Evicted
+
+What Toa does not deploy for a context, whatever a composition lists. It stays part of the
+context, and is deployed by other means:
+
+```yaml
+# context.toa.yaml
+
+evicted:
+  components:
+    - todos.stats
+  services:
+    - exposition
+```
+
+Nothing an evicted component alone required is deployed either — its storage, the extensions it
+declared. `evicted@production` states it for one environment.
+
+See [compositions](../documentation/compositions.md#evicted).
+
+## Secrets
+
+A value that must not be in the chart is rendered as a reference to a Kubernetes secret, and the
+secret is the application's to deploy. A deploy reads the namespace it deploys into before it builds
+anything, and refuses where a key a workload would read is not there:
+
+```
+$ toa deploy production
+Secrets are not deployed: toa-mongodb.default/username, toa-mongodb.default/password
+```
+
+Required is what `toa export secrets` lists, less the keys it marks `(optional)`, plus the
+`registry.credentials` secret where a context names one. `toa deploy --dry` reads no cluster, and
+neither does anything else that reads a context: `toa env`, `toa export`, `toa build` and `toa push`.
+
+See [variables and secrets](../documentation/deployment.md#variables-and-secrets).
+
 ## Context
 
 ### Container Registry
 
+Deploy images default to `FROM ghcr.io/toa-io/runtime:<runtime.version>`
+(published with each Toa release). The base image already has `@toa.io/runtime`
+installed; composition/service Dockerfiles only install component dependencies.
+
+To use a custom base image, set `registry.build.image` (or `composition.image`).
+That image must provide the `toa` CLI, or install it via `registry.build.run`. The binary is
+`@toa.io/cli`'s, which the runtime depends on, so a local install puts it on the `PATH`:
+
+```yaml
+# context.toa.yaml
+
+registry:
+  build:
+    image: node:24.14.0-alpine3.22
+    run: |
+      npm i --prefix /toa @toa.io/runtime --omit=dev
+      ln -s /toa/node_modules/.bin/toa /usr/local/bin/toa
+```
+
+`/toa` is where it goes: what an extension needs for what a component declares is installed
+there, beside the extension that reads the declaration.
+
+#### Composition Images
+
+A composition is two images in one repository. `composition-<name>:deps-<hash>` is what its
+components depend on, installed on the base image: it is tagged by everything the install
+reads — the runtime version, the base image, the build options, each component's
+`package.json` (and `package-lock.json`, where there is one), and what the extensions install
+for what the components declare — and is built only when one of those changes. `composition-<name>:<hash>` is the sources laid over it in a single linked
+layer, so a deploy that changes code alone builds and pushes that layer, and neither
+downloads nor uploads the dependencies again. The same holds for `mono`.
+
+The sources are copied as files, so a component that links a directory in — sources it shares with
+another component — carries what the link points to, and a link the build cannot read fails the
+build. What is linked is source alone: dependencies are installed per component, from its own
+`package.json`.
+
+Beside each component's sources the layer carries `manifest.toa.json`, the manifest as this
+build normalised it. A composition reads it instead of normalising again, so it loads no
+bridge to read what a module declares; a workspace has no such file and is read as it always
+was. A component an extension ships has none either — its package is published long before any
+image is built — and is read from the digest `@toa.io/definitions` carries, which a deploy has
+always read. So nothing that runs reads a module's source, and `oxc-parser` is installed only
+where a manifest is normalised: a workspace and a deploy, both through `@toa.io/operations`. What a build cannot express there — a prototype in a directory of the application's own
+rather than in a package — fails the build, where before it failed the container.
+
+A pushed image builds on the `toa` container builder, whose registry exporter is what lays
+an image over a base it never pulled; `toa build` loads on the daemon's own.
+
+A dependency named by a moving git ref is installed when the dependencies image is built and
+not again until its manifest changes, so pin such a dependency to a commit and bump it there.
+
+An extension's heavy dependency is not installed with the extension: `@toa.io/extensions.storages`
+declares the AWS and Cloudinary SDKs as optional peers, so the base image carries neither. What a
+component declares is what a deploy installs — the storages named in its `manifest.toa.yaml`,
+resolved through the context's annotation to their providers' packages, installed into `/toa`
+beside the extension that reads them. A composition whose components declare no `s3` storage
+carries no AWS SDK, whatever the context declares for another composition. A workspace installs
+the same set with `toa npm`.
+
+#### Extension Service Images
+
+`registry.services` says where an extension service's image comes from.
+
+`build`, the default, builds one per service into `registry.base`. Its tag carries the
+runtime version, so every Toa release rebuilds them all.
+
+`published` deploys the image the extension ships and builds nothing:
+
+```yaml
+# context.toa.yaml
+
+registry:
+  services: published
+```
+
+The images are tagged with the runtime version:
+
+```
+ghcr.io/toa-io/extension-exposition-gateway:1.0.0-alpha.285
+ghcr.io/toa-io/extension-introspection-explorer:1.0.0-alpha.285
+ghcr.io/toa-io/extension-configuration-values:1.0.0-alpha.285
+```
+
+The cluster pulls them from `ghcr.io` rather than from `registry.base`. They are public and
+`registry.credentials` does not apply; a cluster that cannot reach `ghcr.io` needs `build`.
+
+The field is environment-scoped like the rest:
+
+```yaml
+# context.toa.yaml
+
+registry:
+  base@local: localhost:5000
+  base@production: registry.digitalocean.com/acme
+  services: published
+  services@local: build
+```
+
+An extension that states no image is built whatever this says, as is a service a
+composition runs in its own pod.
+
 #### Build Options
 
 ```yaml
@@ -40,3 +219,48 @@ a secret containing required credentials can be specified using `registry.creden
 registry:
   credentials: docker-credentials-secret-name
 ```
+
+The secret itself is not Toa's to create, and a deploy that does not find it in the cluster is
+[refused](#secrets).
+
+#### Toa images
+
+Each release publishes `ghcr.io/toa-io/runtime:<version>` and, beside it, `:alpha` or `:latest`.
+The extension services share that version:
+
+```
+ghcr.io/toa-io/extension-exposition-gateway:1.0.0-alpha.285
+ghcr.io/toa-io/extension-introspection-explorer:1.0.0-alpha.285
+ghcr.io/toa-io/extension-configuration-values:1.0.0-alpha.285
+```
+
+Untagged manifests are deleted. A prerelease older than 90 days, and not among the last 30, is
+deleted with the four service images of that version. `:alpha`, `:latest`, and a version without
+a pre-release suffix stay.
+
+An application still on a deleted prerelease cannot pull `registry.services: published` and cannot
+rebuild `FROM` that runtime. Images already in `registry.base` keep running. Stay inside the
+window, or pin a graduated release.
+
+#### Userspace images
+
+`toa deploy production` writes two tags on the same composition image (`mono` and a service
+`registry.services: build` built are the same):
+
+- `<name>:<hash>` — what the chart pins. A hash of the runtime and the sources. `toa push` writes
+  this tag and nothing else.
+- `<name>:production` — moved onto that image. The next production deploy moves it again.
+
+`deps-<hash>` is not tagged with the environment. Do not name an environment eight hex digits, or
+`deps-` plus eight: a retention job would treat it as a content tag.
+
+A job the application runs deletes every `<hash>` and `deps-<hash>` older than 7 days, except the
+last 5, except the image `:production` (or `:staging`, or `:latest`) currently names. Then:
+
+```shell
+$ doctl registries garbage-collection start --include-untagged-manifests <registry>
+```
+
+Rollback is only those 7 days, those last 5, and whatever the environment tag still names. Turn
+the job on after the first deploy that writes that tag. The first garbage collection returns the
+space the old tags held, and blocks pushes while it runs.

package/src/deployment/.deployment/.describe/components.js

@@ -1,10 +1,8 @@
-'use strict'
-
 /**
  * @param {toa.deployment.Composition[]} compositions
  * @returns {string[]}
  */
-const components = (compositions) => {
+export const components = (compositions) => {
   /** @type {Set<string>} */
   const components = new Set()
 
@@ -16,5 +14,3 @@ const components = (compositions) => {
 
   return Array.from(components)
 }
-
-exports.components = components