fivefold 0.1.0a1__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 (307) hide show
  1. fivefold-0.1.0a1/.dockerignore +14 -0
  2. fivefold-0.1.0a1/.github/workflows/ci.yml +132 -0
  3. fivefold-0.1.0a1/.github/workflows/nightly.yml +49 -0
  4. fivefold-0.1.0a1/.github/workflows/publish.yml +77 -0
  5. fivefold-0.1.0a1/.gitignore +21 -0
  6. fivefold-0.1.0a1/.python-version +1 -0
  7. fivefold-0.1.0a1/AGENTS.md +10 -0
  8. fivefold-0.1.0a1/CLAUDE.md +67 -0
  9. fivefold-0.1.0a1/CODE_OF_CONDUCT.md +93 -0
  10. fivefold-0.1.0a1/CONTRIBUTING.md +45 -0
  11. fivefold-0.1.0a1/Dockerfile +23 -0
  12. fivefold-0.1.0a1/LICENSE +202 -0
  13. fivefold-0.1.0a1/Makefile +62 -0
  14. fivefold-0.1.0a1/PKG-INFO +524 -0
  15. fivefold-0.1.0a1/README.md +498 -0
  16. fivefold-0.1.0a1/SECURITY.md +38 -0
  17. fivefold-0.1.0a1/db/bootstrap.sql +26 -0
  18. fivefold-0.1.0a1/db/migrations/0001_schemas.sql +67 -0
  19. fivefold-0.1.0a1/db/migrations/0002_gateway.sql +224 -0
  20. fivefold-0.1.0a1/db/migrations/0003_gateway_record_0010.sql +91 -0
  21. fivefold-0.1.0a1/db/migrations/0004_harness.sql +141 -0
  22. fivefold-0.1.0a1/db/migrations/0005_sim.sql +679 -0
  23. fivefold-0.1.0a1/db/migrations/0006_gateway_reads.sql +66 -0
  24. fivefold-0.1.0a1/db/migrations/0007_eval.sql +33 -0
  25. fivefold-0.1.0a1/db/migrations/0008_run_stop.sql +18 -0
  26. fivefold-0.1.0a1/db/migrations/0009_message_copies.sql +69 -0
  27. fivefold-0.1.0a1/db/migrations/0010_gateway_g1_check.sql +14 -0
  28. fivefold-0.1.0a1/db/migrations/0011_model_calls.sql +37 -0
  29. fivefold-0.1.0a1/db/migrations/0012_recovery_latency.sql +23 -0
  30. fivefold-0.1.0a1/db/migrations/0013_split_topology.sql +33 -0
  31. fivefold-0.1.0a1/db/migrations/0014_tool_call_args.sql +20 -0
  32. fivefold-0.1.0a1/db/registry/0001_registry.sql +31 -0
  33. fivefold-0.1.0a1/docker-compose.yml +143 -0
  34. fivefold-0.1.0a1/docs/adr/0000-template.md +21 -0
  35. fivefold-0.1.0a1/docs/adr/0001-action-identity.md +88 -0
  36. fivefold-0.1.0a1/docs/adr/0002-authority-approvals-and-grants.md +100 -0
  37. fivefold-0.1.0a1/docs/adr/0003-action-state-machine.md +192 -0
  38. fivefold-0.1.0a1/docs/adr/0004-five-properties.md +202 -0
  39. fivefold-0.1.0a1/docs/adr/0005-tool-contract-levels.md +113 -0
  40. fivefold-0.1.0a1/docs/adr/0006-fault-catalog.md +176 -0
  41. fivefold-0.1.0a1/docs/adr/0007-tooling.md +109 -0
  42. fivefold-0.1.0a1/docs/adr/0008-configurations-and-trust-boundaries.md +136 -0
  43. fivefold-0.1.0a1/docs/adr/0009-runs-and-deterministic-execution.md +150 -0
  44. fivefold-0.1.0a1/docs/adr/0010-state-machine-corrections.md +74 -0
  45. fivefold-0.1.0a1/docs/adr/0011-policy-after-run-closed.md +41 -0
  46. fivefold-0.1.0a1/docs/adr/0012-viewer-tooling.md +45 -0
  47. fivefold-0.1.0a1/docs/adr/0013-f10-cells.md +51 -0
  48. fivefold-0.1.0a1/docs/adr/0014-recovery-latency.md +69 -0
  49. fivefold-0.1.0a1/docs/adr/0015-status-tool-waits.md +106 -0
  50. fivefold-0.1.0a1/docs/adr/0016-simulator-schema-writer.md +24 -0
  51. fivefold-0.1.0a1/docs/adr/README.md +46 -0
  52. fivefold-0.1.0a1/docs/adr/m0-review-decisions.md +124 -0
  53. fivefold-0.1.0a1/docs/limitations.md +181 -0
  54. fivefold-0.1.0a1/docs/plan.md +85 -0
  55. fivefold-0.1.0a1/docs/product.md +110 -0
  56. fivefold-0.1.0a1/docs/spec.md +393 -0
  57. fivefold-0.1.0a1/faults/expected.yaml +406 -0
  58. fivefold-0.1.0a1/prices/example.yaml +25 -0
  59. fivefold-0.1.0a1/pyproject.toml +104 -0
  60. fivefold-0.1.0a1/scenarios/dev/dev-001-single-po.yaml +45 -0
  61. fivefold-0.1.0a1/scenarios/dev/dev-002-human-approval.yaml +47 -0
  62. fivefold-0.1.0a1/scenarios/scenario.schema.json +576 -0
  63. fivefold-0.1.0a1/scripts/check_identities.py +71 -0
  64. fivefold-0.1.0a1/src/fivefold/__init__.py +4 -0
  65. fivefold-0.1.0a1/src/fivefold/agents/__init__.py +7 -0
  66. fivefold-0.1.0a1/src/fivefold/agents/branch.py +187 -0
  67. fivefold-0.1.0a1/src/fivefold/agents/checkpoint.py +77 -0
  68. fivefold-0.1.0a1/src/fivefold/agents/connection.py +153 -0
  69. fivefold-0.1.0a1/src/fivefold/agents/live.py +492 -0
  70. fivefold-0.1.0a1/src/fivefold/agents/policy.py +426 -0
  71. fivefold-0.1.0a1/src/fivefold/agents/remote.py +333 -0
  72. fivefold-0.1.0a1/src/fivefold/agents/replay.py +170 -0
  73. fivefold-0.1.0a1/src/fivefold/agents/scripted.py +122 -0
  74. fivefold-0.1.0a1/src/fivefold/agents/tools.py +229 -0
  75. fivefold-0.1.0a1/src/fivefold/agents/worker.py +164 -0
  76. fivefold-0.1.0a1/src/fivefold/domain/__init__.py +5 -0
  77. fivefold-0.1.0a1/src/fivefold/domain/api.py +517 -0
  78. fivefold-0.1.0a1/src/fivefold/domain/authority.py +149 -0
  79. fivefold-0.1.0a1/src/fivefold/domain/contracts.py +80 -0
  80. fivefold-0.1.0a1/src/fivefold/domain/identity.py +113 -0
  81. fivefold-0.1.0a1/src/fivefold/domain/prices.py +178 -0
  82. fivefold-0.1.0a1/src/fivefold/domain/report.py +92 -0
  83. fivefold-0.1.0a1/src/fivefold/domain/rules.py +346 -0
  84. fivefold-0.1.0a1/src/fivefold/domain/scenario.py +524 -0
  85. fivefold-0.1.0a1/src/fivefold/evaluator/__init__.py +155 -0
  86. fivefold-0.1.0a1/src/fivefold/evaluator/__main__.py +127 -0
  87. fivefold-0.1.0a1/src/fivefold/evaluator/authorization.py +146 -0
  88. fivefold-0.1.0a1/src/fivefold/evaluator/checks.py +331 -0
  89. fivefold-0.1.0a1/src/fivefold/evaluator/evaluate.py +109 -0
  90. fivefold-0.1.0a1/src/fivefold/evaluator/evidence.py +392 -0
  91. fivefold-0.1.0a1/src/fivefold/evaluator/freshness.py +136 -0
  92. fivefold-0.1.0a1/src/fivefold/evaluator/liveness.py +236 -0
  93. fivefold-0.1.0a1/src/fivefold/evaluator/load.py +354 -0
  94. fivefold-0.1.0a1/src/fivefold/evaluator/metrics.py +95 -0
  95. fivefold-0.1.0a1/src/fivefold/evaluator/records.py +452 -0
  96. fivefold-0.1.0a1/src/fivefold/evaluator/recovery.py +209 -0
  97. fivefold-0.1.0a1/src/fivefold/evaluator/report.py +1096 -0
  98. fivefold-0.1.0a1/src/fivefold/evaluator/result.py +344 -0
  99. fivefold-0.1.0a1/src/fivefold/evaluator/store.py +83 -0
  100. fivefold-0.1.0a1/src/fivefold/faults/__init__.py +5 -0
  101. fivefold-0.1.0a1/src/fivefold/faults/catalog.py +278 -0
  102. fivefold-0.1.0a1/src/fivefold/faults/plan.py +538 -0
  103. fivefold-0.1.0a1/src/fivefold/gateway/__init__.py +6 -0
  104. fivefold-0.1.0a1/src/fivefold/gateway/admin.py +179 -0
  105. fivefold-0.1.0a1/src/fivefold/gateway/admin_api.py +398 -0
  106. fivefold-0.1.0a1/src/fivefold/gateway/codec.py +372 -0
  107. fivefold-0.1.0a1/src/fivefold/gateway/destination.py +64 -0
  108. fivefold-0.1.0a1/src/fivefold/gateway/dispatcher.py +379 -0
  109. fivefold-0.1.0a1/src/fivefold/gateway/freshness.py +83 -0
  110. fivefold-0.1.0a1/src/fivefold/gateway/invariants.py +761 -0
  111. fivefold-0.1.0a1/src/fivefold/gateway/memory.py +277 -0
  112. fivefold-0.1.0a1/src/fivefold/gateway/pg_store.py +657 -0
  113. fivefold-0.1.0a1/src/fivefold/gateway/records.py +592 -0
  114. fivefold-0.1.0a1/src/fivefold/gateway/server.py +102 -0
  115. fivefold-0.1.0a1/src/fivefold/gateway/sim_client.py +295 -0
  116. fivefold-0.1.0a1/src/fivefold/gateway/state_machine.py +376 -0
  117. fivefold-0.1.0a1/src/fivefold/gateway/steps.py +897 -0
  118. fivefold-0.1.0a1/src/fivefold/gateway/store.py +635 -0
  119. fivefold-0.1.0a1/src/fivefold/gateway/tools.py +424 -0
  120. fivefold-0.1.0a1/src/fivefold/gateway/twin.py +199 -0
  121. fivefold-0.1.0a1/src/fivefold/gateway/wire.py +138 -0
  122. fivefold-0.1.0a1/src/fivefold/harness/__init__.py +6 -0
  123. fivefold-0.1.0a1/src/fivefold/harness/actors.py +230 -0
  124. fivefold-0.1.0a1/src/fivefold/harness/cells.py +303 -0
  125. fivefold-0.1.0a1/src/fivefold/harness/clock.py +209 -0
  126. fivefold-0.1.0a1/src/fivefold/harness/demo.py +397 -0
  127. fivefold-0.1.0a1/src/fivefold/harness/fault_effects.py +122 -0
  128. fivefold-0.1.0a1/src/fivefold/harness/live_options.py +159 -0
  129. fivefold-0.1.0a1/src/fivefold/harness/log.py +540 -0
  130. fivefold-0.1.0a1/src/fivefold/harness/mcp_link.py +406 -0
  131. fivefold-0.1.0a1/src/fivefold/harness/migrations.py +520 -0
  132. fivefold-0.1.0a1/src/fivefold/harness/models.py +368 -0
  133. fivefold-0.1.0a1/src/fivefold/harness/registry.py +105 -0
  134. fivefold-0.1.0a1/src/fivefold/harness/reports.py +100 -0
  135. fivefold-0.1.0a1/src/fivefold/harness/rng.py +57 -0
  136. fivefold-0.1.0a1/src/fivefold/harness/run.py +881 -0
  137. fivefold-0.1.0a1/src/fivefold/harness/scheduler.py +441 -0
  138. fivefold-0.1.0a1/src/fivefold/harness/sim_points.py +215 -0
  139. fivefold-0.1.0a1/src/fivefold/harness/split/__init__.py +34 -0
  140. fivefold-0.1.0a1/src/fivefold/harness/split/__main__.py +275 -0
  141. fivefold-0.1.0a1/src/fivefold/harness/split/credentials.py +74 -0
  142. fivefold-0.1.0a1/src/fivefold/harness/split/faults.py +75 -0
  143. fivefold-0.1.0a1/src/fivefold/harness/split/gateway.py +769 -0
  144. fivefold-0.1.0a1/src/fivefold/harness/split/hops.py +291 -0
  145. fivefold-0.1.0a1/src/fivefold/harness/split/lifecycle.py +322 -0
  146. fivefold-0.1.0a1/src/fivefold/harness/split/rundir.py +152 -0
  147. fivefold-0.1.0a1/src/fivefold/harness/split/service.py +157 -0
  148. fivefold-0.1.0a1/src/fivefold/harness/split/simulator.py +432 -0
  149. fivefold-0.1.0a1/src/fivefold/harness/study.py +643 -0
  150. fivefold-0.1.0a1/src/fivefold/harness/transport.py +533 -0
  151. fivefold-0.1.0a1/src/fivefold/paths.py +24 -0
  152. fivefold-0.1.0a1/src/fivefold/py.typed +0 -0
  153. fivefold-0.1.0a1/src/fivefold/recorder/__init__.py +18 -0
  154. fivefold-0.1.0a1/src/fivefold/recorder/__main__.py +308 -0
  155. fivefold-0.1.0a1/src/fivefold/recorder/cassette.py +322 -0
  156. fivefold-0.1.0a1/src/fivefold/recorder/playback.py +316 -0
  157. fivefold-0.1.0a1/src/fivefold/recorder/recording.py +123 -0
  158. fivefold-0.1.0a1/src/fivefold/sim/__init__.py +37 -0
  159. fivefold-0.1.0a1/src/fivefold/sim/config.py +52 -0
  160. fivefold-0.1.0a1/src/fivefold/sim/endpoint.py +176 -0
  161. fivefold-0.1.0a1/src/fivefold/sim/ledger.py +583 -0
  162. fivefold-0.1.0a1/src/fivefold/sim/service.py +834 -0
  163. fivefold-0.1.0a1/src/fivefold/viewer/__init__.py +14 -0
  164. fivefold-0.1.0a1/src/fivefold/viewer/__main__.py +75 -0
  165. fivefold-0.1.0a1/src/fivefold/viewer/app.py +122 -0
  166. fivefold-0.1.0a1/src/fivefold/viewer/records.py +108 -0
  167. fivefold-0.1.0a1/src/fivefold/viewer/source.py +196 -0
  168. fivefold-0.1.0a1/src/fivefold/viewer/timeline.py +61 -0
  169. fivefold-0.1.0a1/tests/conftest.py +408 -0
  170. fivefold-0.1.0a1/tests/pg/test_admin_api_runs.py +276 -0
  171. fivefold-0.1.0a1/tests/pg/test_approver.py +92 -0
  172. fivefold-0.1.0a1/tests/pg/test_authority_faults.py +201 -0
  173. fivefold-0.1.0a1/tests/pg/test_branching.py +671 -0
  174. fivefold-0.1.0a1/tests/pg/test_crash_restarts.py +101 -0
  175. fivefold-0.1.0a1/tests/pg/test_delivery_faults.py +489 -0
  176. fivefold-0.1.0a1/tests/pg/test_demo_1.py +163 -0
  177. fivefold-0.1.0a1/tests/pg/test_demos.py +92 -0
  178. fivefold-0.1.0a1/tests/pg/test_determinism.py +98 -0
  179. fivefold-0.1.0a1/tests/pg/test_drain.py +41 -0
  180. fivefold-0.1.0a1/tests/pg/test_eval_schema.py +120 -0
  181. fivefold-0.1.0a1/tests/pg/test_evaluator_golden.py +1411 -0
  182. fivefold-0.1.0a1/tests/pg/test_expected.py +170 -0
  183. fivefold-0.1.0a1/tests/pg/test_expiry.py +134 -0
  184. fivefold-0.1.0a1/tests/pg/test_g1_runs.py +228 -0
  185. fivefold-0.1.0a1/tests/pg/test_gateway_crash.py +316 -0
  186. fivefold-0.1.0a1/tests/pg/test_gateway_on_sim.py +218 -0
  187. fivefold-0.1.0a1/tests/pg/test_gateway_schema.py +473 -0
  188. fivefold-0.1.0a1/tests/pg/test_harness_log.py +512 -0
  189. fivefold-0.1.0a1/tests/pg/test_live_runs.py +921 -0
  190. fivefold-0.1.0a1/tests/pg/test_migrate.py +405 -0
  191. fivefold-0.1.0a1/tests/pg/test_model_call_log.py +72 -0
  192. fivefold-0.1.0a1/tests/pg/test_nul_messages.py +115 -0
  193. fivefold-0.1.0a1/tests/pg/test_pg_store.py +471 -0
  194. fivefold-0.1.0a1/tests/pg/test_playback.py +373 -0
  195. fivefold-0.1.0a1/tests/pg/test_privileges.py +83 -0
  196. fivefold-0.1.0a1/tests/pg/test_random_plan_runs.py +145 -0
  197. fivefold-0.1.0a1/tests/pg/test_recovery_runs.py +285 -0
  198. fivefold-0.1.0a1/tests/pg/test_registry.py +148 -0
  199. fivefold-0.1.0a1/tests/pg/test_resolver_runs.py +280 -0
  200. fivefold-0.1.0a1/tests/pg/test_results_report.py +75 -0
  201. fivefold-0.1.0a1/tests/pg/test_run_end.py +116 -0
  202. fivefold-0.1.0a1/tests/pg/test_run_templates.py +291 -0
  203. fivefold-0.1.0a1/tests/pg/test_sim_points.py +333 -0
  204. fivefold-0.1.0a1/tests/pg/test_sim_schema.py +883 -0
  205. fivefold-0.1.0a1/tests/pg/test_sim_service.py +1250 -0
  206. fivefold-0.1.0a1/tests/pg/test_split_records.py +89 -0
  207. fivefold-0.1.0a1/tests/pg/test_split_runs.py +1191 -0
  208. fivefold-0.1.0a1/tests/pg/test_status_waits.py +312 -0
  209. fivefold-0.1.0a1/tests/pg/test_study.py +360 -0
  210. fivefold-0.1.0a1/tests/pg/test_tool_call_args.py +111 -0
  211. fivefold-0.1.0a1/tests/pg/test_two_workers.py +140 -0
  212. fivefold-0.1.0a1/tests/pg/test_viewer_api.py +312 -0
  213. fivefold-0.1.0a1/tests/property/test_g1_machine.py +401 -0
  214. fivefold-0.1.0a1/tests/property/test_gateway_machine.py +1075 -0
  215. fivefold-0.1.0a1/tests/property/test_migration_numbering.py +39 -0
  216. fivefold-0.1.0a1/tests/property/test_random_runs.py +164 -0
  217. fivefold-0.1.0a1/tests/property/test_sim_machine.py +638 -0
  218. fivefold-0.1.0a1/tests/unit/test_admin_api.py +787 -0
  219. fivefold-0.1.0a1/tests/unit/test_admission.py +190 -0
  220. fivefold-0.1.0a1/tests/unit/test_authority.py +160 -0
  221. fivefold-0.1.0a1/tests/unit/test_branch.py +522 -0
  222. fivefold-0.1.0a1/tests/unit/test_cassette.py +505 -0
  223. fivefold-0.1.0a1/tests/unit/test_cells.py +320 -0
  224. fivefold-0.1.0a1/tests/unit/test_check_identities.py +111 -0
  225. fivefold-0.1.0a1/tests/unit/test_ci_packaging.py +20 -0
  226. fivefold-0.1.0a1/tests/unit/test_codec.py +229 -0
  227. fivefold-0.1.0a1/tests/unit/test_compose.py +58 -0
  228. fivefold-0.1.0a1/tests/unit/test_connection.py +181 -0
  229. fivefold-0.1.0a1/tests/unit/test_database_names.py +52 -0
  230. fivefold-0.1.0a1/tests/unit/test_dispatcher.py +432 -0
  231. fivefold-0.1.0a1/tests/unit/test_distribution_metadata.py +33 -0
  232. fivefold-0.1.0a1/tests/unit/test_evaluator.py +3022 -0
  233. fivefold-0.1.0a1/tests/unit/test_evaluator_report.py +1587 -0
  234. fivefold-0.1.0a1/tests/unit/test_fault_plan.py +602 -0
  235. fivefold-0.1.0a1/tests/unit/test_g1_dispatcher.py +392 -0
  236. fivefold-0.1.0a1/tests/unit/test_g1_steps.py +385 -0
  237. fivefold-0.1.0a1/tests/unit/test_g1_tools.py +395 -0
  238. fivefold-0.1.0a1/tests/unit/test_gateway_steps.py +894 -0
  239. fivefold-0.1.0a1/tests/unit/test_gateway_tools.py +502 -0
  240. fivefold-0.1.0a1/tests/unit/test_host_scheduler.py +155 -0
  241. fivefold-0.1.0a1/tests/unit/test_identity.py +122 -0
  242. fivefold-0.1.0a1/tests/unit/test_import_boundaries.py +89 -0
  243. fivefold-0.1.0a1/tests/unit/test_invariants.py +700 -0
  244. fivefold-0.1.0a1/tests/unit/test_live.py +491 -0
  245. fivefold-0.1.0a1/tests/unit/test_live_providers.py +532 -0
  246. fivefold-0.1.0a1/tests/unit/test_mcp_link.py +425 -0
  247. fivefold-0.1.0a1/tests/unit/test_migration_files.py +96 -0
  248. fivefold-0.1.0a1/tests/unit/test_package_data.py +78 -0
  249. fivefold-0.1.0a1/tests/unit/test_policy.py +461 -0
  250. fivefold-0.1.0a1/tests/unit/test_prices.py +166 -0
  251. fivefold-0.1.0a1/tests/unit/test_publish_workflow.py +55 -0
  252. fivefold-0.1.0a1/tests/unit/test_random_plan.py +382 -0
  253. fivefold-0.1.0a1/tests/unit/test_record_and_replay.py +443 -0
  254. fivefold-0.1.0a1/tests/unit/test_registry.py +51 -0
  255. fivefold-0.1.0a1/tests/unit/test_report.py +70 -0
  256. fivefold-0.1.0a1/tests/unit/test_report_sink.py +58 -0
  257. fivefold-0.1.0a1/tests/unit/test_resolver.py +563 -0
  258. fivefold-0.1.0a1/tests/unit/test_rules.py +282 -0
  259. fivefold-0.1.0a1/tests/unit/test_run_models.py +159 -0
  260. fivefold-0.1.0a1/tests/unit/test_scenario.py +431 -0
  261. fivefold-0.1.0a1/tests/unit/test_scheduler.py +509 -0
  262. fivefold-0.1.0a1/tests/unit/test_scripted_imports.py +32 -0
  263. fivefold-0.1.0a1/tests/unit/test_sim_api.py +258 -0
  264. fivefold-0.1.0a1/tests/unit/test_sim_points.py +343 -0
  265. fivefold-0.1.0a1/tests/unit/test_split.py +562 -0
  266. fivefold-0.1.0a1/tests/unit/test_state_machine_table.py +246 -0
  267. fivefold-0.1.0a1/tests/unit/test_study.py +336 -0
  268. fivefold-0.1.0a1/tests/unit/test_transport.py +597 -0
  269. fivefold-0.1.0a1/tests/unit/test_viewer_cli.py +44 -0
  270. fivefold-0.1.0a1/tests/unit/test_viewer_source.py +92 -0
  271. fivefold-0.1.0a1/tests/unit/test_viewer_timeline.py +81 -0
  272. fivefold-0.1.0a1/tests/unit/test_wait_limit.py +81 -0
  273. fivefold-0.1.0a1/tests/unit/test_wire.py +148 -0
  274. fivefold-0.1.0a1/tests/unit/test_worker.py +189 -0
  275. fivefold-0.1.0a1/uv.lock +1591 -0
  276. fivefold-0.1.0a1/viewer/.gitignore +3 -0
  277. fivefold-0.1.0a1/viewer/.npmrc +1 -0
  278. fivefold-0.1.0a1/viewer/Dockerfile +30 -0
  279. fivefold-0.1.0a1/viewer/e2e/check.mjs +106 -0
  280. fivefold-0.1.0a1/viewer/eslint.config.js +25 -0
  281. fivefold-0.1.0a1/viewer/index.html +13 -0
  282. fivefold-0.1.0a1/viewer/package-lock.json +3724 -0
  283. fivefold-0.1.0a1/viewer/package.json +41 -0
  284. fivefold-0.1.0a1/viewer/src/App.tsx +30 -0
  285. fivefold-0.1.0a1/viewer/src/api.ts +39 -0
  286. fivefold-0.1.0a1/viewer/src/components/Compare.tsx +127 -0
  287. fivefold-0.1.0a1/viewer/src/components/Ledger.tsx +86 -0
  288. fivefold-0.1.0a1/viewer/src/components/RunList.tsx +121 -0
  289. fivefold-0.1.0a1/viewer/src/components/RunPage.tsx +46 -0
  290. fivefold-0.1.0a1/viewer/src/components/Scorecard.tsx +121 -0
  291. fivefold-0.1.0a1/viewer/src/components/Timeline.tsx +87 -0
  292. fivefold-0.1.0a1/viewer/src/components/common.tsx +34 -0
  293. fivefold-0.1.0a1/viewer/src/components.test.tsx +201 -0
  294. fivefold-0.1.0a1/viewer/src/describe.test.ts +51 -0
  295. fivefold-0.1.0a1/viewer/src/describe.ts +187 -0
  296. fivefold-0.1.0a1/viewer/src/load.ts +25 -0
  297. fivefold-0.1.0a1/viewer/src/main.tsx +13 -0
  298. fivefold-0.1.0a1/viewer/src/route.test.ts +29 -0
  299. fivefold-0.1.0a1/viewer/src/route.ts +50 -0
  300. fivefold-0.1.0a1/viewer/src/runData.ts +29 -0
  301. fivefold-0.1.0a1/viewer/src/styles.css +312 -0
  302. fivefold-0.1.0a1/viewer/src/test/fixtures.ts +380 -0
  303. fivefold-0.1.0a1/viewer/src/types.ts +226 -0
  304. fivefold-0.1.0a1/viewer/src/views.test.ts +117 -0
  305. fivefold-0.1.0a1/viewer/src/views.ts +174 -0
  306. fivefold-0.1.0a1/viewer/tsconfig.json +20 -0
  307. fivefold-0.1.0a1/viewer/vite.config.ts +15 -0
