chronaxis 0.1.0.dev0__py3-none-any.whl

chronaxis/legacy/disjunction.py

@@ -0,0 +1,79 @@
+"""声明按本条原解码方向值分正负桶，并保存不经转换的选择追溯。
+
+LegacyDisjunction给出已绑定别名、positive/negative桶及固定raw_decoded-v1策略。
+运行层须核同一完整消息定位，从当前decoded字典直接取方向原值，不能施加
+SignalDefinition的scale、offset、direction_factor或TTL，也不能补前一次值。
+原生True按正值、False按零；缺字段、非有限值和未选桶的跳过由运行层决定，
+本模块不执行分类、表达式、累计或数值转换。
+
+LegacyDisjunctionTrace保存冻结选择器、原field定位、原生方向值和SourceRef。
+None明确表示方向字段缺失；NaN/Inf保留原诊断，不改成零或字符串。模型只核
+结构，不声称来自真实消息、文件EOF或旧ChrgInfo整条调用链。配置和返回追溯
+由调用方拥有；本模块不创建预算、I/O、缓存或NumPy依赖。
+"""
+
+# 两端共享冻结选择器和追溯，不在计划、结果和运行层各造一套可变字典。
+from dataclasses import dataclass
+
+from ..core.models import SourceRef
+from ..core.validation import require_identifier, require_text
+
+
+@dataclass(frozen=True)
+class LegacyDisjunction:
+    """选择同条消息的原数值方向桶，不修改表达式贡献的正负号。
+
+    signal是分析别名，原字段和完整消息定位仍由当前绑定解析；bucket只允许
+    positive/negative。该声明不自行拆分指标，也不证明方向在表达式依赖中。
+    """
+
+    signal: str  # 已绑定简单别名，可不出现在表达式中。
+    bucket: str  # positive或negative，各指标独立累计。
+    value_policy: str = 'raw_decoded-v1'  # 只看原decoded值，不施转换或保持。
+
+    def __post_init__(self) -> None:
+        """校验安全别名和固定桶/取值策略，不解析来源或输入值。
+
+        参数: 无，读取三个冻结字段。返回: None，保原生文本原样。
+        异常: TypeError为非原生文本；ValueError为别名、桶或策略不支持。
+        """
+        # 不按truthiness或str隐式转换选桶，避免配置拼错后悄悄进入另一种策略。
+        if type(self.signal) is not str or type(self.bucket) is not str or type(self.value_policy) is not str:
+            raise TypeError('disjunction别名、桶和value_policy需要原生str')
+        require_identifier(self.signal, 'disjunction.signal')
+        if self.bucket not in ('positive', 'negative'):
+            raise ValueError('disjunction.bucket仅支持positive或negative')
+        if self.value_policy != 'raw_decoded-v1':
+            raise ValueError('disjunction.value_policy仅支持raw_decoded-v1')
+
+
+@dataclass(frozen=True)
+class LegacyDisjunctionTrace:
+    """保存本次方向的原定位和值，结构冻结但不假造真实读取证明。
+
+    raw_value保int/float/bool原类型，None只表示明确缺字段；非有限float不在
+    模型层改写或拒绝。source_ref原对象保持，实际CAN逐序身份由运行/结果层核。
+    """
+
+    selection: LegacyDisjunction  # 实际指标使用的同一选择器。
+    field: str  # 原SignalDefinition.field，CAN路径为规范六项定位。
+    raw_value: int | float | bool | None  # 未归一化方向值；None为缺失。
+    source_ref: SourceRef  # 同条原消息的真实来源引用。
+
+    def __post_init__(self) -> None:
+        """核选择器、原字段、原生值及引用一致性，不作数值强制转换。
+
+        参数: 无，读取冻结追溯字段。返回: None；保NaN/Inf、负零和原bool。
+        异常: TypeError为非模型/原生数值；ValueError为原字段与引用不一致。
+        """
+        # 选择器必须已由共享模型校验，字段全文保留，不从别名反猜原字典键。
+        if type(self.selection) is not LegacyDisjunction or type(self.field) is not str:
+            raise TypeError('disjunction追溯需要LegacyDisjunction及原生field文本')
+        require_text(self.field, 'disjunction.field')
+        # None不代表零或无效浮点；数值原类型限定，拒绝str、enum和NumPy scalar。
+        if self.raw_value is not None and type(self.raw_value) not in (int, float, bool):
+            raise TypeError('disjunction原值需要原生int/float/bool或明确缺失None')
+        if not isinstance(self.source_ref, SourceRef):
+            raise TypeError('disjunction追溯需要SourceRef')
+        if self.source_ref.field != self.field:
+            raise ValueError('disjunction原field与来源引用不一致')

