@toa.io/operations 1.0.0-alpha.280 → 1.0.0-alpha.283

package/CHANGELOG.md

@@ -3,6 +3,25 @@
 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.283](https://github.com/toa-io/toa/compare/v1.0.0-alpha.282...v1.0.0-alpha.283) (2026-09-04)
+
+### Bug Fixes
+
+* **lint:** lint the operations package ([aab0db5](https://github.com/toa-io/toa/commit/aab0db5ebcec05f5f49db716b86ea71f4377cfe3))
+
+### Features
+
+* **operations:** run extension services inside a composition ([154aced](https://github.com/toa-io/toa/commit/154aced047228a250ac3bab353e09432fcc5a34d))
+
+
+# [1.0.0-alpha.282](https://github.com/toa-io/toa/compare/v1.0.0-alpha.281...v1.0.0-alpha.282) (2026-09-03)
+
+**Note:** Version bump only for package @toa.io/operations
+
+
+
+
+
 # [1.0.0-alpha.280](https://github.com/toa-io/toa/compare/v1.0.0-alpha.279...v1.0.0-alpha.280) (2026-09-03)
 
 ### Bug Fixes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/operations",
-  "version": "1.0.0-alpha.280",
+  "version": "1.0.0-alpha.283",
   "type": "module",
   "description": "Toa Deployment",
   "homepage": "https://toa.io",
@@ -28,11 +28,11 @@
     "test": "echo \"Error: run tests from root\" && exit 1"
   },
   "dependencies": {
-    "@toa.io/generic": "1.0.0-alpha.278",
-    "@toa.io/norm": "1.0.0-alpha.278",
+    "@toa.io/generic": "1.0.0-alpha.283",
+    "@toa.io/norm": "1.0.0-alpha.283",
     "execa": "10.0.1",
     "fs-extra": "11.4.0",
     "js-yaml": "5.4.1"
   },
-  "gitHead": "2cf23f576c46efbe56c21427d877cef3e7ed98d4"
+  "gitHead": "2f52b023bed0ccb2ecdb2b82fe59fbe38bf282e1"
 }

package/readme.md

@@ -1,5 +1,23 @@
 # Toa Operations
 
+## 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).
+
 ## Context
 
 ### Container Registry

package/src/deployment/.deployment/.describe/compositions.js

@@ -1,10 +1,26 @@
 import { addVariables } from './variables.js'
 import { addMounts } from './mounts.js'
+import { fold } from './fold.js'
 
 export function compositions (compositions, dependency) {
   for (const composition of compositions) {
-    addVariables(composition, dependency.variables)
-    addMounts(composition, dependency.mounts)
+    const claimed = (dependency.services ?? [])
+      .filter((service) => service.workload?.includes(composition.name) === true)
+
+    // a service brings components of its own — the identity components inside the gateway —
+    // and their variables are keyed by their own labels, not by the composition's
+    const keys = composition.components
+      .concat(...claimed.map((service) => service.components ?? []))
+
+    addVariables(composition, dependency.variables, keys)
+    addMounts(composition, dependency.mounts, keys)
+
+    if (claimed.length > 0) {
+      // the label each hosted service's own Service selects on
+      composition.hosted = claimed.map((service) => service.name)
+
+      fold(composition, claimed, dependency)
+    }
 
     if (dependency.probe !== undefined && dependency.probe !== false)
       composition.probe ??= dependency.probe

package/src/deployment/.deployment/.describe/fold.js

@@ -0,0 +1,35 @@
+/**
+ * What a workload takes on by running services in its own pod: their variables, the ports
+ * they bind, and a readiness probe answered by one of them rather than by the workload.
+ *
+ * What it does *not* take on is how they are reached. A composition-hosted service keeps
+ * its own Service and Ingress — only the pods behind them change — so the ingress union
+ * belongs to `mono`, the one workload that fronts every service under a single name.
+ *
+ * @param {object} workload
+ * @param {toa.deployment.dependency.Service[]} services
+ * @param {toa.deployment.Dependency} dependency
+ */
+export function fold (workload, services, dependency) {
+  workload.variables ??= []
+
+  for (const service of services) {
+    if (service.variables !== undefined)
+      for (const variable of service.variables)
+        if (!workload.variables.some((item) => item.name === variable.name))
+          workload.variables.push(variable)
+
+    // every declared port is bound by the single process, none is primary
+    if (service.port !== undefined)
+      (workload.backends ??= []).push({ port: service.port, path: service.ingress?.path ?? '/' })
+
+    if (service.probe !== undefined && service.probe !== false)
+      workload.probe = service.probe
+  }
+
+  if (workload.probe === undefined && dependency.probe !== undefined && dependency.probe !== false)
+    workload.probe = dependency.probe
+
+  // the more specific prefix must come first, whatever the controller's tie-break
+  workload.backends?.sort((a, b) => b.path.length - a.path.length)
+}

package/src/deployment/.deployment/.describe/fold.test.js

@@ -0,0 +1,92 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { fold } from './fold.js'
+
+const service = (name, extra = {}) => ({ group: 'group', name, version: '0', ...extra })
+
+it('should collect the ports of every service', () => {
+  const workload = {}
+
+  fold(workload, [service('one', { port: 8000 }), service('two', { port: 8002 })], {})
+
+  assert.deepStrictEqual(workload.backends,
+    [{ port: 8000, path: '/' }, { port: 8002, path: '/' }])
+})
+
+it('should take the path a service declares', () => {
+  const workload = {}
+
+  fold(workload, [service('one', { port: 8002, ingress: { path: '/explorer' } })], {})
+
+  assert.deepStrictEqual(workload.backends, [{ port: 8002, path: '/explorer' }])
+})
+
+it('should put the more specific prefix first', () => {
+  const workload = {}
+
+  fold(workload, [
+    service('one', { port: 8000, ingress: { path: '/' } }),
+    service('two', { port: 8002, ingress: { path: '/explorer' } })
+  ], {})
+
+  assert.deepStrictEqual(workload.backends.map((backend) => backend.path), ['/explorer', '/'])
+})
+
+it('should leave a service without a port out of the backends', () => {
+  const workload = {}
+
+  fold(workload, [service('one')], {})
+
+  assert.strictEqual(workload.backends, undefined)
+})
+
+describe('variables', () => {
+  it('should take those of every service', () => {
+    const workload = {}
+
+    fold(workload, [
+      service('one', { variables: [{ name: 'A', value: '1' }] }),
+      service('two', { variables: [{ name: 'B', value: '2' }] })
+    ], {})
+
+    assert.deepStrictEqual(workload.variables, [{ name: 'A', value: '1' }, { name: 'B', value: '2' }])
+  })
+
+  it('should keep the first of a name', () => {
+    const workload = { variables: [{ name: 'A', value: 'own' }] }
+
+    fold(workload, [service('one', { variables: [{ name: 'A', value: 'theirs' }] })], {})
+
+    assert.deepStrictEqual(workload.variables, [{ name: 'A', value: 'own' }])
+  })
+})
+
+describe('probe', () => {
+  const probe = { path: '/.ready', port: 8004 }
+  const fallback = { path: '/.ready', port: 8001 }
+
+  it('should take the probe of a service over the default', () => {
+    const workload = {}
+
+    fold(workload, [service('one', { port: 8000, probe })], { probe: fallback })
+
+    assert.deepStrictEqual(workload.probe, probe)
+  })
+
+  it('should fall back to the default', () => {
+    const workload = {}
+
+    fold(workload, [service('one', { port: 8000 })], { probe: fallback })
+
+    assert.deepStrictEqual(workload.probe, fallback)
+  })
+
+  it('should ignore a disabled probe', () => {
+    const workload = {}
+
+    fold(workload, [service('one', { port: 8000, probe: false })], { probe: false })
+
+    assert.strictEqual(workload.probe, undefined)
+  })
+})

package/src/deployment/.deployment/.describe/resources.js

@@ -28,6 +28,11 @@ function * units (values) {
   for (const composition of values.compositions ?? [])
     yield { deployment: composition, subject: `Composition '${composition.name}'` }
 
-  for (const service of values.services ?? [])
+  for (const service of values.services ?? []) {
+    // a service a composition runs has no deployment of its own to size; the composition
+    // it runs in states what the pod may take
+    if (service.workload !== undefined) continue
+
     yield { deployment: service, subject: `Service '${service.name}'` }
+  }
 }

package/src/deployment/.deployment/.describe/resources.test.js

@@ -0,0 +1,63 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { resources } from './resources.js'
+
+const declared = { cpu: ['100m', '1'], memory: ['100Mi', '1Gi'] }
+
+it('should take the declaration of a deployment', () => {
+  const values = { compositions: [{ name: 'edge', resources: declared }] }
+
+  resources({}, values)
+
+  assert.deepStrictEqual(values.compositions[0].resources, declared)
+})
+
+it('should fall back to the context', () => {
+  const values = { compositions: [{ name: 'edge' }] }
+
+  resources({ resources: declared }, values)
+
+  assert.deepStrictEqual(values.compositions[0].resources, declared)
+})
+
+it('should take `null` as an answer', () => {
+  const values = { compositions: [{ name: 'edge', resources: null }] }
+
+  assert.doesNotThrow(() => resources({ resources: declared }, values))
+  assert.strictEqual(values.compositions[0].resources, null)
+})
+
+describe('refusal', () => {
+  it('should refuse a composition that declares none', () => {
+    const values = { compositions: [{ name: 'edge' }] }
+
+    assert.throws(() => resources({}, values),
+      (error) => /^Composition 'edge' declares no resources\./.test(error.message))
+  })
+
+  it('should refuse a service that declares none', () => {
+    const values = { services: [{ name: 'exposition-gateway' }] }
+
+    assert.throws(() => resources({}, values),
+      (error) => /^Service 'exposition-gateway' declares no resources\./.test(error.message))
+  })
+
+  it('should refuse the mono deployment when it declares none', () => {
+    const values = { mono: {} }
+
+    assert.throws(() => resources({}, values),
+      (error) => /^The mono deployment declares no resources\./.test(error.message))
+  })
+
+  it('should not ask a service a composition runs', () => {
+    // it has no deployment of its own to size; the composition running it states the pod's
+    const values = {
+      compositions: [{ name: 'edge', resources: declared }],
+      services: [{ name: 'exposition-gateway', workload: ['edge'] }]
+    }
+
+    assert.doesNotThrow(() => resources({}, values))
+    assert.strictEqual(values.services[0].resources, undefined)
+  })
+})

package/src/deployment/.deployment/.describe/services.js

@@ -2,7 +2,9 @@ import { addVariables } from './variables.js'
 
 export function services (services, variables, probe, ingress) {
   for (const service of services) {
-    addVariables(service, variables)
+    // one a composition runs has no deployment of its own to carry them; the composition
+    // it runs in states them, and repeating them here is dead weight in the values
+    if (service.workload === undefined) addVariables(service, variables)
 
     if (service.probe === false)
       delete service.probe

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

@@ -3,6 +3,7 @@ import { addVariables } from './.describe/variables.js'
 import { addMounts } from './.describe/mounts.js'
 import { resources } from './.describe/resources.js'
 import { events } from './.describe/events.js'
+import { fold } from './.describe/fold.js'
 
 export const describe = (context, compositions, dependency, image) => {
   const { services } = dependency
@@ -120,16 +121,11 @@ function unit (context, dependency) {
   addVariables(mono, variables, Object.keys(variables))
   addMounts(mono, dependency.mounts, Object.keys(mounts))
 
-  for (const service of dependency.services ?? []) {
-    if (service.variables !== undefined)
-      for (const variable of service.variables)
-        if (!mono.variables.some((item) => item.name === variable.name))
-          mono.variables.push(variable)
-
-    // every declared port is bound by the single mono process, none is primary
-    if (service.port !== undefined)
-      (mono.backends ??= []).push({ port: service.port, path: service.ingress?.path ?? '/' })
+  fold(mono, dependency.services ?? [], dependency)
 
+  // mono is the one workload that fronts every service it runs under a single name,
+  // so it inherits how they are reached as well as what they run
+  for (const service of dependency.services ?? []) {
     // one Service fronts every backend, so its annotations are the union
     if (service.annotations !== undefined)
       mono.annotations = Object.assign(mono.annotations ?? {}, service.annotations)
@@ -143,16 +139,7 @@ function unit (context, dependency) {
       if (hosts !== undefined)
         mono.ingress.hosts = [...new Set([...(mono.ingress.hosts ?? []), ...hosts])]
     }
-
-    if (service.probe !== undefined && service.probe !== false)
-      mono.probe = service.probe
   }
 
-  if (mono.probe === undefined && dependency.probe !== undefined && dependency.probe !== false)
-    mono.probe = dependency.probe
-
-  // the more specific prefix must come first, whatever the controller's tie-break
-  mono.backends?.sort((a, b) => b.path.length - a.path.length)
-
   return mono
 }

package/src/deployment/.deployment/merge.js

@@ -35,28 +35,43 @@ export const merge = (dependencies) => {
 }
 
 /**
- * In Kubernetes these are separate pods, but `toa mono` and a local run put every
- * service in one process — so a port may be claimed once and only once.
+ * A workload that hosts services puts them in one process — `mono`, a composition that
+ * declares them, a local run — so within one a port may be claimed once and only once.
+ * A service deploying on its own is a pod of its own, and shares a port with nobody.
  */
 const reserve = (services, probe) => {
-  const claimed = new Map()
-
-  if (probe !== undefined && probe !== false)
-    claimed.set(probe.port, 'the readiness probe')
+  /** @type {Map<string, Map<number, string>>} */
+  const workloads = new Map()
 
   for (const service of services)
-    for (const [port, claimant] of ports(service)) {
-      const conflicting = claimed.get(port)
+    // a service several compositions run binds its ports in each of their pods
+    for (const workload of service.workload ?? [service.name]) {
+      let claimed = workloads.get(workload)
+
+      if (claimed === undefined) {
+        claimed = new Map()
+
+        if (probe !== undefined && probe !== false)
+          claimed.set(probe.port, 'the readiness probe')
+
+        workloads.set(workload, claimed)
+      }
+
+      for (const [port, claimant] of ports(service)) {
+        const conflicting = claimed.get(port)
 
-      if (conflicting !== undefined)
-        throw new Error(`Port ${port} is claimed by both ${conflicting} and ${claimant}`)
+        if (conflicting !== undefined)
+          throw new Error(`Port ${port} is claimed by both ${conflicting} and ${claimant}` +
+            (service.workload === undefined ? '' : ` in '${workload}'`))
 
-      claimed.set(port, claimant)
+        claimed.set(port, claimant)
+      }
     }
 }
 
 function * ports (service) {
-  const name = `'${service.group}-${service.name}'`
+  // every service reaching here is named the way it is deployed, `<group>-<name>`
+  const name = `'${service.name}'`
 
   if (service.port !== undefined)
     yield [service.port, name]

package/src/deployment/.deployment/merge.test.js

@@ -3,7 +3,8 @@ import assert from 'node:assert/strict'
 
 import { merge } from './merge.js'
 
-const service = (name, extra = {}) => ({ group: 'group', name, version: '0', ...extra })
+// a service is named the way it is deployed by the time it reaches `merge`
+const service = (name, extra = {}) => ({ group: 'group', name: `group-${name}`, version: '0', ...extra })
 
 it('should merge services of all dependencies', () => {
   const merged = merge([
@@ -15,17 +16,46 @@ it('should merge services of all dependencies', () => {
 })
 
 /*
- * In Kubernetes these are separate pods, but `toa mono` and a local run put every
- * service in one process.
+ * A workload that hosts services puts them in one process, so a port is claimed once
+ * within one. Services in separate pods share nothing.
  */
 describe('port reservation', () => {
-  it('should reject two services claiming one port', () => {
+  const hosted = (name, extra = {}) => service(name, { workload: ['mono'], ...extra })
+
+  it('should reject two services of one workload claiming one port', () => {
+    const dependencies = [
+      { services: [hosted('one', { port: 8000 })] },
+      { services: [hosted('two', { port: 8000 })] }
+    ]
+
+    assert.throws(() => merge(dependencies), (error) => /Port 8000 is claimed by both 'group-one' and 'group-two' in 'mono'/.test(error.message))
+  })
+
+  it('should allow two workloads to claim one port', () => {
+    const dependencies = [
+      { services: [service('one', { port: 8000, workload: ['edge'] })] },
+      { services: [service('two', { port: 8000, workload: ['inner'] })] }
+    ]
+
+    assert.doesNotThrow(() => merge(dependencies))
+  })
+
+  it('should reserve the ports of a service in every workload running it', () => {
+    const dependencies = [
+      { services: [service('one', { port: 8000, workload: ['edge', 'inner'] })] },
+      { services: [service('two', { port: 8000, workload: ['inner'] })] }
+    ]
+
+    assert.throws(() => merge(dependencies), (error) => /Port 8000 is claimed by both 'group-one' and 'group-two' in 'inner'/.test(error.message))
+  })
+
+  it('should allow two services deployed on their own to claim one port', () => {
     const dependencies = [
       { services: [service('one', { port: 8000 })] },
       { services: [service('two', { port: 8000 })] }
     ]
 
-    assert.throws(() => merge(dependencies), (error) => /Port 8000 is claimed by both 'group-one' and 'group-two'/.test(error.message))
+    assert.doesNotThrow(() => merge(dependencies))
   })
 
   it('should reject a service claiming the port of the readiness probe', () => {
@@ -37,13 +67,13 @@ describe('port reservation', () => {
     assert.throws(() => merge(dependencies), (error) => /Port 8001 is claimed by both the readiness probe and 'group-one'/.test(error.message))
   })
 
-  it('should reject a probe claiming the port of another service', () => {
+  it('should reject a probe claiming the port of another service of the workload', () => {
     const dependencies = [
-      { services: [service('one', { port: 8000 })] },
-      { services: [service('two', { port: 8002, probe: { path: '/.ready', port: 8000 } })] }
+      { services: [hosted('one', { port: 8000 })] },
+      { services: [hosted('two', { port: 8002, probe: { path: '/.ready', port: 8000 } })] }
     ]
 
-    assert.throws(() => merge(dependencies), (error) => /Port 8000 is claimed by both 'group-one' and the readiness probe of 'group-two'/.test(error.message))
+    assert.throws(() => merge(dependencies), (error) => /Port 8000 is claimed by both 'group-one' and the readiness probe of 'group-two' in 'mono'/.test(error.message))
   })
 
   it('should allow a service to probe its own port', () => {

package/src/deployment/chart/templates/components.yaml

@@ -6,7 +6,7 @@ metadata:
 spec:
   type: ClusterIP
   selector:
-    {{ . }}: "1"
+    toa/component-{{ . }}: "1"
   ports:
     - name: http-binding
       protocol: TCP

package/src/deployment/chart/templates/compositions.yaml

@@ -10,13 +10,16 @@ spec:
   progressDeadlineSeconds: 900
   selector:
     matchLabels:
-      toa.io/composition: {{ .name }}
+      toa/composition: {{ .name }}
   template:
     metadata:
       labels:
-        toa.io/composition: {{ .name }}
+        toa/composition: {{ .name }}
         {{- range .components }}
-        {{ . }}: "1"
+        toa/component-{{ . }}: "1"
+        {{- end }}
+        {{- range .hosted }}
+        toa/service-{{ . }}: "1"
         {{- end }}
     spec:
       containers:
@@ -41,15 +44,26 @@ spec:
               {{- end }}
             {{- end }}
           {{- end }}          
-          {{- if .variables }}
+          {{- if or .variables .services }}
           env:
+            {{- if .services }}
+            - name: TOA_SERVICES
+              value: {{ join " " .services | quote }}
+            {{- end }}
             {{- range .variables }}
             {{- include "env.var" . | indent 12 }}
             {{- end }}
           {{- end }}
-          {{- if .probe }}
+          {{- if or .backends .probe }}
           ports:
+            {{- range .backends }}
+            - containerPort: {{ .port }}
+            {{- end }}
+            {{- if .probe }}
             - containerPort: {{ .probe.port }}
+            {{- end }}
+          {{- end }}
+          {{- if .probe }}
           startupProbe:
             httpGet:
               path: {{ .probe.path }}
@@ -98,6 +112,6 @@ spec:
           whenUnsatisfiable: ScheduleAnyway
           labelSelector:
             matchLabels:
-              toa.io/composition: {{ .name }}
+              toa/composition: {{ .name }}
 ---
 {{- end }}

package/src/deployment/chart/templates/mono.yaml

@@ -14,13 +14,13 @@ spec:
       maxSurge: 50%
   selector:
     matchLabels:
-      toa.io/composition: mono
+      toa/composition: mono
   template:
     metadata:
       labels:
-        toa.io/composition: mono
+        toa/composition: mono
         {{- range .components }}
-        {{ . }}: "1"
+        toa/component-{{ . }}: "1"
         {{- end }}
     spec:
       containers:
@@ -109,7 +109,7 @@ spec:
           whenUnsatisfiable: ScheduleAnyway
           labelSelector:
             matchLabels:
-              toa.io/composition: mono
+              toa/composition: mono
 {{- if .backends }}
 ---
 apiVersion: v1
@@ -123,7 +123,7 @@ metadata:
 spec:
   type: ClusterIP
   selector:
-    toa.io/composition: mono
+    toa/composition: mono
   ports:
     {{- range .backends }}
     - name: port-{{ .port }}

package/src/deployment/chart/templates/services.yaml

@@ -1,4 +1,5 @@
 {{- range .Values.services }}
+{{- if not .workload }}
 apiVersion: apps/v1
 kind: Deployment
 metadata:
@@ -17,11 +18,12 @@ spec:
       maxSurge: 50%
   selector:
     matchLabels:
-      toa.io/service: extension-{{ .name }}
+      toa/service: extension-{{ .name }}
   template:
     metadata:
       labels:
-        toa.io/service: extension-{{ .name }}
+        toa/service: extension-{{ .name }}
+        toa/service-{{ .name }}: "1"
     spec:
       containers:
         - name: extension-{{ .name }}
@@ -81,7 +83,8 @@ spec:
           whenUnsatisfiable: ScheduleAnyway
           labelSelector:
             matchLabels:
-              toa.io/service: extension-{{ .name }}
+              toa/service: extension-{{ .name }}
+{{- end }}
 {{- if .port }}
 ---
 apiVersion: v1
@@ -95,7 +98,7 @@ metadata:
 spec:
   type: ClusterIP
   selector:
-    toa.io/service: extension-{{ .name }}
+    toa/service-{{ .name }}: "1"
   ports:
     - name: port-{{ .port }}
       protocol: TCP

package/src/deployment/chart/values.yaml

@@ -25,11 +25,23 @@ compositions:
     replicas: 3
     components:
       - users-users
+    # the extensions whose services this composition runs in its own pod
+    services:
+      - '@toa.io/extensions.exposition'
+    # each of those, as its own Service selects it
+    hosted:
+      - exposition-gateway
+    # the ports they bind
+    backends:
+      - port: 8000
+        path: /
 components:
   - todos-tasks
   - todos-stats
   - users-users
 services:
+  # a service a composition runs carries `workload`, and gets no deployment of its own —
+  # its Service and Ingress stay, and select that composition's pods
   - name: resources-gateway
     image: localhost:5000/resources-gateway:0.0.0
     port: 8000

package/src/deployment/composition.js

@@ -9,6 +9,9 @@ export class Composition {
     this.image = image.reference
     this.components = composition.components.map(component)
     this.resources = composition.resources
+
+    // the extensions whose services this composition runs, as `TOA_SERVICES` for the process
+    if (composition.services !== undefined) this.services = composition.services
   }
 }
 

package/src/deployment/factory.js

@@ -23,6 +23,12 @@ export class Factory {
   #process
   #image
 
+  /** Which compositions run a given extension's service, rather than deploying it on its
+   *  own. A service is stateless and already runs several replicas, so several compositions
+   *  running one are replicas of it, behind the one Service that selects them all.
+   *  @type {Map<string, string[]>} */
+  #claims
+
   constructor (context, options = {}) {
     this.#context = context
     this.#mono = options.mono === true
@@ -31,6 +37,7 @@ export class Factory {
     const imagesFactory = new ImagesFactory(context.name, context.runtime, context.registry)
 
     this.#registry = new Registry(context.name, context.registry, imagesFactory, this.#process)
+    this.#claims = claims(context)
     this.#dependencies = this.#getDependencies()
     this.#compositions = []
 
@@ -71,12 +78,26 @@ export class Factory {
 
     if (this.#context.dependencies === undefined) return dependencies
 
+    /** the claimed references that turned out to contribute a service */
+    const contributing = new Set()
+
     for (const [reference, instances] of Object.entries(this.#context.dependencies)) {
       const dependency = await this.#getDependency(reference, instances)
 
-      if (dependency !== undefined) dependencies.push(dependency)
+      if (dependency === undefined) continue
+
+      if (dependency.services?.length > 0) contributing.add(reference)
+
+      dependencies.push(dependency)
     }
 
+    // this is the first point where every `deployment()` has run, so it is the first
+    // point where a reference that yields nothing can be told from one that yields a service
+    for (const [reference, compositions] of this.#claims)
+      if (!contributing.has(reference))
+        throw new Error(`Composition '${compositions[0]}' lists '${reference}', ` +
+          'which contributes no service.')
+
     return dependencies
   }
 
@@ -93,9 +114,16 @@ export class Factory {
     /** @type {toa.deployment.dependency.Declaration} */
     const dependency = module.deployment(instances, annotation)
 
+    // mono claims every service, including one an extension added since this context was
+    // written, so its claim is the wildcard rather than a list
+    const workload = this.#mono ? [MONO] : this.#claims.get(reference)
+
     /** @type {toa.deployment.Service[]} */
     const services = dependency.services?.map((service) =>
-      this.#mono ? service : this.#service(reference, service))
+      workload === undefined
+        ? this.#service(reference, service)   // its own deployment, its own image
+        // named the way `Service` would name it, since it skips that wrapper
+        : { ...service, name: `${service.group}-${service.name}`, workload })
 
     return { ...dependency, services }
   }
@@ -117,3 +145,22 @@ export class Factory {
     return new Factory(context, options)
   }
 }
+
+const MONO = 'mono'
+
+/**
+ * @param {toa.norm.Context} context
+ * @returns {Map<string, string[]>}
+ */
+function claims (context) {
+  const map = new Map()
+
+  for (const composition of context.compositions ?? [])
+    for (const reference of composition.services ?? []) {
+      if (!map.has(reference)) map.set(reference, [])
+
+      map.get(reference).push(composition.name)
+    }
+
+  return map
+}

package/src/deployment/images/image.js

@@ -38,13 +38,19 @@ export class Image {
     this.reference = posix.join(this.#registry.base ?? '', this.#scope, `${this.name}:${tag}`)
   }
 
-  get name () {}
+  /** @returns {string | undefined} */
+  get name () { return undefined }
 
-  get version () {}
+  /** @returns {string | undefined} */
+  get version () { return undefined }
 
-  get base () {}
+  /** The image to build `FROM`. Undefined takes the runtime's, which is what a service does.
+   *  @returns {string | undefined} */
+  get base () { return undefined }
 
-  get run () {}
+  /** Build commands to add. Undefined adds none, which is what a service does.
+   *  @returns {string | undefined} */
+  get run () { return undefined }
 
   async prepare (root) {
     if (this.dockerfile === undefined) throw new Error('Dockerfile isn\'t specified')

package/types/dependency.ts

@@ -13,6 +13,9 @@ export interface Service {
   variables?: Variable[]
   components?: string[]
   probe?: Probe | false
+  /** The workloads running this service, when compositions declared it instead of letting
+   *  it deploy on its own. Set by the deployment, never by an extension. */
+  workload?: string[]
 }
 
 export interface Variable {