@toa.io/norm 1.0.0-alpha.298 → 1.0.0-alpha.299

package/CHANGELOG.md

@@ -3,6 +3,15 @@
 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.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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/norm",
-  "version": "1.0.0-alpha.298",
+  "version": "1.0.0-alpha.299",
   "type": "module",
   "description": "Toa declarations normalization and validation",
   "author": "temich <tema.gurtovoy@gmail.com>",
@@ -21,12 +21,12 @@
     "test": "echo \"Error: run tests from root\" && exit 1"
   },
   "dependencies": {
-    "@toa.io/core": "1.0.0-alpha.293",
-    "@toa.io/definitions": "1.0.0-alpha.298",
+    "@toa.io/core": "1.0.0-alpha.299",
+    "@toa.io/definitions": "1.0.0-alpha.299",
     "@toa.io/generic": "1.0.0-alpha.292",
-    "@toa.io/prototype": "1.0.0-alpha.289",
-    "@toa.io/schemas": "1.0.0-alpha.293",
+    "@toa.io/prototype": "1.0.0-alpha.299",
+    "@toa.io/schemas": "1.0.0-alpha.299",
     "fast-glob": "3.3.3"
   },
-  "gitHead": "334fad8726adfa7507462c33b509ce7db9db853f"
+  "gitHead": "2ba95b16f2cf06f82d6ff8d436761e843e5e4b43"
 }

package/src/.component/collapse.js

@@ -96,4 +96,4 @@ function inherit(manifest, prototype) {
 }
 
 /** What the runtime writes into every record. `id` is not among them: a component may own it. */
-const SYSTEM = ['VERSION', 'CREATED', 'UPDATED', 'DELETED']
+const SYSTEM = ['VERSION', 'CREATED', 'UPDATED', 'DELETED', 'REGION']

package/src/.component/schema.yaml

@@ -89,7 +89,7 @@ properties:
         type: object
         propertyNames:
           not:
-            enum: [id, VERSION, CREATED, UPDATED, DELETED]
+            enum: [id, VERSION, CREATED, UPDATED, DELETED, REGION]
       migrations:
         type: array
         items:

package/src/.context/.dependencies/extensions.js

@@ -1,4 +1,5 @@
 import { Locator } from '@toa.io/core'
+import { converge } from '../converge.js'
 import { component as load } from '../../component.js'
 import { definition } from '../../definition.js'
 
@@ -20,6 +21,9 @@ export const extensions = async (context) => {
 
   components.push(...extracted)
 
+  // after the extraction, because what an extension ships converges like anything else
+  converge(context, components)
+
   for (const component of components) {
     if (component.extensions === undefined) continue
 

package/src/.context/converge.js

@@ -0,0 +1,31 @@
+/**
+ * A context that declares convergence converges every component that stores anything, and no
+ * manifest says so. An extension is loaded, deployed and hooked because a component's
+ * `extensions` names it, so this is where they come to name it.
+ *
+ * **Including the components an extension ships**, which is why this runs where they are
+ * known rather than over what the context declares: an application deployed as two regions
+ * whose identity does not converge is one where a user registered in the first does not
+ * exist in the second.
+ *
+ * There is nothing per-component to normalize and nothing to opt out of: a region is
+ * infrastructure, and what a component stores is not its business. What is genuinely owned by
+ * one region — which delayed calls this one makes — is said where that is decided, in
+ * `cadence.regions`, and not by holding the records back.
+ *
+ * @param {toa.norm.Context} context
+ * @param {toa.norm.Component[]} components every component the context deploys
+ * @returns {void}
+ */
+export const converge = (context, components) => {
+  if (context.annotations?.[REFERENCE] === undefined) return
+
+  for (const component of components) {
+    if (component.entity === undefined) continue
+
+    component.extensions ??= {}
+    component.extensions[REFERENCE] ??= null
+  }
+}
+
+const REFERENCE = '@toa.io/extensions.convergence'

package/src/.context/index.js

@@ -1,4 +1,5 @@
 export { complete } from './complete.js'
+export { converge } from './converge.js'
 export { dependencies } from './dependencies.js'
 export { dereference } from './dereference.js'
 export { expand } from './expand.js'

package/src/context.js

@@ -30,6 +30,9 @@ export const context = async (root, environment = variables.get('TOA_ENV')) => {
   const paths = await glob(resolve(root, COMPONENTS), GLOB)
 
   context.components = await Promise.all(paths.map(component))
+
+  // what a context declares of every component that stores anything, its own and the ones its
+  // extensions bring, is given to them where those are known: inside `dependencies`
   context.dependencies = await dependencies(context)
 
   dereference(context)

package/src/shortcuts.js

@@ -48,5 +48,6 @@ export const SHORTCUTS = {
   storages: '@toa.io/extensions.storages',
   telemetry: '@toa.io/extensions.telemetry',
   cadence: '@toa.io/extensions.cadence',
+  convergence: '@toa.io/extensions.convergence',
   introspection: '@toa.io/extensions.introspection'
 }

package/test/context/converge.test.js

@@ -0,0 +1,57 @@
+import { it, beforeEach } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { converge } from '../../src/.context/index.js'
+
+const REFERENCE = '@toa.io/extensions.convergence'
+
+/** @type {object} */
+let context
+
+/** @type {object[]} */
+let components
+
+const component = (id, properties = {}) => ({ id, entity: {}, ...properties })
+
+beforeEach(() => {
+  context = { annotations: { [REFERENCE]: { priority: 0 } } }
+
+  components = [
+    component('store.orders'),
+    // what an extension ships reaches a deployment the same way and converges the same way:
+    // an application whose identity does not converge has no users in its second region
+    component('identity.basic'),
+    component('exposition.octets', { entity: undefined })
+  ]
+})
+
+it('should give the extension to every component that stores anything', () => {
+  converge(context, components)
+
+  assert.deepEqual(components[0].extensions, { [REFERENCE]: null })
+  assert.deepEqual(components[1].extensions, { [REFERENCE]: null })
+})
+
+it('should leave a component that stores nothing alone', () => {
+  converge(context, components)
+
+  assert.equal(components[2].extensions, undefined)
+})
+
+it('should do nothing where the context is not a region', () => {
+  delete context.annotations
+
+  converge(context, components)
+
+  for (const one of components) assert.equal(one.extensions, undefined)
+})
+
+it('should leave what a manifest declared as it was', () => {
+  const declaration = { some: 'declaration' }
+
+  components[0].extensions = { [REFERENCE]: declaration }
+
+  converge(context, components)
+
+  assert.equal(components[0].extensions[REFERENCE], declaration)
+})

package/test/context/validate.test.js

@@ -122,7 +122,7 @@ describe('compositions', () => {
 
     assert.throws(
       () => validate(context),
-      (error) => /Property compoments is not expected to be here/.test(error.message)
+      (error) => /must NOT have additional properties/.test(error.message)
     )
   })
 })