Skip to content

ADR 0001 — Registry-driven declarations for scoped context and designer

Status

Proposed (direction for extending the capability contract and dashboard). Existing behaviour around scoped_context in workflow YAML and the orchestrator is documented elsewhere; this ADR records the design rule for the next step (designer + metadata).

Context

  • Workflow scoped_context describes declarative slots (name, type, optional init.value) bound to a provider (service_name, …).
  • The dashboard designer should eventually edit this graphically without hard-coded knowledge of variables.service (or future providers).
  • The capability registry already has metadata.designer (form_fields, …) for triggers and steps.

We want one mechanism: the contract describes what a declaration looks like; the UI renders it generically.

Decision

  1. scoped_context stays part of the workflow document (YAML/JSON). The registry does not replace that data; it only supplies schema / UI hints.

  2. Capabilities (or services — exact placement follows the provider contract) may expose an optional metadata block, e.g. under metadata.designer, with a declaration schema for workflow scope, for example:

  3. which fields a row has (name, data type, optional initial value);

  4. optionally purpose / entity to distinguish multiple declaration kinds later.

  5. The dashboard designer selects a provider → loads matching capabilities/metadata → builds forms/tables from that schema and writes scoped_context on the workflow object.

  6. Orchestrator and runtime remain responsible for execution; validation against the schema in the editor is best-effort / UX; stricter validation may come server-side later.

Alternatives (rejected or deferred)

Alternative Why not
YAML-only editing does not scale for non-developers
Per-service hard-coded forms in app.js too much coupling to internal services, duplicate maintenance
Store scoped_context only via registry duplicate source of truth; workflow must stay portable

Consequences

  • Positive: new providers can expose their own declaration shape without a dashboard deploy for every change.
  • Work: extend the canonical provider contract (wiki + example in variables service), a designer component for a generic “declaration table”, tests.

Relation to existing implementation

  • Retrospective: the orchestrator supports scoped_context (context merge, _scoped.*, runner-owned values and types). The variables provider is stateless — see ADR 0008. See Workflow YAML.
  • This ADR mainly states the registry→designer link as an explicit principle.