"""Checkpointed CBB mutations with native evidence and no automatic replay.""" from dataclasses import asdict, dataclass, field, replace from datetime import datetime, timezone import json from pathlib import Path, PureWindowsPath import re from uuid import uuid4 from .library_lock import LibraryLock, LibraryBusy from .scoped_manifest import (ManifestScope, build_manifest, build_exclusive_library_manifest, comparison_rules, copy_verified, hash_file, scan_tree) @dataclass(frozen=True) class Capability: supported: bool reason: str @dataclass(frozen=True) class ManagementRequest: operation: str library: Path name: str partition: str = 'Logical-Physical' source: Path | None = None auto_verify: bool = True evidence_dir: Path = Path('management-evidence') top_level_block: str = '' timeout_seconds: float = 180 mapped_drive: str = '' mapped_remote_root: str = '' transaction_token: str = '' check_previous_release: bool = False @dataclass(frozen=True) class CatalogEntry: name: str partition: str engineering_identity: dict = field(default_factory=dict) @dataclass(frozen=True) class Catalog: library: Path flow: int entries: tuple[CatalogEntry, ...] safe_to_continue: bool = True @dataclass(frozen=True) class NativeOutcome: success: bool safe_to_continue: bool detail: str identity_matches: bool | None = None evidence_path: Path | None = None identity_proof: dict | None = None @dataclass(frozen=True) class ManagementResult: operation: str library: Path name: str partition: str source: Path | None auto_verify: bool stage: str status: str safe_to_continue: bool detail: str = '' evidence_path: Path | None = None release_proof: dict | None = None change_report: dict | None = None def validate_name(value): if (not value or value != value.strip() or value.endswith('.') or value in ('.', '..') or any(ord(c) < 32 or c in '<>:"/\\|?*' for c in value) or value.split('.')[0].upper() in {'CON', 'PRN', 'AUX', 'NUL', *(f'COM{i}' for i in range(1, 10)), *(f'LPT{i}' for i in range(1, 10))}): raise ValueError('CBB 名称/分区不是有效单一名称,禁止路径、控制字符或保留名称。') def source_project(source, top_level_block=''): """Require complete PRJ/PCB and self-contained engineering references.""" from .backup_recovery import _project_text source = Path(source).resolve(strict=True) if source.suffix.casefold() != '.prj' or not source.is_file(): raise ValueError('请选择完整工程的 PRJ 文件。') scan_tree(source.parent) # Reject reparse points, including file links. text = _project_text(source) roots = re.findall(r'^KEY RootBlock "([^"]+)"', text, re.M) if len(roots) != 1 or top_level_block and roots[0] != top_level_block: raise ValueError('工程顶层块不唯一或与输入不一致。') validate_name(roots[0]) def reference(path, key): values = re.findall(r'^KEY ' + re.escape(key) + r' "([^"]+)"', _project_text(path), re.M) if len(values) != 1 or PureWindowsPath(values[0]).is_absolute() or PureWindowsPath(values[0]).drive: raise ValueError(f'{key} 必须为唯一工程内相对引用。') resolved = (path.parent/values[0]).resolve() if not resolved.is_relative_to(source.parent): raise ValueError(f'{key} 越出来源工程。') return resolved pcb = reference(source, 'PCBDesignPath') if not pcb.is_file() or reference(pcb, 'ProjectFile') != source: raise ValueError('PCB 未引用所选来源工程。') from .maintenance_entry import maintenance_project_files for path in maintenance_project_files(source, pcb): if not path.is_file(): raise ValueError('工程缺少 PCB 工程配置。') # Healthy Expedition PCB projects can use Layout/LayoutDB.lyt without # declaring an independent iCDBDir. The schematic DB stays mandatory; # an explicitly declared PCB DB must still pass every reference check. if path != source and not re.search(r'^KEY iCDBDir\b', _project_text(path), re.M): continue db = reference(path, 'iCDBDir') if not (db/'icdb.dat').is_file(): raise ValueError('工程缺少原理图/PCB 数据库。') if not (pcb.parent/'Layout/LayoutDB.lyt').is_file(): raise ValueError('工程缺少布局数据库。') return source, pcb, roots[0] def engineering_identity(source): """Compare actual registered engineering bytes, not a name-only acknowledgment. Conservative until native normalization has an independently proven semantic comparison: changed database bytes cannot be claimed to match the source. """ source, pcb, top = source_project(source) from .backup_recovery import _project_text db = re.findall(r'^KEY iCDBDir "([^"]+)"', _project_text(source), re.M)[0] return {'top_level_block': top, 'schematic_sha256': hash_file(source.parent/db/'icdb.dat'), 'layout_sha256': hash_file(pcb.parent/'Layout/LayoutDB.lyt')} def _write_json(path, value): path = Path(path) pending = path.with_suffix('.pending') with pending.open('w', encoding='utf-8') as stream: json.dump(value, stream, ensure_ascii=False, default=str, indent=2) stream.flush() import os os.fsync(stream.fileno()) pending.replace(path) def unfinished_operations(root): results = [] for path in sorted(Path(root).glob('*/checkpoint.json')): try: record = json.loads(path.read_text(encoding='utf-8')) if (record.get('stage') != 'complete' or record.get('safe_to_continue') is False or record.get('status') == 'RECOVERY_REQUIRED'): results.append({**record, 'evidence_path': str(path)}) except (OSError, ValueError): results.append({'status': 'CHECKPOINT_UNREADABLE', 'evidence_path': str(path)}) return results def _may_have_mutated(record): prewrite = {'preflight', 'release_check', 'catalog_before', 'baseline', 'stage_source', 'prepare_identity'} history = record.get('history') return (record.get('stage') not in prewrite | {'complete'} or record.get('status') == 'RECOVERY_REQUIRED' or not isinstance(history, list) or not history or any(not isinstance(item, dict) or item.get('stage') not in prewrite for item in history)) def run_management(request, *, adapter=None, verifier=None, idle_check=None, progress=None, stop=None, version_prompt=None, write_admission=None): from .verify_runner import VerifyRequest, run_verify from .backup_recovery import _idle_check from contextlib import ExitStack from .operation_queue import check_active, native_channel, task_stop, remember_result stop = task_stop(stop) import pythoncom if adapter is None: from .native_management import NativeManagementAdapter adapter = NativeManagementAdapter() verifier = verifier or run_verify root = report = None native_idle_check = idle_check is None if native_idle_check: from .write_admission import WriteAdmission write_admission=write_admission or WriteAdmission(prompt=version_prompt,stop=stop) idle_check=lambda library,project,pcb:_idle_check(library,project,pcb, confirmation=write_admission,evidence=root,block=request.name) stage = 'preflight' history = [] mutated = uploaded = removed = False owner_safe = True release_proof = None original = None change_report = None def invoke(callback, *args): nonlocal owner_safe if stop is not None and stop.is_set(): raise InterruptedError('MANAGEMENT_CANCELLED: 已停止后续原生操作') with native_channel(): owner_safe = False try: result = callback(*args) except Exception as error: owner_safe = getattr(error, 'safe_to_continue', False) is True raise owner_safe = result.safe_to_continue return result def checkpoint(next_stage, **details): nonlocal stage stage = next_stage history.append({'stage': stage, 'time': datetime.now(timezone.utc).isoformat(), **details}) if report: _write_json(report, {**asdict(request), 'stage': stage, 'status': 'RUNNING', 'safe_to_continue': False, 'history': history, 'backup_policy': 'manual'}) if progress: progress({'stage': stage, 'block': request.name, 'operation': request.operation, **details}) def finish(status, detail='', safe=True): nonlocal change_report remember_result(ManagementResult(request.operation, request.library, request.name, request.partition, request.source, request.auto_verify, 'complete', status, safe, detail, report, release_proof, change_report)) if mutated and original is not None and change_report is None: change_report = {'status': 'UNCONFIRMED', 'scope': original['scope'], **comparison_rules(scope), 'unrelated_cbb_content_checked': False, 'detail': '原生会话尚未释放,未读取写后内容'} remember_result(ManagementResult(request.operation, request.library, request.name, request.partition, request.source, request.auto_verify, 'complete', status, safe, detail, report, release_proof, change_report)) if safe: try: after = build_exclusive_library_manifest(library_root, scope=scope, progress=progress) _write_json(root/'library-after-manifest.json', after) before_files, after_files = original['files'], after['files'] change_report.update(status='RECORDED', detail='目标工程及共享依赖的内容差分', added=sorted(after_files.keys()-before_files.keys()), deleted=sorted(before_files.keys()-after_files.keys()), modified=sorted(path for path in before_files.keys() & after_files.keys() if before_files[path] != after_files[path])) except Exception as error: change_report['detail'] = f'写后内容未确认:{error}' try: _write_json(root/'library-changes.json', change_report) except OSError as error: change_report.update(status='UNCONFIRMED', evidence_error=str(error), detail=f'变更记录保存失败:{error}') if change_report['status'] != 'RECORDED': detail = (detail+'\n'+change_report['detail']).strip() result = ManagementResult(request.operation, request.library, request.name, request.partition, request.source, request.auto_verify, 'complete', status, safe, detail, report, release_proof, change_report) remember_result(result) if report: try: _write_json(report, {**asdict(result), 'history': history, 'backup_policy': 'manual'}) except OSError as error: result = replace(result, detail=f'{detail}\n操作记录写入失败:{error}'.strip()) return remember_result(result) from .com_runtime import initialize_com, uninitialize_com initialized = initialize_com() try: if stop is not None and stop.is_set(): return finish('CANCELLED', '已取消,未启动原生管理操作') if hasattr(adapter, 'bind_stop'): adapter.bind_stop(stop) if request.operation not in ('add', 'update', 'remove'): raise ValueError('不支持的管理操作。') validate_name(request.name); validate_name(request.partition) from .network_path import absolute_preserving_drive library = absolute_preserving_drive(request.library) canonical_library = library.resolve(strict=True) library_root = canonical_library.parent if library.suffix.casefold() != '.lmc' or not library.is_file(): raise ValueError('中心库必须为现有 LMC 文件。') evidence = Path(request.evidence_dir).resolve() if evidence.is_relative_to(library_root) or library_root.is_relative_to(evidence): raise ValueError('操作记录与暂存目录必须位于目标中心库之外,且不能包含目标库。') capability = adapter.capabilities().get(request.operation, Capability(False, '未验证的原生接口')) if not capability.supported: return finish('UNSUPPORTED', capability.reason) unfinished_target = None for unfinished in unfinished_operations(evidence): if (unfinished.get('library') and Path(unfinished['library']).resolve() == canonical_library and _may_have_mutated(unfinished) and (not unfinished.get('name') or str(unfinished['name']).casefold() == request.name.casefold())): unfinished_target = unfinished break source = pcb = None if request.operation in ('add', 'update'): if request.source is None: raise ValueError('新增/更新需要完整来源工程。') if hasattr(adapter, 'validate_source'): adapter.validate_source(request) source, pcb, top = source_project(request.source, request.top_level_block) if (source.parent.is_relative_to(library_root) or library_root.is_relative_to(source.parent) or evidence.is_relative_to(source.parent) or source.parent.is_relative_to(evidence)): raise ValueError('来源工程、目标库与操作证据必须使用独立目录。') root = evidence/('management-' + uuid4().hex) root.mkdir(parents=True, exist_ok=False) report = root/'checkpoint.json' checkpoint('release_check') from .library_lock import recheck_previous_release release_proof = recheck_previous_release(library, root/'previous-release', block_name=request.name, required=request.check_previous_release or bool(unfinished_target and unfinished_target.get('safe_to_continue') is not True), progress=progress, stop=stop) if release_proof is not None: checkpoint('release_check', release_proof=release_proof) if unfinished_target: return finish('BLOCKED', f'存在未完成/需恢复任务,禁止自动重放:{unfinished_target["evidence_path"]}') if hasattr(adapter, 'bind_library_mapping'): adapter.bind_library_mapping(request.mapped_drive, request.mapped_remote_root) if hasattr(adapter,'bind_write_admission'): adapter.bind_write_admission(write_admission if native_idle_check else None) check_active() with LibraryLock(library, block_name=request.name, safe_to_release=lambda: owner_safe or ( callable(getattr(adapter, 'release_confirmed', None)) and adapter.release_confirmed(library))), ExitStack() as native_stack: work = library.parent/'ReusableBlocksLP'/request.name/'Work' target_project, target_pcb = work/(request.name+'.prj'), work/'PCB/pcb.pcb' if request.operation != 'add': # Read actual engineering references when available; fallback # paths still permit removal of catalog entries missing Work. from .verify_runner import preflight try: target_project, target_pcb = preflight(VerifyRequest(library, request.name, root)) except ValueError: pass idle_check(library, target_project, target_pcb) if source: idle_check(library, source, pcb) checkpoint('catalog_before') before = invoke(adapter.catalog, library, root/'before') owner_safe = before.safe_to_continue if not owner_safe or Path(before.library).resolve() != canonical_library or before.flow != 1: return finish('BLOCKED', '原生目录身份/流程或所有者释放未确认。仅支持已验证 DxDesigner 流程。', owner_safe) same_name = [entry for entry in before.entries if entry.name.casefold() == request.name.casefold()] matches = [entry for entry in same_name if entry.partition == request.partition and entry.name == request.name] if request.operation == 'add' and same_name: return finish('UPLOAD_FAILED', '同名 CBB 已存在;新增禁止覆盖,请使用明确的同名更新。') if request.operation != 'add' and len(matches) != 1: return finish('BLOCKED', '目标名称和分区必须与原生目录唯一匹配。') if hasattr(adapter, 'preflight'): adapter.preflight(request, before) # Native/project owners must be idle before snapshot or mutation. idle_check(library, target_project, target_pcb) scope = ManifestScope.library(request.name, library.name) checkpoint('baseline') original = build_exclusive_library_manifest(library_root, scope=scope, progress=progress) _write_json(root/'library-baseline-manifest.json', original) staged = request identity = None if source: checkpoint('stage_source') source_manifest = copy_verified(source.parent, root/'source', progress=progress) _write_json(root/'source-manifest.json', source_manifest) staged = replace(request, source=root/'source'/source.name, top_level_block=top) identity = engineering_identity(staged.source) if build_manifest(source.parent) != source_manifest: raise OSError('来源工程在暂存期间变化。') if source and hasattr(adapter, 'prepare_add_transaction'): checkpoint('prepare_identity') owner_safe = False staged, proof = adapter.prepare_add_transaction(staged, root, original_source=source) owner_safe = proof.safe_to_continue if not owner_safe or proof.identity is None: return finish('UPLOAD_FAILED', proof.detail, owner_safe) identity = proof.identity if build_exclusive_library_manifest(library_root, scope=scope, progress=progress) != original: raise OSError('内容基线记录后中心库发生变化,停止写入。') if request.operation in ('remove', 'update'): if stop is not None and stop.is_set(): return finish('CANCELLED', '已取消,未开始移除', owner_safe) native_stack.enter_context(native_channel()) checkpoint('native_remove') mutated = True; owner_safe = False native = invoke(adapter.remove, request, root/'remove') owner_safe = native.safe_to_continue if not owner_safe or not native.success: return finish('RECOVERY_REQUIRED', native.detail, owner_safe) idle_check(library, target_project, target_pcb) after = invoke(adapter.catalog, library, root/'after-remove') owner_safe = after.safe_to_continue if (not owner_safe or Path(after.library).resolve() != canonical_library or after.flow != 1 or any(e.name == request.name and e.partition == request.partition for e in after.entries)): return finish('RECOVERY_REQUIRED', '原生移除后目录未确认目标缺失。', owner_safe) removed = True checkpoint('removed') if request.operation == 'remove': return finish('REMOVED', '已由原生操作移除,重新读取目录确认不存在;应用未创建备份。') if stop is not None and stop.is_set(): return finish('RECOVERY_REQUIRED' if mutated else 'CANCELLED', '已停止后续导入;已发生的原生变更需要核对', owner_safe) if not removed: native_stack.enter_context(native_channel()) checkpoint('native_add') mutated = True; owner_safe = False native = invoke(adapter.add, staged, root/'add') owner_safe = native.safe_to_continue if not owner_safe or not native.success: return finish('RECOVERY_REQUIRED' if removed or not owner_safe else 'UPLOAD_FAILED', native.detail, owner_safe) idle_check(library, target_project, target_pcb) after = invoke(adapter.catalog, library, root/'after-add') owner_safe = after.safe_to_continue matches = [entry for entry in after.entries if entry.name == request.name and entry.partition == request.partition] expected_proof, registered_proof = identity, native.identity_proof if isinstance(identity, dict) and identity.get('policy') == 'mentor795-import-assets-v1': expected_proof = {key: value for key, value in identity.items() if key != 'assets'} registered_proof = ({key: value for key, value in registered_proof.items() if key != 'assets'} if isinstance(registered_proof, dict) else None) # Library Manager may name the imported top block after the CBB. if registered_proof is not None and registered_proof.get('top_level_block') == request.name: expected_proof['top_level_block'] = request.name proof_matches = (native.identity_matches is True and registered_proof == expected_proof if hasattr(adapter, 'prepare_add_transaction') else len(matches) == 1 and matches[0].engineering_identity == identity) if (not owner_safe or Path(after.library).resolve() != canonical_library or after.flow != 1 or len(matches) != 1 or not proof_matches): return finish('RECOVERY_REQUIRED', '原生新增后名称、分区或工程关联未确认一致。\n'+native.detail, owner_safe) uploaded = True checkpoint('uploaded') native_stack.close() if not request.auto_verify: return finish('UPLOADED', '上传已确认;本批次未启用自动校验。\n'+native.detail) # Adapter catalog cannot return until its exact native owner exits. checkpoint('verify') owner_safe = False options = {'version_prompt': version_prompt} if version_prompt is not None else {} verified = verifier(VerifyRequest(library, request.name, root/'verify', mapped_drive=request.mapped_drive, mapped_remote_root=request.mapped_remote_root), progress=progress, stop=stop, **options) owner_safe = verified.safe_to_continue checkpoint('verified', verification=asdict(verified)) good = verified.status == 'PASS' and verified.library_flag == 'GREEN' and owner_safe return finish('UPLOADED_VERIFIED' if good else 'UPLOADED_VERIFY_FAILED', '\n'.join(filter(None, (native.detail, verified.stderr or verified.library_flag_detail))), owner_safe) except Exception as error: from .write_admission import WriteAdmissionDeclined if isinstance(error,WriteAdmissionDeclined): return finish('RECOVERY_REQUIRED' if mutated else 'CANCELLED' if error.decision=='cancel' else 'SKIPPED',str(error),owner_safe) if uploaded: return finish('UPLOADED_VERIFY_FAILED', str(error), owner_safe) status = 'RECOVERY_REQUIRED' if mutated else ('UPLOAD_FAILED' if request.operation in ('add', 'update') else 'BLOCKED') # Bad input is never described as a native upload attempt. if root is None and isinstance(error, ValueError): status = 'BLOCKED' if stage == 'release_check' and not mutated: status = 'BLOCKED' return finish(status, str(error), owner_safe) finally: uninitialize_com(initialized) def run_management_batch(requests, *, stop=None, progress=None, item_executor=None, context=None, **kwargs): from threading import Event from .write_admission import WriteAdmission from .operation_queue import QueueCancelled, TaskHandoff, request_library_keys, remember_result if context is not None: stop = stop if stop is not None else context.stop progress = context.guard_callback(progress) if progress else None if stop is None: stop = Event() kwargs.setdefault('write_admission',WriteAdmission(prompt=kwargs.get('version_prompt'),stop=stop)) results = [] retained_libraries = set() cancelled = False for request in requests: keys = request_library_keys(request, context) stopped = cancelled or stop.is_set() or context is not None and context.stop.is_set() if stopped or keys.intersection(retained_libraries): result = ManagementResult(request.operation, request.library, request.name, request.partition, request.source, request.auto_verify, 'complete', 'SKIPPED', True, '队列已停止,未操作此 CBB' if stopped else '同库原生会话尚未释放,未启动新的写入') results.append(result) if progress: progress({'stage': result.status, 'block': result.name, 'detail': result.detail}) continue def action(): result = run_management(request, progress=progress, stop=stop, **kwargs) remember_result(result) if not result.safe_to_continue: from .operation_lifecycle import recheck_failed_release result = recheck_failed_release(request.library, request.name, result, stop=stop) return result try: result = item_executor(request, action) if item_executor is not None else action() except QueueCancelled as error: known = error.result if isinstance(error, TaskHandoff) else None if isinstance(known, ManagementResult): result = replace(known, safe_to_continue=False, status='RECOVERY_REQUIRED' if known.status in ('PASS', 'UPLOADED', 'UPLOADED_VERIFIED', 'REMOVED') else known.status, release_proof=dict(status='RELEASE_PENDING', lease_state='PENDING', resource_scope=error.scope, previous_release_proof=known.release_proof)) else: result = ManagementResult(request.operation, request.library, request.name, request.partition, request.source, request.auto_verify, 'complete', 'TIMEOUT' if isinstance(error, TaskHandoff) and not error.cancelled else 'CANCELLED', not isinstance(error, TaskHandoff), str(error)) results.append(result) if progress: progress({'stage': result.status, 'block': result.name, 'detail': result.detail, 'evidence_path': str(result.evidence_path or '')}) if not result.safe_to_continue: retained_libraries.update(keys) if result.status == 'CANCELLED': cancelled = True return results