@toa.io/norm 1.0.0-alpha.288 → 1.0.0-alpha.289

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 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.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/norm

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/norm",
-  "version": "1.0.0-alpha.288",
+  "version": "1.0.0-alpha.289",
   "type": "module",
   "description": "Toa declarations normalization and validation",
   "author": "temich <tema.gurtovoy@gmail.com>",
@@ -21,11 +21,11 @@
     "test": "echo \"Error: run tests from root\" && exit 1"
   },
   "dependencies": {
-    "@toa.io/core": "1.0.0-alpha.288",
-    "@toa.io/generic": "1.0.0-alpha.286",
-    "@toa.io/schemas": "1.0.0-alpha.287",
+    "@toa.io/core": "1.0.0-alpha.289",
+    "@toa.io/generic": "1.0.0-alpha.289",
+    "@toa.io/schemas": "1.0.0-alpha.289",
     "fast-glob": "3.3.3",
     "js-yaml": "5.4.1"
   },
-  "gitHead": "d3d696f0a4e287c3c297ac81028d600ad7574112"
+  "gitHead": "4fcb482beac5896305d8084cdbc1d5fcf372d108"
 }

package/src/.component/collapse.js

@@ -62,12 +62,38 @@ export const collapse = (manifest, prototype) => {
     for (const event of Object.keys(prototype.events))
       if (event in manifest.events) delete prototype.events[event]
 
-  // a migration is applied to a collection, and a prototype has none: what it declares belongs
-  // to the component that declared it, so it is not collapsed into this one
-  if (entity?.migrations !== undefined) delete entity.migrations
+  if (entity?.migrations !== undefined) inherit(manifest, prototype)
 
   merge(manifest, { entity, events, extensions })
 }
 
+/**
+ * What a prototype declares is in every record of its descendants, so its migrations are applied
+ * to each descendant's collection — ahead of the descendant's own, which are written against
+ * what they leave. An inherited one is recorded under the prototype's name, so that it collides
+ * with nothing the component names itself; one inherited from further up already carries its
+ * name and is passed on as it is.
+ */
+function inherit(manifest, prototype) {
+  const inherited = prototype.entity.migrations.map((migration) =>
+    migration.prototype === undefined
+      ? {
+          ...migration,
+          id: `${prototype.name}:${migration.id}`,
+          prototype: prototype.name
+        }
+      : migration
+  )
+
+  const own = manifest.entity?.migrations ?? []
+
+  if (manifest.entity === undefined) manifest.entity = {}
+
+  manifest.entity.migrations = [...inherited, ...own]
+
+  // merged below by `merge`, which would append them a second time
+  delete prototype.entity.migrations
+}
+
 /** What the runtime writes into every record. `id` is not among them: a component may own it. */
 const SYSTEM = ['VERSION', 'CREATED', 'UPDATED', 'DELETED']

package/src/.component/schema.yaml

@@ -100,6 +100,9 @@ properties:
             # what a step means belongs to the storage, which is the only thing that reads it
             steps:
               type: array
+            # the prototype it is inherited from; absent on the component's own
+            prototype:
+              type: string
           required: [id, steps]
           additionalProperties: false
       associated:

package/src/.context/normalize.js

@@ -13,8 +13,9 @@ export const normalize = (context) => {
 
   if (typeof context.registry === 'string') context.registry = { base: context.registry }
 
-  // what an image is built for, where the Context does not say
-  if (context.registry !== undefined) context.registry.platforms ??= PLATFORMS
+  // what an image is built for, where the Context does not say; `~` says the runner's own
+  if (context.registry !== undefined && context.registry.platforms === undefined)
+    context.registry.platforms = PLATFORMS
 }
 
 const PLATFORMS = ['linux/amd64', 'linux/arm/v7', 'linux/arm64']

package/src/component.js

