briefloop 0.11.12__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (424) hide show
  1. briefloop-0.11.12.dist-info/METADATA +473 -0
  2. briefloop-0.11.12.dist-info/RECORD +424 -0
  3. briefloop-0.11.12.dist-info/WHEEL +5 -0
  4. briefloop-0.11.12.dist-info/entry_points.txt +3 -0
  5. briefloop-0.11.12.dist-info/licenses/LICENSE +22 -0
  6. briefloop-0.11.12.dist-info/top_level.txt +1 -0
  7. multi_agent_brief/__init__.py +36 -0
  8. multi_agent_brief/analysis_blocks/__init__.py +11 -0
  9. multi_agent_brief/analysis_blocks/builder.py +206 -0
  10. multi_agent_brief/analysis_blocks/renderer.py +237 -0
  11. multi_agent_brief/analysis_blocks/schemas.py +52 -0
  12. multi_agent_brief/analysis_modules/__init__.py +8 -0
  13. multi_agent_brief/analysis_modules/base.py +87 -0
  14. multi_agent_brief/analysis_modules/market_competitor/__init__.py +68 -0
  15. multi_agent_brief/analysis_modules/market_competitor/auditor.py +290 -0
  16. multi_agent_brief/analysis_modules/market_competitor/config.py +187 -0
  17. multi_agent_brief/analysis_modules/market_competitor/event_builder.py +226 -0
  18. multi_agent_brief/analysis_modules/market_competitor/renderer.py +199 -0
  19. multi_agent_brief/analysis_modules/market_competitor/schemas.py +518 -0
  20. multi_agent_brief/analysis_modules/policy_regulatory/__init__.py +7 -0
  21. multi_agent_brief/analysis_modules/policy_regulatory/audit.py +195 -0
  22. multi_agent_brief/analysis_modules/policy_regulatory/module.py +387 -0
  23. multi_agent_brief/analysis_modules/policy_regulatory/schemas.py +129 -0
  24. multi_agent_brief/analysis_modules/registry.py +73 -0
  25. multi_agent_brief/audience/__init__.py +19 -0
  26. multi_agent_brief/audience/profiles.py +246 -0
  27. multi_agent_brief/audience_memory/__init__.py +23 -0
  28. multi_agent_brief/audience_memory/profile.py +358 -0
  29. multi_agent_brief/audit/__init__.py +36 -0
  30. multi_agent_brief/audit/case_applicability.py +181 -0
  31. multi_agent_brief/audit/deterministic.py +471 -0
  32. multi_agent_brief/audit/editorial_governance.py +404 -0
  33. multi_agent_brief/audit/final_quality.py +764 -0
  34. multi_agent_brief/audit/harness.py +242 -0
  35. multi_agent_brief/audit/interfaces.py +96 -0
  36. multi_agent_brief/audit/limitation_hygiene.py +238 -0
  37. multi_agent_brief/audit/proposal_boundary.py +34 -0
  38. multi_agent_brief/audit/redaction.py +27 -0
  39. multi_agent_brief/audit/rule_packs.py +96 -0
  40. multi_agent_brief/audit/semantic.py +435 -0
  41. multi_agent_brief/capabilities/__init__.py +22 -0
  42. multi_agent_brief/capabilities/catalog.py +215 -0
  43. multi_agent_brief/capabilities/detect.py +199 -0
  44. multi_agent_brief/capabilities/models.py +60 -0
  45. multi_agent_brief/capabilities/recommend.py +206 -0
  46. multi_agent_brief/cli/__init__.py +2 -0
  47. multi_agent_brief/cli/analysis_commands.py +140 -0
  48. multi_agent_brief/cli/approval_commands.py +107 -0
  49. multi_agent_brief/cli/audit_commands.py +59 -0
  50. multi_agent_brief/cli/capability_commands.py +548 -0
  51. multi_agent_brief/cli/claude_commands.py +159 -0
  52. multi_agent_brief/cli/competitors_commands.py +182 -0
  53. multi_agent_brief/cli/controls_commands.py +137 -0
  54. multi_agent_brief/cli/deliver_commands.py +942 -0
  55. multi_agent_brief/cli/eval_cases_commands.py +99 -0
  56. multi_agent_brief/cli/experiments_commands.py +395 -0
  57. multi_agent_brief/cli/feedback_commands.py +192 -0
  58. multi_agent_brief/cli/finalize_commands.py +153 -0
  59. multi_agent_brief/cli/gates_commands.py +174 -0
  60. multi_agent_brief/cli/hermes_commands.py +356 -0
  61. multi_agent_brief/cli/improve_commands.py +224 -0
  62. multi_agent_brief/cli/init_commands.py +564 -0
  63. multi_agent_brief/cli/init_wizard.py +1473 -0
  64. multi_agent_brief/cli/input_commands.py +237 -0
  65. multi_agent_brief/cli/main.py +288 -0
  66. multi_agent_brief/cli/onboard_commands.py +193 -0
  67. multi_agent_brief/cli/product_commands.py +1449 -0
  68. multi_agent_brief/cli/provenance_commands.py +100 -0
  69. multi_agent_brief/cli/release_commands.py +68 -0
  70. multi_agent_brief/cli/repair_commands.py +169 -0
  71. multi_agent_brief/cli/run_commands.py +292 -0
  72. multi_agent_brief/cli/runtime_commands.py +81 -0
  73. multi_agent_brief/cli/secrets_commands.py +232 -0
  74. multi_agent_brief/cli/semantic_support_commands.py +80 -0
  75. multi_agent_brief/cli/sources_commands.py +647 -0
  76. multi_agent_brief/cli/start_commands.py +8 -0
  77. multi_agent_brief/cli/state_commands.py +446 -0
  78. multi_agent_brief/cli/status_commands.py +26 -0
  79. multi_agent_brief/cli/workbuddy_commands.py +103 -0
  80. multi_agent_brief/configs/artifact_contracts.yaml +514 -0
  81. multi_agent_brief/configs/orchestrator_contract.yaml +181 -0
  82. multi_agent_brief/configs/policy_packs/default.yaml +65 -0
  83. multi_agent_brief/configs/policy_profiles/evidence_extract_default.yaml +58 -0
  84. multi_agent_brief/configs/policy_profiles/finance_default.yaml +44 -0
  85. multi_agent_brief/configs/policy_profiles/internet_default.yaml +44 -0
  86. multi_agent_brief/configs/policy_profiles/manufacturing_default.yaml +33 -0
  87. multi_agent_brief/configs/policy_profiles/solar_manufacturing_default.yaml +64 -0
  88. multi_agent_brief/configs/report_packs/evidence_extract.yaml +48 -0
  89. multi_agent_brief/configs/report_packs/management_monthly.yaml +36 -0
  90. multi_agent_brief/configs/report_packs/market_weekly.yaml +36 -0
  91. multi_agent_brief/configs/report_packs/solar_industry_periodic.yaml +50 -0
  92. multi_agent_brief/configs/report_templates/evidence_extract.yaml +55 -0
  93. multi_agent_brief/configs/report_templates/management_monthly.yaml +48 -0
  94. multi_agent_brief/configs/report_templates/market_weekly.yaml +49 -0
  95. multi_agent_brief/configs/report_templates/solar_industry_periodic.yaml +75 -0
  96. multi_agent_brief/configs/stage_specs.yaml +180 -0
  97. multi_agent_brief/contracts/__init__.py +41 -0
  98. multi_agent_brief/contracts/base.py +99 -0
  99. multi_agent_brief/contracts/errors.py +41 -0
  100. multi_agent_brief/contracts/migrations/__init__.py +5 -0
  101. multi_agent_brief/contracts/migrations/claim_v1_to_v2.py +33 -0
  102. multi_agent_brief/contracts/registry.py +159 -0
  103. multi_agent_brief/contracts/role_topology.py +25 -0
  104. multi_agent_brief/contracts/schemas/__init__.py +35 -0
  105. multi_agent_brief/contracts/schemas/analysis_pack.py +135 -0
  106. multi_agent_brief/contracts/schemas/atomic_claim_graph.py +304 -0
  107. multi_agent_brief/contracts/schemas/audit_report.py +80 -0
  108. multi_agent_brief/contracts/schemas/candidate_item.py +51 -0
  109. multi_agent_brief/contracts/schemas/claim.py +197 -0
  110. multi_agent_brief/contracts/schemas/claim_draft.py +386 -0
  111. multi_agent_brief/contracts/schemas/claim_support_matrix.py +334 -0
  112. multi_agent_brief/contracts/schemas/evidence_span_registry.py +270 -0
  113. multi_agent_brief/contracts/schemas/policy_profile.py +247 -0
  114. multi_agent_brief/contracts/schemas/report_spec.py +257 -0
  115. multi_agent_brief/contracts/schemas/semantic_assessment_report.py +480 -0
  116. multi_agent_brief/contracts/schemas/source_evidence_pack_manifest.py +233 -0
  117. multi_agent_brief/contracts/schemas/source_item.py +96 -0
  118. multi_agent_brief/contracts/semantic_assessment_status.py +12 -0
  119. multi_agent_brief/contracts/source_metadata.py +252 -0
  120. multi_agent_brief/contracts/target_contract.py +460 -0
  121. multi_agent_brief/contracts/validator.py +225 -0
  122. multi_agent_brief/controls/__init__.py +23 -0
  123. multi_agent_brief/controls/contract.py +106 -0
  124. multi_agent_brief/controls/switchboard.py +1076 -0
  125. multi_agent_brief/core/__init__.py +2 -0
  126. multi_agent_brief/core/citations.py +14 -0
  127. multi_agent_brief/core/claim_ledger.py +94 -0
  128. multi_agent_brief/core/config.py +191 -0
  129. multi_agent_brief/core/env.py +69 -0
  130. multi_agent_brief/core/previous.py +83 -0
  131. multi_agent_brief/core/schemas.py +181 -0
  132. multi_agent_brief/core/selection.py +189 -0
  133. multi_agent_brief/delivery/__init__.py +6 -0
  134. multi_agent_brief/delivery/base.py +36 -0
  135. multi_agent_brief/delivery/feishu.py +204 -0
  136. multi_agent_brief/delivery/gws.py +237 -0
  137. multi_agent_brief/evaluation_cases/__init__.py +15 -0
  138. multi_agent_brief/evaluation_cases/contract.py +429 -0
  139. multi_agent_brief/evaluation_cases/fixtures/cases/approved_guidance_materialized/workspace/config.yaml +18 -0
  140. multi_agent_brief/evaluation_cases/fixtures/cases/approved_guidance_materialized/workspace/improvement/ledger.jsonl +2 -0
  141. multi_agent_brief/evaluation_cases/fixtures/cases/approved_guidance_materialized/workspace/sources.yaml +2 -0
  142. multi_agent_brief/evaluation_cases/fixtures/cases/approved_guidance_materialized/workspace/user.md +4 -0
  143. multi_agent_brief/evaluation_cases/fixtures/cases/company_event_missing_latest_official_check/workspace/config.yaml +13 -0
  144. multi_agent_brief/evaluation_cases/fixtures/cases/company_event_missing_latest_official_check/workspace/sources.yaml +9 -0
  145. multi_agent_brief/evaluation_cases/fixtures/cases/company_event_missing_latest_official_check/workspace/user.md +4 -0
  146. multi_agent_brief/evaluation_cases/fixtures/cases/control_switchboard_selection_is_not_execution/workspace/config.yaml +12 -0
  147. multi_agent_brief/evaluation_cases/fixtures/cases/control_switchboard_selection_is_not_execution/workspace/sources.yaml +6 -0
  148. multi_agent_brief/evaluation_cases/fixtures/cases/control_switchboard_selection_is_not_execution/workspace/user.md +4 -0
  149. multi_agent_brief/evaluation_cases/fixtures/cases/feedback_triage_required/workspace/config.yaml +6 -0
  150. multi_agent_brief/evaluation_cases/fixtures/cases/feedback_triage_required/workspace/input/human_feedback.md +1 -0
  151. multi_agent_brief/evaluation_cases/fixtures/cases/feedback_triage_required/workspace/sources.yaml +2 -0
  152. multi_agent_brief/evaluation_cases/fixtures/cases/feedback_triage_required/workspace/user.md +3 -0
  153. multi_agent_brief/evaluation_cases/fixtures/cases/final_abstract_quality_warning_surface/workspace/config.yaml +8 -0
  154. multi_agent_brief/evaluation_cases/fixtures/cases/final_abstract_quality_warning_surface/workspace/output/brief.md +14 -0
  155. multi_agent_brief/evaluation_cases/fixtures/cases/final_abstract_quality_warning_surface/workspace/output/intermediate/audit_report.json +1 -0
  156. multi_agent_brief/evaluation_cases/fixtures/cases/final_abstract_quality_warning_surface/workspace/output/intermediate/audited_brief.md +5 -0
  157. multi_agent_brief/evaluation_cases/fixtures/cases/final_abstract_quality_warning_surface/workspace/output/intermediate/candidate_claims.json +1 -0
  158. multi_agent_brief/evaluation_cases/fixtures/cases/final_abstract_quality_warning_surface/workspace/output/intermediate/claim_ledger.json +1 -0
  159. multi_agent_brief/evaluation_cases/fixtures/cases/final_abstract_quality_warning_surface/workspace/output/intermediate/screened_candidates.json +1 -0
  160. multi_agent_brief/evaluation_cases/fixtures/cases/final_abstract_quality_warning_surface/workspace/sources.yaml +2 -0
  161. multi_agent_brief/evaluation_cases/fixtures/cases/final_abstract_quality_warning_surface/workspace/user.md +3 -0
  162. multi_agent_brief/evaluation_cases/fixtures/cases/formal_release_missing_human_approval/workspace/config.yaml +13 -0
  163. multi_agent_brief/evaluation_cases/fixtures/cases/formal_release_missing_human_approval/workspace/sources.yaml +9 -0
  164. multi_agent_brief/evaluation_cases/fixtures/cases/formal_release_missing_human_approval/workspace/user.md +4 -0
  165. multi_agent_brief/evaluation_cases/fixtures/cases/guidance_manifestation_not_observable/workspace/config.yaml +4 -0
  166. multi_agent_brief/evaluation_cases/fixtures/cases/guidance_manifestation_not_observable/workspace/sources.yaml +2 -0
  167. multi_agent_brief/evaluation_cases/fixtures/cases/guidance_manifestation_not_observable/workspace/user.md +3 -0
  168. multi_agent_brief/evaluation_cases/fixtures/cases/media_only_legal_policy_blocks_research_review/workspace/config.yaml +13 -0
  169. multi_agent_brief/evaluation_cases/fixtures/cases/media_only_legal_policy_blocks_research_review/workspace/sources.yaml +9 -0
  170. multi_agent_brief/evaluation_cases/fixtures/cases/media_only_legal_policy_blocks_research_review/workspace/user.md +4 -0
  171. multi_agent_brief/evaluation_cases/fixtures/cases/mixed_metric_scope_support_blocker/workspace/config.yaml +13 -0
  172. multi_agent_brief/evaluation_cases/fixtures/cases/mixed_metric_scope_support_blocker/workspace/sources.yaml +9 -0
  173. multi_agent_brief/evaluation_cases/fixtures/cases/mixed_metric_scope_support_blocker/workspace/user.md +5 -0
  174. multi_agent_brief/evaluation_cases/fixtures/cases/planned_blocking_issue_cannot_continue/workspace/config.yaml +6 -0
  175. multi_agent_brief/evaluation_cases/fixtures/cases/planned_blocking_issue_cannot_continue/workspace/output/intermediate/audited_brief.md +3 -0
  176. multi_agent_brief/evaluation_cases/fixtures/cases/planned_blocking_issue_cannot_continue/workspace/output/intermediate/candidate_claims.json +1 -0
  177. multi_agent_brief/evaluation_cases/fixtures/cases/planned_blocking_issue_cannot_continue/workspace/output/intermediate/claim_ledger.json +1 -0
  178. multi_agent_brief/evaluation_cases/fixtures/cases/planned_blocking_issue_cannot_continue/workspace/output/intermediate/feedback_issues.json +25 -0
  179. multi_agent_brief/evaluation_cases/fixtures/cases/planned_blocking_issue_cannot_continue/workspace/output/intermediate/repair_plan.json +27 -0
  180. multi_agent_brief/evaluation_cases/fixtures/cases/planned_blocking_issue_cannot_continue/workspace/output/intermediate/screened_candidates.json +1 -0
  181. multi_agent_brief/evaluation_cases/fixtures/cases/planned_blocking_issue_cannot_continue/workspace/sources.yaml +2 -0
  182. multi_agent_brief/evaluation_cases/fixtures/cases/planned_blocking_issue_cannot_continue/workspace/user.md +3 -0
  183. multi_agent_brief/evaluation_cases/fixtures/cases/provenance_projection_minimal/workspace/config.yaml +8 -0
  184. multi_agent_brief/evaluation_cases/fixtures/cases/provenance_projection_minimal/workspace/output/intermediate/audit_report.json +1 -0
  185. multi_agent_brief/evaluation_cases/fixtures/cases/provenance_projection_minimal/workspace/output/intermediate/audited_brief.md +3 -0
  186. multi_agent_brief/evaluation_cases/fixtures/cases/provenance_projection_minimal/workspace/output/intermediate/candidate_claims.json +1 -0
  187. multi_agent_brief/evaluation_cases/fixtures/cases/provenance_projection_minimal/workspace/output/intermediate/claim_ledger.json +11 -0
  188. multi_agent_brief/evaluation_cases/fixtures/cases/provenance_projection_minimal/workspace/output/intermediate/quality_gate_report.json +22 -0
  189. multi_agent_brief/evaluation_cases/fixtures/cases/provenance_projection_minimal/workspace/output/intermediate/screened_candidates.json +1 -0
  190. multi_agent_brief/evaluation_cases/fixtures/cases/provenance_projection_minimal/workspace/sources.yaml +2 -0
  191. multi_agent_brief/evaluation_cases/fixtures/cases/provenance_projection_minimal/workspace/user.md +3 -0
  192. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_source_appendix/workspace/config.yaml +13 -0
  193. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_source_appendix/workspace/output/intermediate/audit_report.json +1 -0
  194. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_source_appendix/workspace/output/intermediate/audited_brief.md +5 -0
  195. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_source_appendix/workspace/output/intermediate/candidate_claims.json +1 -0
  196. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_source_appendix/workspace/output/intermediate/claim_ledger.json +40 -0
  197. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_source_appendix/workspace/output/intermediate/screened_candidates.json +1 -0
  198. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_source_appendix/workspace/sources.yaml +3 -0
  199. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_source_appendix/workspace/user.md +3 -0
  200. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_target_relevance/workspace/config.yaml +8 -0
  201. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_target_relevance/workspace/output/brief.md +3 -0
  202. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_target_relevance/workspace/output/intermediate/audit_report.json +1 -0
  203. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_target_relevance/workspace/output/intermediate/audited_brief.md +3 -0
  204. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_target_relevance/workspace/output/intermediate/candidate_claims.json +1 -0
  205. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_target_relevance/workspace/output/intermediate/claim_ledger.json +13 -0
  206. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_target_relevance/workspace/output/intermediate/screened_candidates.json +1 -0
  207. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_target_relevance/workspace/sources.yaml +2 -0
  208. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_target_relevance/workspace/user.md +3 -0
  209. multi_agent_brief/evaluation_cases/fixtures/cases/release_readiness_forged_event_blocker/workspace/config.yaml +13 -0
  210. multi_agent_brief/evaluation_cases/fixtures/cases/release_readiness_forged_event_blocker/workspace/output/intermediate/release_readiness_report.json +31 -0
  211. multi_agent_brief/evaluation_cases/fixtures/cases/release_readiness_forged_event_blocker/workspace/sources.yaml +9 -0
  212. multi_agent_brief/evaluation_cases/fixtures/cases/release_readiness_forged_event_blocker/workspace/user.md +4 -0
  213. multi_agent_brief/evaluation_cases/fixtures/cases/reverted_entry_removed_from_next_snapshot/workspace/config.yaml +18 -0
  214. multi_agent_brief/evaluation_cases/fixtures/cases/reverted_entry_removed_from_next_snapshot/workspace/improvement/ledger.jsonl +3 -0
  215. multi_agent_brief/evaluation_cases/fixtures/cases/reverted_entry_removed_from_next_snapshot/workspace/improvement/memory.md +3 -0
  216. multi_agent_brief/evaluation_cases/fixtures/cases/reverted_entry_removed_from_next_snapshot/workspace/output/intermediate/improvement_memory_snapshot.md +3 -0
  217. multi_agent_brief/evaluation_cases/fixtures/cases/reverted_entry_removed_from_next_snapshot/workspace/sources.yaml +2 -0
  218. multi_agent_brief/evaluation_cases/fixtures/cases/reverted_entry_removed_from_next_snapshot/workspace/user.md +4 -0
  219. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/config.yaml +12 -0
  220. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/input/sources/source-001.txt +1 -0
  221. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/output/brief.md +37 -0
  222. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/output/delivery/brief.md +37 -0
  223. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/output/intermediate/atomic_claim_graph.json +17 -0
  224. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/output/intermediate/audit_report.json +5 -0
  225. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/output/intermediate/audited_brief.md +37 -0
  226. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/output/intermediate/claim_ledger.json +20 -0
  227. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/output/intermediate/evidence_span_registry.json +20 -0
  228. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/output/intermediate/finalize_report.json +40 -0
  229. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/output/intermediate/gates/auditor_quality_gate_report.json +42 -0
  230. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/output/intermediate/gates/finalize_quality_gate_report.json +42 -0
  231. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/output/intermediate/screened_candidates.json +33 -0
  232. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/output/source_appendix.md +12 -0
  233. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/output/source_appendix_trace.md +10 -0
  234. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/report_spec.yaml +24 -0
  235. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/sources.yaml +4 -0
  236. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/user.md +3 -0
  237. multi_agent_brief/evaluation_cases/fixtures/cases/source_evidence_pack_blocks_non_evidence_file/workspace/config.yaml +13 -0
  238. multi_agent_brief/evaluation_cases/fixtures/cases/source_evidence_pack_blocks_non_evidence_file/workspace/input/sources/README.md +4 -0
  239. multi_agent_brief/evaluation_cases/fixtures/cases/source_evidence_pack_blocks_non_evidence_file/workspace/output/intermediate/source_evidence_pack_manifest.json +26 -0
  240. multi_agent_brief/evaluation_cases/fixtures/cases/source_evidence_pack_blocks_non_evidence_file/workspace/sources.yaml +9 -0
  241. multi_agent_brief/evaluation_cases/fixtures/cases/source_evidence_pack_blocks_non_evidence_file/workspace/user.md +4 -0
  242. multi_agent_brief/evaluation_cases/fixtures/cases/stale_current_claim/workspace/config.yaml +9 -0
  243. multi_agent_brief/evaluation_cases/fixtures/cases/stale_current_claim/workspace/output/intermediate/audit_report.json +1 -0
  244. multi_agent_brief/evaluation_cases/fixtures/cases/stale_current_claim/workspace/output/intermediate/audited_brief.md +3 -0
  245. multi_agent_brief/evaluation_cases/fixtures/cases/stale_current_claim/workspace/output/intermediate/candidate_claims.json +1 -0
  246. multi_agent_brief/evaluation_cases/fixtures/cases/stale_current_claim/workspace/output/intermediate/claim_ledger.json +13 -0
  247. multi_agent_brief/evaluation_cases/fixtures/cases/stale_current_claim/workspace/output/intermediate/screened_candidates.json +1 -0
  248. multi_agent_brief/evaluation_cases/fixtures/cases/stale_current_claim/workspace/sources.yaml +2 -0
  249. multi_agent_brief/evaluation_cases/fixtures/cases/stale_current_claim/workspace/user.md +3 -0
  250. multi_agent_brief/evaluation_cases/fixtures/cases/third_party_price_snapshot_formal_block/workspace/config.yaml +13 -0
  251. multi_agent_brief/evaluation_cases/fixtures/cases/third_party_price_snapshot_formal_block/workspace/sources.yaml +9 -0
  252. multi_agent_brief/evaluation_cases/fixtures/cases/third_party_price_snapshot_formal_block/workspace/user.md +4 -0
  253. multi_agent_brief/evaluation_cases/fixtures/cases/trajectory_retry_budget_exhausted/workspace/config.yaml +4 -0
  254. multi_agent_brief/evaluation_cases/fixtures/cases/trajectory_retry_budget_exhausted/workspace/sources.yaml +2 -0
  255. multi_agent_brief/evaluation_cases/fixtures/cases/trajectory_retry_budget_exhausted/workspace/user.md +3 -0
  256. multi_agent_brief/evaluation_cases/fixtures/cases/unapproved_entry_not_materialized/workspace/config.yaml +18 -0
  257. multi_agent_brief/evaluation_cases/fixtures/cases/unapproved_entry_not_materialized/workspace/improvement/ledger.jsonl +1 -0
  258. multi_agent_brief/evaluation_cases/fixtures/cases/unapproved_entry_not_materialized/workspace/sources.yaml +2 -0
  259. multi_agent_brief/evaluation_cases/fixtures/cases/unapproved_entry_not_materialized/workspace/user.md +4 -0
  260. multi_agent_brief/evaluation_cases/fixtures/cases/unauthorized_institution_branding_blocks_release/workspace/config.yaml +18 -0
  261. multi_agent_brief/evaluation_cases/fixtures/cases/unauthorized_institution_branding_blocks_release/workspace/sources.yaml +9 -0
  262. multi_agent_brief/evaluation_cases/fixtures/cases/unauthorized_institution_branding_blocks_release/workspace/user.md +5 -0
  263. multi_agent_brief/evaluation_cases/fixtures/cases/unsupported_material_fact/workspace/config.yaml +8 -0
  264. multi_agent_brief/evaluation_cases/fixtures/cases/unsupported_material_fact/workspace/output/intermediate/audit_report.json +1 -0
  265. multi_agent_brief/evaluation_cases/fixtures/cases/unsupported_material_fact/workspace/output/intermediate/audited_brief.md +8 -0
  266. multi_agent_brief/evaluation_cases/fixtures/cases/unsupported_material_fact/workspace/output/intermediate/candidate_claims.json +1 -0
  267. multi_agent_brief/evaluation_cases/fixtures/cases/unsupported_material_fact/workspace/output/intermediate/claim_ledger.json +1 -0
  268. multi_agent_brief/evaluation_cases/fixtures/cases/unsupported_material_fact/workspace/output/intermediate/screened_candidates.json +1 -0
  269. multi_agent_brief/evaluation_cases/fixtures/cases/unsupported_material_fact/workspace/sources.yaml +2 -0
  270. multi_agent_brief/evaluation_cases/fixtures/cases/unsupported_material_fact/workspace/user.md +3 -0
  271. multi_agent_brief/evaluation_cases/fixtures/manifest.yaml +861 -0
  272. multi_agent_brief/evaluation_cases/fixtures.py +20 -0
  273. multi_agent_brief/evaluation_cases/runner.py +1603 -0
  274. multi_agent_brief/experiments/__init__.py +45 -0
  275. multi_agent_brief/experiments/experiment_080.py +5835 -0
  276. multi_agent_brief/experiments/schemas.py +63 -0
  277. multi_agent_brief/experiments/target_contract.py +10 -0
  278. multi_agent_brief/feedback/__init__.py +17 -0
  279. multi_agent_brief/feedback/feedback_contract.py +482 -0
  280. multi_agent_brief/feedback/feedback_state.py +898 -0
  281. multi_agent_brief/hermes/__init__.py +25 -0
  282. multi_agent_brief/hermes/adapter.py +832 -0
  283. multi_agent_brief/improvement/__init__.py +83 -0
  284. multi_agent_brief/improvement/contract.py +1114 -0
  285. multi_agent_brief/improvement/memory.py +451 -0
  286. multi_agent_brief/improvement/product_definition.py +228 -0
  287. multi_agent_brief/improvement/state.py +961 -0
  288. multi_agent_brief/inputs/__init__.py +2 -0
  289. multi_agent_brief/inputs/classifier.py +322 -0
  290. multi_agent_brief/inputs/contracts.py +59 -0
  291. multi_agent_brief/inputs/extractor.py +310 -0
  292. multi_agent_brief/install/__init__.py +2 -0
  293. multi_agent_brief/install/writer.py +97 -0
  294. multi_agent_brief/onboarding/__init__.py +11 -0
  295. multi_agent_brief/onboarding/io.py +103 -0
  296. multi_agent_brief/onboarding/mapper.py +484 -0
  297. multi_agent_brief/onboarding/schema.py +46 -0
  298. multi_agent_brief/orchestrator/__init__.py +2 -0
  299. multi_agent_brief/orchestrator/fact_layer_import.py +352 -0
  300. multi_agent_brief/orchestrator/handoff.py +2209 -0
  301. multi_agent_brief/orchestrator/role_topology.py +42 -0
  302. multi_agent_brief/orchestrator/run_archive.py +888 -0
  303. multi_agent_brief/orchestrator/run_integrity.py +346 -0
  304. multi_agent_brief/orchestrator/runtime_state/__init__.py +70 -0
  305. multi_agent_brief/orchestrator/runtime_state/_io.py +167 -0
  306. multi_agent_brief/orchestrator/runtime_state/_transactions.py +298 -0
  307. multi_agent_brief/orchestrator/runtime_state/artifact_registry.py +1825 -0
  308. multi_agent_brief/orchestrator/runtime_state/atomic_claim_graph.py +96 -0
  309. multi_agent_brief/orchestrator/runtime_state/claim_ledger_freeze.py +510 -0
  310. multi_agent_brief/orchestrator/runtime_state/claim_metadata_enrichment.py +836 -0
  311. multi_agent_brief/orchestrator/runtime_state/claim_support_matrix.py +582 -0
  312. multi_agent_brief/orchestrator/runtime_state/completion_gates.py +672 -0
  313. multi_agent_brief/orchestrator/runtime_state/contracts_loader.py +66 -0
  314. multi_agent_brief/orchestrator/runtime_state/decisions.py +239 -0
  315. multi_agent_brief/orchestrator/runtime_state/errors.py +61 -0
  316. multi_agent_brief/orchestrator/runtime_state/event_log.py +256 -0
  317. multi_agent_brief/orchestrator/runtime_state/evidence_span_registry.py +233 -0
  318. multi_agent_brief/orchestrator/runtime_state/fact_layer.py +755 -0
  319. multi_agent_brief/orchestrator/runtime_state/identity.py +90 -0
  320. multi_agent_brief/orchestrator/runtime_state/lifecycle.py +675 -0
  321. multi_agent_brief/orchestrator/runtime_state/manifest.py +82 -0
  322. multi_agent_brief/orchestrator/runtime_state/operations.py +224 -0
  323. multi_agent_brief/orchestrator/runtime_state/paths.py +38 -0
  324. multi_agent_brief/orchestrator/runtime_state/repair.py +984 -0
  325. multi_agent_brief/orchestrator/runtime_state/safety_surfaces.py +147 -0
  326. multi_agent_brief/orchestrator/runtime_state/semantic_assessment_report.py +692 -0
  327. multi_agent_brief/orchestrator/runtime_state/semantic_support_acceptance.py +683 -0
  328. multi_agent_brief/orchestrator/runtime_state/source_evidence_pack.py +131 -0
  329. multi_agent_brief/orchestrator/runtime_state/stage_completion.py +1320 -0
  330. multi_agent_brief/orchestrator/runtime_state/trajectory.py +200 -0
  331. multi_agent_brief/orchestrator/runtime_state/workflow.py +350 -0
  332. multi_agent_brief/orchestrator/source_evidence.py +43 -0
  333. multi_agent_brief/orchestrator/timing.py +410 -0
  334. multi_agent_brief/orchestrator_contract.py +96 -0
  335. multi_agent_brief/outputs/__init__.py +2 -0
  336. multi_agent_brief/outputs/atomic_reader_projection.py +288 -0
  337. multi_agent_brief/outputs/docx.py +32 -0
  338. multi_agent_brief/outputs/finalize.py +1036 -0
  339. multi_agent_brief/outputs/ib_docx.py +983 -0
  340. multi_agent_brief/outputs/naming.py +38 -0
  341. multi_agent_brief/outputs/pdf.py +20 -0
  342. multi_agent_brief/outputs/reader_final_gate.py +509 -0
  343. multi_agent_brief/outputs/reader_projection.py +397 -0
  344. multi_agent_brief/outputs/source_appendix.py +753 -0
  345. multi_agent_brief/outputs/templates/__init__.py +112 -0
  346. multi_agent_brief/product/__init__.py +49 -0
  347. multi_agent_brief/product/bundle_projection.py +686 -0
  348. multi_agent_brief/product/citation_profile.py +145 -0
  349. multi_agent_brief/product/guidance_manifestation.py +421 -0
  350. multi_agent_brief/product/materiality_selection.py +472 -0
  351. multi_agent_brief/product/policy_gate_adapter.py +116 -0
  352. multi_agent_brief/product/policy_profile.py +39 -0
  353. multi_agent_brief/product/policy_projection.py +161 -0
  354. multi_agent_brief/product/policy_registry.py +83 -0
  355. multi_agent_brief/product/policy_resolver.py +225 -0
  356. multi_agent_brief/product/quality_closeout.py +188 -0
  357. multi_agent_brief/product/quality_panel.py +2217 -0
  358. multi_agent_brief/product/release_approval.py +1034 -0
  359. multi_agent_brief/product/report_pack.py +130 -0
  360. multi_agent_brief/product/report_pack_aliases.py +68 -0
  361. multi_agent_brief/product/report_registry.py +101 -0
  362. multi_agent_brief/product/report_spec.py +181 -0
  363. multi_agent_brief/product/support_wording.py +525 -0
  364. multi_agent_brief/product/template_conformance.py +516 -0
  365. multi_agent_brief/product/template_projection.py +123 -0
  366. multi_agent_brief/product/template_registry.py +244 -0
  367. multi_agent_brief/product/template_render_plan.py +315 -0
  368. multi_agent_brief/product/template_renderer.py +224 -0
  369. multi_agent_brief/product/trajectory_regulation.py +441 -0
  370. multi_agent_brief/provenance/__init__.py +5 -0
  371. multi_agent_brief/provenance/builder.py +841 -0
  372. multi_agent_brief/provenance/contract.py +21 -0
  373. multi_agent_brief/provenance/io.py +144 -0
  374. multi_agent_brief/provenance/model.py +110 -0
  375. multi_agent_brief/provenance/references.py +43 -0
  376. multi_agent_brief/provenance/validator.py +135 -0
  377. multi_agent_brief/quality_gates/__init__.py +19 -0
  378. multi_agent_brief/quality_gates/contract.py +581 -0
  379. multi_agent_brief/quality_gates/state.py +2498 -0
  380. multi_agent_brief/repair/__init__.py +5 -0
  381. multi_agent_brief/repair/router.py +842 -0
  382. multi_agent_brief/runtime_assets.py +431 -0
  383. multi_agent_brief/sources/__init__.py +16 -0
  384. multi_agent_brief/sources/api_filings.py +236 -0
  385. multi_agent_brief/sources/api_news.py +174 -0
  386. multi_agent_brief/sources/base.py +142 -0
  387. multi_agent_brief/sources/cached_package.py +119 -0
  388. multi_agent_brief/sources/cli_provider.py +263 -0
  389. multi_agent_brief/sources/coverage.py +336 -0
  390. multi_agent_brief/sources/decider.py +756 -0
  391. multi_agent_brief/sources/doctor.py +373 -0
  392. multi_agent_brief/sources/evidence_pack.py +364 -0
  393. multi_agent_brief/sources/feishu_provider.py +326 -0
  394. multi_agent_brief/sources/filing_resolver.py +400 -0
  395. multi_agent_brief/sources/industry_packs.py +130 -0
  396. multi_agent_brief/sources/join.py +206 -0
  397. multi_agent_brief/sources/local_signal.py +81 -0
  398. multi_agent_brief/sources/local_signal_planner.py +636 -0
  399. multi_agent_brief/sources/manual.py +259 -0
  400. multi_agent_brief/sources/mcp_provider.py +309 -0
  401. multi_agent_brief/sources/mineru_provider.py +601 -0
  402. multi_agent_brief/sources/normalizer.py +95 -0
  403. multi_agent_brief/sources/opencli_provider.py +282 -0
  404. multi_agent_brief/sources/planner.py +178 -0
  405. multi_agent_brief/sources/registry.py +367 -0
  406. multi_agent_brief/sources/rss.py +190 -0
  407. multi_agent_brief/sources/search_backends/__init__.py +31 -0
  408. multi_agent_brief/sources/search_backends/base.py +51 -0
  409. multi_agent_brief/sources/search_backends/brave.py +192 -0
  410. multi_agent_brief/sources/search_backends/capabilities.py +94 -0
  411. multi_agent_brief/sources/search_backends/exa.py +180 -0
  412. multi_agent_brief/sources/search_backends/firecrawl.py +164 -0
  413. multi_agent_brief/sources/search_backends/serper.py +241 -0
  414. multi_agent_brief/sources/search_backends/tavily.py +124 -0
  415. multi_agent_brief/sources/sourcehub.py +505 -0
  416. multi_agent_brief/sources/web_search.py +267 -0
  417. multi_agent_brief/status.py +966 -0
  418. multi_agent_brief/tools/__init__.py +3 -0
  419. multi_agent_brief/tools/draft_cleanup.py +198 -0
  420. multi_agent_brief/workbuddy/__init__.py +1 -0
  421. multi_agent_brief/workbuddy/diagnose.py +569 -0
  422. multi_agent_brief/workbuddy/skill_pack.py +309 -0
  423. multi_agent_brief/workspace/__init__.py +1 -0
  424. multi_agent_brief/workspace/init_profile.py +45 -0
