ldcon 0.2.0__py3-none-any.whl

ldcon/__init__.py

@@ -0,0 +1,302 @@
+"""Shared interface cards, instrument ownership and laser dashboard."""
+import importlib as _importlib
+from ldcon._moved import install as _install
+
+# Old flat name -> new subpackage path (refactor phase 2). See ldcon/_moved.py; importing ldcon stays lazy.
+MOVED = {
+    # G1 (ldcon.migration itself became the package __init__: same name, no alias needed)
+    'ldcon.migration_decks': 'ldcon.migration.migration_decks',
+    'ldcon.migration_readiness': 'ldcon.migration.migration_readiness',
+    'ldcon.migration_relocation': 'ldcon.migration.migration_relocation',
+    # G2
+    'ldcon.fizeau': 'ldcon.drivers.fizeau',
+    'ldcon.rigol_scope': 'ldcon.drivers.rigol_scope',
+    'ldcon.esp32_servo': 'ldcon.drivers.esp32_servo',
+    # G3 (fallback_service, report_pdf keep an entry stub ldcon/<name>.py)
+    'ldcon.teams_card': 'ldcon.agents.teams_card',
+    'ldcon.teams_destinations': 'ldcon.agents.teams_destinations',
+    'ldcon.notification_policy': 'ldcon.agents.notification_policy',
+    'ldcon.card_fallback': 'ldcon.agents.card_fallback',
+    'ldcon.fallback_targets': 'ldcon.agents.fallback_targets',
+    'ldcon.fallback_service': 'ldcon.agents.fallback_service',
+    'ldcon.failure_policy': 'ldcon.agents.failure_policy',
+    'ldcon.report_pdf': 'ldcon.agents.report_pdf',
+    # G4 (dashboard_metrics keeps an entry stub)
+    'ldcon.dashboard_activity': 'ldcon.web.dashboard_activity',
+    'ldcon.dashboard_controls_revision': 'ldcon.web.dashboard_controls_revision',
+    'ldcon.dashboard_metrics': 'ldcon.web.dashboard_metrics',
+    'ldcon.dashboard_snapshot': 'ldcon.web.dashboard_snapshot',
+    'ldcon.dashboard_state': 'ldcon.web.dashboard_state',
+    'ldcon.dashboard_wavelength': 'ldcon.web.dashboard_wavelength',
+    'ldcon.dither_quality': 'ldcon.web.dither_quality',
+    'ldcon.quality_threshold_metrics': 'ldcon.web.quality_threshold_metrics',
+    'ldcon.grafana_activity': 'ldcon.web.grafana_activity',
+    'ldcon.grafana_dashboard': 'ldcon.web.grafana_dashboard',
+    'ldcon.grafana_quality': 'ldcon.web.grafana_quality',
+    'ldcon.metric_query_profiles': 'ldcon.web.metric_query_profiles',
+    'ldcon.target_reference_panel': 'ldcon.web.target_reference_panel',
+    'ldcon.job_report': 'ldcon.web.job_report',
+    'ldcon.log_archive': 'ldcon.web.log_archive',
+    'ldcon.operations_settings': 'ldcon.web.operations_settings',
+    'ldcon.job_registry': 'ldcon.web.job_registry',
+    'ldcon.interface_projection': 'ldcon.web.interface_projection',
+    'ldcon.operation_observation': 'ldcon.web.operation_observation',
+    # G5
+    'ldcon.slow_control': 'ldcon.jobs.slow_control',
+    'ldcon.slow_current': 'ldcon.jobs.slow_current',
+    'ldcon.online_pid': 'ldcon.jobs.online_pid',
+    'ldcon.adaptive_pid': 'ldcon.jobs.adaptive_pid',
+    'ldcon.current_cards': 'ldcon.jobs.current_cards',
+    'ldcon.current_devices': 'ldcon.jobs.current_devices',
+    'ldcon.temperature_identification': 'ldcon.jobs.temperature_identification',
+    'ldcon.metric_cards': 'ldcon.jobs.metric_cards',
+    'ldcon.metric_interface': 'ldcon.jobs.metric_interface',
+    'ldcon.optical_broker': 'ldcon.jobs.optical_broker',
+    'ldcon.fringe_sweep_reference': 'ldcon.jobs.fringe_sweep_reference',
+    # G6
+    'ldcon.window_actions': 'ldcon.jobs.window_actions',
+    'ldcon.window_center': 'ldcon.jobs.window_center',
+    'ldcon.window_sampling': 'ldcon.jobs.window_sampling',
+    'ldcon.window_control': 'ldcon.jobs.window_control',
+    'ldcon.window_decisions': 'ldcon.jobs.window_decisions',
+    'ldcon.adaptive_window_session': 'ldcon.jobs.adaptive_window_session',
+    'ldcon.adjustment_continuation': 'ldcon.jobs.adjustment_continuation',
+    'ldcon.background_pid_session': 'ldcon.jobs.background_pid_session',
+    'ldcon.background_parameter_session': 'ldcon.jobs.background_parameter_session',
+    'ldcon.simulation': 'ldcon.jobs.simulation',
+    # G7
+    'ldcon.ecdl_devices': 'ldcon.jobs.ecdl_devices',
+    'ldcon.ecdl_steady': 'ldcon.jobs.ecdl_steady',
+    'ldcon.ecdl_window_center': 'ldcon.jobs.ecdl_window_center',
+    'ldcon.ecdl_online': 'ldcon.jobs.ecdl_online',
+    'ldcon.ecdl_mode_map': 'ldcon.jobs.ecdl_mode_map',
+    'ldcon.ecdl_mode_recovery': 'ldcon.jobs.ecdl_mode_recovery',
+    'ldcon.ecdl_recovery': 'ldcon.jobs.ecdl_recovery',
+    'ldcon.ecdl_recovery_plan': 'ldcon.jobs.ecdl_recovery_plan',
+    'ldcon.ecdl_recovery_test': 'ldcon.jobs.ecdl_recovery_test',
+    'ldcon.ecdl_relock': 'ldcon.jobs.ecdl_relock',
+    'ldcon.ecdl_response_study': 'ldcon.jobs.ecdl_response_study',
+    'ldcon.ecdl_branch_hop': 'ldcon.jobs.ecdl_branch_hop',
+    'ldcon.ecdl_operating_point': 'ldcon.jobs.ecdl_operating_point',
+    'ldcon.ecdl_thermal_context': 'ldcon.jobs.ecdl_thermal_context',
+    'ldcon.ecdl_pi_commission': 'ldcon.jobs.ecdl_pi_commission',
+    'ldcon.workflow_artifacts': 'ldcon.jobs.workflow_artifacts',
+    # G8
+    'ldcon.lock_target': 'ldcon.jobs.lock_target',
+    'ldcon.target_sequence': 'ldcon.jobs.target_sequence',
+    'ldcon.target_response': 'ldcon.jobs.target_response',
+    'ldcon.target_response_analysis': 'ldcon.jobs.target_response_analysis',
+    'ldcon.target_response_control': 'ldcon.jobs.target_response_control',
+    'ldcon.target_response_decisions': 'ldcon.jobs.target_response_decisions',
+    'ldcon.target_response_experiment': 'ldcon.jobs.target_response_experiment',
+    'ldcon.target_response_feedforward': 'ldcon.jobs.target_response_feedforward',
+    'ldcon.target_response_search': 'ldcon.jobs.target_response_search',
+    'ldcon.settling_profile': 'ldcon.jobs.settling_profile',
+    'ldcon.learned_settling': 'ldcon.jobs.learned_settling',
+    'ldcon.pi_response': 'ldcon.jobs.pi_response',
+    'ldcon.wavelength_history': 'ldcon.jobs.wavelength_history',
+    'ldcon.study_execution': 'ldcon.jobs.study_execution',
+    'ldcon.study_adoption': 'ldcon.jobs.study_adoption',
+    'ldcon.quality_baseline': 'ldcon.jobs.quality_baseline',
+    'ldcon.dashboard_api': 'ldcon.jobs.dashboard_api',
+    'ldcon.measurement_notice': 'ldcon.jobs.measurement_notice',
+    'ldcon.operating_point': 'ldcon.jobs.operating_point',
+    'ldcon.device_parameters': 'ldcon.jobs.device_parameters',
+    'ldcon.emission_card': 'ldcon.jobs.emission_card',
+    # G9
+    'ldcon.native_ff_proxy': 'ldcon.jobs.native_ff_proxy',
+    'ldcon.native_ff_sweep': 'ldcon.jobs.native_ff_sweep',
+    'ldcon.ecdl_locked_sweep_proxy': 'ldcon.jobs.ecdl_locked_sweep_proxy',
+    'ldcon.modulation_sweep': 'ldcon.jobs.modulation_sweep',
+    'ldcon.shot_analysis': 'ldcon.jobs.shot_analysis',
+    'ldcon.sweep_tracking': 'ldcon.jobs.sweep_tracking',
+    'ldcon.sweep_verdict': 'ldcon.jobs.sweep_verdict',
+    'ldcon.native_current_acquire': 'ldcon.jobs.native_current_acquire',
+    'ldcon.native_current_card': 'ldcon.jobs.native_current_card',
+    'ldcon.native_current_online': 'ldcon.jobs.native_current_online',
+    'ldcon.native_background_session': 'ldcon.jobs.native_background_session',
+    'ldcon.progress': 'ldcon.jobs.progress',
+    # G10 (monitor_owner, esp32_time_telemetry keep an entry stub); cld_projection was added after the map (owner-side CLD policy)
+    'ldcon.esp32_native_owner': 'ldcon.owners.esp32_native_owner',
+    'ldcon.esp32_native_client': 'ldcon.owners.esp32_native_client',
+    'ldcon.esp32_udp_gate': 'ldcon.owners.esp32_udp_gate',
+    'ldcon.esp32_time_telemetry': 'ldcon.owners.esp32_time_telemetry',
+    'ldcon.native_assembly': 'ldcon.owners.native_assembly',
+    'ldcon.native_assembly_host': 'ldcon.owners.native_assembly_host',
+    'ldcon.native_background': 'ldcon.owners.native_background',
+    'ldcon.native_current_tuning': 'ldcon.owners.native_current_tuning',
+    'ldcon.native_ff_proof': 'ldcon.owners.native_ff_proof',
+    'ldcon.native_instrument_owner': 'ldcon.owners.native_instrument_owner',
+    'ldcon.native_modulation_limits': 'ldcon.owners.native_modulation_limits',
+    'ldcon.native_policy_reload': 'ldcon.owners.native_policy_reload',
+    'ldcon.native_policy_safety': 'ldcon.owners.native_policy_safety',
+    'ldcon.native_policy_update': 'ldcon.owners.native_policy_update',
+    'ldcon.native_system_owner': 'ldcon.owners.native_system_owner',
+    'ldcon.flexible_native_trial': 'ldcon.owners.flexible_native_trial',
+    'ldcon.adc_log_threshold': 'ldcon.owners.adc_log_threshold',
+    'ldcon.full_data_log': 'ldcon.owners.full_data_log',
+    'ldcon.monitor_owner': 'ldcon.owners.monitor_owner',
+    'ldcon.cld_projection': 'ldcon.owners.cld_projection',
+    # G11 (owner_telemetry keeps an entry stub); ecdl_thermal_study, tec_rate were added after the map (owner-only TEC overlay / cadence)
+    'ldcon.ecdl_owner': 'ldcon.owners.ecdl_owner',
+    'ldcon.ecdl_steady_owner': 'ldcon.owners.ecdl_steady_owner',
+    'ldcon.ecdl_steady_policy': 'ldcon.owners.ecdl_steady_policy',
+    'ldcon.ecdl_policy_reload': 'ldcon.owners.ecdl_policy_reload',
+    'ldcon.ecdl_projection': 'ldcon.owners.ecdl_projection',
+    'ldcon.ecdl_native_pid': 'ldcon.owners.ecdl_native_pid',
+    'ldcon.ecdl_background_pid': 'ldcon.owners.ecdl_background_pid',
+    'ldcon.ecdl_background_parameters': 'ldcon.owners.ecdl_background_parameters',
+    'ldcon.background_grants': 'ldcon.owners.background_grants',
+    'ldcon.ecdl_tec_pair': 'ldcon.owners.ecdl_tec_pair',
+    'ldcon.ecdl_target_ff': 'ldcon.owners.ecdl_target_ff',
+    'ldcon.ecdl_target_settling': 'ldcon.owners.ecdl_target_settling',
+    'ldcon.ecdl_hot_control': 'ldcon.owners.ecdl_hot_control',
+    'ldcon.ecdl_locked_sweep': 'ldcon.owners.ecdl_locked_sweep',
+    'ldcon.ecdl_locked_study': 'ldcon.owners.ecdl_locked_study',
+    'ldcon.ecdl_optical': 'ldcon.owners.ecdl_optical',
+    'ldcon.fringe_peaks': 'ldcon.owners.fringe_peaks',
+    'ldcon.external_sweep_guard': 'ldcon.owners.external_sweep_guard',
+    'ldcon.ecdl_prelock': 'ldcon.owners.ecdl_prelock',
+    'ldcon.owner_telemetry': 'ldcon.owners.owner_telemetry',
+    'ldcon.sdg_owner': 'ldcon.owners.sdg_owner',
+    'ldcon.sdg_client': 'ldcon.owners.sdg_client',
+    'ldcon.emission': 'ldcon.owners.emission',
+    'ldcon.emission_adapters': 'ldcon.owners.emission_adapters',
+    'ldcon.operating_mode_owner': 'ldcon.owners.operating_mode_owner',
+    'ldcon.ecdl_thermal_study': 'ldcon.owners.ecdl_thermal_study',
+    'ldcon.tec_rate': 'ldcon.owners.tec_rate',
+    # G12 (instrument_owner, instrument_service, cld_owner, device_registry keep an entry stub)
+    'ldcon.instrument_owner': 'ldcon.owners.instrument_owner',
+    'ldcon.instrument_service': 'ldcon.owners.instrument_service',
+    'ldcon.instrument_identity': 'ldcon.owners.instrument_identity',
+    'ldcon.instrument_projection': 'ldcon.owners.instrument_projection',
+    'ldcon.owner_projection': 'ldcon.owners.owner_projection',
+    'ldcon.projection_transport': 'ldcon.owners.projection_transport',
+    'ldcon.device_registry': 'ldcon.owners.device_registry',
+    'ldcon.remote_instruments': 'ldcon.owners.remote_instruments',
+    'ldcon.cld_owner': 'ldcon.owners.cld_owner',
+    'ldcon.cld_instrument_owner': 'ldcon.owners.cld_instrument_owner',
+    'ldcon.cld_system_owner': 'ldcon.owners.cld_system_owner',
+    'ldcon.current_owner': 'ldcon.owners.current_owner',
+    'ldcon.migration_physical_lock': 'ldcon.owners.migration_physical_lock',
+    # G13 (agent_tools keeps an entry stub: ENTRY_MODULES and `-m ldcon.agent_tools <context>`)
+    'ldcon.agent_adapters': 'ldcon.agents.agent_adapters',
+    'ldcon.agent_background': 'ldcon.agents.agent_background',
+    'ldcon.agent_bundle': 'ldcon.agents.agent_bundle',
+    'ldcon.agent_cards': 'ldcon.agents.agent_cards',
+    'ldcon.agent_config_access': 'ldcon.agents.agent_config_access',
+    'ldcon.agent_configuration': 'ldcon.agents.agent_configuration',
+    'ldcon.agent_configuration_policy': 'ldcon.agents.agent_configuration_policy',
+    'ldcon.agent_connect': 'ldcon.agents.agent_connect',
+    'ldcon.agent_device_parameters': 'ldcon.agents.agent_device_parameters',
+    'ldcon.agent_execution': 'ldcon.agents.agent_execution',
+    'ldcon.agent_history': 'ldcon.agents.agent_history',
+    'ldcon.agent_inbox_watch': 'ldcon.agents.agent_inbox_watch',
+    'ldcon.agent_interactive': 'ldcon.agents.agent_interactive',
+    'ldcon.agent_interactive_hooks': 'ldcon.agents.agent_interactive_hooks',
+    'ldcon.agent_language': 'ldcon.agents.agent_language',
+    'ldcon.agent_log_context': 'ldcon.agents.agent_log_context',
+    'ldcon.agent_log_read': 'ldcon.agents.agent_log_read',
+    'ldcon.agent_log_watch': 'ldcon.agents.agent_log_watch',
+    'ldcon.agent_metrics': 'ldcon.agents.agent_metrics',
+    'ldcon.agent_monitor': 'ldcon.agents.agent_monitor',
+    'ldcon.agent_opencode_http': 'ldcon.agents.agent_opencode_http',
+    'ldcon.agent_owner_status': 'ldcon.agents.agent_owner_status',
+    'ldcon.agent_profiles': 'ldcon.agents.agent_profiles',
+    'ldcon.agent_providers': 'ldcon.agents.agent_providers',
+    'ldcon.agent_repairs': 'ldcon.agents.agent_repairs',
+    'ldcon.agent_routing': 'ldcon.agents.agent_routing',
+    'ldcon.agent_runtime': 'ldcon.agents.agent_runtime',
+    'ldcon.agent_sandbox': 'ldcon.agents.agent_sandbox',
+    'ldcon.agent_startup_notice': 'ldcon.agents.agent_startup_notice',
+    'ldcon.agent_task': 'ldcon.agents.agent_task',
+    'ldcon.agent_tools': 'ldcon.agents.agent_tools',
+    'ldcon.agent_window': 'ldcon.agents.agent_window',
+    'ldcon.agent_workspace': 'ldcon.agents.agent_workspace',
+    'ldcon.resident_agent': 'ldcon.agents.resident_agent',
+    'ldcon.resident_adjustment': 'ldcon.agents.resident_adjustment',
+    'ldcon.resident_quality_apply': 'ldcon.agents.resident_quality_apply',
+    'ldcon.task_decisions': 'ldcon.agents.task_decisions',
+    'ldcon.gateway_role': 'ldcon.agents.gateway_role',
+    'ldcon.manual_adjustment_grant': 'ldcon.agents.manual_adjustment_grant',
+    'ldcon.monitor_quality_binding': 'ldcon.agents.monitor_quality_binding',
+    'ldcon.adjustment_guidance': 'ldcon.agents.adjustment_guidance',
+    'ldcon.adjustment_quality': 'ldcon.agents.adjustment_quality',
+    'ldcon.operating_mode_client': 'ldcon.agents.operating_mode_client',
+    # G14 (job_service, interface_worker keep an entry stub: units, `-m ldcon.interface_worker` spawn + card_fallback cmdline match)
+    'ldcon.job_service': 'ldcon.jobs.job_service',
+    'ldcon.interface_worker': 'ldcon.jobs.interface_worker',
+    'ldcon.interface_devices': 'ldcon.jobs.interface_devices',
+    'ldcon.card_runtime': 'ldcon.jobs.card_runtime',
+    'ldcon.runtime_parameters': 'ldcon.jobs.runtime_parameters',
+    'ldcon.laser_live': 'ldcon.jobs.laser_live',
+    'ldcon.operation_execution': 'ldcon.jobs.operation_execution',
+    # G15 (web_server, web_fleet keep an entry stub: units, ldcon.cli:web_main)
+    'ldcon.agent_approval_api': 'ldcon.web.agent_approval_api',
+    'ldcon.agent_settings_api': 'ldcon.web.agent_settings_api',
+    'ldcon.agent_task_api': 'ldcon.web.agent_task_api',
+    'ldcon.device_parameters_api': 'ldcon.web.device_parameters_api',
+    'ldcon.failure_api': 'ldcon.web.failure_api',
+    'ldcon.operating_mode_api': 'ldcon.web.operating_mode_api',
+    'ldcon.operation_api': 'ldcon.web.operation_api',
+    'ldcon.window_api': 'ldcon.web.window_api',
+    'ldcon.teams_destinations_api': 'ldcon.web.teams_destinations_api',
+    'ldcon.lock_target_api': 'ldcon.web.lock_target_api',
+    'ldcon.lock_target_queue': 'ldcon.web.lock_target_queue',
+    'ldcon.sweep_api': 'ldcon.web.sweep_api',
+    'ldcon.sweep_guard': 'ldcon.web.sweep_guard',
+    'ldcon.shot_analysis_api': 'ldcon.web.shot_analysis_api',
+    'ldcon.laser_operations': 'ldcon.web.laser_operations',
+    'ldcon.online_position': 'ldcon.web.online_position',
+    'ldcon.web_fleet': 'ldcon.web.web_fleet',
+    'ldcon.web_server': 'ldcon.web.web_server',
+    # G16 (job supervisor hub; still re-exports ConflictError/TERMINAL for core until the split in module-map.md 2b)
+    'ldcon.web_runtime': 'ldcon.web.web_runtime',
+    # G17 (core hubs: contracts, records, schema, cards, clients, layout, configuration; no entry)
+    'ldcon.contracts': 'ldcon.core.contracts',
+    'ldcon.records': 'ldcon.core.records',
+    'ldcon.execution_context': 'ldcon.core.execution_context',
+    'ldcon.state_layout': 'ldcon.core.state_layout',
+    'ldcon.deck_yaml': 'ldcon.core.deck_yaml',
+    'ldcon.device_conditions': 'ldcon.core.device_conditions',
+    'ldcon.interface_schema': 'ldcon.core.interface_schema',
+    'ldcon.interface_cards': 'ldcon.core.interface_cards',
+    'ldcon.card_definition': 'ldcon.core.card_definition',
+    'ldcon.instrument_client': 'ldcon.core.instrument_client',
+    'ldcon.current_settings': 'ldcon.core.current_settings',
+    'ldcon.temperature_settings': 'ldcon.core.temperature_settings',
+    'ldcon.site_bindings': 'ldcon.core.site_bindings',
+    'ldcon.result_reservations': 'ldcon.core.result_reservations',
+    'ldcon.configuration': 'ldcon.core.configuration',
+    'ldcon.configuration_transaction': 'ldcon.core.configuration_transaction',
+    'ldcon.metric_quantities': 'ldcon.core.metric_quantities',
+    'ldcon.card_reporting': 'ldcon.core.card_reporting',
+    'ldcon.telegraf': 'ldcon.core.telegraf',
+    'ldcon.telemetry': 'ldcon.core.telemetry',
+    'ldcon.period_context': 'ldcon.core.period_context',
+    'ldcon.adjustment_registry': 'ldcon.core.adjustment_registry',
+    'ldcon.laser_assets': 'ldcon.core.laser_assets',
+    'ldcon.modulation': 'ldcon.core.modulation',
+    'ldcon.agent_authority': 'ldcon.core.agent_authority',
+    'ldcon.operation_registry': 'ldcon.core.operation_registry',
+    'ldcon.card_admission': 'ldcon.core.card_admission',
+    # added after the module map (63db3e1), assigned by responsibility (see doc/card-system-current-state.md, phase 2 G10-G13)
+    'ldcon.branch_maps': 'ldcon.jobs.branch_maps',
+    'ldcon.branch_target_migration': 'ldcon.jobs.branch_target_migration',
+    'ldcon.ecdl_branch_recovery': 'ldcon.jobs.ecdl_branch_recovery',
+    'ldcon.locked_triangle': 'ldcon.jobs.locked_triangle',
+    'ldcon.operating_point_proxy': 'ldcon.jobs.operating_point_proxy',
+    'ldcon.target_response_thermal': 'ldcon.jobs.target_response_thermal',
+    'ldcon.target_response_thermal_experiment': 'ldcon.jobs.target_response_thermal_experiment',
+    'ldcon.target_policy': 'ldcon.core.target_policy',
+    'ldcon.control_readback': 'ldcon.web.control_readback',
+}
+_install(MOVED)
+
+
+def __getattr__(name):
+    if 'ldcon.' + name in MOVED: return _importlib.import_module('ldcon.' + name)  # the finder binds the attribute
+    raise AttributeError(f'module ldcon has no attribute {name!r}')
+
+
+def __dir__(): return sorted(set(globals()) | {name.split('.')[1] for name in MOVED})

