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,1825 @@
1
+ """Artifact registry helpers for Orchestrator runtime state."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import re
7
+ from dataclasses import dataclass
8
+ from datetime import datetime, timezone
9
+ from pathlib import Path, PurePosixPath, PureWindowsPath
10
+ from typing import Any, Mapping
11
+
12
+ import yaml
13
+
14
+ from multi_agent_brief.contracts.schemas.audit_report import AuditReportContract
15
+ from multi_agent_brief.contracts.schemas.atomic_claim_graph import AtomicClaimGraphContract
16
+ from multi_agent_brief.contracts.schemas.claim import ClaimContract
17
+ from multi_agent_brief.contracts.schemas.claim_draft import ClaimDraftContract
18
+ from multi_agent_brief.contracts.schemas.claim_support_matrix import ClaimSupportMatrixContract
19
+ from multi_agent_brief.contracts.schemas.evidence_span_registry import EvidenceSpanRegistryContract
20
+ from multi_agent_brief.contracts.schemas.semantic_assessment_report import SemanticAssessmentReportContract
21
+ from multi_agent_brief.contracts.schemas.source_evidence_pack_manifest import SourceEvidencePackManifestContract
22
+ from multi_agent_brief.contracts.source_metadata import (
23
+ local_file_without_url_missing_identity,
24
+ source_category_error,
25
+ source_url_error,
26
+ )
27
+ from multi_agent_brief.core.claim_ledger import ClaimLedger
28
+ from multi_agent_brief.core.schemas import Claim
29
+ from multi_agent_brief.feedback.feedback_contract import optional_feedback_artifact_activated
30
+ from multi_agent_brief.orchestrator.runtime_state._io import _sha256_file
31
+ from multi_agent_brief.orchestrator.runtime_state.atomic_claim_graph import (
32
+ ATOMIC_CLAIM_GRAPH_VALIDATION_PREFIX,
33
+ validate_atomic_claim_graph_against_ledger,
34
+ )
35
+ from multi_agent_brief.orchestrator.runtime_state.claim_support_matrix import (
36
+ CLAIM_SUPPORT_MATRIX_VALIDATION_PREFIX,
37
+ validate_claim_support_matrix_against_artifacts,
38
+ )
39
+ from multi_agent_brief.orchestrator.runtime_state.evidence_span_registry import (
40
+ EVIDENCE_SPAN_REGISTRY_VALIDATION_PREFIX,
41
+ validate_evidence_span_registry_against_source_pack,
42
+ )
43
+ from multi_agent_brief.orchestrator.runtime_state.semantic_assessment_report import (
44
+ SEMANTIC_ASSESSMENT_REPORT_VALIDATION_PREFIX,
45
+ validate_semantic_assessment_checked_inputs_for_workspace,
46
+ validate_semantic_assessment_report_against_artifacts,
47
+ )
48
+ from multi_agent_brief.orchestrator.runtime_state.semantic_support_acceptance import (
49
+ validate_semantic_support_acceptance_ledger_for_workspace,
50
+ )
51
+ from multi_agent_brief.orchestrator.runtime_state.source_evidence_pack import (
52
+ SOURCE_EVIDENCE_PACK_VALIDATION_PREFIX,
53
+ validate_source_evidence_pack_manifest,
54
+ )
55
+ from multi_agent_brief.orchestrator.runtime_state.errors import (
56
+ E_TRANSACTION_INTEGRITY,
57
+ RuntimeStateError,
58
+ )
59
+ from multi_agent_brief.orchestrator.runtime_state.workflow import (
60
+ project_stage_completion_for_read,
61
+ interpret_stage_completion,
62
+ _stage_is_complete_or_skipped,
63
+ )
64
+ from multi_agent_brief.product.quality_panel import (
65
+ QualityPanelError,
66
+ render_quality_panel_html,
67
+ render_quality_summary,
68
+ validate_quality_panel_html,
69
+ validate_quality_panel_payload,
70
+ validate_quality_summary_markdown,
71
+ )
72
+ from multi_agent_brief.product.guidance_manifestation import (
73
+ validate_guidance_manifestation_report_payload,
74
+ )
75
+ from multi_agent_brief.provenance.contract import provenance_artifact_activated
76
+ from multi_agent_brief.quality_gates.contract import quality_gate_artifact_activated
77
+
78
+
79
+ ARTIFACT_REGISTRY_SCHEMA = "multi-agent-brief-artifact-registry/v1"
80
+
81
+ ARTIFACT_EXPECTED = "expected"
82
+ ARTIFACT_MISSING = "missing"
83
+ ARTIFACT_PRESENT = "present"
84
+ ARTIFACT_VALID = "valid"
85
+ ARTIFACT_INVALID = "invalid"
86
+ ARTIFACT_STALE = "stale"
87
+ CLAIM_LEDGER_FROZEN_EDIT_GUIDANCE = (
88
+ "claim_ledger.json is frozen. Do not hand-edit metadata or synchronize hashes manually. "
89
+ "Rebuild the fact layer or use a deterministic metadata enrichment transaction when available."
90
+ )
91
+ FROZEN_ARTIFACT_CONTROL_FILE_GUIDANCE = (
92
+ "Do not manually update artifact_registry.json, runtime_manifest.json, workflow_state.json, "
93
+ "event_log.jsonl, or SHA fields to hide the change."
94
+ )
95
+
96
+ _SCREENING_STATUSES = {
97
+ "keep",
98
+ "selected",
99
+ "reject",
100
+ "rejected",
101
+ "deprioritized",
102
+ "exclude",
103
+ "excluded",
104
+ "watch",
105
+ }
106
+ _SCREENING_STATUSES_REQUIRING_REASON = {
107
+ "reject",
108
+ "rejected",
109
+ "deprioritized",
110
+ "exclude",
111
+ "excluded",
112
+ }
113
+ _SCREENING_DISCARD_REASON_CODES = {
114
+ "capacity_capped",
115
+ "duplicate_source",
116
+ "low_confidence",
117
+ "low_tier",
118
+ "off_focus",
119
+ "other",
120
+ "outside_scope",
121
+ "stale_source",
122
+ "unsafe_evidence_boundary",
123
+ "weak_relevance",
124
+ }
125
+ _SCREENING_DISCARD_REASON_ALIASES = {
126
+ "capacity_cut": "capacity_capped",
127
+ "capacity_cap": "capacity_capped",
128
+ "capacity_capped": "capacity_capped",
129
+ "duplicate": "duplicate_source",
130
+ "duplicate_source": "duplicate_source",
131
+ "duplicate_sources": "duplicate_source",
132
+ "low_confidence": "low_confidence",
133
+ "low_tier": "low_tier",
134
+ "off_focus": "off_focus",
135
+ "off_topic": "off_focus",
136
+ "other": "other",
137
+ "outside_scope": "outside_scope",
138
+ "stale": "stale_source",
139
+ "stale_source": "stale_source",
140
+ "stale_sources": "stale_source",
141
+ "unsafe_evidence": "unsafe_evidence_boundary",
142
+ "unsafe_evidence_boundary": "unsafe_evidence_boundary",
143
+ "weak_relevance": "weak_relevance",
144
+ }
145
+ _INPUT_CLASSIFICATION_BUCKETS = {"evidence", "context", "feedback", "instruction", "skipped"}
146
+ _INPUT_CLASSIFICATION_PATH_KEYS = {
147
+ "path",
148
+ "file",
149
+ "source_path",
150
+ "relative_path",
151
+ "input_path",
152
+ "workspace_path",
153
+ "extracted_markdown",
154
+ }
155
+
156
+
157
+ @dataclass(frozen=True)
158
+ class FrozenArtifactIntegrityVerdict:
159
+ """Single interpretation of frozen artifact integrity."""
160
+
161
+ kind: str
162
+ value: dict[str, Any]
163
+ reasons: tuple[str, ...] = ()
164
+ contaminates_run: bool = False
165
+
166
+
167
+ def _validate_artifact(path: Path, fmt: str, artifact_id: str = "") -> tuple[str, str]:
168
+ if not path.exists():
169
+ return ARTIFACT_EXPECTED, "not_checked"
170
+ if not path.is_file():
171
+ return ARTIFACT_INVALID, "not_a_file"
172
+ try:
173
+ text = path.read_text(encoding="utf-8")
174
+ except UnicodeDecodeError:
175
+ return ARTIFACT_INVALID, "decode_error"
176
+ except OSError:
177
+ return ARTIFACT_INVALID, "read_error"
178
+ if not text.strip():
179
+ return ARTIFACT_INVALID, "empty"
180
+
181
+ try:
182
+ if fmt == "json":
183
+ payload = json.loads(text)
184
+ if artifact_id == "claim_ledger":
185
+ return _validate_claim_ledger_payload(payload)
186
+ if artifact_id == "claim_drafts":
187
+ return _validate_claim_drafts_payload(payload)
188
+ if artifact_id == "atomic_claim_graph":
189
+ return _validate_atomic_claim_graph_payload(payload, artifact_path=path)
190
+ if artifact_id == "evidence_span_registry":
191
+ return _validate_evidence_span_registry_payload(payload, artifact_path=path)
192
+ if artifact_id == "claim_support_matrix":
193
+ return _validate_claim_support_matrix_payload(payload, artifact_path=path)
194
+ if artifact_id == "semantic_assessment_report":
195
+ return _validate_semantic_assessment_report_payload(payload, artifact_path=path)
196
+ if artifact_id == "semantic_support_acceptance_ledger":
197
+ return _validate_semantic_support_acceptance_ledger_payload(payload, artifact_path=path)
198
+ if artifact_id == "audit_report":
199
+ return _validate_audit_report_payload(payload)
200
+ if artifact_id == "candidate_claims":
201
+ return _validate_candidate_claims_payload(payload)
202
+ if artifact_id == "screened_candidates":
203
+ return _validate_screened_candidates_payload(payload, artifact_path=path)
204
+ if artifact_id == "input_classification":
205
+ return _validate_input_classification_payload(payload, artifact_path=path)
206
+ if artifact_id == "source_evidence_pack_manifest":
207
+ return _validate_source_evidence_pack_manifest_payload(payload, artifact_path=path)
208
+ if artifact_id == "evidence_extract_source_lock":
209
+ return _validate_evidence_extract_source_lock_payload(payload, artifact_path=path)
210
+ if artifact_id == "evidence_extract_page_inventory":
211
+ return _validate_evidence_extract_page_inventory_payload(payload, artifact_path=path)
212
+ if artifact_id == "human_approval_ledger":
213
+ return _validate_human_approval_ledger_payload(payload, artifact_path=path)
214
+ if artifact_id == "release_readiness_report":
215
+ return _validate_release_readiness_report_payload(payload, artifact_path=path)
216
+ if artifact_id == "quality_panel":
217
+ return _validate_quality_panel_payload(payload)
218
+ if artifact_id == "guidance_manifestation_report":
219
+ return _validate_guidance_manifestation_report_payload(payload, artifact_path=path)
220
+ elif fmt in {"yaml", "yml"}:
221
+ yaml.safe_load(text)
222
+ elif fmt == "markdown":
223
+ if artifact_id == "quality_summary":
224
+ return _validate_quality_summary_markdown(text, artifact_path=path)
225
+ elif fmt == "html":
226
+ if artifact_id == "quality_panel_html":
227
+ return _validate_quality_panel_html(text, artifact_path=path)
228
+ except json.JSONDecodeError:
229
+ return ARTIFACT_INVALID, "parse_error"
230
+ except yaml.YAMLError:
231
+ return ARTIFACT_INVALID, "parse_error"
232
+
233
+ return ARTIFACT_VALID, "valid_minimum"
234
+
235
+
236
+ def _validate_candidate_claims_payload(payload: Any) -> tuple[str, str]:
237
+ if not isinstance(payload, list):
238
+ return ARTIFACT_INVALID, "candidate_claims_schema_error:not_list"
239
+
240
+ seen_ids: set[str] = set()
241
+ for idx, candidate in enumerate(payload):
242
+ if not isinstance(candidate, dict):
243
+ return ARTIFACT_INVALID, f"candidate_claims_schema_error:candidate[{idx}]"
244
+ if _candidate_claim_uses_legacy_shape(candidate):
245
+ status, result = _validate_legacy_candidate_claim(candidate, idx=idx, seen_ids=seen_ids)
246
+ else:
247
+ status, result = _validate_contract_candidate_claim(candidate, idx=idx, seen_ids=seen_ids)
248
+ if status != ARTIFACT_VALID:
249
+ return status, result
250
+
251
+ return ARTIFACT_VALID, "valid_candidate_claims_schema"
252
+
253
+
254
+ def _candidate_claim_uses_legacy_shape(candidate: dict[str, Any]) -> bool:
255
+ return "statement" not in candidate and ("claim" in candidate or "candidate_id" in candidate)
256
+
257
+
258
+ def _validate_legacy_candidate_claim(
259
+ candidate: dict[str, Any],
260
+ *,
261
+ idx: int,
262
+ seen_ids: set[str],
263
+ ) -> tuple[str, str]:
264
+ for field in ("candidate_id", "claim", "source_id"):
265
+ value = candidate.get(field)
266
+ if not isinstance(value, str) or not value.strip():
267
+ return ARTIFACT_INVALID, f"candidate_claims_schema_error:candidate[{idx}].{field}"
268
+ candidate_id = str(candidate["candidate_id"]).strip()
269
+ if candidate_id in seen_ids:
270
+ return ARTIFACT_INVALID, f"candidate_claims_schema_error:duplicate_candidate_id:{candidate_id}"
271
+ seen_ids.add(candidate_id)
272
+ return ARTIFACT_VALID, "valid_candidate_claims_schema"
273
+
274
+
275
+ def _validate_contract_candidate_claim(
276
+ candidate: dict[str, Any],
277
+ *,
278
+ idx: int,
279
+ seen_ids: set[str],
280
+ ) -> tuple[str, str]:
281
+ for field in ("statement", "evidence_text", "topic", "claim_type"):
282
+ value = candidate.get(field)
283
+ if not isinstance(value, str) or not value.strip():
284
+ return ARTIFACT_INVALID, f"candidate_claims_schema_error:candidate[{idx}].{field}"
285
+ url_error = source_url_error(candidate.get("source_url"))
286
+ if url_error:
287
+ return ARTIFACT_INVALID, f"candidate_claims_schema_error:candidate[{idx}].source_url"
288
+ category_error = source_category_error(candidate.get("source_category"))
289
+ if category_error:
290
+ return ARTIFACT_INVALID, f"candidate_claims_schema_error:candidate[{idx}].source_category"
291
+ local_identity_error = local_file_without_url_missing_identity(candidate)
292
+ if local_identity_error:
293
+ return ARTIFACT_INVALID, (
294
+ f"candidate_claims_schema_error:candidate[{idx}].{local_identity_error}"
295
+ )
296
+ if not _candidate_claim_has_source_identity(candidate):
297
+ return ARTIFACT_INVALID, f"candidate_claims_schema_error:candidate[{idx}].source_url_or_source_path"
298
+ if not _candidate_claim_has_source_date(candidate):
299
+ return ARTIFACT_INVALID, (
300
+ f"candidate_claims_schema_error:candidate[{idx}].published_at_or_retrieved_at"
301
+ )
302
+ if not _non_empty_scalar(candidate.get("confidence")):
303
+ return ARTIFACT_INVALID, f"candidate_claims_schema_error:candidate[{idx}].confidence"
304
+ for field in ("source_id", "source_path"):
305
+ value = candidate.get(field)
306
+ if value is not None and not _non_empty_string(value):
307
+ return ARTIFACT_INVALID, f"candidate_claims_schema_error:candidate[{idx}].{field}"
308
+ candidate_id = candidate.get("candidate_id")
309
+ if candidate_id is not None:
310
+ if not _non_empty_string(candidate_id):
311
+ return ARTIFACT_INVALID, f"candidate_claims_schema_error:candidate[{idx}].candidate_id"
312
+ normalized_id = candidate_id.strip()
313
+ if normalized_id in seen_ids:
314
+ return ARTIFACT_INVALID, f"candidate_claims_schema_error:duplicate_candidate_id:{normalized_id}"
315
+ seen_ids.add(normalized_id)
316
+ return ARTIFACT_VALID, "valid_candidate_claims_schema"
317
+
318
+
319
+ def _candidate_claim_has_source_identity(candidate: dict[str, Any]) -> bool:
320
+ return _non_empty_string(candidate.get("source_url")) or _non_empty_string(
321
+ candidate.get("source_path")
322
+ )
323
+
324
+
325
+ def _candidate_claim_has_source_date(candidate: dict[str, Any]) -> bool:
326
+ return _non_empty_string(candidate.get("published_at")) or _non_empty_string(
327
+ candidate.get("retrieved_at")
328
+ )
329
+
330
+
331
+ def _non_empty_scalar(value: Any) -> bool:
332
+ return (isinstance(value, str) and bool(value.strip())) or (
333
+ isinstance(value, (int, float)) and not isinstance(value, bool)
334
+ )
335
+
336
+
337
+ def _validate_screened_candidates_payload(
338
+ payload: Any,
339
+ *,
340
+ artifact_path: Path | None = None,
341
+ ) -> tuple[str, str]:
342
+ if isinstance(payload, list):
343
+ return _validate_legacy_screened_candidates(payload)
344
+ if isinstance(payload, dict):
345
+ status, result = _validate_contract_screened_candidates(payload)
346
+ if status != ARTIFACT_VALID:
347
+ return status, result
348
+ universe_error = _screened_candidates_candidate_universe_error(
349
+ payload,
350
+ artifact_path=artifact_path,
351
+ )
352
+ if universe_error:
353
+ return ARTIFACT_INVALID, f"screened_candidates_schema_error:{universe_error}"
354
+ return status, result
355
+ return ARTIFACT_INVALID, "screened_candidates_schema_error:not_list_or_object"
356
+
357
+
358
+ def _validate_legacy_screened_candidates(payload: list[Any]) -> tuple[str, str]:
359
+ for idx, candidate in enumerate(payload):
360
+ if not isinstance(candidate, dict):
361
+ return ARTIFACT_INVALID, f"screened_candidates_schema_error:candidate[{idx}]"
362
+ candidate_id = candidate.get("candidate_id")
363
+ if not isinstance(candidate_id, str) or not candidate_id.strip():
364
+ return ARTIFACT_INVALID, f"screened_candidates_schema_error:candidate[{idx}].candidate_id"
365
+ status = candidate.get("screening_status")
366
+ if not isinstance(status, str) or status.strip() not in _SCREENING_STATUSES:
367
+ return ARTIFACT_INVALID, f"screened_candidates_schema_error:candidate[{idx}].screening_status"
368
+ if status.strip() in _SCREENING_STATUSES_REQUIRING_REASON:
369
+ has_reason = any(
370
+ _non_empty_string(candidate.get(field))
371
+ for field in ("reason", "screening_reason", "excluded_reason")
372
+ )
373
+ if not has_reason:
374
+ return ARTIFACT_INVALID, f"screened_candidates_schema_error:candidate[{idx}].reason"
375
+
376
+ return ARTIFACT_VALID, "valid_screened_candidates_schema"
377
+
378
+
379
+ def _validate_contract_screened_candidates(payload: dict[str, Any]) -> tuple[str, str]:
380
+ selected = payload.get("selected")
381
+ if not isinstance(selected, list):
382
+ return ARTIFACT_INVALID, "screened_candidates_schema_error:selected"
383
+ for idx, candidate in enumerate(selected):
384
+ validation_error = _selected_screened_candidate_error(candidate)
385
+ if validation_error:
386
+ return ARTIFACT_INVALID, f"screened_candidates_schema_error:selected[{idx}].{validation_error}"
387
+
388
+ screening_policy = payload.get("screening_policy")
389
+ if not isinstance(screening_policy, dict) or not screening_policy:
390
+ return ARTIFACT_INVALID, "screened_candidates_schema_error:screening_policy"
391
+
392
+ total_candidates, total_error = _screened_candidates_total(payload, screening_policy)
393
+ if total_error:
394
+ return ARTIFACT_INVALID, f"screened_candidates_schema_error:{total_error}"
395
+
396
+ has_discard_bucket = False
397
+ for bucket in ("excluded", "deprioritized"):
398
+ entries = payload.get(bucket)
399
+ if entries is None:
400
+ continue
401
+ if not isinstance(entries, list):
402
+ return ARTIFACT_INVALID, f"screened_candidates_schema_error:{bucket}"
403
+ has_discard_bucket = True
404
+ for idx, candidate in enumerate(entries):
405
+ if not _valid_screened_candidate_entry(candidate):
406
+ return ARTIFACT_INVALID, f"screened_candidates_schema_error:{bucket}[{idx}]"
407
+ if not _screened_candidate_reason_code(candidate):
408
+ return ARTIFACT_INVALID, f"screened_candidates_schema_error:{bucket}[{idx}].reason_code"
409
+ if not _screened_candidate_has_short_explanation(candidate):
410
+ return ARTIFACT_INVALID, f"screened_candidates_schema_error:{bucket}[{idx}].explanation"
411
+ if not has_discard_bucket:
412
+ return ARTIFACT_INVALID, "screened_candidates_schema_error:excluded_or_deprioritized"
413
+
414
+ if total_candidates is not None:
415
+ discard_count = _screened_candidates_discard_count(payload)
416
+ expected_discards = total_candidates - len(selected)
417
+ if expected_discards < 0:
418
+ return ARTIFACT_INVALID, "screened_candidates_schema_error:total_candidates"
419
+ if expected_discards > 0 and discard_count == 0:
420
+ return ARTIFACT_INVALID, "screened_candidates_schema_error:discard_audit_missing"
421
+ if len(selected) + discard_count != total_candidates:
422
+ return ARTIFACT_INVALID, "screened_candidates_schema_error:discard_audit_count"
423
+
424
+ return ARTIFACT_VALID, "valid_screened_candidates_schema"
425
+
426
+
427
+ def _selected_screened_candidate_error(candidate: Any) -> str | None:
428
+ if not isinstance(candidate, dict):
429
+ return "entry"
430
+ for field in ("statement", "evidence_text"):
431
+ if not _non_empty_string(candidate.get(field)):
432
+ return field
433
+ if source_url_error(candidate.get("source_url")):
434
+ return "source_url"
435
+ if source_category_error(candidate.get("source_category")):
436
+ return "source_category"
437
+ local_identity_error = local_file_without_url_missing_identity(candidate)
438
+ if local_identity_error:
439
+ return local_identity_error
440
+ if not _screened_candidate_has_source_identity(candidate):
441
+ return "source_id_or_source_url_or_source_path"
442
+ if not _candidate_claim_has_source_date(candidate):
443
+ return "published_at_or_retrieved_at"
444
+ return None
445
+
446
+
447
+ def _screened_candidate_has_source_identity(candidate: dict[str, Any]) -> bool:
448
+ return any(
449
+ _non_empty_string(candidate.get(field))
450
+ for field in ("source_id", "source_url", "source_path")
451
+ )
452
+
453
+
454
+ def _valid_screened_candidate_entry(candidate: Any) -> bool:
455
+ if not isinstance(candidate, dict):
456
+ return False
457
+ return any(_non_empty_string(candidate.get(field)) for field in ("candidate_id", "statement", "claim"))
458
+
459
+
460
+ def _screened_candidate_reason_code(candidate: dict[str, Any]) -> str:
461
+ for field in (
462
+ "reason_code",
463
+ "screening_reason_code",
464
+ "excluded_reason_code",
465
+ "deprioritized_reason_code",
466
+ ):
467
+ code = _normalize_screening_reason_code(candidate.get(field))
468
+ if code:
469
+ return code
470
+ return ""
471
+
472
+
473
+ def _normalize_screening_reason_code(value: Any) -> str:
474
+ if not isinstance(value, str):
475
+ return ""
476
+ raw = value.strip().lower()
477
+ if not raw:
478
+ return ""
479
+ normalized = re.sub(r"[^a-z0-9]+", "_", raw).strip("_")
480
+ if normalized in _SCREENING_DISCARD_REASON_CODES:
481
+ return normalized
482
+ return _SCREENING_DISCARD_REASON_ALIASES.get(normalized, "")
483
+
484
+
485
+ def _screened_candidate_has_short_explanation(candidate: dict[str, Any]) -> bool:
486
+ code = _screened_candidate_reason_code(candidate)
487
+ for field in (
488
+ "explanation",
489
+ "short_explanation",
490
+ "screening_explanation",
491
+ "reason_explanation",
492
+ "screening_reason",
493
+ "excluded_reason",
494
+ "deprioritized_reason",
495
+ ):
496
+ value = candidate.get(field)
497
+ if not _non_empty_string(value):
498
+ continue
499
+ if _normalize_screening_reason_code(value) == code:
500
+ continue
501
+ return True
502
+ return False
503
+
504
+
505
+ def _screened_candidates_total(
506
+ payload: dict[str, Any],
507
+ screening_policy: dict[str, Any],
508
+ ) -> tuple[int | None, str | None]:
509
+ total_values: list[int] = []
510
+ for container, prefix in (
511
+ (payload, ""),
512
+ (screening_policy, "screening_policy."),
513
+ ):
514
+ for key in (
515
+ "total_candidates",
516
+ "candidate_count",
517
+ "input_candidate_count",
518
+ "found_candidate_count",
519
+ ):
520
+ value = container.get(key)
521
+ if value is None:
522
+ continue
523
+ if not isinstance(value, int) or isinstance(value, bool) or value < 0:
524
+ return None, f"{prefix}{key}"
525
+ total_values.append(value)
526
+ if not total_values:
527
+ return None, None
528
+ first = total_values[0]
529
+ if any(value != first for value in total_values[1:]):
530
+ return None, "total_candidates_mismatch"
531
+ return first, None
532
+
533
+
534
+ def _screened_candidates_discard_count(payload: dict[str, Any]) -> int:
535
+ count = 0
536
+ for bucket in ("excluded", "deprioritized"):
537
+ entries = payload.get(bucket)
538
+ if isinstance(entries, list):
539
+ count += len(entries)
540
+ return count
541
+
542
+
543
+ def _screened_candidates_candidate_universe_error(
544
+ payload: dict[str, Any],
545
+ *,
546
+ artifact_path: Path | None,
547
+ ) -> str | None:
548
+ if artifact_path is None:
549
+ return None
550
+ screening_policy = payload.get("screening_policy")
551
+ if not isinstance(screening_policy, dict):
552
+ return None
553
+ declared_total, total_error = _screened_candidates_total(payload, screening_policy)
554
+ if total_error:
555
+ return None
556
+
557
+ candidate_payload = _read_json_payload(artifact_path.with_name("candidate_claims.json"))
558
+ if not isinstance(candidate_payload, list):
559
+ return None
560
+ candidate_status, _ = _validate_candidate_claims_payload(candidate_payload)
561
+ if candidate_status != ARTIFACT_VALID:
562
+ return None
563
+
564
+ if declared_total is not None and declared_total != len(candidate_payload):
565
+ return "candidate_universe_count_mismatch"
566
+
567
+ candidate_ids = _candidate_claim_ids(candidate_payload)
568
+ if candidate_ids is None:
569
+ return None
570
+
571
+ screened_ids, screened_id_error = _screened_candidate_ids(payload, candidate_ids)
572
+ if screened_id_error:
573
+ return screened_id_error
574
+
575
+ if declared_total is None:
576
+ return None
577
+
578
+ if screened_ids != candidate_ids:
579
+ return "candidate_universe_id_coverage_mismatch"
580
+ return None
581
+
582
+
583
+ def _screened_candidate_ids(
584
+ payload: dict[str, Any],
585
+ candidate_ids: set[str],
586
+ ) -> tuple[set[str], str | None]:
587
+ screened_ids: set[str] = set()
588
+ for bucket in ("selected", "excluded", "deprioritized"):
589
+ entries = payload.get(bucket)
590
+ if not isinstance(entries, list):
591
+ continue
592
+ for idx, candidate in enumerate(entries):
593
+ if not isinstance(candidate, dict):
594
+ continue
595
+ candidate_id = candidate.get("candidate_id")
596
+ if not _non_empty_string(candidate_id):
597
+ return screened_ids, f"{bucket}[{idx}].candidate_id"
598
+ normalized_id = candidate_id.strip()
599
+ if normalized_id not in candidate_ids:
600
+ return screened_ids, f"{bucket}[{idx}].unknown_candidate_id:{normalized_id}"
601
+ if normalized_id in screened_ids:
602
+ return screened_ids, f"duplicate_screened_candidate_id:{normalized_id}"
603
+ screened_ids.add(normalized_id)
604
+ return screened_ids, None
605
+
606
+
607
+ def _candidate_claim_ids(payload: list[Any]) -> set[str] | None:
608
+ ids: set[str] = set()
609
+ for candidate in payload:
610
+ if not isinstance(candidate, dict):
611
+ return None
612
+ candidate_id = candidate.get("candidate_id")
613
+ if not _non_empty_string(candidate_id):
614
+ return None
615
+ ids.add(candidate_id.strip())
616
+ return ids
617
+
618
+
619
+ def _validate_input_classification_payload(payload: Any, *, artifact_path: Path) -> tuple[str, str]:
620
+ if not isinstance(payload, dict):
621
+ return ARTIFACT_INVALID, "input_classification_schema_error:not_object"
622
+
623
+ workspace = _workspace_root_for_input_classification(artifact_path)
624
+ for bucket in sorted(_INPUT_CLASSIFICATION_BUCKETS):
625
+ entries = payload.get(bucket)
626
+ if entries is None:
627
+ continue
628
+ if not isinstance(entries, list):
629
+ return ARTIFACT_INVALID, f"input_classification_schema_error:{bucket}"
630
+ for idx, entry in enumerate(entries):
631
+ if not isinstance(entry, dict):
632
+ continue
633
+ for key, value in entry.items():
634
+ if key not in _INPUT_CLASSIFICATION_PATH_KEYS or not isinstance(value, str):
635
+ continue
636
+ if _input_classification_path_is_unsafe(value, workspace=workspace):
637
+ return ARTIFACT_INVALID, f"input_classification_schema_error:{bucket}[{idx}].{key}"
638
+
639
+ return ARTIFACT_VALID, "valid_input_classification_schema"
640
+
641
+
642
+ def _validate_source_evidence_pack_manifest_payload(payload: Any, *, artifact_path: Path) -> tuple[str, str]:
643
+ if not isinstance(payload, dict):
644
+ return ARTIFACT_INVALID, "source_evidence_pack_manifest_schema_error:not_object"
645
+ violations = SourceEvidencePackManifestContract.validate(payload)
646
+ errors = [violation for violation in violations if violation.severity == "error"]
647
+ if errors:
648
+ first = errors[0]
649
+ return ARTIFACT_INVALID, f"source_evidence_pack_manifest_schema_error:{first.field}"
650
+
651
+ workspace = artifact_path.parents[2]
652
+ reason = validate_source_evidence_pack_manifest(
653
+ manifest_payload=payload,
654
+ workspace=workspace,
655
+ )
656
+ if reason:
657
+ return ARTIFACT_INVALID, f"{SOURCE_EVIDENCE_PACK_VALIDATION_PREFIX}:{reason}"
658
+ return ARTIFACT_VALID, "experimental_source_evidence_pack_manifest"
659
+
660
+
661
+ def _validate_evidence_extract_source_lock_payload(payload: Any, *, artifact_path: Path) -> tuple[str, str]:
662
+ if not isinstance(payload, dict):
663
+ return ARTIFACT_INVALID, "evidence_extract_source_lock_schema_error:not_object"
664
+ if payload.get("schema_version") != "briefloop.evidence_extract_source_lock.v1":
665
+ return ARTIFACT_INVALID, "evidence_extract_source_lock_schema_error:schema_version"
666
+ if payload.get("report_pack") != "evidence_extract":
667
+ return ARTIFACT_INVALID, "evidence_extract_source_lock_schema_error:report_pack"
668
+ sources = payload.get("sources")
669
+ if not isinstance(sources, list) or not sources:
670
+ return ARTIFACT_INVALID, "evidence_extract_source_lock_schema_error:sources"
671
+ source_count = payload.get("source_count")
672
+ if not isinstance(source_count, int) or source_count != len(sources):
673
+ return ARTIFACT_INVALID, "evidence_extract_source_lock_schema_error:source_count"
674
+
675
+ workspace = artifact_path.parents[2]
676
+ seen_ids: set[str] = set()
677
+ for idx, source in enumerate(sources):
678
+ if not isinstance(source, dict):
679
+ return ARTIFACT_INVALID, f"evidence_extract_source_lock_schema_error:sources[{idx}]"
680
+ source_id = source.get("source_id")
681
+ if not _non_empty_string(source_id):
682
+ return ARTIFACT_INVALID, f"evidence_extract_source_lock_schema_error:sources[{idx}].source_id"
683
+ normalized_id = source_id.strip()
684
+ if normalized_id in seen_ids:
685
+ return ARTIFACT_INVALID, f"evidence_extract_source_lock_schema_error:duplicate_source_id:{normalized_id}"
686
+ seen_ids.add(normalized_id)
687
+
688
+ rel_path = source.get("path")
689
+ if not _non_empty_string(rel_path):
690
+ return ARTIFACT_INVALID, f"evidence_extract_source_lock_schema_error:{normalized_id}.path"
691
+ source_path, path_reason = _evidence_extract_locked_source_path(
692
+ workspace=workspace,
693
+ rel_path=rel_path.strip(),
694
+ )
695
+ if path_reason:
696
+ return ARTIFACT_INVALID, f"evidence_extract_source_lock_validation_error:{path_reason}:{normalized_id}"
697
+ assert source_path is not None
698
+ if not source_path.exists() or not source_path.is_file():
699
+ return ARTIFACT_INVALID, f"evidence_extract_source_lock_validation_error:source_file_missing:{normalized_id}"
700
+
701
+ expected_sha = source.get("source_sha256")
702
+ if not _non_empty_string(expected_sha):
703
+ return ARTIFACT_INVALID, f"evidence_extract_source_lock_schema_error:{normalized_id}.source_sha256"
704
+ if _sha256_file(source_path) != expected_sha.strip():
705
+ return ARTIFACT_INVALID, f"evidence_extract_source_lock_validation_error:source_sha256_mismatch:{normalized_id}"
706
+
707
+ expected_size = source.get("source_size_bytes")
708
+ if not isinstance(expected_size, int) or expected_size < 0:
709
+ return ARTIFACT_INVALID, f"evidence_extract_source_lock_schema_error:{normalized_id}.source_size_bytes"
710
+ try:
711
+ actual_size = source_path.stat().st_size
712
+ except OSError:
713
+ return ARTIFACT_INVALID, f"evidence_extract_source_lock_validation_error:source_file_unreadable:{normalized_id}"
714
+ if actual_size != expected_size:
715
+ return ARTIFACT_INVALID, f"evidence_extract_source_lock_validation_error:source_size_mismatch:{normalized_id}"
716
+
717
+ if source.get("lock_status") != "locked_source_bytes":
718
+ return ARTIFACT_INVALID, f"evidence_extract_source_lock_schema_error:{normalized_id}.lock_status"
719
+
720
+ derived = source.get("derived_markdown")
721
+ if derived is not None:
722
+ derived_reason = _evidence_extract_derived_markdown_error(
723
+ workspace=workspace,
724
+ source=source,
725
+ normalized_id=normalized_id,
726
+ )
727
+ if derived_reason:
728
+ return ARTIFACT_INVALID, f"evidence_extract_source_lock_validation_error:{derived_reason}:{normalized_id}"
729
+ if source.get("registered_only") is True:
730
+ return ARTIFACT_INVALID, f"evidence_extract_source_lock_schema_error:{normalized_id}.registered_only"
731
+ if source.get("text_evidence_basis") != "mineru_derived_markdown":
732
+ return ARTIFACT_INVALID, f"evidence_extract_source_lock_schema_error:{normalized_id}.text_evidence_basis"
733
+ if source.get("text_evidence_path") != derived.get("path"):
734
+ return ARTIFACT_INVALID, f"evidence_extract_source_lock_schema_error:{normalized_id}.text_evidence_path"
735
+
736
+ return ARTIFACT_VALID, "experimental_evidence_extract_source_lock"
737
+
738
+
739
+ def _evidence_extract_derived_markdown_error(
740
+ *,
741
+ workspace: Path,
742
+ source: dict[str, Any],
743
+ normalized_id: str,
744
+ ) -> str | None:
745
+ derived = source.get("derived_markdown")
746
+ if not isinstance(derived, dict):
747
+ return "derived_markdown"
748
+ if derived.get("derivation") != "mineru_adjacent_markdown":
749
+ return "derived_markdown_derivation"
750
+ if derived.get("extractor") != "mineru":
751
+ return "derived_markdown_extractor"
752
+ if derived.get("source_path") != source.get("path"):
753
+ return "derived_markdown_source_path"
754
+ rel_path = derived.get("path")
755
+ if not _non_empty_string(rel_path):
756
+ return "derived_markdown_path"
757
+ derived_path, path_reason = _evidence_extract_locked_source_path(
758
+ workspace=workspace,
759
+ rel_path=rel_path.strip(),
760
+ )
761
+ if path_reason:
762
+ return "derived_markdown_path_unsafe"
763
+ assert derived_path is not None
764
+ if derived_path.suffix.lower() != ".md":
765
+ return "derived_markdown_extension"
766
+ if not derived_path.exists() or not derived_path.is_file():
767
+ return "derived_markdown_missing"
768
+ expected_sha = derived.get("sha256")
769
+ if not _non_empty_string(expected_sha):
770
+ return "derived_markdown_sha256"
771
+ if _sha256_file(derived_path) != expected_sha.strip():
772
+ return "derived_markdown_sha256_mismatch"
773
+ expected_size = derived.get("size_bytes")
774
+ if not isinstance(expected_size, int) or expected_size < 0:
775
+ return "derived_markdown_size_bytes"
776
+ try:
777
+ actual_size = derived_path.stat().st_size
778
+ except OSError:
779
+ return "derived_markdown_unreadable"
780
+ if actual_size != expected_size:
781
+ return "derived_markdown_size_mismatch"
782
+ filename = derived.get("filename")
783
+ if _non_empty_string(filename) and filename.strip() != derived_path.name:
784
+ return "derived_markdown_filename"
785
+ _ = normalized_id
786
+ return None
787
+
788
+
789
+ def _evidence_extract_locked_source_path(*, workspace: Path, rel_path: str) -> tuple[Path | None, str | None]:
790
+ normalized = rel_path.replace("\\", "/")
791
+ posix_path = PurePosixPath(normalized)
792
+ windows_path = PureWindowsPath(rel_path)
793
+ if rel_path.startswith("~") or Path(rel_path).is_absolute() or windows_path.drive:
794
+ return None, "source_path_unsafe"
795
+ if ".." in posix_path.parts or not normalized.startswith("input/sources/evidence_extract/"):
796
+ return None, "source_path_unsafe"
797
+ workspace_root = workspace.resolve(strict=False)
798
+ input_root = workspace / "input"
799
+ sources_root = input_root / "sources"
800
+ evidence_root = sources_root / "evidence_extract"
801
+ for root in (input_root, sources_root, evidence_root):
802
+ if root.is_symlink():
803
+ return None, "source_path_unsafe"
804
+ try:
805
+ root.resolve(strict=False).relative_to(workspace_root)
806
+ except ValueError:
807
+ return None, "source_path_unsafe"
808
+ raw_source_path = workspace / normalized
809
+ if raw_source_path.is_symlink():
810
+ return None, "source_path_unsafe"
811
+ source_path = raw_source_path.resolve(strict=False)
812
+ try:
813
+ source_path.relative_to(evidence_root.resolve(strict=False))
814
+ source_path.relative_to(workspace_root)
815
+ except ValueError:
816
+ return None, "source_path_unsafe"
817
+ return source_path, None
818
+
819
+
820
+ def _validate_evidence_extract_page_inventory_payload(payload: Any, *, artifact_path: Path) -> tuple[str, str]:
821
+ if not isinstance(payload, dict):
822
+ return ARTIFACT_INVALID, "evidence_extract_page_inventory_schema_error:not_object"
823
+ if payload.get("schema_version") != "briefloop.evidence_extract_page_inventory.v1":
824
+ return ARTIFACT_INVALID, "evidence_extract_page_inventory_schema_error:schema_version"
825
+ if payload.get("report_pack") != "evidence_extract":
826
+ return ARTIFACT_INVALID, "evidence_extract_page_inventory_schema_error:report_pack"
827
+ if payload.get("source_lock_path") != "output/intermediate/evidence_extract_source_lock.json":
828
+ return ARTIFACT_INVALID, "evidence_extract_page_inventory_schema_error:source_lock_path"
829
+
830
+ lock_path = artifact_path.with_name("evidence_extract_source_lock.json")
831
+ try:
832
+ lock_payload = json.loads(lock_path.read_text(encoding="utf-8"))
833
+ except FileNotFoundError:
834
+ return ARTIFACT_INVALID, "evidence_extract_page_inventory_validation_error:source_lock_missing"
835
+ except (OSError, UnicodeDecodeError, json.JSONDecodeError):
836
+ return ARTIFACT_INVALID, "evidence_extract_page_inventory_validation_error:source_lock_unreadable"
837
+ lock_status, lock_reason = _validate_evidence_extract_source_lock_payload(lock_payload, artifact_path=lock_path)
838
+ if lock_status != ARTIFACT_VALID:
839
+ return ARTIFACT_INVALID, f"evidence_extract_page_inventory_validation_error:source_lock_invalid:{lock_reason}"
840
+
841
+ expected_lock_sha = payload.get("source_lock_sha256")
842
+ if not _non_empty_string(expected_lock_sha):
843
+ return ARTIFACT_INVALID, "evidence_extract_page_inventory_schema_error:source_lock_sha256"
844
+ if _sha256_file(lock_path) != expected_lock_sha.strip():
845
+ return ARTIFACT_INVALID, "evidence_extract_page_inventory_validation_error:source_lock_sha256_mismatch"
846
+
847
+ lock_sources = lock_payload.get("sources")
848
+ if not isinstance(lock_sources, list):
849
+ return ARTIFACT_INVALID, "evidence_extract_page_inventory_validation_error:source_lock_sources"
850
+ lock_by_id = {
851
+ str(source.get("source_id") or "").strip(): source
852
+ for source in lock_sources
853
+ if isinstance(source, dict) and _non_empty_string(source.get("source_id"))
854
+ }
855
+ workspace = artifact_path.parents[2]
856
+
857
+ sources = payload.get("sources")
858
+ if not isinstance(sources, list) or not sources:
859
+ return ARTIFACT_INVALID, "evidence_extract_page_inventory_schema_error:sources"
860
+ if payload.get("source_count") != len(sources):
861
+ return ARTIFACT_INVALID, "evidence_extract_page_inventory_schema_error:source_count"
862
+ seen_source_ids: set[str] = set()
863
+ total_pages = 0
864
+ inventory_sources = 0
865
+ for idx, source in enumerate(sources):
866
+ if not isinstance(source, dict):
867
+ return ARTIFACT_INVALID, f"evidence_extract_page_inventory_schema_error:sources[{idx}]"
868
+ source_id = source.get("source_id")
869
+ if not _non_empty_string(source_id):
870
+ return ARTIFACT_INVALID, f"evidence_extract_page_inventory_schema_error:sources[{idx}].source_id"
871
+ normalized_id = source_id.strip()
872
+ if normalized_id in seen_source_ids:
873
+ return ARTIFACT_INVALID, f"evidence_extract_page_inventory_schema_error:duplicate_source_id:{normalized_id}"
874
+ seen_source_ids.add(normalized_id)
875
+ lock_source = lock_by_id.get(normalized_id)
876
+ if lock_source is None:
877
+ return ARTIFACT_INVALID, f"evidence_extract_page_inventory_validation_error:unknown_source_id:{normalized_id}"
878
+ if source.get("source_path") != lock_source.get("path"):
879
+ return ARTIFACT_INVALID, f"evidence_extract_page_inventory_validation_error:source_path_mismatch:{normalized_id}"
880
+ if source.get("source_sha256") != lock_source.get("source_sha256"):
881
+ return ARTIFACT_INVALID, f"evidence_extract_page_inventory_validation_error:source_sha256_mismatch:{normalized_id}"
882
+ locked_path, path_reason = _evidence_extract_locked_source_path(
883
+ workspace=workspace,
884
+ rel_path=str(lock_source.get("path") or ""),
885
+ )
886
+ if path_reason:
887
+ return ARTIFACT_INVALID, f"evidence_extract_page_inventory_validation_error:{path_reason}:{normalized_id}"
888
+ assert locked_path is not None
889
+ locked_source_text = ""
890
+ locked_text_reason: str | None = None
891
+ text_basis = "utf8_text_file"
892
+ text_source_path = str(lock_source.get("path") or "")
893
+ text_source_sha256 = str(lock_source.get("source_sha256") or "")
894
+ text_needs_visual_inspection = False
895
+ if lock_source.get("registered_only") is not True:
896
+ (
897
+ locked_source_text,
898
+ locked_text_reason,
899
+ text_basis,
900
+ text_source_path,
901
+ text_source_sha256,
902
+ text_needs_visual_inspection,
903
+ ) = _evidence_extract_inventory_text_binding(
904
+ workspace=workspace,
905
+ lock_source=lock_source,
906
+ locked_path=locked_path,
907
+ )
908
+ if lock_source.get("derived_markdown") is not None or source.get("text_source_path") is not None:
909
+ if source.get("text_source_path") != text_source_path:
910
+ return ARTIFACT_INVALID, f"evidence_extract_page_inventory_validation_error:text_source_path_mismatch:{normalized_id}"
911
+ if source.get("text_source_sha256") != text_source_sha256:
912
+ return ARTIFACT_INVALID, f"evidence_extract_page_inventory_validation_error:text_source_sha256_mismatch:{normalized_id}"
913
+ if source.get("text_evidence_basis") != text_basis:
914
+ return ARTIFACT_INVALID, f"evidence_extract_page_inventory_validation_error:text_evidence_basis_mismatch:{normalized_id}"
915
+
916
+ status = source.get("inventory_status")
917
+ if status not in {
918
+ "text_logical_page_seeded",
919
+ "text_empty_no_pages",
920
+ "unsupported_source_format_registered_only",
921
+ }:
922
+ return ARTIFACT_INVALID, f"evidence_extract_page_inventory_schema_error:{normalized_id}.inventory_status"
923
+ pages = source.get("pages")
924
+ if not isinstance(pages, list):
925
+ return ARTIFACT_INVALID, f"evidence_extract_page_inventory_schema_error:{normalized_id}.pages"
926
+ page_count = source.get("page_count")
927
+ if not isinstance(page_count, int) or page_count != len(pages):
928
+ return ARTIFACT_INVALID, f"evidence_extract_page_inventory_schema_error:{normalized_id}.page_count"
929
+ if status != "text_logical_page_seeded" and pages:
930
+ return ARTIFACT_INVALID, f"evidence_extract_page_inventory_schema_error:{normalized_id}.pages_for_unsupported_source"
931
+ if status == "text_logical_page_seeded":
932
+ if len(pages) != 1:
933
+ return ARTIFACT_INVALID, f"evidence_extract_page_inventory_schema_error:{normalized_id}.logical_page_count"
934
+ inventory_sources += 1
935
+ if locked_text_reason:
936
+ return ARTIFACT_INVALID, f"evidence_extract_page_inventory_validation_error:{locked_text_reason}:{normalized_id}"
937
+ if not locked_source_text.strip():
938
+ return ARTIFACT_INVALID, f"evidence_extract_page_inventory_validation_error:source_text_empty:{normalized_id}"
939
+ elif status == "text_empty_no_pages":
940
+ if locked_text_reason:
941
+ return ARTIFACT_INVALID, f"evidence_extract_page_inventory_validation_error:{locked_text_reason}:{normalized_id}"
942
+ if locked_source_text.strip():
943
+ return ARTIFACT_INVALID, f"evidence_extract_page_inventory_validation_error:source_text_not_empty:{normalized_id}"
944
+ if source.get("needs_external_extraction_tool") is not False:
945
+ return ARTIFACT_INVALID, f"evidence_extract_page_inventory_schema_error:{normalized_id}.needs_external_extraction_tool"
946
+ if source.get("visual_inspection_required") is not text_needs_visual_inspection:
947
+ return ARTIFACT_INVALID, f"evidence_extract_page_inventory_schema_error:{normalized_id}.visual_inspection_required"
948
+ elif status == "unsupported_source_format_registered_only":
949
+ if lock_source.get("registered_only") is not True and not locked_text_reason:
950
+ return ARTIFACT_INVALID, f"evidence_extract_page_inventory_validation_error:source_text_supported:{normalized_id}"
951
+ if source.get("needs_external_extraction_tool") is not True:
952
+ return ARTIFACT_INVALID, f"evidence_extract_page_inventory_schema_error:{normalized_id}.needs_external_extraction_tool"
953
+ if source.get("visual_inspection_required") is not True:
954
+ return ARTIFACT_INVALID, f"evidence_extract_page_inventory_schema_error:{normalized_id}.visual_inspection_required"
955
+ total_pages += len(pages)
956
+ seen_page_ids: set[str] = set()
957
+ for page_idx, page in enumerate(pages):
958
+ page_reason = _evidence_extract_page_entry_error(
959
+ page,
960
+ source_id=normalized_id,
961
+ page_idx=page_idx,
962
+ seen_page_ids=seen_page_ids,
963
+ expected_char_end=len(locked_source_text) if status == "text_logical_page_seeded" else None,
964
+ expected_page_basis=text_basis if status == "text_logical_page_seeded" else None,
965
+ expected_needs_visual_inspection=(
966
+ text_needs_visual_inspection if status == "text_logical_page_seeded" else None
967
+ ),
968
+ )
969
+ if page_reason:
970
+ return ARTIFACT_INVALID, f"evidence_extract_page_inventory_schema_error:{normalized_id}.{page_reason}"
971
+
972
+ if seen_source_ids != set(lock_by_id):
973
+ return ARTIFACT_INVALID, "evidence_extract_page_inventory_validation_error:source_universe_mismatch"
974
+ if payload.get("page_count") != total_pages:
975
+ return ARTIFACT_INVALID, "evidence_extract_page_inventory_schema_error:page_count"
976
+ if payload.get("inventory_source_count") != inventory_sources:
977
+ return ARTIFACT_INVALID, "evidence_extract_page_inventory_schema_error:inventory_source_count"
978
+ return ARTIFACT_VALID, "experimental_evidence_extract_page_inventory"
979
+
980
+
981
+ def _evidence_extract_page_entry_error(
982
+ page: Any,
983
+ *,
984
+ source_id: str,
985
+ page_idx: int,
986
+ seen_page_ids: set[str],
987
+ expected_char_end: int | None,
988
+ expected_page_basis: str | None = None,
989
+ expected_needs_visual_inspection: bool | None = None,
990
+ ) -> str | None:
991
+ if not isinstance(page, dict):
992
+ return f"pages[{page_idx}]"
993
+ page_id = page.get("page_id")
994
+ expected_page_id = f"PAGE-{source_id}-{page_idx + 1:03d}"
995
+ if page_id != expected_page_id:
996
+ return f"pages[{page_idx}].page_id"
997
+ if page_id in seen_page_ids:
998
+ return f"duplicate_page_id:{page_id}"
999
+ seen_page_ids.add(page_id)
1000
+ if page.get("page_number") != page_idx + 1:
1001
+ return f"pages[{page_idx}].page_number"
1002
+ if page.get("page_label") != f"logical-page-{page_idx + 1}":
1003
+ return f"pages[{page_idx}].page_label"
1004
+ if expected_page_basis is not None and page.get("page_basis") != expected_page_basis:
1005
+ return f"pages[{page_idx}].page_basis"
1006
+ if page.get("has_searchable_text") is not True:
1007
+ return f"pages[{page_idx}].has_searchable_text"
1008
+ if (
1009
+ expected_needs_visual_inspection is not None
1010
+ and page.get("needs_visual_inspection") is not expected_needs_visual_inspection
1011
+ ):
1012
+ return f"pages[{page_idx}].needs_visual_inspection"
1013
+ char_start = page.get("char_start")
1014
+ char_end = page.get("char_end")
1015
+ if not isinstance(char_start, int) or char_start < 0:
1016
+ return f"pages[{page_idx}].char_start"
1017
+ if not isinstance(char_end, int) or char_end < char_start:
1018
+ return f"pages[{page_idx}].char_end"
1019
+ if expected_char_end is not None and (char_start != 0 or char_end != expected_char_end):
1020
+ return f"pages[{page_idx}].char_range"
1021
+ return None
1022
+
1023
+
1024
+ def _evidence_extract_inventory_text_binding(
1025
+ *,
1026
+ workspace: Path,
1027
+ lock_source: dict[str, Any],
1028
+ locked_path: Path,
1029
+ ) -> tuple[str, str | None, str, str, str, bool]:
1030
+ derived = lock_source.get("derived_markdown")
1031
+ if isinstance(derived, dict):
1032
+ rel_path = str(derived.get("path") or "")
1033
+ derived_path, path_reason = _evidence_extract_locked_source_path(
1034
+ workspace=workspace,
1035
+ rel_path=rel_path,
1036
+ )
1037
+ if path_reason or derived_path is None:
1038
+ return "", "derived_markdown_path_unsafe", "mineru_derived_markdown", rel_path, "", True
1039
+ text, reason = _evidence_extract_inventory_text_for_source(derived_path)
1040
+ return (
1041
+ text,
1042
+ reason,
1043
+ "mineru_derived_markdown",
1044
+ rel_path,
1045
+ str(derived.get("sha256") or ""),
1046
+ True,
1047
+ )
1048
+
1049
+ text, reason = _evidence_extract_inventory_text_for_source(locked_path)
1050
+ return (
1051
+ text,
1052
+ reason,
1053
+ "utf8_text_file",
1054
+ str(lock_source.get("path") or ""),
1055
+ str(lock_source.get("source_sha256") or ""),
1056
+ False,
1057
+ )
1058
+
1059
+
1060
+ def _evidence_extract_inventory_text_for_source(path: Path) -> tuple[str, str | None]:
1061
+ try:
1062
+ raw_text = path.read_text(encoding="utf-8")
1063
+ except (OSError, UnicodeDecodeError):
1064
+ return "", "source_text_unreadable"
1065
+ if path.suffix.lower() == ".json":
1066
+ try:
1067
+ payload = json.loads(raw_text)
1068
+ except json.JSONDecodeError:
1069
+ return raw_text, None
1070
+ if isinstance(payload, dict) and isinstance(payload.get("content"), str):
1071
+ return payload["content"], None
1072
+ return raw_text, None
1073
+
1074
+
1075
+ def _validate_human_approval_ledger_payload(payload: Any, *, artifact_path: Path) -> tuple[str, str]:
1076
+ from multi_agent_brief.product.release_approval import (
1077
+ validate_human_approval_ledger_event_links,
1078
+ validate_human_approval_ledger_payload,
1079
+ )
1080
+
1081
+ reason = validate_human_approval_ledger_payload(payload)
1082
+ if reason:
1083
+ return ARTIFACT_INVALID, reason
1084
+ workspace = artifact_path.parents[2]
1085
+ link_reason = validate_human_approval_ledger_event_links(payload, workspace=workspace)
1086
+ if link_reason:
1087
+ return ARTIFACT_INVALID, link_reason
1088
+ return ARTIFACT_VALID, "experimental_human_approval_ledger"
1089
+
1090
+
1091
+ def _validate_release_readiness_report_payload(payload: Any, *, artifact_path: Path) -> tuple[str, str]:
1092
+ from multi_agent_brief.product.release_approval import (
1093
+ validate_release_readiness_report_event_link,
1094
+ validate_release_readiness_report_payload,
1095
+ )
1096
+
1097
+ reason = validate_release_readiness_report_payload(payload)
1098
+ if reason:
1099
+ return ARTIFACT_INVALID, reason
1100
+ workspace = artifact_path.parents[2]
1101
+ link_reason = validate_release_readiness_report_event_link(payload, workspace=workspace)
1102
+ if link_reason:
1103
+ return ARTIFACT_INVALID, link_reason
1104
+ return ARTIFACT_VALID, "experimental_release_readiness_report"
1105
+
1106
+
1107
+ def _validate_quality_panel_payload(payload: Any) -> tuple[str, str]:
1108
+ reason = validate_quality_panel_payload(payload)
1109
+ if reason:
1110
+ return ARTIFACT_INVALID, reason
1111
+ return ARTIFACT_VALID, "experimental_quality_panel"
1112
+
1113
+
1114
+ def _validate_guidance_manifestation_report_payload(payload: Any, *, artifact_path: Path) -> tuple[str, str]:
1115
+ current_run_id = ""
1116
+ manifest_path = artifact_path.with_name("runtime_manifest.json")
1117
+ try:
1118
+ manifest_payload = json.loads(manifest_path.read_text(encoding="utf-8"))
1119
+ except (OSError, UnicodeDecodeError, json.JSONDecodeError):
1120
+ manifest_payload = {}
1121
+ if isinstance(manifest_payload, dict):
1122
+ current_run_id = str(manifest_payload.get("run_id") or "").strip()
1123
+ improvement = manifest_payload.get("improvement") if isinstance(manifest_payload, dict) else {}
1124
+ materialized_entry_ids = (
1125
+ [str(item).strip() for item in improvement.get("materialized_entry_ids") if str(item).strip()]
1126
+ if isinstance(improvement, dict) and isinstance(improvement.get("materialized_entry_ids"), list)
1127
+ else []
1128
+ )
1129
+ reason = validate_guidance_manifestation_report_payload(
1130
+ payload,
1131
+ current_run_id=current_run_id or None,
1132
+ materialized_entry_ids=materialized_entry_ids,
1133
+ )
1134
+ if reason:
1135
+ return ARTIFACT_INVALID, reason
1136
+ return ARTIFACT_VALID, "experimental_guidance_manifestation_report"
1137
+
1138
+
1139
+ def _validate_quality_summary_markdown(text: str, *, artifact_path: Path) -> tuple[str, str]:
1140
+ reason = validate_quality_summary_markdown(text)
1141
+ if reason:
1142
+ return ARTIFACT_INVALID, reason
1143
+ panel_path = artifact_path.with_name("quality_panel.json")
1144
+ if not panel_path.exists():
1145
+ return ARTIFACT_INVALID, "quality_summary_validation_error:quality_panel_missing"
1146
+ try:
1147
+ panel_payload = json.loads(panel_path.read_text(encoding="utf-8"))
1148
+ except (OSError, UnicodeDecodeError):
1149
+ return ARTIFACT_INVALID, "quality_summary_validation_error:quality_panel_unreadable"
1150
+ except json.JSONDecodeError:
1151
+ return ARTIFACT_INVALID, "quality_summary_validation_error:quality_panel_parse_error"
1152
+ if not isinstance(panel_payload, dict):
1153
+ return ARTIFACT_INVALID, "quality_summary_validation_error:quality_panel_invalid:not_object"
1154
+ panel_reason = validate_quality_panel_payload(panel_payload)
1155
+ if panel_reason:
1156
+ return ARTIFACT_INVALID, f"quality_summary_validation_error:quality_panel_invalid:{panel_reason}"
1157
+ try:
1158
+ expected = render_quality_summary(panel_payload, quality_panel_sha256=_sha256_file(panel_path))
1159
+ except QualityPanelError as exc:
1160
+ return ARTIFACT_INVALID, f"quality_summary_validation_error:render:{exc}"
1161
+ if text != expected:
1162
+ return ARTIFACT_INVALID, "quality_summary_validation_error:stale_or_hand_edited"
1163
+ return ARTIFACT_VALID, "experimental_quality_summary_markdown"
1164
+
1165
+
1166
+ def _validate_quality_panel_html(text: str, *, artifact_path: Path) -> tuple[str, str]:
1167
+ reason = validate_quality_panel_html(text)
1168
+ if reason:
1169
+ return ARTIFACT_INVALID, reason
1170
+ panel_path = artifact_path.with_name("quality_panel.json")
1171
+ if not panel_path.exists():
1172
+ return ARTIFACT_INVALID, "quality_panel_html_validation_error:quality_panel_missing"
1173
+ try:
1174
+ panel_payload = json.loads(panel_path.read_text(encoding="utf-8"))
1175
+ except (OSError, UnicodeDecodeError):
1176
+ return ARTIFACT_INVALID, "quality_panel_html_validation_error:quality_panel_unreadable"
1177
+ except json.JSONDecodeError:
1178
+ return ARTIFACT_INVALID, "quality_panel_html_validation_error:quality_panel_parse_error"
1179
+ if not isinstance(panel_payload, dict):
1180
+ return ARTIFACT_INVALID, "quality_panel_html_validation_error:quality_panel_invalid:not_object"
1181
+ panel_reason = validate_quality_panel_payload(panel_payload)
1182
+ if panel_reason:
1183
+ return ARTIFACT_INVALID, f"quality_panel_html_validation_error:quality_panel_invalid:{panel_reason}"
1184
+ try:
1185
+ expected = render_quality_panel_html(panel_payload, quality_panel_sha256=_sha256_file(panel_path))
1186
+ except QualityPanelError as exc:
1187
+ return ARTIFACT_INVALID, f"quality_panel_html_validation_error:render:{exc}"
1188
+ if text != expected:
1189
+ return ARTIFACT_INVALID, "quality_panel_html_validation_error:stale_or_hand_edited"
1190
+ return ARTIFACT_VALID, "experimental_quality_panel_html"
1191
+
1192
+
1193
+ def _workspace_root_for_input_classification(artifact_path: Path) -> Path | None:
1194
+ if artifact_path.name == "input_classification.json" and artifact_path.parent.name == "output":
1195
+ return artifact_path.parent.parent
1196
+ return None
1197
+
1198
+
1199
+ def _input_classification_path_is_unsafe(value: str, *, workspace: Path | None) -> bool:
1200
+ raw = value.strip()
1201
+ if not raw:
1202
+ return False
1203
+ if raw.startswith("~"):
1204
+ return True
1205
+ normalized = raw.replace("\\", "/")
1206
+ posix_path = PurePosixPath(normalized)
1207
+ windows_path = PureWindowsPath(raw)
1208
+ if ".." in posix_path.parts or ".." in windows_path.parts:
1209
+ return True
1210
+ path = Path(raw)
1211
+ if path.is_absolute():
1212
+ if workspace is None:
1213
+ return True
1214
+ try:
1215
+ path.resolve(strict=False).relative_to(workspace.resolve(strict=False))
1216
+ except ValueError:
1217
+ return True
1218
+ return False
1219
+ if windows_path.drive:
1220
+ return True
1221
+ return False
1222
+
1223
+
1224
+ def _non_empty_string(value: Any) -> bool:
1225
+ return isinstance(value, str) and bool(value.strip())
1226
+
1227
+
1228
+ def _validate_claim_ledger_payload(payload: Any) -> tuple[str, str]:
1229
+ try:
1230
+ claims = ClaimLedger._claim_items_from_json(payload)
1231
+ except ValueError as exc:
1232
+ return ARTIFACT_INVALID, f"claim_ledger_schema_error:{exc}"
1233
+
1234
+ seen_ids: set[str] = set()
1235
+ for idx, claim in enumerate(claims):
1236
+ for field in ("claim_id", "statement", "source_id", "evidence_text"):
1237
+ value = claim.get(field)
1238
+ if not isinstance(value, str) or not value.strip():
1239
+ return ARTIFACT_INVALID, f"claim_ledger_schema_error:claim[{idx}].{field}"
1240
+ claim_id = str(claim["claim_id"]).strip()
1241
+ if claim_id in seen_ids:
1242
+ return ARTIFACT_INVALID, f"claim_ledger_schema_error:duplicate_claim_id:{claim_id}"
1243
+ seen_ids.add(claim_id)
1244
+ violations = ClaimContract.validate(claim)
1245
+ errors = [violation for violation in violations if violation.severity == "error"]
1246
+ if errors:
1247
+ first = errors[0]
1248
+ return ARTIFACT_INVALID, f"claim_ledger_schema_error:claim[{idx}].{first.field}"
1249
+
1250
+ try:
1251
+ ledger = ClaimLedger([Claim.from_dict(item) for item in claims])
1252
+ except (TypeError, ValueError) as exc:
1253
+ return ARTIFACT_INVALID, f"claim_ledger_schema_error:{exc}"
1254
+ errors = ledger.validate_claims()
1255
+ if errors:
1256
+ return ARTIFACT_INVALID, f"claim_ledger_schema_error:{errors[0]}"
1257
+ return ARTIFACT_VALID, "valid_claim_ledger_schema"
1258
+
1259
+
1260
+ def _validate_claim_drafts_payload(payload: Any) -> tuple[str, str]:
1261
+ if not isinstance(payload, dict):
1262
+ return ARTIFACT_INVALID, "claim_drafts_schema_error:not_object"
1263
+ violations = ClaimDraftContract.validate(payload)
1264
+ errors = [violation for violation in violations if violation.severity == "error"]
1265
+ if errors:
1266
+ first = errors[0]
1267
+ return ARTIFACT_INVALID, f"claim_drafts_schema_error:{first.field}"
1268
+ return ARTIFACT_VALID, "valid_claim_drafts_schema"
1269
+
1270
+
1271
+ def _validate_atomic_claim_graph_payload(payload: Any, *, artifact_path: Path) -> tuple[str, str]:
1272
+ if not isinstance(payload, dict):
1273
+ return ARTIFACT_INVALID, "atomic_claim_graph_schema_error:not_object"
1274
+ violations = AtomicClaimGraphContract.validate(payload)
1275
+ errors = [violation for violation in violations if violation.severity == "error"]
1276
+ if errors:
1277
+ first = errors[0]
1278
+ return ARTIFACT_INVALID, f"atomic_claim_graph_schema_error:{first.field}"
1279
+
1280
+ ledger_path = artifact_path.with_name("claim_ledger.json")
1281
+ try:
1282
+ ledger_payload = json.loads(ledger_path.read_text(encoding="utf-8"))
1283
+ ledger_claims = ClaimLedger._claim_items_from_json(ledger_payload)
1284
+ except FileNotFoundError:
1285
+ return ARTIFACT_INVALID, f"{ATOMIC_CLAIM_GRAPH_VALIDATION_PREFIX}:claim_ledger_missing"
1286
+ except (OSError, UnicodeDecodeError, json.JSONDecodeError, ValueError) as exc:
1287
+ return ARTIFACT_INVALID, f"{ATOMIC_CLAIM_GRAPH_VALIDATION_PREFIX}:claim_ledger_unreadable:{exc}"
1288
+
1289
+ reason = validate_atomic_claim_graph_against_ledger(
1290
+ graph_payload=payload,
1291
+ ledger_claims=ledger_claims,
1292
+ )
1293
+ if reason:
1294
+ return ARTIFACT_INVALID, f"{ATOMIC_CLAIM_GRAPH_VALIDATION_PREFIX}:{reason}"
1295
+
1296
+ return ARTIFACT_VALID, "experimental_atomic_claim_graph_schema"
1297
+
1298
+
1299
+ def _validate_evidence_span_registry_payload(payload: Any, *, artifact_path: Path) -> tuple[str, str]:
1300
+ if not isinstance(payload, dict):
1301
+ return ARTIFACT_INVALID, "evidence_span_registry_schema_error:not_object"
1302
+ violations = EvidenceSpanRegistryContract.validate(payload)
1303
+ errors = [violation for violation in violations if violation.severity == "error"]
1304
+ if errors:
1305
+ first = errors[0]
1306
+ return ARTIFACT_INVALID, f"evidence_span_registry_schema_error:{first.field}"
1307
+
1308
+ workspace = artifact_path.parents[2]
1309
+ page_inventory_payload = _valid_evidence_extract_page_inventory_payload_for_span_registry(
1310
+ artifact_path.with_name("evidence_extract_page_inventory.json")
1311
+ )
1312
+ reason = validate_evidence_span_registry_against_source_pack(
1313
+ registry_payload=payload,
1314
+ workspace=workspace,
1315
+ page_inventory_payload=page_inventory_payload,
1316
+ )
1317
+ if reason:
1318
+ return ARTIFACT_INVALID, f"{EVIDENCE_SPAN_REGISTRY_VALIDATION_PREFIX}:{reason}"
1319
+
1320
+ return ARTIFACT_VALID, "experimental_evidence_span_registry_schema"
1321
+
1322
+
1323
+ def _valid_evidence_extract_page_inventory_payload_for_span_registry(path: Path) -> dict[str, Any] | None:
1324
+ if not path.exists():
1325
+ return None
1326
+ try:
1327
+ payload = json.loads(path.read_text(encoding="utf-8"))
1328
+ except (OSError, UnicodeDecodeError, json.JSONDecodeError):
1329
+ return None
1330
+ status, _validation_result = _validate_evidence_extract_page_inventory_payload(payload, artifact_path=path)
1331
+ if status != ARTIFACT_VALID:
1332
+ return None
1333
+ return payload if isinstance(payload, dict) else None
1334
+
1335
+
1336
+ def _validate_claim_support_matrix_payload(payload: Any, *, artifact_path: Path) -> tuple[str, str]:
1337
+ if not isinstance(payload, dict):
1338
+ return ARTIFACT_INVALID, "claim_support_matrix_schema_error:not_object"
1339
+ violations = ClaimSupportMatrixContract.validate(payload)
1340
+ errors = [violation for violation in violations if violation.severity == "error"]
1341
+ if errors:
1342
+ first = errors[0]
1343
+ return ARTIFACT_INVALID, f"claim_support_matrix_schema_error:{first.field}"
1344
+
1345
+ ledger_claims, reason = _claim_support_matrix_ledger_claims(artifact_path.with_name("claim_ledger.json"))
1346
+ if reason:
1347
+ return ARTIFACT_INVALID, f"{CLAIM_SUPPORT_MATRIX_VALIDATION_PREFIX}:{reason}"
1348
+ graph_payload, reason = _claim_support_matrix_atomic_graph_payload(artifact_path.with_name("atomic_claim_graph.json"))
1349
+ if reason:
1350
+ return ARTIFACT_INVALID, f"{CLAIM_SUPPORT_MATRIX_VALIDATION_PREFIX}:{reason}"
1351
+ evidence_payload, reason = _claim_support_matrix_evidence_span_registry_payload(
1352
+ artifact_path.with_name("evidence_span_registry.json")
1353
+ )
1354
+ if reason:
1355
+ return ARTIFACT_INVALID, f"{CLAIM_SUPPORT_MATRIX_VALIDATION_PREFIX}:{reason}"
1356
+
1357
+ reason = validate_claim_support_matrix_against_artifacts(
1358
+ matrix_payload=payload,
1359
+ ledger_claims=ledger_claims or [],
1360
+ graph_payload=graph_payload or {},
1361
+ evidence_span_registry_payload=evidence_payload or {},
1362
+ )
1363
+ if reason:
1364
+ return ARTIFACT_INVALID, f"{CLAIM_SUPPORT_MATRIX_VALIDATION_PREFIX}:{reason}"
1365
+ return ARTIFACT_VALID, "experimental_claim_support_matrix_schema"
1366
+
1367
+
1368
+ def _validate_semantic_assessment_report_payload(payload: Any, *, artifact_path: Path) -> tuple[str, str]:
1369
+ if not isinstance(payload, dict):
1370
+ return ARTIFACT_INVALID, "semantic_assessment_report_schema_error:not_object"
1371
+ violations = SemanticAssessmentReportContract.validate(payload)
1372
+ errors = [violation for violation in violations if violation.severity == "error"]
1373
+ if errors:
1374
+ first = errors[0]
1375
+ return ARTIFACT_INVALID, f"semantic_assessment_report_schema_error:{first.field}"
1376
+
1377
+ ledger_claims, reason = _claim_support_matrix_ledger_claims(artifact_path.with_name("claim_ledger.json"))
1378
+ if reason:
1379
+ return ARTIFACT_INVALID, f"{SEMANTIC_ASSESSMENT_REPORT_VALIDATION_PREFIX}:{reason}"
1380
+ graph_payload, reason = _claim_support_matrix_atomic_graph_payload(artifact_path.with_name("atomic_claim_graph.json"))
1381
+ if reason:
1382
+ return ARTIFACT_INVALID, f"{SEMANTIC_ASSESSMENT_REPORT_VALIDATION_PREFIX}:{reason}"
1383
+ evidence_payload, reason = _claim_support_matrix_evidence_span_registry_payload(
1384
+ artifact_path.with_name("evidence_span_registry.json")
1385
+ )
1386
+ if reason:
1387
+ return ARTIFACT_INVALID, f"{SEMANTIC_ASSESSMENT_REPORT_VALIDATION_PREFIX}:{reason}"
1388
+
1389
+ reason = validate_semantic_assessment_report_against_artifacts(
1390
+ report_payload=payload,
1391
+ ledger_claims=ledger_claims or [],
1392
+ graph_payload=graph_payload or {},
1393
+ evidence_span_registry_payload=evidence_payload or {},
1394
+ )
1395
+ if reason:
1396
+ return ARTIFACT_INVALID, f"{SEMANTIC_ASSESSMENT_REPORT_VALIDATION_PREFIX}:{reason}"
1397
+ workspace = artifact_path.parent.parent.parent if artifact_path.parent.name == "intermediate" else artifact_path.parent
1398
+ reason = validate_semantic_assessment_checked_inputs_for_workspace(
1399
+ report_payload=payload,
1400
+ workspace=workspace,
1401
+ )
1402
+ if reason:
1403
+ return ARTIFACT_INVALID, f"{SEMANTIC_ASSESSMENT_REPORT_VALIDATION_PREFIX}:{reason}"
1404
+ return ARTIFACT_VALID, "experimental_semantic_assessment_report_schema"
1405
+
1406
+
1407
+ def _validate_semantic_support_acceptance_ledger_payload(payload: Any, *, artifact_path: Path) -> tuple[str, str]:
1408
+ reason = validate_semantic_support_acceptance_ledger_for_workspace(payload, artifact_path=artifact_path)
1409
+ if reason:
1410
+ return ARTIFACT_INVALID, f"semantic_support_acceptance_ledger_schema_error:{reason}"
1411
+ return ARTIFACT_VALID, "experimental_semantic_support_acceptance_ledger"
1412
+
1413
+
1414
+ def _claim_support_matrix_ledger_claims(path: Path) -> tuple[list[dict[str, Any]] | None, str | None]:
1415
+ try:
1416
+ payload = json.loads(path.read_text(encoding="utf-8"))
1417
+ except FileNotFoundError:
1418
+ return None, "claim_ledger_missing"
1419
+ except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc:
1420
+ return None, f"claim_ledger_unreadable:{exc}"
1421
+ status, validation_result = _validate_claim_ledger_payload(payload)
1422
+ if status != ARTIFACT_VALID:
1423
+ return None, _dependency_invalid_reason(
1424
+ "claim_ledger",
1425
+ validation_result,
1426
+ prefixes=("claim_ledger_schema_error",),
1427
+ )
1428
+ try:
1429
+ claims = ClaimLedger._claim_items_from_json(payload)
1430
+ except ValueError as exc:
1431
+ return None, f"claim_ledger_unreadable:{exc}"
1432
+ return claims, None
1433
+
1434
+
1435
+ def _claim_support_matrix_atomic_graph_payload(path: Path) -> tuple[dict[str, Any] | None, str | None]:
1436
+ payload, reason = _read_claim_support_matrix_json(path, missing_reason="atomic_claim_graph_missing")
1437
+ if reason:
1438
+ return None, reason
1439
+ assert payload is not None
1440
+ status, validation_result = _validate_atomic_claim_graph_payload(payload, artifact_path=path)
1441
+ if status != ARTIFACT_VALID:
1442
+ return None, _dependency_invalid_reason(
1443
+ "atomic_claim_graph",
1444
+ validation_result,
1445
+ prefixes=("atomic_claim_graph_schema_error", ATOMIC_CLAIM_GRAPH_VALIDATION_PREFIX),
1446
+ )
1447
+ return payload, None
1448
+
1449
+
1450
+ def _claim_support_matrix_evidence_span_registry_payload(path: Path) -> tuple[dict[str, Any] | None, str | None]:
1451
+ payload, reason = _read_claim_support_matrix_json(path, missing_reason="evidence_span_registry_missing")
1452
+ if reason:
1453
+ return None, reason
1454
+ assert payload is not None
1455
+ status, validation_result = _validate_evidence_span_registry_payload(payload, artifact_path=path)
1456
+ if status != ARTIFACT_VALID:
1457
+ return None, _dependency_invalid_reason(
1458
+ "evidence_span_registry",
1459
+ validation_result,
1460
+ prefixes=("evidence_span_registry_schema_error", EVIDENCE_SPAN_REGISTRY_VALIDATION_PREFIX),
1461
+ )
1462
+ return payload, None
1463
+
1464
+
1465
+ def _read_claim_support_matrix_json(path: Path, *, missing_reason: str) -> tuple[Any | None, str | None]:
1466
+ try:
1467
+ return json.loads(path.read_text(encoding="utf-8")), None
1468
+ except FileNotFoundError:
1469
+ return None, missing_reason
1470
+ except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc:
1471
+ return None, f"{missing_reason.removesuffix('_missing')}_unreadable:{exc}"
1472
+
1473
+
1474
+ def _dependency_invalid_reason(label: str, validation_result: str, *, prefixes: tuple[str, ...]) -> str:
1475
+ for prefix in prefixes:
1476
+ marker = f"{prefix}:"
1477
+ if validation_result.startswith(marker):
1478
+ return f"{label}_invalid:{validation_result.removeprefix(marker)}"
1479
+ return f"{label}_invalid:{validation_result}"
1480
+
1481
+
1482
+ def _validate_audit_report_payload(payload: Any) -> tuple[str, str]:
1483
+ if not isinstance(payload, dict):
1484
+ return ARTIFACT_INVALID, "audit_report_schema_error:not_object"
1485
+ violations = AuditReportContract.validate(payload)
1486
+ errors = [violation for violation in violations if violation.severity == "error"]
1487
+ if errors:
1488
+ first = errors[0]
1489
+ return ARTIFACT_INVALID, f"audit_report_schema_error:{first.field}"
1490
+ findings = payload.get("findings")
1491
+ if findings is not None and not isinstance(findings, list):
1492
+ return ARTIFACT_INVALID, "audit_report_schema_error:findings"
1493
+ for idx, finding in enumerate(findings or []):
1494
+ if not isinstance(finding, dict):
1495
+ return ARTIFACT_INVALID, f"audit_report_schema_error:findings[{idx}]"
1496
+ for field in ("finding_id", "severity", "finding_type", "description"):
1497
+ value = finding.get(field)
1498
+ if not isinstance(value, str) or not value.strip():
1499
+ return ARTIFACT_INVALID, f"audit_report_schema_error:findings[{idx}].{field}"
1500
+ if finding.get("severity") not in {"low", "medium", "high"}:
1501
+ return ARTIFACT_INVALID, f"audit_report_schema_error:findings[{idx}].severity"
1502
+ return ARTIFACT_VALID, "valid_audit_report_schema"
1503
+
1504
+
1505
+ def _artifact_record(
1506
+ *,
1507
+ workspace: Path,
1508
+ artifact: dict[str, Any],
1509
+ workflow: dict[str, Any],
1510
+ ) -> dict[str, Any]:
1511
+ artifact_id = str(artifact.get("artifact_id") or "")
1512
+ rel_path = str(artifact.get("path") or "")
1513
+ fmt = str(artifact.get("format") or "")
1514
+ producer_stage = str(artifact.get("producer_stage") or "")
1515
+ status, validation_result = _validate_artifact(workspace / rel_path, fmt, artifact_id)
1516
+
1517
+ activated_optional = optional_feedback_artifact_activated(
1518
+ workspace=workspace,
1519
+ artifact_id=artifact_id,
1520
+ ) or quality_gate_artifact_activated(
1521
+ workspace=workspace,
1522
+ artifact_id=artifact_id,
1523
+ ) or provenance_artifact_activated(
1524
+ workspace=workspace,
1525
+ artifact_id=artifact_id,
1526
+ )
1527
+ if (
1528
+ status == ARTIFACT_EXPECTED
1529
+ and _stage_is_complete_or_skipped(workflow, producer_stage)
1530
+ and (bool(artifact.get("required", False)) or activated_optional)
1531
+ ):
1532
+ status = ARTIFACT_MISSING
1533
+ validation_result = "missing"
1534
+
1535
+ blocking_reason = ""
1536
+ if status == ARTIFACT_MISSING:
1537
+ blocking_reason = f"Producer stage '{producer_stage}' completed but '{rel_path}' is missing."
1538
+ elif status == ARTIFACT_INVALID:
1539
+ blocking_reason = f"Artifact '{rel_path}' failed minimum {fmt} validation."
1540
+
1541
+ path = workspace / rel_path
1542
+ size_bytes = path.stat().st_size if path.exists() and path.is_file() else None
1543
+ mtime = datetime.fromtimestamp(path.stat().st_mtime, timezone.utc).replace(microsecond=0).isoformat() if path.exists() else None
1544
+ sha256 = _sha256_file(path) if path.exists() and path.is_file() else None
1545
+ stale_metadata = _producer_stage_stale_after_repair(workflow, producer_stage)
1546
+ if stale_metadata and path.exists() and path.is_file():
1547
+ status = ARTIFACT_STALE
1548
+ validation_result = "stale_after_repair"
1549
+ repair_tx = stale_metadata.get("repair_transaction_id") or "<unknown>"
1550
+ repair_owner = stale_metadata.get("repair_owner") or "<unknown>"
1551
+ blocking_reason = (
1552
+ f"Artifact '{rel_path}' was produced before owner-stage repair "
1553
+ f"{repair_tx} by '{repair_owner}'; rerun producer stage '{producer_stage}' "
1554
+ "before consuming it."
1555
+ )
1556
+ stale_baseline_sha256 = None
1557
+ if stale_metadata:
1558
+ baselines = (
1559
+ stale_metadata.get("stale_artifact_baselines")
1560
+ if isinstance(stale_metadata.get("stale_artifact_baselines"), dict)
1561
+ else {}
1562
+ )
1563
+ baseline = baselines.get(artifact_id) if isinstance(baselines.get(artifact_id), dict) else {}
1564
+ baseline_sha = baseline.get("sha256")
1565
+ if isinstance(baseline_sha, str) and baseline_sha:
1566
+ stale_baseline_sha256 = baseline_sha
1567
+
1568
+ record = {
1569
+ "artifact_id": artifact_id,
1570
+ "path": rel_path,
1571
+ "format": fmt,
1572
+ "required": bool(artifact.get("required", False)),
1573
+ "producer_stage": producer_stage,
1574
+ "producer_role": artifact.get("producer_role", ""),
1575
+ "consumer_stages": artifact.get("consumer_stages", []),
1576
+ "status": status,
1577
+ "validation_result": validation_result,
1578
+ "blocking_reason": blocking_reason,
1579
+ "allowed_decisions": artifact.get("allowed_decisions", []),
1580
+ "retry_or_human_review_decision": artifact.get("retry_or_human_review_decision", ""),
1581
+ "size_bytes": size_bytes,
1582
+ "mtime": mtime,
1583
+ "sha256": sha256,
1584
+ }
1585
+ if stale_baseline_sha256:
1586
+ record["stale_baseline_sha256"] = stale_baseline_sha256
1587
+ return record
1588
+
1589
+
1590
+ def _producer_stage_stale_after_repair(
1591
+ workflow: dict[str, Any],
1592
+ producer_stage: str,
1593
+ ) -> dict[str, Any] | None:
1594
+ statuses = workflow.get("stage_statuses") if isinstance(workflow.get("stage_statuses"), dict) else {}
1595
+ stage_status = statuses.get(producer_stage) if isinstance(statuses.get(producer_stage), dict) else {}
1596
+ metadata = stage_status.get("metadata") if isinstance(stage_status.get("metadata"), dict) else {}
1597
+ if metadata.get("stale_after_repair") is True:
1598
+ return metadata
1599
+ return None
1600
+
1601
+
1602
+ def _build_artifact_registry(
1603
+ *,
1604
+ workspace: Path,
1605
+ run_id: str,
1606
+ artifacts: list[dict[str, Any]],
1607
+ workflow: dict[str, Any],
1608
+ updated_at: str,
1609
+ ) -> dict[str, Any]:
1610
+ records = {
1611
+ str(artifact.get("artifact_id")): _artifact_record(
1612
+ workspace=workspace,
1613
+ artifact=artifact,
1614
+ workflow=workflow,
1615
+ )
1616
+ for artifact in artifacts
1617
+ if artifact.get("artifact_id")
1618
+ }
1619
+ return {
1620
+ "schema_version": ARTIFACT_REGISTRY_SCHEMA,
1621
+ "run_id": run_id,
1622
+ "updated_at": updated_at,
1623
+ "artifacts": records,
1624
+ }
1625
+
1626
+
1627
+ def _read_json_payload(path: Path) -> Any:
1628
+ try:
1629
+ return json.loads(path.read_text(encoding="utf-8"))
1630
+ except (OSError, UnicodeDecodeError, json.JSONDecodeError):
1631
+ return None
1632
+
1633
+
1634
+ def interpret_frozen_artifact_integrity(
1635
+ *,
1636
+ old_registry: dict[str, Any] | None,
1637
+ registry: dict[str, Any],
1638
+ workflow: dict[str, Any],
1639
+ artifacts: list[dict[str, Any]],
1640
+ stages: list[dict[str, Any]],
1641
+ mutating_stage: str | None = None,
1642
+ ) -> FrozenArtifactIntegrityVerdict:
1643
+ reasons: list[str] = []
1644
+ if old_registry is not None:
1645
+ old_records_raw = old_registry.get("artifacts")
1646
+ if not isinstance(old_records_raw, dict):
1647
+ return _degraded_frozen_artifact_integrity(
1648
+ "artifact_registry.json artifacts must be an object before frozen integrity can be verified."
1649
+ )
1650
+ old_records = old_records_raw
1651
+ else:
1652
+ old_records = {}
1653
+ new_records = registry.get("artifacts")
1654
+ if not isinstance(new_records, dict):
1655
+ return _degraded_frozen_artifact_integrity(
1656
+ "artifact_registry.json artifacts must be an object before frozen integrity can be verified."
1657
+ )
1658
+ mutating_stage_produces = {
1659
+ str(item)
1660
+ for stage in stages
1661
+ if str(stage.get("stage_id") or "") == str(mutating_stage or "")
1662
+ for item in (stage.get("produces") or [])
1663
+ }
1664
+ for artifact in artifacts:
1665
+ artifact_id = str(artifact.get("artifact_id") or "")
1666
+ if not artifact_id:
1667
+ continue
1668
+ if _artifact_is_non_workflow_projection(artifact):
1669
+ continue
1670
+ if artifact_id in mutating_stage_produces:
1671
+ continue
1672
+ producer_stage = str(artifact.get("producer_stage") or "")
1673
+ old_record = old_records.get(artifact_id) or {}
1674
+ old_sha = old_record.get("sha256")
1675
+ if not old_sha:
1676
+ continue
1677
+ producer_verdict = interpret_stage_completion(workflow, producer_stage)
1678
+ if producer_verdict.kind != "canonical":
1679
+ return _degraded_frozen_artifact_integrity(
1680
+ f"Cannot verify frozen artifact '{artifact_id}' because producer stage "
1681
+ f"'{producer_stage}' status is malformed: {' '.join(producer_verdict.reasons)}"
1682
+ )
1683
+ producer_projection = project_stage_completion_for_read(producer_verdict)
1684
+ if producer_projection.get("complete_or_skipped") is not True:
1685
+ continue
1686
+ new_record = new_records.get(artifact_id) or {}
1687
+ new_sha = new_record.get("sha256")
1688
+ path = str(new_record.get("path") or old_record.get("path") or artifact.get("path") or artifact_id)
1689
+ if new_record.get("status") == ARTIFACT_MISSING or not new_sha:
1690
+ reasons.append(
1691
+ f"Frozen artifact '{path}' from owner stage '{producer_stage}' is missing after stage-complete; route repair back to the owner stage."
1692
+ f" {FROZEN_ARTIFACT_CONTROL_FILE_GUIDANCE}"
1693
+ )
1694
+ elif new_sha != old_sha:
1695
+ reason = (
1696
+ f"Frozen artifact '{path}' from owner stage '{producer_stage}' changed after stage-complete; "
1697
+ "route repair back to the owner stage instead of downstream in-place conversion. "
1698
+ f"{FROZEN_ARTIFACT_CONTROL_FILE_GUIDANCE}"
1699
+ )
1700
+ if artifact_id == "claim_ledger":
1701
+ reason = f"{reason} {CLAIM_LEDGER_FROZEN_EDIT_GUIDANCE}"
1702
+ reasons.append(reason)
1703
+ if reasons:
1704
+ return FrozenArtifactIntegrityVerdict(
1705
+ kind="degraded",
1706
+ value={"status": "changed", "matched": False, "contaminates_run": True, "reasons": reasons},
1707
+ reasons=tuple(reasons),
1708
+ contaminates_run=True,
1709
+ )
1710
+ return FrozenArtifactIntegrityVerdict(
1711
+ kind="canonical",
1712
+ value={"status": "matched", "matched": True, "contaminates_run": False, "reasons": []},
1713
+ )
1714
+
1715
+
1716
+ def _artifact_is_non_workflow_projection(artifact: Mapping[str, Any]) -> bool:
1717
+ if str(artifact.get("producer_kind") or "workflow_stage") == "workflow_stage":
1718
+ return False
1719
+ if bool(artifact.get("required", False)):
1720
+ return False
1721
+ consumers = artifact.get("consumer_stages")
1722
+ return not isinstance(consumers, list) or not consumers
1723
+
1724
+
1725
+ def project_frozen_artifact_integrity_for_read(verdict: FrozenArtifactIntegrityVerdict) -> dict[str, Any]:
1726
+ """Return the read-side projection for frozen artifact integrity."""
1727
+
1728
+ return dict(verdict.value)
1729
+
1730
+
1731
+ def require_frozen_artifact_integrity_pass(verdict: FrozenArtifactIntegrityVerdict) -> list[str]:
1732
+ """Return integrity blockers for write paths; empty means pass."""
1733
+
1734
+ if verdict.kind == "canonical":
1735
+ return []
1736
+ return list(verdict.reasons)
1737
+
1738
+
1739
+ def _degraded_frozen_artifact_integrity(reason: str) -> FrozenArtifactIntegrityVerdict:
1740
+ return FrozenArtifactIntegrityVerdict(
1741
+ kind="degraded",
1742
+ value={"status": "unknown", "matched": False, "contaminates_run": False, "reasons": [reason]},
1743
+ reasons=(reason,),
1744
+ )
1745
+
1746
+
1747
+ def _changed_artifact_events(
1748
+ *,
1749
+ old_registry: dict[str, Any] | None,
1750
+ registry: dict[str, Any],
1751
+ ) -> list[dict[str, Any]]:
1752
+ old_records = ((old_registry or {}).get("artifacts") or {})
1753
+ events: list[dict[str, Any]] = []
1754
+ for artifact_id, record in (registry.get("artifacts") or {}).items():
1755
+ old_record = old_records.get(artifact_id) or {}
1756
+ observed_changed = (
1757
+ record.get("status") in {ARTIFACT_VALID, ARTIFACT_INVALID}
1758
+ and (
1759
+ old_record.get("status") != record.get("status")
1760
+ or old_record.get("size_bytes") != record.get("size_bytes")
1761
+ or old_record.get("mtime") != record.get("mtime")
1762
+ )
1763
+ )
1764
+ if observed_changed:
1765
+ events.append({
1766
+ "event_type": "artifact_observed",
1767
+ "artifact_id": str(artifact_id),
1768
+ "metadata": {
1769
+ "path": record.get("path"),
1770
+ "size_bytes": record.get("size_bytes"),
1771
+ "mtime": record.get("mtime"),
1772
+ },
1773
+ })
1774
+
1775
+ validated_changed = (
1776
+ record.get("status") in {
1777
+ ARTIFACT_PRESENT,
1778
+ ARTIFACT_VALID,
1779
+ ARTIFACT_INVALID,
1780
+ ARTIFACT_MISSING,
1781
+ ARTIFACT_STALE,
1782
+ }
1783
+ and (
1784
+ old_record.get("status") != record.get("status")
1785
+ or old_record.get("validation_result") != record.get("validation_result")
1786
+ or old_record.get("blocking_reason") != record.get("blocking_reason")
1787
+ )
1788
+ )
1789
+ if validated_changed:
1790
+ events.append({
1791
+ "event_type": "artifact_validated",
1792
+ "artifact_id": str(artifact_id),
1793
+ "reason": str(record.get("blocking_reason") or ""),
1794
+ "metadata": {
1795
+ "path": record.get("path"),
1796
+ "status": record.get("status"),
1797
+ "validation_result": record.get("validation_result"),
1798
+ },
1799
+ })
1800
+ return events
1801
+
1802
+
1803
+ def _artifact_registry_sha(
1804
+ registry: dict[str, Any],
1805
+ artifact_id: str,
1806
+ ) -> str:
1807
+ record = ((registry.get("artifacts") or {}).get(artifact_id) or {})
1808
+ sha256 = str(record.get("sha256") or "")
1809
+ if not sha256:
1810
+ path = str(record.get("path") or artifact_id)
1811
+ raise RuntimeStateError(
1812
+ f"Artifact '{artifact_id}' has no frozen sha256 in artifact_registry.json.",
1813
+ details={"artifact_id": artifact_id, "path": path},
1814
+ error_code=E_TRANSACTION_INTEGRITY,
1815
+ )
1816
+ return sha256
1817
+
1818
+
1819
+ def _artifact_registry_path(
1820
+ registry: dict[str, Any],
1821
+ artifact_id: str,
1822
+ default: str,
1823
+ ) -> str:
1824
+ record = ((registry.get("artifacts") or {}).get(artifact_id) or {})
1825
+ return str(record.get("path") or default)