@@ -0,0 +1,14 @@
1
+ .git
2
+ .venv
3
+ wiki
4
+ **/__pycache__
5
+ .mypy_cache
6
+ .ruff_cache
7
+ .pytest_cache
8
+ .hypothesis
9
+ .env
10
+ .env.*
11
+ viewer/node_modules
12
+ viewer/dist
13
+ viewer/e2e/out
14
+ split-run
@@ -0,0 +1,132 @@
1
+ # Deterministic checks on every pull request and every push to main (0007).
2
+ # Live-model runs never run in CI.
3
+ name: CI
4
+
5
+ on:
6
+ pull_request:
7
+ push:
8
+ branches: [main]
9
+
10
+ permissions:
11
+ contents: read
12
+
13
+ jobs:
14
+ check:
15
+ name: Lint, type check and test
16
+ runs-on: ubuntu-24.04
17
+ services:
18
+ postgres:
19
+ image: postgres:16.15
20
+ env:
21
+ POSTGRES_HOST_AUTH_METHOD: trust
22
+ ports:
23
+ - 5432:5432
24
+ options: >-
25
+ --health-cmd "pg_isready -U postgres"
26
+ --health-interval 2s
27
+ --health-timeout 3s
28
+ --health-retries 30
29
+ env:
30
+ FIVEFOLD_ADMIN_DSN: postgresql://postgres@127.0.0.1:5432/postgres
31
+ HYPOTHESIS_PROFILE: ci
32
+ steps:
33
+ - uses: actions/checkout@v4
34
+ - uses: actions/setup-python@v5
35
+ with:
36
+ python-version: "3.12"
37
+ - name: Install uv
38
+ run: pip install uv==0.13.8
39
+ - name: Install locked dependencies
40
+ run: uv sync --locked
41
+ - name: Lint
42
+ run: make lint
43
+ - name: Type check
44
+ run: make typecheck
45
+ - name: Test
46
+ run: make test
47
+
48
+ packaging:
49
+ name: Installed wheel demo
50
+ runs-on: ubuntu-24.04
51
+ services:
52
+ postgres:
53
+ image: postgres:16.15
54
+ env:
55
+ POSTGRES_HOST_AUTH_METHOD: trust
56
+ ports:
57
+ - 5432:5432
58
+ options: >-
59
+ --health-cmd "pg_isready -U postgres"
60
+ --health-interval 2s
61
+ --health-timeout 3s
62
+ --health-retries 30
63
+ env:
64
+ FIVEFOLD_ADMIN_DSN: postgresql://postgres@127.0.0.1:5432/postgres
65
+ steps:
66
+ - uses: actions/checkout@v4
67
+ - uses: actions/setup-python@v5
68
+ with:
69
+ python-version: "3.12"
70
+ - name: Install uv
71
+ run: pip install uv==0.13.8
72
+ - name: Build the sdist and wheel
73
+ run: uv build --out-dir dist
74
+ - name: Run demo 1 from the installed wheel outside the checkout
75
+ run: |
76
+ smoke=$(mktemp -d)
77
+ uv venv --python 3.12 "$smoke/venv"
78
+ uv pip install --python "$smoke/venv/bin/python" dist/*.whl
79
+ cd "$smoke"
80
+ "$smoke/venv/bin/python" -m fivefold.harness.demo 1
81
+
82
+ identities:
83
+ name: Commit identities
84
+ # Every commit of a pull request must use GitHub noreply addresses (CLAUDE.md,
85
+ # "Commits and attribution"). The check never prints what it refuses.
86
+ if: github.event_name == 'pull_request'
87
+ runs-on: ubuntu-24.04
88
+ steps:
89
+ - uses: actions/checkout@v4
90
+ with:
91
+ fetch-depth: 0
92
+ - name: Check every commit's author and committer
93
+ run: python3 scripts/check_identities.py "${{ github.event.pull_request.base.sha }}..${{ github.event.pull_request.head.sha }}"
94
+
95
+ viewer:
96
+ name: Viewer build, lint and test
97
+ # The viewer's frontend (0012) on Node's current LTS line; the Python jobs never need Node.
98
+ runs-on: ubuntu-24.04
99
+ defaults:
100
+ run:
101
+ working-directory: viewer
102
+ steps:
103
+ - uses: actions/checkout@v4
104
+ - uses: actions/setup-node@v4
105
+ with:
106
+ node-version: "26.13.1"
107
+ cache: npm
108
+ cache-dependency-path: viewer/package-lock.json
109
+ - name: Install locked dependencies
110
+ run: npm ci
111
+ - name: Lint
112
+ run: npm run lint
113
+ - name: Test
114
+ run: npm test
115
+ - name: Type check and build
116
+ run: npm run build
117
+
118
+ container:
119
+ name: Compose file and app image
120
+ runs-on: ubuntu-24.04
121
+ steps:
122
+ - uses: actions/checkout@v4
123
+ - name: Validate the Compose file, with each profile
124
+ run: |
125
+ docker compose config --quiet
126
+ docker compose --profile app config --quiet
127
+ docker compose --profile viewer config --quiet
128
+ docker compose --profile split config --quiet
129
+ - name: Build the app image
130
+ run: docker build .
131
+ - name: Build the viewer image
132
+ run: docker build --file viewer/Dockerfile .
@@ -0,0 +1,49 @@
1
+ # Nightly property tests with far more examples than CI (0007). Hypothesis prints a
2
+ # reproduction blob for every failure, and the job uploads its example database.
3
+ name: Nightly
4
+
5
+ on:
6
+ schedule:
7
+ - cron: "17 3 * * *"
8
+ workflow_dispatch:
9
+
10
+ permissions:
11
+ contents: read
12
+
13
+ jobs:
14
+ properties:
15
+ name: Property tests (nightly profile)
16
+ runs-on: ubuntu-24.04
17
+ services:
18
+ postgres:
19
+ image: postgres:16.15
20
+ env:
21
+ POSTGRES_HOST_AUTH_METHOD: trust
22
+ ports:
23
+ - 5432:5432
24
+ options: >-
25
+ --health-cmd "pg_isready -U postgres"
26
+ --health-interval 2s
27
+ --health-timeout 3s
28
+ --health-retries 30
29
+ env:
30
+ FIVEFOLD_ADMIN_DSN: postgresql://postgres@127.0.0.1:5432/postgres
31
+ HYPOTHESIS_PROFILE: nightly
32
+ steps:
33
+ - uses: actions/checkout@v4
34
+ - uses: actions/setup-python@v5
35
+ with:
36
+ python-version: "3.12"
37
+ - name: Install uv
38
+ run: pip install uv==0.13.8
39
+ - name: Install locked dependencies
40
+ run: uv sync --locked
41
+ - name: Test
42
+ run: make test
43
+ - name: Upload failing examples
44
+ if: failure()
45
+ uses: actions/upload-artifact@v4
46
+ with:
47
+ name: hypothesis-examples
48
+ path: .hypothesis/
49
+ if-no-files-found: ignore
@@ -0,0 +1,77 @@
1
+ # Publishes FiveFold to PyPI when a GitHub release is published, through PyPI's
2
+ # Trusted Publishing: no token is stored anywhere. The build job checks that the
3
+ # release's tag is v plus the version in pyproject.toml, builds the sdist and the
4
+ # wheel, installs the wheel outside the repository and runs demo 1 from it, so a
5
+ # package that cannot run is never published. The publish job runs in the GitHub
6
+ # environment `pypi`, whose protection rules apply before anything is published.
7
+ name: Publish
8
+
9
+ on:
10
+ release:
11
+ types: [published]
12
+
13
+ permissions:
14
+ contents: read
15
+
16
+ jobs:
17
+ build:
18
+ name: Build and check the distributions
19
+ runs-on: ubuntu-24.04
20
+ services:
21
+ postgres:
22
+ image: postgres:16.15
23
+ env:
24
+ POSTGRES_HOST_AUTH_METHOD: trust
25
+ ports:
26
+ - 5432:5432
27
+ options: >-
28
+ --health-cmd "pg_isready -U postgres"
29
+ --health-interval 2s
30
+ --health-timeout 3s
31
+ --health-retries 30
32
+ env:
33
+ FIVEFOLD_ADMIN_DSN: postgresql://postgres@127.0.0.1:5432/postgres
34
+ steps:
35
+ - uses: actions/checkout@v4
36
+ - uses: actions/setup-python@v5
37
+ with:
38
+ python-version: "3.12"
39
+ - name: Install uv
40
+ run: pip install uv==0.13.8
41
+ - name: Check that the release tag names the package's version
42
+ run: |
43
+ version=$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')
44
+ tag="${GITHUB_REF#refs/tags/}"
45
+ if [ "$tag" != "v$version" ]; then
46
+ echo "The release tag is $tag, but pyproject.toml says version $version: tag the release v$version."
47
+ exit 1
48
+ fi
49
+ - name: Build the sdist and the wheel
50
+ run: uv build --out-dir dist
51
+ - name: Run demo 1 from the installed wheel, outside the repository
52
+ run: |
53
+ smoke=$(mktemp -d)
54
+ uv venv --python 3.12 "$smoke/venv"
55
+ uv pip install --python "$smoke/venv/bin/python" dist/*.whl
56
+ cd "$smoke"
57
+ "$smoke/venv/bin/python" -m fivefold.harness.demo 1
58
+ - uses: actions/upload-artifact@v7
59
+ with:
60
+ name: dist
61
+ path: dist/
62
+
63
+ publish:
64
+ name: Publish to PyPI
65
+ needs: build
66
+ runs-on: ubuntu-24.04
67
+ environment:
68
+ name: pypi
69
+ url: https://pypi.org/p/fivefold
70
+ permissions:
71
+ id-token: write
72
+ steps:
73
+ - uses: actions/download-artifact@v8
74
+ with:
75
+ name: dist
76
+ path: dist/
77
+ - uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,21 @@
1
+ # Local working wiki for agents and maintainers. Never published.
2
+ /wiki
3
+
4
+ # Python
5
+ __pycache__/
6
+ *.py[cod]
7
+ .venv/
8
+ .mypy_cache/
9
+ .ruff_cache/
10
+ .pytest_cache/
11
+ .hypothesis/
12
+
13
+ # Environment files and secrets
14
+ .env
15
+ .env.*
16
+
17
+ # A split run's directory, which holds the run's secrets (python -m fivefold.harness.split)
18
+ /split-run/
19
+
20
+ # Operating system files
21
+ .DS_Store
@@ -0,0 +1 @@
1
+ 3.12
@@ -0,0 +1,10 @@
1
+ # Instructions for coding agents
2
+
3
+ Follow `CLAUDE.md` and `CONTRIBUTING.md`. Read these files in order before working:
4
+
5
+ 1. `CLAUDE.md`
6
+ 2. `CONTRIBUTING.md`
7
+ 3. `docs/product.md`
8
+ 4. `docs/spec.md`
9
+ 5. `docs/plan.md`
10
+ 6. `docs/adr/README.md`
@@ -0,0 +1,67 @@
1
+ # CLAUDE.md
2
+
3
+ Rules for every coding agent working in this repo.
4
+
5
+ ## What this is
6
+
7
+ FiveFold is an open-source test suite and reference gateway. It checks whether AI agents act correctly under failure: every real-world action happens exactly once, with valid authority, on fresh inputs, is actually committed, and is honestly reported.
8
+
9
+ Read these before writing code, in this order:
10
+
11
+ 1. `docs/product.md`: what and why, scope, non-goals
12
+ 2. `docs/spec.md`: the contracts you build against
13
+ 3. `docs/plan.md`: milestones, teams, tickets
14
+ 4. `docs/adr/`: the accepted decision records, which hold the detail and reasoning behind the spec
15
+
16
+ ## Who decides what
17
+
18
+ - **The maintainer owns the semantics:** action identity, grant lifecycle, states and transitions, invariants I1 to I7, the five property definitions, tool names and return shapes, tool contract levels, and fault IDs.
19
+ - To change any of those, write a decision record in `docs/adr/` with status **Proposed** and stop. Do not mark it Accepted yourself.
20
+ - Everything else (internal module structure, helper names, test layout) is yours, as long as it serves the spec.
21
+
22
+ ## Hard rules
23
+
24
+ - **No invented APIs.** Before calling any library function, confirm it in the official docs or the installed package source. If you are unsure a function exists, say so in the PR instead of guessing.
25
+ - **In gateway configurations (G1, G2), the agent holds no simulator credential,** and only the gateway writes to the simulator. Baselines (B0, B1, B2) write directly by design; that is what they measure (0008).
26
+ - **The gateway and the simulator never share a database transaction.** They connect with separate roles that cannot touch each other's tables (0008).
27
+ - **The evaluator never calls a model.** It decides pass or fail only from simulator and harness records, and reads the gateway's tables only to explain failures (0004).
28
+ - **Every state transition is one database transaction** with row locks, and is logged append-only in ActionEvent. No network call happens inside a database transaction (0003).
29
+ - **Determinism:** every component, the gateway included, reads time only from the run's virtual clock and randomness only from the run's seeded generators (0009). Wall-clock time is recorded for metrics only. Lint bans wall-clock calls and global randomness outside the clock and generator modules (0007).
30
+ - **Held-out scenarios are off-limits.** They live outside this repo. Never search for, read or recreate them.
31
+ - **No live model calls in CI.** Live runs sit behind an explicit flag and a budget cap.
32
+ - **No secrets in the repo.** Keys come from environment variables.
33
+ - **Stay in scope.** The non-goals in `docs/product.md` are binding: no agent framework, no execution engine, no model router, no receipts or TEE in v0.1.
34
+
35
+ ## Tests
36
+
37
+ - Every fault variant has deterministic tests for every applicable (contract, configuration) cell, asserting the verdict and failing properties in `faults/expected.yaml` (0006). For every fault except F1, F10 and F12, at least one cell shows B0 failing where G2 passes.
38
+ - Invariants I1 to I7 are asserted in code and exercised by Hypothesis rule-based state machine tests.
39
+ - A PR that changes behaviour includes a test that would have caught the old behaviour.
40
+
41
+ ## Pull requests
42
+
43
+ - One ticket per PR, kept small. Keep one open PR per branch, and restart the branch from `main` after each merge. When a reviewer merges a sprint's PRs together at its end, stack them: each ticket's branch starts from the previous ticket's branch, and every PR targets `main`.
44
+ - The description names the spec section and decision records it implements, lists each library API it uses with where it was checked (a docs URL, or the installed source path and version), and states anything left uncertain.
45
+ - Dependency upgrades are separate PRs. An upgrade of LangGraph, langgraph-prebuilt or the MCP SDK re-checks the facts that 0008 and 0009 pin.
46
+ - Run the full deterministic suite before asking for review.
47
+
48
+ ## Commits and attribution
49
+
50
+ - Treat this repository as public. Never commit secrets, personal names, personal email addresses, local paths or machine details. Allowed: the maintainer's GitHub username, `samrusani`; GitHub noreply addresses in commit metadata; the contact address in `CODE_OF_CONDUCT.md`, which the maintainer chose as the project's public contact; and links to other people's public work in citations.
51
+ - No tool attribution in commits, pull requests or docs: no "Generated with" footers, no AI co-author trailers and no session links.
52
+ - Agents working for the maintainer commit as `samrusani <samrusani@users.noreply.github.com>`. Other contributors use their own GitHub noreply address.
53
+ - Before every push, check each new commit's author and committer. CI's commit identity check (`scripts/check_identities.py`) fails a pull request whose commits use any address that is not a GitHub noreply address, or the maintainer's address under another name.
54
+
55
+ ## Working wiki
56
+
57
+ - Agents keep working notes in `wiki/` at the repo root: status, roadmap, processes, learnings and a log. It is gitignored and never published.
58
+ - If `wiki/` exists, read `wiki/index.md` and `wiki/status.md` before starting, and follow `wiki/AGENTS.md`.
59
+ - Before finishing a session, update the pages you touched, `wiki/status.md` and `wiki/log.md`.
60
+ - Nothing moves from the wiki into the repository unless it passes the rules above.
61
+
62
+ ## Writing style for docs and the report
63
+
64
+ - Short sentences, plain words, specific numbers with units.
65
+ - No em dashes. Use commas, semicolons, colons, parentheses or separate sentences.
66
+ - Avoid stock phrases such as "It's worth noting", "Notably", "In an era of", "The landscape of", "This underscores" and "a testament to".
67
+ - Cite papers by full title and arXiv ID, and label them as preprints.
@@ -0,0 +1,93 @@
1
+
2
+ # Contributor Covenant 3.0 Code of Conduct
3
+
4
+ ## Our Pledge
5
+
6
+ We pledge to make our community welcoming, safe, and equitable for all.
7
+
8
+ We are committed to fostering an environment that respects and promotes the dignity, rights, and contributions of all individuals, regardless of characteristics including race, ethnicity, caste, color, age, physical characteristics, neurodiversity, disability, sex or gender, gender identity or expression, sexual orientation, language, philosophy or religion, national or social origin, socio-economic position, level of education, or other status. The same privileges of participation are extended to everyone who participates in good faith and in accordance with this Covenant.
9
+
10
+
11
+ ## Encouraged Behaviors
12
+
13
+ While acknowledging differences in social norms, we all strive to meet our community's expectations for positive behavior. We also understand that our words and actions may be interpreted differently than we intend based on culture, background, or native language.
14
+
15
+ With these considerations in mind, we agree to behave mindfully toward each other and act in ways that center our shared values, including:
16
+
17
+ 1. Respecting the **purpose of our community**, our activities, and our ways of gathering.
18
+ 2. Engaging **kindly and honestly** with others.
19
+ 3. Respecting **different viewpoints** and experiences.
20
+ 4. **Taking responsibility** for our actions and contributions.
21
+ 5. Gracefully giving and accepting **constructive feedback**.
22
+ 6. Committing to **repairing harm** when it occurs.
23
+ 7. Behaving in other ways that promote and sustain the **well-being of our community**.
24
+
25
+
26
+ ## Restricted Behaviors
27
+
28
+ We agree to restrict the following behaviors in our community. Instances, threats, and promotion of these behaviors are violations of this Code of Conduct.
29
+
30
+ 1. **Harassment.** Violating explicitly expressed boundaries or engaging in unnecessary personal attention after any clear request to stop.
31
+ 2. **Character attacks.** Making insulting, demeaning, or pejorative comments directed at a community member or group of people.
32
+ 3. **Stereotyping or discrimination.** Characterizing anyone’s personality or behavior on the basis of immutable identities or traits.
33
+ 4. **Sexualization.** Behaving in a way that would generally be considered inappropriately intimate in the context or purpose of the community.
34
+ 5. **Violating confidentiality**. Sharing or acting on someone's personal or private information without their permission.
35
+ 6. **Endangerment.** Causing, encouraging, or threatening violence or other harm toward any person or group.
36
+ 7. Behaving in other ways that **threaten the well-being** of our community.
37
+
38
+ ### Other Restrictions
39
+
40
+ 1. **Misleading identity.** Impersonating someone else for any reason, or pretending to be someone else to evade enforcement actions.
41
+ 2. **Failing to credit sources.** Not properly crediting the sources of content you contribute.
42
+ 3. **Promotional materials**. Sharing marketing or other commercial content in a way that is outside the norms of the community.
43
+ 4. **Irresponsible communication.** Failing to responsibly present content which includes, links or describes any other restricted behaviors.
44
+
45
+
46
+ ## Reporting an Issue
47
+
48
+ Tensions can occur between community members even when they are trying their best to collaborate. Not every conflict represents a code of conduct violation, and this Code of Conduct reinforces encouraged behaviors and norms that can help avoid conflicts and minimize harm.
49
+
50
+ When an incident does occur, it is important to report it promptly. To report a possible violation, email samgithub@pm.me.
51
+
52
+ Community Moderators take reports of violations seriously and will make every effort to respond in a timely manner. They will investigate all reports of code of conduct violations, reviewing messages, logs, and recordings, or interviewing witnesses and other participants. Community Moderators will keep investigation and enforcement actions as transparent as possible while prioritizing safety and confidentiality. In order to honor these values, enforcement actions are carried out in private with the involved parties, but communicating to the whole community may be part of a mutually agreed upon resolution.
53
+
54
+
55
+ ## Addressing and Repairing Harm
56
+
57
+ FiveFold's Community Moderator is its maintainer, [samrusani](https://github.com/samrusani), who handles reports and applies the enforcement ladder below.
58
+
59
+ If an investigation by the Community Moderators finds that this Code of Conduct has been violated, the following enforcement ladder may be used to determine how best to repair harm, based on the incident's impact on the individuals involved and the community as a whole. Depending on the severity of a violation, lower rungs on the ladder may be skipped.
60
+
61
+ 1) Warning
62
+ 1) Event: A violation involving a single incident or series of incidents.
63
+ 2) Consequence: A private, written warning from the Community Moderators.
64
+ 3) Repair: Examples of repair include a private written apology, acknowledgement of responsibility, and seeking clarification on expectations.
65
+ 2) Temporarily Limited Activities
66
+ 1) Event: A repeated incidence of a violation that previously resulted in a warning, or the first incidence of a more serious violation.
67
+ 2) Consequence: A private, written warning with a time-limited cooldown period designed to underscore the seriousness of the situation and give the community members involved time to process the incident. The cooldown period may be limited to particular communication channels or interactions with particular community members.
68
+ 3) Repair: Examples of repair may include making an apology, using the cooldown period to reflect on actions and impact, and being thoughtful about re-entering community spaces after the period is over.
69
+ 3) Temporary Suspension
70
+ 1) Event: A pattern of repeated violation which the Community Moderators have tried to address with warnings, or a single serious violation.
71
+ 2) Consequence: A private written warning with conditions for return from suspension. In general, temporary suspensions give the person being suspended time to reflect upon their behavior and possible corrective actions.
72
+ 3) Repair: Examples of repair include respecting the spirit of the suspension, meeting the specified conditions for return, and being thoughtful about how to reintegrate with the community when the suspension is lifted.
73
+ 4) Permanent Ban
74
+ 1) Event: A pattern of repeated code of conduct violations that other steps on the ladder have failed to resolve, or a violation so serious that the Community Moderators determine there is no way to keep the community safe with this person as a member.
75
+ 2) Consequence: Access to all community spaces, tools, and communication channels is removed. In general, permanent bans should be rarely used, should have strong reasoning behind them, and should only be resorted to if working through other remedies has failed to change the behavior.
76
+ 3) Repair: There is no possible repair in cases of this severity.
77
+
78
+ This enforcement ladder is intended as a guideline. It does not limit the ability of Community Managers to use their discretion and judgment, in keeping with the best interests of our community.
79
+
80
+
81
+ ## Scope
82
+
83
+ This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public or other spaces. Examples of representing our community include using an official email address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
84
+
85
+
86
+ ## Attribution
87
+
88
+ This Code of Conduct is adapted from the Contributor Covenant, version 3.0, permanently available at [https://www.contributor-covenant.org/version/3/0/](https://www.contributor-covenant.org/version/3/0/).
89
+
90
+ Contributor Covenant is stewarded by the Organization for Ethical Source and licensed under CC BY-SA 4.0. To view a copy of this license, visit [https://creativecommons.org/licenses/by-sa/4.0/](https://creativecommons.org/licenses/by-sa/4.0/)
91
+
92
+ For answers to common questions about Contributor Covenant, see the FAQ at [https://www.contributor-covenant.org/faq](https://www.contributor-covenant.org/faq). Translations are provided at [https://www.contributor-covenant.org/translations](https://www.contributor-covenant.org/translations). Additional enforcement and community guideline resources can be found at [https://www.contributor-covenant.org/resources](https://www.contributor-covenant.org/resources). The enforcement ladder was inspired by the work of [Mozilla’s code of conduct team](https://github.com/mozilla/inclusion).
93
+
@@ -0,0 +1,45 @@
1
+ # Contributing
2
+
3
+ FiveFold is working toward its first release, v0.1. The Status section of [README.md](README.md) says what is built and what is left. To report a bug or question a design, open an issue; to review a change, comment on its pull request. To report a vulnerability, follow [SECURITY.md](SECURITY.md) instead of opening an issue.
4
+
5
+ Follow the [Code of Conduct](CODE_OF_CONDUCT.md) when taking part in the community.
6
+
7
+ ## How decisions are made
8
+
9
+ - The contracts live in `docs/spec.md`. The maintainer owns their meaning: action identity, the grant lifecycle, states and transitions, invariants, the five property definitions, tool names and return shapes, contract levels and fault IDs.
10
+ - To change any of these, open a pull request that adds a decision record in `docs/adr/`. Copy `0000-template.md`, set the status to **Proposed**, state the rule so that a test could check it, and list the alternatives you considered.
11
+ - Only the maintainer marks a record **Accepted**. Accepted records are binding, like the spec. The pull request that accepts a record also updates every document it affects.
12
+
13
+ ## Pull requests
14
+
15
+ - Run `make check` before asking for review. The Development section of README.md explains the setup.
16
+ - One change per pull request, kept small.
17
+ - Name the spec section or decision record it implements.
18
+ - List every library API you used and where you checked it: the official docs, or the installed package source with its version. If you are unsure an API exists, say so instead of guessing.
19
+ - Say what is still uncertain.
20
+ - A behaviour change includes a test that would have caught the old behaviour.
21
+ - Live model calls never run in CI.
22
+
23
+ ## Releases
24
+
25
+ Releases go to PyPI through `.github/workflows/publish.yml`, with PyPI's Trusted Publishing, so no token is stored anywhere. To release:
26
+
27
+ 1. In a pull request, set or confirm the version in `pyproject.toml`, such as `0.1.0a1`.
28
+ 2. Once it merges, publish a GitHub release whose tag is `v` plus that version, such as `v0.1.0`.
29
+ 3. The workflow checks the tag against the version, builds the sdist and the wheel, installs the wheel outside the repository and runs demo 1 from it. Only then does the publish job run, in the GitHub environment `pypi`, whose protection rules apply first.
30
+
31
+ ## Writing style
32
+
33
+ Short sentences, plain words, specific numbers with units. No em dashes. Cite papers by full title and arXiv ID, and label them as preprints. The full rules are in [CLAUDE.md](CLAUDE.md).
34
+
35
+ ## What never goes in the repository
36
+
37
+ - Secrets. Keys come from environment variables.
38
+ - Personal names, personal email addresses, local paths and machine details. GitHub noreply addresses in commit metadata, and links to other people's public work in citations, are fine.
39
+ - Held-out evaluation scenarios. They live outside this repository.
40
+
41
+ CI checks that every commit in a pull request uses a GitHub noreply address as author and committer.
42
+
43
+ ## License
44
+
45
+ FiveFold is licensed under the Apache License 2.0. By contributing, you agree that your contributions are licensed under the same terms.
@@ -0,0 +1,23 @@
1
+ # The app image (0007): Python 3.12 with uv. By default it runs `make check`, which needs
2
+ # the postgres service from docker-compose.yml.
3
+ FROM python:3.12-slim
4
+
5
+ RUN apt-get update \
6
+ && apt-get install --yes --no-install-recommends make \
7
+ && rm -rf /var/lib/apt/lists/*
8
+
9
+ RUN pip install --no-cache-dir uv==0.13.8
10
+
11
+ # Use the image's Python 3.12; never download another.
12
+ ENV UV_PYTHON_DOWNLOADS=never
13
+
14
+ WORKDIR /app
15
+
16
+ # Install the locked dependencies first, so code changes reuse this layer.
17
+ COPY pyproject.toml uv.lock ./
18
+ RUN uv sync --locked --no-install-project
19
+
20
+ COPY . .
21
+ RUN uv sync --locked
22
+
23
+ CMD ["make", "check"]