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

package/src/.component/schema.yaml

@@ -8,7 +8,7 @@ definitions:
   binding:
     type: string
     not:
-      const: '@toa.io/bindings.loop' # loop is for system use only
+      const: "@toa.io/bindings.loop" # loop is for system use only
 
 type: object
 properties:
@@ -17,19 +17,19 @@ properties:
     nullable: true
     properties:
       prototype:
-        $ref: '#/properties/prototype'
+        $ref: "#/properties/prototype"
       path:
         type: string
       operations:
         type: object
         propertyNames:
-          $ref: '#/definitions/name'
+          $ref: "#/definitions/name"
         patternProperties:
-          '.*':
+          ".*":
             type: object
             properties:
               bridge:
-                $ref: '#/properties/bridge'
+                $ref: "#/properties/bridge"
 
   path:
     type: string
@@ -38,19 +38,22 @@ properties:
     type: object
     properties:
       id:
-        $ref: 'definitions#/definitions/locator'
+        type: string
+        pattern: ^([a-zA-Z]+([_a-zA-Z0-9]*[a-zA-Z0-9]+)?)(\.([a-zA-Z]+([_a-zA-Z0-9]*[a-zA-Z0-9]+)?))$
       label:
-        $ref: 'definitions#/definitions/label'
+        type: string
+        pattern: ^([a-zA-Z]+([_a-zA-Z0-9]*[a-zA-Z0-9]+)?)(-([a-zA-Z]+([_a-zA-Z0-9]*[a-zA-Z0-9]+)?))*$
 
   name:
-    $ref: 'definitions#/definitions/token'
+    type: string
+    pattern: ^[a-zA-Z]([a-zA-Z0-9]{1,31})?$
 
   namespace:
-    $ref: 'definitions#/definitions/token'
-    default: 'default'
+    type: string
+    pattern: ^[a-zA-Z]([a-zA-Z0-9]{1,31})?$
     not:
       oneOf:
-        - const: 'system'
+        - const: "system"
 
   version:
     type: string
@@ -60,40 +63,60 @@ properties:
     properties:
       image:
         type: string
+      run:
+        type: string
 
   entity:
     type: object
     properties:
       storage:
         type: string
-        default: '@toa.io/storages.mongodb'
-      schema:
-        $ref: 'definitions#/definitions/schema'
+      properties:
         type: object
-        properties:
-          type:
-            default: object
-            const: object
+        # a system property is named like any other, so nothing is enumerated beside them
+        propertyNames:
+          $ref: "#/definitions/name"
+        additionalProperties:
+          $ref: https://json-schema.org/draft/2019-09/schema
+      required:
+        type: array
+        uniqueItems: true
+        items:
+          $ref: "#/definitions/name"
+      blank:
+        # what a record holds before anything is written to it; a system property is the
+        # runtime's to write, so none may be named here
+        type: object
+        propertyNames:
+          not:
+            enum: [id, VERSION, CREATED, UPDATED, DELETED, REGION]
+      migrations:
+        type: array
+        items:
+          type: object
           properties:
-            type: object
-            propertyNames:
-              oneOf:
-                - $ref: '#/definitions/name'
-                - enum: [_version]
-      dependent:
+            id:
+              type: string
+            # what a step means belongs to the storage, which is the only thing that reads it
+            steps:
+              type: array
+            # the prototype it is inherited from; absent on the component's own
+            prototype:
+              type: string
+          required: [id, steps]
+          additionalProperties: false
+      associated:
         type: boolean
-        default: false
       custom:
         type: boolean
-        default: false
-    required: [schema]
+    required: [properties]
     additionalProperties: false
 
   bindings:
     type: array
     uniqueItems: true
     items:
-      $ref: '#/definitions/binding'
+      $ref: "#/definitions/binding"
 
   bridge:
     type: string
@@ -101,27 +124,49 @@ properties:
   operations:
     type: object
     propertyNames:
-      $ref: '#/definitions/name'
+      $ref: "#/definitions/name"
     patternProperties:
-      '.*':
+      ".*":
         type: object
         properties:
           type:
-            enum: [transition, observation, assignment, computation, effect]
+            enum:
+              [
+                transition,
+                observation,
+                assignment,
+                computation,
+                effect,
+                unmanaged,
+              ]
           scope:
-            enum: [object, objects, changeset, none]
+            enum: [object, objects, changeset, stream, none]
           concurrency:
             enum: [none, retry]
+          once:
+            # the same call arriving twice changes state once; see documentation/inbox.md
+            type: boolean
+          stateful:
+            # served by every process under an address of its own, which a call names; see documentation/stateful.md
+            type: boolean
           forward:
