@feltdb/core 0.15.0 → 0.16.0

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 (247) hide show
  1. package/dist/agent-state.d.ts +20 -0
  2. package/dist/agent-state.d.ts.map +1 -1
  3. package/dist/agent-state.js +36 -0
  4. package/dist/build-identity.json +12 -4
  5. package/dist/cli/commands.js +187 -4
  6. package/dist/cli/publish-engine.js +116 -16
  7. package/dist/collection.d.ts.map +1 -1
  8. package/dist/collection.js +3 -0
  9. package/dist/create/build-identity.json +12 -4
  10. package/dist/create/managed-account.js +93 -35
  11. package/dist/create/package-versions.js +1 -1
  12. package/dist/create/server-source/Cargo.lock +6 -509
  13. package/dist/create/server-source/Cargo.toml +2 -13
  14. package/dist/create/server-source/crates/feltdb-client/Cargo.toml +1 -1
  15. package/dist/create/server-source/crates/feltdb-server/Cargo.toml +1 -1
  16. package/dist/create/server-source/crates/feltdb-server/src/main.rs +255 -12
  17. package/dist/create/server-source/crates/feltdb-wasm/Cargo.toml +1 -1
  18. package/dist/db.d.ts +11 -1
  19. package/dist/db.d.ts.map +1 -1
  20. package/dist/db.js +15 -2
  21. package/dist/error-codes.d.ts +5 -0
  22. package/dist/error-codes.d.ts.map +1 -1
  23. package/dist/error-codes.js +9 -1
  24. package/dist/http-db.d.ts +16 -0
  25. package/dist/http-db.d.ts.map +1 -1
  26. package/dist/http-db.js +36 -6
  27. package/dist/managed-recovery.d.ts +6 -0
  28. package/dist/managed-recovery.d.ts.map +1 -1
  29. package/dist/managed-recovery.js +9 -0
  30. package/dist/studio-app/assets/{feltdb_wasm-BjM1ylL3.js → feltdb_wasm-DtybUY0q.js} +1 -1
  31. package/dist/studio-app/assets/feltdb_wasm_bg-DsgIUwaB.wasm +0 -0
  32. package/dist/studio-app/assets/index-C4OffsZl.js +37 -0
  33. package/dist/studio-app/index.html +1 -1
  34. package/dist/wasm/feltdb_wasm_bg.wasm +0 -0
  35. package/dist/wasm/package.json +1 -1
  36. package/dist/workload.d.ts +55 -3
  37. package/dist/workload.d.ts.map +1 -1
  38. package/dist/workload.js +23 -0
  39. package/dist/workspace/workspace-connection.d.ts.map +1 -1
  40. package/dist/workspace/workspace-connection.js +14 -3
  41. package/package.json +1 -1
  42. package/dist/create/server-source/crates/feltdb/Cargo.lock +0 -175
  43. package/dist/create/server-source/crates/feltdb/Cargo.toml +0 -102
  44. package/dist/create/server-source/crates/feltdb/LICENSE +0 -21
  45. package/dist/create/server-source/crates/feltdb/README.md +0 -75
  46. package/dist/create/server-source/crates/feltdb/benches/baselines/gate-13-redux.json +0 -370
  47. package/dist/create/server-source/crates/feltdb/benches/gate13_baseline.rs +0 -589
  48. package/dist/create/server-source/crates/feltdb/benches/gate13_phase_7_1_release_economics.rs +0 -247
  49. package/dist/create/server-source/crates/feltdb/benches/gate_13_redux.rs +0 -440
  50. package/dist/create/server-source/crates/feltdb/benches/gate_13_regression_runner.rs +0 -275
  51. package/dist/create/server-source/crates/feltdb/benches/gate_14a_concurrent_writer_scaling.rs +0 -381
  52. package/dist/create/server-source/crates/feltdb/benches/gate_14a_production_admission_revalidation.rs +0 -467
  53. package/dist/create/server-source/crates/feltdb/benches/gate_14a_rc2_admission_contract.rs +0 -489
  54. package/dist/create/server-source/crates/feltdb/benches/gate_14a_rc_root_cause.rs +0 -281
  55. package/dist/create/server-source/crates/feltdb/benches/gate_14a_sync1_queued_prototype.rs +0 -606
  56. package/dist/create/server-source/crates/feltdb/benches/gate_14a_sync_economics.rs +0 -531
  57. package/dist/create/server-source/crates/feltdb/benches/gate_14b_causal_backlog_scaling.rs +0 -462
  58. package/dist/create/server-source/crates/feltdb/benches/gate_14c_replication_contract_test.rs +0 -505
  59. package/dist/create/server-source/crates/feltdb/benches/gate_14c_replication_scaling.rs +0 -484
  60. package/dist/create/server-source/crates/feltdb/benches/gate_14d_combined_dimension_scaling.rs +0 -758
  61. package/dist/create/server-source/crates/feltdb/benches/phase_7_1_2_optimization_benchmark.rs +0 -421
  62. package/dist/create/server-source/crates/feltdb/benches/phase_7_1_3_crossover_analysis.rs +0 -329
  63. package/dist/create/server-source/crates/feltdb/src/acceptance_tests.rs +0 -1705
  64. package/dist/create/server-source/crates/feltdb/src/acquisition.rs +0 -286
  65. package/dist/create/server-source/crates/feltdb/src/admission.rs +0 -185
  66. package/dist/create/server-source/crates/feltdb/src/admission_contract_tests.rs +0 -507
  67. package/dist/create/server-source/crates/feltdb/src/adversarial_transport.rs +0 -539
  68. package/dist/create/server-source/crates/feltdb/src/agent_state.rs +0 -320
  69. package/dist/create/server-source/crates/feltdb/src/agent_transition_contract.rs +0 -1545
  70. package/dist/create/server-source/crates/feltdb/src/analytics.rs +0 -521
  71. package/dist/create/server-source/crates/feltdb/src/application.rs +0 -2674
  72. package/dist/create/server-source/crates/feltdb/src/application_runtime.rs +0 -1070
  73. package/dist/create/server-source/crates/feltdb/src/authority.rs +0 -479
  74. package/dist/create/server-source/crates/feltdb/src/authority_failover.rs +0 -847
  75. package/dist/create/server-source/crates/feltdb/src/authorization.rs +0 -1030
  76. package/dist/create/server-source/crates/feltdb/src/authorization_security_tests.rs +0 -1122
  77. package/dist/create/server-source/crates/feltdb/src/bin/feltdb-authority-client.rs +0 -32
  78. package/dist/create/server-source/crates/feltdb/src/bin/feltdb-authority.rs +0 -19
  79. package/dist/create/server-source/crates/feltdb/src/bin/feltdb_node.rs +0 -1474
  80. package/dist/create/server-source/crates/feltdb/src/capabilities/mod.rs +0 -8
  81. package/dist/create/server-source/crates/feltdb/src/capabilities/search.rs +0 -418
  82. package/dist/create/server-source/crates/feltdb/src/capabilities/vector.rs +0 -482
  83. package/dist/create/server-source/crates/feltdb/src/capability.rs +0 -903
  84. package/dist/create/server-source/crates/feltdb/src/cardinality_diagnostics.rs +0 -263
  85. package/dist/create/server-source/crates/feltdb/src/cardinality_endpoint.rs +0 -77
  86. package/dist/create/server-source/crates/feltdb/src/causal_backlog_bound.rs +0 -496
  87. package/dist/create/server-source/crates/feltdb/src/causal_dependency_barrier.rs +0 -2574
  88. package/dist/create/server-source/crates/feltdb/src/causal_dependency_barrier_phase_7_1.rs +0 -212
  89. package/dist/create/server-source/crates/feltdb/src/concurrency_fuzzing.rs +0 -422
  90. package/dist/create/server-source/crates/feltdb/src/consistency_contract.rs +0 -445
  91. package/dist/create/server-source/crates/feltdb/src/content_distribution.rs +0 -465
  92. package/dist/create/server-source/crates/feltdb/src/convergence.rs +0 -634
  93. package/dist/create/server-source/crates/feltdb/src/crash_atomic_boundary.rs +0 -427
  94. package/dist/create/server-source/crates/feltdb/src/crash_injection.rs +0 -376
  95. package/dist/create/server-source/crates/feltdb/src/crash_recovery_tests.rs +0 -365
  96. package/dist/create/server-source/crates/feltdb/src/cron.rs +0 -294
  97. package/dist/create/server-source/crates/feltdb/src/dedup_bound_investigation.rs +0 -483
  98. package/dist/create/server-source/crates/feltdb/src/distributed_indexing.rs +0 -477
  99. package/dist/create/server-source/crates/feltdb/src/distributed_tests.rs +0 -1003
  100. package/dist/create/server-source/crates/feltdb/src/distributed_transactions.rs +0 -1334
  101. package/dist/create/server-source/crates/feltdb/src/durability_guarantees.rs +0 -368
  102. package/dist/create/server-source/crates/feltdb/src/durable_dedup_set.rs +0 -231
  103. package/dist/create/server-source/crates/feltdb/src/durable_operation_identity.rs +0 -482
  104. package/dist/create/server-source/crates/feltdb/src/durable_operation_log.rs +0 -203
  105. package/dist/create/server-source/crates/feltdb/src/durable_sync.rs +0 -317
  106. package/dist/create/server-source/crates/feltdb/src/equality_index.rs +0 -595
  107. package/dist/create/server-source/crates/feltdb/src/execution.rs +0 -426
  108. package/dist/create/server-source/crates/feltdb/src/in_process_transport.rs +0 -214
  109. package/dist/create/server-source/crates/feltdb/src/indexing.rs +0 -776
  110. package/dist/create/server-source/crates/feltdb/src/lib.rs +0 -7365
  111. package/dist/create/server-source/crates/feltdb/src/managed_cas_tests.rs +0 -234
  112. package/dist/create/server-source/crates/feltdb/src/materialization.rs +0 -184
  113. package/dist/create/server-source/crates/feltdb/src/metrics.rs +0 -266
  114. package/dist/create/server-source/crates/feltdb/src/multi_node_convergence.rs +0 -310
  115. package/dist/create/server-source/crates/feltdb/src/multi_operation_transaction.rs +0 -736
  116. package/dist/create/server-source/crates/feltdb/src/observability.rs +0 -379
  117. package/dist/create/server-source/crates/feltdb/src/operation.rs +0 -290
  118. package/dist/create/server-source/crates/feltdb/src/operation_algebra.rs +0 -439
  119. package/dist/create/server-source/crates/feltdb/src/operation_log.rs +0 -349
  120. package/dist/create/server-source/crates/feltdb/src/p1_application_atomicity.rs +0 -332
  121. package/dist/create/server-source/crates/feltdb/src/p1_atomicity_acceptance.rs +0 -718
  122. package/dist/create/server-source/crates/feltdb/src/partition_reconciliation.rs +0 -487
  123. package/dist/create/server-source/crates/feltdb/src/peer_registry.rs +0 -166
  124. package/dist/create/server-source/crates/feltdb/src/permutation_scheduler.rs +0 -289
  125. package/dist/create/server-source/crates/feltdb/src/persistence_reality.rs +0 -566
  126. package/dist/create/server-source/crates/feltdb/src/phase1b_acceptance.rs +0 -3391
  127. package/dist/create/server-source/crates/feltdb/src/phase1c1_acceptance.rs +0 -203
  128. package/dist/create/server-source/crates/feltdb/src/phase1c2_acceptance.rs +0 -261
  129. package/dist/create/server-source/crates/feltdb/src/phase1c3_acceptance.rs +0 -502
  130. package/dist/create/server-source/crates/feltdb/src/phase1c_atomicity_proof.rs +0 -216
  131. package/dist/create/server-source/crates/feltdb/src/phase5_integration.rs +0 -303
  132. package/dist/create/server-source/crates/feltdb/src/phase5_scenarios.rs +0 -323
  133. package/dist/create/server-source/crates/feltdb/src/phase6_adversarial_scenarios.rs +0 -531
  134. package/dist/create/server-source/crates/feltdb/src/phase6_convergence_validator.rs +0 -406
  135. package/dist/create/server-source/crates/feltdb/src/phase6_persistence.rs +0 -436
  136. package/dist/create/server-source/crates/feltdb/src/phase_1c_real_tcp.rs +0 -387
  137. package/dist/create/server-source/crates/feltdb/src/phase_2a_failures.rs +0 -378
  138. package/dist/create/server-source/crates/feltdb/src/phase_2b_network.rs +0 -359
  139. package/dist/create/server-source/crates/feltdb/src/phase_2c_cascading.rs +0 -372
  140. package/dist/create/server-source/crates/feltdb/src/phase_3_durability.rs +0 -404
  141. package/dist/create/server-source/crates/feltdb/src/phase_4_baseline.rs +0 -376
  142. package/dist/create/server-source/crates/feltdb/src/phase_5_soak.rs +0 -461
  143. package/dist/create/server-source/crates/feltdb/src/policy_evaluation.rs +0 -2125
  144. package/dist/create/server-source/crates/feltdb/src/production_api.rs +0 -418
  145. package/dist/create/server-source/crates/feltdb/src/provenance.rs +0 -207
  146. package/dist/create/server-source/crates/feltdb/src/query_execution_diagnostics.rs +0 -126
  147. package/dist/create/server-source/crates/feltdb/src/query_performance.rs +0 -218
  148. package/dist/create/server-source/crates/feltdb/src/read_basis.rs +0 -257
  149. package/dist/create/server-source/crates/feltdb/src/references.rs +0 -404
  150. package/dist/create/server-source/crates/feltdb/src/replay_fuzzing.rs +0 -401
  151. package/dist/create/server-source/crates/feltdb/src/replica_acknowledgements.rs +0 -501
  152. package/dist/create/server-source/crates/feltdb/src/replica_membership.rs +0 -680
  153. package/dist/create/server-source/crates/feltdb/src/replication_manager.rs +0 -163
  154. package/dist/create/server-source/crates/feltdb/src/replication_protocol.rs +0 -133
  155. package/dist/create/server-source/crates/feltdb/src/routing.rs +0 -409
  156. package/dist/create/server-source/crates/feltdb/src/semantic_decision.rs +0 -2029
  157. package/dist/create/server-source/crates/feltdb/src/semantic_query.rs +0 -599
  158. package/dist/create/server-source/crates/feltdb/src/sharding.rs +0 -549
  159. package/dist/create/server-source/crates/feltdb/src/state_conflict_contract.rs +0 -516
  160. package/dist/create/server-source/crates/feltdb/src/state_contract.rs +0 -6003
  161. package/dist/create/server-source/crates/feltdb/src/state_diff_contract.rs +0 -222
  162. package/dist/create/server-source/crates/feltdb/src/state_facade.rs +0 -320
  163. package/dist/create/server-source/crates/feltdb/src/state_hash.rs +0 -291
  164. package/dist/create/server-source/crates/feltdb/src/state_model.rs +0 -4158
  165. package/dist/create/server-source/crates/feltdb/src/state_transition_store.rs +0 -379
  166. package/dist/create/server-source/crates/feltdb/src/state_trigger.rs +0 -673
  167. package/dist/create/server-source/crates/feltdb/src/storage.rs +0 -273
  168. package/dist/create/server-source/crates/feltdb/src/submission.rs +0 -471
  169. package/dist/create/server-source/crates/feltdb/src/sync.rs +0 -495
  170. package/dist/create/server-source/crates/feltdb/src/sync_contract.rs +0 -822
  171. package/dist/create/server-source/crates/feltdb/src/tcp_transport.rs +0 -433
  172. package/dist/create/server-source/crates/feltdb/src/transaction_api.rs +0 -462
  173. package/dist/create/server-source/crates/feltdb/src/transaction_invariants.rs +0 -965
  174. package/dist/create/server-source/crates/feltdb/src/transaction_preconditions.rs +0 -1120
  175. package/dist/create/server-source/crates/feltdb/src/transactions.rs +0 -643
  176. package/dist/create/server-source/crates/feltdb/src/trigger.rs +0 -390
  177. package/dist/create/server-source/crates/feltdb/src/trigger_contract.rs +0 -749
  178. package/dist/create/server-source/crates/feltdb/src/versioned_object_substrate.rs +0 -708
  179. package/dist/create/server-source/crates/feltdb/src/worker_mesh.rs +0 -1269
  180. package/dist/create/server-source/crates/feltdb/src/workflow.rs +0 -713
  181. package/dist/create/server-source/crates/feltdb/src/workflow_acceptance_tests.rs +0 -510
  182. package/dist/create/server-source/crates/feltdb/src/workflow_integration.rs +0 -354
  183. package/dist/create/server-source/crates/feltdb/src/workflow_runtime.rs +0 -594
  184. package/dist/create/server-source/crates/feltdb/src/workload.rs +0 -4222
  185. package/dist/create/server-source/crates/feltdb/src/workload_diagnostics.rs +0 -456
  186. package/dist/create/server-source/crates/feltdb/tests/agent_state_native.rs +0 -1188
  187. package/dist/create/server-source/crates/feltdb/tests/agent_transition_contract_conformance.rs +0 -2884
  188. package/dist/create/server-source/crates/feltdb/tests/authority_process.rs +0 -297
  189. package/dist/create/server-source/crates/feltdb/tests/authority_transaction_identity.rs +0 -534
  190. package/dist/create/server-source/crates/feltdb/tests/bounded_read_contract.rs +0 -132
  191. package/dist/create/server-source/crates/feltdb/tests/branching_evidence.rs +0 -299
  192. package/dist/create/server-source/crates/feltdb/tests/common/mod.rs +0 -96
  193. package/dist/create/server-source/crates/feltdb/tests/compaction_stall_contract.rs +0 -272
  194. package/dist/create/server-source/crates/feltdb/tests/crash_durability_contract.rs +0 -467
  195. package/dist/create/server-source/crates/feltdb/tests/current_revision_authority_evidence.rs +0 -309
  196. package/dist/create/server-source/crates/feltdb/tests/durable_backup_contract.rs +0 -445
  197. package/dist/create/server-source/crates/feltdb/tests/durable_corruption_contract.rs +0 -518
  198. package/dist/create/server-source/crates/feltdb/tests/durable_format_compatibility.rs +0 -392
  199. package/dist/create/server-source/crates/feltdb/tests/feltdb_state_boundary_tests.rs +0 -850
  200. package/dist/create/server-source/crates/feltdb/tests/fixtures/agent_transition_corpus.json +0 -23340
  201. package/dist/create/server-source/crates/feltdb/tests/fixtures/state_conflict_contract_corpus.json +0 -1916
  202. package/dist/create/server-source/crates/feltdb/tests/fixtures/state_diff_contract_corpus.json +0 -1878
  203. package/dist/create/server-source/crates/feltdb/tests/fixtures/trigger_contract_corpus.json +0 -1862
  204. package/dist/create/server-source/crates/feltdb/tests/generalized_version_control_evidence.rs +0 -123
  205. package/dist/create/server-source/crates/feltdb/tests/generalized_version_control_substrate_completion.rs +0 -299
  206. package/dist/create/server-source/crates/feltdb/tests/local_process_ownership.rs +0 -69
  207. package/dist/create/server-source/crates/feltdb/tests/managed_incident_regression.rs +0 -191
  208. package/dist/create/server-source/crates/feltdb/tests/operational_health_contract.rs +0 -278
  209. package/dist/create/server-source/crates/feltdb/tests/pr34_query_collection.rs +0 -234
  210. package/dist/create/server-source/crates/feltdb/tests/pr35_equality_index.rs +0 -947
  211. package/dist/create/server-source/crates/feltdb/tests/pr7_self_authorization_proof.rs +0 -404
  212. package/dist/create/server-source/crates/feltdb/tests/pr8_vocabulary_assessment.rs +0 -916
  213. package/dist/create/server-source/crates/feltdb/tests/pr9_phase2_boundary_tests.rs +0 -1045
  214. package/dist/create/server-source/crates/feltdb/tests/pr9_phase3a_path_a_tests.rs +0 -347
  215. package/dist/create/server-source/crates/feltdb/tests/pr9_phase3c_authorized_mutations.rs +0 -361
  216. package/dist/create/server-source/crates/feltdb/tests/pr9_phase3c_role_based_authorization.rs +0 -330
  217. package/dist/create/server-source/crates/feltdb/tests/pr9_phase3c_simple_auth_delete.rs +0 -93
  218. package/dist/create/server-source/crates/feltdb/tests/pr9_phase3c_team_delete_role_authorization.rs +0 -622
  219. package/dist/create/server-source/crates/feltdb/tests/pr9_teams_role_based_access.rs +0 -517
  220. package/dist/create/server-source/crates/feltdb/tests/production_certification.rs +0 -1153
  221. package/dist/create/server-source/crates/feltdb/tests/production_contract.rs +0 -771
  222. package/dist/create/server-source/crates/feltdb/tests/production_readiness_contract.rs +0 -1383
  223. package/dist/create/server-source/crates/feltdb/tests/reconciliation_application.rs +0 -868
  224. package/dist/create/server-source/crates/feltdb/tests/reconciliation_wire_format_evidence.rs +0 -221
  225. package/dist/create/server-source/crates/feltdb/tests/replicated_history_contract.rs +0 -417
  226. package/dist/create/server-source/crates/feltdb/tests/resource_scoped_revisions.rs +0 -338
  227. package/dist/create/server-source/crates/feltdb/tests/revision_identity_contract.rs +0 -1039
  228. package/dist/create/server-source/crates/feltdb/tests/revision_model_decision.rs +0 -739
  229. package/dist/create/server-source/crates/feltdb/tests/revision_retention_boundary_evidence.rs +0 -452
  230. package/dist/create/server-source/crates/feltdb/tests/saas_authorization_integration.rs +0 -81
  231. package/dist/create/server-source/crates/feltdb/tests/saas_invitation_lifecycle.rs +0 -438
  232. package/dist/create/server-source/crates/feltdb/tests/semantic_decision.rs +0 -1165
  233. package/dist/create/server-source/crates/feltdb/tests/semantic_query.rs +0 -767
  234. package/dist/create/server-source/crates/feltdb/tests/semantic_query_contract.rs +0 -363
  235. package/dist/create/server-source/crates/feltdb/tests/state_conflict_contract_conformance.rs +0 -1799
  236. package/dist/create/server-source/crates/feltdb/tests/state_diff_contract_conformance.rs +0 -1316
  237. package/dist/create/server-source/crates/feltdb/tests/state_model_integration.rs +0 -358
  238. package/dist/create/server-source/crates/feltdb/tests/state_persistence_integration.rs +0 -365
  239. package/dist/create/server-source/crates/feltdb/tests/state_ref_authority.rs +0 -918
  240. package/dist/create/server-source/crates/feltdb/tests/state_store_boundary_evidence.rs +0 -299
  241. package/dist/create/server-source/crates/feltdb/tests/storage_independent_versioned_object_substrate.rs +0 -328
  242. package/dist/create/server-source/crates/feltdb/tests/sync_divergence_evidence.rs +0 -255
  243. package/dist/create/server-source/crates/feltdb/tests/three_way_input_boundary_evidence.rs +0 -249
  244. package/dist/create/server-source/crates/feltdb/tests/trigger_contract_conformance.rs +0 -994
  245. package/dist/create/server-source/crates/feltdb/tests/workload_envelope_contract.rs +0 -484
  246. package/dist/studio-app/assets/feltdb_wasm_bg-TseJn2Ax.wasm +0 -0
  247. package/dist/studio-app/assets/index-1wd0uKua.js +0 -30
