stateous 0.2.2__tar.gz → 0.4.0__tar.gz

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 (260) hide show
  1. {stateous-0.2.2 → stateous-0.4.0}/.gitignore +2 -0
  2. {stateous-0.2.2 → stateous-0.4.0}/PKG-INFO +2 -2
  3. {stateous-0.2.2 → stateous-0.4.0}/docs/concepts/agents.md +2 -2
  4. {stateous-0.2.2 → stateous-0.4.0}/docs/concepts/context-notes-memory.md +2 -1
  5. stateous-0.4.0/docs/concepts/data.md +115 -0
  6. {stateous-0.2.2 → stateous-0.4.0}/docs/concepts/guards.md +11 -3
  7. {stateous-0.2.2 → stateous-0.4.0}/docs/concepts/model.md +6 -48
  8. stateous-0.4.0/docs/concepts/notices.md +68 -0
  9. {stateous-0.2.2 → stateous-0.4.0}/docs/concepts/parallel.md +4 -2
  10. {stateous-0.2.2 → stateous-0.4.0}/docs/concepts/pause-resume-cancel.md +4 -0
  11. {stateous-0.2.2 → stateous-0.4.0}/docs/concepts/reliability.md +4 -2
  12. {stateous-0.2.2 → stateous-0.4.0}/docs/concepts/tasks-and-routines.md +3 -3
  13. stateous-0.4.0/docs/concepts/tenancy.md +79 -0
  14. stateous-0.4.0/docs/concepts/transports.md +67 -0
  15. {stateous-0.2.2 → stateous-0.4.0}/docs/concepts/two-sides.md +2 -2
  16. {stateous-0.2.2 → stateous-0.4.0}/docs/getting-started.md +94 -25
  17. stateous-0.4.0/docs/how-to/embed-a-control-plane.md +123 -0
  18. stateous-0.4.0/docs/how-to/run-replicas.md +70 -0
  19. {stateous-0.2.2 → stateous-0.4.0}/docs/how-to/run-supervisors.md +28 -1
  20. {stateous-0.2.2 → stateous-0.4.0}/docs/how-to/steer-tokens.md +8 -2
  21. {stateous-0.2.2 → stateous-0.4.0}/docs/how-to/use-postgres.md +4 -5
  22. {stateous-0.2.2 → stateous-0.4.0}/docs/how-to/write-a-routine.md +8 -2
  23. stateous-0.4.0/docs/how-to/write-a-transport.md +109 -0
  24. {stateous-0.2.2 → stateous-0.4.0}/docs/how-to/write-a-workflow.md +7 -3
  25. stateous-0.4.0/docs/index.md +50 -0
  26. {stateous-0.2.2 → stateous-0.4.0}/docs/inside/data.md +58 -13
  27. stateous-0.4.0/docs/inside/words.md +39 -0
  28. {stateous-0.2.2 → stateous-0.4.0}/docs/inside/workflows.md +5 -5
  29. {stateous-0.2.2 → stateous-0.4.0}/docs/reference/cli.md +32 -7
  30. {stateous-0.2.2 → stateous-0.4.0}/docs/reference/files.md +2 -1
  31. {stateous-0.2.2 → stateous-0.4.0}/docs/reference/http.md +10 -3
  32. stateous-0.4.0/docs/reference/python.md +156 -0
  33. {stateous-0.2.2 → stateous-0.4.0}/mkdocs.yml +8 -0
  34. {stateous-0.2.2 → stateous-0.4.0}/pyproject.toml +34 -3
  35. {stateous-0.2.2 → stateous-0.4.0}/scripts/check.py +1 -1
  36. stateous-0.4.0/src/stateous/__init__.py +141 -0
  37. {stateous-0.2.2 → stateous-0.4.0}/src/stateous/cli/main.py +27 -1
  38. stateous-0.4.0/src/stateous/cli/migrating.py +29 -0
  39. {stateous-0.2.2 → stateous-0.4.0}/src/stateous/cli/running.py +30 -8
  40. {stateous-0.2.2 → stateous-0.4.0}/src/stateous/cli/serving.py +59 -151
  41. {stateous-0.2.2 → stateous-0.4.0}/src/stateous/cli/starter.py +21 -24
  42. {stateous-0.2.2 → stateous-0.4.0}/src/stateous/cli/tokens.py +47 -4
  43. {stateous-0.2.2 → stateous-0.4.0}/src/stateous/client/client.py +48 -12
  44. {stateous-0.2.2 → stateous-0.4.0}/src/stateous/compiler/codegen.py +2 -0
  45. {stateous-0.2.2 → stateous-0.4.0}/src/stateous/compiler/compile.py +13 -4
  46. {stateous-0.2.2 → stateous-0.4.0}/src/stateous/compiler/exclusive.py +1 -1
  47. {stateous-0.2.2 → stateous-0.4.0}/src/stateous/compiler/validate.py +20 -0
  48. stateous-0.4.0/src/stateous/control/access.py +20 -0
  49. stateous-0.4.0/src/stateous/control/answer.py +102 -0
  50. {stateous-0.2.2 → stateous-0.4.0}/src/stateous/control/api.py +246 -166
  51. stateous-0.4.0/src/stateous/control/checks.py +147 -0
  52. stateous-0.4.0/src/stateous/control/clock.py +112 -0
  53. {stateous-0.2.2 → stateous-0.4.0}/src/stateous/control/engine.py +281 -141
  54. stateous-0.4.0/src/stateous/control/errors.py +120 -0
  55. {stateous-0.2.2 → stateous-0.4.0}/src/stateous/control/graph.py +28 -5
  56. stateous-0.4.0/src/stateous/control/ids.py +31 -0
  57. stateous-0.4.0/src/stateous/control/inprocess.py +53 -0
  58. stateous-0.4.0/src/stateous/control/notices.py +106 -0
  59. stateous-0.4.0/src/stateous/control/plane.py +779 -0
  60. stateous-0.4.0/src/stateous/control/scope.py +56 -0
  61. {stateous-0.2.2 → stateous-0.4.0}/src/stateous/control/store/__init__.py +2 -2
  62. stateous-0.4.0/src/stateous/control/store/errors.py +25 -0
  63. {stateous-0.2.2 → stateous-0.4.0}/src/stateous/control/store/migrations/__init__.py +37 -32
  64. {stateous-0.2.2 → stateous-0.4.0}/src/stateous/control/store/migrations/env.py +3 -2
  65. {stateous-0.2.2 → stateous-0.4.0}/src/stateous/control/store/migrations/versions/0001_baseline.py +69 -4
  66. {stateous-0.2.2 → stateous-0.4.0}/src/stateous/control/store/store.py +608 -33
  67. {stateous-0.2.2 → stateous-0.4.0}/src/stateous/control/store/tables.py +74 -0
  68. stateous-0.4.0/src/stateous/control/waiting.py +85 -0
  69. stateous-0.4.0/src/stateous/model/branches.py +32 -0
  70. {stateous-0.2.2 → stateous-0.4.0}/src/stateous/model/context.py +19 -3
  71. {stateous-0.2.2 → stateous-0.4.0}/src/stateous/model/graph_file.py +24 -0
  72. {stateous-0.2.2 → stateous-0.4.0}/src/stateous/model/guards.py +29 -15
  73. {stateous-0.2.2 → stateous-0.4.0}/src/stateous/model/wire.py +17 -0
  74. {stateous-0.2.2 → stateous-0.4.0}/src/stateous/model/workflow.py +58 -6
  75. {stateous-0.2.2 → stateous-0.4.0}/src/stateous/supervisor/folder.py +2 -0
  76. stateous-0.4.0/src/stateous/supervisor/remote.py +184 -0
  77. stateous-0.4.0/src/stateous/supervisor/retrying.py +146 -0
  78. stateous-0.4.0/src/stateous/supervisor/run.py +58 -0
  79. {stateous-0.2.2 → stateous-0.4.0}/src/stateous/supervisor/supervisor.py +56 -20
  80. stateous-0.4.0/src/stateous/testing.py +213 -0
  81. stateous-0.4.0/src/stateous/transport/__init__.py +28 -0
  82. stateous-0.4.0/src/stateous/transport/calling.py +98 -0
  83. stateous-0.4.0/src/stateous/transport/errors.py +21 -0
  84. stateous-0.4.0/src/stateous/transport/messages.py +79 -0
  85. stateous-0.4.0/src/stateous/transport/protocol.py +55 -0
  86. {stateous-0.2.2 → stateous-0.4.0}/tests/docs/test_concepts.py +76 -10
  87. {stateous-0.2.2 → stateous-0.4.0}/tests/docs/test_how_to.py +0 -2
  88. {stateous-0.2.2 → stateous-0.4.0}/tests/docs/test_numbers.py +2 -2
  89. {stateous-0.2.2 → stateous-0.4.0}/tests/docs/test_reference.py +19 -8
  90. {stateous-0.2.2 → stateous-0.4.0}/tests/docs/test_site.py +2 -2
  91. {stateous-0.2.2 → stateous-0.4.0}/tests/e2e/test_example.py +14 -0
  92. {stateous-0.2.2 → stateous-0.4.0}/tests/integration/conftest.py +7 -9
  93. {stateous-0.2.2 → stateous-0.4.0}/tests/integration/supervising.py +3 -2
  94. stateous-0.4.0/tests/integration/test_api_authorize.py +161 -0
  95. stateous-0.4.0/tests/integration/test_api_labels.py +80 -0
  96. {stateous-0.2.2 → stateous-0.4.0}/tests/integration/test_api_parallel.py +3 -1
  97. {stateous-0.2.2 → stateous-0.4.0}/tests/integration/test_api_refusals.py +3 -3
  98. {stateous-0.2.2 → stateous-0.4.0}/tests/integration/test_api_tasks.py +9 -14
  99. {stateous-0.2.2 → stateous-0.4.0}/tests/integration/test_api_tokens.py +4 -4
  100. stateous-0.4.0/tests/integration/test_claim_wait.py +177 -0
  101. {stateous-0.2.2 → stateous-0.4.0}/tests/integration/test_client.py +5 -3
  102. {stateous-0.2.2 → stateous-0.4.0}/tests/integration/test_prepare_serve.py +1 -1
  103. stateous-0.4.0/tests/integration/test_supervise_api.py +145 -0
  104. stateous-0.4.0/tests/postgres/test_given_engine.py +73 -0
  105. {stateous-0.2.2 → stateous-0.4.0}/tests/postgres/test_migrations.py +2 -27
  106. stateous-0.4.0/tests/postgres/test_namespace.py +101 -0
  107. stateous-0.4.0/tests/postgres/test_notices.py +72 -0
  108. stateous-0.4.0/tests/postgres/test_ready_across_replicas.py +125 -0
  109. stateous-0.4.0/tests/postgres/test_replicas.py +223 -0
  110. {stateous-0.2.2 → stateous-0.4.0}/tests/postgres/test_serving.py +7 -7
  111. {stateous-0.2.2 → stateous-0.4.0}/tests/postgres/test_time_limits.py +11 -6
  112. stateous-0.4.0/tests/transport/memory_queue.py +52 -0
  113. stateous-0.4.0/tests/transport/test_kit.py +109 -0
  114. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/cli/test_clock.py +2 -1
  115. stateous-0.4.0/tests/unit/cli/test_command_failures.py +191 -0
  116. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/cli/test_init_workflow.py +4 -4
  117. stateous-0.4.0/tests/unit/cli/test_migrate.py +95 -0
  118. stateous-0.4.0/tests/unit/cli/test_running_paths.py +267 -0
  119. stateous-0.4.0/tests/unit/cli/test_serving_refusals.py +70 -0
  120. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/cli/test_show_children.py +1 -1
  121. stateous-0.4.0/tests/unit/cli/test_show_context.py +130 -0
  122. stateous-0.4.0/tests/unit/client/test_client_requests.py +90 -0
  123. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/compiler/test_codegen.py +63 -0
  124. stateous-0.4.0/tests/unit/compiler/test_exclusive_domains.py +112 -0
  125. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/compiler/test_load.py +8 -0
  126. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/compiler/test_validate.py +37 -0
  127. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/control/support.py +18 -1
  128. stateous-0.4.0/tests/unit/control/test_answer.py +154 -0
  129. stateous-0.4.0/tests/unit/control/test_api_edges.py +69 -0
  130. stateous-0.4.0/tests/unit/control/test_authorize.py +166 -0
  131. stateous-0.4.0/tests/unit/control/test_claim_labels.py +83 -0
  132. stateous-0.4.0/tests/unit/control/test_engine_edges.py +255 -0
  133. stateous-0.4.0/tests/unit/control/test_explicit_migrations.py +84 -0
  134. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/control/test_graph.py +8 -0
  135. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/control/test_inputs.py +14 -5
  136. stateous-0.4.0/tests/unit/control/test_into_engine.py +187 -0
  137. stateous-0.4.0/tests/unit/control/test_labels.py +98 -0
  138. stateous-0.4.0/tests/unit/control/test_made_ids.py +71 -0
  139. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/control/test_migrations.py +16 -82
  140. stateous-0.4.0/tests/unit/control/test_namespace.py +41 -0
  141. stateous-0.4.0/tests/unit/control/test_notices_delivered.py +219 -0
  142. stateous-0.4.0/tests/unit/control/test_notices_labels.py +41 -0
  143. stateous-0.4.0/tests/unit/control/test_notices_written.py +159 -0
  144. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/control/test_parallel.py +6 -6
  145. stateous-0.4.0/tests/unit/control/test_plane.py +181 -0
  146. stateous-0.4.0/tests/unit/control/test_replicas.py +14 -0
  147. stateous-0.4.0/tests/unit/control/test_scope_keys.py +93 -0
  148. stateous-0.4.0/tests/unit/control/test_scopes.py +205 -0
  149. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/control/test_serving.py +2 -16
  150. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/control/test_store.py +0 -16
  151. stateous-0.4.0/tests/unit/control/test_store_edges.py +74 -0
  152. stateous-0.4.0/tests/unit/control/test_task_ready.py +101 -0
  153. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/control/test_tasks.py +4 -3
  154. stateous-0.4.0/tests/unit/control/test_waiting.py +59 -0
  155. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/model/test_context.py +44 -3
  156. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/model/test_contract.py +4 -0
  157. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/model/test_graph_file.py +14 -0
  158. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/model/test_guards.py +43 -8
  159. stateous-0.4.0/tests/unit/model/test_into.py +192 -0
  160. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/supervisor/fakes.py +37 -6
  161. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/supervisor/test_folder.py +17 -0
  162. stateous-0.4.0/tests/unit/supervisor/test_http_transport.py +150 -0
  163. stateous-0.4.0/tests/unit/supervisor/test_outbox_errors.py +39 -0
  164. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/supervisor/test_remote.py +11 -32
  165. stateous-0.4.0/tests/unit/supervisor/test_remote_answers.py +129 -0
  166. stateous-0.4.0/tests/unit/supervisor/test_retrying.py +116 -0
  167. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/supervisor/test_supervisor_edges.py +32 -20
  168. stateous-0.4.0/tests/unit/supervisor/test_supervisor_faults.py +546 -0
  169. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/supervisor/test_supervisor_outbox.py +6 -8
  170. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/test_layout.py +1 -0
  171. stateous-0.4.0/tests/unit/test_public_names.py +49 -0
  172. stateous-0.4.0/tests/unit/transport/test_calling.py +170 -0
  173. stateous-0.4.0/tests/unit/transport/test_messages.py +80 -0
  174. stateous-0.2.2/docs/index.md +0 -44
  175. stateous-0.2.2/docs/reference/python.md +0 -46
  176. stateous-0.2.2/src/stateous/__init__.py +0 -24
  177. stateous-0.2.2/src/stateous/control/store/errors.py +0 -10
  178. stateous-0.2.2/src/stateous/control/store/migrations/versions/0002_claims.py +0 -34
  179. stateous-0.2.2/src/stateous/control/store/migrations/versions/0003_children.py +0 -40
  180. stateous-0.2.2/src/stateous/supervisor/remote.py +0 -238
  181. stateous-0.2.2/tests/unit/test_public_names.py +0 -19
  182. {stateous-0.2.2 → stateous-0.4.0}/LICENSE +0 -0
  183. {stateous-0.2.2 → stateous-0.4.0}/NOTICE +0 -0
  184. {stateous-0.2.2 → stateous-0.4.0}/README.md +0 -0
  185. {stateous-0.2.2 → stateous-0.4.0}/docs/concepts/timers.md +0 -0
  186. {stateous-0.2.2 → stateous-0.4.0}/docs/how-to/change-a-workflow.md +0 -0
  187. {stateous-0.2.2 → stateous-0.4.0}/docs/inside/event-graph.md +0 -0
  188. {stateous-0.2.2 → stateous-0.4.0}/docs/reference/limits.md +0 -0
  189. {stateous-0.2.2 → stateous-0.4.0}/examples/sdlc/build/sdlc.json +0 -0
  190. {stateous-0.2.2 → stateous-0.4.0}/examples/sdlc/flow.py +0 -0
  191. {stateous-0.2.2 → stateous-0.4.0}/examples/sdlc/schemas.py +0 -0
  192. {stateous-0.2.2 → stateous-0.4.0}/examples/sdlc-supervisor/coding.py +0 -0
  193. {stateous-0.2.2 → stateous-0.4.0}/examples/sdlc-supervisor/contract.py +0 -0
  194. {stateous-0.2.2 → stateous-0.4.0}/examples/sdlc-supervisor/stateous.yaml +0 -0
  195. {stateous-0.2.2 → stateous-0.4.0}/examples/sdlc-supervisor/testing.py +0 -0
  196. {stateous-0.2.2 → stateous-0.4.0}/src/stateous/__main__.py +0 -0
  197. {stateous-0.2.2 → stateous-0.4.0}/src/stateous/cli/__init__.py +0 -0
  198. {stateous-0.2.2 → stateous-0.4.0}/src/stateous/cli/errors.py +0 -0
  199. {stateous-0.2.2 → stateous-0.4.0}/src/stateous/cli/project_file.py +0 -0
  200. {stateous-0.2.2 → stateous-0.4.0}/src/stateous/client/__init__.py +0 -0
  201. {stateous-0.2.2 → stateous-0.4.0}/src/stateous/compiler/__init__.py +0 -0
  202. {stateous-0.2.2 → stateous-0.4.0}/src/stateous/compiler/load.py +0 -0
  203. {stateous-0.2.2 → stateous-0.4.0}/src/stateous/compiler/plot.py +0 -0
  204. {stateous-0.2.2 → stateous-0.4.0}/src/stateous/control/__init__.py +0 -0
  205. {stateous-0.2.2 → stateous-0.4.0}/src/stateous/control/store/migrations/script.py.mako +0 -0
  206. {stateous-0.2.2 → stateous-0.4.0}/src/stateous/model/__init__.py +0 -0
  207. {stateous-0.2.2 → stateous-0.4.0}/src/stateous/model/contract.py +0 -0
  208. {stateous-0.2.2 → stateous-0.4.0}/src/stateous/model/durations.py +0 -0
  209. {stateous-0.2.2 → stateous-0.4.0}/src/stateous/model/events.py +0 -0
  210. {stateous-0.2.2 → stateous-0.4.0}/src/stateous/model/host.py +0 -0
  211. {stateous-0.2.2 → stateous-0.4.0}/src/stateous/py.typed +0 -0
  212. {stateous-0.2.2 → stateous-0.4.0}/src/stateous/supervisor/__init__.py +0 -0
  213. {stateous-0.2.2 → stateous-0.4.0}/src/stateous/supervisor/outbox.py +0 -0
  214. {stateous-0.2.2 → stateous-0.4.0}/src/stateous/supervisor/registry.py +0 -0
  215. {stateous-0.2.2 → stateous-0.4.0}/tests/conftest.py +0 -0
  216. {stateous-0.2.2 → stateous-0.4.0}/tests/docs/pages.py +0 -0
  217. {stateous-0.2.2 → stateous-0.4.0}/tests/docs/test_inside.py +0 -0
  218. {stateous-0.2.2 → stateous-0.4.0}/tests/examples/fake_phd.py +0 -0
  219. {stateous-0.2.2 → stateous-0.4.0}/tests/examples/test_coding.py +0 -0
  220. {stateous-0.2.2 → stateous-0.4.0}/tests/examples/test_sdlc.py +0 -0
  221. {stateous-0.2.2 → stateous-0.4.0}/tests/integration/test_parallel_flow.py +0 -0
  222. {stateous-0.2.2 → stateous-0.4.0}/tests/integration/test_project_uv_sync.py +0 -0
  223. {stateous-0.2.2 → stateous-0.4.0}/tests/integration/test_serve_command.py +0 -0
  224. {stateous-0.2.2 → stateous-0.4.0}/tests/integration/test_supervise_cli.py +0 -0
  225. {stateous-0.2.2 → stateous-0.4.0}/tests/integration/test_supervise_process.py +0 -0
  226. {stateous-0.2.2 → stateous-0.4.0}/tests/integration/test_supervisor_flow.py +0 -0
  227. {stateous-0.2.2 → stateous-0.4.0}/tests/integration/test_token_commands.py +0 -0
  228. {stateous-0.2.2 → stateous-0.4.0}/tests/parallel.py +0 -0
  229. {stateous-0.2.2 → stateous-0.4.0}/tests/postgres/test_concurrency.py +0 -0
  230. {stateous-0.2.2 → stateous-0.4.0}/tests/postgres/test_connection.py +0 -0
  231. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/cli/test_closed_output.py +0 -0
  232. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/cli/test_compile_command.py +0 -0
  233. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/cli/test_configure_logging.py +0 -0
  234. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/cli/test_errors.py +0 -0
  235. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/cli/test_graceful_server.py +0 -0
  236. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/cli/test_listen.py +0 -0
  237. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/cli/test_project_file.py +0 -0
  238. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/cli/test_startup.py +0 -0
  239. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/cli/test_supervise_helpers.py +0 -0
  240. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/cli/test_supervised_server.py +0 -0
  241. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/cli/test_token_lines.py +0 -0
  242. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/compiler/test_compile.py +0 -0
  243. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/compiler/test_exclusive.py +0 -0
  244. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/compiler/test_plot.py +0 -0
  245. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/control/test_case_race.py +0 -0
  246. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/control/test_claim_requests.py +0 -0
  247. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/control/test_clock.py +0 -0
  248. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/control/test_deadlock.py +0 -0
  249. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/control/test_engine.py +0 -0
  250. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/control/test_parallel_steering.py +0 -0
  251. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/control/test_pause.py +0 -0
  252. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/model/test_durations.py +0 -0
  253. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/model/test_host.py +0 -0
  254. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/model/test_wire.py +0 -0
  255. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/model/test_workflow.py +0 -0
  256. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/supervisor/test_open.py +0 -0
  257. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/supervisor/test_outbox.py +0 -0
  258. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/supervisor/test_registry.py +0 -0
  259. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/supervisor/test_supervisor.py +0 -0
  260. {stateous-0.2.2 → stateous-0.4.0}/tests/unit/test_test_databases.py +0 -0
