configuration

# configuration The `configuration` worker is a server-side registry of named entries. Every entry has an id (e.g. `iii-stream`, `billing-service`), a human-readable name and description, a JSON Schema describing the value shape, and a JSON value validated against that schema. Workers call `configuration::register` once at startup to declare their schema and `configuration::set` to publish values; consumers call `configuration::get` / `configuration::list` to read and bind a `configuration` trigger to react to changes without polling. The default `fs` adapter persists one YAML file per id under `./config` and watches the directory for external edits, so manual edits surface as `configuration:updated` events. The `bridge` adapter delegates to a remote engine. The worker is engine-owned and may be configured at `engine.workers.configuration`. A per-id TTL (off by default) cleans up entries whose last subscriber trigger has unregistered, scoped to the lifecycle of ephemeral workers that come and go without an explicit teardown step. ## When to Use - A worker needs a typed, observable configuration surface other workers can read and validate against. - Two workers need to agree on the same configuration values without one polling the other or hardcoding a path on disk. - An operator should be able to edit a single YAML file (or the remote control plane) and have the change propagate to every subscriber without a worker restart. - A worker comes and goes (sandboxes, ephemeral consumers) and its configuration should be cleaned up automatically when no one is left subscribing. ## Boundaries - Not a general-purpose key/value store — every entry must have a registered JSON Schema. Use the standalone `state` worker for free-form values. - No partial-update surface; `set` always replaces the whole value. Build the new value client-side and ship it in one call. - The `bridge` adapter cannot delete entries on the remote engine; cleanup over the bridge happens via TTL or directly on the source engine. - Over the `bridge` adapter, `configuration::ensure` is decided by the remote engine (the original candidate is forwarded there), so it requires a remote engine that exposes `configuration::ensure`; against an older remote it fails closed with `ADAPTER_ERROR` rather than falling back to an unsafe `register`. - Schemas are not version-checked across re-registrations — re-registering with an incompatible schema simply replaces it. Coordinate schema migrations out-of-band. ## Migration and runtime overrides Compose defaults to `<namespace>-<container-key>` without a hash (for example, `default-harness`). Invalid or over-64-character generated names require explicit `config_name`. Compose migrates only the exact previous namespace/key hash before starting a stopped worker. After hashed migration, only the `default` namespace adopts the exact bare container key, unless another container explicitly owns it. The bare source wins over an existing destination; `configuration::migrate` is the single operation, delegated through bridges to the authority. It returns `{ action, entry }` with `migrated`, `preserved` (existing destination with absent source, or matching IDs with an existing entry), or `missing` (both source and destination absent). Before migration, Compose and every bridge hop query the read-only `configuration::migration-capabilities` and require `source_priority_archive_revision: 1`. Unknown or unavailable capabilities fail closed before invoking migration; upgrade the authority. It replaces the destination with the raw source entry, then archives the original source as `<source>.yaml.bak`. The previous destination is not backed up. `.yaml.bak`, `.bak.yaml`, and `.bkup.yaml` files are ignored during loading, watching and legacy directory migration. An existing identical backup permits cleanup recovery; a conflicting backup is never overwritten. Missing source is a no-write no-op. Unsupported adapters fail closed. Stop source consumers before migrating; do not share an fs directory between engine processes. `config_override` is delivered through the existing service API. Compose reads the current configuration with `configuration::get` (`raw: true`), merges defaults and overrides, then calls `configuration::set` with `flush: false` before starting the worker. No snapshot file is delivered. `III_CONFIG_NAME` identifies the entry. Memory-only updates never write persistent `config/<id>.yaml`, and no delayed flush is scheduled. `ensure` and metadata registration preserve the active value without persisting it or notifying base defaults. An explicit `set` with default `flush: true` persists the complete submitted object, including override values if submitted. Both forms of `set` notify consumers; applying changes is the worker's responsibility. A new worker start merges the current GET value. Removing an override keeps the current value, not the old disk value. Stopping a worker does not clear active memory; restarting the configuration service loses unsaved values and reloads its adapter. Distinct concurrent overrides sharing one configuration id are not supported. ## Functions - `configuration::register` — declare an id with name, description, JSON Schema, and an optional `initial_value`; idempotent re-registration replaces the schema and metadata. - `configuration::ensure` — atomically seed a default: create or refresh the id but write `initial_value` **only when no non-null value is stored yet**; an existing value (including `false`/`0`/`""`) is preserved verbatim and the seed is ignored. The race-free replacement for read-then-`register` when seeding from one or many workers. Fires `configuration:registered` on creation or `configuration:updated` on refresh, except while an execution injection is active: boot metadata must not deliver the base in place of the active value. - `configuration::migrate` — move an exact source id with source priority, preserving raw persisted values and metadata and archiving the source. On a successful move, source active memory follows the new id without being saved and replaces any destination override; the old id is no longer readable. With no persisted source, destination memory is preserved and orphan source memory is retired. Same-id migration preserves memory; failures retain it for retry. The response contains the persisted entry, while source `:deleted` and destination `:registered` events carry the active snapshot captured at commit. No-ops emit nothing. - `configuration::set` — replace the complete active value and emit `configuration:updated`. `flush` defaults to true, validating and persisting through the adapter for an already-registered id. `flush: false` changes memory only and may precede registration; validation uses the schema when available and normal GET validates again after registration. Explicit null is a value, not a request to clear memory. - `configuration::get` — read the current active entry by id; expands `${VAR:default}` against live env unless `raw: true`. - `configuration::list` — enumerate every registered id with name, description, and schema; never returns the value. - `configuration::schema` — read schema/name/description for one id without exposing the value. `register`, `ensure`, `migrate`, and `set` are the mutators; the read-side functions are cache-backed and cheap. Every mutator (plus `delete`) is linearized per store (the local `fs` store, one engine process), so a seed can never clobber a concurrent `set` and two racing seeds resolve to a single winner. Over the `bridge` adapter the authoritative store is the remote engine and its own linearization applies (the local cache is a best-effort mirror), so `ensure` is decided remotely, never against the local cache. Reads expand `${VAR:default}` placeholders against the live process env on every call, so env changes propagate without restarts — pass `raw: true` to `configuration::get` when you need the stored template form. ## Reactive triggers Bind a `configuration` trigger when a function should run automatically on every register / set / delete — including external `fs` file edits and bridge-forwarded events from a remote engine. The engine invokes matching handlers asynchronously after each successful mutation and after TTL-driven cleanup, so a worker stays in sync with its configuration without polling. Reach for it when: - A worker needs to reload in-memory state when its configuration is rewritten by another component or by an operator editing the YAML directly. - The same handler should run regardless of who edited the configuration (local SDK call, remote engine via the bridge adapter, or a file edit). If you only need the new value inside the same function that wrote it, `configuration::set` already returns `old_value` / `new_value` — register a trigger only when a *different* worker should react. ### How to bind 1. Register a handler: `iii.registerFunction('stream::on-config-change', handler)`. 2. Register the trigger: ```typescript iii.registerTrigger({ type: 'configuration', function_id: 'stream::on-config-change', config: { configuration_id: 'iii-stream', // optional. Omit to receive every id. event_types: ['configuration:updated'], // optional. Subset of configuration:registered|configuration:updated|configuration:deleted. // condition_function_id is also supported — see get function info. }, }) ``` Mutations that fire triggers: `configuration::register` (`:registered` on first call, `:updated` on re-registration), `configuration::ensure` (`:registered` on creation, `:updated` on refresh), `configuration::set` (`:updated`), TTL cleanup (`:deleted`), and external `fs` create/edit/delete events. Reads do **not** fire triggers. The worker also respects per-id TTL: when `ttl_seconds > 0` is configured and the **last** trigger bound to a `configuration_id` is unregistered, the entry is deleted after the TTL elapses. A new trigger registration before the countdown fires aborts the cleanup. For the event payload shape, call `iii get function info` on the trigger type or handler function id.