graphcore-kernel 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (343) hide show
  1. graphcore/__init__.py +5 -0
  2. graphcore/agent_frontend/__init__.py +8 -0
  3. graphcore/agent_frontend/api.py +69 -0
  4. graphcore/agent_frontend/base/__init__.py +11 -0
  5. graphcore/agent_frontend/base/views.py +167 -0
  6. graphcore/agent_frontend/client.py +31 -0
  7. graphcore/agent_frontend/context.py +157 -0
  8. graphcore/agent_frontend/errors.py +12 -0
  9. graphcore/agent_frontend/loading.py +54 -0
  10. graphcore/agent_frontend/registry.py +42 -0
  11. graphcore/agent_frontend/render.py +207 -0
  12. graphcore/agent_frontend/server.py +103 -0
  13. graphcore/agent_frontend/signatures.py +35 -0
  14. graphcore/agent_frontend/testing.py +45 -0
  15. graphcore/agent_frontend/tests/__init__.py +0 -0
  16. graphcore/agent_frontend/tests/fakes.py +114 -0
  17. graphcore/agent_frontend/tests/test_frontend.py +447 -0
  18. graphcore/agent_frontend/tests/test_loading.py +83 -0
  19. graphcore/agent_frontend/tests/test_server.py +109 -0
  20. graphcore/agent_frontend/tools.py +137 -0
  21. graphcore/api/__init__.py +4 -0
  22. graphcore/api/graph_api.py +378 -0
  23. graphcore/api/predicate_codec.py +81 -0
  24. graphcore/api/tests/__init__.py +0 -0
  25. graphcore/api/tests/test_changed_entities.py +109 -0
  26. graphcore/api/tests/test_graph_api.py +290 -0
  27. graphcore/api/tests/test_graph_api_access.py +94 -0
  28. graphcore/api/tests/test_graph_api_grants.py +90 -0
  29. graphcore/api/tests/test_predicate_codec.py +83 -0
  30. graphcore/api/tests/test_subtree_query.py +79 -0
  31. graphcore/apps.py +71 -0
  32. graphcore/auth/__init__.py +1 -0
  33. graphcore/auth/authn/README.md +178 -0
  34. graphcore/auth/authn/__init__.py +3 -0
  35. graphcore/auth/authn/authenticator.py +120 -0
  36. graphcore/auth/authn/onboarding.py +105 -0
  37. graphcore/auth/authn/principals.py +20 -0
  38. graphcore/auth/authn/resource_metadata.py +43 -0
  39. graphcore/auth/authn/service_accounts.py +96 -0
  40. graphcore/auth/authn/testing.py +96 -0
  41. graphcore/auth/authn/tests/__init__.py +0 -0
  42. graphcore/auth/authn/tests/test_authenticator.py +145 -0
  43. graphcore/auth/authn/tests/test_onboarding.py +145 -0
  44. graphcore/auth/authn/tests/test_service_accounts.py +180 -0
  45. graphcore/auth/authn/users.py +59 -0
  46. graphcore/auth/authz/__init__.py +0 -0
  47. graphcore/auth/authz/access_port.py +120 -0
  48. graphcore/auth/authz/adapter/__init__.py +0 -0
  49. graphcore/auth/authz/adapter/default_access_adapter.py +556 -0
  50. graphcore/auth/authz/adapter/tests/__init__.py +0 -0
  51. graphcore/auth/authz/adapter/tests/test_default_adapter.py +543 -0
  52. graphcore/auth/authz/adapter/tests/test_entity_write_hooks.py +207 -0
  53. graphcore/auth/authz/adapter/tests/test_group_types.py +70 -0
  54. graphcore/auth/authz/adapter/tests/test_sync_support.py +209 -0
  55. graphcore/auth/authz/defaults.py +26 -0
  56. graphcore/auth/authz/kernel_policy.py +191 -0
  57. graphcore/auth/authz/kernel_writes.py +31 -0
  58. graphcore/auth/authz/lookups.py +25 -0
  59. graphcore/auth/authz/policy.py +403 -0
  60. graphcore/auth/authz/tests/__init__.py +0 -0
  61. graphcore/auth/authz/tests/test_can_contain.py +150 -0
  62. graphcore/auth/authz/tests/test_contained_by.py +167 -0
  63. graphcore/auth/authz/tests/test_creation.py +391 -0
  64. graphcore/auth/authz/tests/test_delete_permission.py +82 -0
  65. graphcore/auth/authz/tests/test_granted_to_me.py +160 -0
  66. graphcore/auth/authz/tests/test_integration.py +637 -0
  67. graphcore/auth/authz/tests/test_invites.py +184 -0
  68. graphcore/auth/authz/tests/test_kernel_policy.py +140 -0
  69. graphcore/auth/authz/tests/test_lockout.py +132 -0
  70. graphcore/auth/authz/tests/test_policy.py +329 -0
  71. graphcore/auth/authz/tests/test_primitives.py +73 -0
  72. graphcore/auth/authz/tests/test_principal_creation.py +62 -0
  73. graphcore/bootstrap/__init__.py +0 -0
  74. graphcore/bootstrap/deployment.py +67 -0
  75. graphcore/bootstrap/signals.py +16 -0
  76. graphcore/bootstrap/tests/__init__.py +0 -0
  77. graphcore/bootstrap/tests/test_deployment_seed.py +154 -0
  78. graphcore/broadcast/__init__.py +4 -0
  79. graphcore/broadcast/broadcaster.py +201 -0
  80. graphcore/broadcast/channels.py +56 -0
  81. graphcore/broadcast/tests/__init__.py +0 -0
  82. graphcore/broadcast/tests/test_broadcaster.py +444 -0
  83. graphcore/celery.py +14 -0
  84. graphcore/docs/AGENT_FRONTEND_TDD.md +389 -0
  85. graphcore/docs/ARCHITECTURE_PRINCIPLES.md +152 -0
  86. graphcore/docs/AUTHORIZATION_TECHNICAL_TDD.md +1379 -0
  87. graphcore/docs/ENTITY_REFERENCE_TDD.md +561 -0
  88. graphcore/docs/GRAPHAPI_FRONT_DOOR.md +173 -0
  89. graphcore/docs/RUNTIME.md +90 -0
  90. graphcore/docs/SCHEDULING_TDD.md +244 -0
  91. graphcore/docs/STRATEGY_EXECUTION_TDD.md +1043 -0
  92. graphcore/docs/VIEW_ENTITY_TDD.md +522 -0
  93. graphcore/docs/VIEW_SYSTEM_TDD.md +307 -0
  94. graphcore/docs/__init__.py +0 -0
  95. graphcore/docs/doc_topics.py +97 -0
  96. graphcore/docs/docs_discovery.py +64 -0
  97. graphcore/docs/public_api.py +56 -0
  98. graphcore/domain/__init__.py +0 -0
  99. graphcore/domain/entity/Entity.py +204 -0
  100. graphcore/domain/entity/__init__.py +0 -0
  101. graphcore/domain/entity/deployment/Deployment.py +25 -0
  102. graphcore/domain/entity/deployment/__init__.py +0 -0
  103. graphcore/domain/entity/grant/Grant.py +31 -0
  104. graphcore/domain/entity/grant/__init__.py +0 -0
  105. graphcore/domain/entity/group/Group.py +48 -0
  106. graphcore/domain/entity/group/README.md +88 -0
  107. graphcore/domain/entity/group/__init__.py +0 -0
  108. graphcore/domain/entity/invite/Invite.py +31 -0
  109. graphcore/domain/entity/invite/__init__.py +0 -0
  110. graphcore/domain/entity/request_template/RequestTemplate.py +48 -0
  111. graphcore/domain/entity/request_template/__init__.py +0 -0
  112. graphcore/domain/entity/request_template/tests/__init__.py +0 -0
  113. graphcore/domain/entity/request_template/tests/test_request_template.py +52 -0
  114. graphcore/domain/entity/service_account/ServiceAccount.py +41 -0
  115. graphcore/domain/entity/service_account/__init__.py +0 -0
  116. graphcore/domain/entity/strategy_request/StrategyRequest.py +61 -0
  117. graphcore/domain/entity/strategy_request/__init__.py +0 -0
  118. graphcore/domain/entity/strategy_request/tests/__init__.py +0 -0
  119. graphcore/domain/entity/strategy_request/tests/test_strategy_request_entity.py +35 -0
  120. graphcore/domain/entity/tests/__init__.py +0 -0
  121. graphcore/domain/entity/tests/test_entity.py +227 -0
  122. graphcore/domain/entity/tests/test_grant_group_entities.py +36 -0
  123. graphcore/domain/entity/tests/test_write_once_fields.py +98 -0
  124. graphcore/domain/entity/user/User.py +39 -0
  125. graphcore/domain/entity/user/__init__.py +0 -0
  126. graphcore/domain/entity/user/tests/__init__.py +0 -0
  127. graphcore/domain/entity/user/tests/test_user_entity.py +33 -0
  128. graphcore/domain/entity/view/View.py +37 -0
  129. graphcore/domain/entity/view/__init__.py +0 -0
  130. graphcore/domain/entity/view/position.py +78 -0
  131. graphcore/domain/entity/view/tests/__init__.py +0 -0
  132. graphcore/domain/entity/view/tests/test_position.py +71 -0
  133. graphcore/domain/entity/view/tests/test_view_entity.py +134 -0
  134. graphcore/domain/strategy/BaseStrategy.py +759 -0
  135. graphcore/domain/strategy/DeploymentStrategies.py +55 -0
  136. graphcore/domain/strategy/GrantStrategies.py +189 -0
  137. graphcore/domain/strategy/GroupStrategies.py +193 -0
  138. graphcore/domain/strategy/InviteStrategies.py +84 -0
  139. graphcore/domain/strategy/RequestTemplateStrategies.py +126 -0
  140. graphcore/domain/strategy/ViewStrategies.py +219 -0
  141. graphcore/domain/strategy/__init__.py +0 -0
  142. graphcore/domain/strategy/runner.py +84 -0
  143. graphcore/domain/strategy/session.py +56 -0
  144. graphcore/domain/strategy/tests/BaseStrategyTest.py +167 -0
  145. graphcore/domain/strategy/tests/__init__.py +0 -0
  146. graphcore/domain/strategy/tests/test_BaseStrategies.py +870 -0
  147. graphcore/domain/strategy/tests/test_grant_strategies.py +245 -0
  148. graphcore/domain/strategy/tests/test_group_strategies.py +99 -0
  149. graphcore/domain/strategy/tests/test_runner.py +220 -0
  150. graphcore/domain/strategy/tests/test_strategy_locks.py +446 -0
  151. graphcore/domain/strategy/tests/test_utils.py +95 -0
  152. graphcore/domain/strategy/tests/test_view_strategies.py +436 -0
  153. graphcore/errors.py +145 -0
  154. graphcore/execution/README.md +97 -0
  155. graphcore/execution/StrategyExecutorService.py +333 -0
  156. graphcore/execution/__init__.py +0 -0
  157. graphcore/execution/dispatcher.py +19 -0
  158. graphcore/execution/environments/__init__.py +0 -0
  159. graphcore/execution/environments/celery.py +59 -0
  160. graphcore/execution/environments/in_process.py +55 -0
  161. graphcore/execution/local_session.py +117 -0
  162. graphcore/execution/redis_run_events.py +74 -0
  163. graphcore/execution/requests.py +22 -0
  164. graphcore/execution/run_events.py +85 -0
  165. graphcore/execution/strategy_context.py +54 -0
  166. graphcore/execution/tasks.py +34 -0
  167. graphcore/execution/tests/__init__.py +5 -0
  168. graphcore/execution/tests/contract.py +171 -0
  169. graphcore/execution/tests/support.py +310 -0
  170. graphcore/execution/tests/test_dispatchers.py +76 -0
  171. graphcore/execution/tests/test_executor.py +368 -0
  172. graphcore/execution/tests/test_local_session.py +95 -0
  173. graphcore/execution/tests/test_reconcile_runs.py +134 -0
  174. graphcore/execution/tests/test_run_events.py +106 -0
  175. graphcore/execution/tests/test_strategy_context.py +62 -0
  176. graphcore/gateway/__init__.py +1 -0
  177. graphcore/gateway/remote.py +35 -0
  178. graphcore/gateway/tests/__init__.py +0 -0
  179. graphcore/gateway/tests/test_remote.py +30 -0
  180. graphcore/graph/EntityService.py +710 -0
  181. graphcore/graph/__init__.py +0 -0
  182. graphcore/graph/entity_cache.py +152 -0
  183. graphcore/graph/tests/__init__.py +4 -0
  184. graphcore/graph/tests/test_EntityService.py +908 -0
  185. graphcore/graph/tests/test_EntityService_list.py +170 -0
  186. graphcore/graph/tests/test_EntityService_model_resolution.py +339 -0
  187. graphcore/graph/tests/test_EntityService_referrers.py +236 -0
  188. graphcore/graph/tests/test_EntityService_routing.py +119 -0
  189. graphcore/graph/tests/test_dependent_on.py +141 -0
  190. graphcore/graph/tests/test_engine_is_type_agnostic.py +25 -0
  191. graphcore/graph/tests/test_engine_resolves_read_permission.py +93 -0
  192. graphcore/graph/tests/test_entity_cache.py +159 -0
  193. graphcore/graph/tests/test_null_entity_cache.py +12 -0
  194. graphcore/management/__init__.py +0 -0
  195. graphcore/management/commands/__init__.py +0 -0
  196. graphcore/management/commands/dev_reset.py +18 -0
  197. graphcore/management/commands/graphcore_createadmin.py +65 -0
  198. graphcore/management/commands/graphcore_policy.py +59 -0
  199. graphcore/management/commands/graphcore_status.py +98 -0
  200. graphcore/management/tests/__init__.py +0 -0
  201. graphcore/management/tests/test_createadmin.py +78 -0
  202. graphcore/management/tests/test_policy_command.py +46 -0
  203. graphcore/management/tests/test_status_command.py +85 -0
  204. graphcore/migrations/0001_initial.py +186 -0
  205. graphcore/migrations/0002_invite.py +26 -0
  206. graphcore/migrations/__init__.py +0 -0
  207. graphcore/models.py +11 -0
  208. graphcore/persistence/ENTITY_REPOSITORY_TECHNICAL_TDD.md +396 -0
  209. graphcore/persistence/__init__.py +6 -0
  210. graphcore/persistence/django/__init__.py +0 -0
  211. graphcore/persistence/django/backends.py +43 -0
  212. graphcore/persistence/django/bindings.py +28 -0
  213. graphcore/persistence/django/cache.py +38 -0
  214. graphcore/persistence/django/compiler.py +214 -0
  215. graphcore/persistence/django/identity.py +18 -0
  216. graphcore/persistence/django/models.py +252 -0
  217. graphcore/persistence/django/repository.py +525 -0
  218. graphcore/persistence/django/tests/__init__.py +0 -0
  219. graphcore/persistence/django/tests/test_backends.py +68 -0
  220. graphcore/persistence/django/tests/test_compiler.py +269 -0
  221. graphcore/persistence/django/tests/test_repository.py +472 -0
  222. graphcore/persistence/django/tests/test_shared_column.py +120 -0
  223. graphcore/persistence/django/tests/test_threads.py +50 -0
  224. graphcore/persistence/django/tests/test_update_shape.py +175 -0
  225. graphcore/persistence/django/threads.py +38 -0
  226. graphcore/persistence/repository.py +172 -0
  227. graphcore/persistence/tests/__init__.py +0 -0
  228. graphcore/persistence/tests/contract.py +688 -0
  229. graphcore/persistence/tests/evaluate.py +51 -0
  230. graphcore/persistence/tests/fixtures.py +32 -0
  231. graphcore/persistence/tests/memory.py +263 -0
  232. graphcore/persistence/tests/test_memory_repository.py +10 -0
  233. graphcore/persistence/tests/test_query_types.py +127 -0
  234. graphcore/public/__init__.py +9 -0
  235. graphcore/public/api.py +9 -0
  236. graphcore/public/apps.py +10 -0
  237. graphcore/public/auth/__init__.py +1 -0
  238. graphcore/public/auth/grants.py +7 -0
  239. graphcore/public/auth/onboarding.py +8 -0
  240. graphcore/public/auth/perms.py +7 -0
  241. graphcore/public/auth/policy.py +10 -0
  242. graphcore/public/auth/roles.py +8 -0
  243. graphcore/public/auth/subjects.py +7 -0
  244. graphcore/public/entities/__init__.py +32 -0
  245. graphcore/public/errors.py +19 -0
  246. graphcore/public/persistence/__init__.py +44 -0
  247. graphcore/public/persistence/django.py +24 -0
  248. graphcore/public/scheduling.py +23 -0
  249. graphcore/public/strategies/__init__.py +85 -0
  250. graphcore/public/test_settings.py +16 -0
  251. graphcore/public/testing.py +47 -0
  252. graphcore/registry/EntityDirectory.py +246 -0
  253. graphcore/registry/README.md +147 -0
  254. graphcore/registry/StrategyDirectory.py +308 -0
  255. graphcore/registry/TYPE_METADATA_PLACEMENT.md +66 -0
  256. graphcore/registry/__init__.py +0 -0
  257. graphcore/registry/app_discovery.py +108 -0
  258. graphcore/registry/decorators.py +77 -0
  259. graphcore/registry/discovery.py +111 -0
  260. graphcore/registry/registry.py +79 -0
  261. graphcore/registry/tests/__init__.py +0 -0
  262. graphcore/registry/tests/test_agent_frontend_discovery.py +56 -0
  263. graphcore/registry/tests/test_app_config.py +36 -0
  264. graphcore/registry/tests/test_discovery.py +147 -0
  265. graphcore/registry/tests/test_entity_directory_storage.py +73 -0
  266. graphcore/registry/tests/test_import_package.py +87 -0
  267. graphcore/registry/tests/test_principal_flag.py +67 -0
  268. graphcore/registry/tests/test_strategy_directory.py +29 -0
  269. graphcore/routes/__init__.py +116 -0
  270. graphcore/routes/tests/__init__.py +0 -0
  271. graphcore/routes/tests/test_routes.py +90 -0
  272. graphcore/runtime.py +243 -0
  273. graphcore/scheduling/__init__.py +0 -0
  274. graphcore/scheduling/beat_scheduler.py +164 -0
  275. graphcore/scheduling/beat_tasks.py +63 -0
  276. graphcore/scheduling/scheduler.py +37 -0
  277. graphcore/scheduling/tests/__init__.py +0 -0
  278. graphcore/scheduling/tests/contract.py +136 -0
  279. graphcore/scheduling/tests/memory.py +42 -0
  280. graphcore/scheduling/tests/test_beat_scheduler.py +87 -0
  281. graphcore/scheduling/tests/test_memory_scheduler.py +15 -0
  282. graphcore/scheduling/tests/test_ticks.py +143 -0
  283. graphcore/tasks.py +9 -0
  284. graphcore/test_settings.py +78 -0
  285. graphcore/testing/__init__.py +0 -0
  286. graphcore/testing/case.py +112 -0
  287. graphcore/testing/runner.py +32 -0
  288. graphcore/testing/settings.py +26 -0
  289. graphcore/testing/tests/__init__.py +0 -0
  290. graphcore/testing/tests/agent_view_fixture.py +19 -0
  291. graphcore/testing/tests/test_case_and_runner.py +219 -0
  292. graphcore/testing/tests/test_settings_for_apps.py +50 -0
  293. graphcore/tests/__init__.py +0 -0
  294. graphcore/tests/ids.py +14 -0
  295. graphcore/tests/public_api_manifest.py +102 -0
  296. graphcore/tests/runs.py +7 -0
  297. graphcore/tests/test_app_discovery.py +90 -0
  298. graphcore/tests/test_composition_boundaries.py +231 -0
  299. graphcore/tests/test_docs_discovery.py +108 -0
  300. graphcore/tests/test_no_print.py +70 -0
  301. graphcore/tests/test_packaging.py +64 -0
  302. graphcore/tests/test_public_api_boundaries.py +229 -0
  303. graphcore/tests/test_public_api_contract.py +62 -0
  304. graphcore/tests/test_public_api_docs.py +28 -0
  305. graphcore/tests/test_runtime.py +42 -0
  306. graphcore/tests/test_shared_type_boundaries.py +128 -0
  307. graphcore/tests/test_shared_types.py +144 -0
  308. graphcore/tests/test_test_settings.py +45 -0
  309. graphcore/transport/__init__.py +0 -0
  310. graphcore/transport/agent_asgi.py +68 -0
  311. graphcore/transport/agent_client.py +85 -0
  312. graphcore/transport/channel_layer.py +68 -0
  313. graphcore/transport/consumers.py +507 -0
  314. graphcore/transport/routing.py +6 -0
  315. graphcore/transport/tests/__init__.py +0 -0
  316. graphcore/transport/tests/test_agent_client.py +31 -0
  317. graphcore/transport/tests/test_api_views.py +733 -0
  318. graphcore/transport/tests/test_channel_layer.py +96 -0
  319. graphcore/transport/tests/test_consumers.py +963 -0
  320. graphcore/transport/tests/test_resource_metadata.py +67 -0
  321. graphcore/transport/urls.py +29 -0
  322. graphcore/transport/views.py +358 -0
  323. graphcore/types/__init__.py +4 -0
  324. graphcore/types/access.py +114 -0
  325. graphcore/types/api.py +76 -0
  326. graphcore/types/entities.py +100 -0
  327. graphcore/types/entity_id.py +85 -0
  328. graphcore/types/execution.py +41 -0
  329. graphcore/types/identity.py +20 -0
  330. graphcore/types/onboarding.py +20 -0
  331. graphcore/types/query.py +116 -0
  332. graphcore/types/schedules.py +91 -0
  333. graphcore/types/strategy.py +73 -0
  334. graphcore/types/tests/__init__.py +0 -0
  335. graphcore/types/tests/test_entity_id.py +50 -0
  336. graphcore/urls.py +5 -0
  337. graphcore_kernel-0.1.0.dist-info/METADATA +94 -0
  338. graphcore_kernel-0.1.0.dist-info/RECORD +343 -0
  339. graphcore_kernel-0.1.0.dist-info/WHEEL +5 -0
  340. graphcore_kernel-0.1.0.dist-info/entry_points.txt +2 -0
  341. graphcore_kernel-0.1.0.dist-info/licenses/LICENSE +202 -0
  342. graphcore_kernel-0.1.0.dist-info/licenses/NOTICE +2 -0
  343. graphcore_kernel-0.1.0.dist-info/top_level.txt +1 -0
