Reference

Control interaction registry contract

The registry gives an adapter stable control identity, serializable metadata, bounded commands, staged proposals, confirmation rules, and explicit refusal reasons.

Verified against s-m-r-t 0.42.4

Address controls by declared identity

ControlIdentity combines a formId, a controlId, and an optional subject. An adapter uses this address instead of DOM position or visible text.

Form supplies the stable form scope and the interaction registry.
Each registered control supplies metadata and small imperative handles.
list returns snapshots for all controls or one form. get returns one exact identity.

Inspect a minimized snapshot

A snapshot contains identity, metadata, runtime state, the readable live value, and a separately staged value. Classification controls value exposure and capabilities.

Metadata can include kind, label, description, sensitivity, options, constraints, unit, and capabilities.
Runtime state can include disabled, read-only, valid, and validation-message values.
A secret or non-readable control reports valueRedacted and omits its value.
A secret control omits read, stage, apply, clear, and undo capabilities.

Use the bounded command set

execute accepts focus, reveal, highlight, explain, validate, stage, apply, clear, or undo. ControlCommandContext records the request source and confirmation signal.

Stage stores a proposed value without calling the control writer.
Apply uses the staged value unless the command supplies a value.
Undo restores the previous value from the current registry history.
User, voice, agent, tutorial, and test are the declared command sources.

Apply the default refusal policy

The default policy checks mutation authority before it runs a control capability. A custom policy can make these rules stricter for application risk and permissions.

A secret mutation returns sensitive_control.
A non-writable mutation returns control_not_writable.
A disabled or read-only mutation returns control_not_editable.
An agent apply, clear, or undo on an otherwise-permitted control always returns human_confirmation_required, regardless of confirmed — a more specific refusal still takes precedence.
An unknown identity returns not_found, and an unavailable capability returns unsupported.

Observe registry events

subscribe receives registered, unregistered, staged, and command events. Command events retain the command source, result, identity, and registry timestamp.

Events do not make a transport or durable audit log.
The application owns authentication, authorization, persistence, and external rollback.
The registry does not include a language model or a chat transport.