@@ -11,3 +11,5 @@ try/
11
11
  try.db
12
12
  .stateous/
13
13
  site/
14
+ .coverage
15
+ .coverage.*
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: stateous
3
- Version: 0.2.2
3
+ Version: 0.4.0
4
4
  Summary: A process as a graph of states. A control plane keeps every token durable.
5
5
  Project-URL: Homepage, https://github.com/StateousLabs/stateous
6
6
  Project-URL: Source, https://github.com/StateousLabs/stateous
@@ -33,7 +33,7 @@ Requires-Dist: starlette>=0.40
33
33
  Requires-Dist: typer>=0.12
34
34
  Requires-Dist: uvicorn>=0.30
35
35
  Provides-Extra: phd
36
- Requires-Dist: poly-harness-dispatcher>=0.1; extra == 'phd'
36
+ Requires-Dist: poly-harness-dispatcher>=0.2; extra == 'phd'
37
37
  Description-Content-Type: text/markdown
38
38
 
39
39
  # Stateous
@@ -6,7 +6,7 @@ A routine runs a coding agent with the library PHD, and Stateous keeps the agent
6
6
 
7
7
  ## Why it exists
8
8
 
9
- A coding agent can work for an hour, hang, or crash with its computer. Its answer must be one of the outcomes that the state allows. When it fails, the next try should continue its session, not start again.
9
+ A coding agent can work for an hour, hang, or crash with its computer. Its answer must name one of the events that the state allows. When it fails, the next try should continue its session, not start again.
10
10
 
