@toa.io/core 1.0.0-alpha.26 → 1.0.0-alpha.262

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# 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.262](https://github.com/toa-io/toa/compare/v1.0.0-alpha.261...v1.0.0-alpha.262) (2026-08-28)
+
+
+### Features
+
+* **core:** identify the origin of a call with `request.source` ([9da6b66](https://github.com/toa-io/toa/commit/9da6b66df852690351a1e82c7b8cc176fd89774a))
+
+
+
+
+
+# [1.0.0-alpha.259](https://github.com/toa-io/toa/compare/v1.0.0-alpha.258...v1.0.0-alpha.259) (2026-08-24)
+
+
+### Features
+
+* **runtime:** split component RC into preflight and settle ([0d648b3](https://github.com/toa-io/toa/commit/0d648b314e4aac226c254bf01a86affa04b59b34))
+
+
+
+
+
+# [1.0.0-alpha.257](https://github.com/toa-io/toa/compare/v1.0.0-alpha.256...v1.0.0-alpha.257) (2026-08-24)
+
+
+### Bug Fixes
+
+* **core:** lift tombstone on commit when transition leaves it untouched ([38c0d15](https://github.com/toa-io/toa/commit/38c0d15e946c3e2d559d4b18aecc33e0fda2471a))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/core",
-  "version": "1.0.0-alpha.26",
+  "version": "1.0.0-alpha.262",
   "description": "Toa Core",
   "author": "temich <tema.gurtovoy@gmail.com>",
   "homepage": "https://github.com/toa-io/toa#readme",
@@ -21,13 +21,11 @@
   },
   "dependencies": {
     "@rsql/parser": "1.2.4",
-    "@toa.io/console": "1.0.0-alpha.26",
-    "@toa.io/generic": "1.0.0-alpha.26",
-    "@toa.io/yaml": "1.0.0-alpha.26",
-    "error-value": "0.3.0"
+    "@toa.io/generic": "1.0.0-alpha.254",
+    "@toa.io/yaml": "1.0.0-alpha.254",
+    "error-value": "0.3.0",
+    "openspan": "1.0.0-alpha.254",
+    "uuid": "11.1.1"
   },
-  "devDependencies": {
-    "clone-deep": "4.0.1"
-  },
-  "gitHead": "0ddd9260762d1fe2b8be88eb7b9725e3f7838299"
+  "gitHead": "e14059cf5cc364d933f2a4b3d7114f3b5ec0764f"
 }

package/src/call.js

@@ -1,28 +1,42 @@
 'use strict'
 
 const { Readable } = require('node:stream')
+const { current, encode } = require('openspan')
 const { Connector } = require('./connector')
 const { Err } = require('error-value')
 
 class Call extends Connector {
   #transmitter
   #contract
+  #source
 
-  constructor (transmitter, contract) {
+  constructor (transmitter, contract, source) {
     super()
 
     this.#transmitter = transmitter
     this.#contract = contract
+    this.#source = source
 
     this.depends(transmitter)
   }
 
   async invoke (request = {}) {
+    request.input ??= null
+
+    // the caller may have attributed the call itself, as the node bridge does
+    if (this.#source !== undefined)
+      request.source ??= this.#source
+
     this.#contract.fit(request)
 
     // avoid validation on the recipient's side
     request.authentic = true
 
+    const context = current()
+
+    if (context !== undefined)
+      request.telemetry = encode(context)
+
     const reply = await this.#transmitter.request(request)
 
     if (reply === null) return null
@@ -37,6 +51,10 @@ class Call extends Connector {
         return reply.output
     }
   }
+
+  explain () {
+    return this.#contract.discovery
+  }
 }
 
 exports.Call = Call

package/src/cascade.js

@@ -1,19 +1,21 @@
 'use strict'
 
-const { merge } = require('@toa.io/generic')
 const { Connector } = require('./connector')
 
 class Cascade extends Connector {
-  #bridges
+  // #bridges
   #last
 
-  constructor (bridges) {
+  constructor (bridges, preflight) {
     super()
 
-    this.#bridges = bridges
+    // this.#bridges = bridges
     this.#last = bridges[bridges.length - 1]
 
-    this.depends(bridges)
+    if (preflight === undefined)
+      this.depends(bridges)
+    else
+      this.depends(bridges).depends(preflight)
   }
 
   async run (...args) {

package/src/component.js

@@ -1,40 +1,64 @@
 'use strict'
 
-const { console } = require('@toa.io/console')
+const assert = require('node:assert')
+const { console, current, decode, run } = require('openspan')
 const { Connector } = require('./connector')
-const { NotImplementedException } = require('./exceptions')
 
-/**
- * @implements {toa.core.Component}
- */
 class Component extends Connector {
   locator
 
-  #operations
+  /** @protected */
+  operations
+
+  /** @protected */
+  kind = 'server'
 
   constructor (locator, operations) {
     super()
 
     this.locator = locator
-    this.#operations = operations
+    this.operations = operations
 
     Object.values(operations).forEach((operation) => this.depends(operation))
   }
 
-  async open () {
-    console.info(`Runtime '${this.locator.id}' connected`)
-  }
+  async invoke (endpoint, request) {
+    assert.ok(endpoint in this.operations,
+      `Endpoint '${endpoint}' is not provided by '${this.locator.id}'`)
 
-  async dispose () {
-    console.info(`Runtime '${this.locator.id}' disconnected`)
+    // if the request carries no telemetry, the trace starts here
+    const remote = request?.telemetry === undefined ? null : decode(request.telemetry)
+    const task = () => this.process(endpoint, request)
+
+    if (remote === null)
+      return task()
+    else
+      return run(remote, task)
   }
 
-  async invoke (endpoint, request) {
-    if (!(endpoint in this.#operations)) {
-      throw new NotImplementedException(`Endpoint '${endpoint}' not found in '${this.locator.id}'`)
-    }
+  /** @private */
+  async process (endpoint, request) {
+    const options = { name: `${this.locator.id}.${endpoint}`, kind: this.kind }
+
+    // the server span is emitted by the component itself,
+    // while the client span belongs to the calling service and inherits it from the context
+    if (this.kind === 'server')
+      options.service = this.locator.id
+
+    return console.span(options, async () => {
+      const reply = await this.operations[endpoint].invoke(request)
+
+      if (reply?.exception !== undefined) {
+        current().status = 'error'
+
+        console.error('Failed to execute operation', {
+          endpoint: `${this.locator.id}.${endpoint}`,
+          exception: reply.exception
+        })
+      }
 
-    return this.#operations[endpoint].invoke(request)
+      return reply
+    })
   }
 }
 

package/src/composition.js

@@ -1,6 +1,6 @@
 'use strict'
 
-const { console } = require('@toa.io/console')
+const { console } = require('openspan')
 const { Connector } = require('./connector')
 
 class Composition extends Connector {

package/src/connector.js

@@ -1,7 +1,6 @@
 'use strict'
 
-const { console } = require('@toa.io/console')
-const { newid } = require('@toa.io/generic')
+const { console } = require('openspan')
 
 /**
  * Abstract connections hierarchy
@@ -26,7 +25,7 @@ class Connector {
   connected = false
 
   constructor () {
-    this.id = this.constructor.name + '#' + newid().substring(0, 8)
+    this.id = this.constructor.name + '#' + Math.random().toString(36).substring(2, 8)
   }
 
   /**
@@ -86,12 +85,18 @@ class Connector {
 
     this.#disconnecting = undefined
 
-    console.debug(`Connecting '${this.id}' with ${this.#dependencies.length} dependencies...`)
-
-    this.#connecting = (async () => {
+    const work = async () => {
       await Promise.all(this.#dependencies.map((connector) => connector.connect()))
       await this.open()
-    })()
+    }
+
+    // anonymous grouping nodes are not worth a span
+    this.#connecting = TRACE_BOOT && this.constructor.name !== 'Connector'
+      ? console.span({
+        name: `connect ${this.constructor.name}`,
+        attributes: { id: this.locator?.id ?? this.id }
+      }, work)
+      : work()
 
     try {
       await this.#connecting
@@ -100,8 +105,6 @@ class Connector {
       await this.disconnect(true)
       throw e
     }
-
-    console.debug(`Connector '${this.id}' connected`)
   }
 
   /**
@@ -115,7 +118,11 @@ class Connector {
    * @returns {Promise<void>}
    */
   async disconnect (interrupt) {
-    if (interrupt !== true) await this.#connecting
+    // a connector that has not finished connecting has nothing to close, and
+    // awaiting a connection that may never settle outlives any grace period
+    const pending = interrupt === true || this.connected === false
+
+    if (!pending) await this.#connecting
 
     if (this.#disconnecting) return this.#disconnecting
 
@@ -132,10 +139,11 @@ class Connector {
       const interval = setInterval(() => {
         const delay = +new Date() - start
 
-        if (delay > DELAY) console.warn(`Connector ${this.id} still disconnecting (${delay})`)
+        if (delay > DELAY)
+          console.warn(`Connector ${this.id} still disconnecting (${delay})`)
       }, DELAY)
 
-      if (interrupt !== true) await this.close()
+      if (!pending) await this.close()
 
       clearInterval(interval)
 
@@ -145,8 +153,6 @@ class Connector {
     })()
 
     await this.#disconnecting
-
-    console.debug(`Connector '${this.id}' disconnected`)
   }
 
   async reconnect () {
@@ -179,5 +185,6 @@ class Connector {
 }
 
 const DELAY = 5000
+const TRACE_BOOT = process.env.TOA_BOOT_TRACE === '1'
 
 exports.Connector = Connector

package/src/context.js

@@ -6,7 +6,10 @@ const { Connector } = require('./connector')
  * @implements {toa.core.Context}
  */
 class Context extends Connector {
+  env
+  name
   aspects
+  locator
 
   #local
   #discover
@@ -15,7 +18,10 @@ class Context extends Connector {
   constructor (local, discover, aspects = []) {
     super()
 
+    this.env = process.env.TOA_ENV
+    this.name = process.env.TOA_CONTEXT
     this.aspects = aspects
+    this.locator = local?.locator
 
     this.#local = local
     this.#discover = discover

package/src/contract/contract.js

@@ -0,0 +1,22 @@
+'use strict'
+
+const { SystemException } = require('../exceptions')
+
+class Contract {
+  schema
+
+  constructor (schema) {
+    this.schema = schema
+  }
+
+  fit (value) {
+    const error = this.schema.fit(value)
+
+    if (error !== null)
+      throw new this.constructor.Exception(error, value)
+  }
+
+  static Exception = SystemException
+}
+
+exports.Contract = Contract

package/src/contract/reply.js

@@ -1,22 +1,39 @@
 'use strict'
 
 const schemas = require('./schemas')
-const { Conditions } = require('./conditions')
+const { Contract } = require('./contract')
 const { ResponseContractException } = require('../exceptions')
 
-class Reply extends Conditions {
+class Reply extends Contract {
   static Exception = ResponseContractException
 
-  /**
-   * @returns {toa.schema.JSON}
-   */
-  static schema (output, error) {
+  static schema (output, errors) {
     const schema = { type: 'object', properties: {}, additionalProperties: false }
 
-    if (output !== undefined) schema.properties.output = output
+    if (output !== undefined) {
+      if (output.type === 'object')
+        output.additionalProperties = true
+      else if (output.type === 'array' && output.items?.type === 'object')
+        output.items.additionalProperties = true
 
-    if (error !== undefined) schema.properties.error = error
-    else schema.properties.error = schemas.error
+      schema.properties.output = output
+    }
+
+    if (errors !== undefined)
+      schema.properties.error = {
+        type: 'object',
+        properties: {
+          code: {
+            enum: errors
+          },
+          message: {
+            type: 'string'
+          }
+        },
+        required: ['code']
+      }
+    else
+      schema.properties.error = schemas.error
 
     return schema
   }

package/src/contract/request.js

@@ -2,9 +2,20 @@
 
 const schemas = require('./schemas')
 const { RequestContractException } = require('../exceptions')
-const { Conditions } = require('./conditions')
+const { Contract } = require('./contract')
+
+class Request extends Contract {
+  /** @readonly */
+  discovery = {}
+
+  constructor (schema, definition) {
+    super(schema)
+
+    for (const key of ['input', 'output', 'errors'])
+      if (definition[key] !== undefined)
+        this.discovery[key] = definition[key]
+  }
 
-class Request extends Conditions {
   static Exception = RequestContractException
 
   /**
@@ -13,7 +24,11 @@ class Request extends Conditions {
   static schema (definition, entity) {
     const schema = {
       type: 'object',
-      properties: { authentic: { type: 'boolean' } },
+      properties: {
+        authentic: { type: 'boolean' },
+        task: { type: 'boolean' },
+        source: structuredClone(schemas.source)
+      },
       additionalProperties: true
     }
 
@@ -22,9 +37,8 @@ class Request extends Conditions {
     if (definition.input !== undefined) {
       schema.properties.input = definition.input
       required.push('input')
-    } else {
+    } else
       schema.properties.input = { type: 'null' }
-    }
 
     if (entity === undefined)
       definition.query = false

package/src/contract/schemas/index.js

@@ -5,3 +5,4 @@ const { load } = require('@toa.io/yaml')
 
 exports.query = load.sync(resolve(__dirname, './query.yaml'))
 exports.error = load.sync(resolve(__dirname, './error.yaml'))
+exports.source = load.sync(resolve(__dirname, './source.yaml'))

package/src/contract/schemas/query.yaml

@@ -1,11 +1,22 @@
 type: object
 properties:
-  id: { }
+  id:
+    type: string
+  ids:
+    type: array
+    uniqueItems: true
+    minItems: 1
+    items:
+      type: string
   version:
     type: integer
     minimum: 0
   criteria:
     type: string
+  search:
+    type: string
+  sample:
+    type: number
   omit:
     type: integer
     minimum: 0
@@ -27,4 +38,6 @@ properties:
       type: string
       not:
         const: id
+  deleted:
+    type: boolean
 additionalProperties: false

package/src/contract/schemas/source.yaml

@@ -0,0 +1,23 @@
+# Origin of a call, see toa.core.Source.
+# Deliberately permissive on required properties: the contract throws on a mismatch,
+# and a strict union would turn a partially stamped source into a failed business call.
+# `additionalProperties: false` combined with `removeAdditional` is what matters here —
+# it strips whatever a peer puts in, bounding the cardinality of the resulting map.
+type: object
+properties:
+  namespace:
+    type: string
+    maxLength: 64
+  component:
+    type: string
+    maxLength: 64
+  operation:
+    type: string
+    maxLength: 64
+  event:
+    type: string
+    maxLength: 64
+  service:
+    type: string
+    maxLength: 64
+additionalProperties: false

package/src/discovery.js

@@ -1,6 +1,6 @@
 'use strict'
 
-const { console } = require('@toa.io/console')
+const { console } = require('openspan')
 const { Connector } = require('./connector')
 
 class Discovery extends Connector {
@@ -25,20 +25,26 @@ class Discovery extends Connector {
       this.depends(this.#lookups[id])
     }
 
-    console.debug(`Sending lookup request to '${id}'`)
+    const since = Date.now()
 
-    const warning = () => console.warn(`Waiting for lookup response from '${id}'...`)
-    const timeout = setTimeout(warning, TIMEOUT)
+    // the wait is unbounded by design, as a dependency may still be starting,
+    // so repeating is the only way a component stuck on one stays visible
+    const warning = setInterval(() => {
+      const waiting = Math.round((Date.now() - since) / 1000)
+
+      console.warn('Waiting for lookup response', { component: id, waiting })
+    }, INTERVAL)
+
+    warning.unref()
 
     const output = await this.#lookups[id].invoke()
 
-    console.debug(`Lookup response from '${id}' received`)
-    clearTimeout(timeout)
+    clearInterval(warning)
 
     return output
   }
 }
 
-const TIMEOUT = 5000
+const INTERVAL = 5000
 
 exports.Discovery = Discovery

package/src/effect.js

@@ -0,0 +1,19 @@
+'use strict'
+
+const { Observation } = require('./observation')
+
+class Effect extends Observation {
+
+  async acquire (store) {
+    const { query, entity, input } = store.request
+
+    if (entity === undefined)
+      return super.acquire(store)
+
+    store.scope = await this.scope.ensure(query, entity, input)
+    store.state = store.scope.get()
+  }
+
+}
+
+exports.Effect = Effect

package/src/entities/changeset.js

@@ -1,10 +1,5 @@
 'use strict'
 
-const {
-  merge,
-  overwrite,
-  newid
-} = require('@toa.io/generic')
 const { EntityContractException } = require('../exceptions')
 
 class Changeset {
@@ -18,7 +13,7 @@ class Changeset {
     this.query = query
 
     this.#schema = schema
-    this.#state = schema.system()
+    this.#state = {}
   }
 
   get () {
@@ -26,10 +21,12 @@ class Changeset {
   }
 
   set (value) {
-    const error = this.#schema.adapt(value)
+    const error = this.#schema.match(value)
 
-    if (error !== null) throw new EntityContractException(error)
+    if (error !== null)
+      throw new EntityContractException(error, value)
 
+    delete value._version
     value._updated = Date.now()
 
     this.#state = value