@toa.io/extensions.configuration 1.0.0-alpha.29 → 1.0.0-alpha.292

package/CHANGELOG.md

@@ -0,0 +1,42 @@
+# 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.292](https://github.com/toa-io/toa/compare/v1.0.0-alpha.291...v1.0.0-alpha.292) (2026-09-07)
+
+### Features
+
+* **definitions:** what a package declares is read from one package ([7052341](https://github.com/toa-io/toa/commit/70523411b5d9e2b204c999aa02365173f3bb518d))
+
+
+# [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/extensions.configuration
+
+
+
+
+
+# [1.0.0-alpha.289](https://github.com/toa-io/toa/compare/v1.0.0-alpha.288...v1.0.0-alpha.289) (2026-09-07)
+
+* A deploy moves only what changed, and a component sees none of the runtime's environment (#1073) ([f38e3db](https://github.com/toa-io/toa/commit/f38e3db533f24db866c57bfa1ef294eff1eaf499)), closes [#1073](https://github.com/toa-io/toa/issues/1073) [#1064](https://github.com/toa-io/toa/issues/1064) [#1066](https://github.com/toa-io/toa/issues/1066) [#1067](https://github.com/toa-io/toa/issues/1067) [#1068](https://github.com/toa-io/toa/issues/1068) [#1069](https://github.com/toa-io/toa/issues/1069) [#1071](https://github.com/toa-io/toa/issues/1071) [#1070](https://github.com/toa-io/toa/issues/1070) [#1072](https://github.com/toa-io/toa/issues/1072)
+
+### BREAKING CHANGES
+
+* a component that read `process.env.TOA_*` reads `context` instead;
+  `echo(input)` no longer substitutes from the environment; a bash operation sees no
+  `TOA_*`; images no longer set `USER node` — see migrations/289.md.
+
+
+# [1.0.0-alpha.288](https://github.com/toa-io/toa/compare/v1.0.0-alpha.287...v1.0.0-alpha.288) (2026-09-06)
+
+**Note:** Version bump only for package @toa.io/extensions.configuration
+
+
+
+
+
+# [1.0.0-alpha.287](https://github.com/toa-io/toa/compare/v1.0.0-alpha.286...v1.0.0-alpha.287) (2026-09-06)
+
+**Note:** Version bump only for package @toa.io/extensions.configuration

package/components/configuration.values/manifest.toa.yaml

@@ -0,0 +1,151 @@
+namespace: configuration
+name: values
+
+# One document per configuration created. Documents are immutable: a change is a new
+# document, and the latest one for a component and an epoch is the last created.
+# What every component's epoch, schema and defaults are, the service is told on
+# deployment (`TOA_CONFIGURATION_VALUES`). A created object is published as the
+# prototype's `created` event.
+
+entity:
+  properties:
+    component:
+      type: string
+    epoch:
+      type: string
+    configuration:
+      type: object
+    originator:
+      type: string
+  required:
+    - component
+    - epoch
+    - configuration
+    - originator
+
+operations:
+  # the latest configuration of a component: created, else deployed defaults, else none
+  get:
+    query: false
+    input:
+      type: object
+      properties:
+        component:
+          type: string
+        epoch:
+          type: string
+      required:
+        - component
+    # the value and the schema it is checked against, so a caller can show and check it
+    output:
+      type: object
+      nullable: true
+      properties:
+        configuration:
+          type: object
+        schema:
+          type: object
+        epoch:
+          type: string
+      required:
+        - configuration
+        - epoch
+  # the same for many at once, as the aspects of one process ask
+  fetch:
+    query: false
+    input:
+      type: array
+      items:
+        type: object
+        properties:
+          component:
+            type: string
+          epoch:
+            type: string
+        required:
+          - component
+          - epoch
+    output:
+      type: array
+      items:
+        type: object
+        properties:
+          component:
+            type: string
+          epoch:
+            type: string
+          configuration:
+            type: object
+            nullable: true
+          created:
+            type: integer
+        required:
+          - component
+          - epoch
+          - configuration
+          - created
+  # every component's configuration for its deployed epoch, by component name
+  list:
+    query: false
+    output:
+      type: array
+      items:
+        type: object
+        properties:
+          component:
+            type: string
+          epoch:
+            type: string
+          schema:
+            type: object
+          configuration:
+            type: object
+        required:
+          - component
+          - epoch
+          - schema
+          - configuration
+  create:
+    query: false
+    input:
+      type: object
+      properties:
+        component:
+          type: string
+        configuration:
+          type: object
+        originator:
+          type: object
+          properties:
+            id:
+              type: string
+          required:
+            - id
+      required:
+        - component
+        - configuration
+        - originator
+    errors:
+      - UNKNOWN_COMPONENT
+      - INVALID_CONFIGURATION
+
+exposition:
+  isolated: true
+  /:
+    GET:
+      io:output: true
+      auth:role: system:configuration:get
+      endpoint: list
+  /:component:
+    map:segments:
+      component: component
+    GET:
+      io:output: true
+      auth:role: system:configuration:get
+      endpoint: get
+    POST:
+      io:output: [id, epoch]
+      auth:rule:
+        role: system:configuration:create
+        delegate: originator
+      endpoint: create

package/components/configuration.values/migrations/0002-indexes.yaml

@@ -0,0 +1,7 @@
+- index:
+    name: index_lookup
+    keys:
+      component: asc
+      epoch: asc
+      CREATED: desc
+    sparse: true

package/components/configuration.values/operations/create.js

@@ -0,0 +1,30 @@
+import * as schemas from '@toa.io/schemas';
+import { entry } from './lib/map.js';
+export async function transition(input, object) {
+    const known = entry(input.component);
+    if (known === undefined)
+        return new UnknownComponentError(input.component);
+    const configuration = structuredClone(input.configuration);
+    const schema = schemas.schema(known.schema);
+    try {
+        schema.validate(configuration);
+    }
+    catch (error) {
+        return new InvalidConfigurationError(error.message);
+    }
+    object.component = input.component;
+    object.epoch = known.epoch;
+    object.configuration = configuration;
+    object.originator = input.originator.id;
+    return object;
+}
+class UnknownComponentError extends Error {
+    code = 'UNKNOWN_COMPONENT';
+    constructor(component) {
+        super(`Component '${component}' is not configured`);
+    }
+}
+class InvalidConfigurationError extends Error {
+    code = 'INVALID_CONFIGURATION';
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY3JlYXRlLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc291cmNlL2NyZWF0ZS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLGlCQUFpQixDQUFBO0FBQzFDLE9BQU8sRUFBRSxLQUFLLEVBQUUsTUFBTSxjQUFjLENBQUE7QUFHcEMsTUFBTSxDQUFDLEtBQUssVUFBVSxVQUFVLENBQUMsS0FBWSxFQUFFLE1BQWM7SUFDM0QsTUFBTSxLQUFLLEdBQUcsS0FBSyxDQUFDLEtBQUssQ0FBQyxTQUFTLENBQUMsQ0FBQTtJQUVwQyxJQUFJLEtBQUssS0FBSyxTQUFTO1FBQUUsT0FBTyxJQUFJLHFCQUFxQixDQUFDLEtBQUssQ0FBQyxTQUFTLENBQUMsQ0FBQTtJQUUxRSxNQUFNLGFBQWEsR0FBRyxlQUFlLENBQUMsS0FBSyxDQUFDLGFBQWEsQ0FBQyxDQUFBO0lBRTFELE1BQU0sTUFBTSxHQUFnQixPQUFPLENBQUMsTUFBTSxDQUFDLEtBQUssQ0FBQyxNQUFNLENBQUMsQ0FBQTtJQUV4RCxJQUFJLENBQUM7UUFDSCxNQUFNLENBQUMsUUFBUSxDQUFDLGFBQWEsQ0FBQyxDQUFBO0lBQ2hDLENBQUM7SUFBQyxPQUFPLEtBQUssRUFBRSxDQUFDO1FBQ2YsT0FBTyxJQUFJLHlCQUF5QixDQUFFLEtBQWUsQ0FBQyxPQUFPLENBQUMsQ0FBQTtJQUNoRSxDQUFDO0lBRUQsTUFBTSxDQUFDLFNBQVMsR0FBRyxLQUFLLENBQUMsU0FBUyxDQUFBO0lBQ2xDLE1BQU0sQ0FBQyxLQUFLLEdBQUcsS0FBSyxDQUFDLEtBQUssQ0FBQTtJQUMxQixNQUFNLENBQUMsYUFBYSxHQUFHLGFBQWEsQ0FBQTtJQUNwQyxNQUFNLENBQUMsVUFBVSxHQUFHLEtBQUssQ0FBQyxVQUFVLENBQUMsRUFBRSxDQUFBO0lBRXZDLE9BQU8sTUFBTSxDQUFBO0FBQ2YsQ0FBQztBQUVELE1BQU0scUJBQXNCLFNBQVEsS0FBSztJQUN2QixJQUFJLEdBQUcsbUJBQW1CLENBQUE7SUFFMUMsWUFBbUIsU0FBaUI7UUFDbEMsS0FBSyxDQUFDLGNBQWMsU0FBUyxxQkFBcUIsQ0FBQyxDQUFBO0lBQ3JELENBQUM7Q0FDRjtBQUVELE1BQU0seUJBQTBCLFNBQVEsS0FBSztJQUMzQixJQUFJLEdBQUcsdUJBQXVCLENBQUE7Q0FDL0MifQ==

package/components/configuration.values/operations/fetch.js

@@ -0,0 +1,13 @@
+import { resolve } from './lib/resolve.js';
+export async function computation(input, context) {
+    return await Promise.all(input.map(async ({ component, epoch }) => {
+        const value = await resolve(context, component, epoch);
+        return {
+            component,
+            epoch,
+            configuration: value === null ? null : value.configuration,
+            created: value === null ? 0 : value.created
+        };
+    }));
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZmV0Y2guanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zb3VyY2UvZmV0Y2gudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxFQUFFLE9BQU8sRUFBZ0IsTUFBTSxrQkFBa0IsQ0FBQTtBQUV4RCxNQUFNLENBQUMsS0FBSyxVQUFVLFdBQVcsQ0FBQyxLQUFhLEVBQUUsT0FBZ0I7SUFDL0QsT0FBTyxNQUFNLE9BQU8sQ0FBQyxHQUFHLENBQ3RCLEtBQUssQ0FBQyxHQUFHLENBQUMsS0FBSyxFQUFFLEVBQUUsU0FBUyxFQUFFLEtBQUssRUFBRSxFQUFFLEVBQUU7UUFDdkMsTUFBTSxLQUFLLEdBQUcsTUFBTSxPQUFPLENBQUMsT0FBTyxFQUFFLFNBQVMsRUFBRSxLQUFLLENBQUMsQ0FBQTtRQUV0RCxPQUFPO1lBQ0wsU0FBUztZQUNULEtBQUs7WUFDTCxhQUFhLEVBQUUsS0FBSyxLQUFLLElBQUksQ0FBQyxDQUFDLENBQUMsSUFBSSxDQUFDLENBQUMsQ0FBQyxLQUFLLENBQUMsYUFBYTtZQUMxRCxPQUFPLEVBQUUsS0FBSyxLQUFLLElBQUksQ0FBQyxDQUFDLENBQUMsQ0FBQyxDQUFDLENBQUMsQ0FBQyxLQUFLLENBQUMsT0FBTztTQUM1QyxDQUFBO0lBQ0gsQ0FBQyxDQUFDLENBQ0gsQ0FBQTtBQUNILENBQUMifQ==

package/components/configuration.values/operations/get.js

@@ -0,0 +1,19 @@
+import { entry } from './lib/map.js';
+import { resolve } from './lib/resolve.js';
+/**
+ * The latest configuration of a component, with the schema it is checked against. The
+ * schema is the deployment's, so an epoch the deployment does not know has none — the
+ * value is still what was stored for it.
+ */
+export async function computation(input, context) {
+    const value = await resolve(context, input.component, input.epoch);
+    if (value === null)
+        return null;
+    const known = entry(input.component);
+    return {
+        configuration: value.configuration,
+        schema: known?.schema,
+        epoch: input.epoch ?? known.epoch
+    };
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZ2V0LmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc291cmNlL2dldC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQUUsS0FBSyxFQUFFLE1BQU0sY0FBYyxDQUFBO0FBQ3BDLE9BQU8sRUFBRSxPQUFPLEVBQWdCLE1BQU0sa0JBQWtCLENBQUE7QUFFeEQ7Ozs7R0FJRztBQUNILE1BQU0sQ0FBQyxLQUFLLFVBQVUsV0FBVyxDQUFDLEtBQVksRUFBRSxPQUFnQjtJQUM5RCxNQUFNLEtBQUssR0FBRyxNQUFNLE9BQU8sQ0FBQyxPQUFPLEVBQUUsS0FBSyxDQUFDLFNBQVMsRUFBRSxLQUFLLENBQUMsS0FBSyxDQUFDLENBQUE7SUFFbEUsSUFBSSxLQUFLLEtBQUssSUFBSTtRQUFFLE9BQU8sSUFBSSxDQUFBO0lBRS9CLE1BQU0sS0FBSyxHQUFHLEtBQUssQ0FBQyxLQUFLLENBQUMsU0FBUyxDQUFDLENBQUE7SUFFcEMsT0FBTztRQUNMLGFBQWEsRUFBRSxLQUFLLENBQUMsYUFBYTtRQUNsQyxNQUFNLEVBQUUsS0FBSyxFQUFFLE1BQU07UUFDckIsS0FBSyxFQUFFLEtBQUssQ0FBQyxLQUFLLElBQUksS0FBTSxDQUFDLEtBQUs7S0FDbkMsQ0FBQTtBQUNILENBQUMifQ==

package/components/configuration.values/operations/lib/map.js

@@ -0,0 +1,22 @@
+import { environment } from '@toa.io/generic';
+/** What the deployment told the service about every configured component. */
+export function entry(component) {
+    return read()[component];
+}
+/** The configured components, by name. */
+export function components() {
+    return Object.keys(read()).sort();
+}
+function read() {
+    const source = environment.get(VARIABLE) ?? '{}';
+    // read again once the variable changes, as it does between scenarios of one process
+    if (source !== parsed) {
+        values = JSON.parse(source);
+        parsed = source;
+    }
+    return values;
+}
+let parsed = null;
+let values = {};
+export const VARIABLE = 'TOA_CONFIGURATION_VALUES';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibWFwLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc291cmNlL2xpYi9tYXAudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxFQUFFLFdBQVcsRUFBRSxNQUFNLGlCQUFpQixDQUFBO0FBRTdDLDZFQUE2RTtBQUM3RSxNQUFNLFVBQVUsS0FBSyxDQUFDLFNBQWlCO0lBQ3JDLE9BQU8sSUFBSSxFQUFFLENBQUMsU0FBUyxDQUFDLENBQUE7QUFDMUIsQ0FBQztBQUVELDBDQUEwQztBQUMxQyxNQUFNLFVBQVUsVUFBVTtJQUN4QixPQUFPLE1BQU0sQ0FBQyxJQUFJLENBQUMsSUFBSSxFQUFFLENBQUMsQ0FBQyxJQUFJLEVBQUUsQ0FBQTtBQUNuQyxDQUFDO0FBRUQsU0FBUyxJQUFJO0lBQ1gsTUFBTSxNQUFNLEdBQUcsV0FBVyxDQUFDLEdBQUcsQ0FBQyxRQUFRLENBQUMsSUFBSSxJQUFJLENBQUE7SUFFaEQsb0ZBQW9GO0lBQ3BGLElBQUksTUFBTSxLQUFLLE1BQU0sRUFBRSxDQUFDO1FBQ3RCLE1BQU0sR0FBRyxJQUFJLENBQUMsS0FBSyxDQUFDLE1BQU0sQ0FBVyxDQUFBO1FBQ3JDLE1BQU0sR0FBRyxNQUFNLENBQUE7SUFDakIsQ0FBQztJQUVELE9BQU8sTUFBTSxDQUFBO0FBQ2YsQ0FBQztBQUVELElBQUksTUFBTSxHQUFrQixJQUFJLENBQUE7QUFDaEMsSUFBSSxNQUFNLEdBQVcsRUFBRSxDQUFBO0FBRXZCLE1BQU0sQ0FBQyxNQUFNLFFBQVEsR0FBRywwQkFBMEIsQ0FBQSJ9

package/components/configuration.values/operations/lib/resolve.js

@@ -0,0 +1,24 @@
+import { entry } from './map.js';
+/**
+ * The latest configuration created for the component and the epoch; the deployed
+ * defaults when none was; `null` when the epoch is not the one deployed.
+ */
+export async function resolve(context, component, epoch) {
+    const known = entry(component);
+    epoch ??= known?.epoch;
+    if (epoch === undefined)
+        return null;
+    // one query per pair, so that a component's latest is never behind another's newer ones
+    const query = {
+        criteria: `component=="${component}";epoch=="${epoch}"`,
+        sort: ['CREATED:desc'],
+        limit: 1
+    };
+    const objects = await context.local.enumerate({ query });
+    if (objects.length > 0)
+        return { configuration: objects[0].configuration, created: objects[0].CREATED };
+    if (known !== undefined && known.epoch === epoch)
+        return { configuration: known.defaults ?? {}, created: 0 };
+    return null;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicmVzb2x2ZS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NvdXJjZS9saWIvcmVzb2x2ZS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQUUsS0FBSyxFQUFFLE1BQU0sVUFBVSxDQUFBO0FBRWhDOzs7R0FHRztBQUNILE1BQU0sQ0FBQyxLQUFLLFVBQVUsT0FBTyxDQUMzQixPQUFnQixFQUNoQixTQUFpQixFQUNqQixLQUFjO0lBRWQsTUFBTSxLQUFLLEdBQUcsS0FBSyxDQUFDLFNBQVMsQ0FBQyxDQUFBO0lBRTlCLEtBQUssS0FBSyxLQUFLLEVBQUUsS0FBSyxDQUFBO0lBRXRCLElBQUksS0FBSyxLQUFLLFNBQVM7UUFBRSxPQUFPLElBQUksQ0FBQTtJQUVwQyx3RkFBd0Y7SUFDeEYsTUFBTSxLQUFLLEdBQVU7UUFDbkIsUUFBUSxFQUFFLGVBQWUsU0FBUyxhQUFhLEtBQUssR0FBRztRQUN2RCxJQUFJLEVBQUUsQ0FBQyxjQUFjLENBQUM7UUFDdEIsS0FBSyxFQUFFLENBQUM7S0FDVCxDQUFBO0lBRUQsTUFBTSxPQUFPLEdBQUcsTUFBTSxPQUFPLENBQUMsS0FBSyxDQUFDLFNBQVMsQ0FBQyxFQUFFLEtBQUssRUFBRSxDQUFDLENBQUE7SUFFeEQsSUFBSSxPQUFPLENBQUMsTUFBTSxHQUFHLENBQUM7UUFDcEIsT0FBTyxFQUFFLGFBQWEsRUFBRSxPQUFPLENBQUMsQ0FBQyxDQUFDLENBQUMsYUFBYSxFQUFFLE9BQU8sRUFBRSxPQUFPLENBQUMsQ0FBQyxDQUFDLENBQUMsT0FBTyxFQUFFLENBQUE7SUFFakYsSUFBSSxLQUFLLEtBQUssU0FBUyxJQUFJLEtBQUssQ0FBQyxLQUFLLEtBQUssS0FBSztRQUM5QyxPQUFPLEVBQUUsYUFBYSxFQUFFLEtBQUssQ0FBQyxRQUFRLElBQUksRUFBRSxFQUFFLE9BQU8sRUFBRSxDQUFDLEVBQUUsQ0FBQTtJQUU1RCxPQUFPLElBQUksQ0FBQTtBQUNiLENBQUMifQ==

package/components/configuration.values/operations/list.js

@@ -0,0 +1,11 @@
+import { components, entry } from './lib/map.js';
+import { resolve } from './lib/resolve.js';
+/** The configuration of every component for its deployed epoch, by component name. */
+export async function computation(_, context) {
+    return await Promise.all(components().map(async (component) => {
+        const { epoch, schema } = entry(component);
+        const value = await resolve(context, component, epoch);
+        return { component, epoch, schema, configuration: value.configuration };
+    }));
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibGlzdC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3NvdXJjZS9saXN0LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sRUFBRSxVQUFVLEVBQUUsS0FBSyxFQUFFLE1BQU0sY0FBYyxDQUFBO0FBQ2hELE9BQU8sRUFBRSxPQUFPLEVBQWdCLE1BQU0sa0JBQWtCLENBQUE7QUFFeEQsc0ZBQXNGO0FBQ3RGLE1BQU0sQ0FBQyxLQUFLLFVBQVUsV0FBVyxDQUFDLENBQU8sRUFBRSxPQUFnQjtJQUN6RCxPQUFPLE1BQU0sT0FBTyxDQUFDLEdBQUcsQ0FDdEIsVUFBVSxFQUFFLENBQUMsR0FBRyxDQUFDLEtBQUssRUFBRSxTQUFTLEVBQUUsRUFBRTtRQUNuQyxNQUFNLEVBQUUsS0FBSyxFQUFFLE1BQU0sRUFBRSxHQUFHLEtBQUssQ0FBQyxTQUFTLENBQUUsQ0FBQTtRQUMzQyxNQUFNLEtBQUssR0FBRyxNQUFNLE9BQU8sQ0FBQyxPQUFPLEVBQUUsU0FBUyxFQUFFLEtBQUssQ0FBQyxDQUFBO1FBRXRELE9BQU8sRUFBRSxTQUFTLEVBQUUsS0FBSyxFQUFFLE1BQU0sRUFBRSxhQUFhLEVBQUUsS0FBTSxDQUFDLGFBQWEsRUFBRSxDQUFBO0lBQzFFLENBQUMsQ0FBQyxDQUNILENBQUE7QUFDSCxDQUFDIn0=

package/components/configuration.values/source/create.ts

@@ -0,0 +1,54 @@
+import * as schemas from '@toa.io/schemas'
+import { entry } from './lib/map.js'
+import type { Schema } from '@toa.io/schemas'
+
+export async function transition(input: Input, object: Entity): Promise<Entity | Error> {
+  const known = entry(input.component)
+
+  if (known === undefined) return new UnknownComponentError(input.component)
+
+  const configuration = structuredClone(input.configuration)
+
+  const schema: Schema<any> = schemas.schema(known.schema)
+
+  try {
+    schema.validate(configuration)
+  } catch (error) {
+    return new InvalidConfigurationError((error as Error).message)
+  }
+
+  object.component = input.component
+  object.epoch = known.epoch
+  object.configuration = configuration
+  object.originator = input.originator.id
+
+  return object
+}
+
+class UnknownComponentError extends Error {
+  public readonly code = 'UNKNOWN_COMPONENT'
+
+  public constructor(component: string) {
+    super(`Component '${component}' is not configured`)
+  }
+}
+
+class InvalidConfigurationError extends Error {
+  public readonly code = 'INVALID_CONFIGURATION'
+}
+
+interface Input {
+  component: string
+  configuration: object
+  originator: {
+    id: string
+  }
+}
+
+interface Entity {
+  id: string
+  component: string
+  epoch: string
+  configuration: object
+  originator: string
+}

package/components/configuration.values/source/fetch.ts

@@ -0,0 +1,26 @@
+import { resolve, type Context } from './lib/resolve.js'
+
+export async function computation(input: Pair[], context: Context): Promise<Fetched[]> {
+  return await Promise.all(
+    input.map(async ({ component, epoch }) => {
+      const value = await resolve(context, component, epoch)
+
+      return {
+        component,
+        epoch,
+        configuration: value === null ? null : value.configuration,
+        created: value === null ? 0 : value.created
+      }
+    })
+  )
+}
+
+interface Pair {
+  component: string
+  epoch: string
+}
+
+interface Fetched extends Pair {
+  configuration: object | null
+  created: number
+}

package/components/configuration.values/source/get.ts

@@ -0,0 +1,32 @@
+import { entry } from './lib/map.js'
+import { resolve, type Context } from './lib/resolve.js'
+
+/**
+ * The latest configuration of a component, with the schema it is checked against. The
+ * schema is the deployment's, so an epoch the deployment does not know has none — the
+ * value is still what was stored for it.
+ */
+export async function computation(input: Input, context: Context): Promise<Item | null> {
+  const value = await resolve(context, input.component, input.epoch)
+
+  if (value === null) return null
+
+  const known = entry(input.component)
+
+  return {
+    configuration: value.configuration,
+    schema: known?.schema,
+    epoch: input.epoch ?? known!.epoch
+  }
+}
+
+interface Input {
+  component: string
+  epoch?: string
+}
+
+interface Item {
+  configuration: object
+  schema?: object
+  epoch: string
+}

package/components/configuration.values/source/lib/map.test.ts

@@ -0,0 +1,42 @@
+import { it, afterEach } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { VARIABLE, components, entry } from './map.js'
+
+afterEach(() => {
+  delete process.env[VARIABLE]
+})
+
+it('should be empty without the variable', () => {
+  assert.strictEqual(entry('a.b'), undefined)
+})
+
+it('should read the variable', () => {
+  const values = {
+    'a.b': { epoch: 'e', schema: { type: 'object' }, defaults: { foo: 1 } }
+  }
+
+  process.env[VARIABLE] = JSON.stringify(values)
+
+  assert.deepStrictEqual(entry('a.b'), values['a.b'])
+  assert.strictEqual(entry('a.c'), undefined)
+})
+
+it('should follow the variable', () => {
+  process.env[VARIABLE] = JSON.stringify({ 'a.b': { epoch: 'e1', schema: {} } })
+
+  assert.deepStrictEqual(entry('a.b')?.epoch, 'e1')
+
+  process.env[VARIABLE] = JSON.stringify({ 'a.b': { epoch: 'e2', schema: {} } })
+
+  assert.deepStrictEqual(entry('a.b')?.epoch, 'e2')
+})
+
+it('should list the components by name', () => {
+  process.env[VARIABLE] = JSON.stringify({
+    'b.two': { epoch: 'e', schema: {} },
+    'a.one': { epoch: 'e', schema: {} }
+  })
+
+  assert.deepStrictEqual(components(), ['a.one', 'b.two'])
+})

package/components/configuration.values/source/lib/map.ts

@@ -0,0 +1,36 @@
+import { environment } from '@toa.io/generic'
+
+/** What the deployment told the service about every configured component. */
+export function entry(component: string): Entry | undefined {
+  return read()[component]
+}
+
+/** The configured components, by name. */
+export function components(): string[] {
+  return Object.keys(read()).sort()
+}
+
+function read(): Values {
+  const source = environment.get(VARIABLE) ?? '{}'
+
+  // read again once the variable changes, as it does between scenarios of one process
+  if (source !== parsed) {
+    values = JSON.parse(source) as Values
+    parsed = source
+  }
+
+  return values
+}
+
+let parsed: string | null = null
+let values: Values = {}
+
+export const VARIABLE = 'TOA_CONFIGURATION_VALUES'
+
+export interface Entry {
+  epoch: string
+  schema: object
+  defaults?: object
+}
+
+export type Values = Record<string, Entry>

package/components/configuration.values/source/lib/resolve.ts

@@ -0,0 +1,57 @@
+import { entry } from './map.js'
+
+/**
+ * The latest configuration created for the component and the epoch; the deployed
+ * defaults when none was; `null` when the epoch is not the one deployed.
+ */
+export async function resolve(
+  context: Context,
+  component: string,
+  epoch?: string
+): Promise<Value | null> {
+  const known = entry(component)
+
+  epoch ??= known?.epoch
+
+  if (epoch === undefined) return null
+
+  // one query per pair, so that a component's latest is never behind another's newer ones
+  const query: Query = {
+    criteria: `component=="${component}";epoch=="${epoch}"`,
+    sort: ['CREATED:desc'],
+    limit: 1
+  }
+
+  const objects = await context.local.enumerate({ query })
+
+  if (objects.length > 0)
+    return { configuration: objects[0].configuration, created: objects[0].CREATED }
+
+  if (known !== undefined && known.epoch === epoch)
+    return { configuration: known.defaults ?? {}, created: 0 }
+
+  return null
+}
+
+/** A configuration and when it was created; `0` for the deployed defaults. */
+export interface Value {
+  configuration: object
+  created: number
+}
+
+export interface Context {
+  local: {
+    enumerate: (request: { query: Query }) => Promise<Stored[]>
+  }
+}
+
+interface Query {
+  criteria: string
+  sort: string[]
+  limit: number
+}
+
+interface Stored {
+  configuration: object
+  CREATED: number
+}

package/components/configuration.values/source/list.ts

@@ -0,0 +1,21 @@
+import { components, entry } from './lib/map.js'
+import { resolve, type Context } from './lib/resolve.js'
+
+/** The configuration of every component for its deployed epoch, by component name. */
+export async function computation(_: null, context: Context): Promise<Item[]> {
+  return await Promise.all(
+    components().map(async (component) => {
+      const { epoch, schema } = entry(component)!
+      const value = await resolve(context, component, epoch)
+
+      return { component, epoch, schema, configuration: value!.configuration }
+    })
+  )
+}
+
+interface Item {
+  component: string
+  epoch: string
+  schema: object
+  configuration: object
+}

package/components/configuration.values/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../../../tsconfig.component.json",
+  "compilerOptions": {
+    "outDir": "./operations",
+    "rootDir": "./source"
+  },
+  "include": [
+    "source"
+  ]
+}