chronaxis/legacy/export_worker.py

@@ -0,0 +1,147 @@
+"""在独立spawn子进程按单次PUT许可调用冻结的原BLF写出链。
+
+输入为有界INIT/PUT/FINISH JSON bytes，输出同次READY、逐帧ACK和完成候选。
+INIT才核三份vendor及锁定依赖，独占取得新输出文件，再原样调用一次
+build_writer(str(path),'blf')。每PUT完整恢复同一LegacyRawFrame公开字段并
+构造can.Message，原writer.on_message_received只调用一次，不读源CAN或DBC。
+FINISH仅在原stop成功后发送完成候选；父仍须核真实子退出、句柄及费用收尾。
+
+本模块复用CAN读取协议的有界JSON、错误摘要和vendor加载函数，不修改或继承其read
+生命周期。失败保有限远端事实并非零退出，finally只对尚未尝试stop的writer调用
+一次原stop；失败的stop不被静默重试或改写。实际子退出回收未公开旧FD，不能
+据父RAM账本声称旧库、压缩缓存或整进程RSS受限。产物保留，不自动删除失败文件。
+"""
+
+# 模块导入不加载CAN库或打开输出；只有有效INIT之后才进入原样vendor。
+from importlib import metadata
+import os
+from pathlib import Path
+import platform
+from .records import PROFILE_ID, frame_from_dict
+from .worker import VENDOR_SHA256, _exact, _load_vendor, _receive, _report_error, _send
+
+
+WRITE_DEPENDENCIES = {'python-can': '4.6.1', 'cantools': '39.4.3', 'natsort': '8.4.0'}
+
+
+def _output(packet):
+    """检查唯一INIT及新输出路径，不猜格式或覆盖已有文件。
+
+    参数: packet为已通过严格JSON边界的dict。返回: resolved新BLF Path。
+    异常: TypeError/ValueError为字段、版本、profile、后缀或受保护路径；
+        FileExistsError为已有目标，FileNotFoundError为尚无控制器工作根。
+    副作用: 仅检查文件系统；真正独占创建仍在writer建立之前执行。
+    """
+    _exact(packet, ('op', 'version', 'profile', 'path'))
+    if (packet['op'] != 'init' or type(packet['version']) is not int or packet['version'] != 1
+            or type(packet['profile']) is not str or packet['profile'] != PROFILE_ID
+            or type(packet['path']) is not str):
+        raise ValueError('原CAN写出需要init/version1及固定profile路径')
+    path = Path(packet['path']).resolve()
+    # resolve先于保护检查，不能经目录链接把新产物写进历史快照。
+    if path.suffix.lower() != '.blf' or any(part.casefold() == 'refprojects' for part in path.parts):
+        raise ValueError('原CAN写出仅支持RefProjects之外的新BLF')
+    if path.exists():
+        raise FileExistsError(path)
+    if not path.parent.is_dir():
+        raise FileNotFoundError(path.parent)
+    return path
+
+
+def _message(can, frame):
+    """把全部原公开写出字段交给原can.Message构造，不添加check或归一化参数。
+
+    参数: can为原vendor实际导入的模块；frame为已校验LegacyRawFrame。
+    返回: 新can.Message，timestamp/data/DLC及全部标志保持原参数。
+    异常: 原can.Message构造错误；不以新层猜测修正旧格式限制。
+    """
+    if frame.is_rx is None:
+        raise ValueError('BLF写出需要收发方向is_rx')
+    return can.Message(timestamp=frame.timestamp, arbitration_id=frame.arbitration_id,
+        is_extended_id=frame.is_extended_id, is_remote_frame=frame.is_remote_frame,
+        is_error_frame=frame.is_error_frame, channel=frame.channel, dlc=frame.dlc,
+        data=frame.data, is_fd=frame.is_fd, is_rx=frame.is_rx,
+        bitrate_switch=frame.bitrate_switch, error_state_indicator=frame.error_state_indicator)
+
+
+def worker_main(connection):
+    """作为真实spawn目标，按INIT/单PUT/FINISH顺序调用唯一原writer。
+
+    参数: connection为父传来的实际duplex端点。返回: 原stop成功并发送候选后None。
+    异常: 原错误尽力发送有限ERROR，最终SystemExit(1)；管道清理也不能伪成正常退出。
+    副作用: 独占创建一个新BLF、一次build_writer、每许可一次on_message_received，
+        至多一次stop；不读取输入CAN/DBC，不调parse或为ACK额外写帧。
+    """
+    writer = claim = failure = request_id = None
+    phase, frame_count, stop_attempted = 'init', 0, False
+    try:
+        path = _output(_receive(connection))
+        phase = 'vendor'
+        _, processor, hashes = _load_vendor()
+        versions = {'python': platform.python_version(),
+            **{name: metadata.version(name) for name in WRITE_DEPENDENCIES}}
+        if any(versions[name] != expected for name, expected in WRITE_DEPENDENCIES.items()):
+            raise ValueError('原CAN writer依赖不符合已验证profile')
+        # xb原子拒绝已有文件；原build_writer只重开本child刚取得的自有空产物。
+        phase = 'claim'
+        claim = path.open('xb')
+        claim.close()
+        claim = None
+        phase = 'build_writer'
+        writer, actual_path = processor.build_writer(str(path), 'blf')
+        if actual_path != str(path):
+            raise ValueError('原build_writer返回的路径与本次目标不一致')
+        _send(connection, {'op': 'ready', 'version': 1, 'profile': PROFILE_ID,
+            'worker_pid': os.getpid(), 'dependency_versions': versions, 'vendor_sha256': hashes})
+        # 仅收到一条PUT后写一帧；下一许可前不保留当前消息或构造额外帧。
+        while True:
+            phase, request_id = 'control', None
+            packet = _receive(connection)
+            if packet.get('op') == 'finish':
+                _exact(packet, ('op', 'frame_count'))
+                if type(packet['frame_count']) is not int or packet['frame_count'] != frame_count:
+                    raise ValueError('FINISH帧数与本次原writer确认数量不符')
+                phase, stop_attempted = 'stop', True
+                writer.stop()
+                writer = None
+                _send(connection, {'op': 'finished', 'frame_count': frame_count})
+                break
+            _exact(packet, ('op', 'request_id', 'frame'))
+            candidate = packet['request_id']
+            request_id = candidate if type(candidate) is int and candidate >= 0 else None
+            if packet['op'] != 'put' or request_id is None or request_id != frame_count:
+                raise ValueError('PUT许可必须从0严格连续且为原生int')
+            phase = 'frame'
+            frame = frame_from_dict(packet['frame'])
+            message = _message(processor.can, frame)
+            phase = 'write'
+            writer.on_message_received(message)
+            frame_count += 1
+            _send(connection, {'op': 'ack', 'request_id': request_id, 'frame_count': frame_count})
+            frame = message = None
+    except BaseException as exc:
+        failure = exc
+        _report_error(connection, exc, phase, request_id)
+    finally:
+        # 失败或父提前断管只结束已有writer；不重发PUT，不重试已经失败的原stop。
+        if writer is not None and not stop_attempted:
+            try:
+                stop_attempted = True
+                writer.stop()
+            except BaseException as cleanup:
+                if failure is None:
+                    failure = cleanup
+                    _report_error(connection, cleanup, 'stop', request_id)
+                else:
+                    failure.add_note('原writer.stop附加失败: ' + type(cleanup).__name__)
+        for resource, label in ((claim, '新文件声明句柄'), (connection, '子连接')):
+            if resource is not None:
+                try:
+                    resource.close()
+                except BaseException as cleanup:
+                    if failure is None:
+                        failure = cleanup
+                    else:
+                        failure.add_note(label + '关闭附加失败: ' + type(cleanup).__name__)
+    if failure is not None:
+        raise SystemExit(1)

