OpenMed 隐私豁免生命周期账本WaiverLedgerPHI 安全的追加式本地合规证据记录【免费下载链接】openmedLocal-first healthcare AI: clinical NER HIPAA PII de-identification that runs 100% on-device. 2,200 medical models, 21 languages, Apple MLX Python, no cloud, no patient data leaving your network. Apache-2.0项目地址: https://gitcode.com/GitHub_Trending/ope/openmed本文以 OpenMed 开源仓库中的 waiver-ledger.md 为骨架深入讲解openmed.compliance.WaiverLedger的设计与用法它以追加式事件序列记录隐私豁免privacy waiver的完整生命周期刻意剔除身份、发现文本与时间戳等敏感字段只保留可控的事件类型、不透明标识符与聚合状态计数适用于本地优先local-first的医疗 AI 合规审计场景。读完本文你将掌握该账本的记录形态、状态机迁移规则、确定性序列化方式、源码级校验原理及其与仓库中审计链等证据组件的协作边界。一、定位证据助手而非合规认证在 HIPAA PII 脱敏、DPIA 评估等合规流程中隐私豁免waiver——即对某条策略规则的有条件豁免——的批准、替换、撤销与过期过程本身需要被忠实记录下来作为后续审计的证据。OpenMed 在 openmed/compliance/waiver_ledger.py 中提供了WaiverLedger把一次豁免的生命周期记录成追加式append-only的本地事件序列。需要特别强调的是定位边界原文档明确说明它是一个evidence helper证据助手而不是合规认证compliance certification、法律批准legal approval或临床决策机制clinical decision mechanism。它不负责判断豁免是否应被批准策略例外是否合法部署是否临床安全——这些决策权属于调用方自己的治理流程。相关文档 compliance.md 亦将其描述为记录确定性、仅聚合的豁免状态不含身份或发现文本的组件。二、安全记录形态Safe Record Shape豁免账本的安全核心是最小化记录表面。每条事件WaiverLifecycleEvent只包含字段类型说明sequenceint序号从 0 开始、必须连续event_type枚举可控事件类型之一create/approve/supersede/revoke/expirewaiver_id不透明字符串豁免标识符不携带语义信息policy_id不透明字符串策略引用创建时必填、后续事件必须保持不变state枚举事件导致的最终状态superseded_by可选字符串仅supersede事件可携带的替代豁免引用故意缺失的字段身份identity、发现文本finding-text、理由reason、源文档source-document、时间戳timestamp。原文档的告诫是当需要额外证据时使用周边治理系统管理的引用或哈希而不要把原始个人数据或发现文本放进任何标识符。这一设计在源码中有严格落地_IDENTIFIER_RE规定标识符必须匹配^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$waiver_ledger.py即只允许字母数字与少量分隔符从语法层面就拒绝了携带空格、自然语言或临床文本的伪标识符。三、生命周期状态机原文档给出了完整的生命周期图create - pending - approve - active | | | supersede | expire | | | superseded revoke | | revoked expired对应的迁移约束为只有pending状态的豁免可以被批准approve只有active状态的豁免可以被替换supersede、撤销revoke或显式过期expire策略引用policy_id在创建时必须提供且在后续所有事件中不得改变非法迁移不会追加任何记录fail without appending。源码中状态与事件的对应关系由_TARGET_STATE映射集中定义waiver_ledger.pycreate→pending、approve→active、supersede→superseded、revoke→revoked、expire→expired。同时WaiverState为可读性提供了别名CREATED pending、APPROVED active避免在事件词汇与状态词汇之间制造第二套序列化表示。_append_eventwaiver_ledger.py集中执行全部迁移校验create只允许针对未知豁免其他事件要求豁免已创建、policy_id必须与创建时一致approve仅对 pending 有效supersede/revoke/expire仅对 active 有效。任何校验失败都会抛出InvalidWaiverTransitionError未知豁免时抛出其子类UnknownWaiverError且不会改动账本内容。四、本地确定性用法原文档给出的最小示例from openmed.compliance import WaiverLedger ledger WaiverLedger() ledger.create(wvr_001, pol_privacy_001) ledger.approve(wvr_001) ledger.expire(wvr_001) print(ledger.render_active_state_counts()) # {active:0,expired:1,pending:0,revoked:0,superseded:0}结合源码事件 API 比示例更丰富waiver_ledger.pyfrom openmed.compliance import WaiverLedger ledger WaiverLedger() # 创建pendingpolicy_id 必填 ledger.create(wvr_001, pol_privacy_001) # 后续事件可省略 policy_id自动沿用创建时的引用 ledger.approve(wvr_001) ledger.expire(wvr_001) # supersede 支持两种写法关键字 replacement_waiver_id 或 superseded_by ledger.create(wvr_002, pol_privacy_001) ledger.approve(wvr_002) ledger.supersede(wvr_002, replacement_waiver_idwvr_003) # 通用入口 record()与各语义方法等价 event ledger.record(revoke, wvr_004, pol_privacy_001) # 冗长别名便于事件驱动的集成代码自解释 ledger.record_create(wvr_005, pol_privacy_001) ledger.record_approve(wvr_005) ledger.record_expire(wvr_005)注意record()的参数语义policy_id在create时必填在后续事件中可以省略自动复用创建时的策略引用若显式提供则必须与创建时一致否则抛出InvalidWaiverTransitionErrorwaiver_ledger.py。superseded_by仅对supersede事件有效且不能指向豁免自身replacement_waiver_id与superseded_by二选一同时提供会报错。五、追加式实现与非法迁移零副作用原理账本内部维护三份状态_events不可变的WaiverLifecycleEvent元组按追加顺序保存_stateswaiver_id → 当前状态的映射_policieswaiver_id → 创建时策略引用的映射。当前状态不单独落盘而是通过重放事件序列推导replay这与原文档同一合成事件序列必然产生相同的状态计数与 JSON 表示的确定性承诺一致。追加时有两条硬性约束序号连续event.sequence ! len(self._events)时直接报错waiver_ledger.py杜绝乱序或重复非法迁移零副作用所有校验都在self._events (*self._events, event)之前完成任何失败都不会污染已记录的事件。事件记录本身是frozenTrue, slotsTrue的不可变 dataclasswaiver_ledger.py并在__post_init__中校验事件状态必须与事件类型匹配superseded_by只能出现在supersede事件superseded_by必须指向不同豁免。测试 test_waiver_ledger.py 专门验证了非法迁移如对 pending 豁免 revoke、对 active 豁免重复 approve、重复 create抛出InvalidWaiverTransitionError且len(ledger)保持不变。六、标识符约束与敏感信息不泄漏源码为错误与输入做了两层防护第一层语法约束。_identifier()校验所有标识符必须匹配^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$否则抛出InvalidWaiverIdentifierError_sequence()要求序号为非负整数bool 会被拒绝。第二层错误消息不回显输入。异常消息只包含固定的安全文案如waiver_id must be an opaque identifier token绝不把原始输入拼进异常。测试 test_waiver_ledger.py 用synthetic sensitive finding text作为非法标识符断言异常文本中不含该输入、账本事件为空、序列化后的 JSON 中既不含该输入也不含finding/identity字样另一个测试还验证了非法事件触发异常后的完整 traceback 不会回显输入test_waiver_ledger.py。这与仓库的 no-raw-phi-logging.md 策略一脉相承日志与证据输出只允许计数、长度、标签、偏移与安全标识符禁止任何形式的原始 PHI 文本。七、序列化与本地审计存储to_json()与write_json()暴露的是同一组受控字段供本地审计存储使用。to_dict()waiver_ledger.py生成的结构为{ schema_version: 1, events: [ {sequence: 0, event_type: create, waiver_id: wvr_001, policy_id: pol_privacy_001, state: pending} ], state_counts: {active: 0, expired: 0, pending: 1, revoked: 0, superseded: 0} }序列化特性确定性json.dumps使用sort_keysTrue、ensure_asciiTrue、allow_nanFalse同样的合成事件序列永远产出同样的字节版本化WAIVER_LEDGER_SCHEMA_VERSION 1waiver_ledger.pyfrom_json()/from_mapping()会校验版本号并拒绝不支持的 schema一致性自检加载时若提供的state_counts与重放事件推导出的计数不一致直接报错waiver_ledger.py严格字段白名单事件与账本映射都只接受预定字段from_mapping()对未知字段一律拒绝防止注入自由格式内容waiver_ledger.py。测试验证了 JSON 往返的稳定性WaiverLedger.from_json(ledger.to_json()).to_json() ledger.to_json()且事件不可变——直接对事件字段赋值会触发FrozenInstanceErrortest_waiver_ledger.py。write_json(path)把上述 JSON默认indent2末尾带换行写入本地路径并返回该Path。因为记录内只有不透明标识符与受控事件类型这份文件可以安全地放入本地审计目录、备份或交给周边治理系统做哈希链式存证——仓库中的 audit_chain.pyHashChainAuditLog正是这类记录发生了导出/预览这一事实而不落盘底层个人数据的互补证据组件。八、聚合渲染只报计数不报标识符聚合渲染器render_active_state_counts()waiver_ledger.py是账本面向外部报告的唯一聚合出口它只输出计数绝不包含任何豁免或策略标识符。输出格式为紧凑 JSONprint(ledger.render_active_state_counts()) # {active:0,expired:1,pending:0,revoked:0,superseded:0}其内部实现固定枚举五态顺序pending、active、superseded、revoked、expired并保证计数稳定。测试明确断言渲染结果中不出现wvr_001之类的标识符test_waiver_ledger.py。这意味着它可以安全地进入操作面板、状态页或告警系统而不把豁免与策略的关联关系暴露给不必要的读者。模块级函数render_active_state_counts(ledger)与该方法等价方便以函数式风格调用。九、边界与职责声明最后原文档给出了三条不可越界的承诺使用时务必牢记不联网账本不发起任何网络调用所有操作都在本地内存与本地文件内完成符合 OpenMed no cloud、患者数据不出网络 的本地优先定位不推断过期账本不读取墙钟wall clock来推断豁免过期——过期是一个显式事件因此同一合成事件序列在任何时间重放都产生相同结果不替代决策它不决定豁免是否应被批准、策略例外是否合法、部署是否临床安全批准权限与法律/临床判断属于调用方的治理流程。十、测试验证与相关组件仓库为账本提供了完整的聚焦测试套件 test_waiver_ledger.py覆盖完整合成生命周期含 supersede 指向替代豁免、非法迁移零副作用、标识符与错误不回显敏感值、聚合渲染确定性与仅计数、事件不可变与 JSON 往返稳定、异常 traceback 不回显输入。如需在 OpenMed 的合规证据体系中继续深入可对照阅读compliance.md合规组件全景其中 waiver-ledger.md 与 access-review-expiry.md结构化访问复核过期门同为确定性、仅本地的证据助手privacy-release-gate.md隐私发布门中豁免waived结果的聚合处理policy-impact.md按动作、门与豁免迁移聚合的策略影响报告同样排除资源标识符、载荷值与豁免理由audit_chain.py哈希链式追加审计日志可与账本输出配合实现可检测篡改的本地审计存储no-raw-phi-logging.md账本无原始 PHI 记录设计所遵循的仓库级策略。综上WaiverLedger以极小的受控记录面、严格的状态机与确定性序列化为本地优先的医疗 AI 部署提供了一种证据充足但不触碰敏感内容的隐私豁免生命周期记录方案——它刻意保持简单把是否该豁免、是否合法、是否安全留给真正负责这些判断的人与流程。【免费下载链接】openmedLocal-first healthcare AI: clinical NER HIPAA PII de-identification that runs 100% on-device. 2,200 medical models, 21 languages, Apple MLX Python, no cloud, no patient data leaving your network. Apache-2.0项目地址: https://gitcode.com/GitHub_Trending/ope/openmed创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/19 12:28:20 · 阅读 1.2k OpenMed 隐私豁免生命周期账本（WaiverLedger）：PHI 安全的追加式本地合规证据记录
OpenMed 隐私豁免生命周期账本WaiverLedgerPHI 安全的追加式本地合规证据记录【免费下载链接】openmedLocal-first healthcare AI: clinical NER HIPAA PII de-identification that runs 100% on-device. 2,200 medical models, 21 languages, Apple MLX Python, no cloud, no patient data leaving your network. Apache-2.0项目地址: https://gitcode.com/GitHub_Trending/ope/openmed本文以 OpenMed 开源仓库中的 waiver-ledger.md 为骨架深入讲解openmed.compliance.WaiverLedger的设计与用法它以追加式事件序列记录隐私豁免privacy waiver的完整生命周期刻意剔除身份、发现文本与时间戳等敏感字段只保留可控的事件类型、不透明标识符与聚合状态计数适用于本地优先local-first的医疗 AI 合规审计场景。读完本文你将掌握该账本的记录形态、状态机迁移规则、确定性序列化方式、源码级校验原理及其与仓库中审计链等证据组件的协作边界。一、定位证据助手而非合规认证在 HIPAA PII 脱敏、DPIA 评估等合规流程中隐私豁免waiver——即对某条策略规则的有条件豁免——的批准、替换、撤销与过期过程本身需要被忠实记录下来作为后续审计的证据。OpenMed 在 openmed/compliance/waiver_ledger.py 中提供了WaiverLedger把一次豁免的生命周期记录成追加式append-only的本地事件序列。需要特别强调的是定位边界原文档明确说明它是一个evidence helper证据助手而不是合规认证compliance certification、法律批准legal approval或临床决策机制clinical decision mechanism。它不负责判断豁免是否应被批准策略例外是否合法部署是否临床安全——这些决策权属于调用方自己的治理流程。相关文档 compliance.md 亦将其描述为记录确定性、仅聚合的豁免状态不含身份或发现文本的组件。二、安全记录形态Safe Record Shape豁免账本的安全核心是最小化记录表面。每条事件WaiverLifecycleEvent只包含字段类型说明sequenceint序号从 0 开始、必须连续event_type枚举可控事件类型之一create/approve/supersede/revoke/expirewaiver_id不透明字符串豁免标识符不携带语义信息policy_id不透明字符串策略引用创建时必填、后续事件必须保持不变state枚举事件导致的最终状态superseded_by可选字符串仅supersede事件可携带的替代豁免引用故意缺失的字段身份identity、发现文本finding-text、理由reason、源文档source-document、时间戳timestamp。原文档的告诫是当需要额外证据时使用周边治理系统管理的引用或哈希而不要把原始个人数据或发现文本放进任何标识符。这一设计在源码中有严格落地_IDENTIFIER_RE规定标识符必须匹配^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$waiver_ledger.py即只允许字母数字与少量分隔符从语法层面就拒绝了携带空格、自然语言或临床文本的伪标识符。三、生命周期状态机原文档给出了完整的生命周期图create - pending - approve - active | | | supersede | expire | | | superseded revoke | | revoked expired对应的迁移约束为只有pending状态的豁免可以被批准approve只有active状态的豁免可以被替换supersede、撤销revoke或显式过期expire策略引用policy_id在创建时必须提供且在后续所有事件中不得改变非法迁移不会追加任何记录fail without appending。源码中状态与事件的对应关系由_TARGET_STATE映射集中定义waiver_ledger.pycreate→pending、approve→active、supersede→superseded、revoke→revoked、expire→expired。同时WaiverState为可读性提供了别名CREATED pending、APPROVED active避免在事件词汇与状态词汇之间制造第二套序列化表示。_append_eventwaiver_ledger.py集中执行全部迁移校验create只允许针对未知豁免其他事件要求豁免已创建、policy_id必须与创建时一致approve仅对 pending 有效supersede/revoke/expire仅对 active 有效。任何校验失败都会抛出InvalidWaiverTransitionError未知豁免时抛出其子类UnknownWaiverError且不会改动账本内容。四、本地确定性用法原文档给出的最小示例from openmed.compliance import WaiverLedger ledger WaiverLedger() ledger.create(wvr_001, pol_privacy_001) ledger.approve(wvr_001) ledger.expire(wvr_001) print(ledger.render_active_state_counts()) # {active:0,expired:1,pending:0,revoked:0,superseded:0}结合源码事件 API 比示例更丰富waiver_ledger.pyfrom openmed.compliance import WaiverLedger ledger WaiverLedger() # 创建pendingpolicy_id 必填 ledger.create(wvr_001, pol_privacy_001) # 后续事件可省略 policy_id自动沿用创建时的引用 ledger.approve(wvr_001) ledger.expire(wvr_001) # supersede 支持两种写法关键字 replacement_waiver_id 或 superseded_by ledger.create(wvr_002, pol_privacy_001) ledger.approve(wvr_002) ledger.supersede(wvr_002, replacement_waiver_idwvr_003) # 通用入口 record()与各语义方法等价 event ledger.record(revoke, wvr_004, pol_privacy_001) # 冗长别名便于事件驱动的集成代码自解释 ledger.record_create(wvr_005, pol_privacy_001) ledger.record_approve(wvr_005) ledger.record_expire(wvr_005)注意record()的参数语义policy_id在create时必填在后续事件中可以省略自动复用创建时的策略引用若显式提供则必须与创建时一致否则抛出InvalidWaiverTransitionErrorwaiver_ledger.py。superseded_by仅对supersede事件有效且不能指向豁免自身replacement_waiver_id与superseded_by二选一同时提供会报错。五、追加式实现与非法迁移零副作用原理账本内部维护三份状态_events不可变的WaiverLifecycleEvent元组按追加顺序保存_stateswaiver_id → 当前状态的映射_policieswaiver_id → 创建时策略引用的映射。当前状态不单独落盘而是通过重放事件序列推导replay这与原文档同一合成事件序列必然产生相同的状态计数与 JSON 表示的确定性承诺一致。追加时有两条硬性约束序号连续event.sequence ! len(self._events)时直接报错waiver_ledger.py杜绝乱序或重复非法迁移零副作用所有校验都在self._events (*self._events, event)之前完成任何失败都不会污染已记录的事件。事件记录本身是frozenTrue, slotsTrue的不可变 dataclasswaiver_ledger.py并在__post_init__中校验事件状态必须与事件类型匹配superseded_by只能出现在supersede事件superseded_by必须指向不同豁免。测试 test_waiver_ledger.py 专门验证了非法迁移如对 pending 豁免 revoke、对 active 豁免重复 approve、重复 create抛出InvalidWaiverTransitionError且len(ledger)保持不变。六、标识符约束与敏感信息不泄漏源码为错误与输入做了两层防护第一层语法约束。_identifier()校验所有标识符必须匹配^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$否则抛出InvalidWaiverIdentifierError_sequence()要求序号为非负整数bool 会被拒绝。第二层错误消息不回显输入。异常消息只包含固定的安全文案如waiver_id must be an opaque identifier token绝不把原始输入拼进异常。测试 test_waiver_ledger.py 用synthetic sensitive finding text作为非法标识符断言异常文本中不含该输入、账本事件为空、序列化后的 JSON 中既不含该输入也不含finding/identity字样另一个测试还验证了非法事件触发异常后的完整 traceback 不会回显输入test_waiver_ledger.py。这与仓库的 no-raw-phi-logging.md 策略一脉相承日志与证据输出只允许计数、长度、标签、偏移与安全标识符禁止任何形式的原始 PHI 文本。七、序列化与本地审计存储to_json()与write_json()暴露的是同一组受控字段供本地审计存储使用。to_dict()waiver_ledger.py生成的结构为{ schema_version: 1, events: [ {sequence: 0, event_type: create, waiver_id: wvr_001, policy_id: pol_privacy_001, state: pending} ], state_counts: {active: 0, expired: 0, pending: 1, revoked: 0, superseded: 0} }序列化特性确定性json.dumps使用sort_keysTrue、ensure_asciiTrue、allow_nanFalse同样的合成事件序列永远产出同样的字节版本化WAIVER_LEDGER_SCHEMA_VERSION 1waiver_ledger.pyfrom_json()/from_mapping()会校验版本号并拒绝不支持的 schema一致性自检加载时若提供的state_counts与重放事件推导出的计数不一致直接报错waiver_ledger.py严格字段白名单事件与账本映射都只接受预定字段from_mapping()对未知字段一律拒绝防止注入自由格式内容waiver_ledger.py。测试验证了 JSON 往返的稳定性WaiverLedger.from_json(ledger.to_json()).to_json() ledger.to_json()且事件不可变——直接对事件字段赋值会触发FrozenInstanceErrortest_waiver_ledger.py。write_json(path)把上述 JSON默认indent2末尾带换行写入本地路径并返回该Path。因为记录内只有不透明标识符与受控事件类型这份文件可以安全地放入本地审计目录、备份或交给周边治理系统做哈希链式存证——仓库中的 audit_chain.pyHashChainAuditLog正是这类记录发生了导出/预览这一事实而不落盘底层个人数据的互补证据组件。八、聚合渲染只报计数不报标识符聚合渲染器render_active_state_counts()waiver_ledger.py是账本面向外部报告的唯一聚合出口它只输出计数绝不包含任何豁免或策略标识符。输出格式为紧凑 JSONprint(ledger.render_active_state_counts()) # {active:0,expired:1,pending:0,revoked:0,superseded:0}其内部实现固定枚举五态顺序pending、active、superseded、revoked、expired并保证计数稳定。测试明确断言渲染结果中不出现wvr_001之类的标识符test_waiver_ledger.py。这意味着它可以安全地进入操作面板、状态页或告警系统而不把豁免与策略的关联关系暴露给不必要的读者。模块级函数render_active_state_counts(ledger)与该方法等价方便以函数式风格调用。九、边界与职责声明最后原文档给出了三条不可越界的承诺使用时务必牢记不联网账本不发起任何网络调用所有操作都在本地内存与本地文件内完成符合 OpenMed no cloud、患者数据不出网络 的本地优先定位不推断过期账本不读取墙钟wall clock来推断豁免过期——过期是一个显式事件因此同一合成事件序列在任何时间重放都产生相同结果不替代决策它不决定豁免是否应被批准、策略例外是否合法、部署是否临床安全批准权限与法律/临床判断属于调用方的治理流程。十、测试验证与相关组件仓库为账本提供了完整的聚焦测试套件 test_waiver_ledger.py覆盖完整合成生命周期含 supersede 指向替代豁免、非法迁移零副作用、标识符与错误不回显敏感值、聚合渲染确定性与仅计数、事件不可变与 JSON 往返稳定、异常 traceback 不回显输入。如需在 OpenMed 的合规证据体系中继续深入可对照阅读compliance.md合规组件全景其中 waiver-ledger.md 与 access-review-expiry.md结构化访问复核过期门同为确定性、仅本地的证据助手privacy-release-gate.md隐私发布门中豁免waived结果的聚合处理policy-impact.md按动作、门与豁免迁移聚合的策略影响报告同样排除资源标识符、载荷值与豁免理由audit_chain.py哈希链式追加审计日志可与账本输出配合实现可检测篡改的本地审计存储no-raw-phi-logging.md账本无原始 PHI 记录设计所遵循的仓库级策略。综上WaiverLedger以极小的受控记录面、严格的状态机与确定性序列化为本地优先的医疗 AI 部署提供了一种证据充足但不触碰敏感内容的隐私豁免生命周期记录方案——它刻意保持简单把是否该豁免、是否合法、是否安全留给真正负责这些判断的人与流程。【免费下载链接】openmedLocal-first healthcare AI: clinical NER HIPAA PII de-identification that runs 100% on-device. 2,200 medical models, 21 languages, Apple MLX Python, no cloud, no patient data leaving your network. Apache-2.0项目地址: https://gitcode.com/GitHub_Trending/ope/openmed创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考