-            $ref: '#/definitions/name'
+            $ref: "#/definitions/name"
           bridge:
             type: string
           bindings:
-            $ref: '#/properties/bindings'
+            $ref: "#/properties/bindings"
+          description:
+            # what the operation is, for whoever reads it: a generated type, an OPTIONS, a model
+            type: string
           input:
-            $ref: 'definitions#/definitions/schema'
+            $ref: https://json-schema.org/draft/2019-09/schema
           output:
-            $ref: 'definitions#/definitions/schema'
+            $ref: https://json-schema.org/draft/2019-09/schema
+          errors:
+            # what a reply may carry as a code: the error schema allows either
+            type: array
+            items:
+              type: [string, integer]
           query:
             type: boolean
         required: [type, scope, bindings]
@@ -133,8 +178,8 @@ properties:
             then:
               properties:
                 scope:
-                  enum: [object]
-              if: # transition query: false
+                  enum: [object, objects]
+              if: # not query: false
                 not:
                   properties:
                     query:
@@ -142,6 +187,17 @@ properties:
                   required: [query]
               then:
                 required: [concurrency]
+          - if: # transition and scope=objects
+              properties:
+                type:
+                  const: transition
+                scope:
+                  const: objects
+            then:
+              properties:
+                query:
+                  not:
+                    const: false
           - if: # not transition
               not:
                 properties:
@@ -151,6 +207,30 @@ properties:
               properties:
                 concurrency:
                   const: ~ # never pass
+          - if: # neither a transition nor an assignment
+              not:
+                properties:
+                  type:
+                    enum: [transition, assignment]
+            then:
+              properties:
+                # An operation that writes nothing has nothing to record. An effect writes, but
+                # its write is get-or-create, so a second arrival of one writes nothing already —
+                # and it writes in `acquire`, before its algorithm has run, so its reply is not
+                # known where the record is made.
+                once:
+                  const: ~ # never pass
+          - if: # commits more than one entity
+              properties:
+                type:
+                  const: transition
+                scope:
+                  const: objects
+            then:
+              properties:
+                # the reply is recorded, and over a set it is unbounded
+                once:
+                  const: ~ # never pass
           - if: # observation
               properties:
                 type:
@@ -158,7 +238,7 @@ properties:
             then:
               properties:
                 scope:
-                  enum: [object, objects, none]
+                  enum: [object, objects, stream, none]
                 query:
                   not:
                     const: false
@@ -173,15 +253,13 @@ properties:
           - if: # computation
               properties:
                 type:
-                  const: computation
+                  enum: [computation, unmanaged]
             then:
               properties:
                 scope:
                   const: none
-                  default: none
                 query:
                   const: false
-                  default: false
           - if: # effect
               properties:
                 type:
@@ -189,20 +267,16 @@ properties:
             then:
               properties:
                 scope:
-                  const: none
-                  default: none
-                query:
-                  const: false
-                  default: false
+                  enum: [object, objects, stream, none]
         additionalProperties: false
     additionalProperties: false
 
   events:
     type: object
     propertyNames:
-      $ref: 'definitions#/definitions/name'
+      $ref: "#/definitions/name"
     patternProperties:
-      '.*':
+      ".*":
         type: object
         properties:
           bridge:
@@ -210,47 +284,53 @@ properties:
           path:
             type: string
           binding:
-            $ref: '#/definitions/binding'
+            $ref: "#/definitions/binding"
           conditioned:
             type: boolean
-            default: false
           subjective:
             type: boolean
-            default: false
         required: [bridge, path]
         additionalProperties: false
 
   receivers:
     type: object
     patternProperties:
-      '.*':
+      ".*":
         type: object
         properties:
           operation:
-            $ref: 'definitions#/definitions/name'
+            $ref: "#/definitions/name"
           bridge:
             type: string
           binding:
             type: string
           source:
-            $ref: 'definitions#/definitions/name'
+            $ref: "#/definitions/name"
             not:
               const: context
           path:
             type: string
           conditioned:
             type: boolean
-            default: false
           adaptive:
             type: boolean
-            default: false
+          arguments:
+            type: array
         required: [operation]
         additionalProperties: false
 
-  extensions:
+  guards:
     type: object
+    patternProperties:
+      ".*":
+        type: object
+        properties:
+          bridge: { type: string }
+          path: { type: string }
+        required: [bridge, path]
+        additionalProperties: false
 
-  properties:
+  extensions:
     type: object
 
 additionalProperties: false

