RFC: Declared parameters, telemetry, and control for media functions

[znerol2]

Summary

dmfdeploy is an independent, open prototype of a Dynamic Media Facility. It proves its claims with conformance checks against published specifications and shares what it learns upstream as evidence. It does not call itself a reference.

This RFC proposes how a media function declares its configuration parameters and its telemetry in dmf-function.yaml, how the platform validates a change, and how it proves the change took effect. It builds on the NMOS control stack (MS-05-02, IS-12, IS-14, and BCP-008) and adds only the glue a package needs.

It also proposes who may control a function. The descriptor is the contract, and any controller that conforms to it can drive the function. That includes control applications that facilities already run, and translator functions that put older devices behind the same contract. The platform ships a small default controller and its own read-only observer, so the evidence never depends on which controller wrote.

This is v0.2-era design. It extends the package format RFC (#663) and the descriptor issue (#634). It adds no work to the v0.1 polish milestone.

The problem

Today the console learns the outcome of a change by reading the log of the automation job that made it. The job prints fixed marker text, and the console matches that text. A marker proves that a playbook reached a step. It doesn't prove that the function holds the new value, and text from other sources can look like a marker.

Function parameters and telemetry have no declared contract. The platform has no typed definition to validate a request against, and nothing to compare a read-back with. The EBU DMF Reference Architecture v2.0 (2026-04-15) asks the platform to monitor whether each Media Function has the correct parameters set. Nothing in dmfdeploy does that today.

Real facilities also run more than one controller. A facility orchestrator drives domain controllers, hardware panels write to the same devices, and many devices speak older control protocols.

The current MXL launch and switch jobs are a demo fixture. This design doesn't build on them.

Three kinds of configuration

Kind	Example	A change needs	Declared in	Applied through
Deploy-time values	image, resource requests, MXL domain mount	a new pod	Helm values.schema.json, generated from the descriptor	the launcher's Helm install or upgrade
Runtime parameters	gain, output format, labels	a running function	the new parameters block	IS-14 restore or IS-12 Set
Connections	the flow a receiver reads	a running function	ports and NMOS nodes (#663)	IS-05, with BCP-007-03 (v1.0.0, 2026-08-18) for MXL

NMOS stays the source of media intent. Senders, receivers, and flows come from the IS-04 registry and IS-05 state. The static connection file in the JT-DMF IN-004 draft is a deploy-time value.

Declaring parameters

The descriptor gains a parameters block. It is a static copy of the MS-05-02 (v1.0.0, 2023-09-12) class and property descriptors that the running function publishes over IS-12, in MS-05-02's own vocabulary of datatypes and constraints.

parameters:
  model: nmos-ms-05-02/v1.0
  objects:
    - rolePath: [processor]
      classId: "<registered or authority-key class id>"
      properties:
        - name: outputGain
          typeName: NcFloat32
          constraints: { minimum: -60, maximum: 12, step: 0.5 }
          unit: dB          # dmfdeploy field: MS-05-02 has no unit
          apply: runtime
        - name: outputFormat
          typeName: NcString
          apply: restart
          chartValue: output.format   # required when apply is restart

MS-05-02 has no unit field, so the block adds one, using UCUM symbols. The apply field sorts each parameter into a runtime parameter or a deploy-time value. A deploy-time value names the chart value it sets, and the tool checks that the chart has it. The conformance tool generates a JSON Schema for runtime profiles and the deploy-time part of the chart's values.schema.json. MS-05-03 Blockspecs (work in progress) may later become the source of this block.

Two validation paths

A profile can hold both kinds of field. The platform splits it by apply and runs each part on its own path.

Runtime fields take three steps:

1. Static. The conformance tool from [dmf-media] Define the media function descriptor schema and a conformance tool #634 checks the profile against the generated schema. The console runs the same check before it submits.
2. Admission. The controller sends the runtime part to the live function as an IS-14 (v1.0.0, 2025-08-26) validate request. IS-14 says that devices "MUST NOT make any changes to the device model when validating bulk properties" and that they run the same checks as a real restore. A single live change can use IS-12 Set directly, because IS-12 has no validate-only call.
3. Read-back. The controller applies the change with an IS-14 restore or an IS-12 (v1.0.1, 2025-07-25) Set. The observer then reads each value back and compares it with the request.

IS-14 also returns a validation fingerprint, which records the device's hardware, software, and firmware versions. The platform keeps it as a compatibility check. It can't show what state the device holds, so the proof comes from comparing values.

Deploy-time fields take a different path. The static check covers the schema and the chart-value mapping. The approved values go to the desired-state store, and the launcher runs a Helm upgrade. The evidence is the Helm revision, the readiness of the new pods, and the values in the rendered manifest. That shows what the function was deployed with. The console labels it "deployed with values" unless the function also offers a real read-back.

Outcome	Meaning
Applied	The read-back matches the request.
Coerced	The device accepted the write and holds a different value after rounding or clamping it.
Failed	The device or the launcher rejected the change.
Sent	The write left the controller, and the property has no read-back.
Deployed with values	A deploy-time change rolled out, with revision and rendered-value evidence.

Existing control products and SDKs often round or ignore an out-of-range value and still report success, so the platform never trusts a success code alone. A mismatch, at apply time or later, is a configuration delta in the closed-loop assurance model (#669).

One prerequisite comes first: an ADR that chooses the desired-state store. NetBox holds instances, and ADR-0037 retired the custom resource for that layer. The ADR must say where profiles live, who may write them, how a profile ties to a package version, and where observed evidence goes, since ADR-0037 keeps live state out of NetBox.

Declaring telemetry

The descriptor gains a telemetry block that points to existing formats:

telemetry:
  health:
    readiness: { httpGet: { port: http, path: /ready } }
  metrics:
    endpoints: [{ port: metrics, path: /metrics, format: openmetrics-text/1.0.0 }]
    registry: telemetry/registry/      # OpenTelemetry Weaver registry
    required: [dmf.function.frames.dropped]
  nmos:
    monitors: { receivers: "1.2.2.1", senders: "1.2.2.2" }
  logs: { stream: stdout, format: json }
  alerts:
    rules: telemetry/alerts.rules.yaml
    tests: telemetry/alerts.test.yaml

Health uses Kubernetes probe semantics. Metrics use an OpenTelemetry Weaver registry with pinned semantic conventions. NMOS monitors use the BCP-008-01 and BCP-008-02 classes (v1.0.0 each, 2025-08-26). Alert rules ship as plain Prometheus rule files, because ADR-0047 forbids CRDs on the generic path. Each environment may override thresholds.

The tool runs weaver registry check and promtool test rules on every package. At certification tier, it compares a real scrape with the registry and runs the NMOS Testing Tool suites for IS-12 and BCP-008.

The block becomes the single source for the ADR-0038 monitoring: lanes. It feeds three delta classes into #669. A contract delta is a missing or mistyped metric. A presence delta is an instance in NetBox that is missing from the NMOS registry or the scrape targets. A media-health delta is a connected receiver that BCP-008 reports as unhealthy.

The control contract

The descriptor, in MS-05 terms, is the contract. A function declares its parameters, its IS-12 and IS-14 endpoints, and its BCP-008 monitors, and any controller that speaks that contract can drive it. Here a controller means an NMOS controller: a client that finds devices through the IS-04 Query API and calls IS-12 and IS-14. It is unrelated to a Kubernetes controller.

Existing facility control products solve parameter control with large libraries of per-device drivers, so the device model lives inside the controller. We found no public product documentation that claims an IS-12 or IS-14 controller yet, and AMWA has started a track for controller vendors. With the model in the descriptor, those products can plug in as they add NMOS control.

No standard calls a controller a media function. IN-003 defines a Media Function as something that produces or consumes live media streams. The EBU architecture places control in its Application and UI layer. IN-001 separates the orchestration system that deploys functions from the control system that sets parameters. So this RFC uses two terms. A control application is a controller in the EBU Application and UI layer, or the IN-003 Application tier. A translator function exposes other devices through the contract.

The design has three parts:

• A default controller, so the contract works on day one. It does IS-14 validate and restore, IS-12 Set and Get, and BCP-008 monitoring for changes the platform starts.
• An observer. It holds read-only access to every managed function, subscribes to IS-12 change notifications, collects BCP-008 status, and reads back after every write, whoever made it. It writes nothing, so it can ship first. It is also the IS-12 to Prometheus bridge that the media-health delta needs, which has no open implementation that we found.
• Control applications. A third-party controller can be a package on the platform or an existing system outside it. The platform registers it with a named identity and grants it write scopes.

Position on the actuator decisions

Three accepted decisions make AWX the actuator. ADR-0025 runs catalog launchers as AWX jobs. ADR-0037 makes AWX the reconciler. ADR-0043 keeps AWX as the catalog and workflow actuator.

This RFC leaves all three as they are. The default controller runs behind the backend-agnostic actuator seam from #669, as a worker that the current actuator invokes. A runtime change that the platform starts is still an AWX job, and the job calls the controller. Granting or revoking a lease is also a platform action through the seam. A control application's writes inside its lease are operational control for its own operators, which the platform observes.

If a controller later became the actuator for runtime parameters, that would need its own ADR. It would amend ADR-0025 (runtime configuration leaves the AWX job path), ADR-0037 (configuration drift gains another reconciler), ADR-0043 (its actuator rule), and the ADR-0013 rule that the console drives Configure through AWX. It would also change the ADR-0047 note that the actuator chain is untouched.

ADR-0047 accepts no operator install path on the generic path and asks for a separate ADR before one exists. That requirement stands for the default controller, the observer, and any packaged control application.

Many controllers

The standards expect several controllers and leave arbitration open:

• MS-05-01 expects several controllers at once and counts a front panel as one. It keeps controllers in sync with change notifications and defines no lock.
• MS-05-02 has a Locked status code, and nothing defines how an object becomes locked. Change notifications don't say who made the change.
• IS-12 commands carry no field for the requesting user.
• BCP-003-02 has read and write claims per role path for IS-12 and IS-14 only on its unreleased v1.1-dev branch.

So the platform arbitrates with its own authority model. For each target, and optionally each role path, it grants a write scope to one controller at a time, as a lease that it can revoke. A facility orchestrator might hold the lease during a show, and the platform controller takes it for a change-over. Other controllers get read access. Once functions implement the BCP-003-02 claims, the platform enforces the lease by issuing write claims only to the holder. Until then, enforcement is advisory, and the observer flags any write outside a lease as a delta.

ADR-0028 requires every automated action to carry the actor, role, request id, and reason. The seam records them for each change the platform starts and for each lease grant and revocation. A write by a control application can only be attributed to the application's identity, unless the application passes the requesting human with each change. We propose that as an admission condition for control applications. NMOS doesn't standardize it.

Translator functions

Many devices speak Ember+, SNMP, or a vendor API. A translator function exposes them through the contract. We found no public translator from Ember+ or SNMP to IS-12, so the first example we propose is an Ember+ translator with one device profile.

The standards already give a translator what it needs. One IS-04 Node can register many Devices, each with its own IS-12 endpoint, so each target gets its own identity, claim scope, and NetBox instance. MS-05-02 nested blocks with stable role paths are the fallback when targets can't have separate endpoints.

role: translator
southbound: [emberplus]
northbound: [nmos-is12, nmos-is14, nmos-bcp008]
targets: { source: netbox }          # instances and addresses
profiles:
  - match: { deviceType: "<device type>", firmware: "4.x" }
    parameters: profiles/<device-type>.yaml

Targets come from NetBox, so a silent target shows up as a presence delta. Each profile is a static parameters declaration for one device type, signed with the translator package under the ADR-0047 trust model. A translator can also discover a model by walking an Ember+ tree. The platform shows discovered values and runs no validated profile against them until someone reviews and signs a profile.

A translator can't always prove what a native function proves, so each translated property declares its evidence level:

          evidence:
            validate: translator   # device | translator | none
            readback: device       # device | cached | none
            notify: device         # device | poll:<interval> | none

The console reports evidence at the declared level. A translator validation reads as checked against the declared profile. A read-back counts as proof only at readback: device, from a fresh read after the set. A property with readback: none can only reach Sent. Certification tests the translator against a southbound simulator that coerces or refuses values. Each target also reports BCP-008-style status for its southbound link, so a lost link never looks like a healthy device.

Relation to JT-DMF work

JT-DMF publishes its work as AMWA Increments, which are draft specifications. IN-001 puts "Control of processing parameters" out of scope. IN-003 declares resources, and its spec.args has no schema. IN-004 names IS-12, OpenTelemetry, and ST 2138 as candidate monitoring protocols. dmfdeploy maps its descriptor to these drafts and does not fork them. This RFC proposes no text for any AMWA document. Our only contact so far is a questions-only issue, AMWA-TV/in-003#4.

Decisions this would amend

• ADR-0013: the catalog entry gains parameters, telemetry, and role.
• ADR-0038: the monitoring: lanes derive from telemetry.
• ADR-0047: the descriptor gains two blocks and two roles without media ports. Translator profiles join the signed package.
• ADR-0012: Configure keeps its existing steps. It launches the workload, sets the initial connections through IS-05, and moves the NetBox lifecycle tag to lifecycle:active. This RFC adds two conditions before the tag moves: each runtime field is Applied, or Sent where the function has no read-back, and each deploy-time field is Deployed with values.
• ADR-0028: lease grants and control application writes join the attribution rule.

ADR-0025, ADR-0037, and ADR-0043 stay unchanged. The desired-state store needs its own ADR first.

Alternatives considered

• A third-party orchestrator as the only controller. The parameter model would live inside that product, and the platform would see only what it reports.
• A platform controller as the only writer. It ignores the panels and facility systems that write in practice.
• SMPTE ST 2138 has a typed parameter model and addresses many devices behind one service. Its parts are public committee drafts, with no validate-only call or lock that we saw. We will watch it as a second binding.
• NETCONF and YANG (RFC 6241) have validate and confirmed commit. We found no broadcast YANG models for media functions.

What would prove this wrong

• Control applications that add IS-12 support can't work inside a revocable lease, for example because they need exclusive ownership of a device.
• BCP-003-02 v1.1 ships with claims that can't express per-target write leases or read-only observer access.
• The first Ember+ translator reaches readback: device for few of its properties, so translated evidence is too weak to be useful.
• JT-DMF or MS-05-03 settles on a different parameter declaration. The parameters block would then follow it.
• An actuator job per live change is too slow for live control. The actuator ADRs would then need amending sooner.

Questions for discussion

1. Should the parameters block come from the publisher, an MS-05-03 Blockspec, or a capture of a running instance? How should the tool report drift from what the device publishes?
2. Which store should hold desired profiles, and what should its ADR cover?
3. Is a lease per target enough, or do some workloads need leases per role path?
4. Should control applications have to pass the requesting human with each change?
5. Who signs a translator profile: its publisher, the device vendor, or the facility after review?
6. On drift, should the platform report only, or enforce? Is that a workload policy (ADR-0046) or a function policy?
7. Should the observer ship before the default controller?
8. Is telemetry conformance a promotion gate under ADR-0047, or advisory at first?

How this gets decided

Discussion here shapes the design. When it converges, ADRs record the desired-state store first, then the descriptor blocks, the validation paths, the control contract, and the install path for the controller and observer, following the RFC to ADR path.

The research is in three survey notes: configuration control, telemetry declaration, and orchestration and control. Work on this RFC is tracked in #685.

[znerol2]

Decision update, tracked in #746. The "Relation to JT-DMF work" section says dmfdeploy maps its descriptor to IN-003. The rule is now stronger: IN-003 field names are authoritative, and the descriptor is a superset of IN-003. A descriptor field with the same meaning as an IN-003 field takes the IN-003 name and shape.

For this RFC, that affects role. IN-003 already has spec.role, so we will check whether the role in this proposal can use that name and shape, or whether the two need different names. The new parameters and telemetry blocks have no IN-003 counterpart, so they stay as additions.