ldcon/_moved.py

@@ -0,0 +1,49 @@
+"""Old import paths of modules moved into subpackages (refactor phase 2, 2026-10-27).
+
+`ldcon.MOVED` maps each old name to the new dotted path. A meta-path finder installed by
+`ldcon/__init__.py` resolves `import ldcon.<old>`, `from ldcon.<old> import x`, `from ldcon import <old>`,
+`importlib.import_module('ldcon.<old>')` and `python -m ldcon.<old>` to the *same module object* as the new
+path (an alias in `sys.modules`, not a copy), so a `monkeypatch.setattr` through the old alias reaches the
+globals the real functions read. Entry modules additionally keep a tiny `ldcon/<old>.py` stub for
+`python -m ldcon.<old>` (the units name them). The aliases exist for releases, units, deploy scripts and
+external callers that still use the old names; code inside the package imports the new paths directly.
+"""
+import importlib, importlib.abc, importlib.machinery, importlib.util, sys
+
+
+def alias(old, new=None):
+    """Bind sys.modules[old] and the parent attribute to the module at `new` (default: ldcon.MOVED[old])."""
+    new = new or sys.modules['ldcon'].MOVED[old]
+    module = importlib.import_module(new)
+    sys.modules[old] = module
+    parent, _, attribute = old.rpartition('.')
+    setattr(sys.modules[parent], attribute, module)
+    return module
+
+
+class _Loader(importlib.abc.Loader):
+    def __init__(self, new): self.new = new
+    def create_module(self, spec):
+        module = importlib.import_module(self.new)
+        self.spec = module.__spec__
+        return module
+    def exec_module(self, module):
+        module.__spec__ = self.spec  # module_from_spec replaced it with the alias spec; the module keeps its own identity
+    def get_code(self, name):  # runpy (`python -m ldcon.<old>`) without a stub file
+        return importlib.import_module(self.new).__spec__.loader.get_code(self.new)
+
+
+class _Finder(importlib.abc.MetaPathFinder):
+    def __init__(self, table): self.table = table
+    def find_spec(self, name, path=None, target=None):
+        new = self.table.get(name)
+        if new is None: return None
+        found = importlib.util.find_spec(new)
+        if found is None: raise ImportError(f'{name} was moved to {new}, which does not exist')
+        return importlib.machinery.ModuleSpec(name, _Loader(new), origin=found.origin)
+
+
+def install(table):
+    """Append the finder once (after the path finder, so real files such as the entry stubs win)."""
+    if not any(isinstance(finder, _Finder) for finder in sys.meta_path):
+        sys.meta_path.append(_Finder(table))

