sandloom 0.7.0a1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (498) hide show
  1. sandloom/__init__.py +349 -0
  2. sandloom/core/AGENTS.md +120 -0
  3. sandloom/core/CLAUDE.md +1 -0
  4. sandloom/core/__init__.py +10 -0
  5. sandloom/core/_internal/__init__.py +6 -0
  6. sandloom/core/_internal/db_provider.py +53 -0
  7. sandloom/core/admin/__init__.py +5 -0
  8. sandloom/core/admin/api/__init__.py +1 -0
  9. sandloom/core/admin/api/platform.py +754 -0
  10. sandloom/core/admin/compiler.py +529 -0
  11. sandloom/core/admin/models.py +106 -0
  12. sandloom/core/app_factory.py +1135 -0
  13. sandloom/core/archcheck/__init__.py +22 -0
  14. sandloom/core/archcheck/analyzers.py +1830 -0
  15. sandloom/core/archcheck/api10_rules.py +952 -0
  16. sandloom/core/archcheck/manifest.py +286 -0
  17. sandloom/core/archcheck/module_rules.py +546 -0
  18. sandloom/core/archcheck/runner.py +685 -0
  19. sandloom/core/async_runner.py +195 -0
  20. sandloom/core/auth/__init__.py +7 -0
  21. sandloom/core/auth/bearer.py +118 -0
  22. sandloom/core/auth/blocks.py +277 -0
  23. sandloom/core/auth/hashing.py +232 -0
  24. sandloom/core/auth/marks.py +307 -0
  25. sandloom/core/auth/recovery.py +384 -0
  26. sandloom/core/auth/revocation.py +393 -0
  27. sandloom/core/auth/tokens.py +361 -0
  28. sandloom/core/auth/verification.py +238 -0
  29. sandloom/core/beat_lease.py +387 -0
  30. sandloom/core/claims.py +29 -0
  31. sandloom/core/cli/__init__.py +0 -0
  32. sandloom/core/cli/_operator.py +71 -0
  33. sandloom/core/cli/add.py +1467 -0
  34. sandloom/core/cli/admin.py +41 -0
  35. sandloom/core/cli/backup.py +265 -0
  36. sandloom/core/cli/check.py +242 -0
  37. sandloom/core/cli/config.py +283 -0
  38. sandloom/core/cli/contracts.py +231 -0
  39. sandloom/core/cli/doctor.py +627 -0
  40. sandloom/core/cli/dto_copies.py +695 -0
  41. sandloom/core/cli/events.py +320 -0
  42. sandloom/core/cli/explain.py +61 -0
  43. sandloom/core/cli/extract.py +1311 -0
  44. sandloom/core/cli/generated.py +1354 -0
  45. sandloom/core/cli/gunicorn_conf.py +319 -0
  46. sandloom/core/cli/image_secrets.py +161 -0
  47. sandloom/core/cli/keys.py +344 -0
  48. sandloom/core/cli/migrate.py +679 -0
  49. sandloom/core/cli/migrate_drift.py +156 -0
  50. sandloom/core/cli/migrate_rls.py +102 -0
  51. sandloom/core/cli/project.py +1164 -0
  52. sandloom/core/cli/projections.py +144 -0
  53. sandloom/core/cli/route_weakening.py +212 -0
  54. sandloom/core/cli/routes.py +120 -0
  55. sandloom/core/cli/run_tests.py +521 -0
  56. sandloom/core/cli/sagas.py +306 -0
  57. sandloom/core/cli/scaffold_deploy.py +969 -0
  58. sandloom/core/cli/scaffold_wiring.py +183 -0
  59. sandloom/core/cli/security.py +408 -0
  60. sandloom/core/cli/skills.py +62 -0
  61. sandloom/core/cli/templates/api-cheatsheet.md +54 -0
  62. sandloom/core/cli/templates/deploy/compose/microservices.yml.tmpl +311 -0
  63. sandloom/core/cli/templates/deploy/gateway/nginx.conf +71 -0
  64. sandloom/core/cli/templates/deploy/postgres/init-databases.sh +26 -0
  65. sandloom/core/cli/templates/module-AGENTS.md +120 -0
  66. sandloom/core/cli/templates/skills/sandloom-event-version-roll/SKILL.md +55 -0
  67. sandloom/core/cli/templates/skills/sandloom-new-module/SKILL.md +57 -0
  68. sandloom/core/cli/templates/skills/sandloom-quality-gates/SKILL.md +52 -0
  69. sandloom/core/cli/templates/skills/sandloom-split-deploy/SKILL.md +50 -0
  70. sandloom/core/cli/tool_process.py +36 -0
  71. sandloom/core/composition.py +95 -0
  72. sandloom/core/config/__init__.py +7 -0
  73. sandloom/core/config/accepted_risks.py +189 -0
  74. sandloom/core/config/auth.py +141 -0
  75. sandloom/core/config/cache.py +40 -0
  76. sandloom/core/config/common.py +118 -0
  77. sandloom/core/config/contracts.py +147 -0
  78. sandloom/core/config/database.py +123 -0
  79. sandloom/core/config/eventing.py +172 -0
  80. sandloom/core/config/http.py +73 -0
  81. sandloom/core/config/infra.py +20 -0
  82. sandloom/core/config/modules.py +81 -0
  83. sandloom/core/config/observability.py +30 -0
  84. sandloom/core/config/password_params.py +120 -0
  85. sandloom/core/config/replay_limits.py +28 -0
  86. sandloom/core/config/rpc.py +94 -0
  87. sandloom/core/config/runtime.py +136 -0
  88. sandloom/core/config/sagas.py +40 -0
  89. sandloom/core/config/services.py +50 -0
  90. sandloom/core/config/settings.py +775 -0
  91. sandloom/core/config/tiers.py +982 -0
  92. sandloom/core/config/trust.py +76 -0
  93. sandloom/core/consumers/__init__.py +7 -0
  94. sandloom/core/consumers/callbacks.py +424 -0
  95. sandloom/core/consumers/runtime.py +636 -0
  96. sandloom/core/contract_cache_shadow.py +953 -0
  97. sandloom/core/contract_compat.py +684 -0
  98. sandloom/core/contract_context.py +71 -0
  99. sandloom/core/contract_testing.py +488 -0
  100. sandloom/core/contract_wire.py +847 -0
  101. sandloom/core/contracts/__init__.py +43 -0
  102. sandloom/core/contracts/payload_validation.py +168 -0
  103. sandloom/core/contracts/schema_registry.py +114 -0
  104. sandloom/core/contracts/uow.py +56 -0
  105. sandloom/core/contracts/validators.py +255 -0
  106. sandloom/core/cpu_quota.py +66 -0
  107. sandloom/core/descriptors/__init__.py +318 -0
  108. sandloom/core/descriptors/contract_refs.py +80 -0
  109. sandloom/core/descriptors/module_names.py +164 -0
  110. sandloom/core/descriptors/sagas.py +695 -0
  111. sandloom/core/di.py +994 -0
  112. sandloom/core/drivers/__init__.py +0 -0
  113. sandloom/core/drivers/bootstrap.py +221 -0
  114. sandloom/core/drivers/celery_taskqueue.py +242 -0
  115. sandloom/core/drivers/event_bus_driver.py +241 -0
  116. sandloom/core/drivers/filesystem_storage.py +155 -0
  117. sandloom/core/drivers/linger_pool.py +358 -0
  118. sandloom/core/drivers/local_objectstore.py +221 -0
  119. sandloom/core/drivers/log_notifier.py +107 -0
  120. sandloom/core/drivers/memory_document_store.py +123 -0
  121. sandloom/core/drivers/redis_cache.py +836 -0
  122. sandloom/core/drivers/smtp_notifier.py +128 -0
  123. sandloom/core/drivers/sqlalchemy_database.py +913 -0
  124. sandloom/core/drivers/system_db.py +160 -0
  125. sandloom/core/effects.py +286 -0
  126. sandloom/core/error_codes.py +1350 -0
  127. sandloom/core/eventing/__init__.py +0 -0
  128. sandloom/core/eventing/bus_base.py +346 -0
  129. sandloom/core/eventing/bus_metrics.py +49 -0
  130. sandloom/core/eventing/consumer_inbox.py +107 -0
  131. sandloom/core/eventing/core_events.py +116 -0
  132. sandloom/core/eventing/delivery.py +79 -0
  133. sandloom/core/eventing/envelope.py +132 -0
  134. sandloom/core/eventing/event_bus.py +63 -0
  135. sandloom/core/eventing/memory_bus.py +250 -0
  136. sandloom/core/eventing/memory_transport.py +355 -0
  137. sandloom/core/eventing/origin.py +41 -0
  138. sandloom/core/eventing/pubsub_bus.py +429 -0
  139. sandloom/core/eventing/streams_bus.py +477 -0
  140. sandloom/core/eventing/streams_consume.py +628 -0
  141. sandloom/core/eventing/streams_dispatch.py +325 -0
  142. sandloom/core/eventing/streams_groups.py +398 -0
  143. sandloom/core/eventing/streams_inventory.py +207 -0
  144. sandloom/core/eventing/streams_lease.py +100 -0
  145. sandloom/core/eventing/streams_transport.py +264 -0
  146. sandloom/core/eventing/streams_transport_base.py +185 -0
  147. sandloom/core/eventing/subscriptions.py +142 -0
  148. sandloom/core/eventing/transport_base.py +355 -0
  149. sandloom/core/eventing/transport_capabilities.py +122 -0
  150. sandloom/core/exceptions.py +57 -0
  151. sandloom/core/facade/__init__.py +313 -0
  152. sandloom/core/facade/_claims.py +476 -0
  153. sandloom/core/facade/_registries.py +365 -0
  154. sandloom/core/facade/_runtime.py +118 -0
  155. sandloom/core/facade/_services.py +294 -0
  156. sandloom/core/facade/_state.py +173 -0
  157. sandloom/core/gc_tuning.py +279 -0
  158. sandloom/core/guarantee_lattice.py +218 -0
  159. sandloom/core/guarantee_windows.py +256 -0
  160. sandloom/core/guard_order.py +293 -0
  161. sandloom/core/http/__init__.py +0 -0
  162. sandloom/core/http/error_handlers.py +302 -0
  163. sandloom/core/http/middlewares.py +597 -0
  164. sandloom/core/http/request_authority.py +93 -0
  165. sandloom/core/http/route_index.py +252 -0
  166. sandloom/core/http/route_runtime.py +592 -0
  167. sandloom/core/http/tenant_scope.py +186 -0
  168. sandloom/core/idempotency/__init__.py +72 -0
  169. sandloom/core/idempotency/automatic.py +166 -0
  170. sandloom/core/idempotency/cache_store.py +118 -0
  171. sandloom/core/idempotency/capture.py +251 -0
  172. sandloom/core/idempotency/durable.py +350 -0
  173. sandloom/core/idempotency/fingerprint.py +209 -0
  174. sandloom/core/idempotency/guard.py +207 -0
  175. sandloom/core/idempotency/replay.py +159 -0
  176. sandloom/core/idempotency/reservation.py +277 -0
  177. sandloom/core/infra/__init__.py +119 -0
  178. sandloom/core/infra/access.py +135 -0
  179. sandloom/core/infra/active.py +42 -0
  180. sandloom/core/infra/capabilities.py +207 -0
  181. sandloom/core/infra/config.py +218 -0
  182. sandloom/core/infra/contracts.py +1170 -0
  183. sandloom/core/infra/extra_capabilities.py +266 -0
  184. sandloom/core/infra/registry.py +831 -0
  185. sandloom/core/ingress/__init__.py +6 -0
  186. sandloom/core/ingress/client_ip.py +161 -0
  187. sandloom/core/ingress/rate_limit.py +213 -0
  188. sandloom/core/internal_auth.py +92 -0
  189. sandloom/core/lifecycle.py +210 -0
  190. sandloom/core/loader/__init__.py +0 -0
  191. sandloom/core/loader/manifest.py +445 -0
  192. sandloom/core/loader/plugin_loader.py +664 -0
  193. sandloom/core/migrations/__init__.py +45 -0
  194. sandloom/core/migrations/alembic_support.py +236 -0
  195. sandloom/core/migrations/backup.py +592 -0
  196. sandloom/core/migrations/core_chain/README +1 -0
  197. sandloom/core/migrations/core_chain/env.py +27 -0
  198. sandloom/core/migrations/core_chain/script.py.mako +28 -0
  199. sandloom/core/migrations/core_chain/versions/0001_core_infra_core_infrastructure_tables.py +110 -0
  200. sandloom/core/migrations/core_chain/versions/0002_outbox_lease.py +37 -0
  201. sandloom/core/migrations/core_chain/versions/0003_outbox_claim_token.py +37 -0
  202. sandloom/core/migrations/core_chain/versions/0004_outbox_backoff.py +37 -0
  203. sandloom/core/migrations/core_chain/versions/0005_outbox_partial_indexes.py +74 -0
  204. sandloom/core/migrations/core_chain/versions/0006_contract_command_log.py +55 -0
  205. sandloom/core/migrations/core_chain/versions/0007_consumer_inbox_processed_at.py +41 -0
  206. sandloom/core/migrations/core_chain/versions/0008_outbox_trace_id.py +23 -0
  207. sandloom/core/migrations/core_chain/versions/0009_http_idempotency_log.py +56 -0
  208. sandloom/core/migrations/core_chain/versions/0010_saga_state.py +133 -0
  209. sandloom/core/migrations/core_chain/versions/0011_projection_watermarks.py +41 -0
  210. sandloom/core/migrations/core_chain/versions/0012_projection_rebuilds_active.py +47 -0
  211. sandloom/core/migrations/core_chain/versions/0013_contract_command_effects.py +38 -0
  212. sandloom/core/migrations/migrations.py +930 -0
  213. sandloom/core/migrations/urls.py +61 -0
  214. sandloom/core/module_api/__init__.py +210 -0
  215. sandloom/core/module_api/_bootstrap.py +52 -0
  216. sandloom/core/module_api/_call.py +460 -0
  217. sandloom/core/module_api/_context.py +125 -0
  218. sandloom/core/module_api/_dedupe.py +393 -0
  219. sandloom/core/module_api/_define.py +186 -0
  220. sandloom/core/module_api/_errors.py +187 -0
  221. sandloom/core/module_api/_method.py +224 -0
  222. sandloom/core/module_api/_provider.py +396 -0
  223. sandloom/core/module_api/_read_guard.py +57 -0
  224. sandloom/core/module_api/_read_scope.py +492 -0
  225. sandloom/core/module_api/_registration.py +572 -0
  226. sandloom/core/module_api/_schema.py +280 -0
  227. sandloom/core/module_api/_service_registry.py +134 -0
  228. sandloom/core/module_api/_spec.py +97 -0
  229. sandloom/core/observability/__init__.py +0 -0
  230. sandloom/core/observability/guardrails.py +221 -0
  231. sandloom/core/observability/logging.py +192 -0
  232. sandloom/core/observability/metrics.py +763 -0
  233. sandloom/core/observability/metrics_utils.py +27 -0
  234. sandloom/core/observability/observability.py +131 -0
  235. sandloom/core/observability/request_context.py +16 -0
  236. sandloom/core/observability/tracing.py +137 -0
  237. sandloom/core/orm.py +69 -0
  238. sandloom/core/planner.py +979 -0
  239. sandloom/core/production_profile.py +310 -0
  240. sandloom/core/projections/__init__.py +54 -0
  241. sandloom/core/projections/consumer.py +61 -0
  242. sandloom/core/projections/descriptors.py +162 -0
  243. sandloom/core/projections/operations.py +232 -0
  244. sandloom/core/projections/purge.py +268 -0
  245. sandloom/core/projections/rebuild.py +131 -0
  246. sandloom/core/projections/registry.py +129 -0
  247. sandloom/core/projections/stores.py +262 -0
  248. sandloom/core/projections/tokens.py +304 -0
  249. sandloom/core/projections/upsert.py +230 -0
  250. sandloom/core/route_markers.py +256 -0
  251. sandloom/core/route_policy.py +532 -0
  252. sandloom/core/route_snapshots.py +426 -0
  253. sandloom/core/rpc/__init__.py +217 -0
  254. sandloom/core/rpc/binding.py +237 -0
  255. sandloom/core/rpc/client.py +154 -0
  256. sandloom/core/rpc/context.py +210 -0
  257. sandloom/core/rpc/dispatch.py +246 -0
  258. sandloom/core/rpc/envelope.py +208 -0
  259. sandloom/core/rpc/errors.py +67 -0
  260. sandloom/core/rpc/inbound_auth.py +358 -0
  261. sandloom/core/rpc/outbound.py +120 -0
  262. sandloom/core/rpc/proxy.py +757 -0
  263. sandloom/core/rpc/readiness.py +345 -0
  264. sandloom/core/rpc/server.py +393 -0
  265. sandloom/core/rpc/wire.py +88 -0
  266. sandloom/core/rpc_binding.py +465 -0
  267. sandloom/core/rpc_identity.py +368 -0
  268. sandloom/core/rpc_pair_mac.py +831 -0
  269. sandloom/core/rpc_transport.py +687 -0
  270. sandloom/core/rpc_transport_compat.py +416 -0
  271. sandloom/core/runtime.py +98 -0
  272. sandloom/core/sagas/__init__.py +196 -0
  273. sandloom/core/sagas/channel.py +156 -0
  274. sandloom/core/sagas/ops.py +528 -0
  275. sandloom/core/sagas/outcomes.py +231 -0
  276. sandloom/core/sagas/registry.py +315 -0
  277. sandloom/core/sagas/runtime.py +992 -0
  278. sandloom/core/sagas/sweep.py +233 -0
  279. sandloom/core/schema/__init__.py +0 -0
  280. sandloom/core/schema/registry.py +220 -0
  281. sandloom/core/signing_keys.py +248 -0
  282. sandloom/core/sql_alchemy/__init__.py +1 -0
  283. sandloom/core/sql_alchemy/base.py +17 -0
  284. sandloom/core/sql_alchemy/columns.py +134 -0
  285. sandloom/core/sql_alchemy/command_log.py +193 -0
  286. sandloom/core/sql_alchemy/dead_connection.py +343 -0
  287. sandloom/core/sql_alchemy/dedupe_log.py +380 -0
  288. sandloom/core/sql_alchemy/driver_compat.py +470 -0
  289. sandloom/core/sql_alchemy/durable_inbox.py +131 -0
  290. sandloom/core/sql_alchemy/effect_rows.py +448 -0
  291. sandloom/core/sql_alchemy/models/__init__.py +37 -0
  292. sandloom/core/sql_alchemy/models/audit.py +50 -0
  293. sandloom/core/sql_alchemy/models/consumer_inbox.py +59 -0
  294. sandloom/core/sql_alchemy/models/contract_command.py +53 -0
  295. sandloom/core/sql_alchemy/models/http_idempotency.py +56 -0
  296. sandloom/core/sql_alchemy/models/outbox.py +130 -0
  297. sandloom/core/sql_alchemy/models/projection_watermark.py +31 -0
  298. sandloom/core/sql_alchemy/models/saga.py +136 -0
  299. sandloom/core/sql_alchemy/money_ledger.py +94 -0
  300. sandloom/core/sql_alchemy/outbox_store/__init__.py +509 -0
  301. sandloom/core/sql_alchemy/outbox_store/audit.py +144 -0
  302. sandloom/core/sql_alchemy/outbox_store/relay.py +549 -0
  303. sandloom/core/sql_alchemy/outbox_store/statements.py +125 -0
  304. sandloom/core/sql_alchemy/planner_adapter/__init__.py +362 -0
  305. sandloom/core/sql_alchemy/planner_adapter/compiler.py +673 -0
  306. sandloom/core/sql_alchemy/planner_adapter/forms.py +529 -0
  307. sandloom/core/sql_alchemy/planner_adapter/units.py +460 -0
  308. sandloom/core/sql_alchemy/planner_safety.py +213 -0
  309. sandloom/core/sql_alchemy/projection_watermarks.py +207 -0
  310. sandloom/core/sql_alchemy/read_guard.py +116 -0
  311. sandloom/core/sql_alchemy/read_only_policy.py +88 -0
  312. sandloom/core/sql_alchemy/reconnect.py +97 -0
  313. sandloom/core/sql_alchemy/repositories/__init__.py +1 -0
  314. sandloom/core/sql_alchemy/repositories/outbox.py +28 -0
  315. sandloom/core/sql_alchemy/request_log.py +184 -0
  316. sandloom/core/sql_alchemy/rls.py +210 -0
  317. sandloom/core/sql_alchemy/saga_store.py +434 -0
  318. sandloom/core/sql_alchemy/tenant_rls.py +696 -0
  319. sandloom/core/sql_alchemy/uow.py +93 -0
  320. sandloom/core/sql_alchemy/write_admission.py +462 -0
  321. sandloom/core/tasks/__init__.py +1 -0
  322. sandloom/core/tasks/enqueue.py +127 -0
  323. sandloom/core/tasks/event_ops.py +155 -0
  324. sandloom/core/tasks/periodic.py +39 -0
  325. sandloom/core/tasks/pool_metrics.py +87 -0
  326. sandloom/core/tasks/relay.py +826 -0
  327. sandloom/core/tenant.py +643 -0
  328. sandloom/core/tenant_context.py +100 -0
  329. sandloom/core/testing/__init__.py +236 -0
  330. sandloom/core/testing/_uow.py +450 -0
  331. sandloom/core/testing/auth.py +87 -0
  332. sandloom/core/testing/authz.py +183 -0
  333. sandloom/core/testing/boot.py +209 -0
  334. sandloom/core/testing/connections.py +195 -0
  335. sandloom/core/testing/database.py +367 -0
  336. sandloom/core/testing/deploy_profile.py +1088 -0
  337. sandloom/core/testing/env.py +83 -0
  338. sandloom/core/testing/events.py +143 -0
  339. sandloom/core/testing/fixtures.py +558 -0
  340. sandloom/core/testing/infra.py +52 -0
  341. sandloom/core/testing/isolation.py +236 -0
  342. sandloom/core/testing/migrations.py +312 -0
  343. sandloom/core/testing/observed.py +91 -0
  344. sandloom/core/testing/ownership.py +314 -0
  345. sandloom/core/testing/plugin.py +104 -0
  346. sandloom/core/testing/registration.py +135 -0
  347. sandloom/core/testing/resources.py +535 -0
  348. sandloom/core/testing/routes.py +86 -0
  349. sandloom/core/testing/sagas.py +755 -0
  350. sandloom/core/testing/security.py +129 -0
  351. sandloom/core/testing/served.py +262 -0
  352. sandloom/core/testing/server_errors.py +77 -0
  353. sandloom/core/testing/services.py +57 -0
  354. sandloom/core/testing/session_checks.py +175 -0
  355. sandloom/core/testing/shuffle.py +112 -0
  356. sandloom/core/testing/static_checks.py +318 -0
  357. sandloom/core/testing/workers.py +364 -0
  358. sandloom/core/unit_of_work/__init__.py +488 -0
  359. sandloom/core/unit_of_work/dispatch.py +626 -0
  360. sandloom/core/unit_of_work/effects.py +266 -0
  361. sandloom/core/unit_of_work/hooks.py +314 -0
  362. sandloom/core/unit_of_work/intent.py +398 -0
  363. sandloom/core/unit_of_work/request.py +574 -0
  364. sandloom/core/unit_of_work/risk.py +838 -0
  365. sandloom/core/unit_of_work/savepoints.py +68 -0
  366. sandloom/core/unit_of_work/scope.py +325 -0
  367. sandloom/core/unit_of_work/versioning.py +82 -0
  368. sandloom/core/utils.py +11 -0
  369. sandloom/core/worker.py +420 -0
  370. sandloom/main.py +48 -0
  371. sandloom/py.typed +0 -0
  372. sandloom/sdk/__init__.py +74 -0
  373. sandloom/sdk/_decl/__init__.py +13 -0
  374. sandloom/sdk/_decl/_caller.py +152 -0
  375. sandloom/sdk/_decl/_event_wire.py +1065 -0
  376. sandloom/sdk/_decl/_owner.py +103 -0
  377. sandloom/sdk/_decl/_recording.py +36 -0
  378. sandloom/sdk/_decl/contracts.py +520 -0
  379. sandloom/sdk/_decl/errors.py +79 -0
  380. sandloom/sdk/_decl/events.py +594 -0
  381. sandloom/sdk/_decl/module.py +592 -0
  382. sandloom/sdk/_decl/projections.py +1051 -0
  383. sandloom/sdk/_decl/sagas.py +110 -0
  384. sandloom/sdk/_decl/testing.py +89 -0
  385. sandloom/sdk/_decl/web.py +276 -0
  386. sandloom/sdk/_prim/__init__.py +12 -0
  387. sandloom/sdk/_prim/app.py +59 -0
  388. sandloom/sdk/_prim/authz.py +12 -0
  389. sandloom/sdk/_prim/contracts.py +96 -0
  390. sandloom/sdk/_prim/data.py +47 -0
  391. sandloom/sdk/_prim/docs.py +253 -0
  392. sandloom/sdk/_prim/docs_wire.py +322 -0
  393. sandloom/sdk/_prim/effects.py +13 -0
  394. sandloom/sdk/_prim/events.py +24 -0
  395. sandloom/sdk/_prim/infra.py +13 -0
  396. sandloom/sdk/_prim/module.py +23 -0
  397. sandloom/sdk/_prim/projections.py +61 -0
  398. sandloom/sdk/_prim/recipes.py +987 -0
  399. sandloom/sdk/_prim/sagas.py +14 -0
  400. sandloom/sdk/_prim/tasks.py +111 -0
  401. sandloom/sdk/_prim/tenant.py +26 -0
  402. sandloom/sdk/_prim/testing.py +142 -0
  403. sandloom/sdk/_prim/web.py +113 -0
  404. sandloom/sdk/_stub.py +14 -0
  405. sandloom/sdk/app.py +26 -0
  406. sandloom/sdk/authz.py +151 -0
  407. sandloom/sdk/contracts.py +94 -0
  408. sandloom/sdk/data.py +88 -0
  409. sandloom/sdk/effects.py +41 -0
  410. sandloom/sdk/errors.py +93 -0
  411. sandloom/sdk/events.py +39 -0
  412. sandloom/sdk/infra.py +61 -0
  413. sandloom/sdk/migrations.py +24 -0
  414. sandloom/sdk/module.py +49 -0
  415. sandloom/sdk/projections.py +82 -0
  416. sandloom/sdk/sagas.py +54 -0
  417. sandloom/sdk/security.py +74 -0
  418. sandloom/sdk/tasks.py +24 -0
  419. sandloom/sdk/tenant.py +37 -0
  420. sandloom/sdk/testing/__init__.py +205 -0
  421. sandloom/sdk/testing/fixtures.py +114 -0
  422. sandloom/sdk/testing/plugin.py +99 -0
  423. sandloom/sdk/tooling.py +24 -0
  424. sandloom/sdk/web.py +96 -0
  425. sandloom/shared/README.md +58 -0
  426. sandloom/shared/__init__.py +0 -0
  427. sandloom/shared/authz/__init__.py +155 -0
  428. sandloom/shared/authz/_resolve.py +173 -0
  429. sandloom/shared/authz/account.py +263 -0
  430. sandloom/shared/authz/algebra.py +282 -0
  431. sandloom/shared/authz/atoms_claims.py +363 -0
  432. sandloom/shared/authz/atoms_fact.py +125 -0
  433. sandloom/shared/authz/atoms_live.py +231 -0
  434. sandloom/shared/authz/atoms_resource.py +43 -0
  435. sandloom/shared/authz/constants.py +31 -0
  436. sandloom/shared/authz/context.py +89 -0
  437. sandloom/shared/authz/deps.py +287 -0
  438. sandloom/shared/authz/enforce.py +134 -0
  439. sandloom/shared/authz/facts.py +600 -0
  440. sandloom/shared/authz/facts_contract.py +108 -0
  441. sandloom/shared/authz/live_contracts.py +175 -0
  442. sandloom/shared/authz/metrics.py +35 -0
  443. sandloom/shared/authz/projection.py +83 -0
  444. sandloom/shared/authz/results.py +205 -0
  445. sandloom/shared/contracts/__init__.py +1 -0
  446. sandloom/shared/contracts/billing_credits_v1.py +56 -0
  447. sandloom/shared/contracts/billing_entitlements_v1.py +54 -0
  448. sandloom/shared/contracts/identity_contact_v1.py +38 -0
  449. sandloom/shared/contracts/identity_dto.py +32 -0
  450. sandloom/shared/contracts/identity_security_v1.py +34 -0
  451. sandloom/shared/contracts/tenancy_dto.py +41 -0
  452. sandloom/shared/contracts/tenancy_membership_v1.py +69 -0
  453. sandloom/shared/events/billing.credits.added.v1.json +51 -0
  454. sandloom/shared/events/billing.credits.restored.v1.json +51 -0
  455. sandloom/shared/events/billing.credits.reversed.v1.json +51 -0
  456. sandloom/shared/events/billing.credits.spent.v1.json +51 -0
  457. sandloom/shared/events/billing.subscription.canceled.v1.json +51 -0
  458. sandloom/shared/events/billing.subscription.created.v1.json +51 -0
  459. sandloom/shared/events/billing.subscription.updated.v1.json +51 -0
  460. sandloom/shared/events/identity.sso_linked.v1.json +86 -0
  461. sandloom/shared/events/identity.sso_unlinked.v1.json +86 -0
  462. sandloom/shared/events/identity.twofa_backup_codes_regenerated.v1.json +86 -0
  463. sandloom/shared/events/identity.twofa_disabled.v1.json +86 -0
  464. sandloom/shared/events/identity.twofa_enabled.v1.json +86 -0
  465. sandloom/shared/events/identity.user_deleted.v1.json +86 -0
  466. sandloom/shared/events/identity.user_email_confirmed.v1.json +86 -0
  467. sandloom/shared/events/identity.user_logged_in.v1.json +86 -0
  468. sandloom/shared/events/identity.user_logged_out.v1.json +86 -0
  469. sandloom/shared/events/identity.user_password_reset.v1.json +86 -0
  470. sandloom/shared/events/identity.user_registered.v1.json +86 -0
  471. sandloom/shared/events/identity.user_role_assigned.v1.json +86 -0
  472. sandloom/shared/events/identity.user_role_revoked.v1.json +86 -0
  473. sandloom/shared/events/identity.user_sessions_revoked.v1.json +86 -0
  474. sandloom/shared/events/identity.user_updated.v1.json +86 -0
  475. sandloom/shared/events/tenancy.invitation_accepted.v1.json +48 -0
  476. sandloom/shared/events/tenancy.invitation_created.v1.json +48 -0
  477. sandloom/shared/events/tenancy.invitation_revoked.v1.json +48 -0
  478. sandloom/shared/events/tenancy.member_added.v1.json +62 -0
  479. sandloom/shared/events/tenancy.member_added.v2.json +66 -0
  480. sandloom/shared/events/tenancy.member_removed.v1.json +62 -0
  481. sandloom/shared/events/tenancy.member_removed.v2.json +66 -0
  482. sandloom/shared/events/tenancy.member_role_changed.v1.json +62 -0
  483. sandloom/shared/events/tenancy.member_role_changed.v2.json +66 -0
  484. sandloom/shared/events/tenancy.organization_created.v1.json +29 -0
  485. sandloom/shared/events/tenancy.organization_deleted.v1.json +29 -0
  486. sandloom/shared/events/tenancy.organization_updated.v1.json +29 -0
  487. sandloom/shared/guards/__init__.py +0 -0
  488. sandloom/shared/guards/auth.py +26 -0
  489. sandloom/shared/guards/platform.py +19 -0
  490. sandloom/shared/guards/service.py +27 -0
  491. sandloom/shared/membership.py +72 -0
  492. sandloom/shared/subject.py +122 -0
  493. sandloom-0.7.0a1.dist-info/METADATA +97 -0
  494. sandloom-0.7.0a1.dist-info/RECORD +498 -0
  495. sandloom-0.7.0a1.dist-info/WHEEL +4 -0
  496. sandloom-0.7.0a1.dist-info/entry_points.txt +2 -0
  497. sandloom-0.7.0a1.dist-info/licenses/LICENSE +202 -0
  498. sandloom-0.7.0a1.dist-info/licenses/NOTICE +8 -0