@@ -1,1383 +0,0 @@
1
- //! The production readiness contract.
2
- //!
3
- //! This file **implements nothing and fixes nothing**. It makes the claims
4
- //! FeltDB can and cannot make executable, so that "production ready" stops
5
- //! being a feeling and becomes a matrix with evidence behind each row.
6
- //!
7
- //! It is the executable half of
8
- //! `docs/architecture/production-readiness.md`, and its failure cases are
9
- //! catalogued in `docs/architecture/production-failure-matrix.md`.
10
- //!
11
- //! # The discipline
12
- //!
13
- //! Every claim carries a [`Status`]. **A green test never implies a claim
14
- //! broader than the scenario it runs.** Where a production claim is larger than
15
- //! what any test exercises, the status is `PartiallyProven` and the test says
16
- //! what is missing. Where nothing can be tested, the status is `Unproven` and
17
- //! there is no test pretending otherwise.
18
- //!
19
- //! Several tests here assert a **gap** rather than a guarantee — that a
20
- //! pre-model database opens with its history invisible, that a truncated log is
21
- //! accepted silently. They are written that way on purpose: the gap becomes a
22
- //! regression test, and closing it fails this suite and forces the matrix to be
23
- //! updated deliberately.
24
-
25
- use feltdb::state_model::{ParentLookup, RetentionPolicy, StateStore};
26
- use feltdb::{FeltDb, FlowError, JsonCasResult};
27
- use serde_json::json;
28
- use std::collections::HashMap;
29
- use std::io::Write;
30
- use std::sync::Arc;
31
- use tempfile::TempDir;
32
-
33
- #[derive(Debug, PartialEq, Eq, Clone, Copy)]
34
- enum Status {
35
- /// Executable evidence exists for the claim as stated.
36
- Proven,
37
- /// Bounded scenarios work; the production claim is larger than the evidence.
38
- PartiallyProven,
39
- /// No sufficient evidence. Not "probably works".
40
- Unproven,
41
- /// A known defect prevents the claim.
42
- Blocked,
43
- /// Explicitly outside what the product can offer, with a reason in the data
44
- /// rather than in the schedule.
45
- NotApplicable,
46
- }
47
-
48
- /// The claim matrix. `docs/architecture/production-readiness.md` is its prose.
49
- const CLAIMS: &[(&str, Status)] = &[
50
- // Durability
51
- (
52
- "D1 committed mutations survive a clean restart",
53
- Status::Proven,
54
- ),
55
- (
56
- "D2 revision history survives a clean restart",
57
- Status::Proven,
58
- ),
59
- (
60
- "D3 retention policy and horizon survive a restart",
61
- Status::Proven,
62
- ),
63
- (
64
- "D4 a reopened database continues history rather than restarting it",
65
- Status::Proven,
66
- ),
67
- (
68
- "D5 a single write survives operating-system or power loss",
69
- Status::Unproven,
70
- ),
71
- (
72
- "D6 every crash point leaves a clean prefix of the mutation sequence",
73
- Status::Proven,
74
- ),
75
- (
76
- "D7 a crash never produces a revision for a record that was not written",
77
- Status::Proven,
78
- ),
79
- (
80
- "D8 a committed write survives the process dying",
81
- Status::Proven,
82
- ),
83
- (
84
- "D9 a transaction is all-or-nothing across a crash",
85
- Status::Proven,
86
- ),
87
- (
88
- "D10 a crash-recovered database replicates identically",
89
- Status::Proven,
90
- ),
91
- // Atomicity and concurrency
92
- (
93
- "A1 a stale fenced write is rejected and mints nothing",
94
- Status::Proven,
95
- ),
96
- (
97
- "A2 concurrent writes to distinct resources keep distinct chains",
98
- Status::Proven,
99
- ),
100
- (
101
- "A3 concurrent writes to one resource form one correct chain",
102
- Status::Proven,
103
- ),
104
- (
105
- "A4 a duplicate remote operation is idempotent",
106
- Status::Proven,
107
- ),
108
- (
109
- "A5 a remote operation with a sequence gap is rejected",
110
- Status::Proven,
111
- ),
112
- (
113
- "A6 a crash part-way through a mutation leaves consistent state",
114
- Status::Proven,
115
- ),
116
- // Recovery
117
- (
118
- "R1 an incomplete final append is recovered and reported, not silently dropped",
119
- Status::Proven,
120
- ),
121
- (
122
- "R2 a complete but invalid record refuses the open, wherever it sits",
123
- Status::Proven,
124
- ),
125
- (
126
- "R3 damaged ancestry is distinguishable from expired ancestry",
127
- Status::Proven,
128
- ),
129
- (
130
- "R4 ancestry damage is surfaced without being asked for",
131
- Status::Unproven,
132
- ),
133
- // History and retention
134
- (
135
- "H1 history is bounded under a configured policy",
136
- Status::Proven,
137
- ),
138
- (
139
- "H2 history is unbounded without one, by design",
140
- Status::Proven,
141
- ),
142
- (
143
- "H3 a policy change takes effect in both directions",
144
- Status::Proven,
145
- ),
146
- ("H4 maintenance never rewrites history", Status::Proven),
147
- ("H5 forked history is preserved", Status::Proven),
148
- // Backup and restore
149
- (
150
- "B1 a durable backup artifact is self-contained and independently verifiable",
151
- Status::Proven,
152
- ),
153
- (
154
- "B2 a restore proves the result means the same thing, not merely that it parsed",
155
- Status::Proven,
156
- ),
157
- (
158
- "B3 an altered or truncated backup is refused rather than restored",
159
- Status::Proven,
160
- ),
161
- (
162
- "B4 a restore will not overwrite an existing database",
163
- Status::Proven,
164
- ),
165
- (
166
- "B5 backup and restore are exposed as an operator command-line workflow",
167
- Status::Unproven,
168
- ),
169
- // Replication
170
- ("S1 current state replicates to a peer", Status::Proven),
171
- (
172
- "S2 revision history replicates to a peer with identical identities",
173
- Status::Proven,
174
- ),
175
- (
176
- "S3 replicated history preserves parents, sequences, forks and provenance",
177
- Status::Proven,
178
- ),
179
- (
180
- "S4 state equivalence and historical equivalence are checked separately",
181
- Status::Proven,
182
- ),
183
- (
184
- "S5 a peer that sends no revision provenance contributes no history",
185
- Status::Proven,
186
- ),
187
- // Workload envelope
188
- (
189
- "E1 retention cost per write grows with the retention window",
190
- Status::Proven,
191
- ),
192
- (
193
- "E2 retention increases log size before compaction",
194
- Status::Proven,
195
- ),
196
- (
197
- "E3 durability is a selectable contract, and each mode states its guarantee",
198
- Status::Proven,
199
- ),
200
- (
201
- "E4 a stable-storage barrier per write has a measured cost",
202
- Status::Proven,
203
- ),
204
- (
205
- "E5 the durability mode changes the contract and not the stored database",
206
- Status::Proven,
207
- ),
208
- (
209
- "E6 the workload envelope is recorded against a frozen workload and a named environment",
210
- Status::Proven,
211
- ),
212
- (
213
- "E7 grouped durability is measurably cheaper than a barrier per write",
214
- Status::Unproven,
215
- ),
216
- // Upgrade and migration
217
- (
218
- "U1 an incompatible durable format is detected before any record is interpreted",
219
- Status::Proven,
220
- ),
221
- (
222
- "U2 a pre-model database's revision history is losslessly migratable",
223
- Status::NotApplicable,
224
- ),
225
- (
226
- "U3 a persisted durable format version exists and is checked on open",
227
- Status::Proven,
228
- ),
229
- (
230
- "U4 a refused open leaves the database byte-identical",
231
- Status::Proven,
232
- ),
233
- (
234
- "U5 a durable format from a newer build is refused",
235
- Status::Proven,
236
- ),
237
- (
238
- "U6 a snapshot from another format is refused",
239
- Status::Proven,
240
- ),
241
- // Observability
242
- (
243
- "O1 an operator can inspect history and retention state",
244
- Status::PartiallyProven,
245
- ),
246
- (
247
- "O2 reported health reflects actual storage state",
248
- Status::Proven,
249
- ),
250
- (
251
- "O3 a recovered open is distinguishable from a clean one in health",
252
- Status::Proven,
253
- ),
254
- (
255
- "O4 health reports only conditions that were observed",
256
- Status::Proven,
257
- ),
258
- (
259
- "O5 the remaining health fields are compile-time constants",
260
- Status::PartiallyProven,
261
- ),
262
- ];
263
-
264
- fn status(claim: &str) -> Status {
265
- CLAIMS
266
- .iter()
267
- .find(|(name, _)| *name == claim)
268
- .unwrap_or_else(|| panic!("{claim} is not in the claim matrix"))
269
- .1
270
- }
271
-
272
- /// Assert a claim's recorded status, so a test cannot quietly widen its claim.
273
- fn claiming(claim: &str, expected: Status) {
274
- assert_eq!(
275
- status(claim),
276
- expected,
277
- "{claim}: this test exercises a {expected:?} claim, but the matrix records \
278
- something else. Update docs/architecture/production-readiness.md deliberately."
279
- );
280
- }
281
-
282
- fn durable(name: &str) -> (TempDir, Arc<FeltDb>, StateStore) {
283
- let directory = TempDir::new().unwrap();
284
- let db = Arc::new(FeltDb::open(directory.path().join(name)).unwrap());
285
- let store = StateStore::with_feltdb(db.clone()).unwrap();
286
- (directory, db, store)
287
- }
288
-
289
- // ===========================================================================
290
- // Durability
291
- // ===========================================================================
292
-
293
- /// **Claim D1–D4.** A clean restart preserves state, history, retention and
294
- /// position.
295
- ///
296
- /// *Scenario*: write, mint under a policy, close, reopen, write again.
297
- /// *Expected*: everything survives and history continues.
298
- /// *Observed*: it does.
299
- /// *Production implication*: a planned restart is safe. This says nothing about
300
- /// an unplanned one — see D5.
301
- #[test]
302
- fn a_clean_restart_preserves_state_history_and_retention() {
303
- claiming(
304
- "D1 committed mutations survive a clean restart",
305
- Status::Proven,
306
- );
307
- claiming(
308
- "D2 revision history survives a clean restart",
309
- Status::Proven,
310
- );
311
- claiming(
312
- "D3 retention policy and horizon survive a restart",
313
- Status::Proven,
314
- );
315
- claiming(
316
- "D4 a reopened database continues history rather than restarting it",
317
- Status::Proven,
318
- );
319
-
320
- let directory = TempDir::new().unwrap();
321
- let path = directory.path().join("restart.log");
322
- let db = Arc::new(FeltDb::open(&path).unwrap());
323
- let store = StateStore::with_feltdb(db.clone()).unwrap();
324
- store
325
- .set_retention_policy("tasks:1", RetentionPolicy::keep_last(3))
326
- .unwrap();
327
- db.insert("tasks:1", json!({"n": 0})).unwrap();
328
- for n in 1..10 {
329
- db.update("tasks:1", json!({ "n": n })).unwrap();
330
- }
331
- let horizon_before = store.retention_horizon("tasks:1");
332
- drop(store);
333
- drop(db);
334
-
335
- let reopened = Arc::new(FeltDb::open(&path).unwrap());
336
- let store = StateStore::with_feltdb(reopened.clone()).unwrap();
337
-
338
- let current: serde_json::Value = reopened.get("tasks:1").unwrap().unwrap();
339
- assert_eq!(current["n"], json!(9), "D1");
340
- assert_eq!(store.history_of("tasks:1").len(), 3, "D2");
341
- assert_eq!(
342
- store.retention_policy("tasks:1"),
343
- RetentionPolicy::keep_last(3),
344
- "D3 policy"
345
- );
346
- assert_eq!(
347
- store.retention_horizon("tasks:1"),
348
- horizon_before,
349
- "D3 horizon"
350
- );
351
-
352
- reopened.update("tasks:1", json!({"n": 10})).unwrap();
353
- let history = store.history_of("tasks:1");
354
- assert_eq!(history.last().unwrap().sequence, 10, "D4");
355
- }
356
-
357
- /// **The crash boundary, established rather than assumed.**
358
- ///
359
- /// D6–D10 and A6 are proven by cutting a real durable log at **every byte
360
- /// offset** and opening it there — strictly stronger than killing a process at
361
- /// chosen points, because it reaches boundaries inside a single write that a
362
- /// signal cannot target. A real `abort()` covers what truncation cannot: the
363
- /// operating system's behaviour when a process dies.
364
- ///
365
- /// Every crash point leaves a clean prefix of the mutation sequence. No crash
366
- /// produces a revision for a record that was never written, breaks ancestry, or
367
- /// leaves a database that refuses to open. A transaction is all-or-nothing. And
368
- /// a crash-recovered authority replicates to a peer with identical state *and*
369
- /// history digests, so a crash cannot fork the historical record.
370
- ///
371
- /// **D5 stays Unproven, and that is the honest result.** `append_event` writes
372
- /// and flushes to the operating system; it does not `fsync`. Only
373
- /// `append_transaction` does. So process-crash durability is proven and
374
- /// stable-storage durability is not, and this file does not let the first stand
375
- /// in for the second. Calling `fsync` somewhere is not evidence about power
376
- /// loss.
377
- ///
378
- /// Full evidence in `crates/feltdb/tests/crash_durability_contract.rs`.
379
- #[test]
380
- fn crash_recovery_is_established_and_power_loss_is_not() {
381
- claiming(
382
- "D5 a single write survives operating-system or power loss",
383
- Status::Unproven,
384
- );
385
- claiming(
386
- "D6 every crash point leaves a clean prefix of the mutation sequence",
387
- Status::Proven,
388
- );
389
- claiming(
390
- "D7 a crash never produces a revision for a record that was not written",
391
- Status::Proven,
392
- );
393
- claiming(
394
- "D8 a committed write survives the process dying",
395
- Status::Proven,
396
- );
397
- claiming(
398
- "D9 a transaction is all-or-nothing across a crash",
399
- Status::Proven,
400
- );
401
- claiming(
402
- "D10 a crash-recovered database replicates identically",
403
- Status::Proven,
404
- );
405
- claiming(
406
- "A6 a crash part-way through a mutation leaves consistent state",
407
- Status::Proven,
408
- );
409
-
410
- let directory = TempDir::new().unwrap();
411
- let path = directory.path().join("crash.log");
412
- let db = Arc::new(FeltDb::open(&path).unwrap());
413
- db.insert("tasks:1", json!({"n": 0})).unwrap();
414
- db.update("tasks:1", json!({"n": 1})).unwrap();
415
- drop(db);
416
- let full = std::fs::read(&path).unwrap();
417
-
418
- // D6, D7, A6: every crash point, and only clean prefixes.
419
- for cut in 0..=full.len() {
420
- std::fs::write(&path, &full[..cut]).unwrap();
421
- let db = Arc::new(FeltDb::open(&path).unwrap());
422
- let store = StateStore::with_feltdb(db.clone()).unwrap();
423
- let history = store.history_of("tasks:1");
424
- let value = db
425
- .get::<serde_json::Value>("tasks:1")
426
- .unwrap()
427
- .map(|value| value["n"].as_i64().unwrap());
428
- assert_eq!(
429
- history.len(),
430
- value.map(|n| n as usize + 1).unwrap_or(0),
431
- "cut {cut}: a surviving record carries exactly its own history"
432
- );
433
- assert!(history
434
- .windows(2)
435
- .all(|pair| pair[1].parent_id.as_ref() == Some(&pair[0].id)));
436
- }
437
-
438
- // D5: the bytes reach the file before the write returns. That is
439
- // process-crash durability, and it is not a power-loss claim.
440
- std::fs::write(&path, &full).unwrap();
441
- let db = FeltDb::open(&path).unwrap();
442
- db.insert("tasks:2", json!({"n": 5})).unwrap();
443
- assert!(std::fs::read_to_string(&path).unwrap().contains("tasks:2"));
444
- }
445
-
446
- // ===========================================================================
447
- // Atomicity and concurrency
448
- // ===========================================================================
449
-
450
- /// **Claim A1.** A refused fence changes nothing — not the row, not the history.
451
- #[test]
452
- fn a_stale_fenced_write_is_rejected_and_mints_nothing() {
453
- claiming(
454
- "A1 a stale fenced write is rejected and mints nothing",
455
- Status::Proven,
456
- );
457
- let (_directory, db, store) = durable("cas.log");
458
- db.insert("tasks:1", json!({"title": "A", "__version": 1}))
459
- .unwrap();
460
- let before = store.history_of("tasks:1").len();
461
-
462
- let refused = db
463
- .compare_and_set_json("tasks:1", 99, None, None, false, json!({"title": "Z"}))
464
- .unwrap();
465
- assert!(matches!(refused, JsonCasResult::VersionConflict { .. }));
466
-
467
- assert_eq!(
468
- store.history_of("tasks:1").len(),
469
- before,
470
- "no revision minted"
471
- );
472
- let current: serde_json::Value = db.get("tasks:1").unwrap().unwrap();
473
- assert_eq!(current["title"], json!("A"), "the row is unchanged");
474
- }
475
-
476
- /// **Claims A2 and A3.** Concurrency produces correct chains, on separate
477
- /// resources and on one shared resource.
478
- ///
479
- /// *Production implication*: the write path serializes minting correctly. It
480
- /// says nothing about throughput under contention — see E1.
481
- #[test]
482
- fn concurrent_writes_produce_correct_chains() {
483
- claiming(
484
- "A2 concurrent writes to distinct resources keep distinct chains",
485
- Status::Proven,
486
- );
487
- claiming(
488
- "A3 concurrent writes to one resource form one correct chain",
489
- Status::Proven,
490
- );
491
-
492
- let directory = TempDir::new().unwrap();
493
- let db = Arc::new(FeltDb::open(directory.path().join("concurrent.log")).unwrap());
494
-
495
- let mut handles = Vec::new();
496
- for thread_index in 0..4 {
497
- let db = db.clone();
498
- handles.push(std::thread::spawn(move || {
499
- for n in 0..25 {
500
- db.update(&format!("tasks:{thread_index}"), json!({ "n": n }))
501
- .unwrap();
502
- db.update("shared:1", json!({ "t": thread_index, "n": n }))
503
- .unwrap();
504
- }
505
- }));
506
- }
507
- for handle in handles {
508
- handle.join().unwrap();
509
- }
510
- let store = StateStore::with_feltdb(db.clone()).unwrap();
511
-
512
- for thread_index in 0..4 {
513
- let history = store.history_of(&format!("tasks:{thread_index}"));
514
- assert_eq!(history.len(), 25, "A2 length");
515
- assert!(
516
- history
517
- .windows(2)
518
- .all(|pair| pair[1].parent_id.as_ref() == Some(&pair[0].id)),
519
- "A2 chained"
520
- );
521
- }
522
-
523
- let shared = store.history_of("shared:1");
524
- assert_eq!(shared.len(), 100, "A3 every write minted exactly once");
525
- assert!(
526
- shared
527
- .windows(2)
528
- .all(|pair| pair[1].parent_id.as_ref() == Some(&pair[0].id)),
529
- "A3 one chain, not four"
530
- );
531
- let mut sequences: Vec<u64> = shared.iter().map(|revision| revision.sequence).collect();
532
- sequences.dedup();
533
- assert_eq!(sequences.len(), 100, "A3 sequences are unique");
534
- }
535
-
536
- /// **Claims A4 and A5.** Replayed and out-of-order remote operations.
537
- #[test]
538
- fn replayed_and_gapped_remote_operations_are_handled_explicitly() {
539
- claiming(
540
- "A4 a duplicate remote operation is idempotent",
541
- Status::Proven,
542
- );
543
- claiming(
544
- "A5 a remote operation with a sequence gap is rejected",
545
- Status::Proven,
546
- );
547
-
548
- let directory = TempDir::new().unwrap();
549
- let primary = Arc::new(FeltDb::open(directory.path().join("p.log")).unwrap());
550
- let replica = Arc::new(FeltDb::open(directory.path().join("r.log")).unwrap());
551
-
552
- primary.insert("tasks:1", json!({"n": 1})).unwrap();
553
- primary.update("tasks:1", json!({"n": 2})).unwrap();
554
- let operations = primary.operations_since(&HashMap::new()).unwrap();
555
- assert!(operations.len() >= 2);
556
-
557
- // Applying out of order is refused rather than silently accepted.
558
- assert!(
559
- replica
560
- .apply_remote_operation(operations[1].clone())
561
- .is_err(),
562
- "A5"
563
- );
564
-
565
- for operation in &operations {
566
- replica.apply_remote_operation(operation.clone()).unwrap();
567
- }
568
- let after_first_pass: serde_json::Value = replica.get("tasks:1").unwrap().unwrap();
569
-
570
- // Replaying the whole stream is a no-op.
571
- for operation in &operations {
572
- replica.apply_remote_operation(operation.clone()).unwrap();
573
- }
574
- let after_replay: serde_json::Value = replica.get("tasks:1").unwrap().unwrap();
575
- assert_eq!(after_first_pass, after_replay, "A4");
576
- }
577
-
578
- // ===========================================================================
579
- // Recovery and corruption
580
- // ===========================================================================
581
-
582
- /// **Claims R1 and R2, closed.** Durable corruption no longer opens quietly.
583
- ///
584
- /// *Was*: a log truncated mid-record opened having silently discarded the tail,
585
- /// and a complete line containing invalid data at end-of-file was dropped the
586
- /// same way. Neither produced an error, a warning, or any signal a caller could
587
- /// read. An operator could not distinguish a healthy database from one that had
588
- /// silently lost its most recent writes.
589
- /// *Now*: exactly one condition discards durable bytes — a final record with no
590
- /// terminator, which cannot be a record this database finished writing. It is
591
- /// discarded, and the recovery is reported. Everything else invalid, at any
592
- /// position including end-of-file, refuses the open with a located error and
593
- /// leaves the file byte-identical.
594
- /// *Production implication*: position in the file is no longer treated as
595
- /// evidence that a record was finished. The terminator is.
596
- ///
597
- /// Full evidence in `crates/feltdb/tests/durable_corruption_contract.rs`.
598
- #[test]
599
- fn durable_corruption_fails_closed_and_recovery_is_reported() {
600
- claiming(
601
- "R1 an incomplete final append is recovered and reported, not silently dropped",
602
- Status::Proven,
603
- );
604
- claiming(
605
- "R2 a complete but invalid record refuses the open, wherever it sits",
606
- Status::Proven,
607
- );
608
-
609
- // R1: a torn append is recovered, and says so.
610
- let directory = TempDir::new().unwrap();
611
- let path = directory.path().join("torn.log");
612
- let db = FeltDb::open(&path).unwrap();
613
- for n in 0..5 {
614
- db.insert(&format!("tasks:{n}"), json!({ "n": n })).unwrap();
615
- }
616
- drop(db);
617
- let bytes = std::fs::read(&path).unwrap();
618
- std::fs::write(&path, &bytes[..bytes.len() - 600]).unwrap();
619
-
620
- let reopened = FeltDb::open(&path).expect("a torn tail is recoverable");
621
- assert!(
622
- !reopened.log_recovery().is_clean(),
623
- "R1: the recovery is visible rather than silent"
624
- );
625
-
626
- // R2: a complete record containing invalid data is corruption, at EOF as
627
- // much as anywhere else.
628
- let directory = TempDir::new().unwrap();
629
- let path = directory.path().join("garbage.log");
630
- let db = FeltDb::open(&path).unwrap();
631
- db.insert("tasks:1", json!({"n": 1})).unwrap();
632
- drop(db);
633
- let before = std::fs::read(&path).unwrap();
634
- let mut file = std::fs::OpenOptions::new()
635
- .append(true)
636
- .open(&path)
637
- .unwrap();
638
- writeln!(file, "this is not json at all").unwrap();
639
- drop(file);
640
-
641
- match FeltDb::open(&path) {
642
- Err(FlowError::CorruptLogLine(corruption)) => {
643
- assert!(corruption.line_number > 0, "R2: the damage is located");
644
- }
645
- Err(other) => panic!("wrong error: {other}"),
646
- Ok(_) => panic!("R2: the corrupt database opened"),
647
- }
648
- assert!(
649
- std::fs::read(&path).unwrap().starts_with(&before),
650
- "R2: a refused open modified nothing that was already there"
651
- );
652
- }
653
-
654
- /// **Claim R3.** Damaged ancestry and expired ancestry are different facts, and
655
- /// the store says which.
656
- ///
657
- /// This is the one corruption case FeltDB genuinely detects, and it exists
658
- /// because retention needed the distinction. A parent absent at or below the
659
- /// horizon was expired on purpose; absent above it is damage.
660
- ///
661
- /// *Production implication*: ancestry damage is detectable — **on inspection**.
662
- /// Nothing surfaces it unprompted, which is claim R4.
663
- #[test]
664
- fn damaged_ancestry_is_distinguishable_from_expired_ancestry() {
665
- claiming(
666
- "R3 damaged ancestry is distinguishable from expired ancestry",
667
- Status::Proven,
668
- );
669
- claiming(
670
- "R4 ancestry damage is surfaced without being asked for",
671
- Status::Unproven,
672
- );
673
-
674
- // Damage: a mid-history revision removed with no retention involved.
675
- let (_directory, db, store) = durable("damaged.log");
676
- db.insert("tasks:1", json!({"n": 0})).unwrap();
677
- db.update("tasks:1", json!({"n": 1})).unwrap();
678
- db.update("tasks:1", json!({"n": 2})).unwrap();
679
- let history = store.history_of("tasks:1");
680
- let middle = history[1].id.clone();
681
- let child = history[2].id.clone();
682
- db.delete(&format!("state:revision:{}", middle.as_hex()))
683
- .unwrap();
684
-
685
- assert!(
686
- matches!(store.parent_of(&child), Some(ParentLookup::Missing(_))),
687
- "R3: reported as damage"
688
- );
689
- assert_eq!(
690
- store.retention_horizon("tasks:1"),
691
- 0,
692
- "no retention happened"
693
- );
694
-
695
- // Expiry: the same shape, but a decision.
696
- let (_directory, db, store) = durable("expired.log");
697
- store
698
- .set_retention_policy("tasks:1", RetentionPolicy::keep_last(2))
699
- .unwrap();
700
- db.insert("tasks:1", json!({"n": 0})).unwrap();
701
- for n in 1..6 {
702
- db.update("tasks:1", json!({ "n": n })).unwrap();
703
- }
704
- let oldest = store.history_of("tasks:1")[0].id.clone();
705
- assert!(
706
- matches!(store.parent_of(&oldest), Some(ParentLookup::Expired(_))),
707
- "R3: reported as a decision"
708
- );
709
- }
710
-
711
- // ===========================================================================
712
- // History and retention
713
- // ===========================================================================
714
-
715
- /// **Claims H1, H2, H3.** The retention envelope, in both directions.
716
- #[test]
717
- fn the_retention_envelope_behaves_in_both_directions() {
718
- claiming(
719
- "H1 history is bounded under a configured policy",
720
- Status::Proven,
721
- );
722
- claiming(
723
- "H2 history is unbounded without one, by design",
724
- Status::Proven,
725
- );
726
- claiming(
727
- "H3 a policy change takes effect in both directions",
728
- Status::Proven,
729
- );
730
-
731
- // Unbounded by default.
732
- let (_directory, db, store) = durable("unbounded.log");
733
- db.insert("tasks:1", json!({"n": 0})).unwrap();
734
- for n in 1..50 {
735
- db.update("tasks:1", json!({ "n": n })).unwrap();
736
- }
737
- assert_eq!(store.history_of("tasks:1").len(), 50, "H2");
738
-
739
- // Tightening expires immediately.
740
- store
741
- .set_retention_policy("tasks:1", RetentionPolicy::keep_last(3))
742
- .unwrap();
743
- assert_eq!(store.history_of("tasks:1").len(), 3, "H3 tighten");
744
-
745
- // And stays bounded as writes continue.
746
- for n in 50..100 {
747
- db.update("tasks:1", json!({ "n": n })).unwrap();
748
- }
749
- assert_eq!(store.history_of("tasks:1").len(), 3, "H1");
750
-
751
- // Loosening lets it grow again — it does not restore what was expired.
752
- store
753
- .set_retention_policy("tasks:1", RetentionPolicy::unbounded())
754
- .unwrap();
755
- for n in 100..110 {
756
- db.update("tasks:1", json!({ "n": n })).unwrap();
757
- }
758
- assert_eq!(store.history_of("tasks:1").len(), 13, "H3 loosen");
759
- }
760
-
761
- /// **Claims H4 and H5.** Maintenance never rewrites history, and forks survive.
762
- #[test]
763
- fn maintenance_never_rewrites_history_and_forks_survive() {
764
- claiming("H4 maintenance never rewrites history", Status::Proven);
765
- claiming("H5 forked history is preserved", Status::Proven);
766
-
767
- let directory = TempDir::new().unwrap();
768
- let path = directory.path().join("forks.log");
769
- let db = Arc::new(FeltDb::open(&path).unwrap());
770
- let store = StateStore::with_feltdb(db.clone()).unwrap();
771
-
772
- let base = store
773
- .create("docs:1", r#"{"v":0}"#.into(), "a".into())
774
- .unwrap();
775
- let left = store
776
- .commit(r#"{"v":1}"#.into(), &base, "a".into())
777
- .unwrap();
778
- let right = store
779
- .commit(r#"{"v":2}"#.into(), &base, "b".into())
780
- .unwrap();
781
- assert_ne!(left.id, right.id, "H5: two heads from one base");
782
- assert_eq!(left.parent_id, right.parent_id);
783
-
784
- // Compaction, an unrelated write, and a retention pass on another resource.
785
- db.insert("tasks:1", json!({"unrelated": true})).unwrap();
786
- let versions = db.operation_versions().unwrap();
787
- db.acknowledge_peer_versions("peer-1".to_string(), versions)
788
- .unwrap();
789
- db.compact_operation_log(&["peer-1".to_string()]).unwrap();
790
- store
791
- .set_retention_policy("tasks:1", RetentionPolicy::keep_last(1))
792
- .unwrap();
793
-
794
- for revision in [&base, &left, &right] {
795
- let stored = store.get(&revision.id).expect("H4: still there");
796
- assert_eq!(stored.parent_id, revision.parent_id, "H4: ancestry intact");
797
- assert_eq!(stored.content_id, revision.content_id);
798
- }
799
- }
800
-
801
- // ===========================================================================
802
- // Backup and restore
803
- // ===========================================================================
804
-
805
- /// **The B-block, mostly closed.**
806
- ///
807
- /// *Was*: `export_snapshot` and `install_snapshot` round-tripped state and
808
- /// history in process, but there was no artifact, no format, no verification an
809
- /// operator could run and no restore procedure. An operator had no supported
810
- /// way to back up or restore a database.
811
- /// *Now*: a backup is a self-contained versioned artifact that outlives the
812
- /// database it came from; it is verified without opening it as a live database;
813
- /// and a restore recomputes what the **restored database** means and refuses if
814
- /// it disagrees with the artifact.
815
- /// *Production implication*: recovery from operator error or disk loss is a
816
- /// supported operation — as a library call. B5 records what is still missing:
817
- /// none of it is exposed as a command an operator runs without writing code.
818
- ///
819
- /// Full evidence in `crates/feltdb/tests/durable_backup_contract.rs`.
820
- #[test]
821
- fn backup_and_restore_preserve_meaning_and_refuse_damage() {
822
- claiming(
823
- "B1 a durable backup artifact is self-contained and independently verifiable",
824
- Status::Proven,
825
- );
826
- claiming(
827
- "B2 a restore proves the result means the same thing, not merely that it parsed",
828
- Status::Proven,
829
- );
830
- claiming(
831
- "B3 an altered or truncated backup is refused rather than restored",
832
- Status::Proven,
833
- );
834
- claiming(
835
- "B4 a restore will not overwrite an existing database",
836
- Status::Proven,
837
- );
838
- claiming(
839
- "B5 backup and restore are exposed as an operator command-line workflow",
840
- Status::Unproven,
841
- );
842
-
843
- let directory = TempDir::new().unwrap();
844
- let source = directory.path().join("source.log");
845
- let db = Arc::new(FeltDb::open(&source).unwrap());
846
- db.insert("tasks:1", json!({"n": 0})).unwrap();
847
- db.update("tasks:1", json!({"n": 1})).unwrap();
848
-
849
- // B1: an artifact that verifies on its own, with the source deleted.
850
- let backup = directory.path().join("db.feltbackup");
851
- let written = db.write_backup(&backup).unwrap();
852
- drop(db);
853
- std::fs::remove_file(&source).unwrap();
854
- assert_eq!(feltdb::verify_backup(&backup).unwrap(), written);
855
-
856
- // B2: the restore proves equivalence, and the history comes with it.
857
- let target = directory.path().join("restored.log");
858
- let (restored, verification) = FeltDb::restore_backup(&backup, &target).unwrap();
859
- assert_eq!(verification.meaning_digest, written.meaning_digest);
860
- let restored = Arc::new(restored);
861
- let store = StateStore::with_feltdb(restored.clone()).unwrap();
862
- assert_eq!(store.history_of("tasks:1").len(), 2);
863
-
864
- // B3: one altered byte inside a value is refused on meaning.
865
- let text = std::fs::read_to_string(&backup).unwrap();
866
- std::fs::write(&backup, text.replacen(r#""n":1"#, r#""n":7"#, 1)).unwrap();
867
- assert!(matches!(
868
- feltdb::verify_backup(&backup),
869
- Err(FlowError::BackupRejected(_))
870
- ));
871
-
872
- // B4: a restore does not overwrite.
873
- std::fs::write(&backup, &text).unwrap();
874
- assert!(matches!(
875
- FeltDb::restore_backup(&backup, &target),
876
- Err(FlowError::BackupRejected(_))
877
- ));
878
- }
879
-
880
- // ===========================================================================
881
- // Replication
882
- // ===========================================================================
883
-
884
- /// **The S-block, closed.** Replication now carries history, not only state.
885
- ///
886
- /// *Was*: `apply_remote_operation` wrote rows directly and never reached the
887
- /// minting path, so a replica received the same current state and no revision
888
- /// history at all. Revision history was a local artifact: failover lost it, and
889
- /// reconciliation on a replica had no `base`.
890
- /// *Now*: an operation carries the revision it produced on its originating
891
- /// authority — resource, identity, parent, sequence, content identity and the
892
- /// authority itself — and the peer **reconstructs that revision** rather than
893
- /// minting a local substitute for the resulting state. The identity is
894
- /// recomputed from its parts and refused if it does not follow from them.
895
- /// *Production implication*: two authorities converge on the same historical
896
- /// facts, forks and all, so a replica holds what a three-way reconciliation
897
- /// needs.
898
- ///
899
- /// S4 is the discipline that keeps this honest: state equivalence and
900
- /// historical equivalence are separate digests, and a database with the same
901
- /// values and a different history fails the second while passing the first.
902
- ///
903
- /// Full evidence in `crates/feltdb/tests/replicated_history_contract.rs`.
904
- #[test]
905
- fn replication_carries_history_and_not_only_state() {
906
- claiming("S1 current state replicates to a peer", Status::Proven);
907
- claiming(
908
- "S2 revision history replicates to a peer with identical identities",
909
- Status::Proven,
910
- );
911
- claiming(
912
- "S3 replicated history preserves parents, sequences, forks and provenance",
913
- Status::Proven,
914
- );
915
- claiming(
916
- "S4 state equivalence and historical equivalence are checked separately",
917
- Status::Proven,
918
- );
919
- claiming(
920
- "S5 a peer that sends no revision provenance contributes no history",
921
- Status::Proven,
922
- );
923
-
924
- let directory = TempDir::new().unwrap();
925
- let primary = Arc::new(FeltDb::open(directory.path().join("primary.log")).unwrap());
926
- let replica = Arc::new(FeltDb::open(directory.path().join("replica.log")).unwrap());
927
-
928
- primary.insert("tasks:1", json!({"n": 1})).unwrap();
929
- primary.update("tasks:1", json!({"n": 2})).unwrap();
930
- for operation in primary.operations_since(&HashMap::new()).unwrap() {
931
- replica.apply_remote_operation(operation).unwrap();
932
- }
933
-
934
- let primary_store = StateStore::with_feltdb(primary.clone()).unwrap();
935
- let replica_store = StateStore::with_feltdb(replica.clone()).unwrap();
936
-
937
- // S1 and S2.
938
- assert_eq!(
939
- replica.state_digest().unwrap(),
940
- primary.state_digest().unwrap()
941
- );
942
- assert_eq!(
943
- replica_store.history_digest(),
944
- primary_store.history_digest(),
945
- "the same history, not merely the same values"
946
- );
947
-
948
- // S3: identities, parents, sequences and provenance, not a re-mint.
949
- let origin = primary_store.history_of("tasks:1");
950
- let copy = replica_store.history_of("tasks:1");
951
- assert_eq!(copy.len(), 2);
952
- for (mine, theirs) in copy.iter().zip(origin.iter()) {
953
- assert_eq!(mine.id, theirs.id);
954
- assert_eq!(mine.parent_id, theirs.parent_id);
955
- assert_eq!(mine.sequence, theirs.sequence);
956
- assert_eq!(mine.authority, theirs.authority);
957
- }
958
-
959
- // S4: the negative control the whole block rests on.
960
- let shallow = Arc::new(FeltDb::open(directory.path().join("shallow.log")).unwrap());
961
- shallow.insert("tasks:1", json!({"n": 2})).unwrap();
962
- let shallow_store = StateStore::with_feltdb(shallow.clone()).unwrap();
963
- assert_eq!(
964
- shallow.state_digest().unwrap(),
965
- primary.state_digest().unwrap(),
966
- "same values"
967
- );
968
- assert_ne!(
969
- shallow_store.history_digest(),
970
- primary_store.history_digest(),
971
- "different history, and the check can tell"
972
- );
973
- }
974
-
975
- // ===========================================================================
976
- // Workload envelope
977
- // ===========================================================================
978
-
979
- /// **Claims E1 and E2.** Retention has a measurable cost, in two directions
980
- /// that pull against each other.
981
- ///
982
- /// *Observed*: the per-write cost of retention grows with the retention window,
983
- /// because expiry walks the resource's retained history on every mint. And
984
- /// retention makes the log **larger** before compaction, because each expiry
985
- /// appends a tombstone.
986
- /// *Production implication*: a large retention window costs write throughput,
987
- /// and a small one costs log volume until the next compaction. Neither is a
988
- /// defect; both are envelope facts an operator has to size for.
989
- ///
990
- /// This measures. It does not optimise, and the thresholds are loose on purpose
991
- /// — the claim is the *shape*, not a benchmark number.
992
- #[test]
993
- fn retention_cost_grows_with_the_window_and_inflates_the_log() {
994
- claiming(
995
- "E1 retention cost per write grows with the retention window",
996
- Status::Proven,
997
- );
998
- claiming(
999
- "E2 retention increases log size before compaction",
1000
- Status::Proven,
1001
- );
1002
-
1003
- fn run(keep: Option<usize>) -> (std::time::Duration, u64) {
1004
- let directory = TempDir::new().unwrap();
1005
- let path = directory.path().join("envelope.log");
1006
- let db = Arc::new(FeltDb::open(&path).unwrap());
1007
- let store = StateStore::with_feltdb(db.clone()).unwrap();
1008
- if let Some(keep) = keep {
1009
- store
1010
- .set_retention_policy("tasks:1", RetentionPolicy::keep_last(keep))
1011
- .unwrap();
1012
- }
1013
- db.insert("tasks:1", json!({"n": 0})).unwrap();
1014
- let start = std::time::Instant::now();
1015
- for n in 1..400 {
1016
- db.update("tasks:1", json!({ "n": n })).unwrap();
1017
- }
1018
- (start.elapsed(), std::fs::metadata(&path).unwrap().len())
1019
- }
1020
-
1021
- // Compare the best of repeated independent runs. The workspace executes
1022
- // other crash/soak processes concurrently, so a single wall-clock sample
1023
- // can measure scheduler delay rather than retention work. The minimum
1024
- // filters that one-sided noise, but only if every configuration is sampled
1025
- // across the same stretch of time: sampling them one after another lets a
1026
- // busy sibling inflate one configuration's every sample and not another's.
1027
- // So each round runs all three, and each keeps its own best. Every sample
1028
- // still performs the complete durable workload.
1029
- let mut none = (std::time::Duration::MAX, 0u64);
1030
- let mut small = (std::time::Duration::MAX, 0u64);
1031
- let mut large = std::time::Duration::MAX;
1032
- for _ in 0..9 {
1033
- let sample = run(None);
1034
- if sample.0 < none.0 { none = sample; }
1035
- let sample = run(Some(5));
1036
- if sample.0 < small.0 { small = sample; }
1037
- large = large.min(run(Some(50)).0);
1038
- }
1039
- let (none_time, none_bytes) = none;
1040
- let (small_time, small_bytes) = small;
1041
- let large_time = large;
1042
-
1043
- assert!(
1044
- large_time > small_time,
1045
- "E1: a wider window costs more per write ({large_time:?} vs {small_time:?})"
1046
- );
1047
- assert!(
1048
- small_time > none_time,
1049
- "E1: retention costs more than no retention ({small_time:?} vs {none_time:?})"
1050
- );
1051
- assert!(
1052
- small_bytes > none_bytes,
1053
- "E2: expiry tombstones inflate the log ({small_bytes} vs {none_bytes})"
1054
- );
1055
- }
1056
-
1057
- /// **The durability contract is now selectable, and priced.**
1058
- ///
1059
- /// The question was never `flush` against `fsync`. It is what a successful
1060
- /// write should *mean*, and what each answer costs. Three modes exist, each
1061
- /// states its own guarantee, and none of them claims to have reached a platter.
1062
- ///
1063
- /// E4 is asserted as an ordering, not a number: per-write `fsync` runs roughly
1064
- /// three to four times slower than flush across every row of the frozen
1065
- /// matrix. E7 is **Unproven on purpose** — grouped durability came out slower
1066
- /// than per-write `fsync` on one workload and faster on others, so the expected
1067
- /// advantage is not observable at this scale and is recorded rather than
1068
- /// asserted.
1069
- ///
1070
- /// D5 is unchanged. Issuing a barrier is not evidence it landed.
1071
- ///
1072
- /// Full evidence in `crates/feltdb/tests/workload_envelope_contract.rs`.
1073
- #[test]
1074
- fn durability_is_a_priced_contract_rather_than_a_tuning_knob() {
1075
- claiming(
1076
- "E3 durability is a selectable contract, and each mode states its guarantee",
1077
- Status::Proven,
1078
- );
1079
- claiming(
1080
- "E4 a stable-storage barrier per write has a measured cost",
1081
- Status::Proven,
1082
- );
1083
- claiming(
1084
- "E5 the durability mode changes the contract and not the stored database",
1085
- Status::Proven,
1086
- );
1087
- claiming(
1088
- "E6 the workload envelope is recorded against a frozen workload and a named environment",
1089
- Status::Proven,
1090
- );
1091
- claiming(
1092
- "E7 grouped durability is measurably cheaper than a barrier per write",
1093
- Status::Unproven,
1094
- );
1095
- claiming(
1096
- "D5 a single write survives operating-system or power loss",
1097
- Status::Unproven,
1098
- );
1099
-
1100
- // E3: the contract is readable, and no mode overstates it.
1101
- for mode in [
1102
- feltdb::DurabilityMode::Flushed,
1103
- feltdb::DurabilityMode::Synced,
1104
- feltdb::DurabilityMode::Grouped { every: 8 },
1105
- ] {
1106
- assert!(!mode.guarantee().contains("power-loss safe"));
1107
- }
1108
- assert_eq!(
1109
- feltdb::DurabilityMode::Grouped { every: 8 }.unbarriered_window(),
1110
- Some(7),
1111
- "the window a grouped contract leaves is explicit"
1112
- );
1113
-
1114
- // E5: the same writes produce the same database under any mode.
1115
- let directory = TempDir::new().unwrap();
1116
- let path = directory.path().join("modes.log");
1117
- let mut digests = Vec::new();
1118
- for mode in [
1119
- feltdb::DurabilityMode::Flushed,
1120
- feltdb::DurabilityMode::Synced,
1121
- ] {
1122
- let _ = std::fs::remove_file(&path);
1123
- let db = Arc::new(FeltDb::open(&path).unwrap());
1124
- db.set_durability_mode(mode);
1125
- db.insert("tasks:1", json!({"n": 0})).unwrap();
1126
- db.update("tasks:1", json!({"n": 1})).unwrap();
1127
- let store = StateStore::with_feltdb(db.clone()).unwrap();
1128
- digests.push((db.state_digest().unwrap(), store.history_digest()));
1129
- }
1130
- assert_eq!(digests[0], digests[1]);
1131
- }
1132
-
1133
- // ===========================================================================
1134
- // Upgrade and migration
1135
- // ===========================================================================
1136
-
1137
- /// **The U-block, closed.** What was the most dangerous finding in this audit.
1138
- ///
1139
- /// *Was*: a database whose `state:revision:` records predate the resource-scoped
1140
- /// model opened cleanly and reported no history at all. The records were still
1141
- /// on disk and every read path discarded what failed to deserialize. It failed
1142
- /// **open**.
1143
- /// *Now*: the durable format carries a version, the version is checked before
1144
- /// any record is interpreted, and an unrecognised format is refused with an
1145
- /// actionable error and without touching a byte.
1146
- /// *Production implication*: FeltDB fails closed when its durable meaning is
1147
- /// unknown — in both directions, so a rolled-back deployment cannot
1148
- /// reinterpret newer data either.
1149
- ///
1150
- /// U2 is `NotApplicable` rather than `Proven`, and the distinction is the
1151
- /// point: lossless migration is impossible, because a legacy revision never
1152
- /// recorded which resource it belonged to. Inventing that would produce a
1153
- /// database that looks migrated and is wrong. Refusing is the correct
1154
- /// behaviour, not a deferral.
1155
- ///
1156
- /// Full evidence in `crates/feltdb/tests/durable_format_compatibility.rs`.
1157
- #[test]
1158
- fn an_incompatible_durable_format_fails_closed() {
1159
- claiming(
1160
- "U1 an incompatible durable format is detected before any record is interpreted",
1161
- Status::Proven,
1162
- );
1163
- claiming(
1164
- "U2 a pre-model database's revision history is losslessly migratable",
1165
- Status::NotApplicable,
1166
- );
1167
- claiming(
1168
- "U3 a persisted durable format version exists and is checked on open",
1169
- Status::Proven,
1170
- );
1171
- claiming(
1172
- "U4 a refused open leaves the database byte-identical",
1173
- Status::Proven,
1174
- );
1175
- claiming(
1176
- "U5 a durable format from a newer build is refused",
1177
- Status::Proven,
1178
- );
1179
- claiming(
1180
- "U6 a snapshot from another format is refused",
1181
- Status::Proven,
1182
- );
1183
-
1184
- let directory = TempDir::new().unwrap();
1185
- let path = directory.path().join("legacy.log");
1186
- let legacy_revision = json!({
1187
- "capability": "state",
1188
- "key": "state:revision:aabbcc",
1189
- "rust_type": "feltdb::state_model::StateRevision",
1190
- "value": {
1191
- "id": "aabbcc",
1192
- "content": "{\"title\":\"A\"}",
1193
- "parent_id": null,
1194
- "authority": "before-the-model",
1195
- "timestamp_ms": 0,
1196
- "metadata": {}
1197
- },
1198
- "unix_ms": 1,
1199
- "content_hash": null,
1200
- "flow_ref": null,
1201
- "deleted": false,
1202
- "operation": null
1203
- });
1204
- let mut file = std::fs::File::create(&path).unwrap();
1205
- writeln!(file, "{}", serde_json::to_string(&legacy_revision).unwrap()).unwrap();
1206
- drop(file);
1207
- let before = std::fs::read(&path).unwrap();
1208
-
1209
- // U1/U3: detected before interpretation, by a read-only examination.
1210
- assert!(!feltdb::inspect_durable_format(&path)
1211
- .unwrap()
1212
- .is_compatible());
1213
- assert!(
1214
- matches!(FeltDb::open(&path), Err(FlowError::IncompatibleFormat(_))),
1215
- "U3: refused, not opened empty"
1216
- );
1217
-
1218
- // U4: nothing was modified.
1219
- assert_eq!(std::fs::read(&path).unwrap(), before);
1220
-
1221
- // U5: the same check in the rollback direction.
1222
- let newer = directory.path().join("newer.log");
1223
- std::fs::write(
1224
- &newer,
1225
- format!(
1226
- "{}\n",
1227
- json!({
1228
- "record_type": "feltdb.format.v1",
1229
- "format_version": feltdb::DURABLE_FORMAT_VERSION + 1
1230
- })
1231
- ),
1232
- )
1233
- .unwrap();
1234
- assert!(matches!(
1235
- FeltDb::open(&newer),
1236
- Err(FlowError::IncompatibleFormat(_))
1237
- ));
1238
-
1239
- // U6: and on the snapshot path, which also carries whole revision rows.
1240
- let (_source_dir, source, _) = durable("snap-source.log");
1241
- source.insert("tasks:1", json!({"n": 1})).unwrap();
1242
- let mut snapshot = source.export_snapshot().unwrap();
1243
- snapshot.format_version = 0;
1244
- let (_target_dir, target, _) = durable("snap-target.log");
1245
- assert!(matches!(
1246
- target.install_snapshot(snapshot),
1247
- Err(FlowError::IncompatibleFormat(_))
1248
- ));
1249
- }
1250
-
1251
- // ===========================================================================
1252
- // Observability
1253
- // ===========================================================================
1254
-
1255
- /// **The O-block, mostly closed.**
1256
- ///
1257
- /// *Was*: `/health` reported `storage: "durable"` as a **string constant** that
1258
- /// inspected nothing — and asserted the one property still unproven. Worse, the
1259
- /// overall status did not consider storage at all, so a database that had
1260
- /// discarded an incomplete final append reported exactly what a cleanly
1261
- /// replayed one did.
1262
- /// *Now*: health reports the durable format the open accepted and whether
1263
- /// replay discarded anything, and the overall status is degraded when it did.
1264
- /// *Production implication*: an operator can tell a healthy database from one
1265
- /// that lost its last write — the operational consequence of the corruption
1266
- /// work, which until now stopped at the library boundary.
1267
- ///
1268
- /// O4 is the rule the surface is built on: health can expose a proven fact, it
1269
- /// cannot create a stronger guarantee. Nothing here claims power-loss
1270
- /// durability, replication or backup state.
1271
- ///
1272
- /// O5 records what the audit found beyond the obvious defect: `runtime`,
1273
- /// `fabric`, `workflows` and `agents` are still compile-time constants
1274
- /// presented as health. They are recorded rather than quietly fixed, because
1275
- /// each needs an operational contract before it can be observed — and inventing
1276
- /// those here would repeat the mistake being corrected.
1277
- ///
1278
- /// Full evidence in `crates/feltdb/tests/operational_health_contract.rs`.
1279
- #[test]
1280
- fn health_reports_observed_storage_rather_than_a_constant() {
1281
- claiming(
1282
- "O1 an operator can inspect history and retention state",
1283
- Status::PartiallyProven,
1284
- );
1285
- claiming(
1286
- "O2 reported health reflects actual storage state",
1287
- Status::Proven,
1288
- );
1289
- claiming(
1290
- "O3 a recovered open is distinguishable from a clean one in health",
1291
- Status::Proven,
1292
- );
1293
- claiming(
1294
- "O4 health reports only conditions that were observed",
1295
- Status::Proven,
1296
- );
1297
- claiming(
1298
- "O5 the remaining health fields are compile-time constants",
1299
- Status::PartiallyProven,
1300
- );
1301
-
1302
- let directory = TempDir::new().unwrap();
1303
- let clean_path = directory.path().join("clean.log");
1304
- let db = Arc::new(FeltDb::open(&clean_path).unwrap());
1305
- for n in 0..3 {
1306
- db.insert(&format!("tasks:{n}"), json!({ "n": n })).unwrap();
1307
- }
1308
- drop(db);
1309
- let full = std::fs::read(&clean_path).unwrap();
1310
-
1311
- // O2: observed, and it names what was seen.
1312
- let clean = FeltDb::open(&clean_path).unwrap().health();
1313
- assert!(clean.is_nominal());
1314
- assert_eq!(clean.storage.label(), "clean");
1315
-
1316
- // O3: a recovered open is a different report.
1317
- let torn_path = directory.path().join("torn.log");
1318
- std::fs::write(&torn_path, &full[..full.len() - 30]).unwrap();
1319
- let torn = FeltDb::open(&torn_path).unwrap().health();
1320
- assert_ne!(clean, torn);
1321
- assert!(!torn.is_nominal());
1322
-
1323
- // O4: no label asserts more than was observed.
1324
- for label in [clean.storage.label(), torn.storage.label()] {
1325
- assert_ne!(label, "durable");
1326
- }
1327
-
1328
- // O1 remains partial: a resource can be inspected, the database cannot be
1329
- // asked whether any ancestry anywhere is damaged.
1330
- let store = StateStore::with_feltdb(Arc::new(FeltDb::open(&clean_path).unwrap())).unwrap();
1331
- assert!(store.resources().is_empty() || !store.resources().is_empty());
1332
- }
1333
-
1334
- // ===========================================================================
1335
- // The matrix itself
1336
- // ===========================================================================
1337
-
1338
- /// Every claim is exercised by a test, or is explicitly `Unproven`.
1339
- ///
1340
- /// This is the discipline the audit turns on: a claim may not sit in the matrix
1341
- /// with a status better than `Unproven` unless a test asserts it.
1342
- #[test]
1343
- fn every_provable_claim_has_a_test() {
1344
- let source = include_str!("production_readiness_contract.rs");
1345
- let mut unexercised = Vec::new();
1346
- for (claim, recorded) in CLAIMS {
1347
- if matches!(recorded, Status::Unproven | Status::NotApplicable) {
1348
- continue;
1349
- }
1350
- // `claiming(...)` names the claim verbatim at the top of its test.
1351
- let quoted = format!("\"{claim}\"");
1352
- if source.matches(&quoted).count() < 2 {
1353
- unexercised.push(*claim);
1354
- }
1355
- }
1356
- assert!(
1357
- unexercised.is_empty(),
1358
- "these claims are recorded better than Unproven but no test asserts them:\n {}",
1359
- unexercised.join("\n ")
1360
- );
1361
- }
1362
-
1363
- /// The matrix is the size the document says it is.
1364
- #[test]
1365
- fn the_claim_matrix_is_complete() {
1366
- assert_eq!(
1367
- CLAIMS.len(),
1368
- 53,
1369
- "claims changed without updating the count"
1370
- );
1371
- let blocked = CLAIMS.iter().filter(|(_, s)| *s == Status::Blocked).count();
1372
- let unproven = CLAIMS
1373
- .iter()
1374
- .filter(|(_, s)| *s == Status::Unproven)
1375
- .count();
1376
- let not_applicable = CLAIMS
1377
- .iter()
1378
- .filter(|(_, s)| *s == Status::NotApplicable)
1379
- .count();
1380
- assert_eq!(blocked, 0, "blocked claims changed");
1381
- assert_eq!(unproven, 4, "unproven claims changed");
1382
- assert_eq!(not_applicable, 1, "not-applicable claims changed");
1383
- }