@@ -0,0 +1,186 @@
1
+ # Generated by Django 5.2.17 on 2026-10-16 16:01
2
+
3
+ import django.contrib.postgres.indexes
4
+ import django.db.models.deletion
5
+ import graphcore.types.entity_id
6
+ from django.db import migrations, models
7
+
8
+
9
+ class Migration(migrations.Migration):
10
+
11
+ initial = True
12
+
13
+ dependencies = [
14
+ ]
15
+
16
+ operations = [
17
+ migrations.CreateModel(
18
+ name='BackendIdentityModel',
19
+ fields=[
20
+ ('backend_id', models.CharField(default=graphcore.types.entity_id.new_backend_id, editable=False, max_length=10, primary_key=True, serialize=False)),
21
+ ('singleton', models.BooleanField(default=True, unique=True)),
22
+ ],
23
+ ),
24
+ migrations.CreateModel(
25
+ name='EntityModel',
26
+ fields=[
27
+ ('entity_id', models.CharField(editable=False, max_length=96, primary_key=True, serialize=False)),
28
+ ('attributes', models.JSONField(db_column='attributes', default=dict)),
29
+ ('parent_id', models.CharField(blank=True, db_index=True, max_length=255, null=True)),
30
+ ('sibling_position', models.FloatField(default=0.0)),
31
+ ('ancestor_ids', models.JSONField(default=list)),
32
+ ('reference_ids', models.JSONField(default=list)),
33
+ ('created_at', models.DateTimeField(auto_now_add=True)),
34
+ ('updated_at', models.DateTimeField(auto_now=True)),
35
+ ('entity_type_id', models.CharField(db_index=True, max_length=100)),
36
+ ('version', models.IntegerField(default=0)),
37
+ ('owner', models.CharField(blank=True, max_length=200, null=True)),
38
+ ],
39
+ ),
40
+ migrations.CreateModel(
41
+ name='EntityReferenceModel',
42
+ fields=[
43
+ ('pk', models.CompositePrimaryKey('target_id', 'source', blank=True, editable=False, primary_key=True, serialize=False)),
44
+ ('target_id', models.CharField(max_length=96)),
45
+ ('source', models.ForeignKey(db_column='source_id', on_delete=django.db.models.deletion.CASCADE, related_name='references', to='graphcore.entitymodel')),
46
+ ],
47
+ ),
48
+ migrations.CreateModel(
49
+ name='DeploymentModel',
50
+ fields=[
51
+ ('entitymodel_ptr', models.OneToOneField(auto_created=True, on_delete=django.db.models.deletion.CASCADE, parent_link=True, primary_key=True, serialize=False, to='graphcore.entitymodel')),
52
+ ('singleton', models.BooleanField(default=True, editable=False, unique=True)),
53
+ ('new_user_group_ids', models.JSONField(default=list)),
54
+ ('new_user_roles', models.JSONField(default=list)),
55
+ ],
56
+ bases=('graphcore.entitymodel',),
57
+ ),
58
+ migrations.CreateModel(
59
+ name='GrantModel',
60
+ fields=[
61
+ ('entitymodel_ptr', models.OneToOneField(auto_created=True, on_delete=django.db.models.deletion.CASCADE, parent_link=True, primary_key=True, serialize=False, to='graphcore.entitymodel')),
62
+ ('subject_id', models.CharField(max_length=255)),
63
+ ('role_name', models.CharField(max_length=100)),
64
+ ],
65
+ bases=('graphcore.entitymodel',),
66
+ ),
67
+ migrations.CreateModel(
68
+ name='GroupModel',
69
+ fields=[
70
+ ('entitymodel_ptr', models.OneToOneField(auto_created=True, on_delete=django.db.models.deletion.CASCADE, parent_link=True, primary_key=True, serialize=False, to='graphcore.entitymodel')),
71
+ ('name', models.CharField(blank=True, max_length=255, null=True)),
72
+ ('key', models.CharField(blank=True, max_length=150, null=True)),
73
+ ('member_ids', models.JSONField(default=list)),
74
+ ],
75
+ bases=('graphcore.entitymodel',),
76
+ ),
77
+ migrations.CreateModel(
78
+ name='RequestTemplateModel',
79
+ fields=[
80
+ ('entitymodel_ptr', models.OneToOneField(auto_created=True, on_delete=django.db.models.deletion.CASCADE, parent_link=True, primary_key=True, serialize=False, to='graphcore.entitymodel')),
81
+ ('strategy_name', models.CharField(max_length=255)),
82
+ ('param_config', models.JSONField(default=dict)),
83
+ ('target_entity_id', models.CharField(blank=True, db_index=True, max_length=255, null=True)),
84
+ ('callbacks', models.JSONField(default=list)),
85
+ ('cron', models.CharField(blank=True, max_length=100, null=True)),
86
+ ('enabled', models.BooleanField(default=True)),
87
+ ],
88
+ bases=('graphcore.entitymodel',),
89
+ ),
90
+ migrations.CreateModel(
91
+ name='StrategyRequestModel',
92
+ fields=[
93
+ ('entitymodel_ptr', models.OneToOneField(auto_created=True, on_delete=django.db.models.deletion.CASCADE, parent_link=True, primary_key=True, serialize=False, to='graphcore.entitymodel')),
94
+ ('strategy_name', models.CharField(max_length=255)),
95
+ ('param_config', models.JSONField(default=dict)),
96
+ ('target_entity_id', models.CharField(blank=True, max_length=255, null=True)),
97
+ ('callbacks', models.JSONField(default=list)),
98
+ ('callback_channel', models.CharField(blank=True, max_length=255, null=True)),
99
+ ('client_request_id', models.CharField(blank=True, max_length=255, null=True)),
100
+ ('status', models.CharField(default='pending', max_length=16)),
101
+ ('attempt', models.IntegerField(default=0)),
102
+ ('attempt_deadline', models.FloatField(blank=True, null=True)),
103
+ ('ret_val', models.JSONField(default=dict)),
104
+ ('error', models.TextField(blank=True, null=True)),
105
+ ('error_code', models.CharField(blank=True, max_length=64, null=True)),
106
+ ('error_details', models.JSONField(default=dict)),
107
+ ('template_id', models.CharField(blank=True, max_length=255, null=True)),
108
+ ],
109
+ bases=('graphcore.entitymodel',),
110
+ ),
111
+ migrations.CreateModel(
112
+ name='UserModel',
113
+ fields=[
114
+ ('entitymodel_ptr', models.OneToOneField(auto_created=True, on_delete=django.db.models.deletion.CASCADE, parent_link=True, primary_key=True, serialize=False, to='graphcore.entitymodel')),
115
+ ('username', models.CharField(blank=True, max_length=150, null=True)),
116
+ ('issuer', models.CharField(blank=True, max_length=255, null=True)),
117
+ ('subject', models.CharField(blank=True, max_length=255, null=True)),
118
+ ],
119
+ bases=('graphcore.entitymodel',),
120
+ ),
121
+ migrations.CreateModel(
122
+ name='ServiceAccountModel',
123
+ fields=[
124
+ ('entitymodel_ptr', models.OneToOneField(auto_created=True, on_delete=django.db.models.deletion.CASCADE, parent_link=True, primary_key=True, serialize=False, to='graphcore.entitymodel')),
125
+ ('app_id', models.CharField(blank=True, max_length=100, null=True)),
126
+ ('client_name', models.CharField(blank=True, max_length=100, null=True)),
127
+ ('client_id', models.CharField(blank=True, max_length=255, null=True)),
128
+ ('issuer', models.CharField(blank=True, max_length=255, null=True)),
129
+ ],
130
+ bases=('graphcore.entitymodel',),
131
+ ),
132
+ migrations.CreateModel(
133
+ name='ViewModel',
134
+ fields=[
135
+ ('entitymodel_ptr', models.OneToOneField(auto_created=True, on_delete=django.db.models.deletion.CASCADE, parent_link=True, primary_key=True, serialize=False, to='graphcore.entitymodel')),
136
+ ('component', models.CharField(blank=True, max_length=255, null=True)),
137
+ ('renders', models.CharField(blank=True, db_index=True, max_length=255, null=True)),
138
+ ('client', models.CharField(blank=True, max_length=255, null=True)),
139
+ ('slot', models.CharField(blank=True, max_length=255, null=True)),
140
+ ('address', models.CharField(blank=True, max_length=255, null=True)),
141
+ ('position_key', models.CharField(blank=True, max_length=64, null=True)),
142
+ ('state', models.JSONField(default=dict)),
143
+ ],
144
+ bases=('graphcore.entitymodel',),
145
+ ),
146
+ migrations.AddIndex(
147
+ model_name='entitymodel',
148
+ index=django.contrib.postgres.indexes.GinIndex(fields=['ancestor_ids'], name='entitymodel_ancestors_gin'),
149
+ ),
150
+ migrations.AddIndex(
151
+ model_name='entitymodel',
152
+ index=models.Index(fields=['parent_id', 'sibling_position'], name='entitymodel_parent_pos_idx'),
153
+ ),
154
+ migrations.AddIndex(
155
+ model_name='grantmodel',
156
+ index=models.Index(fields=['subject_id'], name='grantmodel_subject_id_idx'),
157
+ ),
158
+ migrations.AddIndex(
159
+ model_name='groupmodel',
160
+ index=django.contrib.postgres.indexes.GinIndex(fields=['member_ids'], name='group_member_ids_gin'),
161
+ ),
162
+ migrations.AddConstraint(
163
+ model_name='groupmodel',
164
+ constraint=models.UniqueConstraint(condition=models.Q(('key__isnull', False)), fields=('key',), name='uniq_group_key'),
165
+ ),
166
+ migrations.AddIndex(
167
+ model_name='strategyrequestmodel',
168
+ index=models.Index(fields=['status', 'attempt_deadline'], name='request_status_deadline_idx'),
169
+ ),
170
+ migrations.AddConstraint(
171
+ model_name='serviceaccountmodel',
172
+ constraint=models.UniqueConstraint(condition=models.Q(('client_id__isnull', False)), fields=('client_id',), name='uniq_service_account_client_id'),
173
+ ),
174
+ migrations.AddConstraint(
175
+ model_name='usermodel',
176
+ constraint=models.UniqueConstraint(condition=models.Q(('issuer__isnull', False), ('subject__isnull', False)), fields=('issuer', 'subject'), name='uniq_user_iss_sub'),
177
+ ),
178
+ migrations.AddIndex(
179
+ model_name='viewmodel',
180
+ index=models.Index(fields=['address', 'client'], name='view_address_client_idx'),
181
+ ),
182
+ migrations.AddConstraint(
183
+ model_name='viewmodel',
184
+ constraint=models.UniqueConstraint(condition=models.Q(('position_key__isnull', False)), fields=('position_key',), name='uniq_view_position_key'),
185
+ ),
186
+ ]
@@ -0,0 +1,26 @@
1
+ # Generated by Django 5.2.17 on 2026-10-20 16:09
2
+
3
+ import django.db.models.deletion
4
+ from django.db import migrations, models
5
+
6
+
7
+ class Migration(migrations.Migration):
8
+
9
+ dependencies = [
10
+ ('graphcore', '0001_initial'),
11
+ ]
12
+
13
+ operations = [
14
+ migrations.CreateModel(
15
+ name='InviteModel',
16
+ fields=[
17
+ ('entitymodel_ptr', models.OneToOneField(auto_created=True, on_delete=django.db.models.deletion.CASCADE, parent_link=True, primary_key=True, serialize=False, to='graphcore.entitymodel')),
18
+ ('role_name', models.CharField(max_length=100)),
19
+ ('token_hash', models.CharField(max_length=64)),
20
+ ('expires_at', models.FloatField(blank=True, null=True)),
21
+ ('max_uses', models.IntegerField(default=1)),
22
+ ('redeemed_by', models.JSONField(default=list)),
23
+ ],
24
+ bases=('graphcore.entitymodel',),
25
+ ),
26
+ ]
File without changes
graphcore/models.py ADDED
@@ -0,0 +1,11 @@
1
+ """Django loads this module to discover the app's models."""
2
+
3
+ from graphcore.persistence.django.models import (
4
+ EntityModel, GrantModel, GroupModel, InviteModel, RequestTemplateModel, StrategyRequestModel,
5
+ UserModel,
6
+ )
7
+
8
+ __all__ = [
9
+ 'EntityModel', 'GrantModel', 'GroupModel', 'InviteModel', 'RequestTemplateModel',
10
+ 'StrategyRequestModel', 'UserModel',
11
+ ]
@@ -0,0 +1,396 @@
1
+ # Entity Repository Technical Design
2
+
3
+ ## Introduction
4
+
5
+ The entity repository separates entity persistence from database
6
+ technology. Callers describe what they want with a small predicate
7
+ vocabulary; a backend compiles those predicates into database operations.
8
+ `EntityService` conjoins caller criteria (including an optional app
9
+ predicate, `EntityFilter.where`) with the predicate `AccessPort` produces
10
+ and hands the whole thing to the repository as one query. The repository
11
+ interprets relational operations only — it does not know what a role, a
12
+ grant, or an owner means.
13
+
14
+ ## Definitions
15
+
16
+ These name ordinary responsibilities; none implies an extra service or a
17
+ persisted GraphCore entity.
18
+
19
+ - **EntityRepository:** Loads and saves entities. Executes predicates; decides nothing.
20
+ - **Backend identity:** The immutable identifier minted into the store when it was initialised, reported by `backend_id()`. Identifiers are opaque strings to the repository; it parses and routes nothing.
21
+ - **Record:** An entity's own `to_dict()` — the complete, JSON-compatible, round-trippable state. No mapper, no separate record type.
22
+ - **Storage:** `EntityDirectory.bind_storage(entity_cls, storage)` — an opaque handle per entity class, a Django model class for the Django repository.
23
+ - **Predicate:** A filter condition over entity fields, e.g. `Equal('owner', principal)`.
24
+ - **EntityQuery:** A predicate plus a `PageRequest`, returning whole entities.
25
+ - **PageRequest:** A positive `limit` and an optional keyset `cursor`.
26
+ - **SaveReceipt / DeleteReceipt:** Detached facts about a committed write — what it replaced, what it touched, what it removed. Not a promise that any later access or cache update succeeded.
27
+ - **Cover:** `{entity} ∪ ancestor_ids(entity)`. A read of entity fields, not a table.
28
+
29
+ ## Requirements
30
+
31
+ 1. Domain entities, the query vocabulary, `AccessPort` and `EntityService` do not depend on Django querysets, models, `Q` expressions, or SQL.
32
+ 2. `AccessPort` produces predicates; `EntityService` combines them (including `EntityFilter.where`); `EntityRepository` executes them. There is no separate access repository.
33
+ 3. The repository interprets relational operations, not roles, permissions, `PUBLIC`, or ownership.
34
+ 4. Filtering, including authorization and any app predicate, happens before pagination — never as a Python filter over an already-sliced page.
35
+ 5. The vocabulary extends by adding a node type and a handler per backend, not by changing method signatures. Filterable fields extend by binding a model with the column, not by editing the compiler.
36
+ 6. An unsupported node or an unbound field fails explicitly, before execution. No condition is ever dropped or treated as true.
37
+ 7. Stored records and client projections stay distinct. Hydration preserves specialized entity behavior, including `User.to_client`'s redaction.
38
+ 8. `EntityService` runs access updates after persistence commits. The repository owns no access storage and coordinates no cross-component rollback.
39
+ 9. Single-parent containment and child-owned order stay authoritative. `children_ids`, `ancestor_ids` and `reference_ids` are derived, and are never written from a record.
40
+ 10. The repository reports the identity of the store it fronts, and stores every id-bearing column — the primary key included — as an opaque string.
41
+
42
+ ## Architecture
43
+
44
+ Paths are relative to `kernel/backend/graphcore`:
45
+
46
+ ```text
47
+ types/query.py # the predicate vocabulary (no Django)
48
+ persistence/
49
+ repository.py # EntityRepository, SaveReceipt, DeleteReceipt, DeletedEntity
50
+ django/
51
+ models.py # the concrete storage models
52
+ compiler.py # QueryCompiler: predicate -> Q, fields derived from bound models
53
+ repository.py # DjangoEntityRepository (column split via _meta)
54
+ bindings.py # kernel storage bindings (Entity/Grant/Group/User/StrategyRequest -> models)
55
+ tests/
56
+ contract.py # the contract every backend must satisfy
57
+ evaluate.py # matches(predicate, record) — the semantic reference
58
+ memory.py # MemoryEntityRepository
59
+ fixtures.py # persist() for tests that bypass EntityService
60
+ registry/EntityDirectory.py # entity registry + bind_storage/storage
61
+ ```
62
+
63
+ Dependency arrows: `auth/authz → persistence`; `persistence` never imports
64
+ `auth/`; `domain/entity` imports neither.
65
+
66
+ ### The query vocabulary
67
+
68
+ Six frozen nodes over plain field names and literal values
69
+ (`str | UUID | bool | int | float | None`). Not a language: no
70
+ field-to-field comparison, no correlation, no projection, no sub-select.
71
+ Every query targets the entity collection.
72
+
73
+ | Node | Meaning |
74
+ | --- | --- |
75
+ | `Equal(field, value)` | equality; `value=None` is an explicit null check |
76
+ | `InValues(field, values)` | membership; empty set matches nothing |
77
+ | `ContainsValue(field, value)` | the collection at `field` holds `value` |
78
+ | `ContainsAny(field, values)` | the collection at `field` overlaps `values` |
79
+ | `AllOf(predicates)` | conjunction; empty is true |
80
+ | `AnyOf(predicates)` | disjunction; empty is false |
81
+
82
+ `EntityFilter` remains the caller-facing criteria type (`type_ids`,
83
+ `parent_id`, an optional `where: Predicate | None`, and `granted_to_me`);
84
+ `Predicate.from_filter(criteria)` converts it, appending `where` last when set.
85
+ `granted_to_me` depends on the caller, so `EntityService.list_entities`
86
+ resolves it into an `InValues('entity_id', ...)` before conversion and
87
+ `from_filter` refuses a filter that still carries it.
88
+
89
+ `persistence/tests/evaluate.matches` is the semantic reference: the shortest
90
+ statement of what each node means. It is test-only — production pushes
91
+ predicates into storage rather than filtering in memory — and every backend
92
+ must agree with it case for case, which `persistence/tests/contract.py`
93
+ enforces. `Equal(field, None)` and `InValues(field, ...)` never match a
94
+ record that doesn't carry the field at all — the same null-check hazard the
95
+ Django compiler closes (below), pinned identically here.
96
+
97
+ #### Wire encoding
98
+
99
+ Clients outside the process send a predicate as JSON, one object per node.
100
+ `/api/list_entities/` and `/api/referrers/` accept it as `where`:
101
+
102
+ ```json
103
+ {"all_of": [
104
+ {"equal": {"field": "slot", "value": "entity"}},
105
+ {"in_values": {"field": "renders", "values": ["gc://k7m2x9qp4n/3fz8a1c0w4ne"]}}
106
+ ]}
107
+ ```
108
+
109
+ | Node | Encoding |
110
+ | --- | --- |
111
+ | `Equal` | `{"equal": {"field": f, "value": v}}`; `null` is an explicit null check |
112
+ | `InValues` | `{"in_values": {"field": f, "values": [...]}}` |
113
+ | `ContainsValue` | `{"contains_value": {"field": f, "value": v}}` |
114
+ | `ContainsAny` | `{"contains_any": {"field": f, "values": [...]}}` |
115
+ | `AllOf` | `{"all_of": [node, ...]}` |
116
+ | `AnyOf` | `{"any_of": [node, ...]}` |
117
+
118
+ Values are JSON scalars. `GraphAPI` decodes the object into a `Predicate`
119
+ and conjoins it with the caller's access predicate exactly as an
120
+ in-process caller's predicate is; a wire predicate never widens access.
121
+
122
+ Invariants:
123
+
124
+ - A field is a plain column name: a base entity column or a typed column of
125
+ the listed types. Paths into JSON structures are not addressable.
126
+ - A malformed node, an unknown node name, or a field the storage adapter
127
+ cannot resolve is refused with `InvalidRequest`, never ignored.
128
+ - A predicate more than 8 levels deep or carrying more than 1,000 values is
129
+ refused with `InvalidRequest`.
130
+
131
+ ### The contract
132
+
133
+ ```python
134
+ class EntityRepository(ABC):
135
+ def backend_id() -> str
136
+ async def load(entity_id) -> Entity | None
137
+ async def load_many(entity_ids) -> dict[str, Entity]
138
+ async def versions(entity_ids) -> dict[str, int]
139
+ async def list_entities(query: EntityQuery) -> EntityPage
140
+ async def list_ids(predicate: Predicate) -> set[str]
141
+ async def descendant_ids(root_id) -> set[str]
142
+ async def referrers(target_id, predicate: Predicate, page: PageRequest) -> EntityPage
143
+ async def save(entity, precondition: Precondition | None = None) -> SaveReceipt
144
+ async def delete_many(entity_ids, precondition: Precondition | None = None) -> DeleteReceipt
145
+ ```
146
+
147
+ `Precondition(entity_id, where)` makes a write conditional on another
148
+ entity: the write takes effect only while the entity `entity_id` matches the
149
+ predicate `where`, and otherwise raises `PreconditionFailed` (a `Conflict`)
150
+ and writes nothing. The check and the write are atomic: the precondition
151
+ entity cannot change between them. The repository knows nothing of what the
152
+ precondition entity is; callers above it give it meaning (the strategy
153
+ session fences each write on its request's attempt this way).
154
+
155
+ `SaveReceipt(entity, previous, created, touched_parent_ids)` is what lets
156
+ `EntityService` run the cache, broadcast and access fallout without
157
+ re-reading storage. `DeleteReceipt` carries one `DeletedEntity` per row it removed
158
+ (`entity_id`, `parent_id`, `entity_type_id`, `owner`, `ancestor_ids`) — what
159
+ each entity *was*, so a tombstone can still be routed to the scopes that
160
+ covered it once the row is gone.
161
+
162
+ ### The `ancestor_ids` invariant
163
+
164
+ The repository owns one derived column:
165
+
166
+ > `ancestor_ids(e) = ancestor_ids(parent) + [parent_id]`, root-first.
167
+
168
+ Recomputed on create and on every `parent_id` change, for the whole
169
+ subtree, in the same save — **without** bumping the descendants' `version`
170
+ or emitting events for them. A move is not a write to the things being
171
+ carried.
172
+
173
+ This is what makes authorization a predicate over entity fields:
174
+ `ContainsAny('ancestor_ids', granted_scopes)` replaces the derived cover
175
+ index that used to be maintained alongside every write. `ancestor_ids` is
176
+ read-only on `Entity` (like `children_ids`), is never present in
177
+ `to_dict()`, only in `to_client()`, and `from_dict` never hydrates it from
178
+ a payload — only the repository sets it, from the row it just read.
179
+
180
+ ### The `reference_ids` projection
181
+
182
+ The repository owns a second derived column, on the same terms:
183
+
184
+ > `reference_ids(e)` = every entity identifier appearing anywhere in
185
+ > `e.to_dict()` other than `e`'s own id, deduplicated and sorted.
186
+
187
+ Rebuilt on every save by `project_reference_ids` (`persistence/repository.py`),
188
+ which both adapters call so they cannot disagree. Every field counts alike —
189
+ `parent_id`, `owner`, a typed column such as a grant's `subject_id`, a value
190
+ nested in the attributes. The derived projections (`ancestor_ids`,
191
+ `children_ids`) are not in `to_dict()` and so never appear. Like
192
+ `ancestor_ids`, it is read-only on `Entity` and `from_dict` never hydrates it
193
+ from a payload.
194
+
195
+ Reverse lookup is the port method `referrers(target_id, predicate, page)`:
196
+ one keyset page of sources, ordered by `entity_id`, with `predicate` applied
197
+ in the same statement before the limit. A target is never read or written
198
+ when a reference to it is created or removed. How the reverse index is
199
+ stored is the adapter's choice; the memory adapter scans.
200
+
201
+ ### Store identity
202
+
203
+ `backend_id()` returns the store's own identity — the singleton
204
+ `BackendIdentityModel` row, whose table migration `0015` creates and whose row
205
+ `graphcore.apps` ensures on `post_migrate`. It is synchronous and read once,
206
+ at composition: `build_runtime` puts it on `Runtime.backend_id` and on
207
+ `EntityService`, whose `create()` mints `gc://<backend_id>/<local_id>` from it.
208
+ See `docs/ENTITY_REFERENCE_TDD.md`.
209
+
210
+ ### Records are `to_dict()`
211
+
212
+ There is no mapper and no separate record type. `Entity.to_dict()` is the
213
+ complete, JSON-compatible, round-trippable state — system fields, typed
214
+ subclass fields, and the attribute bag nested under `attributes`; it never
215
+ includes the derived projections (`children_ids`, `parent_ids`,
216
+ `ancestor_ids`, `reference_ids`), which live only on `to_client()`. `from_dict(data)` is its
217
+ inverse.
218
+
219
+ The Django repository splits a `to_dict()` on write, and reassembles one on
220
+ read, using the bound model's `_meta`:
221
+
222
+ - **Write:** editable concrete columns (by `attname`) receive their matching
223
+ `to_dict()` values, including the nested `attributes` JSON object. An emitted
224
+ field without a model column raises `ImproperlyConfigured`. Primary keys and
225
+ non-editable storage fields are handled by storage, not populated from the bag.
226
+ - **Read:** editable non-primary-key columns, the entity id and the nested bag
227
+ go to `entity_cls.from_dict(...)`. The repository sets `_ancestor_ids` and
228
+ `_reference_ids`, which it owns. Invalid records raise; they are not missing
229
+ entities. Unknown entity types are logged and skipped.
230
+
231
+ `from_dict` accepts declared public instance fields in the serialization
232
+ contract, ignores derived keys, and rejects unknown, private, method and class
233
+ metadata keys. Bag keys never hydrate typed fields, even when their names match.
234
+
235
+ The in-memory repository (`persistence/tests/memory.py`) stores the nested
236
+ `to_dict()` output plus `ancestor_ids`/`reference_ids`/`version`. Insertion order
237
+ is kept separately from the record and never reaches entity hydration.
238
+
239
+ ### Backend specifics (Django)
240
+
241
+ **Supported databases.** `persistence/django/backends.py` lists them:
242
+ PostgreSQL, the reference database, and SQLite. `DjangoEntityRepository`
243
+ refuses to construct on any other, and a Django system check
244
+ (`graphcore.E001`) reports it from `check`, `migrate` and `test`. Where the
245
+ databases differ, the code asks Django's feature flags
246
+ (`connection.features`) and names a database (`connection.vendor`) only
247
+ where Django has no portable answer, such as the Postgres-only GIN indexes
248
+ in migrations 0004 and 0013. Adding a database means adding it to that list
249
+ and passing the tests below on it.
250
+
251
+ `compiler.py`'s `QueryCompiler(entity_directory)` derives filterable fields
252
+ from whatever is actually bound — no hardcoded field list, no kernel
253
+ knowledge in the compiler. On first `compile()`, it walks
254
+ `entity_directory.storage_classes()` and maps every concrete field's
255
+ `attname` to `(prefix, field)`: root `EntityModel` columns map to
256
+ themselves; an MTI child model's columns map through
257
+ `f'{model._meta.model_name}__{attname}'` (e.g. `subject_id` through
258
+ `grantmodel__subject_id`). A name absent from every bound model, or
259
+ present on two different bound models, raises `UnsupportedQuery` before any
260
+ query runs — ambiguity is refused, never resolved as an OR.
261
+
262
+ **Type-pinned resolution.** An `AllOf` that pins `entity_type_id`
263
+ (`Equal` or `InValues`) resolves the field names beneath it against those
264
+ types' bound models (and their MTI parents) plus `EntityModel` only — every
265
+ row it can match is one of those types. `EntityFilter.where` is always
266
+ pinned this way by `Predicate.from_filter`, so two apps may declare the same
267
+ column and each filter on its own. When several pinned types declare the
268
+ name, it matches any of their columns: one clause per column, ORed, each
269
+ child-table null check guarded as below. Columns of different types are
270
+ refused. Unpinned, a name on two bound models is still refused, so
271
+ installing an app never widens an existing query. A pin inside an `AnyOf`
272
+ branch scopes nothing beyond that branch.
273
+
274
+ This refusal is the Django compiler's alone: the reference evaluator reads
275
+ the top-level typed fields of a record without model-column metadata, so it cannot tell which model a name
276
+ belongs to and matches it on any type.
277
+
278
+ **The null-check hazard.** A `LEFT OUTER JOIN` row that doesn't exist for a
279
+ type without that child table is *also* null on every child column, so
280
+ without pinning the join itself, `Equal(child_field, None)` would match
281
+ every other type too. The compiler closes this explicitly:
282
+ `Q(**{f'{model_name}__isnull': False, f'{path}__isnull': True})` — the join
283
+ must exist (the row is of that type) *and* the column on it must be null.
284
+
285
+ Containment (`ContainsValue`/`ContainsAny`) is defined only for `JSONField`
286
+ columns with `default is list`: on `EntityModel` itself (`ancestor_ids`,
287
+ `reference_ids`), and on a child table (`GroupModel.member_ids`) only
288
+ inside an `AllOf` that pins `entity_type_id` to types stored there — pinned,
289
+ every row matched has the child row; unpinned, the compiler refuses it.
290
+ Django's JSON `contains` where
291
+ `connection.features.supports_json_field_contains` (`jsonb @>` on
292
+ PostgreSQL, through the reverse join for a child column, e.g.
293
+ `groupmodel__member_ids__contains`), otherwise a parameterized
294
+ `json_each` scan (SQLite): an `EXISTS` over the base column, or
295
+ `entity_id IN (SELECT <ptr> FROM <child table>, json_each(<child
296
+ table>.member_ids) WHERE json_each.value IN (...))` for a child column.
297
+ `member_ids` and `ancestor_ids` are GIN-indexed; `reference_ids` is not,
298
+ because reverse lookup never queries it.
299
+
300
+ Reverse lookup reads `EntityReferenceModel`, one row per `(target_id, source)`,
301
+ maintained by `save` whenever an entity's `reference_ids` change (written
302
+ after the entity row, outside a transaction; a failure between the two
303
+ leaves the edges stale until the next save). The composite primary key's
304
+ order lets `referrers` walk a target's sources in `entity_id` order and stop
305
+ at the page limit, so its cost is bounded by the target's fan-in however
306
+ broad the access predicate. `source` cascades on delete; `target_id` is not
307
+ a foreign key, because targets may be remote or deleted.
308
+
309
+ `repository.py` never lets a model instance out: reads go through
310
+ `.values()` into records, writes build `model_cls(**record)` or
311
+ `update(**record)` directly from the column/`attributes` split above. The
312
+ update is a compare-and-swap on `(entity_id, version)` with a database-side
313
+ `F('version') + 1`, so optimistic locking is one statement.
314
+
315
+ The row write (insert, update, or delete) runs in one transaction. With a
316
+ precondition, that transaction first locks the precondition row
317
+ (`SELECT … FOR NO KEY UPDATE`) and checks `where` against it, so a
318
+ concurrent write to that row waits for this one to commit, or this one sees
319
+ the row's new state and is refused.
320
+
321
+ **Database threads.** Django runs each async query through
322
+ `sync_to_async(thread_sensitive=True)`. A task that calls
323
+ `use_shared_threads` (`persistence/django/threads.py`; every WebSocket
324
+ connection and in-process run does) spreads its queries over
325
+ `GRAPHCORE_DB_THREADS` threads, each with its own connection, so two awaited
326
+ queries of one task may run on different connections. A transaction, or a
327
+ cursor read over several awaits (`aiterator()`), therefore never spans an
328
+ `await`, in the kernel or in app code: it opens and closes inside one
329
+ synchronous function, as `_insert`, `_write` and `_replace_edges` do in
330
+ `repository.py`.
331
+
332
+ Cursor paging is ascending `entity_id`, `entity_id > cursor`, with a
333
+ `limit + 1` probe; the predicate (type/parent/`where`/access, all conjoined)
334
+ and the limit are in the same `SELECT`.
335
+
336
+ ### Storage binding
337
+
338
+ `EntityDirectory.bind_storage(entity_cls, storage)`, resolved exact match
339
+ first, then the nearest bound ancestor in the MRO — so a subclass that adds
340
+ no columns inherits its parent's binding. Last registration for a class
341
+ wins; binding after the directory closes raises. Discovery runs the same
342
+ loop for every app's `GraphCoreAppConfig.graphcore_persistence` hook, in
343
+ `INSTALLED_APPS` order — the kernel's own bindings
344
+ (`graphcore.persistence.django.bindings.configure`) are configured through
345
+ this identical hook via `GraphCoreConfig`, not a special case.
346
+ `graphcore/runtime.py::django_runtime` is where the backend is chosen; a
347
+ forked test registry gets its own copy of the bindings, so an override
348
+ there never leaks.
349
+
350
+ An app registers its own type like this:
351
+
352
+ ```python
353
+ # app/models.py
354
+ from graphcore.public.persistence.django import EntityModel
355
+ from django.db import models
356
+
357
+ class BoardModel(EntityModel):
358
+ column_order = models.JSONField(default=list)
359
+ ```
360
+
361
+ ```python
362
+ # app/persistence.py
363
+ from app.entities import Board
364
+ from app.models import BoardModel
365
+
366
+ def configure(entities) -> None:
367
+ entities.bind_storage(Board, BoardModel)
368
+ ```
369
+
370
+ ```python
371
+ # app/apps.py
372
+ class BoardsConfig(GraphCoreAppConfig):
373
+ graphcore_persistence = 'app.persistence.configure'
374
+ ```
375
+
376
+ `Board` adds `column_order` to its own `to_dict()` override (the same
377
+ pattern `Group.name` uses); nothing else — no mapper, no manual
378
+ record shape — is needed for `column_order` to round-trip, appear on the
379
+ wire via `to_client()`, and be filterable with
380
+ `EntityFilter(..., where=Equal('column_order', ...))`.
381
+
382
+ ## Testing
383
+
384
+ `persistence/tests/contract.py` is one suite run against every
385
+ implementation: `MemoryEntityRepository` (no SQL) and
386
+ `DjangoEntityRepository`, on every supported database. `scripts/test` (at
387
+ the monorepo root) runs every suite on PostgreSQL, then the suites that
388
+ depend on the database (`graphcore.persistence`, `graphcore.auth.authz`) on
389
+ each other supported database; `graphcore.test_settings` picks the database
390
+ from `GRAPHCORE_TEST_DB`. A query-shape test proves
391
+ `list_entities` selects ids in exactly one `SELECT … LIMIT` with the
392
+ predicate in `WHERE`; a contract case proves the null-check hazard is
393
+ closed identically on both backends using a real nullable child column.
394
+
395
+ `graphcore.tests.test_shared_type_boundaries.OrmFreeLayerTests` is the
396
+ executable form of requirement 1.
@@ -0,0 +1,6 @@
1
+ """The storage seam: a backend-neutral entity repository contract - a
2
+ record is an entity's own ``to_dict()``/``from_dict()``, no mapper - and
3
+ the Django implementation under ``persistence/django``.
4
+
5
+ Nothing outside ``persistence/django`` imports Django.
6
+ """
File without changes