11
11
  Stateous and PHD share this work. PHD runs the agent and checks its answer. Stateous keeps the task, the retries and the session id. PHD knows nothing of workflows, and it does not report to Stateous.
12
12
 
@@ -137,7 +137,7 @@ async def code(ctx: TicketContext) -> events.done | events.stuck:
137
137
 
138
138
  ## Guarantees
139
139
 
140
- - Only an outcome that the state can emit is accepted. PHD checks it, and the control plane checks it again.
140
+ - Only an event that the state can emit is accepted. PHD checks it, and the control plane checks it again.
141
141
  - The task's lease stays alive while the routine runs, for as long as the agent works.
142
142
  - When the token leaves the state, or is cancelled, the supervisor cancels the routine at the next heartbeat, and PHD stops the run.
143
143
  - The session id in `ctx.memory` stays after a crash, so the next attempt can resume the session.
@@ -25,9 +25,10 @@ These are the fields of `ctx`:
25
25
  | `ctx.note(text)` | One line of progress in the token's history. It is sent at once. |
26
26
  | `ctx.token` | The token's id. |
27
27
  | `ctx.task` | The task's id. |
28
+ | `ctx.labels` | The token's labels, for example `{"user": "u42"}`: they tell which tenant the token is of. |
28
29
  | `ctx.visit` | 1 the first time the token is in this state, 2 the next time, and so on. |
