@toa.io/norm 1.0.0-alpha.313 → 1.0.0-alpha.315

package/CHANGELOG.md

@@ -3,6 +3,31 @@
 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.315](https://github.com/toa-io/toa/compare/v1.0.0-alpha.314...v1.0.0-alpha.315) (2026-09-23)
+
+* feat(map)!: leave out of a contract what the runtime gives every component ([b81837a](https://github.com/toa-io/toa/commit/b81837a3bc4771d7ee1c10fe613c9a1d7501bf1a))
+
+### BREAKING CHANGES
+
+* the deployed component map is `/etc/toa/.map.json.gz`.
+
+
+# [1.0.0-alpha.314](https://github.com/toa-io/toa/compare/v1.0.0-alpha.313...v1.0.0-alpha.314) (2026-09-19)
+
+* feat(core)!: let an operation state how long its calls are remembered ([af177c2](https://github.com/toa-io/toa/commit/af177c2ab3d00d475840b5ef9e612f04e82b72bd))
+* feat(core)!: rename trailers to the TRAILERS system property ([8d59ef9](https://github.com/toa-io/toa/commit/8d59ef90d04b7329578203fe10bd21fe41dfe2f5))
+
+### Features
+
+* **core:** a reference may name a declaration its package claims ([8040f60](https://github.com/toa-io/toa/commit/8040f60976549ab90497675bb54e664261f5b6bb))
+
+### BREAKING CHANGES
+
+* `inbox.retention` under 600 is refused. See
+  migrations/313.md.
+* `state._trailers` is `state.TRAILERS`; see migrations/313.md.
+
+
 # [1.0.0-alpha.313](https://github.com/toa-io/toa/compare/v1.0.0-alpha.312...v1.0.0-alpha.313) (2026-09-18)
 
 **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.313",
+  "version": "1.0.0-alpha.315",
   "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.312",
-    "@toa.io/definitions": "1.0.0-alpha.313",
+    "@toa.io/core": "1.0.0-alpha.315",
+    "@toa.io/definitions": "1.0.0-alpha.315",
     "@toa.io/generic": "1.0.0-alpha.311",
-    "@toa.io/prototype": "1.0.0-alpha.301",
+    "@toa.io/prototype": "1.0.0-alpha.315",
     "@toa.io/schemas": "1.0.0-alpha.311",
     "fast-glob": "3.3.3"
   },
-  "gitHead": "7da3b2627ceeefd1fa19d5c8851be88d928523b6"
+  "gitHead": "d88ed286bf44bf95b5f3d9db6e7d4621261dbb99"
 }

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

@@ -7,7 +7,7 @@ export function extensions(manifest) {
 
 const SHORTCUTS = {
   exposition: '@toa.io/extensions.exposition',
-  realtime: '@toa.io/extensions.realtime',
+  realtime: '@toa.io/extensions.exposition#realtime',
   configuration: '@toa.io/extensions.configuration',
   state: '@toa.io/extensions.state',
   stash: '@toa.io/extensions.stash',

package/src/.component/schema.yaml

@@ -101,7 +101,7 @@ properties:
         type: object
         propertyNames:
           not:
-            enum: [id, VERSION, CREATED, UPDATED, DELETED, REGION]
+            enum: [id, VERSION, CREATED, UPDATED, DELETED, REGION, TRAILERS]
       migrations:
         type: array
         items:
@@ -157,7 +157,12 @@ properties:
             enum: [none, retry]
           once:
             # the same call arriving twice changes state once; see documentation/inbox.md
-            type: boolean
+            # a number is how many seconds a call is remembered, which a deployment's
+            # `inbox.retention` is the default for; ten minutes at least, because the broker
+            # alone repeats a call for about that long. One type list rather than `oneOf`: the
+            # manifest is validated with coercion, and a branch would coerce `true` into `1`
+            type: [boolean, integer]
+            minimum: 600
           stateful:
             # served by every process under an address of its own, which a call names; see documentation/stateful.md
             type: boolean

package/src/.component/validate.js

@@ -25,6 +25,10 @@ export const validate = async (manifest) => {
 const entity = (manifest) => {
   const { properties, required, blank } = manifest.entity
 
+  // what an algorithm writes beside the record for the event of its commit; never stored
+  if (properties.TRAILERS !== undefined)
+    throw new Error("System property 'TRAILERS' cannot be declared")
+
   for (const name of required ?? [])
     if (properties[name] === undefined)
       throw new Error(`Entity requires property '${name}', which is not defined`)

package/src/.context/schema.yaml

@@ -164,9 +164,11 @@ properties:
           Seconds a call is remembered, which is the window a duplicate of it is caught in. Budget
           it for how late a duplicate can arrive — a redelivery, the attempts the broker library
           makes of a message, whatever a client retries on — rather than for how long the change
-          matters. Every call of an operation that declares `once` is a record for this long.
+          matters. Every call of an operation that declares `once: true` is a record for this
+          long; an operation that states a number of its own is kept for that instead. Ten minutes
+          at least, because the broker alone repeats a call for about that long.
         type: integer
-        minimum: 1
+        minimum: 600
   addressed:
     type: object
     additionalProperties: false

package/src/definition.js

@@ -31,10 +31,17 @@ async function load(reference) {
 
   if (known !== undefined) return { name: reference, module: known }
 
-  const name = metadata(reference)?.name ?? reference
-  const module = await import(pathToFileURL(resolve(reference)).href)
+  // `package#key` is a declaration of its own that a package claims beside its main one
+  const [path, key] = reference.split('#')
+  const name = (metadata(path)?.name ?? path) + (key === undefined ? '' : '#' + key)
+  const module = await import(pathToFileURL(resolve(path)).href)
 
-  return { name, module }
+  if (key === undefined) return { name, module }
+
+  if (module.keys?.[key] === undefined)
+    throw new Error(`'${reference}' names a key that '${path}' does not claim`)
+
+  return { name, module: module.keys[key] }
 }
 
 function resolve(reference) {

package/src/shortcuts.js

@@ -43,7 +43,7 @@ export const SHORTCUTS = {
   bash: '@toa.io/bridges.bash',
   mongodb: '@toa.io/storages.mongodb',
   exposition: '@toa.io/extensions.exposition',
-  realtime: '@toa.io/extensions.realtime',
+  realtime: '@toa.io/extensions.exposition#realtime',
   configuration: '@toa.io/extensions.configuration',
   stash: '@toa.io/extensions.stash',
   storages: '@toa.io/extensions.storages',

package/test/component/validate.test.js

@@ -115,6 +115,13 @@ describe('entity', () => {
       }
       await assert.doesNotReject(validate(manifest))
     })
+
+    it('should not declare TRAILERS', async () => {
+      manifest.entity.properties.TRAILERS = { type: 'object' }
+      await assert.rejects(validate(manifest), (error) =>
+        /System property 'TRAILERS' cannot be declared/.test(error.message)
+      )
+    })
   })
 
   describe('required', () => {
@@ -146,6 +153,13 @@ describe('entity', () => {
         /must NOT be valid/.test(error.message)
       )
     })
+
+    it('should not name TRAILERS', async () => {
+      manifest.entity.blank = { TRAILERS: {} }
+      await assert.rejects(validate(manifest), (error) =>
+        /must NOT be valid/.test(error.message)
+      )
+    })
   })
 })
 
@@ -257,6 +271,37 @@ describe('operations', () => {
     })
   })
 
+  describe('once', () => {
+    it('should be true, false or a number of seconds', async () => {
+      for (const once of [true, false, 600, 86400]) {
+        manifest.operations.add.once = once
+        await assert.doesNotReject(validate(manifest), `once: ${once}`)
+      }
+    })
+
+    it('should stay true rather than be coerced into a number', async () => {
+      manifest.operations.add.once = true
+      await validate(manifest)
+
+      assert.strictEqual(manifest.operations.add.once, true)
+    })
+
+    it('should not be a window shorter than ten minutes', async () => {
+      manifest.operations.add.once = 599
+      await assert.rejects(validate(manifest), (error) => /must be >= 600/.test(error.message))
+    })
+
+    it('should not be a fraction of a second', async () => {
+      manifest.operations.add.once = 600.5
+      await assert.rejects(validate(manifest))
+    })
+
+    it('should throw for an operation that takes none', async () => {
+      manifest.operations.get.once = 600
+      await assert.rejects(validate(manifest))
+    })
+  })
+
   describe('concurrency', () => {
     it('should be required for transitions', async () => {
       delete manifest.operations.add.concurrency

package/test/context/evict.fixtures.js

@@ -29,7 +29,7 @@ export const context = {
     {
       name: 'foo',
       components: ['a.b', 'b.a'],
-      services: ['@toa.io/extensions.exposition', '@toa.io/extensions.realtime']
+      services: ['@toa.io/extensions.exposition', '@toa.io/extensions.cadence']
     },
     {
       name: 'bar',

package/test/context/evict.test.js

@@ -25,7 +25,10 @@ it('should mark an evicted component and keep it', () => {
   evict(context)
 
   assert.deepStrictEqual(
-    context.components.map((component) => [component.locator.id, component.evicted === true]),
+    context.components.map((component) => [
+      component.locator.id,
+      component.evicted === true
+    ]),
     [
       ['a.b', true],
       ['b.a', false],
@@ -56,14 +59,12 @@ it('should drop an evicted service from a composition that runs it', () => {
 
   evict(context)
 
-  assert.deepStrictEqual(context.compositions[0].services, [
-    '@toa.io/extensions.realtime'
-  ])
+  assert.deepStrictEqual(context.compositions[0].services, ['@toa.io/extensions.cadence'])
 })
 
 it('should leave no services where every one is evicted', () => {
   context.evicted = {
-    services: ['@toa.io/extensions.exposition', '@toa.io/extensions.realtime']
+    services: ['@toa.io/extensions.exposition', '@toa.io/extensions.cadence']
   }
 
   evict(context)

package/test/context/validate.test.js

@@ -84,6 +84,21 @@ it('should require registry url', () => {
   )
 })
 
+describe('inbox', () => {
+  it('should allow a retention of ten minutes or more', () => {
+    context.inbox = { retention: 600 }
+    assert.doesNotThrow(() => validate(context))
+  })
+
+  it('should refuse a retention shorter than ten minutes', () => {
+    context.inbox = { retention: 599 }
+    assert.throws(
+      () => validate(context),
+      (error) => /must be >= 600/.test(error.message)
+    )
+  })
+})
+
 it('should allow mono replicas and resources', () => {
   context.mono = {
     replicas: 2,

package/test/system.test.js

@@ -0,0 +1,31 @@
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+import { readFileSync } from 'node:fs'
+import { it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { yaml as jsyaml } from '@toa.io/generic'
+import { contract } from '@toa.io/core'
+
+/*
+ * A contract leaves out what the root prototype gives every entity, and `@toa.io/core` is what
+ * puts it back — where the prototype is not installed, so it holds a copy of that declaration.
+ * This is what keeps the copy the same as what a component is actually collapsed with.
+ */
+
+const path = dirname(createRequire(import.meta.url).resolve('@toa.io/prototype'))
+const prototype = jsyaml.load(readFileSync(join(path, 'manifest.toa.yaml'), 'utf8'))
+
+it('should state the system properties the prototype gives', () => {
+  const { id, ...system } = prototype.entity.properties
+
+  assert.deepStrictEqual(system, contract.SYSTEM)
+  assert.deepStrictEqual(id, contract.ID)
+})
+
+it('should require every one of them, and nothing else', () => {
+  assert.deepStrictEqual(prototype.entity.required, [
+    'id',
+    ...Object.keys(contract.SYSTEM)
+  ])
+})