openstategraph 0.3.0__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 (456) hide show
  1. openstategraph/__init__.py +116 -0
  2. openstategraph/_extras.py +176 -0
  3. openstategraph/abc/__init__.py +146 -0
  4. openstategraph/abc/agent.py +571 -0
  5. openstategraph/abc/async_doors.py +186 -0
  6. openstategraph/abc/async_task_middleware.py +574 -0
  7. openstategraph/abc/criteria_check.py +59 -0
  8. openstategraph/abc/deep_tier_offload.py +809 -0
  9. openstategraph/abc/grader.py +425 -0
  10. openstategraph/abc/guardrail.py +416 -0
  11. openstategraph/abc/kanban_store.py +635 -0
  12. openstategraph/abc/middleware.py +111 -0
  13. openstategraph/abc/narration.py +640 -0
  14. openstategraph/abc/node_family.py +251 -0
  15. openstategraph/abc/orchestrator.py +852 -0
  16. openstategraph/abc/prompt.py +316 -0
  17. openstategraph/abc/router.py +501 -0
  18. openstategraph/abc/run_context_prompt.py +133 -0
  19. openstategraph/abc/tool.py +656 -0
  20. openstategraph/abc/tool_findings.py +766 -0
  21. openstategraph/abc/tool_notes.py +891 -0
  22. openstategraph/abc/tool_sentences.py +325 -0
  23. openstategraph/agent_brief.md +158 -0
  24. openstategraph/agent_brief.py +123 -0
  25. openstategraph/agent_config.py +436 -0
  26. openstategraph/agent_skills/kanban-patrol/SKILL.md +100 -0
  27. openstategraph/agent_skills/openstategraph/SKILL.md +250 -0
  28. openstategraph/agent_skills/openstategraph/references/build-loop.md +189 -0
  29. openstategraph/agent_skills/openstategraph/references/environments.md +117 -0
  30. openstategraph/agent_skills/openstategraph/references/interview.md +138 -0
  31. openstategraph/agent_skills/openstategraph/references/shapes.md +278 -0
  32. openstategraph/agent_skills/openstategraph/references/subagents.md +80 -0
  33. openstategraph/agent_skills/ticket-forge/SKILL.md +62 -0
  34. openstategraph/api/__init__.py +26 -0
  35. openstategraph/api/ambient_tools.py +65 -0
  36. openstategraph/api/audience.py +608 -0
  37. openstategraph/api/auth.py +397 -0
  38. openstategraph/api/broadcast.py +257 -0
  39. openstategraph/api/burst_recorder.py +175 -0
  40. openstategraph/api/capability_discovery.py +751 -0
  41. openstategraph/api/catalogue_events.py +148 -0
  42. openstategraph/api/chat_page.py +20 -0
  43. openstategraph/api/customer_graph.py +220 -0
  44. openstategraph/api/deps.py +103 -0
  45. openstategraph/api/diagram.py +102 -0
  46. openstategraph/api/editor_assets.py +352 -0
  47. openstategraph/api/embed.py +125 -0
  48. openstategraph/api/frame_clock.py +137 -0
  49. openstategraph/api/kanban_events.py +244 -0
  50. openstategraph/api/knowledge_build.py +162 -0
  51. openstategraph/api/knowledge_curation.py +176 -0
  52. openstategraph/api/listening.py +104 -0
  53. openstategraph/api/live_stream.py +150 -0
  54. openstategraph/api/main.py +366 -0
  55. openstategraph/api/model_resolution.py +319 -0
  56. openstategraph/api/mount_resolution.py +232 -0
  57. openstategraph/api/openapi_document.py +91 -0
  58. openstategraph/api/patrol_events.py +170 -0
  59. openstategraph/api/patrol_registry.py +136 -0
  60. openstategraph/api/plugin_capabilities.py +341 -0
  61. openstategraph/api/registries.py +454 -0
  62. openstategraph/api/routes/__init__.py +15 -0
  63. openstategraph/api/routes/chat_ui.py +57 -0
  64. openstategraph/api/routes/demo.py +68 -0
  65. openstategraph/api/routes/examples.py +92 -0
  66. openstategraph/api/routes/kanban.py +469 -0
  67. openstategraph/api/routes/mcp.py +324 -0
  68. openstategraph/api/routes/providers.py +130 -0
  69. openstategraph/api/routes/recordings.py +288 -0
  70. openstategraph/api/routes/runs.py +725 -0
  71. openstategraph/api/routes/site.py +80 -0
  72. openstategraph/api/routes/system.py +316 -0
  73. openstategraph/api/routes/threads.py +103 -0
  74. openstategraph/api/routes/workflows.py +1092 -0
  75. openstategraph/api/schemas.py +1765 -0
  76. openstategraph/api/services.py +447 -0
  77. openstategraph/api/site_pages.py +120 -0
  78. openstategraph/api/sse_contract.py +139 -0
  79. openstategraph/api/static/chat.html +2292 -0
  80. openstategraph/api/static/editor/assets/__vite-browser-external-DvHC826_.js +2 -0
  81. openstategraph/api/static/editor/assets/abnfDiagram-N423BO3Z-BSwYC7ml.js +2 -0
  82. openstategraph/api/static/editor/assets/arc-DDMrFQ_b.js +2 -0
  83. openstategraph/api/static/editor/assets/architecture-TIHT7OUA-JHDAwbjN.js +1 -0
  84. openstategraph/api/static/editor/assets/architectureDiagram-T3A2C74G-BP7p2NAG.js +37 -0
  85. openstategraph/api/static/editor/assets/archivo-latin-ext-wght-normal-C4zznr8T.woff2 +0 -0
  86. openstategraph/api/static/editor/assets/archivo-latin-wght-normal-E0tuGl4L.woff2 +0 -0
  87. openstategraph/api/static/editor/assets/array-BifhSqXX.js +2 -0
  88. openstategraph/api/static/editor/assets/blockDiagram-VBNYF7ZC-0h_dkxD-.js +133 -0
  89. openstategraph/api/static/editor/assets/c4Diagram-5PPSVZJV-DwLWEqq_.js +11 -0
  90. openstategraph/api/static/editor/assets/channel-Db-O9VqS.js +2 -0
  91. openstategraph/api/static/editor/assets/chunk-2GRJ4B5K-DXBJ0RsQ.js +2 -0
  92. openstategraph/api/static/editor/assets/chunk-2Q5K7J3B-C1jixKkw.js +2 -0
  93. openstategraph/api/static/editor/assets/chunk-4I5QYGJK-CsFwS4Lg.js +2 -0
  94. openstategraph/api/static/editor/assets/chunk-5RXB4S5H-BSEGk_ut.js +232 -0
  95. openstategraph/api/static/editor/assets/chunk-5VM5RSS4-ZNzvKenW.js +16 -0
  96. openstategraph/api/static/editor/assets/chunk-6Q2QTUOP-BHAoBLWf.js +89 -0
  97. openstategraph/api/static/editor/assets/chunk-7BUUIJ7U-Bb538aSH.js +2 -0
  98. openstategraph/api/static/editor/assets/chunk-7Z6QIM7H-B5bFtaqu.js +11 -0
  99. openstategraph/api/static/editor/assets/chunk-GF5L2VYU-DG5c0NFA.js +207 -0
  100. openstategraph/api/static/editor/assets/chunk-I66GZJ75-DmCheD4s.js +128 -0
  101. openstategraph/api/static/editor/assets/chunk-JQJVKLGR-8idHhP4j.js +157 -0
  102. openstategraph/api/static/editor/assets/chunk-JWPE2WC7-DVXcaiue.js +2 -0
  103. openstategraph/api/static/editor/assets/chunk-KBJHAD2P-BT9F3jrA.js +2 -0
  104. openstategraph/api/static/editor/assets/chunk-KEIR6QF5-DEvma7oi.js +162 -0
  105. openstategraph/api/static/editor/assets/chunk-NSK5VX7P-Dgz6OU53.js +3 -0
  106. openstategraph/api/static/editor/assets/chunk-QR6OTTB3-fys2tz_Z.js +63 -0
  107. openstategraph/api/static/editor/assets/chunk-RYQCIY6F-CRj7pW-i.js +2 -0
  108. openstategraph/api/static/editor/assets/chunk-UBXNYLIW-BK_OvCxP.js +2 -0
  109. openstategraph/api/static/editor/assets/chunk-W5SLKNZC-DCbgXbJu.js +2 -0
  110. openstategraph/api/static/editor/assets/chunk-WRU74C26-Dnm_SPAR.js +71 -0
  111. openstategraph/api/static/editor/assets/chunk-XXDRQBXY-CRqRy7wC.js +2 -0
  112. openstategraph/api/static/editor/assets/chunk-Y2CYZVJY-DsF7k-Jl.js +2 -0
  113. openstategraph/api/static/editor/assets/classDiagram-JCYQIIEL-Depm8ksq.js +2 -0
  114. openstategraph/api/static/editor/assets/classDiagram-v2-OCEON4UE-Depm8ksq.js +2 -0
  115. openstategraph/api/static/editor/assets/cose-bilkent-JH36ORCC-D5TK9rNS.js +2 -0
  116. openstategraph/api/static/editor/assets/cynefin-VYW2F7L2-D4Q9WVaa.js +1 -0
  117. openstategraph/api/static/editor/assets/cynefinDiagram-MW4NZA55-CoHRISXQ.js +63 -0
  118. openstategraph/api/static/editor/assets/cytoscape.esm-C3UvhD5t.js +322 -0
  119. openstategraph/api/static/editor/assets/dagre-Buvkdvvj.js +2 -0
  120. openstategraph/api/static/editor/assets/dagre-VZM6K2ZE-D21mJWEs.js +5 -0
  121. openstategraph/api/static/editor/assets/defaultLocale-BFoDCU3G.js +2 -0
  122. openstategraph/api/static/editor/assets/diagram-7IWD3JNH-DH8djcKe.js +31 -0
  123. openstategraph/api/static/editor/assets/diagram-B4RE2ZJO-TCo5p7fm.js +4 -0
  124. openstategraph/api/static/editor/assets/diagram-LBJQPF4R-CgbTOT1t.js +25 -0
  125. openstategraph/api/static/editor/assets/diagram-Q27KOJAE-C66hKgaF.js +25 -0
  126. openstategraph/api/static/editor/assets/diagram-UB23O5K3-DfQdI_zj.js +42 -0
  127. openstategraph/api/static/editor/assets/dist-Cf7dFMHT.js +2 -0
  128. openstategraph/api/static/editor/assets/ebnfDiagram-BXEA7PRR-zmsTHIxX.js +2 -0
  129. openstategraph/api/static/editor/assets/erDiagram-JOGREHBK-CghTrytX.js +86 -0
  130. openstategraph/api/static/editor/assets/eventmodeling-45OFAUF4-CMwSn-Ho.js +1 -0
  131. openstategraph/api/static/editor/assets/flowDiagram-UKHOOZJN-C-_w-s1Q.js +1 -0
  132. openstategraph/api/static/editor/assets/ganttDiagram-PKOTCBZU-97e9PAPc.js +293 -0
  133. openstategraph/api/static/editor/assets/gitGraph-TEB2WS4Q-DRKzZwY3.js +1 -0
  134. openstategraph/api/static/editor/assets/gitGraphDiagram-DS77QQ5N-CW0XXeRI.js +107 -0
  135. openstategraph/api/static/editor/assets/graphlib-DS17s2tU.js +2 -0
  136. openstategraph/api/static/editor/assets/ibm-plex-mono-latin-400-normal-DMJ8VG8y.woff2 +0 -0
  137. openstategraph/api/static/editor/assets/ibm-plex-mono-latin-ext-400-normal-BmRBH3aV.woff2 +0 -0
  138. openstategraph/api/static/editor/assets/ibm-plex-sans-latin-ext-wght-normal-CIII54If.woff2 +0 -0
  139. openstategraph/api/static/editor/assets/ibm-plex-sans-latin-wght-normal-IvpUvPa2.woff2 +0 -0
  140. openstategraph/api/static/editor/assets/index-C82F-VOn.js +97 -0
  141. openstategraph/api/static/editor/assets/index-aFbfZIkT.css +1 -0
  142. openstategraph/api/static/editor/assets/info-DKCQHKI2-SysKRxO_.js +1 -0
  143. openstategraph/api/static/editor/assets/infoDiagram-6WML65LV-DZbcdVbQ.js +3 -0
  144. openstategraph/api/static/editor/assets/init-C-OQMol4.js +2 -0
  145. openstategraph/api/static/editor/assets/ishikawaDiagram-WSZJBQD7-db9uBmh5.js +71 -0
  146. openstategraph/api/static/editor/assets/journeyDiagram-NVQOT4AX-BRA0mH1X.js +140 -0
  147. openstategraph/api/static/editor/assets/kanban-definition-27J2QSJJ-BC9rn5e4.js +90 -0
  148. openstategraph/api/static/editor/assets/katex-DolUETbr.js +258 -0
  149. openstategraph/api/static/editor/assets/line-B7qqN3Ir.js +2 -0
  150. openstategraph/api/static/editor/assets/linear-5J5m_kC5.js +2 -0
  151. openstategraph/api/static/editor/assets/map-BaFkSB1l.js +2 -0
  152. openstategraph/api/static/editor/assets/mermaid-parser.core-BGnhWAUE.js +8 -0
  153. openstategraph/api/static/editor/assets/mermaid.core-16iQohrd.js +43 -0
  154. openstategraph/api/static/editor/assets/mindmap-definition-FAOFIHXS-D5CjGmqV.js +97 -0
  155. openstategraph/api/static/editor/assets/node.browser-NgqoTrLm.js +2 -0
  156. openstategraph/api/static/editor/assets/openai-CkyQtVOo.js +19 -0
  157. openstategraph/api/static/editor/assets/ordinal-BDEzSJ7C.js +2 -0
  158. openstategraph/api/static/editor/assets/packet-7NZHBO7P-sQm5Oec1.js +1 -0
  159. openstategraph/api/static/editor/assets/path-COt_16Va.js +2 -0
  160. openstategraph/api/static/editor/assets/pegDiagram-VL7TDLO6-uYvU6KEE.js +2 -0
  161. openstategraph/api/static/editor/assets/pie-RZYD4A2V-BTbfwsIW.js +1 -0
  162. openstategraph/api/static/editor/assets/pieDiagram-7S7Q4E2Y-D_PiFPb_.js +40 -0
  163. openstategraph/api/static/editor/assets/quadrantDiagram-CIZ2JOQS-C8DSaWmz.js +8 -0
  164. openstategraph/api/static/editor/assets/radar-I7S5WNFK-CkFE88Ku.js +1 -0
  165. openstategraph/api/static/editor/assets/railroad-3IZDKUUU-Dts1ojtZ.js +1 -0
  166. openstategraph/api/static/editor/assets/railroad-abnf-AHOZXSZD-D-c7lnP-.js +1 -0
  167. openstategraph/api/static/editor/assets/railroad-ebnf-EBAXGLYW-C6_n505H.js +1 -0
  168. openstategraph/api/static/editor/assets/railroad-peg-LSFZ7HO6-CG9QfFVy.js +1 -0
  169. openstategraph/api/static/editor/assets/railroadDiagram-AXF67PYL-nuUZ0qwl.js +2 -0
  170. openstategraph/api/static/editor/assets/requirementDiagram-LRYGKXZP-DxBF5NhC.js +85 -0
  171. openstategraph/api/static/editor/assets/rough.esm-By172zw-.js +2 -0
  172. openstategraph/api/static/editor/assets/sankeyDiagram-W5VNT64P-CntNPYqA.js +41 -0
  173. openstategraph/api/static/editor/assets/sdk-Cp3Re1Le.js +38 -0
  174. openstategraph/api/static/editor/assets/sequenceDiagram-SI44F4Z6-HZo4SLa8.js +163 -0
  175. openstategraph/api/static/editor/assets/sizeCapture-X5ZJPWSS-B0uUizjq.js +2 -0
  176. openstategraph/api/static/editor/assets/src-DqrQFfgz.js +2 -0
  177. openstategraph/api/static/editor/assets/stateDiagram-OKZ733FA-CLS4pIgN.js +2 -0
  178. openstategraph/api/static/editor/assets/stateDiagram-v2-UEYNNEHI-COwAZwMg.js +2 -0
  179. openstategraph/api/static/editor/assets/swimlanes-SLNWSIFB-D29zxlMr.js +3 -0
  180. openstategraph/api/static/editor/assets/swimlanesDiagram-ULZ7WXOC-BDcjn2xv.js +9 -0
  181. openstategraph/api/static/editor/assets/timeline-definition-Z64GVDOM-CelnRNqa.js +121 -0
  182. openstategraph/api/static/editor/assets/treeView-QDETBFTQ-DFJeT3QC.js +1 -0
  183. openstategraph/api/static/editor/assets/treemap-6X3UGDF4-BEjfDtSh.js +1 -0
  184. openstategraph/api/static/editor/assets/vennDiagram-T6HMQDX7-CDZD7jBy.js +35 -0
  185. openstategraph/api/static/editor/assets/wardley-OPB4EBWU-CnK4FjgH.js +1 -0
  186. openstategraph/api/static/editor/assets/wardleyDiagram-T6FBY63Y-CAtiCqwR.js +79 -0
  187. openstategraph/api/static/editor/assets/xychartDiagram-ELKLHX3M-sU7T-aSM.js +8 -0
  188. openstategraph/api/static/editor/favicon.svg +41 -0
  189. openstategraph/api/static/editor/index.html +71 -0
  190. openstategraph/api/static/editor_missing.html +104 -0
  191. openstategraph/api/static/site/behind-the-scenes.html +1155 -0
  192. openstategraph/api/static/site/gallery.html +1969 -0
  193. openstategraph/api/static/site/index.html +1497 -0
  194. openstategraph/api/static/vendor/mermaid.min.js +3587 -0
  195. openstategraph/api/streaming.py +2909 -0
  196. openstategraph/api/team_board.py +133 -0
  197. openstategraph/api/threads.py +892 -0
  198. openstategraph/api/workflow_events.py +305 -0
  199. openstategraph/api/workflow_store.py +779 -0
  200. openstategraph/async_tasks.py +624 -0
  201. openstategraph/bundled_skills.py +152 -0
  202. openstategraph/catalogue.py +273 -0
  203. openstategraph/chat_model.py +414 -0
  204. openstategraph/cli.py +3461 -0
  205. openstategraph/compile/__init__.py +0 -0
  206. openstategraph/compile/checked_nodes.py +117 -0
  207. openstategraph/compile/composition.py +196 -0
  208. openstategraph/compile/context.py +476 -0
  209. openstategraph/compile/deep_tier.py +81 -0
  210. openstategraph/compile/diagnostics.py +772 -0
  211. openstategraph/compile/fields.py +121 -0
  212. openstategraph/compile/graph_names.py +80 -0
  213. openstategraph/compile/grounding.py +116 -0
  214. openstategraph/compile/mount_overrides.py +207 -0
  215. openstategraph/compile/mount_persistence.py +119 -0
  216. openstategraph/compile/node_catalogue.py +368 -0
  217. openstategraph/compile/node_doors.py +231 -0
  218. openstategraph/compile/node_families.py +125 -0
  219. openstategraph/compile/node_runtime.py +1516 -0
  220. openstategraph/compile/node_types.py +132 -0
  221. openstategraph/compile/nodes/__init__.py +94 -0
  222. openstategraph/compile/nodes/agent.py +785 -0
  223. openstategraph/compile/nodes/approval.py +91 -0
  224. openstategraph/compile/nodes/functions.py +166 -0
  225. openstategraph/compile/nodes/grader.py +467 -0
  226. openstategraph/compile/nodes/guard.py +440 -0
  227. openstategraph/compile/nodes/io.py +438 -0
  228. openstategraph/compile/nodes/memory.py +108 -0
  229. openstategraph/compile/nodes/mount.py +795 -0
  230. openstategraph/compile/nodes/named_check.py +66 -0
  231. openstategraph/compile/nodes/orchestration.py +493 -0
  232. openstategraph/compile/nodes/resolvers.py +200 -0
  233. openstategraph/compile/nodes/route_check.py +162 -0
  234. openstategraph/compile/nodes/router.py +225 -0
  235. openstategraph/compile/paused_mount.py +100 -0
  236. openstategraph/compile/port_specs.json +3871 -0
  237. openstategraph/compile/reducers.py +165 -0
  238. openstategraph/compile/reporting.py +458 -0
  239. openstategraph/compile/run_context.py +899 -0
  240. openstategraph/compile/runtime_services.py +187 -0
  241. openstategraph/compile/side_effects.py +143 -0
  242. openstategraph/compile/silent_turn.py +97 -0
  243. openstategraph/compile/state.py +839 -0
  244. openstategraph/compile/static_source.py +180 -0
  245. openstategraph/compile/subagents.py +272 -0
  246. openstategraph/compile/token_stream.py +138 -0
  247. openstategraph/compile/upstream.py +38 -0
  248. openstategraph/compile/workflow_compiler.py +2907 -0
  249. openstategraph/concurrent_producers.py +265 -0
  250. openstategraph/config_edit.py +340 -0
  251. openstategraph/config_file.py +939 -0
  252. openstategraph/counted_rows.py +475 -0
  253. openstategraph/delegations.py +158 -0
  254. openstategraph/deployment.py +248 -0
  255. openstategraph/developer_channel.py +351 -0
  256. openstategraph/document_checks.py +926 -0
  257. openstategraph/dotenv.py +270 -0
  258. openstategraph/editor_freshness.py +89 -0
  259. openstategraph/engineering_rules.md +165 -0
  260. openstategraph/engineering_rules.py +30 -0
  261. openstategraph/errors.py +457 -0
  262. openstategraph/evaluation/__init__.py +83 -0
  263. openstategraph/evaluation/dataset.py +225 -0
  264. openstategraph/evaluation/denotation.py +345 -0
  265. openstategraph/evaluation/recovery.py +78 -0
  266. openstategraph/evaluation/runner.py +578 -0
  267. openstategraph/evaluation/scoring.py +337 -0
  268. openstategraph/examples/__init__.py +302 -0
  269. openstategraph/examples/agentic-rag-rewrite/AGENTS.md +88 -0
  270. openstategraph/examples/agentic-rag-rewrite/knowledge/escalation-paths.md +30 -0
  271. openstategraph/examples/agentic-rag-rewrite/knowledge/incident-response.md +32 -0
  272. openstategraph/examples/agentic-rag-rewrite/knowledge/oncall-rotation.md +30 -0
  273. openstategraph/examples/agentic-rag-rewrite/knowledge/release-train.md +30 -0
  274. openstategraph/examples/agentic-rag-rewrite/knowledge/support-tiers.md +25 -0
  275. openstategraph/examples/agentic-rag-rewrite/tests/test_agentic_rag_rewrite_document.py +135 -0
  276. openstategraph/examples/agentic-rag-rewrite/workflow.json +91 -0
  277. openstategraph/examples/approval-in-the-loop/AGENTS.md +122 -0
  278. openstategraph/examples/approval-in-the-loop/tests/test_approval_in_the_loop_document.py +84 -0
  279. openstategraph/examples/approval-in-the-loop/workflow.json +65 -0
  280. openstategraph/examples/archetype-orchestrator-report/AGENTS.md +128 -0
  281. openstategraph/examples/archetype-orchestrator-report/tests/test_archetype_orchestrator_report_document.py +133 -0
  282. openstategraph/examples/archetype-orchestrator-report/workflow.json +147 -0
  283. openstategraph/examples/budget-exhaustion/AGENTS.md +97 -0
  284. openstategraph/examples/budget-exhaustion/tests/test_budget_exhaustion_document.py +73 -0
  285. openstategraph/examples/budget-exhaustion/workflow.json +67 -0
  286. openstategraph/examples/chained-summarizer/AGENTS.md +80 -0
  287. openstategraph/examples/chained-summarizer/tests/test_chained_summarizer_document.py +68 -0
  288. openstategraph/examples/chained-summarizer/workflow.json +61 -0
  289. openstategraph/examples/classifier-router-qa/AGENTS.md +60 -0
  290. openstategraph/examples/classifier-router-qa/tests/test_classifier_router_qa_document.py +75 -0
  291. openstategraph/examples/classifier-router-qa/workflow.json +115 -0
  292. openstategraph/examples/delegate-by-mount/AGENTS.md +87 -0
  293. openstategraph/examples/delegate-by-mount/tests/test_delegate_by_mount_document.py +122 -0
  294. openstategraph/examples/delegate-by-mount/workflow.json +145 -0
  295. openstategraph/examples/evaluator-optimizer/AGENTS.md +70 -0
  296. openstategraph/examples/evaluator-optimizer/tests/test_evaluator_optimizer_document.py +65 -0
  297. openstategraph/examples/evaluator-optimizer/workflow.json +67 -0
  298. openstategraph/examples/fanout-in-a-loop/AGENTS.md +113 -0
  299. openstategraph/examples/fanout-in-a-loop/tests/test_fanout_in_a_loop_document.py +93 -0
  300. openstategraph/examples/fanout-in-a-loop/workflow.json +93 -0
  301. openstategraph/examples/guarded-lookup/AGENTS.md +122 -0
  302. openstategraph/examples/guarded-lookup/tests/test_guarded_lookup_document.py +96 -0
  303. openstategraph/examples/guarded-lookup/tools/directory.py +102 -0
  304. openstategraph/examples/guarded-lookup/workflow.json +114 -0
  305. openstategraph/examples/index.json +194 -0
  306. openstategraph/examples/knowledge-lookup-qa/AGENTS.md +96 -0
  307. openstategraph/examples/knowledge-lookup-qa/knowledge/accessions.md +29 -0
  308. openstategraph/examples/knowledge-lookup-qa/knowledge/duplication.md +30 -0
  309. openstategraph/examples/knowledge-lookup-qa/knowledge/storage-tiers.md +30 -0
  310. openstategraph/examples/knowledge-lookup-qa/knowledge/viability-testing.md +36 -0
  311. openstategraph/examples/knowledge-lookup-qa/knowledge/withdrawals.md +29 -0
  312. openstategraph/examples/knowledge-lookup-qa/tests/test_knowledge_lookup_qa_document.py +119 -0
  313. openstategraph/examples/knowledge-lookup-qa/workflow.json +59 -0
  314. openstategraph/examples/morning-brief/AGENTS.md +138 -0
  315. openstategraph/examples/morning-brief/knowledge/gallery.md +29 -0
  316. openstategraph/examples/morning-brief/knowledge/on-call.md +35 -0
  317. openstategraph/examples/morning-brief/knowledge/release-checklist.md +31 -0
  318. openstategraph/examples/morning-brief/knowledge/support-desks.md +30 -0
  319. openstategraph/examples/morning-brief/tests/test_morning_brief_document.py +197 -0
  320. openstategraph/examples/morning-brief/workflow.json +164 -0
  321. openstategraph/examples/nested-mounts/AGENTS.md +120 -0
  322. openstategraph/examples/nested-mounts/tests/test_nested_mounts_document.py +129 -0
  323. openstategraph/examples/nested-mounts/workflow.json +48 -0
  324. openstategraph/examples/nested-mounts-mid/AGENTS.md +35 -0
  325. openstategraph/examples/nested-mounts-mid/workflow.json +48 -0
  326. openstategraph/examples/parallel-workers-join/AGENTS.md +95 -0
  327. openstategraph/examples/parallel-workers-join/tests/test_parallel_workers_join_document.py +81 -0
  328. openstategraph/examples/parallel-workers-join/workflow.json +74 -0
  329. openstategraph/examples/remembers-across-runs/AGENTS.md +111 -0
  330. openstategraph/examples/remembers-across-runs/tests/test_remembers_across_runs_document.py +101 -0
  331. openstategraph/examples/remembers-across-runs/workflow.json +92 -0
  332. openstategraph/examples/same-package-twice/AGENTS.md +87 -0
  333. openstategraph/examples/same-package-twice/tests/test_same_package_twice_document.py +148 -0
  334. openstategraph/examples/same-package-twice/workflow.json +71 -0
  335. openstategraph/examples/skill-driven-rubric/AGENTS.md +98 -0
  336. openstategraph/examples/skill-driven-rubric/tests/test_skill_driven_rubric_document.py +117 -0
  337. openstategraph/examples/skill-driven-rubric/workflow.json +87 -0
  338. openstategraph/examples/sql-qa/AGENTS.md +130 -0
  339. openstategraph/examples/sql-qa/data/Chinook_Sqlite.sqlite +0 -0
  340. openstategraph/examples/sql-qa/evals/sql-qa.eval.json +119 -0
  341. openstategraph/examples/sql-qa/tests/test_sql_qa_document.py +237 -0
  342. openstategraph/examples/sql-qa/workflow.json +88 -0
  343. openstategraph/examples/support-triage/AGENTS.md +204 -0
  344. openstategraph/examples/support-triage/tests/test_support_triage_document.py +171 -0
  345. openstategraph/examples/support-triage/workflow.json +157 -0
  346. openstategraph/examples/two-stage-double-loop/AGENTS.md +88 -0
  347. openstategraph/examples/two-stage-double-loop/tests/test_two_stage_double_loop_document.py +88 -0
  348. openstategraph/examples/two-stage-double-loop/workflow.json +99 -0
  349. openstategraph/examples/web-research-digest/AGENTS.md +139 -0
  350. openstategraph/examples/web-research-digest/tests/test_web_research_digest_document.py +131 -0
  351. openstategraph/examples/web-research-digest/workflow.json +89 -0
  352. openstategraph/examples/youtube-trend-digest/AGENTS.md +257 -0
  353. openstategraph/examples/youtube-trend-digest/tests/test_youtube_trend_digest_document.py +150 -0
  354. openstategraph/examples/youtube-trend-digest/workflow.json +118 -0
  355. openstategraph/executed_statements.py +157 -0
  356. openstategraph/extensions.py +554 -0
  357. openstategraph/function_contracts.py +149 -0
  358. openstategraph/gap_report.py +741 -0
  359. openstategraph/gap_report_client.py +201 -0
  360. openstategraph/gap_report_door.py +408 -0
  361. openstategraph/generated_module_contract.py +453 -0
  362. openstategraph/github_issue_bridge.py +375 -0
  363. openstategraph/grounded_numbers.py +226 -0
  364. openstategraph/injection.py +177 -0
  365. openstategraph/install_hint.py +225 -0
  366. openstategraph/kanban_migrations/0001_kanban_cards.sql +140 -0
  367. openstategraph/kanban_migrations/0002_kanban_cards_rls.sql +95 -0
  368. openstategraph/kanban_migrations/0003_gap_report_door.sql +195 -0
  369. openstategraph/kanban_migrations/0004_ledger_rls.sql +69 -0
  370. openstategraph/kanban_migrations/0005_card_gap_evidence.sql +33 -0
  371. openstategraph/kanban_migrations/0006_gap_cards_land_on_the_team_board.sql +128 -0
  372. openstategraph/kanban_postgres.py +446 -0
  373. openstategraph/kanban_sqlite.py +396 -0
  374. openstategraph/kanban_store.py +893 -0
  375. openstategraph/knowledge.py +199 -0
  376. openstategraph/knowledge_builders.py +736 -0
  377. openstategraph/knowledge_engines.py +354 -0
  378. openstategraph/knowledge_explorer.py +777 -0
  379. openstategraph/live.py +504 -0
  380. openstategraph/loader.py +1042 -0
  381. openstategraph/mcp_server.py +1879 -0
  382. openstategraph/mcp_sessions.py +416 -0
  383. openstategraph/memory.py +1240 -0
  384. openstategraph/memory_segment.py +348 -0
  385. openstategraph/messages.py +237 -0
  386. openstategraph/model_readiness.py +120 -0
  387. openstategraph/mssql_connection.py +276 -0
  388. openstategraph/node_report.py +209 -0
  389. openstategraph/opening.py +221 -0
  390. openstategraph/package_testing.py +180 -0
  391. openstategraph/patrol.py +557 -0
  392. openstategraph/plugin_interop.py +714 -0
  393. openstategraph/postgres.py +212 -0
  394. openstategraph/prebuilt_architect.py +179 -0
  395. openstategraph/prebuilt_databricks.py +184 -0
  396. openstategraph/prebuilt_email.py +143 -0
  397. openstategraph/prebuilt_knowledge.py +165 -0
  398. openstategraph/prebuilt_mcp.py +1720 -0
  399. openstategraph/prebuilt_mssql.py +206 -0
  400. openstategraph/prebuilt_platform.py +340 -0
  401. openstategraph/prebuilt_session.py +81 -0
  402. openstategraph/prebuilt_sql.py +246 -0
  403. openstategraph/prebuilt_warehouse.py +504 -0
  404. openstategraph/prebuilt_web.py +289 -0
  405. openstategraph/prebuilt_youtube.py +403 -0
  406. openstategraph/principal.py +193 -0
  407. openstategraph/progress.py +203 -0
  408. openstategraph/project_id_carriers.py +238 -0
  409. openstategraph/project_identity.py +188 -0
  410. openstategraph/providers.py +1323 -0
  411. openstategraph/py.typed +0 -0
  412. openstategraph/readable_tree.py +58 -0
  413. openstategraph/readonly_sqlite.py +148 -0
  414. openstategraph/reasoning.py +379 -0
  415. openstategraph/results.py +350 -0
  416. openstategraph/run_doors.py +305 -0
  417. openstategraph/run_findings.py +695 -0
  418. openstategraph/run_identity.py +81 -0
  419. openstategraph/run_journal.py +450 -0
  420. openstategraph/run_sinks.py +2046 -0
  421. openstategraph/run_stream.py +579 -0
  422. openstategraph/run_summary.py +291 -0
  423. openstategraph/scaffold.py +969 -0
  424. openstategraph/schema.py +269 -0
  425. openstategraph/search_backends.py +332 -0
  426. openstategraph/skills.py +218 -0
  427. openstategraph/sources.py +442 -0
  428. openstategraph/sql_reach.py +119 -0
  429. openstategraph/state_dir.py +173 -0
  430. openstategraph/step_budget.py +335 -0
  431. openstategraph/stream_parts.py +71 -0
  432. openstategraph/table_coverage.py +632 -0
  433. openstategraph/templates/__init__.py +162 -0
  434. openstategraph/templates/index.json +44 -0
  435. openstategraph/templates/loop/AGENTS.md +77 -0
  436. openstategraph/templates/loop/tests/test_shape.py +31 -0
  437. openstategraph/templates/loop/workflow.json +47 -0
  438. openstategraph/templates/minimal/AGENTS.md +51 -0
  439. openstategraph/templates/minimal/tests/test_shape.py +30 -0
  440. openstategraph/templates/minimal/workflow.json +20 -0
  441. openstategraph/templates/routed-qa/AGENTS.md +71 -0
  442. openstategraph/templates/routed-qa/tests/test_shape.py +37 -0
  443. openstategraph/templates/routed-qa/workflow.json +85 -0
  444. openstategraph/templates/team/AGENTS.md +50 -0
  445. openstategraph/templates/team/tests/test_shape.py +33 -0
  446. openstategraph/templates/team/workflow.json +64 -0
  447. openstategraph/units.py +201 -0
  448. openstategraph/validation.py +418 -0
  449. openstategraph/vocabulary.py +573 -0
  450. openstategraph/web_transport.py +131 -0
  451. openstategraph/workflows_root.py +200 -0
  452. openstategraph-0.3.0.dist-info/METADATA +162 -0
  453. openstategraph-0.3.0.dist-info/RECORD +456 -0
  454. openstategraph-0.3.0.dist-info/WHEEL +4 -0
  455. openstategraph-0.3.0.dist-info/entry_points.txt +2 -0
  456. openstategraph-0.3.0.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,632 @@