29
30
  | `ctx.attempt` | 1, then 2 after a retry, and so on. |
30
- | `ctx.entered_by` | The event that brought the token here: `.name` and `.payload`. In the first state, `.name` is `__started__`. |
31
+ | `ctx.entered_by` | The name of the event that brought the token here, as `ctx.entered_by.name`. In the first state, it is `__started__`. A routine does not get the payload: an event whose payload the token keeps declares `into=`. See [Where data goes](data.md). |
31
32
  | `ctx.schedule(event, after="10m")` | A timer. See [Timers and timeouts](timers.md). |
32
33
 
33
34
  ### The context
@@ -0,0 +1,115 @@
1
+ # Where data goes
2
+
3
+ ## In one sentence
4
+
5
+ A routine reads and writes only the context: an event says why a token moved, and `into=` keeps its payload in the context.
6
+
7
+ ## Why it exists
8
+
9
+ A token carries data from state to state. Without one rule, data can go to many places, and you must choose each time.
10
+
11
+ Stateous has two rules, and the API follows them:
12
+
13
+ 1. **Data.** A routine reads and writes only the context. An event's name and payload say *why* the token moved. Guards and the history read the payload. If the token must keep a payload, the event declares `into=`.
14
+ 2. **Decisions.** Routines decide, and guards only route. A routine returns the event that names its decision. A guard only chooses a transition, from data that is already there.
15
+
16
+ ## How it works
17
+
18
+ | Place | What it is for | Who reads it | When it is saved |
19
+ |---|---|---|---|
20
+ | The context, `ctx["key"]` | The data of the token: all that later states need. | Each routine of the token, and the guards. | With the event, or not at all. |
21
+ | An event's payload | Why the token moved, for example a `Verdict`. | The guards, and the history. Not the routines. | With the event, in the history. |
22
+ | `into="key"` on an event | Keeps the event's payload in the context, as `ctx["key"]`. | Each later routine, through the context. | With the event, before the guards run. |
23
+ | `ctx.memory` | The routine's own bookkeeping, for example an agent's session id. | The routine of the same state, on a retry or a later visit. | At once. |
24
+ | `ctx.note(text)` | One line of progress, for people. | People, in the history. | At once. |
25
+ | `inputs=` on a parallel state | Data that goes down, from the parent's context to each child's context. | The routines of the child. | When the child starts. |
26
+ | `into="key"` on a parallel state | Data that comes back up: the `Branches` of the join, with each child's context. | Each later routine of the parent. | When the join is met. |
27
+
28
+ Some facts:
29
+
30
+ - A routine knows which event brought the token in: `ctx.entered_by.name`, for example `timeout`. It does not get that event's payload. For the payload, declare `into=`.
31
+ - `into=` works for each source of the event: a routine's report, `stateous token fire`, a timer and a resume.
32
+ - If a routine writes the same key that the event's `into=` names, the payload wins.
33
+ - `stateous compile` checks `into=`. The field must be in the context model, and its type must take the payload model, for example `Verdict` or `Verdict | None`.
34
+ - `stateous token show` prints the context, so you can see what each routine wrote.
35
+
36
+ ## Example
37
+
38
+ This is a `triage` workflow for support tickets. `classify` decides if a ticket is urgent. `escalate` pages an engineer. `answer` writes the reply.
39
+
40
+ ```python
41
+ # triage/schemas.py
42
+ from pydantic import BaseModel
43
+
44
+
45
+ class Ticket(BaseModel):
46
+ title: str
47
+ body: str
48
+ on_call: str = "" # escalate writes it
49
+ reply: str = "" # answer writes it
50
+ ```
51
+
52
+ The rule "the body has the word 'down'" is a decision. So a routine makes it, and returns `urgent` or `normal`. A guard does not search the text.
53
+
54
+ ```python
55
+ # triage-supervisor/classify.py
56
+ import re
57
+
58
+ from stateous import on_state
59
+
60
+ from contract import TicketContext, events, states
61
+
62
+
63
+ @on_state(states.classify)
64
+ def classify(ctx: TicketContext) -> events.urgent | events.normal:
65
+ if re.search(r"\bdown\b", ctx["body"].lower()):
66
+ return events.urgent()
67
+ return events.normal()
68
+ ```
69
+
70
+ `escalate` writes the engineer's name to the context. `answer`, a later state, reads it there:
71
+
72
+ ```python
73
+ # triage-supervisor/escalate.py
74
+ from stateous import on_state
75
+
76
+ from contract import TicketContext, events, states
77
+
78
+
79
+ @on_state(states.escalate)
80
+ def escalate(ctx: TicketContext) -> events.paged:
81
+ ctx["on_call"] = "Ada"
82
+ ctx.note("paged Ada")
83
+ return events.paged()
84
+ ```
85
+
86
+ ```python
87
+ # triage-supervisor/answer.py
88
+ from stateous import on_state
89
+
90
+ from contract import TicketContext, events, states
91
+
92
+
93
+ @on_state(states.answer)
94
+ def answer(ctx: TicketContext) -> events.replied:
95
+ if ctx["on_call"]:
96
+ ctx["reply"] = f"This is urgent. {ctx['on_call']} works on it now."
97
+ else:
98
+ ctx["reply"] = "Thank you. We reply soon."
99
+ return events.replied()
100
+ ```
101
+
102
+ `stateous token show TICKET-1` then prints the context with `on_call` and `reply`.
103
+
104
+ ## Guarantees
105
+
106
+ - A routine's context changes and an event's `into=` are saved in one transaction with the event, or not at all.
107
+ - A routine never sees a payload. So it cannot depend on data that the token does not keep.
108
+ - `stateous compile` refuses an `into=` whose field is not in the context model. It also refuses a field whose type does not take the payload.
109
+
110
+ ## See also
111
+
112
+ - [Context, notes and memory](context-notes-memory.md): each field of `ctx`.
113
+ - [Guards](guards.md): what a guard can read.
114
+ - [Parallel and nested work](parallel.md): `inputs=` and `into=` on a parallel state.
115
+ - [The model](model.md): the words context, payload and event.
@@ -6,10 +6,12 @@ A guard is a small condition in `when=` that chooses which transition an event t
6
6
 