package/src/.component/validate.js

@@ -1,25 +1,43 @@
-'use strict'
+import path from 'node:path'
 
-const path = require('node:path')
+import { readFileSync } from 'node:fs'
+import { yaml } from '@toa.io/generic'
+import * as schemas from '@toa.io/schemas'
+import { definition } from '../definition.js'
 
-const { load } = require('@toa.io/yaml')
-const { Schema } = require('@toa.io/schema')
+const object = yaml.load(
+  readFileSync(path.resolve(import.meta.dirname, 'schema.yaml'), 'utf8')
+)
+const schema = schemas.schema(object)
 
-const object = load.sync(path.resolve(__dirname, 'schema.yaml'))
-const schema = new Schema(object)
-
-const validate = (manifest) => {
+export const validate = async (manifest) => {
   const error = schema.fit(manifest)
 
-  if (error) throw new Error(error.message)
+  if (error) throw error
 
-  if (manifest.events !== undefined) events(manifest)
+  if (manifest.entity !== undefined) entity(manifest)
+  if (manifest.events !== undefined) await events(manifest)
   if (manifest.receivers !== undefined) receivers(manifest)
 }
 
-const events = (manifest) => {
+/** What only the entity's own declaration can answer: whether a name it uses is one it declares. */
+const entity = (manifest) => {
+  const { properties, required, blank } = manifest.entity
+
+  for (const name of required ?? [])
+    if (properties[name] === undefined)
+      throw new Error(`Entity requires property '${name}', which is not defined`)
+
+  for (const name of Object.keys(blank ?? {}))
+    if (properties[name] === undefined)
+      throw new Error(`Entity blank names property '${name}', which is not defined`)
+}
+
+const events = async (manifest) => {
   for (const [label, event] of Object.entries(manifest.events)) {
-    if (require(event.binding).properties.async !== true) {
+    const { properties } = (await definition(event.binding)).module
+
+    if (properties.async !== true) {
       throw new Error(`Event '${label}' binding '${event.binding}' is not async`)
     }
   }
@@ -28,15 +46,17 @@ const events = (manifest) => {
 const receivers = (manifest) => {
   for (const [locator, receiver] of Object.entries(manifest.receivers)) {
     if (manifest.operations?.[receiver.operation] === undefined) {
-      throw new Error(`Receiver '${locator}' refers to undefined operation '${receiver.operation}'`)
+      throw new Error(
+        `Receiver '${locator}' refers to undefined operation '${receiver.operation}'`
+      )
     }
 
     if (!TYPES.has(manifest.operations[receiver.operation].type)) {
-      throw new Error(`Receiver '${locator}' must refer to an operation of one of the allowed types: ${Array.from(TYPES).join(', ')}`)
+      throw new Error(
+        `Receiver '${locator}' must refer to an operation of the allowed types: ${Array.from(TYPES).join(', ')}`
+      )
     }
   }
 }
 
-const TYPES = new Set(['transition', 'effect'])
-
-exports.validate = validate
+const TYPES = new Set(['transition', 'assignment', 'effect', 'unmanaged'])

package/src/.context/.dependencies/connectors.js

@@ -1,20 +1,23 @@
-'use strict'
+import { resolve } from 'node:path'
 
-const connectors = (context, extracted) => {
+export const connectors = (context, extracted) => {
   const connectors = {}
 
-  const components = (context.components === undefined
+  const components =
+    (context.components === undefined
       ? extracted
-      : context.components.concat(extracted)
-  ) ?? []
+      : context.components.concat(extracted)) ?? []
 
   for (const component of components) {
     if (component.entity !== undefined) {
-      if (connectors[component.entity.storage] === undefined) {
-        connectors[component.entity.storage] = []
+      let storage = component.entity.storage
+
+      if (storage[0] === '.') {
+        storage = resolve(component.path, storage)
       }
 
-      connectors[component.entity.storage].push(component)
+      connectors[storage] ??= []
+      connectors[storage].push(component)
     }
 
     const bindings = new Set()
@@ -42,5 +45,3 @@ const connectors = (context, extracted) => {
 
   return connectors
 }
-
-exports.connectors = connectors

package/src/.context/.dependencies/describe.js

@@ -1,10 +1,9 @@
-'use strict'
-
 /**
  * @param {toa.norm.Component} component
  * @param {Object} manifest
  * @returns {toa.norm.context.dependencies.Instance}
  */
-const describe = (component, manifest = undefined) => ({ locator: component.locator, manifest })
-
-exports.describe = describe
+export const describe = (component, manifest = undefined) => ({
+  locator: component.locator,
+  manifest
+})

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

@@ -1,12 +1,34 @@
-'use strict'
+import { Locator } from '@toa.io/core'
+import { converge } from '../converge.js'
+import { component as load } from '../../component.js'
+import { definition } from '../../definition.js'
 
-const extensions = async (context) => {
+export const extensions = async (context) => {
   const extensions = {}
   const components = context.components?.slice() ?? []
-  const extracted = await extractExtensionComponents(components, extensions)
+
+  /** the components each extension brings, by reference
+   *  @type {Map<string, toa.norm.Component[]>} */
+  const contributed = new Map()
+
+  // an extension a composition runs may be referenced by no component of this context,
+  // and its own components must be extracted all the same
+  const declared = await extractDeclaredServices(context, extensions, contributed)
+
+  const extracted = declared.concat(
+    await extractExtensionComponents(
+      components.concat(declared),
+      extensions,
+      contributed,
+      context.annotations
+    )
+  )
 
   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
 
@@ -17,12 +39,33 @@ const extensions = async (context) => {
     }
   }
 
-  return { extensions, components: extracted }
+  return { extensions, components: extracted, contributed }
 }
 
-async function extractExtensionComponents (components, extensions) {
-  const { component: load } = require('../../component')
+async function extractDeclaredServices(context, extensions, contributed) {
+  const extracted = []
+
+  for (const composition of context.compositions ?? [])
+    for (const reference of composition.services ?? []) {
+      if (reference in extensions) continue
 
+      try {
+        extracted.push(
+          ...(await extract(reference, extensions, contributed, context.annotations))
+        )
+      } catch (e) {
+        throw new Error(
+          `Composition '${composition.name}' lists '${reference}', ` +
+            `which cannot be resolved: ${e.message}`,
+          { cause: e }
+        )
+      }
+    }
+
+  return extracted
+}
+
+async function extractExtensionComponents(components, extensions, contributed, annotations) {
   const extracted = []
 
   for (const component of components) {
@@ -31,26 +74,56 @@ async function extractExtensionComponents (components, extensions) {
     for (const reference of Object.keys(component.extensions)) {
       if (reference in extensions) continue
 
-      extensions[reference] = []
+      extracted.push(...(await extract(reference, extensions, contributed, annotations)))
+    }
+  }
+
+  if (extracted.length === 0) return extracted
 
-      const mod = require(reference)
+  const deeper = await extractExtensionComponents(
+    extracted,
+    extensions,
+    contributed,
+    annotations
+  )
 
-      if (mod.components === undefined) continue
+  return extracted.concat(deeper)
+}
 
-      for (const path of mod.components().paths) {
-        const component = await load(path)
+/**
+ * The components an extension contributes, if it contributes any.
+ *
+ * @param {string} reference
+ * @param {object} extensions
+ * @param {Map<string, toa.norm.Component[]>} contributed
+ * @param {object} [annotations]
+ * @returns {Promise<Array<toa.norm.Component>>}
+ */
+async function extract(reference, extensions, contributed, annotations) {
+  extensions[reference] = []
 
-        extracted.push(component)
-      }
-    }
-  }
+  const { name, module: mod } = await definition(reference)
 
-  if (extracted.length === 0)
-    return extracted
+  if (mod.components === undefined) return []
 
-  const deeper = await extractExtensionComponents(extracted, extensions)
+  // the annotation decides whether an extension contributes components at all
+  const annotation = annotations?.[name]
+  const { manifests, paths } = mod.components(annotation)
 
-  return extracted.concat(deeper)
+  // a definition carries the manifests, read where the extension is not installed;
+  // an entry names the directories, where it is
+  const extracted = manifests === undefined ? [] : manifests.map(revive)
+
+  if (manifests === undefined) for (const path of paths) extracted.push(await load(path))
+
+  contributed.set(reference, extracted)
+
+  return extracted
 }
 
-exports.extensions = extensions
+/** A manifest as a digest carries it, which is one norm read, without the locator. */
+function revive(manifest) {
+  manifest.locator = new Locator(manifest.name, manifest.namespace)
+
+  return manifest
+}

package/src/.context/.dependencies/index.js

@@ -1,9 +1,3 @@
-'use strict'
-
-const { connectors } = require('./connectors')
-const { extensions } = require('./extensions')
-const { resolve } = require('./resolve')
-
-exports.connectors = connectors
-exports.extensions = extensions
-exports.resolve = resolve
+export { connectors } from './connectors.js'
+export { extensions } from './extensions.js'
+export { resolve } from './resolve.js'