ldcon/agent_tools.py

@@ -0,0 +1,4 @@
+"""`python -m ldcon.agent_tools <context>` stays valid for ENTRY_MODULES and external callers; the module is ldcon.agents.agent_tools."""
+from ldcon._moved import alias
+_module = alias('ldcon.agent_tools')
+if __name__ == '__main__': _module.main()

ldcon/agents/__init__.py

@@ -0,0 +1 @@
+"""Resident agents, notifications and reports. Importing never contacts a model, an owner or Teams."""

ldcon/agents/adjustment_guidance.py

@@ -0,0 +1,73 @@
+"""Laser-specific proposal advice, separate from owner safety and trial grants."""
+from ldcon.core.state_layout import asset_parts, root_from_laser_file
+
+from experiment_core.adjustment_guidance import validate as validate_document, snapshot
+
+# Units describe proposals, not a promise that an owner supports every knob.
+UNITS = dict(current='V', temperature='V', piezo_center_dac='count',
+             kp_count_per_nm='count/nm', ki_count_per_nm_s='count/(nm*s)',
+             integral_limit_count='count', p_sample='1', g_sample='1',
+             tec_gain='1', tec_dt_cap_s='s', supervision_interval_s='s',
+             current_per_temperature='V/V', target_ff_scale='1', target_step_hz='Hz')
+
+
+def validate(value):
+    value = validate_document(value)
+    for knob, item in value['knobs'].items():
+        if knob not in UNITS:
+            raise ValueError('Unknown laser adjustment guidance knob: '+knob)
+        if item['kind'] == 'absolute' and item['unit'] != UNITS[knob]:
+            raise ValueError('Incorrect physical unit for guidance knob: '+knob)
+    return value
+
+
+def location(root, laser_id):
+    from pathlib import Path
+    from experiment_core.records import safe_id
+    path=Path(root).joinpath(*asset_parts(root, safe_id(laser_id)))/'data'/'adjustment-guidance.json'
+    if any(p.is_symlink() for p in (path,*path.parents)):
+        raise ValueError('Adjustment guidance must not use symlinks')
+    return path
+
+
+def read(root, laser_id):
+    import json
+    path=location(root,laser_id)
+    raw=path.read_bytes() if path.exists() else b'{"schema_version":1,"knobs":{}}'
+    if len(raw)>65536:raise ValueError('Adjustment guidance is too large')
+    value=validate(json.loads(raw))
+    return dict(snapshot(value),laser_id=laser_id,
+                availability='configured' if value['knobs'] else 'not_configured')
+
+
+def current(runtime, laser_id):
+    # Establish scope, then read advice independently of the physical policy.
+    runtime.interface_repository.read('lasers',laser_id)
+    return read(runtime.root,laser_id)
+
+
+def for_job(directory, laser_id):
+    from ldcon.jobs.laser_live import laser_file
+    return read(root_from_laser_file(laser_file(directory,laser_id)),laser_id)
+
+
+def update(runtime, laser_id, data):
+    import fcntl
+    import os
+    from experiment_core.records import atomic_json
+    from ldcon.web.web_runtime import ConflictError
+    if not isinstance(data,dict) or set(data)!={'expected_revision','document'}:
+        raise ValueError('Expected revision and an advisory document')
+    document=validate(data['document'])
+    if len(__import__('json').dumps(document).encode())>65536:
+        raise ValueError('Adjustment guidance is too large')
+    with runtime.mutex:
+        runtime.interface_repository.read('lasers',laser_id)
+        path=location(runtime.root,laser_id);path.parent.mkdir(parents=True,exist_ok=True)
+        descriptor=os.open(path.with_suffix('.lock'),os.O_CREAT|os.O_RDWR|os.O_NOFOLLOW,0o600)
+        with os.fdopen(descriptor,'a') as stream:
+            fcntl.flock(stream,fcntl.LOCK_EX)
+            if current(runtime,laser_id)['revision']!=data['expected_revision']:
+                raise ConflictError('Adjustment advice changed; read it before saving')
+            atomic_json(path,document)
+        return current(runtime,laser_id)