sandloom/__init__.py ADDED
@@ -0,0 +1,349 @@
1
+ """Sandloom framework — top-level CLI (`sandloom`).
2
+
3
+ Subcommands:
4
+ sandloom new <app> scaffold a standalone application that consumes the
5
+ framework (see sandloom.core.cli.project)
6
+ sandloom add ... generate code: a module, an event, a contract, a
7
+ consumer, a saga, a projection, a task, and a
8
+ module's microservices deployment (sandloom add deploy)
9
+ (see sandloom.core.cli.add)
10
+ sandloom check run the architecture (module isolation) rules against
11
+ ./architecture_rules.yml (see sandloom.core.cli.check)
12
+ sandloom explain <code> the long form of a framework error code (SANDLOOM-xxxx)
13
+ sandloom docs <name> the Public API 1.0 reference of a name or module
14
+ (sandloom.sdk; see sandloom.sdk.tooling.docs_main)
15
+ sandloom generate [module ...]
16
+ write every generated file (module, route and
17
+ contract snapshots, contract stubs, DTO copies,
18
+ exported event schemas) after the compatibility
19
+ checks (see sandloom.core.cli.generated)
20
+ sandloom test [module] the module's tests, the fast (--full: whole) parallel
21
+ suite and every static gate, with one summary; it
22
+ never writes a generated file (see
23
+ sandloom.core.cli.run_tests)
24
+ sandloom migrate ... database migrations (see sandloom.core.cli.migrate);
25
+ `sandloom migrate new <module> "<msg>"` autogenerates a
26
+ revision with row-level security
27
+ sandloom projection ... operate query projections (see
28
+ sandloom.core.cli.projections)
29
+ sandloom outbox ... list / requeue dead-lettered outbox events
30
+ sandloom streams ... list / replay the Streams dead-letter queue
31
+ (both: see sandloom.core.cli.events)
32
+ sandloom keys generate generate an asymmetric signing key pair (JWT
33
+ access tokens, or --purpose rpc: a service identity)
34
+ sandloom keys allowlist derive RPC_ALLOWED_CALLS from SERVICE_BINDINGS
35
+ (both: see sandloom.core.cli.keys)
36
+ sandloom contracts ... sync-contract snapshots + rolling-upgrade compatibility
37
+ checks (see sandloom.core.cli.contracts)
38
+ sandloom routes ... per-module route snapshots (method, path, operation
39
+ class) and the route reference (sandloom.core.cli.routes)
40
+ sandloom admin export export the platform-owner UI manifest
41
+ sandloom backup ... backup plan, restore verification, security-cache
42
+ reconciliation after a restore (see sandloom.core.cli.backup)
43
+ sandloom sagas ... list / show / retry / park / resolve saga instances
44
+ (see sandloom.core.cli.sagas)
45
+ sandloom security ... incident response: mass session revocation, forced
46
+ password reset, audit export (see sandloom.core.cli.security)
47
+ sandloom config dump the effective settings, secrets redacted, with the
48
+ source of each value (see sandloom.core.cli.config)
49
+ sandloom doctor read-only deployment preflight: config, modules,
50
+ infra reachability, migration heads, consumer lag,
51
+ RLS (see sandloom.core.cli.doctor)
52
+ sandloom version print the installed framework version
53
+ """
54
+
55
+ from __future__ import annotations
56
+
57
+ import argparse
58
+ import importlib
59
+ import sys
60
+ from pathlib import Path
61
+ from typing import Any
62
+
63
+
64
+ def _static_import(name: str) -> Any:
65
+ """Import a STATIC CLI module (``sandloom new`` / ``add`` / ``check``).
66
+
67
+ ``sandloom.core`` resolves its re-exports lazily, so these code-generation and
68
+ static-analysis commands never build the settings object and work in an
69
+ empty directory with no DATABASE_URL / JWT_SECRET configured.
70
+ """
71
+ return importlib.import_module(name)
72
+
73
+
74
+ #: Commands that read the deployment's configuration: they refuse to run on
75
+ #: one a process would refuse to boot with, like the app and the worker.
76
+ #: (``migrate`` checks in its own entry point, ``sandloom.core.cli.migrate``; ``doctor``
77
+ #: reports the problems instead.)
78
+ _CONFIGURED_COMMANDS = frozenset(
79
+ {
80
+ "projection",
81
+ "outbox",
82
+ "streams",
83
+ "contracts",
84
+ "routes",
85
+ "backup",
86
+ "security",
87
+ "config",
88
+ "sagas",
89
+ }
90
+ )
91
+
92
+
93
+ def _load_test_env_for_authoring() -> None:
94
+ """``sandloom migrate new`` and ``sandloom generate`` run where ``sandloom
95
+ test`` runs: with the project's ``.env.test`` (+ ``SANDLOOM_TEST_*``)
96
+ loaded, like the test harness, before the settings object is built.
97
+ ``migrate new`` writes only to a scratch database on that server, never
98
+ to the configured ones; ``generate`` connects to none."""
99
+ try:
100
+ fixtures = _static_import("sandloom.core.testing.env")
101
+ except ImportError: # no test tooling installed: the process env stands
102
+ return
103
+ if fixtures.find_env_file([Path.cwd()]) is not None:
104
+ fixtures.load_test_env([Path.cwd()])
105
+
106
+
107
+ def _enforce_configuration() -> None:
108
+ """The boot checks of ``create_app`` (``SystemExit`` with the reason)."""
109
+ # Imported here: the static commands (new / add / check / keys /
110
+ # admin) must not build the settings object.
111
+ from sandloom.core.app_factory import enforce_configuration
112
+
113
+ enforce_configuration()
114
+
115
+
116
+ def _version() -> str:
117
+ try:
118
+ from importlib.metadata import version
119
+
120
+ return version("sandloom")
121
+ except Exception: # pragma: no cover # noqa: BLE001 - editable / unbuilt tree has no dist metadata
122
+ return "0.0.0+local"
123
+
124
+
125
+ def _cmd_new(argv: list[str]) -> int:
126
+ project = _static_import("sandloom.core.cli.project")
127
+ generate_project, quickstart = project.generate_project, project.quickstart
128
+
129
+ parser = argparse.ArgumentParser(
130
+ prog="sandloom new", description="Scaffold a standalone Sandloom application"
131
+ )
132
+ parser.add_argument("app", help="application name (snake_case, e.g. helpdesk)")
133
+ parser.add_argument(
134
+ "--dir", type=Path, default=Path.cwd(), help="parent directory (default: cwd)"
135
+ )
136
+ parser.add_argument(
137
+ "--with",
138
+ dest="batteries",
139
+ default="",
140
+ help="comma-separated standard modules to install and load: "
141
+ "identity,tenancy,billing (the sandloom-<module> packages)",
142
+ )
143
+ parser.add_argument(
144
+ "--no-batteries",
145
+ action="store_true",
146
+ help="install no standard module (minimal app)",
147
+ )
148
+ parser.add_argument(
149
+ "--module",
150
+ default="example",
151
+ help="name of the initial sample module (default: example)",
152
+ )
153
+ parser.add_argument(
154
+ "--framework-req",
155
+ default=None,
156
+ help=(
157
+ "override the framework dependency requirement string "
158
+ "(default: sandloom[redis,celery]>=0.7.0a1,<0.8; each --with module "
159
+ "adds its sandloom-<module> package)"
160
+ ),
161
+ )
162
+ parser.add_argument(
163
+ "--framework-source",
164
+ choices=("pypi", "git", "path"),
165
+ default=None,
166
+ help="distribution source (checkout: git; installed wheel: pypi)",
167
+ )
168
+ parser.add_argument(
169
+ "--framework-path",
170
+ type=Path,
171
+ default=None,
172
+ help=(
173
+ "framework repository (or its backend/ directory, holding "
174
+ "packages/) for --framework-source path"
175
+ ),
176
+ )
177
+ args = parser.parse_args(argv)
178
+
179
+ batteries: list[str] = []
180
+ if not args.no_batteries and args.batteries:
181
+ batteries = [m.strip() for m in args.batteries.split(",") if m.strip()]
182
+
183
+ try:
184
+ created = generate_project(
185
+ args.app,
186
+ args.dir,
187
+ with_batteries=batteries,
188
+ sample_module=args.module,
189
+ framework_req=args.framework_req,
190
+ framework_source=args.framework_source,
191
+ framework_path=args.framework_path,
192
+ )
193
+ except (ValueError, FileExistsError) as exc:
194
+ print(f"error: {exc}", file=sys.stderr)
195
+ return 1
196
+
197
+ root = args.dir / args.app
198
+ print(f"Created application '{args.app}' ({len(created)} files) at {root}")
199
+ # The generated files (snapshots, schemas, stubs): the app's own CI gate
200
+ # (`sandloom test --ci`) only checks them, so a fresh app must carry them.
201
+ problem = project.write_generated_files(root)
202
+ if problem is not None:
203
+ print(
204
+ f"note: generated files not written ({problem}); "
205
+ "run `uv run sandloom generate` once the app installs"
206
+ )
207
+ # The quickstart's one source (sandloom.core.cli.project.QUICKSTART): the docs
208
+ # are tested against it and the CI job `quickstart` runs these lines.
209
+ in_cwd = args.dir.resolve() == Path.cwd().resolve()
210
+ lines = quickstart(args.app, args.module, path=None if in_cwd else str(root))
211
+ print("\nNext steps:\n" + "".join(f" {line}\n" for line in lines))
212
+ return 0
213
+
214
+
215
+ def main() -> None: # noqa: C901
216
+ parser = argparse.ArgumentParser(
217
+ prog="sandloom", description="Sandloom framework CLI"
218
+ )
219
+ sub = parser.add_subparsers(dest="command")
220
+ sub.add_parser("new", add_help=False, help="scaffold a standalone application")
221
+ sub.add_parser(
222
+ "add",
223
+ add_help=False,
224
+ help="generate code: module, event, contract, consumer, saga, "
225
+ "projection, task, deploy",
226
+ )
227
+ sub.add_parser(
228
+ "check", add_help=False, help="run architecture (module isolation) checks"
229
+ )
230
+ sub.add_parser(
231
+ "explain", add_help=False, help="explain an SANDLOOM-xxxx error code"
232
+ )
233
+ sub.add_parser(
234
+ "docs", add_help=False, help="the sandloom.sdk reference: sandloom docs <name>"
235
+ )
236
+ sub.add_parser(
237
+ "generate",
238
+ add_help=False,
239
+ help="write the generated files (snapshots, stubs, DTO copies, schemas)",
240
+ )
241
+ sub.add_parser(
242
+ "test", add_help=False, help="module tests + fast suite + static gates"
243
+ )
244
+ sub.add_parser("migrate", add_help=False, help="run database migrations")
245
+ sub.add_parser("projection", add_help=False, help="operate query projections")
246
+ sub.add_parser("outbox", add_help=False, help="requeue dead-lettered outbox events")
247
+ sub.add_parser(
248
+ "streams", add_help=False, help="replay the Streams dead-letter queue"
249
+ )
250
+ sub.add_parser("keys", add_help=False, help="generate signing keys")
251
+ sub.add_parser(
252
+ "contracts",
253
+ add_help=False,
254
+ help="contract snapshots / compatibility checks",
255
+ )
256
+ sub.add_parser(
257
+ "routes", add_help=False, help="route snapshots (each route's policy)"
258
+ )
259
+ sub.add_parser("admin", add_help=False, help="export a generated admin UI manifest")
260
+ sub.add_parser("backup", add_help=False, help="backup plan / restore verification")
261
+ sub.add_parser(
262
+ "security", add_help=False, help="incident response (sessions, audit export)"
263
+ )
264
+ sub.add_parser(
265
+ "sagas", add_help=False, help="list / show / retry / park / resolve sagas"
266
+ )
267
+ sub.add_parser(
268
+ "config", add_help=False, help="effective settings (sandloom config dump)"
269
+ )
270
+ sub.add_parser("doctor", add_help=False, help="read-only deployment preflight")
271
+ sub.add_parser("version", help="print the framework version")
272
+
273
+ args, rest = parser.parse_known_args()
274
+ if args.command in _CONFIGURED_COMMANDS:
275
+ _enforce_configuration()
276
+
277
+ if args.command == "new":
278
+ raise SystemExit(_cmd_new(rest))
279
+ if args.command == "add":
280
+ raise SystemExit(_static_import("sandloom.core.cli.add").main(rest))
281
+ if args.command == "check":
282
+ raise SystemExit(_static_import("sandloom.core.cli.check").main(rest))
283
+ if args.command == "generate":
284
+ _load_test_env_for_authoring()
285
+ raise SystemExit(_static_import("sandloom.core.cli.generated").main(rest))
286
+ if args.command == "test":
287
+ raise SystemExit(_static_import("sandloom.core.cli.run_tests").main(rest))
288
+ if args.command == "docs":
289
+ raise SystemExit(_static_import("sandloom.sdk.tooling").docs_main(rest))
290
+ if args.command == "explain":
291
+ raise SystemExit(_static_import("sandloom.core.cli.explain").main(rest))
292
+ if args.command == "migrate":
293
+ if rest[:1] == ["new"]:
294
+ _load_test_env_for_authoring()
295
+ from sandloom.core.cli.migrate import main as migrate_main
296
+
297
+ raise SystemExit(migrate_main(rest))
298
+ if args.command == "projection":
299
+ from sandloom.core.cli.projections import main as projection_main
300
+
301
+ raise SystemExit(projection_main(rest))
302
+ if args.command == "outbox":
303
+ from sandloom.core.cli.events import outbox_main
304
+
305
+ raise SystemExit(outbox_main(rest))
306
+ if args.command == "streams":
307
+ from sandloom.core.cli.events import streams_main
308
+
309
+ raise SystemExit(streams_main(rest))
310
+ if args.command == "keys":
311
+ raise SystemExit(_static_import("sandloom.core.cli.keys").main(rest))
312
+ if args.command == "contracts":
313
+ from sandloom.core.cli.contracts import main as contracts_main
314
+
315
+ raise SystemExit(contracts_main(rest))
316
+ if args.command == "routes":
317
+ from sandloom.core.cli.routes import main as routes_main
318
+
319
+ raise SystemExit(routes_main(rest))
320
+ if args.command == "admin":
321
+ raise SystemExit(_static_import("sandloom.core.cli.admin").main(rest))
322
+ if args.command == "backup":
323
+ from sandloom.core.cli.backup import main as backup_main
324
+
325
+ raise SystemExit(backup_main(rest))
326
+ if args.command == "security":
327
+ from sandloom.core.cli.security import main as security_main
328
+
329
+ raise SystemExit(security_main(rest))
330
+ if args.command == "sagas":
331
+ raise SystemExit(_static_import("sandloom.core.cli.sagas").main(rest))
332
+ if args.command == "config":
333
+ from sandloom.core.cli.config import main as config_main
334
+
335
+ raise SystemExit(config_main(rest))
336
+ if args.command == "doctor":
337
+ from sandloom.core.cli.doctor import main as doctor_main
338
+
339
+ raise SystemExit(doctor_main(rest))
340
+ if args.command == "version":
341
+ print(_version())
342
+ raise SystemExit(0)
343
+
344
+ parser.print_help()
345
+ raise SystemExit(0)
346
+
347
+
348
+ if __name__ == "__main__": # pragma: no cover
349
+ main()
@@ -0,0 +1,120 @@
1
+ # Sandloom kernel-contributor contract (`sandloom.core`, `sandloom.sdk`, `sandloom.shared`)
2
+
3
+ For changes to the framework kernel itself. Module authors never need this file: their
4
+ contract is `src/sandloom/AGENTS.md`. The module rules still apply here wherever kernel code
5
+ acts like a module (units, effects, tenancy). Concepts: `docs/concepts/index.md`; every check
6
+ and refusal: `docs/reference/error-codes.md` (`sandloom.core.error_codes` is its source).
7
+
8
+ ## Layers and imports (ADR-0007)
9
+
10
+ - **Layers.** `sandloom.core` is layered top (tooling, composition) to bottom
11
+ (configuration): `.importlinter`, checked by `lint-imports` and
12
+ `tests/architecture/test_kernel_import_contracts.py`.
13
+ - A module imports its own layer or a lower one, with no cycle at any depth.
14
+ - `sandloom.core.config` is a leaf and imports nothing above it.
15
+ - `exhaustive`: a new `sandloom.core` child fails until you place it in a layer.
16
+ - No `ignore_imports`: one would be debt needing a `; reason:` and an owner.
17
+ - **Function-local imports.** A kernel `# noqa: PLC0415` states its category:
18
+ - `- optional: <reason>`: the dependency may be absent or unconfigured;
19
+ - `- cold: <reason>`: import cost or side effects kept off the app import.
20
+
21
+ The reason names a boundary (plugin entry, static command, gunicorn master,
22
+ worker healthcheck, a driver SDK on the app path); a cycle break is not a
23
+ category. A hoisted import is `import sandloom.core.x as _x` so test patches still
24
+ apply. Check: `test_lint_suppression_ratchet.py`.
25
+ - **Other `# noqa` markers:** one code per line (`PGH004`, `RUF100`); `BLE001`
26
+ and bandit `S…` need a reason after ` - `; `NOQA_BASELINE` only goes down
27
+ (`docs/contributing/lint-policy.md`).
28
+ - **`sandloom.sdk` is the only public surface** (Public API 1.0, ADR-0010). Each
29
+ public module declares `__all__` and `__beginner__`; the root re-exports
30
+ the 29 beginner names. `public_api_baseline.json` records every
31
+ name and signature (SANDLOOM-T008), and each module's generated reference block
32
+ stays current (`sandloom docs --write`). Adding a name is an API decision.
33
+ - **Levels:** public facades > `sandloom.sdk._decl` (L1, declarative) >
34
+ `sandloom.sdk._prim` (L2 primitives) > `sandloom.core` (L3). `_decl` never imports
35
+ `sandloom.core`; `sandloom.core` and `sandloom.shared` never import `sandloom.sdk`; every L2
36
+ name L1 uses is public (`test_l1_uses_only_public_l2`).
37
+ - **Importing `sandloom.sdk` reads no environment and does no I/O**
38
+ (`test_sdk_import_is_side_effect_free`): settings stay lazy.
39
+ - The framework is unreleased: remove a name outright, no compat aliases.
40
+
41
+ ## Guarantees and effects (ADR-0005)
42
+
43
+ - **The effect model.** Every write-side guarantee is one model: outbox,
44
+ durable inbox, command dedupe, `idempotency_guard` (cache and durable),
45
+ enqueue dedupe, `on_commit` / `before_commit`. See
46
+ `docs/adr/0005-effect-model.md`, `sandloom.core.effects` and `COMMIT_PIPELINE` in
47
+ `sandloom.core.unit_of_work`.
48
+ - **Do not add a new dedupe store or a new post-commit variant.** Reuse one,
49
+ or amend the ADR. Review enforces this; no check can.
50
+ - **Guarantee windows are startup-checked** (`sandloom.core.guarantee_windows`,
51
+ stable risk ids). The command TTL must cover the relay horizon, and
52
+ `--inbox-days` must cover stream retention.
53
+ - **The core chain is infra-only**: outbox, audit, consumer_inbox and
54
+ contract_command_log (`migrations/core/versions/`, shipped as
55
+ `sandloom/core/migrations/core_chain`). Module tables never go there.
56
+
57
+ ## Configuration (ADR-0006, configuration tiers)
58
+
59
+ - **Classify every new setting** in `sandloom.core.config.tiers` as semantic or
60
+ ops. Check: `src/sandloom/core/tests/test_config_tiers.py`.
61
+ - The semantic count is ratcheted (ceiling 16) and needs an ADR to grow.
62
+ Prefer an ops knob or a profile-chosen value.
63
+ - **A production weakening is an accepted risk, never a boolean.** Add an id
64
+ to `sandloom.core.config.accepted_risks` and read it with
65
+ `settings.accepts_risk(id)`. An unknown id fails startup.
66
+ - **Removed settings** (`config_tiers.REMOVED`) fail startup unless they are
67
+ set to their inert value.
68
+ - **Read configuration only through `Settings`, never `os.getenv`.** The
69
+ exceptions are `SANDLOOM_COMPOSITION_ROOT` (process env first) and
70
+ `SANDLOOM_WORKER_TASKQUEUE`.
71
+
72
+ ## Infrastructure layer
73
+
74
+ - **Drivers construct backends.** A backend constructor
75
+ (`create_async_engine`, `redis.from_url`, `Celery(...)`, `Storage(...)`)
76
+ appears only in `sandloom.core.drivers/**`, built lazily by `get_default_*()`
77
+ factories. Check: `test_infra_constructed_only_in_drivers`.
78
+ - **SQLAlchemy stays inside the relational surface**: `orm`, `tenant`, `di`,
79
+ `sql_alchemy/`, `projections/upsert`, `migrations/` and the drivers.
80
+ `TYPE_CHECKING` imports are exempt. Check: `test_relational_paradigm_boundary`.
81
+ - **Outbox and audit writes go through the `OutboxStore` / `AuditStore`
82
+ contracts** (`provider.outbox()` / `.audit()`). `sandloom.core.di` never imports
83
+ a concrete ORM model.
84
+ - **New capabilities ship as contracts only.** Register a `CapabilitySpec`
85
+ with `stability="experimental"`; a driver plugin supplies the backend.
86
+
87
+ ## Kernel conventions
88
+
89
+ - **The kernel names no module.** Module names come only from `sandloom.core.descriptors.module_names`
90
+ (entry-point name, else the last import segment; an ambiguous name: SANDLOOM-B020).
91
+ - **Kernel code reads a request's bearer only through
92
+ `sandloom.core.auth.bearer.bearer_claims(request)`**, which returns access
93
+ tokens only.
94
+ - **Route policy is model E** (ADR-0009, `sandloom.core.route_policy`): deny by
95
+ default, everything else derived. The declarations a route may carry
96
+ (`public`, `no_idempotency`, `replay_safe`, `sensitive`, `operation_intent`,
97
+ `writes`, `allow_multi_db_write`) are no-op markers that `create_app` prunes
98
+ from `route.dependant`; `resolve_route_policy` reads them through
99
+ `sandloom.core.route_markers.route_marker_calls`.
100
+ - **Startup refusals belong in `create_app` / `enforce_configuration`**, which
101
+ every entry point runs (app, worker, `sandloom migrate`, the `sandloom` CLI). Each
102
+ refusal has an `sandloom.core.error_codes` entry and says what to change.
103
+ - **The framework carries no deprecated API.** `error::DeprecationWarning:sandloom`
104
+ turns one into a test failure.
105
+ - **Hot paths are measured.** Change the request path, the UoW or eventing
106
+ only with numbers: cachegrind instruction counts on a shared machine
107
+ (`benchmarks/`, `docs/design/*profile*`).
108
+ - **The test harness is framework code** (`sandloom.core.testing`, public through
109
+ `sandloom.sdk.testing`). A seam module tests need goes there.
110
+
111
+ ## Before you push
112
+
113
+ - `uv run sandloom generate`, `uv run sandloom test --full`, then `uv run sandloom test --ci`
114
+ (no ruff fixes) and `uv run python tools/checks/check_architecture.py`, plus:
115
+ - the slow suites: `SANDLOOM_TEST_REDIS_DB_STRIDE=auto uv run pytest -q -n auto --dist loadfile`
116
+ (split conformance included; `sandloom test` will wrap it).
117
+ - Run the local CI stand-in from the repo root:
118
+ `tools/ci/ci_local.sh <ref> [--jobs a,b]` (`docs/contributing/local-ci.md`).
119
+ - On a shared machine, use your own test DB and Redis (`SANDLOOM_TEST_*`), never
120
+ `pkill` by pattern, and measure CPU only when the machine is idle.
@@ -0,0 +1 @@
1
+ @AGENTS.md
@@ -0,0 +1,10 @@
1
+ """The Sandloom kernel.
2
+
3
+ The package exports nothing: import the submodule that owns a name.
4
+ Business modules use the public core API only (``sandloom.core.di``,
5
+ ``sandloom.core.facade``, ``sandloom.core.module_api``, ``sandloom.core.descriptors``,
6
+ ``sandloom.core.orm``, ``sandloom.core.projections``); infrastructure is reached through
7
+ ``sandloom.core.di`` and the capability registry — never via concrete-backend
8
+ globals. Importing a submodule costs only that submodule, so the static tools
9
+ (``sandloom add``, ``sandloom new``, ``sandloom check``) never build ``settings``.
10
+ """
@@ -0,0 +1,6 @@
1
+ """Framework-internal core modules — not a public API surface.
2
+
3
+ Nothing here is importable by business modules (an architecture test enforces
4
+ it). These modules exist for the composition root and for tests that override
5
+ raw dependencies via ``app.dependency_overrides``.
6
+ """
@@ -0,0 +1,53 @@
1
+ """Default-database raw request dependency (framework-internal).
2
+
3
+ ``get_db`` is the raw session provider the request UoW wraps. It lives under
4
+ ``sandloom.core._internal`` deliberately: it is NOT a public surface. Only the
5
+ composition root (``create_app``) and test conftests touch it — the latter to
6
+ override it via ``app.dependency_overrides``. The engine/sessionmaker it uses
7
+ are owned and constructed by the database DRIVER
8
+ (``sandloom.core.drivers.sqlalchemy_database``); this module holds no engine of
9
+ its own. Business modules use ``DbSession`` from ``sandloom.core.di`` instead.
10
+ """
11
+
12
+ from collections.abc import AsyncGenerator
13
+ from typing import Any
14
+
15
+ from sqlalchemy.ext.asyncio import AsyncSession
16
+
17
+ from sandloom.core.drivers.sqlalchemy_database import (
18
+ build_disposable_engine,
19
+ get_default_sessionmaker,
20
+ release_default_pools,
21
+ )
22
+
23
+
24
+ async def get_db() -> AsyncGenerator[AsyncSession, None]:
25
+ async with get_default_sessionmaker()() as session:
26
+ yield session
27
+
28
+
29
+ def is_relational_session(value: Any) -> bool:
30
+ """True if ``value`` is a relational (UoW) session instance.
31
+
32
+ Lets paradigm-agnostic kernel code (e.g. the RPC proxy) recognise an
33
+ injected database session without importing SQLAlchemy itself — the
34
+ relational session type stays known only to the relational surface.
35
+ """
36
+ return isinstance(value, AsyncSession)
37
+
38
+
39
+ def is_relational_session_type(annotation: Any) -> bool:
40
+ """True if ``annotation`` is the relational session type (see above)."""
41
+ return annotation is AsyncSession
42
+
43
+
44
+ # Test-harness seams (``sandloom.core.testing``): the harness reaches the driver's
45
+ # default pools and a caller-owned engine through this adapter, so no other
46
+ # kernel module needs to import a concrete driver.
47
+ __all__ = [
48
+ "build_disposable_engine",
49
+ "get_db",
50
+ "is_relational_session",
51
+ "is_relational_session_type",
52
+ "release_default_pools",
53
+ ]
@@ -0,0 +1,5 @@
1
+ """Offline admin manifest compiler; no ORM, lifespan or production discovery."""
2
+
3
+ from .compiler import compile_app, compile_resources
4
+
5
+ __all__ = ["compile_app", "compile_resources"]
@@ -0,0 +1 @@
1
+ """Authenticated operator HTTP surface, separate from internal probes."""