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:

typescriptCopy code
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.