7
7
  ## Why it exists
8
8
 
9
- One outcome can lead to different places. For example, a failed test run goes back to `coding` two times, but the third failure ends the token. The routine must not know this rule, because it does not see the graph.
9
+ One event can lead to different places. For example, a failed test run goes back to `coding` two times, but the third failure ends the token. The routine must not know this rule, because it does not see the graph.
10
10
 
11
11
  So the graph holds the rule, as a guard on the transition. Stateous checks the guards when you compile, so a token never has two ways to go.
12
12
 
13
+ Routines decide, and guards only route. A decision about the work, such as "the body of the ticket has the word 'down'", is the work of a routine. The routine returns the event that names the decision, for example `urgent` or `normal`. A guard only chooses a transition from data that is already there: a count, a field of the payload, a field of the context. So the guard language has no text search and no arithmetic. See [Where data goes](data.md).
14
+
13
15
  ## How it works
14
16
 
15
17
  A guard is an expression in a small language. It is not Python, and nothing runs it as Python. It can use these items:
@@ -38,6 +40,14 @@ When an event comes, the control plane looks at the transitions from the token's
38
40
  2. If no guard matches, the token takes the transition with `otherwise=True`.
39
41
  3. If no guard matches and there is no `otherwise=True`, the control plane refuses the event. The token stays where it is.
40
42
 
43
+ **The rule of `otherwise=True`.** This is the one place where the docs give this rule:
44
+
45
+ - A transition that is the only one from its state on its event needs no guard and no `otherwise=True`.
46
+ - When a state has two or more transitions on one event, each has a guard, except at most one. That one has no guard, and it must have `otherwise=True`: it is the fallback.
47
+ - The fallback is optional. With no fallback, an event that no guard matches is refused.
48
+
49
+ Compile stops if a transition breaks this rule.
50
+
41
51
  ### The overlap check
42
52
 
43
53
  `stateous compile` makes sure that the guards on one state and one event never overlap. Two guards overlap when some data can make both of them true.
@@ -46,8 +56,6 @@ If two guards can overlap, compile stops with an error, and it gives an example
46
56
 
47
57
  Compile also stops when it cannot prove that two guards never overlap. This occurs when a guard compares two values with each other, orders a list, or uses `branches`. Then make one transition the fallback with `otherwise=True`.
48
58
 
49
- Next to transitions with guards, a transition without a guard must have `otherwise=True`. Compile stops if it does not.
50
-
51
59
  ## Example
52
60
 
53
61
  In `sdlc`, the event `failed` has two transitions from `testing`:
@@ -10,7 +10,7 @@ A long process has many steps, and each step can take minutes or days. A step ca
10
10
 
11
11
  Stateous puts the process in one graph. The graph tells all the places where a run can be, and all the ways to go on. A run never moves in a way that the graph does not show.
12
12
 
13
- This page defines each word of Stateous. Every other page uses each word in the same sense.
13
+ This page defines each word that you need to build with Stateous. Every other page uses each word in the same sense. The words of how Stateous works inside, such as lease and outbox, are on [The words inside](../inside/words.md).
14
14
 
15
15
  ## How it works
16
16
 
@@ -44,7 +44,7 @@ Two states are Stateous's own. `START` is where each token begins, and `END` is
44
44
 
45
45
  ### event
46
46
 
47
- An outcome of a state, for example `passed` or `failed`. Only an event moves a token. An event can have a payload.
47
+ What happened in a state, for example `passed` or `failed`. Only an event moves a token. Its name and its payload say why the token moved.
48
48
 
49
49
  Stateous has three events of its own: `timeout`, `error` and `joined`. Your transitions use them by name. You cannot declare them, and you cannot fire them.
50
50
 
@@ -62,25 +62,20 @@ The status is `active`, `paused`, `completed`, `failed` or `cancelled`. A token
62
62
 
63
63
  ### context
64
64
 
65
- The business data of a token, for example the path of a checkout. A pydantic model gives its fields. A routine reads it as `ctx["key"]`, and can write it.
65
+ The business data of a token, for example the path of a checkout. A pydantic model gives its fields. A routine reads it as `ctx["key"]`, and can write it. It is the only data that a routine reads and writes. See [Where data goes](data.md).
66
66
 
67
67
  ### payload
68
68
 
69
- The data of one event, for example the numbers of tests that passed and failed. A pydantic model gives its fields. An event without a payload model has no payload.
69
+ The data of one event, for example the numbers of tests that passed and failed. A pydantic model gives its fields. An event without a payload model has no payload. Guards and the history read the payload. To keep it for later states, the event declares `into="key"`, and the context keeps it as `ctx["key"]`.
70
70
 
71
71
  ### task
72
72
 
73
73
  "Do state S for token T". The control plane queues one task each time a token enters a state. A supervisor claims the task and runs its routine.
74
74
 
75
-
76
75
  ### visit
77
76
 
78
77
  One stay of a token in one state. The first time that a token enters a state is visit 1, the next time is visit 2. A routine reads it as `ctx.visit`. The history shows it, for example `entered coding (visit 2)`.
79
78
 
80
- ### claim
81
-
82
- A supervisor's request for a task of the states that it serves. The control plane answers with a grant: one queued task, its token, its visit, its attempt and its context. The task is then claimed.
83
-
84
79
  ### routine
85
80
 
86
81
  Your function that does the work of one state. It gets the token's context as `ctx`, and it returns an event. It is in the supervisor's folder, and it is marked with `@on_state(states.X)`.
@@ -97,45 +92,22 @@ The process that keeps every token, and chooses each next state. You start it wi
97
92
 
98
93
  The compiled workflow, as JSON, for example `sdlc/build/sdlc.json`. `stateous compile` writes it, and `stateous serve` serves it.