@@ -37,12 +37,19 @@ const load = async (path, base, proto = false) => {
 
   manifest.path = path
 
+  const anonymous = manifest.name === undefined
+
   defaults(manifest, proto)
   await expand(manifest)
 
   await merge(path, manifest)
   await migrations(path, manifest)
 
+  // an inherited migration is recorded under the prototype's name, and a generated one is not
+  // the same on the next machine
+  if (proto && anonymous && manifest.entity?.migrations !== undefined)
+    throw new Error(`Prototype at '${path}' declares migrations, so it has to be named`)
+
   if (manifest.prototype !== null) {
     const prototype = await load(manifest.prototype, path, true)
 

package/src/context.js

@@ -1,5 +1,5 @@
 import { resolve } from 'node:path'
-import { convolve } from '@toa.io/generic'
+import { convolve, environment as variables } from '@toa.io/generic'
 import glob from 'fast-glob'
 import { readFile } from 'node:fs/promises'
 import { yaml as jsyaml } from '@toa.io/generic'
@@ -15,7 +15,7 @@ import {
   validate
 } from './.context/index.js'
 
-export const context = async (root, environment = process.env.TOA_ENV) => {
+export const context = async (root, environment = variables.get('TOA_ENV')) => {
   const path = resolve(root, CONTEXT)
   const context = /** @type {toa.norm.Context} */ await read(path)
 

package/test/component/collapse.test.js

@@ -50,7 +50,10 @@ describe('entity', () => {
 
   it('should refuse a component that states a property the runtime writes', () => {
     const prototype = { entity: { properties: { DELETED: { type: 'integer' } } } }
-    const manifest = { name: 'pot', entity: { properties: { DELETED: { type: 'integer' } } } }
+    const manifest = {
+      name: 'pot',
+      entity: { properties: { DELETED: { type: 'integer' } } }
+    }
 
     assert.throws(
       () => collapse(manifest, prototype),
@@ -58,25 +61,54 @@ describe('entity', () => {
     )
   })
 
-  it('should not inherit migrations', () => {
+  it('should inherit migrations ahead of its own, under the prototype name', () => {
     const manifest = { entity: { migrations: [{ id: '0002', steps: [] }] } }
-    const prototype = { entity: { migrations: [{ id: '0001', steps: [] }] } }
+    const prototype = {
+      name: 'base',
+      entity: { migrations: [{ id: '0001', steps: [] }] }
+    }
+
+    collapse(manifest, prototype)
+
+    assert.deepStrictEqual(manifest.entity.migrations, [
+      { id: 'base:0001', steps: [], prototype: 'base' },
+      { id: '0002', steps: [] }
+    ])
+  })
+
+  it('should pass on what the prototype inherited as it is', () => {
+    const manifest = { entity: { migrations: [{ id: '0002', steps: [] }] } }
+    const prototype = {
+      name: 'base',
+      entity: {
+        migrations: [
+          { id: 'system:0001', steps: [], prototype: 'system' },
+          { id: '0001', steps: [] }
+        ]
+      }
+    }
 
     collapse(manifest, prototype)
 
     assert.deepStrictEqual(
       manifest.entity.migrations.map(({ id }) => id),
-      ['0002']
+      ['system:0001', 'base:0001', '0002']
     )
   })
 
-  it('should leave a component with no migrations without any', () => {
+  it('should inherit migrations into a component that declares none', () => {
     const manifest = {}
-    const prototype = { entity: { migrations: [{ id: '0001', steps: [] }] } }
+    const prototype = {
+      name: 'base',
+      entity: { migrations: [{ id: '0001', steps: [] }] }
+    }
 
     collapse(manifest, prototype)
 
-    assert.strictEqual(manifest.entity?.migrations, undefined)
+    assert.deepStrictEqual(
+      manifest.entity.migrations.map(({ id }) => id),
+      ['base:0001']
+    )
   })
 })
 

package/test/context/normalize.test.js

@@ -47,3 +47,12 @@ it('should set default platforms', () => {
     'linux/arm64'
   ])
 })
+
+it('should keep platforms declared as none', () => {
+  // `platforms: ~` in the context: the runner's own platform, not the default list
+  context.registry = { base: generate(), platforms: null }
+
+  normalize(context)
+
+  assert.strictEqual(context.registry.platforms, null)
+})

package/types/component.d.ts

@@ -39,6 +39,8 @@ type Receiver = {
 type Migration = {
   id: string
   steps: unknown[]
+  /** the prototype it is inherited from; absent on the component's own */
+  prototype?: string
 }
 
 export type Entity = {