1
+ """What one row is, and which period a table covers — read from a declaration.
2
+
3
+ `launch-readiness/166`, the half `165` could not build.
4
+
5
+ `165` shipped everything the platform can know **without a declaration**: a
6
+ bare `COUNT(*)` counts rows, so publishing that figure under a plural entity
7
+ noun is asked to say what it counted. Two things stayed out of reach, and both
8
+ are facts only the table can state:
9
+
10
+ 1. **What one row is.** A declaration saying `grain: daily` is a word about
11
+ the *date* axis and not a key. `main.PlaylistTrack` is the worked case: its
12
+ row is `(PlaylistId, TrackId)`, so a row is one track *in one playlist* and
13
+ never one track.
14
+ 2. **What the table covers.** `workflows/chinook-assistant`'s database ships
15
+ with this repository, so the second fact is one anybody can re-measure:
16
+ `main.Invoice` runs `2009-01-01 -> 2013-12-22`, and `main.PlaylistTrack`
17
+ carries no date column at all.
18
+
19
+ So *"last month"* over `main.Invoice` is guaranteed empty, and every run that
20
+ answers *"0 invoices"* is right by accident and reads **identically** to a run
21
+ that looked and found none. That is this project's most expensive shape, and
22
+ it is the whole of the ticket.
23
+
24
+ ## The declaration is the lens's, and the enforcement is ours
25
+
26
+ The same split `87` and `98` took and both worked. This module does not guess a
27
+ coverage window and never will: a fabricated one is worse than none, because it
28
+ would let the platform state as fact something nobody measured. What it does is
29
+ **read** one when a table publishes it, and **say so when a table does not**.
30
+
31
+ The wire format is deliberately the shape a schema-describing tool already
32
+ returns — a payload that names a table, carrying `row_key` and `coverage`
33
+ beside the columns:
34
+
35
+ ```json
36
+ {"table": "main.Invoice",
37
+ "row_key": ["CustomerId", "InvoiceDate"],
38
+ "coverage": {"column": "InvoiceDate", "min": "2009-01-01", "max": "2013-12-22"}}
39
+ ```
40
+
41
+ `docs/declaring-a-table.md` is the publication of that contract.
42
+
43
+ ## Four states, and no toggle between them
44
+
45
+ `launch-readiness/135`'s resolver established the shape and this reuses it: the
46
+ failure being closed is *two situations rendering identically*, so every state
47
+ gets its own rendering and none of them is silence-by-omission.
48
+
49
+ | The run filtered on dates and the answer reports none, and… | State | What happens |
50
+ | --- | --- | --- |
51
+ | the window lies entirely outside the declared coverage | `outside` | **revise** — nothing could have matched, and the answer must say so |
52
+ | the window runs past one end of the declared coverage | `partial` | a reader disclosure naming the last date the data holds |
53
+ | the window sits inside the declared coverage | `covered` | **silence** — the zero is a measurement, and saying anything here is the `133` failure |
54
+ | the table declares no coverage at all | `undeclared` | a reader disclosure: *"none" cannot be told apart from "not covered"* |
55
+
56
+ The **`covered` row is the one that decides whether anyone keeps this gate.**
57
+ `launch-readiness/133` is the counter-example already paid for: a check that
58
+ fires on correct work teaches people to route around it. A zero over a window
59
+ the table demonstrably holds is a real answer and this module has nothing to
60
+ say about it.
61
+
62
+ ## Why `outside` revises and the other two disclose
63
+
64
+ `outside` is **correctable in one lap and by the model only**: the sentence a
65
+ reader needs — *"none, and none was possible: this data stops on 2013-12-22"* —
66
+ is prose about the question that was asked, and the model is the thing holding
67
+ that question. `165`'s repair has the same shape.
68
+
69
+ `undeclared` and `partial` are **not correctable at all.** No revision lap can
70
+ make a table declare something, so routing them to `revise` would build a guard
71
+ that objects forever and then publishes anyway — which is `launch-readiness/167`
72
+ in person. They travel the reader rail instead
73
+ (`abc/tool_notes.UncoveredWindow`), which renders whether or not the model
74
+ mentions them.
75
+
76
+ ## What this module will not do
77
+
78
+ - **It will not fabricate a window.** An undeclared table is reported as
79
+ undeclared, forever, until somebody measures it and writes it down.
80
+ - **It will not read a coverage window out of returned rows.** A live MCP
81
+ envelope carries a `date_columns` block with `min`/`max` — computed over the
82
+ rows *this statement returned*, not over the table. Reading it as coverage
83
+ would turn *"the sample I fetched spans one day"* into *"this table holds one
84
+ day"*, which is a confident wrong answer where the honest one is "undeclared".
85
+ - **It will not decide which column identifies the entity.** A `row_key` of more
86
+ than one column is enough to know a row is not one of anything; naming which
87
+ member is the entity is a second declaration nobody has made.
88
+ """
89
+
90
+ from __future__ import annotations
91
+
92
+ import re
93
+ from dataclasses import dataclass, field
94
+ from datetime import date
95
+ from typing import Any, Iterable, Mapping
96
+
97
+ from openstategraph.counted_rows import ROW_NOUNS, exchanges_in, payloads_of
98
+
99
+ #: An ISO date, the only spelling this module reads. A declaration is written
100
+ #: by a loader rather than typed by a person, so tolerating `12/05/2026` would
101
+ #: buy an ambiguity (`launch-readiness/125`'s axis problem in miniature: two
102
+ #: readings, one string) for no reader.
103
+ _ISO = re.compile(r"^\d{4}-\d{2}-\d{2}")
104
+
105
+ #: A quoted date literal inside a statement — how a run says which period it
106
+ #: asked about. Anything else (a bound parameter, `DATEADD`, a relative
107
+ #: expression) leaves the window unknown, and unknown is reported as such
108
+ #: rather than assumed to be covered.
109
+ _DATE_LITERAL = re.compile(r"'(\d{4}-\d{2}-\d{2})(?:[T ][\d:.]+)?'")
110
+
111
+ #: Plural words that stand between *"no"* and the thing actually being counted.
112
+ #: *"no recorded **instances** of dark vessels"* is about vessels, and a
113
+ #: disclosure naming `instances` reads as though the machine did not follow the
114
+ #: sentence. Walked **past**, not stopped at — unlike `ROW_NOUNS` below.
115
+ _VAGUE: frozenset[str] = frozenset(
116
+ {
117
+ "results", "matches", "hits", "instances", "occurrences", "values",
118
+ "changes", "issues", "problems", "errors", "details", "others",
119
+ "dates", "days", "months", "years", "times", "cases", "columns",
120
+ "tables", "sightings",
121
+ }
122
+ )
123
+
124
+ #: How far past *"no"* to look for the noun it denies. Six rather than `165`'s
125
+ #: four, because the vague words above sit **between** the two: *"no recorded
126
+ #: instances of dark vessels"* is five words from `no` to `vessels`.
127
+ _ENTITY_WINDOW = 6
128
+
129
+ _WORD = re.compile(r"[A-Za-z][A-Za-z-]*")
130
+
131
+ #: English words ending in `s` that are not nouns. `165` keeps its own copy for
132
+ #: its own window; this one is reached by a different walk and the two lists
133
+ #: answer different questions, so they are not shared.
134
+ _NOT_A_NOUN: frozenset[str] = frozenset(
135
+ {
136
+ "was", "is", "has", "does", "as", "its", "this", "thus", "us", "plus",
137
+ "less", "across", "whereas", "yes", "also", "always", "perhaps",
138
+ "series", "various", "hers", "theirs", "ours", "yours", "gas",
139
+ }
140
+ )
141
+
142
+ #: The words that open a claim of nothing. `none` is here and earns almost
143
+ #: nothing on its own — *"I found none."* attaches no noun, so it is read and
144
+ #: then dropped by the plural-noun rule below. That is a known miss, recorded
145
+ #: rather than patched: widening it to a bare `none` would fire on *"none of
146
+ #: the ports is in Norway"*, which is a claim about a subset and not a zero.
147
+ _NOTHING = re.compile(r"\b(?:no|zero|none|0)\b", re.IGNORECASE)
148
+
149
+ #: How deep to look for a declaration inside a nested payload. A lens's
150
+ #: schema dump nests one or two levels (`data.tables[]`); past this it is not a
151
+ #: declaration, it is somebody's data.
152
+ _MAX_DEPTH = 6
153
+
154
+ #: The cheapest possible way to not parse a result. A tool answer that contains
155
+ #: neither word cannot carry a declaration, and every run pays this scan.
156
+ _MARKERS: tuple[str, ...] = ("row_key", "coverage")
157
+
158
+
159
+ @dataclass(frozen=True)
160
+ class TableDeclaration:
161
+ """What a table says about itself. Everything here is somebody's statement.
162
+
163
+ Nothing on this record is inferred, measured or defaulted by the platform.
164
+ A field that was not declared is empty, and empty is reported as
165
+ *undeclared* rather than filled in — which is the single property that
166
+ stops this module from ever being the source of a confident wrong answer.
167
+ """
168
+
169
+ #: The table this is about, as the statement spells it. Compared casefolded.
170
+ table: str
171
+ #: The columns that together identify one row. Its **length** is what the
172
+ #: platform reads: more than one column and a row is not one of anything.
173
+ row_key: tuple[str, ...] = field(default=())
174
+ #: The date column the window below is measured on.
175
+ coverage_column: str = ""
176
+ #: The first and last date the table holds. `None` is *not declared* — never
177
+ #: "unbounded", which would be a claim.
178
+ coverage_min: date | None = None
179
+ coverage_max: date | None = None
180
+
181
+ def declares_row_key(self) -> bool:
182
+ return bool(self.row_key)
183
+
184
+ def declares_coverage(self) -> bool:
185
+ """Both ends, or nothing.
186
+
187
+ A half-declared window cannot answer *"could this have matched"* in one
188
+ direction, and a check that is right about one edge and silent about the
189
+ other is the shape this ticket exists to remove.
190
+ """
191
+ return self.coverage_min is not None and self.coverage_max is not None
192
+
193
+ def a_row_is_not_one_thing(self) -> bool:
194
+ """Whether the declaration itself says `COUNT(*)` is not a count of entities."""
195
+ return len(self.row_key) > 1
196
+
197
+
198
+ def _iso(value: Any) -> date | None:
199
+ text = str(value or "").strip()
200
+ if not _ISO.match(text):
201
+ return None
202
+ try:
203
+ return date.fromisoformat(text[:10])
204
+ except ValueError:
205
+ return None
206
+
207
+
208
+ def _row_key(value: Any) -> tuple[str, ...]:
209
+ """A declared row key, read tolerantly.
210
+
211
+ A list is the wire format; a comma-separated string is what a YAML author
212
+ writes by hand often enough that refusing it would lose a real declaration
213
+ to punctuation.
214
+ """
215
+ if isinstance(value, str):
216
+ parts = [part.strip() for part in value.split(",")]
217
+ elif isinstance(value, (list, tuple)):
218
+ parts = [str(part).strip() for part in value]
219
+ else:
220
+ return ()
221
+ return tuple(part for part in parts if part)
222
+
223
+
224
+ def declaration_in(payload: Any) -> TableDeclaration | None:
225
+ """One mapping read as a declaration, or `None`.
226
+
227
+ **Tolerant in reading, strict in trusting** — CLAUDE.md's rule, and both
228
+ halves are load-bearing here. Three spellings of the table's name are
229
+ accepted because a schema payload, a lens registry and a hand-written YAML
230
+ each pick a different one. But a payload contributes a declaration only
231
+ when it names a table **and** carries at least one of the two declarations
232
+ in a shape that parses: a mapping with a `coverage` key holding prose, or
233
+ dates that are not dates, declares nothing, and *declares nothing* is a
234
+ state this module renders rather than swallows.
235
+ """
236
+ if not isinstance(payload, Mapping):
237
+ return None
238
+ table = ""
239
+ for key in ("table", "canonical_table", "table_name", "name"):
240
+ candidate = payload.get(key)
241
+ if isinstance(candidate, str) and candidate.strip():
242
+ table = candidate.strip()
243
+ break
244
+ if not table:
245
+ return None
246
+
247
+ row_key = _row_key(payload.get("row_key"))
248
+
249
+ coverage = payload.get("coverage")
250
+ column, low, high = "", None, None
251
+ if isinstance(coverage, Mapping):
252
+ column = str(coverage.get("column") or "").strip()
253
+ low = _iso(coverage.get("min"))
254
+ high = _iso(coverage.get("max"))
255
+ else:
256
+ # The flat spelling, for a producer that cannot nest — a CSV catalogue,
257
+ # a registry row. Same three fields, same meaning, no second contract.
258
+ column = str(payload.get("coverage_column") or "").strip()
259
+ low = _iso(payload.get("coverage_min"))
260
+ high = _iso(payload.get("coverage_max"))
261
+
262
+ if low is not None and high is not None and low > high:
263
+ # A window that ends before it starts is not a narrower claim, it is a
264
+ # broken one. Dropped rather than reversed: reversing would publish a
265
+ # window nobody declared.
266
+ low, high = None, None
267
+
268
+ if not row_key and (low is None or high is None):
269
+ return None
270
+ return TableDeclaration(
271
+ table=table,
272
+ row_key=row_key,
273
+ coverage_column=column,
274
+ coverage_min=low,
275
+ coverage_max=high,
276
+ )
277
+
278
+
279
+ def declarations_in_result(result: Any) -> list[TableDeclaration]:
280
+ """Every declaration carried anywhere in one tool answer.
281
+
282
+ The three envelope layers `165` measured are undone by `payloads_of`; from
283
+ there this walks the structure, because a lens's bulk schema dump puts one
284
+ entry per table under a list and a single-table describe puts it at the
285
+ top. Bounded in depth, and prefiltered on the two marker words so a run
286
+ whose tools declare nothing pays a substring scan and not a parse.
287
+ """
288
+ text = str(result or "")
289
+ if not any(marker in text for marker in _MARKERS):
290
+ return []
291
+ found: list[TableDeclaration] = []
292
+ seen: set[str] = set()
293
+
294
+ def walk(node: Any, depth: int) -> None:
295
+ if depth > _MAX_DEPTH:
296
+ return
297
+ if isinstance(node, Mapping):
298
+ declaration = declaration_in(node)
299
+ if declaration is not None and declaration.table.casefold() not in seen:
300
+ seen.add(declaration.table.casefold())
301
+ found.append(declaration)
302
+ for value in node.values():
303
+ walk(value, depth + 1)
304
+ elif isinstance(node, (list, tuple)):
305
+ for value in node:
306
+ walk(value, depth + 1)
307
+
308
+ for payload in payloads_of(text):
309
+ walk(payload, 0)
310
+ return found
311
+
312
+
313
+ def declarations_in(state: Mapping[str, Any]) -> dict[str, TableDeclaration]:
314
+ """Every table declaration this run was given, keyed by casefolded table name.
315
+
316
+ Two rails, the same pair `counted_rows.exchanges_in` reads and for the same
317
+ reason: `_agent` returns no messages, so what an agent's loop was told sits
318
+ on `tool_use[node]["declares"]` (written by `tool_report`) and nowhere else.
319
+ """
320
+ found: dict[str, TableDeclaration] = {}
321
+
322
+ def add(declaration: TableDeclaration | None) -> None:
323
+ if declaration is None:
324
+ return
325
+ found.setdefault(declaration.table.casefold(), declaration)
326
+
327
+ for row in (state.get("tool_use") or {}).values():
328
+ for payload in (row or {}).get("declares") or []:
329
+ add(declaration_in(payload))
330
+
331
+ for message in state.get("messages") or []:
332
+ if getattr(message, "type", "") != "tool":
333
+ continue
334
+ if getattr(message, "status", None) == "error":
335
+ continue
336
+ for declaration in declarations_in_result(getattr(message, "content", "")):
337
+ add(declaration)
338
+ return found
339
+
340
+
341
+ def window_of(sql: str) -> tuple[date | None, date | None]:
342
+ """The period one statement asked about, or `(None, None)`.
343
+
344
+ Read from the quoted date literals in the statement, lowest and highest —
345
+ not from which column they were compared against, and not from the operator.
346
+ Parsing `>=` against `<` correctly would need a SQL parser, and the two
347
+ facts this module needs (*does the window start after the data stops*,
348
+ *does it end before the data starts*) are answerable from the extremes
349
+ alone.
350
+
351
+ A statement with no date literal has an **unknown** window, not an
352
+ unfiltered one — a bound parameter and a relative expression both land
353
+ here — and unknown is reported as such by every caller.
354
+ """
355
+ dates: set[date] = set()
356
+ for match in _DATE_LITERAL.finditer(str(sql or "")):
357
+ parsed = _iso(match.group(1))
358
+ if parsed is not None:
359
+ dates.add(parsed)
360
+ if not dates:
361
+ return (None, None)
362
+ found = sorted(dates)
363
+ return (found[0], found[-1])
364
+
365
+
366
+ #: The four states, named once so a test, a caller and a document enumerate the
367
+ #: same set. `unknown` is the fifth thing that can happen and is deliberately
368
+ #: not one of them: it means this module was never in a position to ask.
369
+ COVERAGE_STATES: tuple[str, ...] = ("covered", "partial", "outside", "undeclared")
370
+
371
+ #: How much doubt each state carries, for a statement that names several
372
+ #: tables. `undeclared` outranks `covered` deliberately: one table covering the
373
+ #: window says nothing about the one beside it that has never said what it
374
+ #: holds, and a zero out of a join is only as conclusive as its weakest side.
375
+ _SEVERITY: dict[str, int] = {"covered": 0, "undeclared": 1, "partial": 2, "outside": 3}
376
+
377
+
378
+ def assess(
379
+ window: tuple[date | None, date | None], declaration: TableDeclaration | None
380
+ ) -> str:
381
+ """Which of the four states this statement's window is in, or `""`.
382
+
383
+ `""` — *unknown* — whenever there is no window to judge. A statement with
384
+ no date literal is not evidence of anything either way, and reporting it as
385
+ `undeclared` would put a disclosure on every run that never asked about a
386
+ period at all.
387
+ """
388
+ start, end = window
389
+ if start is None or end is None:
390
+ return ""
391
+ if declaration is None or not declaration.declares_coverage():
392
+ return "undeclared"
393
+ low = declaration.coverage_min
394
+ high = declaration.coverage_max
395
+ assert low is not None and high is not None # declares_coverage
396
+ if start > high or end < low:
397
+ return "outside"
398
+ if start < low or end > high:
399
+ return "partial"
400
+ return "covered"
401
+
402
+
403
+ def _is_a_code(prose: str, start: int, end: int) -> bool:
404
+ """Whether this `no` is a bracketed token rather than the English word.
405
+
406
+ **Found live, on the first real run** (2026-08-29, the owner's own
407
+ question): the answer listed *"Biodiesel: 32,759 barrels to Floro [NO]"*,
408
+ and `[NO]` is Norway. Three country codes matched, and the disclosure named
409
+ *"no barrels and instances"* — a sentence about nothing, attached to a
410
+ breakdown that was correct. `133` exactly, and it took one live run to
411
+ find and no fixture to have missed.
412
+
413
+ A token wrapped in brackets or parentheses is a code, never prose.
414
+ """
415
+ before = prose[:start].rstrip()
416
+ after = prose[end:].lstrip()
417
+ return bool(before[-1:] in "[(" and after[:1] in ")]")
418
+
419
+
420
+ def entity_after(prose: str, end: int) -> str:
421
+ """The plural entity noun a *"no"* denies, or `""`.
422
+
423
+ `165`'s `label_after` answers a neighbouring question — *what noun is this
424
+ number presented as counting* — and stops at the first plural word. This
425
+ one **walks past** the vague count-words that sit between a denial and its
426
+ subject, which is the difference between disclosing about `instances` and
427
+ disclosing about `vessels`.
428
+
429
+ A row-noun still wins outright and silences the whole claim, for `165`'s
430
+ reason: *"the query returned no rows"* is a sentence about the record, and
431
+ a disclosure about what the data covers is not what a reader of it needs.
432
+ """
433
+ words: list[str] = []
434
+ for match in _WORD.finditer(prose, end):
435
+ words.append(match.group())
436
+ if len(words) >= _ENTITY_WINDOW:
437
+ break
438
+ if prose[match.end() : match.end() + 1] in ".;:!?":
439
+ break
440
+ for word in (candidate.lower() for candidate in words):
441
+ if word in ROW_NOUNS:
442
+ return ""
443
+ if word in _VAGUE or word in _NOT_A_NOUN:
444
+ continue
445
+ if len(word) >= 4 and word.endswith("s"):
446
+ return word
447
+ return ""
448
+
449
+
450
+ def nothing_claims_in(prose: str) -> list[str]:
451
+ """The plural entity nouns this answer reports **none** of."""
452
+ found: list[str] = []
453
+ for match in _NOTHING.finditer(prose or ""):
454
+ if _is_a_code(prose or "", match.start(), match.end()):
455
+ continue
456
+ label = entity_after(prose or "", match.end())
457
+ if not label or label in found:
458
+ continue
459
+ found.append(label)
460
+ return found
461
+
462
+
463
+ #: Month names, for the spellings a model actually writes. `165`'s lesson about
464
+ #: parsers applies here in reverse: the prompt asked for *"the last date the
465
+ #: data holds"* and the model answered *"May 12, 2026"*, which no ISO matcher
466
+ #: would have recognised. Suspect the parser.
467
+ _MONTHS: tuple[str, ...] = (
468
+ "january", "february", "march", "april", "may", "june",
469
+ "july", "august", "september", "october", "november", "december",
470
+ )
471
+
472
+
473
+ def states_the_date(prose: str, day: date) -> bool:
474
+ """Whether this answer names that exact date, in any ordinary spelling.
475
+
476
+ **The check's own exit, and it is deterministic.** `165`'s repair changes
477
+ the SQL or the noun, so its check simply goes quiet; this one asks for
478
+ *prose*, and a gate that cannot see its own repair objects forever — which
479
+ is `launch-readiness/167` built on purpose rather than met by accident.
480
+ Observed live on 2026-08-29: the model complied fully — *"The data for the
481
+ dark fleet only goes up to May 12, 2026"* — and the guard rejected it twice
482
+ more and exhausted.
483
+
484
+ This is not *"did the model comply"* read as sentiment, which is what
485
+ `Grader.normalise` warns against. It is one literal the check itself
486
+ supplied, matched exactly: the last date the declaration states. An answer
487
+ naming it has said the one thing that distinguishes *"none"* from *"this
488
+ data does not reach that period"*, which is the whole of what was asked.
489
+
490
+ Ambiguous numeric spellings (`12/05/2026`) are deliberately not read: two
491
+ readings of one string is the defect this map is named for.
492
+ """
493
+ text = str(prose or "").lower()
494
+ if day.isoformat() in text:
495
+ return True
496
+ month = _MONTHS[day.month - 1]
497
+ year = day.year
498
+ return any(
499
+ pattern in text
500
+ for pattern in (
501
+ f"{month} {day.day}, {year}",
502
+ f"{month} {day.day} {year}",
503
+ f"{day.day} {month} {year}",
504
+ f"{day.day} {month}, {year}",
505
+ )
506
+ )
507
+
508
+
509
+ def coverage_findings(
510
+ candidate: str, state: Mapping[str, Any]
511
+ ) -> tuple[list[tuple[str, str, TableDeclaration | None, tuple[date | None, date | None]]], list[str]]:
512
+ """`(findings, subjects)` — what each date-filtered statement was, and of what the answer reports none.
513
+
514
+ Split out from the check so both the revise reason and the reader
515
+ disclosure are computed from one reading of the run, rather than from two
516
+ that can disagree about which statement they mean.
517
+ """
518
+ from openstategraph.counted_rows import tables_in
519
+
520
+ subjects = nothing_claims_in(candidate)
521
+ if not subjects:
522
+ return ([], [])
523
+ declarations = declarations_in(state)
524
+ findings: list[tuple[str, str, TableDeclaration | None, tuple[date | None, date | None]]] = []
525
+ for sql, _result in exchanges_in(state):
526
+ window = window_of(sql)
527
+ if window == (None, None):
528
+ continue
529
+ # **Every table the statement names**, and the worst answer wins. A
530
+ # join reaches two tables and a zero could have come from either, so
531
+ # reading only the first `FROM` would clear a statement on the strength
532
+ # of the table that happened to be written first — observed on a live
533
+ # run (2026-08-29) whose statement had the shape `FROM main.Invoice
534
+ # ... EXISTS (SELECT 1 FROM main.PlaylistTrack …)`, putting the suspect
535
+ # table second.
536
+ best: tuple[str, str, TableDeclaration | None] | None = None
537
+ for table in tables_in(sql) or [""]:
538
+ declaration = declarations.get(table.casefold())
539
+ state_name = assess(window, declaration)
540
+ if not state_name:
541
+ continue
542
+ if best is None or _SEVERITY[state_name] > _SEVERITY[best[0]]:
543
+ best = (state_name, table, declaration)
544
+ if best is None:
545
+ continue
546
+ findings.append((best[0], best[1], best[2], window))
547
+ return (findings, subjects)
548
+
549
+
550
+ def _english(values: Iterable[str]) -> str:
551
+ items = [value for value in values if value]
552
+ if len(items) <= 1:
553
+ return "".join(items)
554
+ return ", ".join(items[:-1]) + " and " + items[-1]
555
+
556
+
557
+ def check_zero_outside_coverage(
558
+ candidate: str, state: Mapping[str, Any], model_authored: Iterable[str]
559
+ ) -> str:
560
+ """`guard.check`'s coverage gate: empty is a pass, text is the revise reason.
561
+
562
+ Fires on one situation only — the answer reports **none** of something, and
563
+ a statement this run executed asked about a period the table it read
564
+ **declares** it does not hold. Then a zero is not a measurement and the
565
+ answer must say which of the two it means.
566
+
567
+ Everything else is a pass, and two of those passes are not silent: an
568
+ undeclared table and a window running past the end of a declared one both
569
+ put a sentence on the reader rail (`abc/tool_notes.UncoveredWindow`),
570
+ because no revision lap can repair either and a guard that objects forever
571
+ and then publishes is `launch-readiness/167`.
572
+
573
+ `model_authored` is accepted and unused, as it is on
574
+ `check_row_counts_in_prose`: it is part of the built-in check signature
575
+ because `numbers_in_prose` needs to know whose text is evidence, and this
576
+ check reads tool calls, which are nobody's draft.
577
+ """
578
+ from openstategraph.abc.tool_notes import UncoveredWindow, record_notes
579
+
580
+ findings, subjects = coverage_findings(candidate, state)
581
+ if not findings:
582
+ return ""
583
+ subject = _english(subjects)
584
+
585
+ outside = [entry for entry in findings if entry[0] == "outside"]
586
+ if outside:
587
+ _state_name, table, declaration, window = outside[0]
588
+ assert declaration is not None and declaration.coverage_max is not None
589
+ if states_the_date(candidate, declaration.coverage_max):
590
+ # The answer has said it. See `states_the_date` — this is the
591
+ # check's own exit, and without it the gate objects forever.
592
+ return ""
593
+ return (
594
+ f"The answer reports no {subject}. Every date this run filtered on lies "
595
+ f"outside what {table or 'that table'} declares it holds: the statement asked "
596
+ f"about {window[0]} to {window[1]}, and the table's declared coverage is "
597
+ f"{declaration.coverage_min} to {declaration.coverage_max}. No row could have "
598
+ "matched, so this zero is not a measurement. Say which of the two it is — "
599
+ "that nothing was found, or that this data does not reach the period asked "
600
+ "about — and name the last date the data holds."
601
+ )
602
+
603
+ notes: list[Any] = []
604
+ for state_name, table, declaration, window in findings:
605
+ if state_name == "partial" and declaration is not None:
606
+ notes.append(
607
+ UncoveredWindow(
608
+ subject=subject,
609
+ table=table,
610
+ declared_max=str(declaration.coverage_max or ""),
611
+ )
612
+ )
613
+ elif state_name == "undeclared":
614
+ notes.append(UncoveredWindow(subject=subject, table=table))
615
+ if notes:
616
+ record_notes(notes)
617
+ return ""
618
+
619
+
620
+ __all__ = [
621
+ "COVERAGE_STATES",
622
+ "TableDeclaration",
623
+ "assess",
624
+ "check_zero_outside_coverage",
625
+ "coverage_findings",
626
+ "declaration_in",
627
+ "declarations_in",
628
+ "declarations_in_result",
629
+ "nothing_claims_in",
630
+ "states_the_date",
631
+ "window_of",
632
+ ]