99
94
 
100
-
101
- ### checksum
102
-
103
- The hash of the whole graph file, for example `sha256:...`. Each change to the graph file changes it. A supervisor's `contract.py` is for one checksum.
104
-
105
- ### structure
106
-
107
- The hash of the graph file without the `timeout=` and `retries=` of its states. A database serves one structure at a time. See [Change a workflow](../how-to/change-a-workflow.md).
108
-
109
95
  ### contract
110
96
 
111
97
  The file `contract.py` in the supervisor's folder. `stateous init supervisor` writes it from the graph. It gives the states, the events that each state can emit, and the models. It is all that a supervisor knows of the workflow.
112
98
 
113
- ### ledger
114
-
115
- The history of each token. Each change adds one row, and the rows are never changed. `stateous token show` prints the ledger of a token.
116
-
117
99
  ### guard
118
100
 
119
- A condition on a transition, written in `when=`. It reads the context, the payload and counts of events. See [Guards](guards.md).
101
+ A condition on a transition, written in `when=`. It reads the context, the payload and counts of events. A guard only routes: a routine makes the decisions. See [Guards](guards.md).
120
102
 
121
103
  ### timer
122
104
 
123
105
  An event that the clock fires later, if the token is still in the same state. A state's `timeout=` is a timer too. See [Timers and timeouts](timers.md).
124
106
 
125
- ### lease
126
-
127
- The time for which a supervisor holds a claimed task. A heartbeat renews it. See [Tasks and routines](tasks-and-routines.md).
128
-
129
-
130
- ### heartbeat
131
-
132
- The message that a supervisor sends every 30 seconds for all the tasks that it holds. It renews their leases. Its answer names each task that the supervisor does not hold now, for example because the token left the state.
133
-
134
107
  ### attempt
135
108
 
136
109
  One try of a task. The first claim is attempt 1. When an attempt fails and the state has retries left, the next claim is attempt 2.
137
110
 
138
-
139
111
  ### retries
140
112
 
141
113
  The number of more attempts that a state gives after a failed attempt: `retries=2` gives three attempts in all. After the last failed attempt, the token gets the event `error`.
@@ -156,24 +128,10 @@ A state whose work is other workflows, which run at the same time. It has no tas
156
128
 
157
129
  A token that a parallel state starts, one for each workflow of the state. Its parent is the token in the parallel state.
158
130
 
159
-
160
131
  ### join
161
132
 
162
133
  The rule that tells when a parallel state is done. `join="all"` waits for each child token to end. `join="any"` continues when the first child token ends. When the join is met, the control plane fires `joined` on the parent.
163
134
 
164
- ### outbox
165
-
166
- The supervisor's local file of messages that the control plane did not answer yet: `.stateous/outbox.db`. See [Reliability](reliability.md).
167
-
168
- ### idempotency key
169
-
170
- A key that you give with an event from outside. A second event with the same key applies nothing, and gets the answer "duplicate". See [Reliability](reliability.md).
171
-
172
-
173
- ### held event
174
-
175
- An event that comes to a paused token. The control plane keeps it, and applies it on resume, in the order of arrival. The history shows `done held while paused`. See [Pause, resume and cancel](pause-resume-cancel.md).
176
-
177
135
  ## Example
178
136
 
179
137
  The `sdlc` workflow has two states. In `coding`, an agent writes code. In `testing`, a routine runs the tests.
@@ -240,7 +198,7 @@ stateDiagram-v2
240
198
  - A token is in one state at a time. Only an event moves it, and only along a transition of the graph.
241
199
  - An event that the token's state cannot take is refused. The token stays where it is, and the ledger records the refusal.
242
200
  - The ledger keeps each change. Stateous never changes or deletes a row of the ledger.
243
- - Not guaranteed: that your routine does the right work. Stateous makes sure only that its outcome is one that the graph allows.
201
+ - Not guaranteed: that your routine does the right work. Stateous makes sure only that its event is one that the graph allows.
244
202
 
245
203
  ## See also
246
204
 
@@ -0,0 +1,68 @@
1
+ # Notices
2
+
3
+ ## In one sentence
4
+
5
+ A notice tells your code that a token changed: an event was accepted, a token ended, or a task failed for the last time.
6
+
7
+ ## Why it exists
8
+
9
+ Workflows know nothing about each other. Your code decides that the end of workflow A starts workflow B. Your code also updates a UI, or sends a message to a queue.
10
+
11
+ So your code must hear what each workflow does. Polling `stateous token show` is slow, and it can miss a change. A notice is kept in the database until your handler has it.
12
+
13
+ ## How it works
14
+
15
+ Notices are a setting of the database. Turn them on with `stateous migrate --notices`, or with `ControlPlane.migrate(notices=True)`. Each control plane reads the setting when it opens.
16
+
17
+ When notices are on, each of these changes writes a notice in the same transaction as the change:
18
+
19
+ | Kind | When |
20
+ |---|---|
21
+ | `event` | An event was accepted. A held event counts when a resume applies it. A rejected event gives no notice. |
22
+ | `completed`, `failed`, `cancelled` | A token ended so. A child token of a parallel state gives one too, with its `parent`. |
23
+ | `task_failed` | A task failed for the last time. A failure that will retry gives no notice. |
24
+
25
+ `ControlPlane.deliver_notices(handler)` gives the waiting notices to your handler. It deletes each notice after the handler returns. `run_notices(handler)` does this in your event loop until `close()`.
26
+
27
+ Some facts:
28
+
29
+ - **At least once.** If the process stops before the delete is saved, the handler gets the notice again.
30
+ - **In order for each token family.** A family is a top token and its child tokens. Between families there is no order.
31
+ - **Labels.** `notice.labels` are the token's labels, so a handler can route a notice to its tenant.
32
+ - **The id is stable.** `notice.id` is the same at each delivery. Use it as an idempotency key.
33
+ - **A failing handler.** If the handler raises, its family's notices come again on the next call. The other families go on.
34
+ - **Keep the handler short.** It runs inside a database transaction. Hand slow work to your own queue.
35
+ - **On SQLite**, the handler must not call the same control plane. It can call another control plane.
36
+
37
+ ## Example
38
+
39
+ When a token of `plan` ends, start a token of `tasks` for the same project:
40
+
41
+ ```python
42
+ from stateous import ControlPlane, Notice
43
+
44
+
45
+ def connect(plan: ControlPlane, tasks: ControlPlane) -> None:
46
+ """Start `tasks` for each `plan` token that completes."""
47
+
48
+ def handler(notice: Notice) -> None:
49
+ if notice.kind == "completed" and notice.parent is None:
50
+ tasks.start(f"tasks-of-{notice.token}", {"plan": notice.token})
51
+
52
+ plan.deliver_notices(handler)
53
+ ```
54
+
55
+ To start a token that exists returns it, unchanged. So a notice that comes twice starts `tasks` once.
56
+
57
+ ## Guarantees
58
+
59
+ - A change and its notice are saved in one transaction, or neither is.
60
+ - A notice is deleted only after the handler returned with no error.
61
+ - Two deliverers on one database never get the same family at the same time.
62
+
63
+ ## See also
64
+
65
+ - [Embed a control plane](../how-to/embed-a-control-plane.md): a control plane in your own service.
66
+ - [Reliability](reliability.md): the ledger, and the other mechanisms.
67
+ - [The commands](../reference/cli.md): `stateous migrate --notices`.
68
+ - [The Python API](../reference/python.md): `Notice` and `ControlPlane.deliver_notices`.
@@ -47,9 +47,11 @@ When the join is met, the control plane fires the event `joined` on the parent.
47
47
  - `token`: the child's id;