@@ -0,0 +1,1114 @@
1
+ """Side-effect-free Improvement Ledger contract.
2
+
3
+ The v0.7 Improvement Ledger is an append-only workspace contract for
4
+ human-approved audience guidance. This module validates ledger revisions,
5
+ computes current read state, and checks append preconditions. It deliberately
6
+ does not write files, append events, read runtime state, or materialize runtime
7
+ snapshots.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import hashlib
13
+ import json
14
+ import re
15
+ from dataclasses import dataclass
16
+ from datetime import datetime
17
+ from pathlib import Path, PurePosixPath, PureWindowsPath
18
+ from typing import Any
19
+
20
+
21
+ IMPROVEMENT_LEDGER_SCHEMA = "multi-agent-brief-improvement-ledger/v1"
22
+ LEDGER_RELATIVE_PATH = "improvement/ledger.jsonl"
23
+
24
+ ALLOWED_LEVEL = 2
25
+ ALLOWED_TARGET_KIND = "audience_guidance"
26
+ ALLOWED_STATUSES = {"proposed", "approved", "rejected", "reverted"}
27
+ TERMINAL_STATUSES = {"rejected", "reverted"}
28
+ ALLOWED_SOURCE_TYPES = {"human_feedback", "feedback_issue"}
29
+ AUDIENCE_GUIDANCE_CATEGORIES = {
30
+ "audience_mismatch",
31
+ "tone",
32
+ "structure",
33
+ "length",
34
+ "source_presentation",
35
+ "other",
36
+ }
37
+ AUDIENCE_GUIDANCE_SCOPES = {
38
+ "brief",
39
+ "executive_summary",
40
+ "section",
41
+ "source_appendix",
42
+ }
43
+ ALLOWED_ORIGIN_KEYS = {
44
+ "control_file",
45
+ "gate_id",
46
+ "finding_type",
47
+ "blocking_level",
48
+ "source_item_id",
49
+ "issue_category",
50
+ "issue_source",
51
+ "origin_runtime",
52
+ }
53
+ DIAGNOSTIC_SEVERITIES = {"info", "warning", "error"}
54
+ DIAGNOSTIC_CODES = {
55
+ "unknown_schema_version",
56
+ "invalid_entry_id",
57
+ "invalid_level",
58
+ "reserved_in_v0_7",
59
+ "invalid_target_kind",
60
+ "invalid_status",
61
+ "stored_applied_state_forbidden",
62
+ "invalid_revision_sequence",
63
+ "invalid_transition",
64
+ "missing_previous_revision",
65
+ "previous_revision_hash_mismatch",
66
+ "corrupt_trailing_line",
67
+ "corrupt_non_trailing_line",
68
+ "append_preflight_failed",
69
+ "unsafe_guidance_text",
70
+ "missing_approval_metadata",
71
+ "missing_source_evidence",
72
+ "invalid_source_evidence",
73
+ "invalid_timestamp",
74
+ "immutable_revision_field_changed",
75
+ "invalid_change",
76
+ "invalid_origin",
77
+ "invalid_approval_metadata",
78
+ "invalid_supersedes_id",
79
+ "unknown_supersedes_reference",
80
+ "supersession_cycle",
81
+ "supersession_fork",
82
+ }
83
+
84
+ MAX_GUIDANCE_TEXT_LENGTH = 500
85
+ MAX_EVIDENCE_SUMMARY_LENGTH = 300
86
+ MAX_SOURCE_REFERENCE_LENGTH = 160
87
+ MAX_ORIGIN_VALUE_LENGTH = 120
88
+ MAX_APPROVAL_REASON_LENGTH = 300
89
+
90
+ _ENTRY_ID_RE = re.compile(r"^AG-\d{4,}$")
91
+ _OPERATOR_ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.@-]{0,79}$")
92
+ _UTC_ISO_RE = re.compile(r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$")
93
+ _CONTROL_CHAR_RE = re.compile(r"[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]")
94
+ _WINDOWS_ABSOLUTE_RE = re.compile(r"\b[A-Za-z]:[\\/]")
95
+ _TOKEN_PATTERNS = [
96
+ re.compile(r"sk-[A-Za-z0-9_-]{16,}"),
97
+ re.compile(r"ghp_[A-Za-z0-9_]{16,}"),
98
+ re.compile(r"xox[baprs]-[A-Za-z0-9-]{10,}"),
99
+ re.compile(r"AKIA[0-9A-Z]{16}"),
100
+ re.compile(r"\b[A-Za-z0-9_-]{40,}\b"),
101
+ ]
102
+ _INJECTION_PHRASES = [
103
+ "system:",
104
+ "developer:",
105
+ "assistant:",
106
+ "ignore previous",
107
+ "ignore all previous",
108
+ ]
109
+ _FORBIDDEN_PATH_FRAGMENTS = [
110
+ "/Users/",
111
+ "/home/",
112
+ "/var/",
113
+ "file://",
114
+ ]
115
+
116
+
117
+ @dataclass(frozen=True)
118
+ class LedgerDiagnostic:
119
+ code: str
120
+ severity: str
121
+ message: str
122
+ line_number: int | None = None
123
+ entry_id: str | None = None
124
+ revision: int | None = None
125
+
126
+ def __post_init__(self) -> None:
127
+ if self.severity not in DIAGNOSTIC_SEVERITIES:
128
+ raise ValueError(f"Unsupported diagnostic severity: {self.severity}")
129
+ if self.code not in DIAGNOSTIC_CODES:
130
+ raise ValueError(f"Unsupported diagnostic code: {self.code}")
131
+
132
+
133
+ @dataclass(frozen=True)
134
+ class LedgerReadResult:
135
+ valid_revisions: list[dict[str, Any]]
136
+ current_entries: dict[str, dict[str, Any]]
137
+ diagnostics: list[LedgerDiagnostic]
138
+
139
+
140
+ @dataclass(frozen=True)
141
+ class AppendPreflightResult:
142
+ ok: bool
143
+ diagnostics: list[LedgerDiagnostic]
144
+
145
+
146
+ def canonical_json(payload: dict[str, Any]) -> str:
147
+ """Return the canonical JSON string used for revision hash chaining."""
148
+ return json.dumps(payload, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
149
+
150
+
151
+ def revision_sha256(payload: dict[str, Any]) -> str:
152
+ """Return SHA-256 of a revision's full canonical JSON."""
153
+ return hashlib.sha256(canonical_json(payload).encode("utf-8")).hexdigest()
154
+
155
+
156
+ def current_entries_from_revisions(revisions: list[dict[str, Any]]) -> dict[str, dict[str, Any]]:
157
+ """Return the highest valid revision for each entry_id."""
158
+ current: dict[str, dict[str, Any]] = {}
159
+ for revision in revisions:
160
+ entry_id = str(revision.get("entry_id") or "")
161
+ if not entry_id:
162
+ continue
163
+ existing = current.get(entry_id)
164
+ if existing is None or int(revision.get("revision", 0)) > int(existing.get("revision", 0)):
165
+ current[entry_id] = revision
166
+ return current
167
+
168
+
169
+ def supersedes_id(entry: dict[str, Any]) -> str | None:
170
+ """Return normalized supersedes_id; missing and null are semantically equal."""
171
+ value = entry.get("supersedes_id")
172
+ if value is None:
173
+ return None
174
+ if isinstance(value, str) and value.strip():
175
+ return value.strip()
176
+ return None
177
+
178
+
179
+ def read_ledger_text(text: str) -> LedgerReadResult:
180
+ """Parse ledger JSONL text into valid revisions and diagnostics.
181
+
182
+ A corrupt trailing line is reported as a warning and valid prior revisions
183
+ remain readable. A corrupt middle line is fatal for the remaining file:
184
+ later lines are ignored because the append-only chain is no longer trusted.
185
+ """
186
+ diagnostics: list[LedgerDiagnostic] = []
187
+ valid_revisions: list[dict[str, Any]] = []
188
+ previous_by_entry: dict[str, dict[str, Any]] = {}
189
+ lines = text.splitlines()
190
+
191
+ for idx, line in enumerate(lines, start=1):
192
+ is_trailing = idx == len(lines)
193
+ if not line.strip():
194
+ code = "corrupt_trailing_line" if is_trailing else "corrupt_non_trailing_line"
195
+ severity = "warning" if is_trailing else "error"
196
+ diagnostics.append(_diag(
197
+ code,
198
+ severity,
199
+ "Ledger JSONL line is blank.",
200
+ line_number=idx,
201
+ ))
202
+ if not is_trailing:
203
+ break
204
+ continue
205
+ try:
206
+ payload = json.loads(line)
207
+ except json.JSONDecodeError as exc:
208
+ code = "corrupt_trailing_line" if is_trailing else "corrupt_non_trailing_line"
209
+ severity = "warning" if is_trailing else "error"
210
+ diagnostics.append(_diag(
211
+ code,
212
+ severity,
213
+ f"Ledger JSONL line is not valid JSON: {exc}",
214
+ line_number=idx,
215
+ ))
216
+ break
217
+ if not isinstance(payload, dict):
218
+ diagnostics.append(_diag(
219
+ "corrupt_trailing_line" if is_trailing else "corrupt_non_trailing_line",
220
+ "warning" if is_trailing else "error",
221
+ "Ledger JSONL line must contain an object.",
222
+ line_number=idx,
223
+ ))
224
+ if not is_trailing:
225
+ break
226
+ continue
227
+
228
+ entry_id = str(payload.get("entry_id") or "")
229
+ previous = previous_by_entry.get(entry_id)
230
+ errors = validate_revision_payload(payload, previous_revision=previous, line_number=idx)
231
+ diagnostics.extend(errors)
232
+ if any(item.severity == "error" for item in errors):
233
+ if not is_trailing:
234
+ break
235
+ continue
236
+ valid_revisions.append(payload)
237
+ previous_by_entry[entry_id] = payload
238
+
239
+ current_entries = current_entries_from_revisions(valid_revisions)
240
+ diagnostics.extend(_validate_supersession_graph(current_entries))
241
+ return LedgerReadResult(
242
+ valid_revisions=valid_revisions,
243
+ current_entries=current_entries,
244
+ diagnostics=diagnostics,
245
+ )
246
+
247
+
248
+ def validate_append_preflight(text: str) -> AppendPreflightResult:
249
+ """Validate whether an existing ledger text is safe to append to."""
250
+ if text == "":
251
+ return AppendPreflightResult(ok=True, diagnostics=[])
252
+ diagnostics: list[LedgerDiagnostic] = []
253
+ if not text.endswith("\n"):
254
+ diagnostics.append(_diag(
255
+ "append_preflight_failed",
256
+ "error",
257
+ "Existing ledger must end with a newline before appending.",
258
+ ))
259
+ read_result = read_ledger_text(text)
260
+ diagnostics.extend(read_result.diagnostics)
261
+ if read_result.valid_revisions and len(read_result.valid_revisions) != _non_empty_line_count(text):
262
+ diagnostics.append(_diag(
263
+ "append_preflight_failed",
264
+ "error",
265
+ "Existing ledger contains invalid or untrusted JSONL lines.",
266
+ ))
267
+ if not read_result.valid_revisions and _non_empty_line_count(text) > 0:
268
+ diagnostics.append(_diag(
269
+ "append_preflight_failed",
270
+ "error",
271
+ "Existing ledger contains no valid append base.",
272
+ ))
273
+ ok = not any(item.severity in {"warning", "error"} for item in diagnostics)
274
+ return AppendPreflightResult(ok=ok, diagnostics=_dedupe_diagnostics(diagnostics))
275
+
276
+
277
+ def validate_next_revision(existing_text: str, revision: dict[str, Any]) -> AppendPreflightResult:
278
+ """Validate append preflight plus the next revision payload."""
279
+ preflight = validate_append_preflight(existing_text)
280
+ if not preflight.ok:
281
+ return preflight
282
+ read_result = read_ledger_text(existing_text)
283
+ entry_id = str(revision.get("entry_id") or "")
284
+ previous = read_result.current_entries.get(entry_id)
285
+ diagnostics = validate_revision_payload(revision, previous_revision=previous)
286
+ if not any(item.severity == "error" for item in diagnostics):
287
+ current_entries = current_entries_from_revisions([*read_result.valid_revisions, revision])
288
+ diagnostics.extend(_validate_supersession_graph(current_entries))
289
+ return AppendPreflightResult(
290
+ ok=not any(item.severity == "error" for item in diagnostics),
291
+ diagnostics=diagnostics,
292
+ )
293
+
294
+
295
+ def validate_revision_payload(
296
+ payload: dict[str, Any],
297
+ *,
298
+ previous_revision: dict[str, Any] | None = None,
299
+ line_number: int | None = None,
300
+ ) -> list[LedgerDiagnostic]:
301
+ """Validate one complete ledger revision payload."""
302
+ diagnostics: list[LedgerDiagnostic] = []
303
+ entry_id = payload.get("entry_id")
304
+ revision = payload.get("revision")
305
+ entry_id_text = str(entry_id) if entry_id is not None else None
306
+ revision_number = revision if isinstance(revision, int) else None
307
+
308
+ if payload.get("schema_version") != IMPROVEMENT_LEDGER_SCHEMA:
309
+ diagnostics.append(_diag(
310
+ "unknown_schema_version",
311
+ "error",
312
+ "Ledger revision has an unsupported schema_version.",
313
+ line_number=line_number,
314
+ entry_id=entry_id_text,
315
+ revision=revision_number,
316
+ ))
317
+
318
+ if not isinstance(entry_id, str) or not _ENTRY_ID_RE.match(entry_id):
319
+ diagnostics.append(_diag(
320
+ "invalid_entry_id",
321
+ "error",
322
+ "entry_id must match AG-0001 style.",
323
+ line_number=line_number,
324
+ entry_id=entry_id_text,
325
+ revision=revision_number,
326
+ ))
327
+
328
+ diagnostics.extend(_validate_supersedes_id(
329
+ payload,
330
+ line_number=line_number,
331
+ entry_id=entry_id_text,
332
+ revision=revision_number,
333
+ ))
334
+
335
+ if not isinstance(revision, int) or revision < 1:
336
+ diagnostics.append(_diag(
337
+ "invalid_revision_sequence",
338
+ "error",
339
+ "revision must be a positive integer.",
340
+ line_number=line_number,
341
+ entry_id=entry_id_text,
342
+ revision=revision_number,
343
+ ))
344
+ revision_number = None
345
+
346
+ if not _is_utc_timestamp(payload.get("created_at")):
347
+ diagnostics.append(_diag(
348
+ "invalid_timestamp",
349
+ "error",
350
+ "created_at must be a UTC ISO-like timestamp such as 2026-06-10T00:00:00Z.",
351
+ line_number=line_number,
352
+ entry_id=entry_id_text,
353
+ revision=revision_number,
354
+ ))
355
+
356
+ status = payload.get("status")
357
+ if status == "applied":
358
+ diagnostics.append(_diag(
359
+ "stored_applied_state_forbidden",
360
+ "error",
361
+ "applied is a per-run manifest fact, not a stored ledger state.",
362
+ line_number=line_number,
363
+ entry_id=entry_id_text,
364
+ revision=revision_number,
365
+ ))
366
+ elif status not in ALLOWED_STATUSES:
367
+ diagnostics.append(_diag(
368
+ "invalid_status",
369
+ "error",
370
+ f"status must be one of {sorted(ALLOWED_STATUSES)}.",
371
+ line_number=line_number,
372
+ entry_id=entry_id_text,
373
+ revision=revision_number,
374
+ ))
375
+
376
+ level = payload.get("level")
377
+ if level != ALLOWED_LEVEL:
378
+ code = "reserved_in_v0_7" if level in {0, 1, 3, 4} else "invalid_level"
379
+ diagnostics.append(_diag(
380
+ code,
381
+ "error",
382
+ "Only level=2 Improvement Ledger entries are active in v0.7.",
383
+ line_number=line_number,
384
+ entry_id=entry_id_text,
385
+ revision=revision_number,
386
+ ))
387
+
388
+ target_kind = payload.get("target_kind")
389
+ if target_kind == "workspace_memory":
390
+ diagnostics.append(_diag(
391
+ "reserved_in_v0_7",
392
+ "error",
393
+ "workspace_memory is rejected in v0.7.",
394
+ line_number=line_number,
395
+ entry_id=entry_id_text,
396
+ revision=revision_number,
397
+ ))
398
+ elif target_kind != ALLOWED_TARGET_KIND:
399
+ diagnostics.append(_diag(
400
+ "invalid_target_kind",
401
+ "error",
402
+ "Only target_kind=audience_guidance is active in v0.7.",
403
+ line_number=line_number,
404
+ entry_id=entry_id_text,
405
+ revision=revision_number,
406
+ ))
407
+
408
+ diagnostics.extend(_validate_revision_chain(
409
+ payload,
410
+ previous_revision=previous_revision,
411
+ line_number=line_number,
412
+ entry_id=entry_id_text,
413
+ revision=revision_number,
414
+ ))
415
+ diagnostics.extend(_validate_transition(
416
+ payload,
417
+ previous_revision=previous_revision,
418
+ line_number=line_number,
419
+ entry_id=entry_id_text,
420
+ revision=revision_number,
421
+ ))
422
+ diagnostics.extend(_validate_immutable_status_revision(
423
+ payload,
424
+ previous_revision=previous_revision,
425
+ line_number=line_number,
426
+ entry_id=entry_id_text,
427
+ revision=revision_number,
428
+ ))
429
+ diagnostics.extend(_validate_change(
430
+ payload.get("change"),
431
+ line_number=line_number,
432
+ entry_id=entry_id_text,
433
+ revision=revision_number,
434
+ ))
435
+ diagnostics.extend(_validate_source_evidence(
436
+ payload.get("source_evidence"),
437
+ line_number=line_number,
438
+ entry_id=entry_id_text,
439
+ revision=revision_number,
440
+ ))
441
+ diagnostics.extend(_validate_status_metadata(
442
+ payload,
443
+ line_number=line_number,
444
+ entry_id=entry_id_text,
445
+ revision=revision_number,
446
+ ))
447
+ return diagnostics
448
+
449
+
450
+ def validate_guidance_text(text: Any) -> list[LedgerDiagnostic]:
451
+ diagnostics: list[LedgerDiagnostic] = []
452
+ if not isinstance(text, str) or not text.strip():
453
+ return [_diag("unsafe_guidance_text", "error", "guidance_text must be a non-empty string.")]
454
+ if len(text) > MAX_GUIDANCE_TEXT_LENGTH:
455
+ diagnostics.append(_diag("unsafe_guidance_text", "error", "guidance_text is too long."))
456
+ diagnostics.extend(_text_hygiene_diagnostics(text, code="unsafe_guidance_text", label="guidance_text"))
457
+ return diagnostics
458
+
459
+
460
+ def _validate_revision_chain(
461
+ payload: dict[str, Any],
462
+ *,
463
+ previous_revision: dict[str, Any] | None,
464
+ line_number: int | None,
465
+ entry_id: str | None,
466
+ revision: int | None,
467
+ ) -> list[LedgerDiagnostic]:
468
+ diagnostics: list[LedgerDiagnostic] = []
469
+ if revision is None:
470
+ return diagnostics
471
+
472
+ if "previous_revision_sha256" not in payload:
473
+ diagnostics.append(_diag(
474
+ "missing_previous_revision",
475
+ "error",
476
+ "previous_revision_sha256 is required and must be null for revision 1.",
477
+ line_number=line_number,
478
+ entry_id=entry_id,
479
+ revision=revision,
480
+ ))
481
+ return diagnostics
482
+
483
+ previous_hash = payload.get("previous_revision_sha256")
484
+ if revision == 1:
485
+ if previous_revision is not None:
486
+ diagnostics.append(_diag(
487
+ "invalid_revision_sequence",
488
+ "error",
489
+ "revision 1 cannot follow an existing revision for the same entry.",
490
+ line_number=line_number,
491
+ entry_id=entry_id,
492
+ revision=revision,
493
+ ))
494
+ if previous_hash is not None:
495
+ diagnostics.append(_diag(
496
+ "missing_previous_revision",
497
+ "error",
498
+ "revision 1 must explicitly set previous_revision_sha256 to null.",
499
+ line_number=line_number,
500
+ entry_id=entry_id,
501
+ revision=revision,
502
+ ))
503
+ return diagnostics
504
+
505
+ if previous_revision is None:
506
+ diagnostics.append(_diag(
507
+ "missing_previous_revision",
508
+ "error",
509
+ "revision > 1 requires a previous revision for the same entry_id.",
510
+ line_number=line_number,
511
+ entry_id=entry_id,
512
+ revision=revision,
513
+ ))
514
+ return diagnostics
515
+
516
+ expected_revision = int(previous_revision.get("revision", 0)) + 1
517
+ if revision != expected_revision:
518
+ diagnostics.append(_diag(
519
+ "invalid_revision_sequence",
520
+ "error",
521
+ f"revision must increment monotonically to {expected_revision}.",
522
+ line_number=line_number,
523
+ entry_id=entry_id,
524
+ revision=revision,
525
+ ))
526
+ expected_hash = revision_sha256(previous_revision)
527
+ if previous_hash != expected_hash:
528
+ diagnostics.append(_diag(
529
+ "previous_revision_hash_mismatch",
530
+ "error",
531
+ "previous_revision_sha256 must match the immediately previous revision canonical hash.",
532
+ line_number=line_number,
533
+ entry_id=entry_id,
534
+ revision=revision,
535
+ ))
536
+ return diagnostics
537
+
538
+
539
+ def _validate_transition(
540
+ payload: dict[str, Any],
541
+ *,
542
+ previous_revision: dict[str, Any] | None,
543
+ line_number: int | None,
544
+ entry_id: str | None,
545
+ revision: int | None,
546
+ ) -> list[LedgerDiagnostic]:
547
+ status = payload.get("status")
548
+ if status not in ALLOWED_STATUSES:
549
+ return []
550
+ if previous_revision is None:
551
+ if status != "proposed":
552
+ return [_diag(
553
+ "invalid_transition",
554
+ "error",
555
+ "revision 1 must start in proposed state.",
556
+ line_number=line_number,
557
+ entry_id=entry_id,
558
+ revision=revision,
559
+ )]
560
+ return []
561
+
562
+ previous_status = previous_revision.get("status")
563
+ allowed = {
564
+ "proposed": {"approved", "rejected"},
565
+ "approved": {"reverted"},
566
+ "rejected": set(),
567
+ "reverted": set(),
568
+ }
569
+ if status not in allowed.get(str(previous_status), set()):
570
+ return [_diag(
571
+ "invalid_transition",
572
+ "error",
573
+ f"Invalid ledger transition: {previous_status} -> {status}.",
574
+ line_number=line_number,
575
+ entry_id=entry_id,
576
+ revision=revision,
577
+ )]
578
+ return []
579
+
580
+
581
+ def _validate_immutable_status_revision(
582
+ payload: dict[str, Any],
583
+ *,
584
+ previous_revision: dict[str, Any] | None,
585
+ line_number: int | None,
586
+ entry_id: str | None,
587
+ revision: int | None,
588
+ ) -> list[LedgerDiagnostic]:
589
+ """Status-only transitions must not rewrite approved guidance content."""
590
+ if previous_revision is None:
591
+ return []
592
+ diagnostics: list[LedgerDiagnostic] = []
593
+ for field in ("level", "target_kind", "change", "source_evidence"):
594
+ if payload.get(field) != previous_revision.get(field):
595
+ diagnostics.append(_diag(
596
+ "immutable_revision_field_changed",
597
+ "error",
598
+ f"{field} must remain unchanged across status transitions.",
599
+ line_number=line_number,
600
+ entry_id=entry_id,
601
+ revision=revision,
602
+ ))
603
+ if supersedes_id(payload) != supersedes_id(previous_revision):
604
+ diagnostics.append(_diag(
605
+ "immutable_revision_field_changed",
606
+ "error",
607
+ "supersedes_id must remain unchanged across status transitions.",
608
+ line_number=line_number,
609
+ entry_id=entry_id,
610
+ revision=revision,
611
+ ))
612
+ return diagnostics
613
+
614
+
615
+ def _validate_supersedes_id(
616
+ payload: dict[str, Any],
617
+ *,
618
+ line_number: int | None,
619
+ entry_id: str | None,
620
+ revision: int | None,
621
+ ) -> list[LedgerDiagnostic]:
622
+ if "supersedes_id" not in payload:
623
+ return []
624
+ value = payload.get("supersedes_id")
625
+ if value is None:
626
+ return []
627
+ if not isinstance(value, str) or not _ENTRY_ID_RE.match(value):
628
+ return [_diag(
629
+ "invalid_supersedes_id",
630
+ "error",
631
+ "supersedes_id must be null or match AG-0001 style.",
632
+ line_number=line_number,
633
+ entry_id=entry_id,
634
+ revision=revision,
635
+ )]
636
+ if entry_id and value == entry_id:
637
+ return [_diag(
638
+ "invalid_supersedes_id",
639
+ "error",
640
+ "supersedes_id must not reference the same entry.",
641
+ line_number=line_number,
642
+ entry_id=entry_id,
643
+ revision=revision,
644
+ )]
645
+ return []
646
+
647
+
648
+ def _validate_change(
649
+ change: Any,
650
+ *,
651
+ line_number: int | None,
652
+ entry_id: str | None,
653
+ revision: int | None,
654
+ ) -> list[LedgerDiagnostic]:
655
+ if not isinstance(change, dict):
656
+ return [_diag(
657
+ "invalid_change",
658
+ "error",
659
+ "change must be an object containing guidance_text.",
660
+ line_number=line_number,
661
+ entry_id=entry_id,
662
+ revision=revision,
663
+ )]
664
+ diagnostics: list[LedgerDiagnostic] = []
665
+ category = change.get("category")
666
+ if category not in AUDIENCE_GUIDANCE_CATEGORIES:
667
+ diagnostics.append(_diag(
668
+ "invalid_change",
669
+ "error",
670
+ f"change.category must be one of {sorted(AUDIENCE_GUIDANCE_CATEGORIES)}.",
671
+ line_number=line_number,
672
+ entry_id=entry_id,
673
+ revision=revision,
674
+ ))
675
+ scope = change.get("scope")
676
+ if scope not in AUDIENCE_GUIDANCE_SCOPES:
677
+ diagnostics.append(_diag(
678
+ "invalid_change",
679
+ "error",
680
+ f"change.scope must be one of {sorted(AUDIENCE_GUIDANCE_SCOPES)}.",
681
+ line_number=line_number,
682
+ entry_id=entry_id,
683
+ revision=revision,
684
+ ))
685
+ for diagnostic in validate_guidance_text(change.get("guidance_text")):
686
+ diagnostics.append(_diag(
687
+ diagnostic.code,
688
+ diagnostic.severity,
689
+ diagnostic.message,
690
+ line_number=line_number,
691
+ entry_id=entry_id,
692
+ revision=revision,
693
+ ))
694
+ return diagnostics
695
+
696
+
697
+ def _validate_source_evidence(
698
+ evidence: Any,
699
+ *,
700
+ line_number: int | None,
701
+ entry_id: str | None,
702
+ revision: int | None,
703
+ ) -> list[LedgerDiagnostic]:
704
+ if not isinstance(evidence, list) or not evidence:
705
+ return [_diag(
706
+ "missing_source_evidence",
707
+ "error",
708
+ "source_evidence must be a non-empty list.",
709
+ line_number=line_number,
710
+ entry_id=entry_id,
711
+ revision=revision,
712
+ )]
713
+ diagnostics: list[LedgerDiagnostic] = []
714
+ for idx, item in enumerate(evidence):
715
+ if not isinstance(item, dict):
716
+ diagnostics.append(_diag(
717
+ "invalid_source_evidence",
718
+ "error",
719
+ f"source_evidence[{idx}] must be an object.",
720
+ line_number=line_number,
721
+ entry_id=entry_id,
722
+ revision=revision,
723
+ ))
724
+ continue
725
+ source_type = item.get("source_type")
726
+ if source_type not in ALLOWED_SOURCE_TYPES:
727
+ diagnostics.append(_diag(
728
+ "invalid_source_evidence",
729
+ "error",
730
+ f"source_evidence[{idx}].source_type must be one of {sorted(ALLOWED_SOURCE_TYPES)}.",
731
+ line_number=line_number,
732
+ entry_id=entry_id,
733
+ revision=revision,
734
+ ))
735
+ elif source_type == "feedback_issue":
736
+ for ref_key in ("issue_id", "run_id"):
737
+ ref_value = item.get(ref_key)
738
+ if not isinstance(ref_value, str) or not ref_value.strip():
739
+ diagnostics.append(_diag(
740
+ "invalid_source_evidence",
741
+ "error",
742
+ f"source_evidence[{idx}].{ref_key} is required for feedback_issue evidence.",
743
+ line_number=line_number,
744
+ entry_id=entry_id,
745
+ revision=revision,
746
+ ))
747
+ continue
748
+ if len(ref_value) > MAX_SOURCE_REFERENCE_LENGTH:
749
+ diagnostics.append(_diag(
750
+ "invalid_source_evidence",
751
+ "error",
752
+ f"source_evidence[{idx}].{ref_key} is too long.",
753
+ line_number=line_number,
754
+ entry_id=entry_id,
755
+ revision=revision,
756
+ ))
757
+ if "/" in ref_value or "\\" in ref_value:
758
+ diagnostics.append(_diag(
759
+ "invalid_source_evidence",
760
+ "error",
761
+ f"source_evidence[{idx}].{ref_key} must not contain path separators.",
762
+ line_number=line_number,
763
+ entry_id=entry_id,
764
+ revision=revision,
765
+ ))
766
+ for diagnostic in _text_hygiene_diagnostics(
767
+ ref_value,
768
+ code="invalid_source_evidence",
769
+ label=f"source_evidence[{idx}].{ref_key}",
770
+ allow_single_sentence=True,
771
+ ):
772
+ diagnostics.append(_diag(
773
+ diagnostic.code,
774
+ diagnostic.severity,
775
+ diagnostic.message,
776
+ line_number=line_number,
777
+ entry_id=entry_id,
778
+ revision=revision,
779
+ ))
780
+ summary = item.get("summary")
781
+ if not isinstance(summary, str) or not summary.strip():
782
+ diagnostics.append(_diag(
783
+ "invalid_source_evidence",
784
+ "error",
785
+ f"source_evidence[{idx}].summary is required.",
786
+ line_number=line_number,
787
+ entry_id=entry_id,
788
+ revision=revision,
789
+ ))
790
+ elif len(summary) > MAX_EVIDENCE_SUMMARY_LENGTH:
791
+ diagnostics.append(_diag(
792
+ "invalid_source_evidence",
793
+ "error",
794
+ f"source_evidence[{idx}].summary is too long.",
795
+ line_number=line_number,
796
+ entry_id=entry_id,
797
+ revision=revision,
798
+ ))
799
+ else:
800
+ for diagnostic in _text_hygiene_diagnostics(
801
+ summary,
802
+ code="invalid_source_evidence",
803
+ label=f"source_evidence[{idx}].summary",
804
+ allow_single_sentence=True,
805
+ ):
806
+ diagnostics.append(_diag(
807
+ diagnostic.code,
808
+ diagnostic.severity,
809
+ diagnostic.message,
810
+ line_number=line_number,
811
+ entry_id=entry_id,
812
+ revision=revision,
813
+ ))
814
+ origin = item.get("origin")
815
+ if origin is not None and not isinstance(origin, dict):
816
+ diagnostics.append(_diag(
817
+ "invalid_origin",
818
+ "error",
819
+ f"source_evidence[{idx}].origin must be an object when present.",
820
+ line_number=line_number,
821
+ entry_id=entry_id,
822
+ revision=revision,
823
+ ))
824
+ elif isinstance(origin, dict):
825
+ diagnostics.extend(_validate_origin(
826
+ origin,
827
+ prefix=f"source_evidence[{idx}].origin",
828
+ line_number=line_number,
829
+ entry_id=entry_id,
830
+ revision=revision,
831
+ ))
832
+ return diagnostics
833
+
834
+
835
+ def _validate_status_metadata(
836
+ payload: dict[str, Any],
837
+ *,
838
+ line_number: int | None,
839
+ entry_id: str | None,
840
+ revision: int | None,
841
+ ) -> list[LedgerDiagnostic]:
842
+ status = payload.get("status")
843
+ requirements = {
844
+ "approved": [("approved_by", "text"), ("approved_at", "time")],
845
+ "rejected": [("rejected_by", "text"), ("rejected_at", "time"), ("rejection_reason", "text")],
846
+ "reverted": [("reverted_by", "text"), ("reverted_at", "time"), ("revert_reason", "text")],
847
+ }
848
+ diagnostics: list[LedgerDiagnostic] = []
849
+ for field, field_type in requirements.get(str(status), []):
850
+ value = payload.get(field)
851
+ if field_type == "time":
852
+ if not _is_utc_timestamp(value):
853
+ diagnostics.append(_diag(
854
+ "missing_approval_metadata",
855
+ "error",
856
+ f"{field} is required and must be UTC ISO-like timestamp.",
857
+ line_number=line_number,
858
+ entry_id=entry_id,
859
+ revision=revision,
860
+ ))
861
+ elif not isinstance(value, str) or not value.strip():
862
+ diagnostics.append(_diag(
863
+ "missing_approval_metadata",
864
+ "error",
865
+ f"{field} is required.",
866
+ line_number=line_number,
867
+ entry_id=entry_id,
868
+ revision=revision,
869
+ ))
870
+ elif field.endswith("_by") and not _OPERATOR_ID_RE.match(value):
871
+ diagnostics.append(_diag(
872
+ "invalid_approval_metadata",
873
+ "error",
874
+ f"{field} must be a compact operator id.",
875
+ line_number=line_number,
876
+ entry_id=entry_id,
877
+ revision=revision,
878
+ ))
879
+ elif field.endswith("_reason"):
880
+ if len(value) > MAX_APPROVAL_REASON_LENGTH:
881
+ diagnostics.append(_diag(
882
+ "invalid_approval_metadata",
883
+ "error",
884
+ f"{field} is too long.",
885
+ line_number=line_number,
886
+ entry_id=entry_id,
887
+ revision=revision,
888
+ ))
889
+ for diagnostic in _text_hygiene_diagnostics(
890
+ value,
891
+ code="invalid_approval_metadata",
892
+ label=field,
893
+ allow_single_sentence=True,
894
+ ):
895
+ diagnostics.append(_diag(
896
+ diagnostic.code,
897
+ diagnostic.severity,
898
+ diagnostic.message,
899
+ line_number=line_number,
900
+ entry_id=entry_id,
901
+ revision=revision,
902
+ ))
903
+ return diagnostics
904
+
905
+
906
+ def _validate_origin(
907
+ origin: dict[str, Any],
908
+ *,
909
+ prefix: str,
910
+ line_number: int | None,
911
+ entry_id: str | None,
912
+ revision: int | None,
913
+ ) -> list[LedgerDiagnostic]:
914
+ diagnostics: list[LedgerDiagnostic] = []
915
+ for key, value in origin.items():
916
+ if key not in ALLOWED_ORIGIN_KEYS:
917
+ diagnostics.append(_diag(
918
+ "invalid_origin",
919
+ "error",
920
+ f"{prefix}.{key} is not an allowed origin field.",
921
+ line_number=line_number,
922
+ entry_id=entry_id,
923
+ revision=revision,
924
+ ))
925
+ continue
926
+ if not isinstance(value, str) or not value.strip():
927
+ diagnostics.append(_diag(
928
+ "invalid_origin",
929
+ "error",
930
+ f"{prefix}.{key} must be a non-empty string.",
931
+ line_number=line_number,
932
+ entry_id=entry_id,
933
+ revision=revision,
934
+ ))
935
+ continue
936
+ if len(value) > MAX_ORIGIN_VALUE_LENGTH:
937
+ diagnostics.append(_diag(
938
+ "invalid_origin",
939
+ "error",
940
+ f"{prefix}.{key} is too long.",
941
+ line_number=line_number,
942
+ entry_id=entry_id,
943
+ revision=revision,
944
+ ))
945
+ if "/" in value or "\\" in value:
946
+ diagnostics.append(_diag(
947
+ "invalid_origin",
948
+ "error",
949
+ f"{prefix}.{key} must not contain path separators.",
950
+ line_number=line_number,
951
+ entry_id=entry_id,
952
+ revision=revision,
953
+ ))
954
+ for diagnostic in _text_hygiene_diagnostics(
955
+ value,
956
+ code="invalid_origin",
957
+ label=f"{prefix}.{key}",
958
+ allow_single_sentence=True,
959
+ ):
960
+ diagnostics.append(_diag(
961
+ diagnostic.code,
962
+ diagnostic.severity,
963
+ diagnostic.message,
964
+ line_number=line_number,
965
+ entry_id=entry_id,
966
+ revision=revision,
967
+ ))
968
+ return diagnostics
969
+
970
+
971
+ def _validate_supersession_graph(current_entries: dict[str, dict[str, Any]]) -> list[LedgerDiagnostic]:
972
+ diagnostics: list[LedgerDiagnostic] = []
973
+ graph: dict[str, str] = {}
974
+ approved_superseders_by_target: dict[str, list[str]] = {}
975
+ for entry_id, entry in current_entries.items():
976
+ target_id = supersedes_id(entry)
977
+ if target_id is None:
978
+ continue
979
+ graph[entry_id] = target_id
980
+ if entry.get("status") == "approved":
981
+ approved_superseders_by_target.setdefault(target_id, []).append(entry_id)
982
+ if target_id not in current_entries:
983
+ diagnostics.append(_diag(
984
+ "unknown_supersedes_reference",
985
+ "error",
986
+ f"supersedes_id references unknown entry {target_id}.",
987
+ entry_id=entry_id,
988
+ revision=entry.get("revision") if isinstance(entry.get("revision"), int) else None,
989
+ ))
990
+
991
+ for entry_id in sorted(graph):
992
+ seen: set[str] = set()
993
+ cursor = entry_id
994
+ while cursor in graph:
995
+ if cursor in seen:
996
+ diagnostics.append(_diag(
997
+ "supersession_cycle",
998
+ "error",
999
+ f"supersession cycle detected at {cursor}.",
1000
+ entry_id=entry_id,
1001
+ revision=(
1002
+ current_entries.get(entry_id, {}).get("revision")
1003
+ if isinstance(current_entries.get(entry_id, {}).get("revision"), int)
1004
+ else None
1005
+ ),
1006
+ ))
1007
+ break
1008
+ seen.add(cursor)
1009
+ cursor = graph[cursor]
1010
+ for target_id, superseders in sorted(approved_superseders_by_target.items()):
1011
+ if len(superseders) <= 1:
1012
+ continue
1013
+ diagnostics.append(_diag(
1014
+ "supersession_fork",
1015
+ "error",
1016
+ (
1017
+ f"Multiple approved entries supersede {target_id}: "
1018
+ f"{', '.join(sorted(superseders))}."
1019
+ ),
1020
+ entry_id=target_id,
1021
+ ))
1022
+ return diagnostics
1023
+
1024
+
1025
+ def _text_hygiene_diagnostics(
1026
+ text: str,
1027
+ *,
1028
+ code: str,
1029
+ label: str,
1030
+ allow_single_sentence: bool = False,
1031
+ ) -> list[LedgerDiagnostic]:
1032
+ diagnostics: list[LedgerDiagnostic] = []
1033
+ lower = text.lower()
1034
+ if "\n" in text or "\r" in text:
1035
+ diagnostics.append(_diag(code, "error", f"{label} must be a single paragraph."))
1036
+ if text.lstrip().startswith("#") or any(line.lstrip().startswith("#") for line in text.splitlines()):
1037
+ diagnostics.append(_diag(code, "error", f"{label} must not contain Markdown headings."))
1038
+ if "```" in text or "~~~" in text:
1039
+ diagnostics.append(_diag(code, "error", f"{label} must not contain code fences."))
1040
+ if "<!--" in text or "-->" in text:
1041
+ diagnostics.append(_diag(code, "error", f"{label} must not contain HTML comments."))
1042
+ if _CONTROL_CHAR_RE.search(text):
1043
+ diagnostics.append(_diag(code, "error", f"{label} must not contain control characters."))
1044
+ if any(fragment.lower() in lower for fragment in _FORBIDDEN_PATH_FRAGMENTS) or _WINDOWS_ABSOLUTE_RE.search(text):
1045
+ diagnostics.append(_diag(code, "error", f"{label} must not contain local absolute paths."))
1046
+ if _path_is_absolute_any_platform(text.strip()):
1047
+ diagnostics.append(_diag(code, "error", f"{label} must not be a local absolute path."))
1048
+ if any(pattern.search(text) for pattern in _TOKEN_PATTERNS):
1049
+ diagnostics.append(_diag(code, "error", f"{label} must not contain token-like strings."))
1050
+ if any(phrase in lower for phrase in _INJECTION_PHRASES):
1051
+ diagnostics.append(_diag(code, "error", f"{label} must not contain role or prompt-injection phrases."))
1052
+ if not allow_single_sentence and not text.strip():
1053
+ diagnostics.append(_diag(code, "error", f"{label} must not be empty."))
1054
+ return diagnostics
1055
+
1056
+
1057
+ def _is_utc_timestamp(value: Any) -> bool:
1058
+ if not isinstance(value, str) or not _UTC_ISO_RE.match(value):
1059
+ return False
1060
+ try:
1061
+ datetime.strptime(value, "%Y-%m-%dT%H:%M:%SZ")
1062
+ except ValueError:
1063
+ return False
1064
+ return True
1065
+
1066
+
1067
+ def _path_is_absolute_any_platform(value: str) -> bool:
1068
+ return (
1069
+ Path(value).is_absolute()
1070
+ or PurePosixPath(value).is_absolute()
1071
+ or PureWindowsPath(value).is_absolute()
1072
+ )
1073
+
1074
+
1075
+ def _non_empty_line_count(text: str) -> int:
1076
+ return sum(1 for line in text.splitlines() if line.strip())
1077
+
1078
+
1079
+ def _dedupe_diagnostics(diagnostics: list[LedgerDiagnostic]) -> list[LedgerDiagnostic]:
1080
+ seen: set[tuple[Any, ...]] = set()
1081
+ result: list[LedgerDiagnostic] = []
1082
+ for diagnostic in diagnostics:
1083
+ key = (
1084
+ diagnostic.code,
1085
+ diagnostic.severity,
1086
+ diagnostic.message,
1087
+ diagnostic.line_number,
1088
+ diagnostic.entry_id,
1089
+ diagnostic.revision,
1090
+ )
1091
+ if key in seen:
1092
+ continue
1093
+ seen.add(key)
1094
+ result.append(diagnostic)
1095
+ return result
1096
+
1097
+
1098
+ def _diag(
1099
+ code: str,
1100
+ severity: str,
1101
+ message: str,
1102
+ *,
1103
+ line_number: int | None = None,
1104
+ entry_id: str | None = None,
1105
+ revision: int | None = None,
1106
+ ) -> LedgerDiagnostic:
1107
+ return LedgerDiagnostic(
1108
+ code=code,
1109
+ severity=severity,
1110
+ message=message,
1111
+ line_number=line_number,
1112
+ entry_id=entry_id,
1113
+ revision=revision,
1114
+ )