@toa.io/norm 1.0.0-alpha.3 → 1.0.0-alpha.300

package/CHANGELOG.md

@@ -0,0 +1,124 @@
+# 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.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.3",
+  "version": "1.0.0-alpha.300",
+  "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.3",
-    "@toa.io/generic": "1.0.0-alpha.3",
-    "@toa.io/schema": "1.0.0-alpha.3",
-    "@toa.io/schemas": "1.0.0-alpha.3",
-    "@toa.io/yaml": "1.0.0-alpha.3"
+    "@toa.io/core": "1.0.0-alpha.300",
+    "@toa.io/definitions": "1.0.0-alpha.300",
+    "@toa.io/generic": "1.0.0-alpha.292",
+    "@toa.io/prototype": "1.0.0-alpha.300",
+    "@toa.io/schemas": "1.0.0-alpha.299",
+    "fast-glob": "3.3.3"
   },
-  "gitHead": "e36ac7871fc14d15863aaf8f9bbdeace8bdfa9f0"
+  "gitHead": "f91131a9aeb29aa271f177c4055ddcf0cda8c75e"
 }

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,10 @@ 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'
 }
-
-exports.extensions = extensions

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

@@ -1,17 +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')
-
-exports.bridge = bridge
-exports.entity = entity
-exports.events = events
-exports.extensions = extensions
-exports.operations = operations
-exports.properties = properties
-exports.receivers = receivers
+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

