@toa.io/norm 1.0.0-alpha.291 → 1.0.0-alpha.293

package/CHANGELOG.md

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

package/package.json

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

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

@@ -3,6 +3,5 @@ export { entity } from './entity.js'
 export { events } from './events.js'
 export { extensions } from './extensions.js'
 export { operations } from './operations.js'
-export { properties } from './properties.js'
 export { receivers } from './receivers.js'
 export { version } from './version.js'

package/src/.component/.normalize/events.js

@@ -1,3 +1,5 @@
+import { definition } from '../../definition.js'
+
 export const events = async (component) => {
   if (component.events === undefined) return
 
@@ -14,7 +16,7 @@ export const events = async (component) => {
 /** The first binding that carries events, which only its module can say. */
 async function asynchronous(bindings) {
   for (const binding of bindings) {
-    const { properties } = await import(binding)
+    const { properties } = (await definition(binding)).module
 
     if (properties.async === true) return binding
   }

package/src/.component/expand.js

@@ -5,7 +5,6 @@ import {
   events,
   receivers,
   extensions,
-  properties,
   version
 } from './.expand/index.js'
 
@@ -15,7 +14,6 @@ export async function expand(manifest) {
   operations(manifest)
   events(manifest)
   receivers(manifest)
-  properties(manifest)
   extensions(manifest)
 
   await version(manifest)

package/src/.component/extensions.js

@@ -1,7 +1,6 @@
 import { find } from '@toa.io/generic'
 import { resolve } from '../shortcuts.js'
-
-const cache = {}
+import { definition } from '../definition.js'
 
 export const extensions = async (manifest) => {
   manifest.extensions = Object.assign({}, PREDEFINED, manifest.extensions)
@@ -14,9 +13,7 @@ export const extensions = async (manifest) => {
     // relative path
     if (key[0] === '.') key = find(key, manifest.path)
 
-    cache[key] ??= import(key)
-
-    const extension = await cache[key]
+    const { module: extension } = await definition(key)
 
     if (extension.manifest !== undefined) {
       declaration = extension.manifest(declaration, manifest)

package/src/.component/merge.js

@@ -1,4 +1,5 @@
 import { merge } from '@toa.io/generic'
+import { definition } from '../definition.js'
 
 const bridge = async (root, manifest) => {
   await Promise.all([
@@ -18,7 +19,7 @@ const define = async (root, manifest, property) => {
       if (item.bridge === undefined || item.bridge === manifest.bridge) continue // default bridge later
 
       const bridge = item.bridge || manifest.bridge
-      const { define } = await req(bridge)
+      const { define } = await bridged(bridge)
       const definition = await define[singular](root, endpoint)
 
       merge(item, definition)
@@ -53,20 +54,20 @@ const define = async (root, manifest, property) => {
   }
 }
 
-const cache = {}
-
-// the promise is what is remembered, so a bridge is loaded once
-function req(mod) {
-  cache[mod] ??= import(mod)
-
-  return cache[mod]
-}
-
 const scan = async (bridge, root, property) => {
-  const { define } = await req(bridge)
+  const { define } = await bridged(bridge)
 
   if (property in define) return define[property](root)
   else return undefined
 }
 
+async function bridged(reference) {
+  const { module } = await definition(reference)
+
+  if (module.define === undefined)
+    throw new Error(`Bridge '${reference}' defines nothing: it exports no 'define'`)
+
+  return module
+}
+
 export { bridge as merge }

package/src/.component/schema.yaml

@@ -303,7 +303,4 @@ properties:
   extensions:
     type: object
 
-  properties:
-    type: object
-
 additionalProperties: false

package/src/.component/validate.js

@@ -3,6 +3,7 @@ import path from '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 object = yaml.load(
   readFileSync(path.resolve(import.meta.dirname, 'schema.yaml'), 'utf8')
@@ -34,7 +35,7 @@ const entity = (manifest) => {
 
 const events = async (manifest) => {
   for (const [label, event] of Object.entries(manifest.events)) {
-    const { properties } = await import(event.binding)
+    const { properties } = (await definition(event.binding)).module
 
     if (properties.async !== true) {
       throw new Error(`Event '${label}' binding '${event.binding}' is not async`)

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

@@ -1,5 +1,6 @@
+import { Locator } from '@toa.io/core'
 import { component as load } from '../../component.js'
-import { load as loadDependency } from './load.js'
+import { definition } from '../../definition.js'
 
 export const extensions = async (context) => {
   const extensions = {}
@@ -84,15 +85,28 @@ async function extractExtensionComponents(components, extensions, annotations) {
 async function extract(reference, extensions, annotations) {
   extensions[reference] = []
 
-  const { metadata, module: mod } = await loadDependency(reference)
+  const { name, module: mod } = await definition(reference)
 
   if (mod.components === undefined) return []
 
   // the annotation decides whether an extension contributes components at all
-  const annotation = annotations?.[metadata?.name ?? reference]
+  const annotation = annotations?.[name]
+  const { manifests, paths } = mod.components(annotation)
+
+  // a definition carries the manifests, read where the extension is not installed;
+  // an entry names the directories, where it is
+  if (manifests !== undefined) return manifests.map(revive)
+
   const extracted = []
 
-  for (const path of mod.components(annotation).paths) extracted.push(await load(path))
+  for (const path of paths) extracted.push(await load(path))
 
   return extracted
 }
+
+/** 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/resolve.js

@@ -1,11 +1,10 @@
-import { load } from './load.js'
+import { definition } from '../../definition.js'
 
-export const resolve = async (references, annotations = {}) => {
+export const resolve = async (references, annotations = {}, context = {}) => {
   const dependencies = {}
 
   for (const [dependency, components] of Object.entries(references)) {
-    const { metadata, module } = await load(dependency)
-    const id = metadata.name
+    const { name: id, module } = await definition(dependency)
 
     const instances = components.map((component) => ({
       locator: component.locator,
@@ -20,6 +19,27 @@ export const resolve = async (references, annotations = {}) => {
     if (annotation !== undefined && module.annotation !== undefined) {
       annotations[id] = module.annotation(annotation, instances)
     }
+
+    // what a declaration costs to install, read from the definition rather than from the
+    // package: a deploy installs it, and nothing that declares nothing carries it. A component
+    // is asked for its own instance; a composition that runs the package's service is asked
+    // with none, because what a service brings is not a component's to declare
+    if (module.installs !== undefined) {
+      for (const instance of instances)
+        Object.assign(
+          (instance.component.packages ??= {}),
+          module.installs(instance, annotations[id])
+        )
+
+      const service = module.installs(undefined, annotations[id])
+
+      // mono runs every service in one process, so it takes every service's packages
+      Object.assign((context.packages ??= {}), service)
+
+      for (const composition of context.compositions ?? [])
+        if (composition.services?.includes(dependency) === true)
+          Object.assign((composition.packages ??= {}), service)
+    }
   }
 
   for (const dependency of Object.keys(annotations)) {
@@ -40,7 +60,7 @@ export const resolve = async (references, annotations = {}) => {
  */
 async function optional(reference) {
   try {
-    return (await load(reference)).module
+    return (await definition(reference)).module
   } catch {
     return null
   }

package/src/.context/dependencies.js

@@ -5,5 +5,5 @@ export const dependencies = async (context) => {
   const c = connectors(context, components)
   const references = { ...c, ...e }
 
-  return resolve(references, context.annotations)
+  return resolve(references, context.annotations, context)
 }

package/src/.context/normalize.js

@@ -1,14 +1,14 @@
-import * as runtime from '@toa.io/runtime'
+import * as definitions from '@toa.io/definitions'
 
 /**
  * @param {toa.norm.context.Declaration | Object} context
  */
 export const normalize = (context) => {
-  if (context.runtime === undefined) context.runtime = { version: runtime.version }
+  if (context.runtime === undefined) context.runtime = { version: definitions.version }
   if (typeof context.runtime === 'string') context.runtime = { version: context.runtime }
 
   if (context.runtime.version === undefined || context.runtime.version === '.') {
-    context.runtime.version = runtime.version
+    context.runtime.version = definitions.version
   }
 
   if (typeof context.registry === 'string') context.registry = { base: context.registry }

package/src/definition.js

@@ -0,0 +1,56 @@
+import { createRequire } from 'node:module'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import * as definitions from '@toa.io/definitions'
+
+// import.meta.resolve takes no paths, and a dependency is named rather than
+// written as a path
+const require = createRequire(import.meta.url)
+
+/**
+ * What a package declares, read without running it.
+ *
+ * A first-party package's definition is in `@toa.io/definitions`. Another package's is
+ * its `definition.js`, or its entry where it ships none — so an extension that exports
+ * its `manifest` and `deployment` beside its `Factory` is read as it always was.
+ *
+ * @param {string} reference a package name, or a directory
+ * @returns {Promise<toa.norm.Definition>}
+ */
+export function definition(reference) {
+  cache[reference] ??= load(reference)
+
+  return cache[reference]
+}
+
+const cache = {}
+
+async function load(reference) {
+  const known = await definitions.definition(reference)
+
+  if (known !== undefined) return { name: reference, module: known }
+
+  const name = metadata(reference)?.name ?? reference
+  const module = await import(pathToFileURL(resolve(reference)).href)
+
+  return { name, module }
+}
+
+function resolve(reference) {
+  try {
+    return require.resolve(join(reference, 'definition.js'))
+  } catch {
+    return require.resolve(reference)
+  }
+}
+
+function metadata(reference) {
+  try {
+    return JSON.parse(
+      readFileSync(require.resolve(join(reference, 'package.json')), 'utf8')
+    )
+  } catch {
+    return null
+  }
+}

package/src/index.js

@@ -1,4 +1,6 @@
 export { context } from './context.js'
 export { component } from './component.js'
+export { plain, revive, NORMALIZED } from './manifest.js'
+export { definition } from './definition.js'
 export * as shortcuts from './shortcuts.js'
 export * as entity from './entity.js'

package/src/manifest.js

@@ -0,0 +1,154 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, isAbsolute, join, parse, relative, sep } from 'node:path'
+
+import { Locator } from '@toa.io/core'
+import { find } from '@toa.io/generic'
+
+/**
+ * A normalised manifest, as it is carried in a file beside the component it is of.
+ *
+ * A build normalises every component to tag its image; the process that runs it normalised them
+ * again at start, reading every operation module's source through its bridge to do it. What the
+ * build derived is written instead, and the two cannot disagree: the sources it was read from are
+ * what the image's tag digests, and the version of Toa that read them is in that tag as well.
+ *
+ * What cannot be carried is where things are. A workspace and an image put a component in one
+ * directory and Toa's own packages in another, so every path is written as what it is of rather
+ * than as where it was — the component itself, or the package that holds it — and is resolved
+ * again on the other side, the way norm resolved it.
+ *
+ * A key with no value is not carried: a file has no way to say `undefined`, and nothing reads
+ * one apart from a key that is not there.
+ */
+export function plain(manifest) {
+  const { locator, packages, path, ...rest } = manifest
+
+  // what is carried is written, not the manifest the caller goes on using, and it is written
+  // as a file holds it: a key with no value does not survive and is not meant to
+  const declared = JSON.parse(JSON.stringify(rest))
+
+  walk(declared, (item) => {
+    item.path = carried(item.path, path)
+  })
+
+  local(declared, path)
+
+  return declared
+}
+
+/** What `plain` wrote, read back beside the component it is of. */
+export function revive(declared, path) {
+  const manifest = { ...structuredClone(declared), path }
+
+  walk(manifest, (item) => {
+    item.path = resolved(item.path, path)
+  })
+
+  manifest.locator = new Locator(manifest.name, manifest.namespace)
+
+  return manifest
+}
+
+/**
+ * Everything in a manifest that says where a module of it is: what an inherited one declares is
+ * in the prototype it came from, and what the component declares is in the component.
+ */
+function walk(manifest, rewrite) {
+  for (const property of ROOTED)
+    for (const item of Object.values(manifest[property] ?? {}))
+      if (item.path !== undefined) rewrite(item)
+
+  for (let prototype = manifest.prototype; prototype != null; prototype = prototype.prototype)
+    if (prototype.path !== undefined) rewrite(prototype)
+}
+
+/** Where it is written. A workspace has none: it is a build's output, read by a process. */
+export const NORMALIZED = 'manifest.toa.json'
+
+/** Where norm says a module is, beside what it says about it. */
+const ROOTED = ['events', 'receivers', 'guards']
+
+/** The component's own directory, which is where it is read back. */
+const SELF = '.'
+
+function carried(path, root) {
+  if (path === root) return SELF
+  if (path.startsWith(root + sep)) return SELF + '/' + relative(root, path).split(sep).join('/')
+
+  return specifier(path)
+}
+
+function resolved(path, root) {
+  if (path === SELF) return root
+  if (path.startsWith(SELF + '/')) return join(root, path.slice(2))
+
+  return find(path, root, MANIFEST)
+}
+
+/**
+ * A directory in a package, named the way a manifest would name it, so that it is found again
+ * wherever the package is installed. A prototype that is a directory of the application's own is
+ * refused here rather than in the container: an image carries components and nothing between
+ * them, so nothing would be there to find, whether it is normalised here or there.
+ */
+function specifier(path) {
+  const root = above(path)
+
+  if (root !== undefined) {
+    const { name, private: hidden } = JSON.parse(
+      readFileSync(join(root, 'package.json'), 'utf8')
+    )
+
+    if (name !== undefined && hidden !== true)
+      return [name, ...relative(root, path).split(sep)].filter(Boolean).join('/')
+  }
+
+  throw new Error(
+    `'${path}' is in no package, so an image cannot carry what is in it: ` +
+      'what a component inherits is reached by the reference of the package it is in.'
+  )
+}
+
+/** The directory of the package a path is in. */
+function above(path) {
+  const { root } = parse(path)
+
+  let current = path
+
+  while (current !== root) {
+    if (existsSync(join(current, 'package.json'))) return current
+
+    current = dirname(current)
+  }
+
+  return undefined
+}
+
+/**
+ * Nothing that is carried may say where it was on the machine that read it. What is checked is
+ * what can be told apart from a value of the application's own — an HTTP route is `/accounts`
+ * and is a path to nobody — so: anything inside the component, and any directory a manifest
+ * declares a component or a prototype in. This is what catches a path norm starts writing
+ * somewhere this file does not know about, at the build rather than at the start of a container
+ * that cannot find it.
+ */
+function local(value, root, at = '') {
+  if (typeof value === 'string') {
+    if (value === root || value.startsWith(root + sep) || component(value))
+      throw new Error(`'${at}' carries a path of the machine that read it: ${value}`)
+
+    return
+  }
+
+  if (value === null || typeof value !== 'object') return
+
+  for (const [key, item] of Object.entries(value))
+    local(item, root, at === '' ? key : `${at}.${key}`)
+}
+
+/** Whether a value is a directory a component or a prototype is declared in. */
+function component(value) {
+  return isAbsolute(value) && existsSync(join(value, MANIFEST))
+}
+
+const MANIFEST = 'manifest.toa.yaml'

package/src/shortcuts.js

@@ -41,7 +41,6 @@ export const SHORTCUTS = {
   node: '@toa.io/bridges.node',
   bash: '@toa.io/bridges.bash',
   mongodb: '@toa.io/storages.mongodb',
-  queues: '@toa.io/storages.queues',
   exposition: '@toa.io/extensions.exposition',
   realtime: '@toa.io/extensions.realtime',
   configuration: '@toa.io/extensions.configuration',

package/test/component/expand.test.js

@@ -30,14 +30,3 @@ it('should keep declared version', async () => {
 
   assert.deepStrictEqual(source.version, '1.0.0')
 })
-
-it('should recognize storages.queues', async () => {
-  const queues = { foo: 'bar' }
-
-  source.queues = clone(queues)
-
-  await expand(source)
-
-  assert.strictEqual(source.queues, undefined)
-  assert.partialDeepStrictEqual(source.properties['@toa.io/storages.queues'], queues)
-})

package/test/context/normalize.test.js

@@ -1,4 +1,4 @@
-import * as runtime from '@toa.io/runtime'
+import * as definitions from '@toa.io/definitions'
 import { it, beforeEach } from 'node:test'
 import assert from 'node:assert/strict'
 
@@ -20,7 +20,7 @@ it('should resolve local version', () => {
   normalize(context)
 
   assert.notDeepStrictEqual(context.runtime, '.')
-  assert.deepStrictEqual(context.runtime.version, runtime.version)
+  assert.deepStrictEqual(context.runtime.version, definitions.version)
 })
 
 it('should expand registry', () => {

package/test/definition.test.js

@@ -0,0 +1,35 @@
+import { it } from 'node:test'
+import assert from 'node:assert/strict'
+import { join } from 'node:path'
+
+import { definition } from '../src/definition.js'
+
+it('reads a definition.js where a package ships one', async () => {
+  const { name, module } = await definition(join(import.meta.dirname, 'dummies/defined'))
+
+  assert.equal(name, 'dummies.defined')
+  assert.equal(module.declares, true)
+  assert.equal(module.runs, undefined)
+})
+
+it('reads the entry where a package ships no definition.js', async () => {
+  const path = join(import.meta.dirname, '../')
+  const { name, module } = await definition(path)
+
+  assert.equal(name, '@toa.io/norm')
+  assert.ok(module.context instanceof Function)
+})
+
+it('names a directory without package.json by its reference', async () => {
+  const path = join(import.meta.dirname, 'dummies/bare')
+  const { name, module } = await definition(path)
+
+  assert.equal(name, path)
+  assert.equal(module.declares, true)
+})
+
+it('loads a definition once', async () => {
+  const path = join(import.meta.dirname, 'dummies/bare')
+
+  assert.equal(await definition(path), await definition(path))
+})

package/test/dummies/bare/index.js

@@ -0,0 +1 @@
+export const declares = true

package/test/dummies/defined/definition.js

@@ -0,0 +1 @@
+export const declares = true

package/test/dummies/defined/index.js

@@ -0,0 +1 @@
+export const runs = true

package/test/dummies/defined/package.json

@@ -0,0 +1 @@
+{ "name": "dummies.defined", "type": "module", "main": "index.js" }

package/test/manifest.test.js

@@ -0,0 +1,126 @@
+import { it, describe } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { resolve } from 'node:path'
+
+import { component } from '../src/component.js'
+import { plain, revive } from '../src/manifest.js'
+
+/** the prototype itself: an entity, operations and events, and no prototype of its own */
+const PROTOTYPE = resolve(import.meta.dirname, '../../prototype')
+
+/** a component on the default prototype, with an entity, events and receivers */
+const COMPONENT = resolve(
+  import.meta.dirname,
+  '../../../features/steps/.workspace/components/collection/external.consumer'
+)
+
+/** a component whose prototype is a directory of the workspace's own */
+const EXTENDED = resolve(
+  import.meta.dirname,
+  '../../../features/steps/.workspace/components/collection/configuration.extended'
+)
+
+const carry = (manifest) => JSON.parse(JSON.stringify(plain(manifest)))
+
+describe('a manifest carried through a file', () => {
+  for (const [name, path] of [
+    ['the prototype', PROTOTYPE],
+    ['a component', COMPONENT]
+  ])
+    it(`comes back the same: ${name}`, async () => {
+      const manifest = await component(path)
+
+      assert.deepStrictEqual(revive(carry(manifest), path), manifest)
+    })
+
+  it('does not carry a key with no value', () => {
+    const carried = plain({ name: 'a', namespace: 'b', path: '/x', operations: { echo: { input: undefined } } })
+
+    assert.deepStrictEqual(carried.operations.echo, {})
+  })
+
+  it('leaves the manifest it was given alone', async () => {
+    const manifest = await component(COMPONENT)
+    const before = JSON.stringify(manifest)
+
+    plain(manifest)
+
+    assert.strictEqual(JSON.stringify(manifest), before)
+  })
+
+  it('is read beside the component wherever it is', async () => {
+    const carried = carry(await component(COMPONENT))
+    const revived = revive(carried, '/composition/external-consumer')
+
+    assert.strictEqual(revived.path, '/composition/external-consumer')
+
+    // what the component declares is in the component
+    assert.strictEqual(
+      revived.receivers['something_happened'].path,
+      '/composition/external-consumer'
+    )
+  })
+
+  it('reads what is inherited where the prototype is', async () => {
+    const prototype = (await component(COMPONENT)).prototype.path
+    const revived = revive(carry(await component(COMPONENT)), '/composition/external-consumer')
+
+    // an event of the prototype's is in the prototype, wherever the component is
+    assert.strictEqual(revived.events.created.path, prototype)
+  })
+
+  it('carries what is inherited by the package that holds it', async () => {
+    const carried = carry(await component(COMPONENT))
+
+    assert.strictEqual(carried.prototype.path, '@toa.io/prototype')
+    assert.strictEqual(carried.events.created.path, '@toa.io/prototype')
+    assert.strictEqual(carried.receivers['something_happened'].path, '.')
+  })
+})
+
+describe('what cannot be carried', () => {
+  it('leaves out where the manifest is and what only a deploy reads', async () => {
+    const manifest = await component(PROTOTYPE)
+
+    manifest.packages = { cloudinary: '2.11.0' }
+
+    const carried = plain(manifest)
+
+    assert.ok(!('locator' in carried))
+    assert.ok(!('path' in carried))
+    assert.ok(!('packages' in carried))
+  })
+
+  it('refuses a prototype an image would not have', async () => {
+    const manifest = await component(EXTENDED)
+
+    assert.throws(() => plain(manifest), /is in no package, so an image cannot carry what is in it/)
+  })
+
+  it('refuses a path inside the component it does not know about', () => {
+    assert.throws(
+      () => plain({ name: 'a', namespace: 'b', path: '/x', invented: { at: '/x/y' } }),
+      /carries a path of the machine that read it/
+    )
+  })
+
+  it('refuses a component directory it does not know about', async () => {
+    const manifest = await component(PROTOTYPE)
+
+    manifest.invented = { at: COMPONENT }
+
+    assert.throws(() => plain(manifest), /carries a path of the machine that read it/)
+  })
+
+  it('leaves a value of the application\'s own alone', () => {
+    const carried = plain({
+      name: 'a',
+      namespace: 'b',
+      path: '/x',
+      extensions: { exposition: { routes: [{ path: '/accounts' }] } }
+    })
+
+    assert.strictEqual(carried.extensions.exposition.routes[0].path, '/accounts')
+  })
+})

package/types/component.d.ts

@@ -65,10 +65,11 @@ type Declaration = {
   events?: Events
   receivers?: Record<string, Receiver>
   extensions?: Record<string, object>
-  properties?: Record<string, object>
 }
 
 export type Manifest = Declaration & {
   locator: Locator
   path: string
+  /** what a deploy installs beside this component for what it declares, by package name */
+  packages?: Record<string, string>
 }

package/types/context.d.ts

@@ -23,6 +23,8 @@ interface Composition {
   name: string
   components: Manifest[]
   services?: string[]
+  /** what a deploy installs for the services this composition runs, by package name */
+  packages?: Record<string, string>
 }
 
 export interface Dependency<T = undefined> {
@@ -38,6 +40,8 @@ interface Context extends Declaration {
   compositions?: Composition[]
   components?: Manifest[]
   dependencies?: Record<string, Dependency[]>
+  /** what a deploy installs for every service, which is what `mono` runs */
+  packages?: Record<string, string>
 }
 
 export function context(path: string, environment?: string): Promise<Context>

package/types/index.d.ts

@@ -3,3 +3,11 @@ export * as component from './component.js'
 
 export { Manifest } from './component.js'
 export * as entity from './entity.js'
+
+export interface Definition {
+  /** The package's name, or the reference where it has no package.json */
+  name: string
+  module: Record<string, any>
+}
+
+export function definition(reference: string): Promise<Definition>

package/src/.component/.expand/properties.js

@@ -1,10 +0,0 @@
-import { recognize } from '../../shortcuts.js'
-
-export function properties(manifest) {
-  recognize(SHORTCUTS, manifest, 'properties')
-  recognize(SHORTCUTS, manifest.properties)
-}
-
-const SHORTCUTS = {
-  queues: '@toa.io/storages.queues'
-}

package/src/.context/.dependencies/load.js

@@ -1,39 +0,0 @@
-import { createRequire } from 'node:module'
-import { readFileSync } from 'node:fs'
-import { join } from 'node:path'
-import { pathToFileURL } from 'node:url'
-
-// import.meta.resolve takes no paths, and a dependency is named rather than
-// written as a path
-const require = createRequire(import.meta.url)
-
-/**
- * @param {string} path
- * @returns {Promise<{ metadata: object, module: object }>}
- */
-export async function load(path) {
-  const metadata = loadMetadata(path)
-  const module = await loadModule(path)
-
-  return { metadata, module }
-}
-
-function loadMetadata(reference) {
-  try {
-    return JSON.parse(
-      readFileSync(require.resolve(join(reference, 'package.json')), 'utf8')
-    )
-  } catch {
-    return null
-  }
-}
-
-/**
- * @param {string} reference
- * @returns {Promise<object>}
- */
-async function loadModule(reference) {
-  const path = require.resolve(reference)
-
-  return await import(pathToFileURL(path).href)
-}

package/test/context/dependencies.load.test.js

@@ -1,25 +0,0 @@
-import { it } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { join } from 'node:path'
-import { load } from '../../src/.context/.dependencies/load.js'
-
-it('should be', async () => {
-  assert.ok(load instanceof Function)
-})
-
-it('should load module', async () => {
-  const path = join(import.meta.dirname, '../../')
-  const { metadata, module } = await load(path)
-
-  assert.deepStrictEqual(metadata.name, '@toa.io/norm')
-  assert.ok(module.context instanceof Function)
-})
-
-it('should return null metadata if no package.json', async () => {
-  const path = join(import.meta.dirname, '../../src')
-  const { metadata, module } = await load(path)
-
-  assert.strictEqual(metadata, null)
-  assert.ok(module.context instanceof Function)
-})