48
48
  - `status`: `completed` or `failed`;
49
49
  - `final`: the state that the child was in when it ended;
50
- - `payload`: the payload of the event that brought the child into that state.
50
+ - `context`: the child's context when it ended.
51
51
 
52
- A guard on `joined` can use `branches.all(...)` and `branches.any(...)`. In the parentheses, use `workflow`, `token`, `status`, `final` and `payload.field`. The guard can also use `ctx` and `count`.
52
+ A guard on `joined` can use `branches.all(...)` and `branches.any(...)`. In the parentheses, use `workflow`, `token`, `status`, `final` and `context.field`. `stateous compile` checks that a child workflow of the state has the field. The guard can also use `ctx` and `count`.
53
+
54
+ To keep the results of the children for later states, give the parallel state `into="reviews"`. The parent's context then keeps the payload of `joined` as `ctx["reviews"]`. Its type in the context model is `Branches` (from `stateous`), or `Branches | None`. So data goes down to the children with `inputs=`, and comes back with `into=`, always through the context. See [Where data goes](data.md).
53
55
 
54
56
  `stateous compile` cannot prove that two guards with `branches` never overlap. So give the guard to one transition, and make the other the fallback with `otherwise=True`. If no transition takes `joined`, the parent fails.
55
57
 
@@ -103,6 +103,10 @@ error: the control plane at http://127.0.0.1:8080 refused (409): token 'TICKET-3
103
103
 