@@ -0,0 +1,55 @@
+import { join } from 'node:path'
+import { createHash } from 'node:crypto'
+import fs from 'node:fs/promises'
+
+export async function version(manifest) {
+  manifest.version ??= await hash(manifest.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.
+ *
+ * What the image excludes cannot change it: `node_modules` is in the `.dockerignore` the
+ * build writes (see `operations/src/deployment/images/image.js`), so hashing it would only
+ * retag an identical image after a local install.
+ */
+async function hash(path) {
+  const files = (await list(path)).sort()
+  const digests = await Promise.all(files.map((file) => digest(join(path, file))))
+  const total = createHash('sha256')
+
+  // 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} root
+ * @param {string} [path] relative
+ * @param {string[]} [acc]
+ * @returns {Promise<string[]>} paths relative to `root`
+ */
+async function list(root, path = '', acc = []) {
+  const entries = await fs.readdir(join(root, path), { withFileTypes: true })
+
+  for (const entry of entries) {
+    if (EXCLUDED.has(entry.name)) continue
+
+    const relative = path === '' ? entry.name : `${path}/${entry.name}`
+
+    if (entry.isDirectory()) await list(root, relative, acc)
+    else if (entry.isFile()) acc.push(relative)
+  }
+
+  return acc
+}
+
+async function digest(path) {
+  return createHash('sha256')
+    .update(await fs.readFile(path))
+    .digest()
+}
+
+const EXCLUDED = new Set(['node_modules', '.git'])

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,20 @@
-'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 ??= {}
 
     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

package/src/.component/collapse.js

@@ -1,8 +1,6 @@
-'use strict'
+import { merge } from '@toa.io/generic'
 
-const { merge } = require('@toa.io/generic')
-
-const collapse = (manifest, prototype) => {
+export const collapse = (manifest, prototype) => {
   delete manifest.prototype
 
   if (prototype.operations) {
@@ -14,7 +12,8 @@ const collapse = (manifest, prototype) => {
       if (manifest.operations === undefined) manifest.operations = {}
 
       for (let [endpoint, operation] of operations) {
-        if (manifest.operations[endpoint] === undefined) manifest.operations[endpoint] = {}
+        if (manifest.operations[endpoint] === undefined)
+          manifest.operations[endpoint] = {}
         else {
           const { virtual, ...real } = operation
 
@@ -26,7 +25,8 @@ const collapse = (manifest, prototype) => {
         merge(manifest.operations[endpoint], declaration)
 
         if (bridge !== undefined) {
-          if (manifest.prototype.operations === undefined) manifest.prototype.operations = {}
+          if (manifest.prototype.operations === undefined)
+            manifest.prototype.operations = {}
 
           manifest.prototype.operations[endpoint] = { bridge }
         }
@@ -36,13 +36,64 @@ const collapse = (manifest, prototype) => {
 
   const { entity, events, extensions } = prototype
 
-  if (manifest.entity?.schema?.properties.id !== undefined && entity?.schema?.properties.id !== undefined) {
+  if (
+    manifest.entity?.properties?.id !== undefined &&
+    entity?.properties?.id !== undefined
+  ) {
     manifest.entity.custom = true
 
-    delete prototype.entity.schema.properties.id
+    delete prototype.entity.properties.id
   }
 
+  /*
+   * `id` is the only one a component may state for itself. The rest are written by the runtime
+   * and read by it, so one redeclared here would be merged over what the prototype says and
+   * change what the record holds, or what a criterion against it compares — without the
+   * component that wrote it having anything to do with either.
+   */
+  for (const name of SYSTEM)
+    if (
+      manifest.entity?.properties?.[name] !== undefined &&
+      entity?.properties?.[name] !== undefined
+    )
+      throw new Error(`System property '${name}' cannot be overridden`)
+
+  if (prototype.events !== undefined && manifest.events !== undefined)
+    for (const event of Object.keys(prototype.events))
+      if (event in manifest.events) delete prototype.events[event]
+
+  if (entity?.migrations !== undefined) inherit(manifest, prototype)
+
   merge(manifest, { entity, events, extensions })
 }
 
-exports.collapse = collapse
+/**
+ * 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', 'REGION']

package/src/.component/defaults.js

@@ -1,11 +1,11 @@
-'use strict'
-
-const { hash } = require('@toa.io/generic')
-const assert = require('node:assert')
+import { hash } from '@toa.io/generic'
 
 // these defaults are required before validation
-const defaults = (manifest) => {
-  if (manifest.name === undefined) manifest.name = protoName(manifest)
+export const defaults = (manifest, proto) => {
+  if (manifest.name === undefined)
+    if (proto) manifest.name = protoName(manifest)
+    else nameAfterDir(manifest)
+
   if (manifest.bindings === undefined) manifest.bindings = ['@toa.io/bindings.amqp']
   if (manifest.bridge === undefined) manifest.bridge = '@toa.io/bridges.node'
 
@@ -13,30 +13,21 @@ const defaults = (manifest) => {
     if (manifest.entity.storage === null)
       manifest.entity.storage = '@toa.io/storages.null'
   } else {
-    if (manifest.prototype === undefined)
-      manifest.prototype = null
+    if (manifest.prototype === undefined) manifest.prototype = null
   }
 
   if (manifest.prototype === undefined) manifest.prototype = '@toa.io/prototype'
-
-  // TODO: bridge.version()
-
-  if (manifest.version === undefined) {
-    const bridge = require(manifest.bridge)
-
-    if ('version' in bridge)
-      manifest.version = bridge.version(manifest)
-  }
-
-  if (manifest.version === undefined) {
-    console.warn(`Component '${manifest.namespace ? manifest.namespace + '.' : ''}${manifest.name}' has no version`)
-
-    manifest.version = Math.random().toString(36).slice(2)
-  }
 }
 
-function protoName (manifest) {
+function protoName(manifest) {
   return 'proto' + hash(manifest.path)
 }
 
-exports.defaults = defaults
+function nameAfterDir(manifest) {
+  const parts = manifest.path.split('/')
+  const dirname = parts[parts.length - 1]
+  const [name, namespace] = dirname.split('.').reverse()
+
+  manifest.name = name
+  manifest.namespace = namespace
+}

package/src/.component/dependencies.js

@@ -1,29 +1,33 @@
-'use strict'
+import { createRequire } from 'node:module'
+import { join, dirname } from 'node:path'
 
-const { join, dirname } = require('node:path')
+// import.meta.resolve takes no paths, and a storage is resolved against the
+// component that names it
+const require = createRequire(import.meta.url)
 
 /**
  * @param {toa.norm.Component} component
  */
-const dependencies = (component) => {
-  if ('entity' in component) component.entity.storage = resolve(component.path, component.entity.storage)
+export const dependencies = (component) => {
+  if ('entity' in component)
+    component.entity.storage = resolve(component.path, component.entity.storage)
 }
 
-function resolve (root, reference) {
-  const paths = [root, __dirname]
+function resolve(root, reference) {
+  const paths = [root, import.meta.dirname]
   const options = { paths }
 
   let path
 
-  try { // as package
+  try {
+    // as package
     const packageJsonRef = join(reference, 'package.json')
 
     path = require.resolve(packageJsonRef, options)
-  } catch { // as directory
+  } catch {
+    // as directory
     path = require.resolve(reference, options)
   }
 
   return dirname(path)
 }
-
-exports.dependencies = dependencies