ldcon 0.2.1__tar.gz → 0.2.2__tar.gz

{ldcon-0.2.1 → ldcon-0.2.2}/MANIFEST.in

@@ -1,5 +1,5 @@
 include LICENSE README.md
-recursive-include docs *.html
+recursive-include docs *.html *.svg *.png
 recursive-include scripts *.py
 recursive-include tests *.py *.cjs *.json *.yaml
 recursive-include examples *.json

{ldcon-0.2.1/src/ldcon.egg-info → ldcon-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ldcon
-Version: 0.2.1
+Version: 0.2.2
 Summary: Laser operations, physical owners and fleet presentation
 Author: FanHarvard contributors
 License-Expression: MIT
@@ -38,6 +38,8 @@ Provides-Extra: analysis
 Requires-Dist: scipy>=1.10; extra == "analysis"
 Dynamic: license-file
 
+<img src="https://raw.githubusercontent.com/FanHarvard/ldcon/main/docs/icon.png" alt="LDCon: an agent guiding a laser feedback loop" width="64" height="64">
+
 # LDCon
 
 **Still in active development.**
@@ -89,3 +91,5 @@ a new physical setup. See [test suite](tests/).
 laser definitions, decks and assignments, with output disabled and placeholder
 connections. Installation starts no hardware or service and includes no credentials.
 [Publishing](docs/publishing.html) · [MIT license](LICENSE)
+
+FanHarvard site configuration and deployment: [ldcon-fanharvard](https://github.com/FanHarvard/ldcon-fanharvard).

{ldcon-0.2.1 → ldcon-0.2.2}/README.md

@@ -1,3 +1,5 @@
+<img src="https://raw.githubusercontent.com/FanHarvard/ldcon/main/docs/icon.png" alt="LDCon: an agent guiding a laser feedback loop" width="64" height="64">
+
 # LDCon
 
 **Still in active development.**
@@ -49,3 +51,5 @@ a new physical setup. See [test suite](tests/).
 laser definitions, decks and assignments, with output disabled and placeholder
 connections. Installation starts no hardware or service and includes no credentials.
 [Publishing](docs/publishing.html) · [MIT license](LICENSE)
+
+FanHarvard site configuration and deployment: [ldcon-fanharvard](https://github.com/FanHarvard/ldcon-fanharvard).

ldcon-0.2.2/docs/icon.svg

@@ -0,0 +1,20 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="512" height="512" viewBox="0 0 96 96" fill="none">
+  <title>LDCon: a laser diode with agent-guided feedback</title>
+  <rect width="96" height="96" rx="18" fill="#f8fafc"/>
+  <g stroke="#334155" stroke-width="3" stroke-linecap="round" stroke-linejoin="round">
+    <!-- Laser diode and its emitted beam. -->
+    <rect x="10" y="15" width="38" height="31" rx="6" fill="white"/>
+    <path d="M15 31h7m0-8v16l13-8-13-8m13 0v16m0-8h7"/>
+    <path d="M29 20l5-5m-1 0h1v1M38 22l5-5m-1 0h1v1" stroke="#dc2626" stroke-width="2"/>
+    <path d="M48 31h35m-7-7 7 7-7 7" stroke="#dc2626"/>
+    <!-- Feedback returns through the agent to the diode. -->
+    <path d="M78 43v20a8 8 0 0 1-8 8h-7M33 71H24a8 8 0 0 1-8-8v-9m-5 5 5-5 5 5"/>
+    <path d="M48 57v-5"/>
+    <circle cx="48" cy="50" r="2.5" fill="white"/>
+    <rect x="33" y="58" width="30" height="26" rx="6" fill="white"/>
+    <path d="M29 67v8m38-8v8" stroke-width="2.5"/>
+    <circle cx="42" cy="68" r="2" fill="#334155" stroke="none"/>
+    <circle cx="54" cy="68" r="2" fill="#334155" stroke="none"/>
+    <path d="M43 76h10" stroke-width="2.5"/>
+  </g>
+</svg>

ldcon-0.2.2/docs/publishing.html

@@ -0,0 +1,62 @@
+<!doctype html><html lang="en"><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1"><title>Publishing ldcon</title>
+<style>body{font:16px/1.7 system-ui;max-width:900px;margin:3rem auto;padding:0 1rem}pre{background:#f2f4f6;padding:1rem;overflow:auto}code{font-size:.9em}</style>
+<h1>Publishing ldcon</h1><p>Public repository: <a href="https://github.com/FanHarvard/ldcon">FanHarvard/ldcon</a>.
+Current version: 0.2.2. No production service is activated by publication.</p>
+<h2>One-time PyPI setup</h2><p>A PyPI account owner creates a pending publisher at
+<a href="https://pypi.org/manage/account/publishing/">PyPI publishing settings</a> with:</p>
+<table><tr><th>Project name</th><td>ldcon</td></tr><tr><th>Owner</th><td>FanHarvard</td></tr>
+<tr><th>Repository</th><td>ldcon</td></tr><tr><th>Workflow</th><td>release.yml</td></tr>
+<tr><th>Environment</th><td>pypi</td></tr></table>
+<p>Use the repository's <code>pypi</code> environment to restrict release access. Authentication uses
+GitHub OIDC and PyPI Trusted Publishing; no long-lived PyPI API token belongs in this repository.
+See the <a href="https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/">official PyPI setup</a>.</p>
+<h2>Updating an installation</h2>
+<p>In the virtual environment used for the installation:</p>
+<pre>python -m pip install --upgrade "ldcon[web,instruments,analysis,agents]"
+python -m pip check</pre>
+<p>This selects the latest LDCon release and its declared compatible dependencies. LDCon pins
+experiment-core and fanharvard-agentbridge versions, so independent updates to those projects are
+adopted when the LDCon dependency pins are updated. For standalone use, update either with
+<code>python -m pip install --upgrade experiment-core</code> or
+<code>python -m pip install --upgrade fanharvard-agentbridge</code>.</p>
+<p>Updating a Python environment does not promote an immutable production release or restart a service.
+The existing production installation uses its separate deployment and handover procedure.</p>
+<h2>Updating GitHub</h2>
+<p>Edit the public checkout, commit reviewed files and push to <code>main</code>. README and icon changes
+are visible on GitHub after the push; they do not require a PyPI version bump. The icon source is
+<code>docs/icon.svg</code>; regenerate its PNG with:</p>
+<pre>rsvg-convert --width 512 --height 512 --output docs/icon.png docs/icon.svg</pre>
+<p>The public checkout was split from the internal deployment repository. They do not synchronize
+automatically. Port reviewed source changes and test fixtures explicitly; export deployment
+configurations as disabled, sanitized examples. Preserve the public packaging metadata and exclude
+credentials, inboxes and runtime state instead of copying the full deployment directory or its Git history.</p>
+<h2>Publishing a new PyPI version</h2><p>Change <code>project.version</code> in <code>pyproject.toml</code>
+to a new, unused version. Publish updated experiment-core or agentbridge dependencies first if needed.
+When changing the experiment-core pin, update its checkout tag in both CI and release workflows too.</p>
+<p>From a development environment with the build, test and role dependencies installed, build into an
+empty directory so old distributions cannot be uploaded accidentally:</p>
+<pre>release_dir=$(mktemp -d)
+python -m build --outdir "$release_dir"
+python -m twine check --strict "$release_dir"/*
+python scripts/check_dist.py "$release_dir"
+python scripts/check_secrets.py
+python -m pip install --force-reinstall --no-deps "$release_dir"/*.whl
+python -m pytest -q
+python -m pip check</pre>
+<p>Commit and push the reviewed changes. After CI succeeds, create a tag matching the new version
+(<code>vX.Y.Z</code>) and publish a GitHub Release for it. That runs <code>release.yml</code>; alternatively
+dispatch that workflow at the tag. The workflow checks the tag against package metadata, builds and audits distributions,
+tests the wheel, and publishes through the dedicated environment. Do not reuse an uploaded PyPI version.
+The CI workflow also checks Python 3.10, 3.12 and 3.13. An existing PyPI release's embedded README
+changes only with a new package version; a GitHub push alone does not replace it.</p>
+<h2>Site configuration</h2><p>FanHarvard deployment configuration and clone/install procedures live in
+<a href="https://github.com/FanHarvard/ldcon-fanharvard">ldcon-fanharvard</a>.
+That repository pins published packages; it does not vendor this library. Credential values and runtime state stay local.</p>
+<h2>Public/private boundary</h2><p>Public: source, tests, documentation, MIT license and reviewed examples.
+Private: credentials, .env/.pypirc files, runtime databases, job logs, agent conversations,
+approval receipts, local deployment history and live service configuration. New public repositories
+start from a reviewed snapshot; the internal Git history is not uploaded.</p>
+<p>The secret scanner compares findings against individually reviewed non-secret fixtures and code
+literals in <code>.secrets.baseline</code>. New findings fail CI. This complements artifact inspection;
+it is not a proof that arbitrary future data is safe to publish.</p></html>

{ldcon-0.2.1 → ldcon-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ldcon"
-version = "0.2.1"
+version = "0.2.2"
 description = "Laser operations, physical owners and fleet presentation"
 readme = "README.md"
 requires-python = ">=3.10"

{ldcon-0.2.1 → ldcon-0.2.2}/src/ldcon/agents/agent_monitor.py

@@ -65,7 +65,17 @@ def snapshot(box):
                     source = node.get('dither_source_unix_s', stamp) if key == 'dither_response' else stamp
                     metrics[path] = dict(value=item, acquired_unix_s=source,
                         valid=source is not None and node.get(key+'_valid', node.get('valid', True)) is not False)
-        collect(value.get('content', value.get('data', value)))
+        document=value.get('content', value.get('data', value))
+        collect(document)
+        # DLC optics have their own HTTP acquisition clock. A new WSU UDP
+        # frequency sample must not refresh a cached/invalid fringe frame.
+        quality=(document.get('observation') or {}).get('quality') if isinstance(document,dict) else None
+        if isinstance(quality,dict):
+            for name in quality.get('metrics') or {}:
+                key='observation.quality.metrics.'+name
+                if key in metrics:
+                    metrics[key]['valid']=quality.get('fresh') is True and quality.get('quality_valid') is True
+                    metrics[key]['acquired_unix_s']=quality.get('acquired_unix_s')
     for source, target, scale, absolute in (
             ('error_hz','abs_error_hz',1.,True),
             ('native_interval_us','source_interval_s',1e-6,False),
@@ -74,6 +84,11 @@ def snapshot(box):
             raw=metrics[source]
             metrics[target]={**raw,'value':(abs(raw['value']) if absolute else raw['value'])*scale,
                              'derived_from':source}
+    if 'integral_v' in metrics and 'control.integral_limit_v' in metrics:
+        integral,limit=metrics['integral_v'],metrics['control.integral_limit_v']
+        if limit['value']>0:
+            metrics['integral_utilization']={**integral,'value':abs(integral['value'])/limit['value'],
+                'valid':integral['valid'] and limit['valid'],'derived_from':['integral_v','control.integral_limit_v']}
     return dict(jobs=jobs, metrics=metrics,
                 authority='recorded data only; no physical state proof or new grant')
 
@@ -120,7 +135,7 @@ def run(directory, p, *, clock, sleep, cancel, emit, runtime=None, snapshot_fn=N
             if grant_dir.is_symlink():raise ValueError('Monitor grant directory must not be a symlink')
             grant_dir.mkdir(parents=True,exist_ok=True)
             atomic_json(grant_dir/(meta['id']+'.json'),dict(generation=state['generation'],bounds=p['background'],
-                enabled=p['enabled'] and p['background']['enabled'] and not phase.startswith('stopped') and phase!='control_data_unavailable',
+                enabled=p['enabled'] and p['background']['enabled'] and not phase.startswith('stopped') and phase not in ('control_data_unavailable','waiting_controller'),
                 last_seen=time.time(),max_age_s=max(30,p['sample_interval_s']*3),parameters_hash=digest(p)))
         except (ValueError,OSError):
             state['background_grant']='unavailable; passive review remains available'
@@ -203,6 +218,10 @@ def run(directory, p, *, clock, sleep, cancel, emit, runtime=None, snapshot_fn=N
                 from ldcon.agents.agent_background import revoke_monitor
                 revoke_monitor(box.root,laser_id,meta['id'],state['generation'])
                 publish('disabled'); sleep(p['sample_interval_s']); continue
+            if p['background'].get('controller_operation')=='servo.dlcpro_frequency' and not any(
+                    j.get('status')=='running' and any(c.get('operation',c.get('card'))=='servo.dlcpro_frequency'
+                    for c in j.get('cards',[])) for j in last_snapshot.get('jobs',[])):
+                publish('waiting_controller'); sleep(p['sample_interval_s']); continue
             due = bool(p['interval_s'] and (state['last_review'] is None or now-state['last_review'] >= p['interval_s']))
             research = bool(p['history_task_card_id'] and p['history_interval_s'] and
                 (state['last_history'] is None or now-state['last_history'] >= p['history_interval_s']) and

{ldcon-0.2.1 → ldcon-0.2.2}/src/ldcon/agents/agent_task.py

@@ -24,6 +24,7 @@ def parameters(card, overrides):
                     execution_profile='', request_delegation=True,
                     lookback_s=3600., sample_interval_s=1., timeout_s=1800., monitor_job_id='', evidence_images=[],
                     adjustment_family='auto', adjustment_plan_card_id='agent-monitor', adjustment_objective='',
+                    adjustment_measurement_cards={},
                     adoption_mode='auto_within_approved')
     p = {**defaults, **card['parameters'], **overrides}
     if set(p) != set(defaults):
@@ -40,6 +41,10 @@ def parameters(card, overrides):
         raise ValueError('Invalid task prompt')
     # The native-only distribution need not install ECDL parameter adapters.
     if p['adjustment_family'] not in ('auto','current','pi','slow_loop','feedforward'):raise ValueError('Unknown adjustment family')
+    plans=p['adjustment_measurement_cards']
+    if not isinstance(plans,dict) or set(plans)-{'current','pi','slow_loop','feedforward'}:
+        raise ValueError('Invalid adjustment measurement cards')
+    for value in plans.values():identifier(value)
     if (not isinstance(p['adjustment_objective'],str) or '\x00' in p['adjustment_objective']
             or len(p['adjustment_objective'].encode())>4000):raise ValueError('Invalid adjustment objective')
     if card['operation']=='agent.history_review' and p['instruction_profile']!='research':
@@ -174,6 +179,8 @@ def run(directory, p, *, clock, sleep, cancel, emit, adapter_factory=None, bridg
                     work_started=True
                     if (invocation.get('adjustment_plan') or {}).get('kind') in ('dlc_pi_change_measure','dlc_pi_target_response'):
                         from ldcon.agents.dlc_pi_adjustment import run as adjust
+                    elif (invocation.get('adjustment_plan') or {}).get('kind') == 'dlc_adjustment':
+                        from ldcon.agents.dlc_parameter_adjustment import run as adjust
                     outcome=adjust(directory,p,clock=clock,sleep=sleep,cancel=cancel,emit=emit,
                         selected=parent,decision_session=child)
                     outcome['explanation']=child.explain(outcome)

ldcon-0.2.2/src/ldcon/agents/dlc_monitor_grant.py

@@ -0,0 +1,87 @@
+"""Protected monitor lifetime for attached DLC parameter comparisons.
+
+This grants only explicitly configured, owner-supported adjustment families.
+It cannot grant target excursions or changes to physical policy.
+The worker binds the immutable monitor invocation; the owner checks its lifetime
+again at each effect and can restore without waiting for the model.
+"""
+from copy import deepcopy
+import math
+import os
+from pathlib import Path
+import time
+
+from experiment_core.records import digest, safe_id
+from ldcon.core.interface_schema import load_mapping
+from ldcon.core.records import read_json
+
+
+def validate_bounds(value):
+    fields = {'enabled', 'controller_operation', 'families', 'timeout_s'}
+    if (not isinstance(value, dict) or set(value) != fields
+            or type(value['enabled']) is not bool
+            or value['controller_operation'] != 'servo.dlcpro_frequency'
+            or not isinstance(value['families'],list) or not value['families']
+            or any(not isinstance(f,str) for f in value['families'])
+            or len(set(value['families']))!=len(value['families'])
+            or set(value['families'])-{'pi','current','slow_loop','feedforward'}
+            or type(value['timeout_s']) not in (int, float)
+            or not math.isfinite(value['timeout_s']) or not 1 <= value['timeout_s'] <= 86400):
+        raise ValueError('DLC monitor requires explicit adjustment families and a finite lifetime')
+    return deepcopy(value)
+
+
+def check_grant(laser_id, binding, *, clock=time.time):
+    if not isinstance(binding, dict) or set(binding) != {'monitor_id', 'generation', 'parameters_hash'}:
+        raise ValueError('Invalid DLC monitor grant binding')
+    safe_id(laser_id); safe_id(binding['monitor_id'])
+    if any(not isinstance(binding[k], str) or not binding[k] for k in ('generation', 'parameters_hash')):
+        raise ValueError('Incomplete DLC monitor generation')
+    root = Path(os.environ.get('LDCON_ADAPTIVE_ROOT', ''))
+    if not root.is_absolute() or not root.is_dir() or root.resolve() != root:
+        raise ValueError('Protected monitor authority is unavailable')
+    path = root/laser_id/'monitors'/(binding['monitor_id']+'.json')
+    if any(p.is_symlink() for p in (path, path.parent, path.parent.parent)):
+        raise ValueError('Monitor authority must not follow symlinks')
+    grant = read_json(path, {})
+    if not isinstance(grant, dict):raise ValueError('Monitor authority is unavailable')
+    bounds = validate_bounds(grant.get('bounds'))
+    stamp, age = grant.get('last_seen'), grant.get('max_age_s')
+    if (grant.get('enabled') is not True or not bounds['enabled']
+            or any(grant.get(k) != binding[k] for k in ('generation', 'parameters_hash'))
+            or any(type(v) not in (int, float) or not math.isfinite(v) for v in (stamp, age))
+            or not 0 < age <= 180 or not 0 <= clock()-stamp <= age):
+        raise ValueError('Monitor grant stopped, changed or expired')
+    return grant
+
+
+def bind(directory, p, laser):
+    """Bind a monitor task to its own frozen parent, never model-supplied text."""
+    if not p.get('monitor_job_id'):return None
+    from ldcon.agents.agent_monitor import parameters
+    from ldcon.agents.agent_background import control_root
+    directory = Path(directory)
+    monitor_id = safe_id(p['monitor_job_id'])
+    parent = directory.parent/monitor_id
+    if parent.is_symlink():raise ValueError('Monitor job must not be a symlink')
+    meta = read_json(parent/'job.json', {})
+    laser_id = laser['id']
+    source = load_mapping((parent/'laser.yaml').read_text())
+    invocation = read_json(parent/'invocation.json', {})
+    deck = load_mapping((parent/'interface-deck.yaml').read_text())
+    card = next((c for c in deck['cards'] if c['id'] == invocation.get('card_id')), None)
+    task = read_json(directory/'invocation.json', {})
+    if (meta.get('id') != monitor_id or source['id'] != laser_id
+            or not card or card['operation'] != 'agent.monitor'):
+        raise ValueError('Monitor belongs to another laser or operation')
+    plan = parameters(card, invocation['parameters'])
+    bounds = validate_bounds(plan['background'])
+    if (plan['task_card_id'] != task['card_id'] or not plan['enabled']
+            or not bounds['enabled'] or p['timeout_s'] > bounds['timeout_s']):
+        raise ValueError('Task differs from the monitor-approved adjustment plan')
+    root = control_root(directory.parent.parent)
+    grant = read_json(root/laser_id/'monitors'/(monitor_id+'.json'), {})
+    binding = dict(monitor_id=monitor_id, generation=grant.get('generation'), parameters_hash=digest(plan))
+    live = check_grant(laser_id, binding)
+    if live['bounds'] != bounds:raise ValueError('Monitor bounds differ from its frozen invocation')
+    return binding

ldcon-0.2.2/src/ldcon/agents/dlc_parameter_adjustment.py

@@ -0,0 +1,274 @@
+"""One task-model workflow over owner-confirmed DLC adjustment families.
+
+The monitor only starts this task. Selection, paired measurements, confirmation
+and adoption are identical for a manual invocation. Models have evidence access,
+not raw controller credentials or direct physical commands.
+"""
+from copy import deepcopy
+import math
+from pathlib import Path
+
+from ldcon.core.contracts import DeviceError
+from ldcon.core.interface_cards import CardCancelled
+from ldcon.core.interface_schema import load_mapping
+from ldcon.core.records import read_json, atomic_json
+from ldcon.jobs.change_measure import ChangeMeasure
+from ldcon.jobs.dlc_parameter_measurement import ParameterAdapter, candidate
+from ldcon.jobs.study_execution import export_evidence, parse_proposal
+
+
+def evidence(directory, result, state, turn):
+    prefix = 'parameters-%03d-' % turn
+    docs = [(prefix+'summary', deepcopy(result)), (prefix+'owner', deepcopy(state))]
+    for row in result['measurements'][-3:]:
+        raw = read_json(directory/row['path'])
+        for name, values, size in (('samples', raw['samples'], 120),
+                                  ('controls', raw.get('control_observations', []), 12)):
+            for i in range(0, len(values), size):
+                docs.append((prefix+row['id']+'-'+name+'-%05d'%i, values[i:i+size]))
+    return docs
+
+
+def response(answer, *, selection=False):
+    value = parse_proposal(answer, allow_progress_prefix=True)
+    if not isinstance(value, dict) or set(value) != {'action', 'parameters'}:
+        raise ValueError('Return exactly action and parameters')
+    action, args = value['action'], value['parameters']
+    expected = ({'choose': {'family', 'reason'}, 'finish': {'reason'}} if selection else
+        {'trial': {'candidate', 'reason'}, 'adopt': {'trial_id', 'reason'}, 'finish': {'reason'},
+         'observe': {'wait_s', 'duration_s', 'reason'}})
+    if (action not in expected or not isinstance(args, dict) or set(args) != expected[action]
+            or not isinstance(args['reason'], str) or not args['reason'].strip()):
+        raise ValueError('Unsupported decision or missing reason')
+    return value
+
+
+def _run(directory, p, *, clock, sleep, cancel, emit, selected, decision_session,
+        adapter=None, report_writer=None):
+    directory = Path(directory)
+    frozen = read_json(directory/'invocation.json').get('adjustment_plan') or {}
+    if frozen.get('kind') != 'dlc_adjustment':raise ValueError('Frozen DLC adjustment plan required')
+    laser = load_mapping((directory/'laser.yaml').read_text())
+    adapter = adapter or ParameterAdapter(laser, directory.name, clock=clock)
+    if hasattr(adapter, 'supervise'):adapter.supervise(directory, p, laser)
+    result = dict(status='running', family=None, trials=[], measurements=[], adopted=False,
+        physical_outcome='no_owner_command_in_flight', target_frequency_hz=adapter.target,
+        interpretation='Finite paired comparisons; no global optimum or long-term stability claim')
+    adopted = False
+
+    def save():atomic_json(directory/'parameter-adjustment.json', result)
+    def check():
+        if cancel() or clock() >= decision_session.deadline:raise CardCancelled('Adjustment cancelled/deadline')
+        adapter.check()
+    def request(prompt, *, selecting=False):
+        for attempt in range(3):
+            check()
+            store, _, _, _ = selected
+            _, manifest = export_evidence(directory, store, laser['id'],
+                evidence(directory, result, adapter.state, decision_session.turns))
+            mode = getattr(adapter, 'operating_mode', None)
+            if mode and mode.get('mode') in ('measurement', 'characterization'):
+                from ldcon.agents.operating_mode_client import instructions
+                policy = instructions(mode)
+            else:policy = ''
+            raw = decision_session.request(dict(kind='dlc_adjustment_decision', prompt=prompt+policy+
+                '\nTask objective: '+p['prompt']+' '+p['adjustment_objective'], evidence_files=manifest), tick=check)
+            try:
+                value = response(raw, selection=selecting)
+                action, args = value['action'], value['parameters']
+                if action == 'choose' and args['family'] not in supported:
+                    raise ValueError('Family is not admitted and supported by this owner')
+                if action == 'trial':candidate(result['family'], args['candidate'])
+                if action == 'observe':
+                    if (any(type(args[k]) not in (int,float) or not math.isfinite(args[k]) for k in ('wait_s','duration_s'))
+                            or not 0 <= args['wait_s'] <= 86400 or not 0 < args['duration_s'] <= 86400):
+                        raise ValueError('Observation timing must be finite and positive')
+                    if args['wait_s']+args['duration_s']+30 >= decision_session.deadline-clock():
+                        raise ValueError('Observation exceeds the remaining finite task budget')
+                if action == 'adopt':
+                    i = args['trial_id']
+                    if type(i) is not int or not 0 <= i < len(result['trials']):raise ValueError('Unknown trial')
+                    if not result['trials'][i]['eligible']:raise ValueError('Incomplete comparison evidence')
+                    if p['adoption_mode'] != 'auto_within_approved':raise ValueError('This run is report-only')
+            except (ValueError, TypeError) as error:
+                result['last_rejection'] = str(error);save()
+                if attempt == 2:raise ValueError('Three invalid decisions; no command replay') from error
+                continue
+            result.pop('last_rejection', None)
+            atomic_json(directory/('parameter-decision-%03d.json'%decision_session.turns), value)
+            return value
+
+    check()
+    supported = [f for f in frozen['measurements']
+        if adapter.state.get('parameter_capabilities', {}).get(f, {}).get('supported') is True
+        and (getattr(adapter,'monitor_families',None) is None or f in adapter.monitor_families)]
+    family = frozen['family']
+    if family == 'auto':
+        answer = request('Select one useful adjustment family from the admitted owner capabilities, or finish '
+            'without physical changes if none is justified. Review current state, supplied monitor events, recent '
+            'source history and prior adjustment outcomes using the advertised read-only evidence tools. '
+            'PI compares independent P/I/integral contribution; current compares the diode current offset; slow_loop '
+            'compares TEC centering gain/period/PZT center; feedforward compares the internal current FF coefficient. '
+            'A quality warning is a prompt to assess, not proof that a particular knob must move. Return '
+            '{"action":"choose","parameters":{"family":"...","reason":"..."}} or '
+            '{"action":"finish","parameters":{"reason":"..."}}. Supported families: '+str(supported), selecting=True)
+        if answer['action'] == 'finish':
+            result.update(status='succeeded', reason=answer['parameters']['reason'],
+                message='Assessment completed without a physical trial', output_writes=0)
+            save();return result
+        family = answer['parameters']['family']
+        result['selection_reason'] = answer['parameters']['reason']
+    if family not in supported:raise ValueError('Requested family has no admitted owner capability')
+    result['family'] = family
+    adapter.select_family(family)
+    if family == 'pi':
+        from ldcon.agents.dlc_pi_adjustment import run as pi_run
+        outcome = pi_run(directory, p, clock=clock, sleep=sleep, cancel=cancel, emit=emit,
+            selected=selected, decision_session=decision_session, adapter=adapter, report_writer=report_writer,
+            plan=dict(kind='dlc_pi_change_measure', measurement=frozen['measurements']['pi']))
+        result.update(status=outcome['status'],adopted=outcome['adopted'],pi_result_path='pi-adjustment.json')
+        save();return dict(outcome,family='pi')
+    measurement = deepcopy(frozen['measurements'][family])
+    result['checkpoint'] = deepcopy(adapter.origin)
+    save()
+
+    def measure(values, role, *, restore=False):
+        check()
+        if restore:
+            receipt = adapter.restore_checkpoint()
+            result.setdefault('restoration_receipts', []).append(receipt)
+        q = deepcopy(measurement)
+        q['target_frequency_hz'] = adapter.target
+        q['changes'] = [] if restore or role == 'baseline' else [dict(parameter=k, value=v) for k,v in values.items()]
+        remaining = decision_session.deadline-clock()
+        if remaining < q['baseline_s']+q['wait_s']+q['duration_s']+10:
+            raise CardCancelled('Insufficient task time for a complete comparison window')
+        q['timeout_s'] = min(q['timeout_s'], remaining)
+        name = 'parameter-window-%03d'%len(result['measurements'])
+        runner = ChangeMeasure(adapter, q, clock=clock, wall_clock=adapter.wall_clock,
+            sleep=sleep, cancel=cancel, emit=emit)
+        try:raw = runner.run()
+        finally:atomic_json(directory/(name+'.json'), runner.result)
+        if raw['status'] != 'succeeded':raise DeviceError('Incomplete measurement window; no adoption')
+        row = dict(id=name, role=role, settings=deepcopy(values), summary=raw['summary'], path=name+'.json')
+        result['measurements'].append(row);save();emit('parameter_measurement_completed', row)
+        return row
+
+    try:
+        adapter.begin()
+        result['checkpoint']=deepcopy(adapter.origin);save()
+        baseline = measure(adapter.origin, 'baseline')
+        while decision_session.turns < decision_session.profile['max_turns']-2:
+            check()
+            if decision_session.deadline-clock() < 30:break
+            answer = request('Choose a bounded informative candidate, request confirmation/adoption of a recorded '
+                'trial, or finish. Compare full time-stamped wavelength/optical measurements, sustained bias, '
+                'oscillation, drift, PZT/TEC coupling and ordinary scatter. Current is the DLC current OFFSET '
+                'in mA; total current including internal FF is checked independently by the owner. Slow-loop '
+                'parameters set TEC centering behavior, not a direct target change. A restored TEC command is '
+                'not proof of thermal settling: use the recorded wait/window and say if it is inadequate. '
+                'An FF candidate is justified only if PZT motion in the evidence identifies its effect; unchanged '
+                'PZT is not a coefficient calibration. Choose a small initial experiment from evidence, rather '
+                'than jumping across physical bounds. Assess metric trade-offs jointly and retain practical '
+                'headroom for drift; do not optimize to a threshold or require every metric to improve. '
+                'The host returns to the trial checkpoint for matched baseline. First adopt requests a repeated '
+                'candidate plus baseline; review that confirmation and issue adopt on its new trial_id to commit. '
+                'No target, safety, calibration, firmware, new hardware sweep or optical-threshold edits are allowed. '
+                'Foreground operations have priority. Return {"action":"trial","parameters":{"candidate":{...},'
+                '"reason":"..."}}, {"action":"adopt","parameters":{"trial_id":0,"reason":"..."}}, '
+                'or {"action":"finish","parameters":{"reason":"..."}}. To change an inadequate measurement '
+                'window, return {"action":"observe","parameters":{"wait_s":5,"duration_s":60,"reason":"..."}} '
+                '(values are illustrative): this creates a fresh checkpoint baseline and invalidates old adoption '
+                'eligibility, preserving comparable windows. Explain actual gains, costs and limits.')
+            action, args = answer['action'], answer['parameters']
+            if action == 'finish':result['reason'] = args['reason'];break
+            if action == 'observe':
+                measurement.update(wait_s=args['wait_s'],duration_s=args['duration_s'])
+                measurement['timeout_s'] = measurement['baseline_s']+measurement['wait_s']+measurement['duration_s']+30
+                for previous in result['trials']:
+                    previous.update(eligible=False, ineligible_reason='Measurement duration changed; a fresh comparison is required')
+                result.setdefault('measurement_plan_changes',[]).append(deepcopy(args))
+                baseline = measure(adapter.origin, 'baseline', restore=True)
+                continue
+            prior = result['trials'][args['trial_id']] if action == 'adopt' else None
+            values = args['candidate'] if action == 'trial' else prior['candidate']
+            if prior and 'confirmation_of' in prior:
+                check()
+                proposal = adapter.preflight([dict(parameter=k, value=v) for k,v in values.items()],
+                    measurement['apply_mode'], measurement['measurements'])
+                result['adoption_receipt'] = adapter.apply(proposal, lambda:None)
+                receipt = adapter.close(adopt=True)
+                result['cleanup'] = receipt
+                if (not receipt or receipt.get('state') != 'adopted' or receipt.get('confirmed') is not True
+                        or receipt.get('settings') != values or receipt.get('identity') != adapter.identity
+                        or receipt.get('target_restored') is not True):
+                    raise CardCancelled('Adoption preempted or unconfirmed')
+                adopted = True
+                result.update(adopted=True, adopted_settings=deepcopy(values), reason=args['reason'])
+                break
+            if decision_session.deadline-clock() < 2*measurement['timeout_s']+30:
+                result['last_rejection'] = 'Insufficient time for another complete pair; finish or adopt a confirmed candidate'
+                save();continue
+            trial = measure(values, 'candidate' if action == 'trial' else 'confirmation')
+            after = measure(adapter.origin, 'matched_baseline', restore=True)
+            row = dict(id=len(result['trials']), candidate=deepcopy(values), before=baseline['id'],
+                trial=trial['id'], after=after['id'], eligible=True, reason=args['reason'])
+            if prior:row['confirmation_of'] = prior['id']
+            result['trials'].append(row);baseline = after;save()
+        result['status'] = 'succeeded'
+        result.setdefault('reason', 'Finite decision budget reached; checkpoint retained')
+    finally:
+        try:
+            if not adopted and not result.get('cleanup'):result['cleanup'] = adapter.close(adopt=False)
+            receipt = result.get('cleanup') or {}
+            if result['status'] == 'succeeded' and not adopted:
+                if (receipt.get('confirmed') is not True or receipt.get('identity') != adapter.identity
+                        or receipt.get('state') != 'restored' or receipt.get('settings') != adapter.origin):
+                    raise DeviceError('Checkpoint restoration is unconfirmed')
+                if receipt.get('target_restored') is not True or receipt.get('reason','completed') != 'completed':
+                    result.update(status='cancelled', reason='Foreground or owner preemption; checkpoint command restoration confirmed')
+        except Exception as error:
+            result.update(status='unknown', physical_outcome='requires_inspection', cleanup_error=type(error).__name__)
+            atomic_json(directory/'device-review.json', dict(source='dlc_parameter',
+                message='Parameter cleanup unconfirmed; inspect owner, do not replay'))
+            save();raise
+        if result['status'] == 'running':result['status'] = 'interrupted'
+        save()
+        try:
+            from ldcon.jobs.measurement_report import write_report
+            frames = [read_json(directory/row['path']) for row in result['measurements']]
+            report = (report_writer or write_report)(directory, dict(schema='ldcon.parameter-comparison/1',
+                status=result['status'], steps=frames, parameter_result=result))
+            import shutil
+            shutil.copyfile(report, directory/'report.pdf');result['report'] = 'report.pdf'
+        except Exception as error:result['report_error'] = type(error).__name__
+        save()
+    result['message'] = ('Repeated measured candidate adopted for this lock' if adopted else
+        'Comparison completed; checkpoint retained' if result['status']=='succeeded' else
+        'Adjustment interrupted; inspect the recorded owner receipt')
+    return result
+
+
+def run(directory, p, *, clock, sleep, cancel, emit, selected, decision_session,
+        adapter=None, report_writer=None):
+    laser=load_mapping((Path(directory)/'laser.yaml').read_text())
+    adapter=adapter or ParameterAdapter(laser,Path(directory).name,clock=clock)
+    try:
+        return _run(directory,p,clock=clock,sleep=sleep,cancel=cancel,emit=emit,
+            selected=selected,decision_session=decision_session,adapter=adapter,report_writer=report_writer)
+    except Exception as error:
+        if isinstance(error,CardCancelled) or cancel():raise
+        if (getattr(adapter,'uncertain',False) or getattr(adapter,'begin_pending',False)
+                or not hasattr(adapter,'session')):raise
+        try:proof=adapter.session.rpc('pi_trial_receipt')
+        except Exception:raise error
+        trial=proof.get('trial') or {};last=trial.get('last') or {}
+        known=(not proof.get('fault') and trial.get('active') is None and
+            (not getattr(adapter,'begin_confirmed',False) or
+             last.get('identity')==adapter.identity and last.get('confirmed') is True and last.get('state')=='restored'))
+        if not known:raise
+        from ldcon.agents.resident_adjustment import HostProtocolStop
+        atomic_json(Path(directory)/'adjustment-known-stop.json',dict(reason=type(error).__name__,
+            owner_receipt=proof,physical_outcome='no_owner_command_in_flight'))
+        raise HostProtocolStop(str(error),dict(status=dict(state='restored' if last else 'not_started',active=False),
+            latest_result=dict(state='restored' if last else 'not_started'))) from error

{ldcon-0.2.1 → ldcon-0.2.2}/src/ldcon/agents/dlc_pi_adjustment.py

@@ -70,13 +70,14 @@ def evidence_documents(directory, result, state, turn):
     return docs
 
 
-def run(directory,p,*,clock,sleep,cancel,emit,selected,decision_session,adapter=None,report_writer=None):
+def run(directory,p,*,clock,sleep,cancel,emit,selected,decision_session,adapter=None,report_writer=None,plan=None):
     directory=Path(directory)
     invocation=read_json(directory/'invocation.json')
-    plan=invocation.get('adjustment_plan') or {}
+    plan=deepcopy(plan if plan is not None else invocation.get('adjustment_plan') or {})
     if plan.get('kind') not in ('dlc_pi_change_measure','dlc_pi_target_response'):raise ValueError('Frozen PI measurement plan required')
     laser=load_mapping((directory/'laser.yaml').read_text())
     adapter=adapter or PIAdapter(laser,directory.name,clock=clock)
+    if hasattr(adapter,'supervise'):adapter.supervise(directory,p,laser)
     joint=plan['kind']=='dlc_pi_target_response'
     if joint:
         if adapter.target!=plan['target_frequency_hz']:raise ValueError('Live target differs from frozen response reference')
@@ -154,7 +155,7 @@ def run(directory,p,*,clock,sleep,cancel,emit,selected,decision_session,adapter=
         result.update(adopted=True,adopted_settings=values,reason=reason,
             adoption_basis='Task-model decision after repeated matched measurements')
     try:
-        adapter.begin();save()
+        adapter.begin();result['checkpoint']=deepcopy(adapter.origin);save()
         baseline=measure(adapter.origin,'baseline')
         invalid=0
         while True:
@@ -179,6 +180,9 @@ def run(directory,p,*,clock,sleep,cancel,emit,selected,decision_session,adapter=
                 'or {"action":"adopt","parameters":{"trial_id":number,"reason":"..."}}, '
                 'or {"action":"finish","parameters":{"reason":"..."}}. No other commands. '
                 'Explain why the evidence warrants a trial, adoption, or no further changes. '+p['prompt']+' '+p['adjustment_objective'])
+            if getattr(adapter,'operating_mode_revision',None) is not None:
+                from ldcon.agents.operating_mode_client import instructions
+                prompt+=instructions(adapter.operating_mode)
             if joint:
                 prompt+=' This is JOINT target-step and steady-noise optimization. The host executes the frozen target-step and return sequence; you only choose P/I/integral coefficients. Judge the overall trade-off among response speed, steady RMS, mean bias, overshoot, saturation and practical robustness. A modest RMS increase can be worthwhile for a substantial speed gain: the human explicitly gave +10 percent RMS with 2x faster response as an acceptable kind of trade-off, not a fixed numeric acceptance rule. Do not require RMS non-degradation or invent fixed weights. Quantify gains and costs and justify your preference. The response band is empirical from the first checkpoint and stays fixed. Null settling times are censored, not zero or the deadline. Compare request/verified-write timestamps, signed mean error, response integral and the full raw waveforms. No candidate-specific relaxation of the band. Requesting adopt for an initial trial triggers a repeat and matched baseline. Review that new confirmation row before issuing adopt again for its trial_id; only the second decision can commit. You may decline after seeing confirmation.'
             answer=decision_session.request(dict(kind='pi_adjustment_decision',prompt=prompt,evidence_files=manifest),tick=check)