104
104
  ```text
105
105
  TICKET-3: testing, cancelled
106
+ context:
107
+ {
108
+ "repo": "acme/api"
109
+ }
106
110
  22:39:47 #1 started
107
111
  22:39:47 #2 __started__ in START
108
112
  22:39:47 #3 entered coding
@@ -28,7 +28,9 @@ These are the seven mechanisms:
28
28
 
29
29
  The control plane keeps all of its data in one database. Each change to a token is one transaction. The transaction changes the token, its tasks and its timers, and it adds rows to the ledger. Either all of it is saved, or none of it.
30
30
 
31
- Each change locks the token, so one token moves one step at a time. One control plane serves one database. A second control plane on the same database does not start.
31
+ Each change locks the token, so one token moves one step at a time. One control plane serves one namespace of a database. A second control plane on the same namespace does not start. On SQLite, a namespace is a database file. On Postgres, several replicas can serve one namespace together: see [Run replicas](../how-to/run-replicas.md).
32
+
33
+ With notices on, a change also writes its [notice](notices.md) in the same transaction. Your handler gets each notice at least once.
32
34
 
33
35
  ### Leases and attempts
34
36
 
@@ -130,7 +132,7 @@ build-box-2 took task 1 (attempt 2)
130
132
 
131
133
  ## See also
132
134
 
133
- - [The model](model.md): the words [ledger](model.md#ledger), [lease](model.md#lease), [outbox](model.md#outbox) and [idempotency key](model.md#idempotency-key).
135
+ - [The words inside](../inside/words.md): [ledger](../inside/words.md#ledger), [lease](../inside/words.md#lease), [outbox](../inside/words.md#outbox) and [idempotency key](../inside/words.md#idempotency-key).
134
136
  - [Tasks and routines](tasks-and-routines.md): claims, heartbeats and attempts.
135
137
  - [Context, notes and memory](context-notes-memory.md): the routine's memory.
136
138
  - [Pause, resume and cancel](pause-resume-cancel.md).
@@ -20,7 +20,7 @@ A task goes through these steps:
20
20
  4. **Heartbeat.** While the routine runs, the supervisor sends a heartbeat every 30 seconds. One heartbeat names all of its running tasks, and it renews their leases.
21
21
  5. **Report.** The routine returns, and the supervisor reports the outcome. An event moves the token, and the task is done.
22
22
 
23
- The supervisor reports one of three kinds of outcome:
23
+ The supervisor reports the **outcome** of the task. An outcome is one of three kinds:
24
24
 
25
25
  | Outcome | When | What the control plane does |
26
26
  |---|---|---|
@@ -128,9 +128,9 @@ build-box-2 took task 1 (attempt 2)
128
128
 
129
129
  ## See also
130
130
 
131
- - [The model](model.md): the words [task](model.md#task), [routine](model.md#routine), [lease](model.md#lease) and [attempt](model.md#attempt).
131
+ - [The model](model.md): the words [task](model.md#task), [routine](model.md#routine), [lease](../inside/words.md#lease) and [attempt](model.md#attempt).
132
132
  - [The two sides](two-sides.md): what crosses the network.
133
133
  - [Timers and timeouts](timers.md): a state's `timeout=` covers all attempts.
134
134
  - [Context, notes and memory](context-notes-memory.md): every field of `ctx`.
135
135
  - [Reliability](reliability.md): leases, the outbox, and what happens when a supervisor stops.
136
- - [Write a routine](../how-to/write-a-routine.md): mark a routine, return an outcome, and fail.
136
+ - [Write a routine](../how-to/write-a-routine.md): mark a routine, return an event, and fail.
@@ -0,0 +1,79 @@
1
+ # Tenancy
2
+
3
+ ## In one sentence
4
+
5
+ Labels scope tokens and tasks to your tenants, and your own authorizer decides who may do what with them.
6
+
7
+ ## Why it exists
8
+
9
+ Stateous does not know what a user, a tenant or a plan is. Your product knows. One product keeps every tenant in one workflow. Another product runs a control plane for each tenant.
10
+
11
+ So Stateous gives two small tools, and no tenancy model. Your code decides how to use them.
12
+
13
+ ## How it works
14
+
15
+ **Labels.** A token gets labels at start, and a routine reads them as `ctx.labels`, for example `{"user": "u42", "project": "p7"}`.
16
+
17
+ - A token has at most 16 labels. A key is a lower-case letter, then up to 63 lower-case letters, digits, `_`, `.` or `-`. A value is a string of 1 to 256 characters.
18
+ - Labels never change after the start. A child token of a parallel state gets its parent's labels.
19
+ - A claim with labels takes only a task whose token has each of them. A claim with no labels takes any task.
20
+ - A list of tokens can filter by labels. Notices and "task ready" carry the labels.
21
+
22
+ **The authorizer.** `ControlPlane(..., authorize=fn)` calls `fn(caller, action, labels)` for each call. It returns True to allow. A refusal raises `Forbidden`, with the code `forbidden`; over HTTP it is 403.
23
+
24
+ | Action | Labels that it gets |
25
+ |---|---|
26
+ | `start` | The labels that the start gives. |
27
+ | `claim` | The labels that the claim asks for, `{}` for none. |
28
+ | `report`, `note`, `memory`, `heartbeat` | The labels of the task's token. A refused heartbeat task counts as lost. |
29
+ | `fire`, `pause`, `resume`, `cancel`, `read` | The labels of the token. A list keeps only the tokens that the caller may read. |
30
+
31
+ **Ids for each scope.** `ControlPlane(..., scope=["user"])` names the labels of a scope, at most 4. A token id is then unique only within those labels' values: user u1 and user u2 can both have `T-1`.
32
+
33
+ - A call names its scope with `scope=`, or your function `scope_of(caller)` gives it.
34
+ - A call never reaches another scope: such a token or task is not found (404). A list and a claim stay in the scope.
35
+ - A start takes its scope from its labels. A start whose labels name another scope than the caller's is `Forbidden`.
36
+ - `ALL_SCOPES` lets a trusted caller act across scopes, for example an admin view. An id that is in several scopes then needs `scope=`.
37
+ - The namespace keeps its scope. Another scope is refused with `ScopeConflict` while the namespace has any token.
38
+ - Inside, Stateous keeps a key made of a hash of the scope and the id. Every id that you see is the plain id.
39
+
40
+ **Ids that Stateous makes.** A start with no id gets a ULID: 26 characters, and ids made later sort later. With `key=`, an idempotency key, a retry in the same scope gets the same token.
41
+
42
+ **The caller.** Stateous never makes a caller. Each transport passes one through:
43
+
44
+ - HTTP: `create_app(plane, caller=fn)`, where `fn(request)` reads, for example, a user id that your gateway checked.
45
+ - In process: `InProcess(plane, caller=...)`.
46
+ - Your queue: `answer(plane, call, caller=...)`.
47
+ - Your own code: the keyword `caller` of each `ControlPlane` method.
48
+
49
+ **Entitlements.** `plane.count_claimed(labels)` counts the tasks claimed now for those labels. Your authorizer can use it, for example to allow about 3 tasks at a time on a plan. It is a soft limit: two claims at the same moment can both see 2, and both claim.
50
+
51
+ ## Example
52
+
53
+ Each user may act only on the tokens of that user. The service itself calls with no caller:
54
+
55
+ ```python
56
+ from collections.abc import Mapping
57
+
58
+ from stateous.control.access import Action
59
+
60
+
61
+ def only_own(caller: object, action: Action, labels: Mapping[str, str]) -> bool:
62
+ """A user may act only on the tokens with the label `user` of that user."""
63
+ return caller is None or labels.get("user") == caller
64
+ ```
65
+
66
+ A supervisor of user `u42` then claims with `labels={"user": "u42"}`, and its requests carry `u42` as the caller.
67
+
68
+ ## Guarantees
69
+
70
+ - A refused call changes nothing.
71
+ - A claim with labels never takes a task of a token without those labels.
72
+ - A waiting claim with labels is not woken by a task of other labels.
73
+
74
+ ## See also
75
+
76
+ - [Run replicas](../how-to/run-replicas.md): several control planes of one workflow.
77
+ - [Transports](transports.md): how the caller reaches the control plane.
78
+ - [Embed a control plane](../how-to/embed-a-control-plane.md): `ControlPlane` in your service.
79
+ - [The Python API](../reference/python.md): `Forbidden`, `Action` and `Authorize`.
@@ -0,0 +1,67 @@
1
+ # Transports
2
+
3
+ ## In one sentence
4
+
5
+ A transport carries the calls of a supervisor to a control plane: in one process, over HTTP, through a gateway, or over your own queue.
6
+
7
+ ## Why it exists
8
+
9
+ Stateous must not decide how the parts of your product talk. One team runs everything on one computer. Another team puts a gateway in front of each service, or sends each message through a broker.
10
+
11
+ So Stateous keeps three things apart:
12
+
13
+ | Layer | What it is | Who owns it |
14
+ |---|---|---|
15
+ | The protocol | The six calls of a supervisor, and their rules: leases, attempts, request ids, refusal codes, the outbox. | Stateous. It does not change. |
16
+ | The transport | How one call reaches the control plane, and how its reply comes back. | You. Stateous ships two. |
17
+ | The policy | Who may claim which tasks: users, tenants, authentication. | You. |
18
+
19
+ ## How it works
20
+
21
+ A supervisor makes six calls: `health`, `claim`, `report`, `heartbeat`, `note` and `set_memory`. A transport makes **one attempt** for each call. It returns the reply, or it raises one of two errors:
22
+
23
+ - `Refused`: the control plane answered no. It has a stable `code`, for example `task_not_held`. To try again does not help.
24
+ - `NotReached`: no answer came. The call may or may not have arrived.
25
+
26
+ The supervisor tries a call that is not reached again, after 1, 2, 4, 8, 16, then every 30 seconds. A claim sent again keeps its request id, so a lost reply never gives a task twice. A transport does not copy this logic.
27
+
28
+ Two codes mean "try again": `database_busy` and `not_serving`. A transport raises `NotReached` for them.
29
+
30
+ Stateous ships two transports:
31
+
32
+ - **HTTP**, the default of `stateous supervise`. It takes extra headers, for example a bearer token, and a URL with a path, for a gateway.
33
+ - **In process**, for a supervisor in the control plane's process. `serve --supervise` uses it.
34
+
35
+ For any other wire, `CallingTransport` needs one function: send a `Call`, give back its `Reply`. Both are plain JSON. On the control plane's side, `answer(plane, call)` gives the reply.
36
+
37
+ **Claims that wait.** A claim can wait up to 30 seconds at the control plane for a task. The control plane wakes it when a task is ready. So a supervisor does not have to poll. `ControlPlane.on_task_ready` tells your own code when a task is ready, with its state and its token's labels. Use it, for example, to publish to a queue for that tenant.
38
+
39
+ ## Example
40
+
41
+ A transport over a queue, in a few lines. The `send` function is yours:
42
+
43
+ ```python
44
+ from collections.abc import Awaitable, Callable
45
+
46
+ from stateous.transport import Call, CallingTransport, Reply
47
+
48
+
49
+ def queue_transport(send: Callable[[Call], Awaitable[Reply]]) -> CallingTransport:
50
+ """A supervisor's transport over your own queue."""
51
+ return CallingTransport(send, where="the jobs queue")
52
+ ```
53
+
54
+ [Write a transport](../how-to/write-a-transport.md) shows both sides, and the test kit.
55
+
56
+ ## Guarantees
57
+
58
+ - A transport never decides who holds a task. The control plane's database decides, with leases and attempts.
59
+ - A claim sent again with the same request id gets the same task. A lost reply loses no task.
60
+ - `stateous.testing.check_transport` checks that a transport keeps these rules. It cannot see every fault, for example a reply that a broker loses only under load.
61
+
62
+ ## See also
63
+
64
+ - [Write a transport](../how-to/write-a-transport.md): a queue transport, step by step.
65
+ - [Run supervisors](../how-to/run-supervisors.md): HTTP, gateways and headers.
66
+ - [Embed a control plane](../how-to/embed-a-control-plane.md): the control plane in your own service.
67
+ - [The HTTP API](../reference/http.md): the routes, and the codes of each refusal.
@@ -12,7 +12,7 @@ So Stateous has two sides. The control plane decides, and the supervisors do the
12
12
 
13
13
  The supervisor never sees the graph, for two reasons:
14
14
 
15
- - A routine cannot depend on the next state. It can only return an outcome, so you can change the graph without a change to the routines.
15
+ - A routine cannot depend on the next state. It can only return an event, so you can change the graph without a change to the routines.
16
16
  - A supervisor has only the information that its work needs. The rest of the process stays on the control plane.
17
17
 
18
18
  ## How it works
@@ -27,7 +27,7 @@ Each side is a folder of its own.
27
27
  The graph file stays on the control plane's side. Two things cross to the supervisor's side:
28
28
 
29
29
  - **The contract.** `stateous init supervisor` writes `contract.py`. It gets the graph from the control plane with `GET /workflow`, or it reads a local graph file or `flow.py`. The contract keeps only the states, the events that each state can emit, and the models.
30
- - **HTTP.** The supervisor claims tasks, sends heartbeats, and reports outcomes. It also sends notes and memory writes. It does this over HTTP, to the control plane's URL in `stateous.yaml`.
30
+ - **The calls.** The supervisor claims tasks, sends heartbeats, and reports outcomes. It also sends notes and memory writes. `stateous supervise` sends them over HTTP, to the control plane's URL in `stateous.yaml`. A program can send them over another wire: see [Transports](transports.md).
31
31
 
32
32
  ```mermaid
33
33
  flowchart LR