Parameter Manager: Types, Locks and a new GUI

AGENTS.md

@@ -195,7 +195,10 @@ BaseClient → ZMQ Network → ThreadPool + Broadcast
 
 ## Testing
 
+Tests never use a fixed port. Use the `server_port` fixture; agents run the suite in parallel.
+
 ### Test Setup (test/pytest/conftest.py)
+- `server_port` fixture - Session-scoped pair of free consecutive ports (server port and broadcast port)
 - `start_server` fixture - Module-scoped server for all tests
 - `cli` fixture - New Client per test
 - `dummy_instrument` fixture - Test dummy instrument with submodules

CONTEXT.md

@@ -20,15 +20,19 @@ A serializable description of an instrument, parameter, or method that lets clie
 _Avoid_: schema, spec
 
 **Broadcast**:
-A parameter-change event published by the Server on its PUB socket for any subscriber.
+A parameter-change event published by the Server on its PUB socket for any subscriber. Most Broadcasts are produced by the Server when it executes a client request; an instrument that implements the **Broadcaster** contract can also emit its own.
 _Avoid_: notification, event stream
 
+**Broadcaster**:
+The opt-in contract by which an instrument emits its own Broadcasts: it exposes `add_broadcast_sink` / `remove_broadcast_sink` / `broadcast`, and the Server registers itself as a sink when the instrument joins the Station. Instruments without it are untouched. The Parameter Manager is the first Broadcaster. It emits `pm-lock-update` (payload: a `PMLockBluePrint`, or `None` when its Lock was removed) and `pm-type-update` (payload: a `PMTypeBluePrint`, or `None` when the Type was removed), and re-emits the Server's own `parameter-creation` for the parameters it creates as side effects of Type edits, `add_instance` and Type Lock declarations; it emits no `parameter-deletion`.
+_Avoid_: hook, callback, event emitter
+
 **Virtual Instrument**:
 An instrument that lives entirely in the Server with no hardware behind it.
 _Avoid_: soft instrument, fake instrument (that's a dummy instrument, for testing)
 
 **Parameter Manager**:
-The flagship Virtual Instrument: a hierarchical, persistent, profile-aware store of experiment parameters.
+The flagship Virtual Instrument: a hierarchical, persistent, profile-aware store of experiment parameters. Its root owns the Type registry and all Lock and Type methods; its submodules are **Parameter Groups**.
 _Avoid_: param store, PM
 
 **Client Station**:
@@ -49,18 +53,61 @@ A hardware-free test instrument shipped in `instrumentserver.testing` for develo
 A Server acting as a Client of another Server, so instruments can be re-exported downstream.
 _Avoid_: server-in-server, daisy-chaining (fine in prose, not as the term)
 
+**Parameter Group**:
+A submodule inside the Parameter Manager: a plain container of parameters and nested groups with no file, profile, Type or Lock logic of its own. Every submodule is a Parameter Group; only the root is the Parameter Manager, which extends the group with those responsibilities.
+_Avoid_: nested manager, sub-manager
+
+**Type**:
+A named set of relative parameter paths (each with a default value and unit), plus **Nested Types** required at named submodules. Type entries carry no value kind and no description. A Type is structural: it describes a shape, not a list of members.
+_Avoid_: template, schema, class. Not to be confused with a parameter's **value kind** (numeric, string, bool…), which is the `ParameterTypes` enum in code.
+
+**Nested Type**:
+A Type required at a named submodule of another Type, e.g. `qubit` requires a `readout` at its submodule `readout` (`add_nested_type("qubit", "readout", "readout")`). The outer Type's effective parameter set is its own entries plus every Nested Type's set under that submodule name. Nesting can go several levels deep but may not cycle.
+_Avoid_: include, import, inherit, extend, subtype
+
+**Instance**:
+A Parameter Manager submodule (at any depth, never the root and never under Globals) that carries every parameter path of a Type, including those of its Nested Types, each with the unit the Type declares. Values are irrelevant to matching. Membership is duck-typed and recomputed on demand, never stored. An empty Type has no Instances. A submodule may be an Instance of several Types at once.
+_Avoid_: member, tagged submodule
+
+**Claiming Type**:
+The Type whose tint a parameter row shows when several Types cover it: the innermost (most deeply nested) Type wins, then the largest.
+
+**Lock**:
+A rule attached to one parameter (the **Follower**) naming another parameter, its **Target**. While the Lock is **locked**, the Follower answers `get` with the Target's value and refuses `set`. While **unlocked**, the Follower behaves as a plain parameter but remembers its Target so it can be locked again. Removing the Lock forgets the Target. Locks chain (a Target may itself have a Lock) but never cycle. Values are pulled on `get`; nothing is ever pushed into a Follower.
+_Avoid_: link, binding, mirror, source. Not the server's **instrument mutex**.
+
+**Target**:
+The parameter a Lock points at. A parameter that is the Target of at least one Lock is marked as such in the tree, its Followers counted locked and unlocked alike. Deleting a Target removes the Locks that pointed at it and clears the Type Lock rules whose stored Target it was; their Followers become plain parameters.
+_Avoid_: source
+
+**Follower**:
+A parameter that has a Lock. Convenience noun for prose; the code says "the parameter's lock".
+
+**Type Lock**:
+A rule on a Type entry naming a Target. Declaring it puts an ordinary, locked Lock on that parameter in every current Instance, and every future Instance gets it at creation. Its default Target is `_globals.<type>.<path>`, created on demand with the entry's default and unit. Instance parameters that already have a Lock on another Target are skipped with a warning. Removing the Type Lock removes only the rule; the Locks it created stay until removed individually. Instances that stop matching keep their Locks.
+_Avoid_: group lock, rule (alone)
+
+**Globals**:
+The reserved `_globals` submodule of the Parameter Manager that holds the default Targets of Type Locks. Its parameters are created on demand by a Type Lock or by a profile load that lists one, never through `add_parameter`, which refuses the name; otherwise a Globals parameter is ordinary: it can be read and set, and it is saved with the profile. Globals is never an Instance of anything.
+
+**Instrument mutex**:
+The server's per-instrument `threading.RLock` that serialises concurrent `call`s to one instrument. Prose uses "instrument mutex" so it never collides with **Lock**; the code keeps its current names (`_instrument_locks`) with a rename note only.
+_Avoid_: instrument lock (in prose)
+
 ## Relationships
 
 - The **Server** owns instruments; **Clients** reach them only through **Proxy Instruments** built from **Blueprints**
 - Every parameter change on the **Server** produces a **Broadcast**; **Listeners** and GUIs consume Broadcasts
 - A **Client Station** groups Proxy Instruments for one client; many Client Stations can share one Server
 - A **Virtual Instrument** is served like any other instrument; the **Parameter Manager** is one
 - **Chained Servers** compose: a downstream Server proxies an upstream Server's instruments
+- A **Type** is a shape; an **Instance** is any submodule matching it. Adding a parameter to a Type writes it into every Instance; removing one from a Type leaves it on the Instances, which then show it as an untyped row
+- A **Lock** makes a **Follower** read its **Target**'s value while locked; a **Type Lock** does this for every Instance of a Type, defaulting its Target to **Globals**
 
 ## Example dialogue
 
 > **Dev:** "If I set a value on a **Proxy Instrument**, who finds out?"
-> **Domain expert:** "The **Server** executes the set under that instrument's lock, then emits a **Broadcast** — every subscribed GUI and **Listener** sees it, no polling needed."
+> **Domain expert:** "The **Server** executes the set under that instrument's **instrument mutex**, then emits a **Broadcast** — every subscribed GUI and **Listener** sees it, no polling needed."
 > **Dev:** "And a **Client Station** is a second server?"
 > **Domain expert:** "No — it never owns instruments. It's a scoped view: one client's chosen set of **Proxy Instruments** over the same shared **Server**. If you actually need a second server re-exporting instruments, that's **Chained Servers**."
 
@@ -69,3 +116,5 @@ _Avoid_: server-in-server, daisy-chaining (fine in prose, not as the term)
 - "apps" — the five console entry points are launchers, not five separate applications; they collapse into three features (Server, Client Station, Monitoring) plus two convenience launchers (Detached GUI, Parameter Manager GUI). Resolved: docs pages follow features, not entry points.
 - "sub-server" — used colloquially for **Client Station**; resolved: explanation, not terminology.
 - "virtual instrument" vs "dummy instrument" — distinct: virtual = production feature with no hardware; dummy = testing stand-in for hardware.
+- "type" — overloaded: the `ParameterTypes` enum is a parameter's **value kind** (drives widget choice); the Parameter Manager's **Type** is a structural shape of a submodule. Resolved: **Type** is the structural concept; the enum is called "value kind" in prose.
+- "lock" — overloaded: the server's per-instrument RLock vs the Parameter Manager's user-facing **Lock**. Resolved: the RLock is the **instrument mutex** in prose; code names unchanged.

docs/adr/0001-duck-typed-parameter-manager-types.md

@@ -0,0 +1,20 @@
+---
+status: accepted
+date: 2026-09-16
+---
+
+# Parameter Manager Types are structural (duck-typed), never a stored membership
+
+A Type in the Parameter Manager is a named shape: a set of relative parameter paths with units, plus Nested Types at named submodules. A submodule is an Instance of a Type purely because it carries every path of that shape with the declared unit; nothing records "q01 is a qubit". Membership is recomputed on demand and never persisted.
+
+## Considered options
+
+- **Explicit registry**: tag submodules with a Type and enforce structure on tagged ones. Rejected: it adds membership state to persist and migrate, and it makes "parameter removed from the Type but still on the Instance" a special case instead of the natural outcome (the row is simply untyped now).
+- **Structural, computed** (chosen): matches how the lab thinks about it ("everything shaped like a qubit is a qubit"), needs no membership state, and lets one submodule match several Types (innermost, then largest, claims the tint).
+
+## Consequences
+
+- Deleting a required parameter silently makes a submodule stop matching; that is accepted. Deleting a parameter that is a Lock Target is the case that gets a GUI confirmation, not this one.
+- An empty Type matches nothing, so a freshly created Type does not claim the tree.
+- Matching walks the tree on every query. Trees are hundreds of parameters; no caching in the first version.
+- The `_globals` submodule is excluded from matching at any depth.

docs/adr/0002-pull-based-locks.md

@@ -0,0 +1,21 @@
+---
+status: accepted
+date: 2026-09-16
+---
+
+# Parameter Locks pull on `get`; nothing is ever pushed into a Follower
+
+A locked Follower answers `get` by asking its Target and returning that value; `set` on a locked Follower raises. The Target knows nothing about its Followers, no value is ever copied into a Follower, and "who follows X" is computed by scanning when asked. The behaviour lives in a `Parameter` subclass (`ManagedParameter`) so the server's call path, the instrument mutex and the existing broadcasts are untouched: the server resolves the dotted path and calls the parameter exactly as it does today.
+
+## Considered options
+
+- **Push on set**: a Target's `set` rewrites every Follower and each rewrite needs its own broadcast. Rejected: it fans one request into many writes, requires the instrument to report side effects to the server for every value change, and forces a dedup rule so Listeners do not log twice.
+- **Pull on get** (chosen): minimal change, the broadcast path is unchanged for values, cycle checking is just a walk up the Target chain, and each hop of a chain is decided by that hop's own locked/unlocked state at read time.
+
+## Consequences
+
+- A Follower keeps its own underlying value while locked. Unlocking exposes that own value again (deliberate: "unlock and see its own value" is the point). Profiles store the own value plus the Lock.
+- QCoDeS reads the cache, not `get`, for snapshots with `update=False`. `ManagedParameter` therefore reports the Target's value in its snapshot while locked, and the profile writer reads the own value explicitly. Otherwise measurement metadata would record stale values.
+- GUIs repaint Followers when they receive a `parameter-update` for the Target; the Parameter Manager emits nothing for values.
+- Deleting a Target removes the Locks pointing at it; their Followers become plain parameters. When the deleted Target was the stored Target of Type Locks, those rules are cleared with it.
+- Targets are restricted to parameters inside the same Parameter Manager.

docs/adr/0003-broadcaster-contract.md

@@ -0,0 +1,23 @@
+---
+status: accepted
+date: 2026-09-16
+---
+
+# Instruments emit their own Broadcasts through an opt-in `Broadcaster` contract
+
+The Server only broadcasts what it can see: parameter sets it executed, and calls whose method name is literally `add_parameter` or `remove_parameter`. Structural changes inside an instrument (a Type edited, a Lock declared, parameters created as a side effect of `add_instance`) were invisible to other clients. We add a small mixin, `Broadcaster`, with `add_broadcast_sink`, `remove_broadcast_sink` and `broadcast(blueprint)`. When an instrument joins the Station (creation over the wire, or loading from config at startup) the Server checks `hasattr(instrument, "add_broadcast_sink")` and registers its own broadcast function as a sink. Instruments without the mixin are registered exactly as before.
+
+## Considered options
+
+- **Hard-code more method names in the Server**, as `add_parameter` is today. Rejected: the Server accumulates one instrument's API.
+- **Instrument declares a method-name to action mapping** that the Server consults after each call. Rejected: passive and coarse; cannot express "one message per created parameter" and still couples the Server to method names.
+- **Server diffs state after each call.** Rejected: heavy, cannot express Type changes.
+- **GUI polling.** Rejected: latency and traffic for nothing.
+- **Opt-in emitter contract** (chosen): generic, three lines in the Server, no base-class change, usable by any future Virtual Instrument, and standalone use of the instrument (no sinks) is a no-op.
+
+## Consequences
+
+- Messages use the existing `ParameterBroadcastBluePrint`, same socket, same topic (instrument name), same wire format. Existing subscribers parse them unchanged.
+- The Parameter Manager emits `pm-lock-update` (`PMLockBluePrint` payload, `None` when a Lock was removed), `pm-type-update` (`PMTypeBluePrint` payload, `None` when a Type was removed), and re-emits `parameter-creation` for the parameters its Type edits, `add_instance` and Type Lock declarations create as side effects. It emits no `parameter-deletion`: only a direct `remove_parameter` call is announced, by the Server; the parameter removals of a profile load and of `remove_all_parameters` re-emit no creation or deletion Broadcasts. Direct `add_parameter` / `remove_parameter` calls keep being announced by the Server, so nothing is announced twice.
+- `broadcast` runs on the thread that called the instrument method, which for a client request is the worker thread holding the instrument mutex: the same place the Server's own broadcasts already run.
+- The `_instrument_locks` code in the Server is not renamed or altered; a comment notes that prose calls it the "instrument mutex".

docs/conf.py

@@ -86,7 +86,7 @@
 }
 
 templates_path = ['_templates']
-exclude_patterns = ['build', 'agents', 'README.md', 'Thumbs.db', '.DS_Store', '**.ipynb_checkpoints']
+exclude_patterns = ['build', 'agents', 'adr', 'README.md', 'Thumbs.db', '.DS_Store', '**.ipynb_checkpoints']
 
 # -- Internationalization ----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#internationalization

docs/getting_started/overview.md

@@ -203,7 +203,7 @@ instruments:
     type: instrumentserver.params.ParameterManager
     initialize: True
     gui:
-      type: instrumentserver.gui.instruments.ParameterManagerGui
+      type: instrumentserver.gui.parameter_manager.ParameterManagerGui
 ```
 
 ![parameter_manager_2](../_static/param_manager_2.png)