chronaxis/legacy/export_write.py

@@ -0,0 +1,378 @@
+"""在独立进程把原始帧交给冻结旧BLF writer，真实收尾后才确认完成。
+
+LegacyCANProcessWrite接收共享ResourceBudget和新输出路径，构造只计有限状态、
+核路径而不spawn或执行旧IO。start实际加载锁定依赖/vendor并创建原writer；每次
+write只发一个有界PUT，收到同序ACK才承认该帧，FINISH没有额外帧写入许可。
+finish须原stop成功、实际exitcode0、所有Pipe/Process及自有RAM清完，并核输出
+stat不超过本writer直接预留，才公开finished。提前close、失败或取消不能伪完成。
+
+进程/管道/wire/READY/当前帧分别先付并记真实槽；释放前后取消可重试，最高
+can_process_write_cleanup_owner始终指向同一实际owner。磁盘在start前保守预留
+65536 bytes、每PUT前4096 bytes，累计保留且不倒扣；不凭共享余额差接管费用。
+原BLF压缩、库内部缓存及整进程RSS未测，也不承诺文件与源BLF字节一致。
+这里只写控制器新工作根下的新文件，不读源CAN/DBC，不修改原read/records/vendor。
+"""
+
+# 仅导入标准库和既有轻量协议；真实旧模块与CAN依赖留在独立spawn子内。
+import multiprocessing
+from pathlib import Path
+import platform
+from .export_worker import WRITE_DEPENDENCIES, worker_main
+from .process_read import RemoteLegacyError, _freeze, _wire_metadata_bytes
+from .records import MAX_WIRE_BYTES, PROFILE_ID, LegacyRawFrame, decode_packet, encode_packet, frame_to_dict
+from .worker import VENDOR_SHA256
+from ..results.budget import ResourceBudget
+from ..results.errors import AnalysisError, ResultClosedError
+from ..results.spool import _cleanup_owner, _release_owned_ram, _reserve_owned_ram
+
+
+class LegacyCANWriteError(AnalysisError):
+    """报告新外部writer协议或原子进程失败；远端原错仅作为明确事实cause。"""
+
+
+class LegacyCANProcessWrite:
+    """拥有一个真实writer子进程与独立费用，借用账本但不关闭其他owner。
+
+    _waiting阻止第二个在途控制包；_process_stopped只由实际exitcode确认。
+    _closed表示自有责任结束，_finished还须本次FINISH及输出大小验证成功。
+    输出路径和累计spool事实在close后保留，READY借引用在close时解除。
+    """
+
+    def __init__(self, budget, output_path):
+        """预约固定协调状态并检查新路径，不启动进程或创建目标文件。
+
+        参数: budget为借用ResourceBudget；output_path为控制器已有新工作根下的
+            str/Path目标，须为.blf后缀，不能已存在或位于RefProjects。
+        返回: 未启动的独立writer。异常: 类型、路径或预算原错；未返回构造的持续
+            清理失败附can_process_write_cleanup_owner，同对象恢复后close。
+        """
+        if not isinstance(budget, ResourceBudget) or not isinstance(output_path, (str, Path)):
+            raise TypeError('原CAN写出需要ResourceBudget和新输出路径')
+        # 所有真实资源和交易槽先安装；后续任何预算取消都有本owner可达责任。
+        self._budget, self._output_path = budget, None
+        self._connection = self._child_connection = self._process = None
+        self._worker_pid = self._exit_code = self._metadata = self._pending_reply = self._frame = None
+        self._fixed_cost = self._wire_cost = self._pipe_cost = self._process_cost = 0
+        self._metadata_cost = self._frame_cost = self._held_cost = self._spool_bytes = 0
+        self._puts_issued = self._acks_received = self._frames_written = 0
+        self._actual_bytes = None
+        self._process_stopped = self._waiting = self._started = self._finish_received = False
+        self._closed = self._closing = self._failed = self._finished = False
+        try:
+            _reserve_owned_ram(self, 1048576, '_fixed_cost')
+            if len(str(output_path)) > 8192:
+                raise ValueError('原CAN输出路径超过本层有限能力')
+            self._output_path = Path(output_path).resolve()
+            self._check_path()
+        except BaseException as exc:
+            self._failed = True
+            _cleanup_owner(self, exc, 'can_process_write_cleanup_owner', '原CAN writer构造')
+            raise
+
+    def _check_path(self):
+        """拒绝已有/受保护目标及缺少的新工作根，不创建目录或文件。
+
+        参数: 无，使用已保存resolved路径。返回: None。
+        异常: ValueError为后缀/RefProjects，FileExistsError为已有目标，
+            FileNotFoundError为父目录不存在；真正独占创建由child执行。
+        """
+        path = self._output_path
+        if path.suffix.lower() != '.blf' or any(part.casefold() == 'refprojects' for part in path.parts):
+            raise ValueError('原CAN写出仅支持RefProjects之外的新BLF')
+        if path.exists():
+            raise FileExistsError(path)
+        if not path.parent.is_dir():
+            raise FileNotFoundError(path.parent)
+
+    @property
+    def output_path(self):
+        """读取实际新目标。参数: 无。返回: resolved Path或构造前失败时None。异常: 无。"""
+        return self._output_path
+
+    @property
+    def closed(self):
+        """读取全部自有责任关闭状态。参数: 无。返回: bool。异常: 无。"""
+        return self._closed
+
+    @property
+    def finished(self):
+        """读取完整FINISH事实。参数: 无。返回: bool，失败/提前close为False。异常: 无。"""
+        return self._finished
+
+    @property
+    def failed(self):
+        """读取失败诊断状态。参数: 无。返回: bool。异常: 无。"""
+        return self._failed
+
+    @property
+    def worker_pid(self):
+        """读取本次真实启动PID。参数: 无。返回: int或None，关闭后保留。异常: 无。"""
+        return self._worker_pid
+
+    @property
+    def spool_bytes(self):
+        """读取本writer直接累计磁盘预留。参数: 无。返回: int bytes，不倒扣。异常: 无。"""
+        return self._spool_bytes
+
+    @property
+    def counters(self):
+        """区分PUT尝试、合法ACK和本父确认帧数，不用断管推断写入成功。
+
+        参数: 无。返回: 新dict，取消时puts_issued仅为许可尝试上界。
+        异常: 原小容器分配错误；不向child发送额外控制或写入。
+        """
+        return {'puts_issued': self._puts_issued, 'acks_received': self._acks_received,
+            'frames_written': self._frames_written}
+
+    @property
+    def metadata(self):
+        """借读同次READY事实，不隐式start。参数: 无。返回: 冻结映射，借用至close。
+        异常: ResultClosedError为关闭/失败，RuntimeError为尚无实际READY。
+        """
+        self._require_open()
+        if self._metadata is None:
+            raise RuntimeError('原CAN writer尚未READY')
+        return self._metadata
+
+    def _require_open(self):
+        """阻止关闭或失败后继续许可。参数: 无。返回: None。
+        异常: ResultClosedError为不可推进；close仍可重复恢复。
+        """
+        if self._closed or self._closing or self._failed:
+            raise ResultClosedError('原CAN writer已关闭、清理中或失败')
+
+    def _reserve_spool(self, amount):
+        """逐笔记录本次直接磁盘预留，回调执行后取消也保留真实归属。
+
+        参数: amount为非负int bytes。返回: None。异常: 原配额/取消，文件及累计值不倒扣。
+        """
+        before = self._budget.spool_bytes
+        try:
+            self._budget.reserve_spool(amount)
+        finally:
+            if self._budget.spool_bytes == before + amount:
+                self._spool_bytes += amount
+
+    def _fail(self, exc, phase):
+        """以实际父错误为主收尾，普通底层错误包装并保cause及最高恢复owner。
+
+        参数: exc为原异常；phase为有限业务位置。返回: 不返回。
+        异常: KI/SystemExit/AnalysisError原对象，其余LegacyCANWriteError保原cause；
+            两次有限cleanup副错只附note，绝不伪称写出完成。
+        """
+        self._failed = True
+        failure = exc if isinstance(exc, (KeyboardInterrupt, SystemExit, AnalysisError)) else LegacyCANWriteError(
+            '原CAN writer' + phase + '失败')
+        _cleanup_owner(self, failure, 'can_process_write_cleanup_owner', '原CAN writer')
+        if failure is exc:
+            raise failure
+        raise failure from exc
+
+    def start(self):
+        """实际创建独立spawn及原writer，READY不包含任何帧许可。
+
+        参数: 无。返回: self，重复成功调用不重建或重复预留。
+        异常: 路径/依赖/管道/协议/配额/预算或父原取消，最高owner按实际槽可恢复。
+        """
+        self._require_open()
+        if self._started:
+            return self
+        try:
+            self._check_path()
+            # 磁盘容量在spawn/原build_writer前预留，空BLF也保65536而非事后认领。
+            self._reserve_spool(65536)
+            _reserve_owned_ram(self, 128 * MAX_WIRE_BYTES, '_wire_cost')
+            _reserve_owned_ram(self, 65536, '_pipe_cost')
+            context = multiprocessing.get_context('spawn')
+            self._connection, self._child_connection = context.Pipe(duplex=True)
+            _reserve_owned_ram(self, 65536, '_process_cost')
+            self._process = context.Process(target=worker_main, args=(self._child_connection,),
+                name='chronaxis-legacy-can-export')
+            try:
+                self._process.start()
+            finally:
+                self._worker_pid = self._process.pid
+            self._close_connection('_child_connection')
+            reply = self._exchange({'op': 'init', 'version': 1, 'profile': PROFILE_ID,
+                'path': str(self._output_path)})
+            self._check_ready(reply)
+            _reserve_owned_ram(self, 4096 + 16 * _wire_metadata_bytes(reply), '_metadata_cost')
+            self._metadata = _freeze(reply)
+            self._pending_reply = None
+            self._started = True
+            return self
+        except BaseException as exc:
+            self._fail(exc, '初始化')
+
+    def _check_ready(self, packet):
+        """核同次实际PID及锁定依赖/vendor，不接受bool伪版本或自称READY。
+
+        参数: packet为decode_packet得到的dict。返回: None。
+        异常: LegacyCANWriteError为结构/类型/profile/PID/版本/摘要不符。
+        """
+        if (set(packet) != {'op', 'version', 'profile', 'worker_pid', 'dependency_versions', 'vendor_sha256'}
+                or packet.get('op') != 'ready' or type(packet.get('version')) is not int or packet['version'] != 1
+                or type(packet.get('profile')) is not str or packet['profile'] != PROFILE_ID
+                or type(packet.get('worker_pid')) is not int or packet['worker_pid'] != self._worker_pid
+                or packet['dependency_versions'] != {'python': platform.python_version(), **WRITE_DEPENDENCIES}
+                or packet['vendor_sha256'] != VENDOR_SHA256):
+            raise LegacyCANWriteError('原CAN writer READY身份、版本、实际PID或vendor不符')
+
+    def _exchange(self, packet):
+        """同步交换唯一控制包，禁止第二个在途PUT或把子退出当成ACK。
+
+        参数: packet为有界控制dict。返回: 严格JSON dict。
+        异常: 父原取消/管道/编码错误或LegacyCANWriteError；远端失败以明确
+            RemoteLegacyError事实为cause，不能声称跨进程保留异常对象身份。
+        """
+        if self._connection is None or self._waiting:
+            raise LegacyCANWriteError('原CAN writer连接不可用或已有在途许可')
+        payload = encode_packet(packet)
+        self._waiting = True
+        self._connection.send_bytes(payload)
+        while not self._connection.poll(0.05):
+            if self._process is not None and self._process.exitcode is not None:
+                raise LegacyCANWriteError('原CAN writer未交付完整回应便退出')
+        self._pending_reply = self._connection.recv_bytes(MAX_WIRE_BYTES)
+        reply = decode_packet(self._pending_reply)
+        self._waiting = False
+        if reply.get('op') == 'error':
+            facts = reply.get('error')
+            if (set(reply) != {'op', 'request_id', 'phase', 'error'}
+                    or type(reply.get('phase')) is not str
+                    or reply.get('request_id') is not None and type(reply.get('request_id')) is not int
+                    or reply.get('request_id') != packet.get('request_id')
+                    or type(facts) is not dict or set(facts) != {'module', 'type', 'message', 'traceback', 'notes'}
+                    or any(type(facts[key]) is not str for key in ('module', 'type', 'message', 'traceback'))
+                    or type(facts['notes']) is not list or any(type(note) is not str for note in facts['notes'])):
+                raise LegacyCANWriteError('原CAN writer远端错误包缺少明确事实或请求不符')
+            remote = RemoteLegacyError(facts, reply['phase'], reply['request_id'])
+            raise LegacyCANWriteError('原CAN writer子进程失败') from remote
+        return reply
+
+    def write(self, frame):
+        """完整发送一个原始帧并等唯一ACK，不缓存后继或按ID筛帧。
+
+        参数: frame为原生LegacyRawFrame，保全部公开字段及原浮点timestamp。
+        返回: None，合法ACK后counters增加；无额外on_message_received。
+        异常: TypeError为非原模型；原预算/磁盘/取消或writer/协议失败，之后只能close。
+        """
+        self._require_open()
+        if type(frame) is not LegacyRawFrame:
+            raise TypeError('原CAN writer.write需要LegacyRawFrame')
+        if frame.is_rx is None:
+            raise ValueError('BLF写出需要收发方向is_rx')
+        try:
+            self.start()
+            # 当前记录、hex和wire容器均在复制前付款；只有本owner持有时才保留该槽。
+            _reserve_owned_ram(self, 4259840, '_frame_cost')
+            self._frame = frame
+            self._reserve_spool(4096)
+            request_id = self._frames_written
+            self._puts_issued += 1
+            reply = self._exchange({'op': 'put', 'request_id': request_id, 'frame': frame_to_dict(frame)})
+            if (set(reply) != {'op', 'request_id', 'frame_count'} or reply.get('op') != 'ack'
+                    or type(reply.get('request_id')) is not int or reply['request_id'] != request_id
+                    or type(reply.get('frame_count')) is not int or reply['frame_count'] != request_id + 1):
+                raise LegacyCANWriteError('原CAN writer ACK不属于本次唯一PUT')
+            self._acks_received += 1
+            self._frames_written += 1
+            self._frame = self._pending_reply = None
+            _release_owned_ram(self, self._frame_cost, '_frame_cost')
+        except BaseException as exc:
+            self._fail(exc, '逐帧写出')
+
+    def finish(self):
+        """完成原stop、真实正常退出及全部费用，再核实际文件未超过预留。
+
+        参数: 无。返回: self，成功后重复调用不重发FINISH或重写文件。
+        异常: 原取消/预算/关闭错误，或LegacyCANWriteError为不完整回应、异常退出
+            或实际stat超本writer累计预留；任何失败都不置finished。
+        """
+        if self._finished:
+            return self
+        self._require_open()
+        try:
+            self.start()
+            reply = self._exchange({'op': 'finish', 'frame_count': self._frames_written})
+            if (set(reply) != {'op', 'frame_count'} or reply.get('op') != 'finished'
+                    or type(reply.get('frame_count')) is not int or reply['frame_count'] != self._frames_written):
+                raise LegacyCANWriteError('原CAN writer FINISH未确认全部原帧')
+            self._finish_received = True
+            self.close()
+            if self._exit_code != 0:
+                raise LegacyCANWriteError('原CAN writer虽发完成候选但未正常退出')
+            self._actual_bytes = self._output_path.stat().st_size
+            if self._actual_bytes > self._spool_bytes:
+                raise LegacyCANWriteError('原BLF实际大小超过本writer保守磁盘预留')
+            self._finished = True
+            return self
+        except BaseException as exc:
+            self._fail(exc, '封口')
+
+    def _close_connection(self, slot):
+        """实际关闭端点后才撤槽。参数: slot为本owner自有端点名。返回: None。
+        异常: 原close/取消；执行后异常也按真实closed确认，不丢未关句柄。
+        """
+        connection = getattr(self, slot)
+        if connection is not None:
+            try:
+                connection.close()
+            finally:
+                if connection.closed:
+                    setattr(self, slot, None)
+
+    def _close_process(self):
+        """有限等待自己实际进程退出再关句柄，绝不以终止请求代替退出证明。
+
+        参数: 无。返回: None。异常: 原join/terminate/kill/close或LegacyCANWriteError；
+            未确认时保原进程/费用并附稳定退出诊断。显式join上限为.5/.5/5秒，
+            Windows kill仍是TerminateProcess，必须实际exitcode非None。
+        """
+        process = self._process
+        if process is None:
+            return
+        if not self._process_stopped:
+            if process.pid is not None:
+                process.join(timeout=.5)
+                if process.exitcode is None:
+                    process.terminate()
+                    process.join(timeout=.5)
+                if process.exitcode is None:
+                    process.kill()
+                    process.join(timeout=5.0)
+                code = process.exitcode
+                if code is None:
+                    failure = LegacyCANWriteError('尚未确认原CAN writer子进程退出')
+                    failure.can_process_write_exit_state = {'pid': self._worker_pid, 'exit_code': None,
+                        'join_wait_limits_seconds': (.5, .5, 5.0)}
+                    raise failure
+                self._exit_code = code
+            self._process_stopped = True
+        # stopped先存，再实际close；close之后取消也不会再次读取已关闭Process属性。
+        process.close()
+        self._process = None
+
+    def close(self):
+        """只关本writer实际IPC/进程和费用，产物与累计磁盘预留保留。
+
+        参数: 无。返回: None，完成后重复调用幂等。
+        异常: 原关闭/预算/取消附can_process_write_cleanup_owner，当前槽供持续恢复；
+            提前关闭不发送额外帧或FINISH，不设置finished，不修改借用预算的其他费用。
+        """
+        if self._closed:
+            return
+        self._closing = True
+        try:
+            self._close_connection('_child_connection')
+            self._close_connection('_connection')
+            self._close_process()
+            self._metadata = self._frame = self._pending_reply = None
+            self._waiting = False
+            for slot in ('_frame_cost', '_metadata_cost', '_wire_cost', '_pipe_cost', '_process_cost', '_fixed_cost'):
+                _release_owned_ram(self, getattr(self, slot), slot)
+            self._closed = True
+        except BaseException as exc:
+            self._failed = True
+            exc.can_process_write_cleanup_owner = self
+            raise