@toa.io/norm 1.0.0-alpha.31 → 1.0.0-alpha.311

package/CHANGELOG.md

@@ -0,0 +1,216 @@
+# 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.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/norm
+
+
+
+
+
+# [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/norm
+
+
+
+
+
+# [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/norm
+
+
+
+
+
+# [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/norm
+
+
+
+
+
+# [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/norm
+
+
+
+
+
+# [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/norm
+
+
+
+
+
+# [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/norm
+
+
+
+
+
+# [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/norm
+
+
+
+
+
+# [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))
+* **telemetry:** let a component declare its own metrics ([05aa3c7](https://github.com/toa-io/toa/commit/05aa3c72cd6a160e1cef99df6176a7f627075bc0))
+
+
+# [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/norm
+
+
+
+
+
+# [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
+
+* **norm:** an operation that takes no input states none ([3b69b4c](https://github.com/toa-io/toa/commit/3b69b4c92b3f06361a3552f036a927f4ff32e58b))
+
+### Features
+
+* **norm:** an environment name may fall back along a colon-separated chain ([a267c1c](https://github.com/toa-io/toa/commit/a267c1caae816a75ada8352d5361b99817c72eb1))
+* **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(boot)!: a process is a thing, and an extension may keep something in one ([528d6cd](https://github.com/toa-io/toa/commit/528d6cdd307b45a6c30b6a184d7e06b3328cecf8))
+* feat(core)!: an operation may ask to run once ([dca616c](https://github.com/toa-io/toa/commit/dca616cb380a7a389e277875d3bd5ca55a6e4d45))
+
+### Features
+
+* **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))
+* **core:** an assignment may ask to run once as well ([10fbcbd](https://github.com/toa-io/toa/commit/10fbcbd86a5e82960e65f62c09d0a465ae8d0353))
+* **norm:** a context says what it does not deploy ([135e6fd](https://github.com/toa-io/toa/commit/135e6fdfbc4270762028e9e5a0516766960ce59c))
+
+### 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.
+* a composition booted directly has no readiness probe. Readiness is
+  the process's, and a composition is not a process. `stage.workload` boots one where a
+  suite needs it.
+
+
+# [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)
+
+### Features
+
+* **convergence:** deployments of one context converge ([8a70343](https://github.com/toa-io/toa/commit/8a70343cf6953aab58d4a25bac215508ff8d9a37))
+* **convergence:** what an extension ships converges too ([b3be33d](https://github.com/toa-io/toa/commit/b3be33d2a1db45cfd844288467441aea2f4a722d))
+* **core:** a record carries the region that wrote it ([13ed187](https://github.com/toa-io/toa/commit/13ed187604f06dec66feec2e26ccf9dae30bb048))
+
+
+# [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)
+
+**Note:** Version bump only for package @toa.io/norm
+
+
+
+
+
+# [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/norm
+
+
+
+
+
+# [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)
+
+**Note:** Version bump only for package @toa.io/norm
+
+
+
+
+
+# [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/norm
+
+
+
+
+
+# [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/norm
+
+
+
+
+
+# [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/norm
+
+
+
+
+
+# [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))
+* **definitions:** the version of Toa is the definitions package's ([3d0272e](https://github.com/toa-io/toa/commit/3d0272ea0ab862f4b6c2e58a2f003f92d0f8a87f))
+* **definitions:** what a package declares is read from one package ([7052341](https://github.com/toa-io/toa/commit/70523411b5d9e2b204c999aa02365173f3bb518d))
+* **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/norm
+
+
+
+
+
+# [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
+
+
+
+
+
+# [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/norm

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@toa.io/norm",
-  "version": "1.0.0-alpha.31",
+  "version": "1.0.0-alpha.311",
+  "type": "module",
   "description": "Toa declarations normalization and validation",
   "author": "temich <tema.gurtovoy@gmail.com>",
   "homepage": "https://github.com/toa-io/toa#readme",
@@ -20,11 +21,12 @@
     "test": "echo \"Error: run tests from root\" && exit 1"
   },
   "dependencies": {
-    "@toa.io/core": "1.0.0-alpha.31",
-    "@toa.io/generic": "1.0.0-alpha.31",
-    "@toa.io/schema": "1.0.0-alpha.31",
-    "@toa.io/schemas": "1.0.0-alpha.31",
-    "@toa.io/yaml": "1.0.0-alpha.31"
+    "@toa.io/core": "1.0.0-alpha.311",
+    "@toa.io/definitions": "1.0.0-alpha.311",
+    "@toa.io/generic": "1.0.0-alpha.311",
+    "@toa.io/prototype": "1.0.0-alpha.301",
+    "@toa.io/schemas": "1.0.0-alpha.311",
+    "fast-glob": "3.3.3"
   },
-  "gitHead": "91839a488176853a0731f49abc70dc7103ed7cca"
+  "gitHead": "4f45061964e275296a27ff8ff39f757ce27d4008"
 }

package/src/.component/.expand/bridge.js

@@ -1,9 +1,5 @@
-'use strict'
+import { resolve } from '../../shortcuts.js'
 
-const { resolve } = require('../../shortcuts')
-
-function bridge (manifest) {
+export function bridge(manifest) {
   manifest.bridge = resolve(manifest.bridge)
 }
-
-exports.bridge = bridge

package/src/.component/.expand/entity.js

@@ -1,14 +1,7 @@
-'use strict'
+import { resolve } from '../../shortcuts.js'
 
-const { expand } = require('@toa.io/schemas')
-
-const { resolve } = require('../../shortcuts')
-
-function entity (manifest) {
+export function entity(manifest) {
   if (!('entity' in manifest)) return
-  if ('schema' in manifest.entity) manifest.entity.schema = expand(manifest.entity.schema)
 
   manifest.entity.storage = resolve(manifest.entity.storage)
 }
-
-exports.entity = entity

package/src/.component/.expand/events.js

@@ -1,8 +1,6 @@
-'use strict'
+import { resolve } from '../../shortcuts.js'
 
-const { resolve } = require('../../shortcuts')
-
-function events (manifest) {
+export function events(manifest) {
   if (manifest.events === undefined) return
 
   for (const event of Object.values(manifest.events)) {
@@ -10,5 +8,3 @@ function events (manifest) {
     if (event.bridge !== undefined) event.bridge = resolve(event.bridge)
   }
 }
-
-exports.events = events

package/src/.component/.expand/extensions.js

@@ -1,8 +1,6 @@
-'use strict'
+import { recognize } from '../../shortcuts.js'
 
-const { recognize } = require('../../shortcuts')
-
-function extensions (manifest) {
+export function extensions(manifest) {
   recognize(SHORTCUTS, manifest, 'extensions')
   recognize(SHORTCUTS, manifest.extensions)
 }
@@ -10,11 +8,11 @@ function extensions (manifest) {
 const SHORTCUTS = {
   exposition: '@toa.io/extensions.exposition',
   realtime: '@toa.io/extensions.realtime',
-  origins: '@toa.io/extensions.origins',
   configuration: '@toa.io/extensions.configuration',
   state: '@toa.io/extensions.state',
   stash: '@toa.io/extensions.stash',
-  storages: '@toa.io/extensions.storages'
+  storages: '@toa.io/extensions.storages',
+  cadence: '@toa.io/extensions.cadence',
+  introspection: '@toa.io/extensions.introspection',
+  telemetry: '@toa.io/extensions.telemetry'
 }
-
-exports.extensions = extensions

package/src/.component/.expand/index.js

@@ -1,19 +1,7 @@
-'use strict'
-
-const { bridge } = require('./bridge')
-const { entity } = require('./entity')
-const { events } = require('./events')
-const { extensions } = require('./extensions')
-const { operations } = require('./operations')
-const { properties } = require('./properties')
-const { receivers } = require('./receivers')
-const { version } = require('./version')
-
-exports.bridge = bridge
-exports.entity = entity
-exports.events = events
-exports.extensions = extensions
-exports.operations = operations
-exports.properties = properties
-exports.receivers = receivers
-exports.version = version
+export { bridge } from './bridge.js'
+export { entity } from './entity.js'
+export { events } from './events.js'
+export { extensions } from './extensions.js'
+export { operations } from './operations.js'
+export { receivers } from './receivers.js'
+export { version } from './version.js'

package/src/.component/.expand/operations.js

@@ -1,14 +1,9 @@
-'use strict'
+import { resolve } from '../../shortcuts.js'
 
-const { expand } = require('@toa.io/schemas')
-const { resolve } = require('../../shortcuts')
-
-function operations (manifest) {
+export function operations(manifest) {
   if (manifest.operations === undefined) return
 
   for (const operation of Object.values(manifest.operations)) {
-    if (operation.input !== undefined) operation.input = expand(operation.input)
-    if (operation.output !== undefined) operation.output = expand(operation.output)
     if (operation.bridge !== undefined) operation.bridge = resolve(operation.bridge)
 
     if (operation.bindings !== undefined && operation.bindings !== null) {
@@ -16,5 +11,3 @@ function operations (manifest) {
     }
   }
 }
-
-exports.operations = operations

package/src/.component/.expand/receivers.js

@@ -1,16 +1,13 @@
-'use strict'
+import { resolve } from '../../shortcuts.js'
 
-const { resolve } = require('../../shortcuts')
-
-function receivers (manifest) {
+export function receivers(manifest) {
   if (manifest.receivers === undefined) return
 
   for (const [locator, receiver] of Object.entries(manifest.receivers)) {
-    if (typeof receiver === 'string') manifest.receivers[locator] = { operation: receiver }
+    if (typeof receiver === 'string')
+      manifest.receivers[locator] = { operation: receiver }
 
     if (receiver.binding !== undefined) receiver.binding = resolve(receiver.binding)
     if (receiver.bridge !== undefined) receiver.bridge = resolve(receiver.bridge)
   }
 }
-
-exports.receivers = receivers

package/src/.component/.expand/version.js

@@ -1,45 +1,84 @@
-'use strict'
+import { join } from 'node:path'
+import { createHash } from 'node:crypto'
+import fs from 'node:fs/promises'
+import glob from 'fast-glob'
 
-const { join } = require('node:path')
-const { createHash } = require('node:crypto')
-const fs = require('node:fs/promises')
-const { createReadStream } = require('node:fs')
-const { once } = require('node:events')
+import { definition } from '../../definition.js'
 
-async function version (manifest) {
-  manifest.version ??= await hash(manifest.path)
+export async function version(manifest) {
+  manifest.version ??= await hash(manifest)
 }
 
-async function hash (path) {
-  const hash = await hashd(path)
+/**
+ * Identifies a build of a component: it becomes the tag of its image, so it must be the
+ * same for the same sources and different for different ones — on any machine, and whichever
+ * build produced them.
+ *
+ * What a build leaves out cannot change it: the bridge states what no build ships, a component
+ * adds to that with `ignore` and puts one back with `!`, and `files` names what its version is
+ * made of where a build copies only some of it. Its manifest is always one of them, because
+ * what it declares is what a caller is held to.
+ */
+async function hash(manifest) {
+  const files = (await list(manifest)).sort()
+  const digests = await Promise.all(files.map((file) => digest(join(manifest.path, file))))
+  const total = createHash('sha256')
 
-  return hash.digest('hex').slice(0, 8)
+  // the path is part of it: moving a file changes the build even if no content did
+  for (let i = 0; i < files.length; i++) total.update(files[i]).update(digests[i])
+
+  return total.digest('hex').slice(0, 8)
 }
 
 /**
- * @param {string} path
- * @param {import('node:crypto').Hash} hash
+ * @param {toa.norm.Component} manifest
+ * @returns {Promise<string[]>} paths relative to the component
  */
-async function hashd (path, hash = createHash('sha256')) {
-  const stat = await fs.stat(path)
+async function list(manifest) {
+  const files = await glob(patterns(manifest.files), {
+    cwd: manifest.path,
+    dot: true,
+    onlyFiles: true,
+    followSymbolicLinks: false,
+    ignore: await ignore(manifest)
+  })
+
+  // what a component declares is what a caller is held to, so its manifest is always one of them
+  if (!files.includes(MANIFEST) && (await exists(join(manifest.path, MANIFEST))))
+    files.push(MANIFEST)
 
-  if (stat.isFile()) {
-    const stream = createReadStream(path)
+  return files
+}
 
-    stream.pipe(hash, { end: false })
+/** A path names what is under it, and a pattern is taken as it is. */
+function patterns(files = ['**']) {
+  return files.flatMap((file) => (file.includes('*') ? [file] : [file, file + '/**']))
+}
 
-    return await once(stream, 'end')
-  }
+async function ignore(manifest) {
+  const { module } = await definition(manifest.bridge)
+  const stated = manifest.ignore ?? []
+  const back = new Set(
+    stated.filter((pattern) => pattern[0] === '!').map((pattern) => pattern.slice(1))
+  )
 
-  if (stat.isDirectory()) {
-    const entries = await fs.opendir(path)
+  return [
+    ...(module.ignore ?? []).filter((pattern) => !back.has(pattern)),
+    ...stated.filter((pattern) => pattern[0] !== '!')
+  ]
+}
 
-    for await (const entry of entries) {
-      await hashd(join(path, entry.name), hash)
-    }
+async function exists(path) {
+  return await fs
+    .access(path)
+    .then(() => true)
+    .catch(() => false)
+}
 
-    return hash
-  }
+async function digest(path) {
+  return createHash('sha256')
+    .update(await fs.readFile(path))
+    .digest()
 }
 
-exports.version = version
+const MANIFEST = 'manifest.toa.yaml'

package/src/.component/.normalize/entity.js

@@ -0,0 +1,7 @@
+export function entity(component) {
+  if (component.entity === undefined) return
+
+  component.entity.storage ??= '@toa.io/storages.mongodb'
+  component.entity.associated ??= false
+  component.entity.custom ??= false
+}

package/src/.component/.normalize/events.js

@@ -1,13 +1,25 @@
-'use strict'
+import { definition } from '../../definition.js'
 
-const events = (component) => {
+export const events = async (component) => {
   if (component.events === undefined) return
 
-  const binding = component.bindings.find((binding) => require(binding).properties.async === true)
+  const binding = await asynchronous(component.bindings)
 
   for (const event of Object.values(component.events)) {
     if (event.binding === undefined) event.binding = binding
+
+    event.conditioned ??= false
+    event.subjective ??= false
   }
 }
 
-exports.events = events
+/** The first binding that carries events, which only its module can say. */
+async function asynchronous(bindings) {
+  for (const binding of bindings) {
+    const { properties } = (await definition(binding)).module
+
+    if (properties.async === true) return binding
+  }
+
+  return undefined
+}

package/src/.component/.normalize/index.js

@@ -1,9 +1,4 @@
-'use strict'
-
-const { events } = require('./events')
-const { operations } = require('./operations')
-const { receivers } = require('./receivers')
-
-exports.events = events
-exports.operations = operations
-exports.receivers = receivers
+export { entity } from './entity.js'
+export { events } from './events.js'
+export { operations } from './operations.js'
+export { receivers } from './receivers.js'

package/src/.component/.normalize/operations.js

@@ -1,16 +1,23 @@
-'use strict'
-
-const operations = (component) => {
+export const operations = (component) => {
   if (component.operations === undefined) return
 
   for (const [endpoint, operation] of Object.entries(component.operations)) {
-    if (operation.type === 'computation' || operation.type === 'effect')
+    // what an operation of this type acquires, where it did not say
+    if (operation.type === 'computation' || operation.type === 'unmanaged') {
+      operation.scope = 'none'
       operation.query = false
+    } else if (operation.type === 'effect') operation.scope ??= 'none'
+
+    if (operation.scope === 'none') operation.query = false
+
+    // an operation that states no output states an empty schema, which every reply fits
+    operation.output ??= {}
+
+    // a bridge says an algorithm takes no input with `null`, which the manifest states as none
+    if (operation.input === null) delete operation.input
 
     if (operation.bindings === undefined) operation.bindings = component.bindings
     if (operation.bindings === null) operation.bindings = []
     if (operation.virtual === true) delete component.operations[endpoint]
   }
 }
-
-exports.operations = operations

package/src/.component/.normalize/receivers.js

@@ -1,6 +1,4 @@
-'use strict'
-
-function receivers (component) {
+export function receivers(component) {
   if (component.receivers === undefined) return
 
   const receivers = component.receivers
@@ -9,6 +7,9 @@ function receivers (component) {
     const segments = key.split('.')
     const source = value.source ?? 'default'
 
+    value.conditioned ??= false
+    value.adaptive ??= false
+
     if (source !== 'default') continue
     if (segments.length === 3) continue // already with a namespace
 
@@ -18,5 +19,3 @@ function receivers (component) {
     receivers[newKey] = value
   }
 }
-
-exports.receivers = receivers