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,561 @@
1
+ # Entity Reference Architecture
2
+
3
+ ## Introduction
4
+
5
+ Entities hold references to other entities. A referenced entity lives either in the same GraphCore deployment as the entity holding the reference or in a cooperating deployment. The kernel gives callers one way to identify, store, and follow a reference regardless of where its target lives, and it keeps the identity of a target separate from the means of reaching it. This document defines the identifier, the storage of references, the resolution of a reference to its target, and the discovery of references pointing at a given entity.
6
+
7
+ ## Definitions
8
+
9
+ - **Deployment**: one GraphCore runtime with one entity store and one backend
10
+ identity.
11
+ - **Backend identity** (`backend_id`): an opaque, immutable 10-character
12
+ identifier (lowercase Crockford base32, 50 random bits) minted once when a
13
+ deployment's store is initialised. It identifies the deployment for
14
+ the store's entire life. It is identity, never configuration.
15
+ - **Handle**: a human-readable name for a deployment. Mutable. Published in
16
+ the deployment's identity document.
17
+ - **Identity document**: the JSON document a deployment serves at a
18
+ well-known path describing itself: `backend_id`, `deployment_entity_id`,
19
+ handle, and API endpoint. The only place a deployment states where it is
20
+ reachable.
21
+ - **Peer table**: a deployment's local mapping `backend_id → identity
22
+ document URL` for the deployments it cooperates with. Operator-populated. The
23
+ only configuration a deployment holds about another deployment.
24
+ - **Issuer**: the OIDC provider a deployment trusts, as defined in
25
+ `IDENTITY.md`. Cooperating deployments share an identity domain or link
26
+ their domains. Authentication is shared through the issuer; authorization is
27
+ local to each deployment.
28
+ - **Entity identifier** (`entity_id`): the string
29
+ `gc://<backend_id>/<local_id>`, where `<local_id>` is 12 characters of the
30
+ same alphabet (60 random bits).
31
+ This is the only identifier form used by any component above the entity
32
+ store.
33
+ - **Backend segment**: the `<backend_id>` part of an entity identifier. It
34
+ names the deployment that minted the entity. The `<local_id>` part is
35
+ unique within that deployment.
36
+ - **Minting deployment**: the deployment named by an identifier's backend
37
+ segment. The minting deployment owns the entity for the entity's life.
38
+ - **Reference**: an entity identifier held anywhere in another entity's data.
39
+ - **Local / remote**: an entity is local to a deployment when its minting
40
+ deployment is that deployment, and remote otherwise.
41
+ - **Entity repository**: the persistence port for local entities. It stores
42
+ identifiers as opaque strings and never resolves or routes.
43
+ - **Remote gateway** (`RemoteGateway`): the kernel component that performs
44
+ reads and strategy execution against another deployment's API on behalf of a
45
+ local caller. The shipped adapter, `NoRemoteGateway`, performs no call and
46
+ answers every identifier with a `Tombstone`.
47
+ - **Delegated token**: the RFC 8693 exchanged token the remote gateway
48
+ obtains from the issuer for one `(principal, target deployment)` pair, with
49
+ `sub` the acting principal, `act` the calling deployment, and `aud` the
50
+ target deployment. Defined in `IDENTITY.md`.
51
+ - **Tombstone**: the value returned in place of an entity that cannot be
52
+ delivered, carrying the identifier and a cause.
53
+ - **Reference projection** (`reference_ids`): a derived, read-only field on
54
+ every entity listing the target identifiers held in any of its fields other
55
+ than its own identifier. Maintained by the entity repository on save, in the
56
+ same way as `ancestor_ids`.
57
+ - **Dependent reference**: a reference held in a field an entity type
58
+ declares in `dependent_on`. The holding entity cannot outlive the local
59
+ entity it names: deleting the target deletes the holder.
60
+ - **Predicate**: the kernel's storage-neutral filter tree, defined with its
61
+ wire encoding in `ENTITY_REPOSITORY_TECHNICAL_TDD.md` (The query vocabulary).
62
+
63
+
64
+
65
+ ## Requirements
66
+
67
+ 1. **References identify entities, not copies of their data.** A reference
68
+ points to a particular entity whose state can change independently.
69
+ Following it accesses that entity under a defined freshness policy.
70
+ 2. **Relationships can express a purpose.** An application can distinguish
71
+ relationships such as a card's specification and a card's customer. The
72
+ References can appear within an entity's data types, including lists of
73
+ references. The entity storing the references defines their purpose and
74
+ how their containing data structures are used. A list preserves its order;
75
+ the entity defines and maintains the meaning of that order. The kernel
76
+ assigns no relationship semantics to list position. These references
77
+ remain discoverable through reverse lookup regardless of their placement
78
+ within the entity's data. No dedicated `refs` field is required by this
79
+ contract.
80
+ 3. **Local and remote entities are valid targets.** An entity can reference
81
+ another entity in the same GraphCore deployment or a cooperating GraphCore
82
+ deployment. Application code has a consistent way to follow either
83
+ reference while handling remote latency and failure.
84
+ 4. **Identity and location are distinct concerns.** The system unambiguously
85
+ identifies the intended target and determines how to reach it.
86
+ 5. **A reference does not itself grant access.** Knowing or storing a target's
87
+ identity does not bypass its authorization rules. Remote access establishes
88
+ who is acting and lets the owning system enforce its permissions.
89
+ 6. **Referencing an entity does not imply owning it.** Creating, removing, or
90
+ deleting a reference does not inherently create or delete the target.
91
+ Multiple entities can reference the same target independently. Stronger
92
+ ownership behavior requires an explicit contract, declared by the
93
+ referencing type (see Dependent references).
94
+ 7. **Unavailable targets are an expected state.** Targets can be deleted,
95
+ inaccessible, temporarily unreachable, or not yet resolvable. These
96
+ conditions have defined outcomes that consumers can handle without losing
97
+ the referencing entity or its other relationships.
98
+ 8. **References support reverse lookup.** Given a target entity, the system
99
+ can discover entities that reference it, subject to the caller's access
100
+ and narrowed by a predicate. The primary use case is view resolution:
101
+ view entities reference the entities they render, and the system finds
102
+ those views from the target entity's identity (`VIEW_ENTITY_TDD.md`). The target entity does not store or maintain knowledge
103
+ of its views; creating or removing a view's reference requires no update
104
+ to the target entity. The scope of discovery across deployments remains
105
+ an architectural decision.
106
+ 9. **Reference-index updates are broadcast.** The broadcaster publishes
107
+ updates when references are added, removed, or changed in the reference
108
+ index. Consumers can subscribe to keep reverse-lookup results, including
109
+ resolved views for an entity, current without requiring a change to the
110
+ target entity. Broadcast delivery respects the subscriber's access.
111
+ 10. **One identifier form for every caller and every target.** Strategies,
112
+ agents, and frontends use the same identifier whether the target is local
113
+ or remote. Callers never choose between identifier forms and never
114
+ construct routing information.
115
+ 11. **Backend identity is immutable.** Changing a deployment's handle or
116
+ endpoint changes no persisted data in any deployment.
117
+
118
+
119
+
120
+ ## Architecture
121
+
122
+
123
+
124
+ ### Backend identity
125
+
126
+ Initialising a deployment's store mints one `BackendIdentityModel` row holding a
127
+ freshly generated backend identity. Migration `0015` creates the table; the row itself is
128
+ ensured by a `post_migrate` receiver in `graphcore.apps`, so a flushed test
129
+ database re-establishes it where a data migration would run only once. The
130
+ row is a singleton; the store enforces that exactly one exists. The runtime
131
+ loads the value at process start, through `EntityRepository.backend_id()`,
132
+ and exposes it as `runtime.backend_id`. A test store's identity is whatever
133
+ that run minted — there is no fixed constant and no setting.
134
+
135
+ Invariants:
136
+
137
+ - Exactly one backend identity exists per deployment.
138
+ - A backend identity never changes and is never overridden by settings,
139
+ environment, or command-line input. No code path accepts a backend identity
140
+ as a parameter.
141
+ - A backend identity appears in exactly four places: the singleton row, the
142
+ runtime, the backend segment of entity identifiers, and the
143
+ deployment's identity document.
144
+ - A backend identity is not a credential. It authenticates nothing; a
145
+ deployment proves who is acting through the issuer, never through its
146
+ identity.
147
+
148
+ This is the identity/handle separation used by decentralized identifiers and
149
+ by SPIFFE trust domains: the stable identifier is opaque and minted, and
150
+ every human-readable or network-dependent fact about the deployment is
151
+ resolved from it rather than encoded in it.
152
+
153
+ ### Entity identifier
154
+
155
+ ```
156
+ gc://k7m2x9qp4n/3fz8a1c0w4ne
157
+ ─────┬──── ─────┬─────
158
+ │ └─ local id, unique within the minting deployment
159
+ └─ backend identity of the minting deployment
160
+ ```
161
+
162
+ Both segments are fixed-length lowercase Crockford base32 (no `i l o u`), so
163
+ an identifier is short, case-free, safe in a URL path without encoding, and
164
+ selected whole by a double-click. Fixed lengths keep the reference scan
165
+ exact: a longer run of the alphabet is never clipped into a false match.
166
+
167
+ `EntityService.create(entity_cls, **kwargs)` mints
168
+ `gc://{runtime.backend_id}/{random local id}` and is the only thing that mints:
169
+ `Entity.__init__` requires an identifier and has none to make one from. An
170
+ entity is therefore always created local to the deployment creating it.
171
+
172
+ Invariants:
173
+
174
+ - The backend segment of an entity identifier is the backend identity of
175
+ the deployment that minted the entity, and that deployment owns the entity
176
+ for its life. Entities do not migrate between deployments; an entity
177
+ recreated elsewhere is a different entity with a different identifier.
178
+ - Every identifier handled by any component above the entity repository is
179
+ in this form. A bare local id is not a valid identifier anywhere in the
180
+ kernel, on the wire, or in entity data.
181
+ - The identifier is opaque to every component except `EntityService`, which
182
+ reads the backend segment to route (see Resolution and routing).
183
+
184
+ Neither segment is globally unique by construction; each is unique where
185
+ it has to be, and a duplicate is refused there rather than made improbable
186
+ by length:
187
+
188
+ - **Local ids** need only be unique within one store. The entity primary
189
+ key enforces it: saving a freshly minted entity under an existing
190
+ identifier is refused (`ConcurrentModificationError`, or an integrity error
191
+ across entity types) and never overwrites the existing row.
192
+ - **Backend identities** need only be unique among deployments that
193
+ cooperate. A collision can misroute only through a deployment's own peer
194
+ table, so the peer table is where it is refused (see Peer table and identity
195
+ document).
196
+
197
+ Because the backend segment records who minted the target, persisting an
198
+ identifier inside another entity's data persists a fact about the target,
199
+ not a fact about infrastructure. This is why references store identifiers
200
+ unchanged.
201
+
202
+ ### Identifiers in the web client
203
+
204
+ The React client routes an entity at `/e/<backend_id>/<local_id>`, the
205
+ identifier with its `gc://` prefix removed. `entityPath` and
206
+ `entityIdFromParams` are the only translation between the two. A catch-all
207
+ route recovers an identifier pasted after the host (`host/gc://…`, whose
208
+ `//` the browser may collapse) and redirects to its canonical path. The
209
+ route is presentation only: the identifier the client holds, sends, and
210
+ stores is always the full `gc://` form.
211
+
212
+ ### References in entity data
213
+
214
+ A reference is an entity identifier stored as a value anywhere in an
215
+ entity's attributes: as a scalar, inside a nested structure, or as an element
216
+ of a list. It is stored exactly as written and read exactly as stored. The
217
+ kernel performs no rewriting of references on save or on load.
218
+
219
+ Containment does not cross a deployment boundary. Access is derived from the
220
+ containment chain, and a deployment computes and enforces that chain only
221
+ over entities it owns.
222
+
223
+ Invariants:
224
+
225
+ - `parent_id` names a local entity. `EntityService` rejects a save whose
226
+ `parent_id` carries a foreign backend segment with a validation error, at
227
+ the persistence chokepoint and before any authorization check.
228
+ `children_ids` and `ancestor_ids` are derived from `parent_id` and are
229
+ therefore local.
230
+ - Attribute-level references carry no such restriction; they name local or
231
+ remote targets freely.
232
+ - The entity repository stores identifiers as opaque strings, including as
233
+ the primary key. It parses nothing and translates nothing.
234
+
235
+ Storing the full identifier in every id-bearing column means one string form
236
+ exists in every layer including storage, and no translation step exists
237
+ anywhere.
238
+
239
+ ### Resolution and routing
240
+
241
+ `EntityService` is the single component that reads an identifier's backend
242
+ segment. Its routing rule:
243
+
244
+ - backend segment equals `runtime.backend_id` → local path: entity
245
+ repository, local `AccessPort`, local cache.
246
+ - backend segment is any other value → remote gateway.
247
+
248
+ Routed entry points: `get_entity`, `get_entities`, and strategy execution
249
+ against a target entity. Every other caller (strategies via `BaseStrategy`,
250
+ `GraphAPI`, the executor, containment traversal) reaches these entry points
251
+ and inherits routing without change.
252
+
253
+ Invariants:
254
+
255
+ - The entity repository is never asked for a remote identifier.
256
+ - No component other than `EntityService` branches on whether an entity is
257
+ local or remote.
258
+ - A strategy request whose target entity is remote is forwarded by the
259
+ executor to the owning deployment, which executes it under its own policy
260
+ and returns the result. The request record itself is a local entity.
261
+
262
+
263
+
264
+ ### Peer table and identity document
265
+
266
+ Every deployment serves its identity document at a well-known path. Every
267
+ deployment holds a peer table naming the deployments it cooperates with and
268
+ where their identity documents are. The remote gateway resolves a backend
269
+ identity by looking it up in the peer table, fetching the identity document,
270
+ and using the endpoint it declares. Fetched documents are cached in memory
271
+ and re-fetched on failure or expiry; they are never persisted.
272
+
273
+ The peer table is deployment configuration, `GRAPHCORE_PEERS`, in the same
274
+ class as `GRAPHCORE_TRUSTED_ISSUERS`: a trust decision made by the operator,
275
+ read once at composition, and handed to the remote gateway. It is not an
276
+ entity and not a table. No strategy, agent, or principal changes it at
277
+ runtime.
278
+
279
+ Invariants:
280
+
281
+ - A deployment's endpoint and handle are stated only in its own identity
282
+ document. No other deployment persists them.
283
+ - A peer table entry is a trust decision and a bootstrap pointer, nothing
284
+ more. Appearing in one deployment's peer table grants no access at the
285
+ other.
286
+ - A fetched identity document whose `backend_id` differs from the peer table
287
+ key is rejected; the target is treated as unreachable.
288
+ - Composition refuses a peer table that names the deployment's own backend
289
+ identity, or names one backend identity twice. This is the only point at
290
+ which two deployments sharing an identity could be confused, so backend
291
+ identities need no uniqueness beyond it.
292
+ - Changing an identity document affects the next remote call to that
293
+ deployment and nothing else.
294
+
295
+
296
+
297
+ ### Remote access and authorization
298
+
299
+ The remote gateway is the interop client specified in `IDENTITY.md`. For a
300
+ call to the owning deployment on behalf of a principal it obtains a delegated
301
+ token from the issuer, caches it per `(principal, target deployment)` until
302
+ expiry, and calls the owner's `GraphAPI` with it. The owner verifies the
303
+ token against the issuer, maps `(iss, sub)` to its own `User`
304
+ (materialising one on first contact), enforces its own `AccessPort` as that
305
+ subject, and records `sub` and `act` in its audit trail.
306
+
307
+ Invariants:
308
+
309
+ - No deployment computes an authorization decision about an entity it does
310
+ not own. The local `AccessPort` is never consulted for a remote identifier.
311
+ - A principal's token is never forwarded. The token presented to the owner is
312
+ always a delegated token audience-bound to that owner.
313
+ - Delegation is granted by the issuer's policy and the principal's consent,
314
+ never by the calling deployment. A deployment cannot make itself able to act
315
+ for a principal at another deployment.
316
+ - A remote call requires a subject token on the acting `Principal`.
317
+ Executions that carry an identity-only `Principal` (background and scheduled
318
+ executions) cannot delegate, and remote targets resolve for them as
319
+ unavailable with cause `undelegated`.
320
+ - A remote read always goes to the owning deployment. Remote entity payloads
321
+ are not cached locally. The freshness policy for a remote read is
322
+ therefore identical to a local read: the caller receives the owner's
323
+ current, access-checked state.
324
+ - A remote entity's `parent_id`, `children_ids`, and `ancestor_ids` are
325
+ valid identifiers naming further entities in the owning deployment. Following them is an ordinary routed
326
+ read subject to the owner's access decision.
327
+
328
+
329
+
330
+ ### Unavailable targets
331
+
332
+ `get_entities` returns a `Tombstone` for each identifier it cannot deliver as
333
+ an entity. `get_entity` raises the corresponding error. Causes:
334
+
335
+ - `missing`: the owning deployment reports no such entity.
336
+ - `forbidden`: the owning deployment denies the acting principal read access.
337
+ - `unreachable`: the owning deployment cannot be contacted, has no peer table
338
+ entry, or its identity document does not match.
339
+ - `undelegated`: the issuer refused or the acting `Principal` carries no
340
+ subject token to exchange.
341
+
342
+ Invariants:
343
+
344
+ - An unavailable target never invalidates the referencing entity or any of
345
+ its other references. The reference remains stored.
346
+ - A `Tombstone` carries the identifier so a consumer can render or retry the
347
+ slot without further lookup.
348
+
349
+
350
+
351
+ ### Reverse lookup and the reference projection
352
+
353
+ On every save, the entity repository serializes every field of the
354
+ entity, collects every value in entity-identifier form other than the
355
+ entity's own identifier, and stores the set as the entity's
356
+ `reference_ids`. Kernel-owned and application fields are treated alike:
357
+ `parent_id`, `owner`, a typed column, and a value nested anywhere in the
358
+ attributes all count. Deleting an entity removes its projection with it.
359
+
360
+ Reverse lookup for a target is
361
+ `EntityService.referrers(target_id, principal, where=None, cursor, limit)`,
362
+ which conjoins `where` with the caller's access predicate and hands the
363
+ target and the combined predicate to
364
+ `EntityRepository.referrers(target_id, predicate, page)`. The port names
365
+ the traversal; how the reverse index is stored is the adapter's choice (the
366
+ Django adapter keeps an `EntityReferenceModel` edge table keyed
367
+ `(target_id, source_id)`). The port promises:
368
+
369
+ - The predicate narrows the match in the same statement, before paging;
370
+ pages are never short because of filtering done afterwards.
371
+ - Results are ordered by source `entity_id`, and the cursor is the last
372
+ `entity_id` of the previous page.
373
+ - Results are hydrated entities.
374
+
375
+ `where` narrows referrers by their own fields: their type, a typed column,
376
+ a base column such as `parent_id`. It cannot select which field of the
377
+ referrer holds the reference. A caller that knows the field queries it
378
+ directly with `list_entities(where=Equal(field, target_id))`, which is
379
+ exact and uses that column's index; `referrers` answers the question for
380
+ references held anywhere.
381
+
382
+ Over HTTP, `/api/referrers/` accepts `where` in the predicate wire
383
+ encoding.
384
+
385
+ The projection records that an identifier appears in an entity, not why.
386
+ Reverse lookup therefore supports discovery (the views of an entity), not
387
+ impact analysis: a source that merely mentions a target is indistinguishable
388
+ from one that depends on it, and sources the caller cannot read are
389
+ invisible to it.
390
+
391
+ Invariants:
392
+
393
+ - `reference_ids` is derived entirely from entity data. It is populated on
394
+ hydration and is not assignable; the repository owns it.
395
+ - A target entity is neither read nor written when a reference to it is
396
+ created or removed.
397
+ - The projection records references held by local entities. Its targets are
398
+ local or remote; the entities carrying it are always local.
399
+ - Re-saving an entity rebuilds its projection; no separate rebuild path
400
+ exists.
401
+
402
+
403
+
404
+ ### Dependent references
405
+
406
+ An entity type declares the fields holding references it cannot outlive:
407
+
408
+ ```python
409
+ class View(Entity):
410
+ dependent_on: ClassVar[tuple[str, ...]] = ('renders',)
411
+ ```
412
+
413
+ `dependent_on` is declarative type metadata, in the same class as
414
+ `write_once_fields` (`ARCHITECTURE_PRINCIPLES.md`, rules 2 and 7). The
415
+ engine reads it from every registered type alike and names no concrete
416
+ type.
417
+
418
+ `EntityService.delete_entity_tree` builds the deletion set in rounds:
419
+
420
+ 1. The root and its containment closure, after the root is authorized.
421
+ 2. Every local entity whose dependent field names an identifier in the
422
+ set, with its containment closure, found by one indexed query per
423
+ declaring type and field through
424
+ `EntityRepository.dependent_ids(type_ids, field, target_ids)` (`InValues`
425
+ for a string field, `ContainsAny` for a list).
426
+ 3. Step 2 repeats over the newly added identifiers until a round adds
427
+ nothing.
428
+
429
+ The access adapter's `check_delete` then runs over the whole set, and the
430
+ set is deleted and broadcast as one deletion.
431
+
432
+ Invariants:
433
+
434
+ - A dependent field is a typed column of the declaring type's storage
435
+ model holding an identifier or a list of identifiers. Startup fails for a
436
+ field that is not. References nested in JSON or in the attribute bag
437
+ cannot be dependent.
438
+ - Dependents are found without regard to the deleting principal's access
439
+ and are deleted without per-entity authorization, in the same way as a
440
+ containment closure. Declaring the dependency is the type's consent to
441
+ being deleted with its target.
442
+ - Only the declaring side is deleted. Deleting a dependent never deletes
443
+ its target.
444
+ - Only the deletion of a local entity triggers the rule. A dependent on a
445
+ remote target is never deleted by it; following the reference yields a
446
+ `Tombstone`.
447
+
448
+ ### Broadcast of reference changes
449
+
450
+ After a save commits, `EntityService` diffs `reference_ids` on the saved
451
+ entity against `SaveReceipt.previous` and emits one `reference_update` event
452
+ per added or removed target, carrying `target_entity_id`,
453
+ `source_entity_id`, and the change kind. Events are routed on the source -
454
+ to its scopes, its owner, and `public` if its type is publicly readable -
455
+ exactly as the source's own save publication is, and the routing is resolved
456
+ once per save however many references changed. Only principals who can read
457
+ the source learn of the change; a target's readers learn nothing about a
458
+ source they cannot see. Events are published after the save commits,
459
+ alongside the entity's own save publication.
460
+
461
+ ### Worked examples
462
+
463
+ **Following a local reference.** A `Card` holds `customer = "gc://A/…c1"`. A strategy on deployment A calls
464
+ `self.get_entity(card.customer)`. `EntityService` reads backend segment `A`,
465
+ matches its own identity, loads from the repository, checks the local
466
+ `AccessPort`, returns the `Customer`.
467
+
468
+ **Following a remote reference, denied.** The same `Card` holds
469
+ `specification = "gc://B/…s9"`. The strategy calls
470
+ `self.get_entity(card.specification)`. `EntityService` reads backend segment `B`,
471
+ hands the identifier to the remote gateway, which resolves `B` through the
472
+ peer table and identity document, obtains a delegated token for the acting
473
+ principal with `aud: B`, and calls B's `GraphAPI`. B verifies the token, maps
474
+ the principal to its own `User`, and its `AccessPort` denies. The gateway returns a `Tombstone` with
475
+ cause `forbidden`; the `Card` and its `customer` reference are unaffected.
476
+
477
+ **An agent creating a reference.** An agent on A is handed a `Product`
478
+ whose `entity_id` is `gc://B/…p4`. It writes that string into a `Card`'s
479
+ `items` list and saves the `Card`. The save stores the string unchanged,
480
+ adds `gc://B/…p4` to the `Card`'s `reference_ids`, and publishes a
481
+ `reference_update` routed on the `Card`. The agent
482
+ constructed no routing information.
483
+
484
+ **Deleting a dependency target.** A `View` holds
485
+ `renders = "gc://A/…d1"`, and `View` declares
486
+ `dependent_on = ('renders',)`. A principal with `Delete` on `gc://A/…d1`
487
+ deletes it. The second round of `delete_entity_tree` queries `View`
488
+ for `renders IN (…d1)`, adds the view and the views it contains to the
489
+ deletion, and the next round adds nothing. The view's owner is not
490
+ consulted.
491
+
492
+ **Following a remote entity's containment.** A strategy on A reads
493
+ `gc://B/…s9` and receives an entity whose `children_ids` contains
494
+ `gc://B/…k2`. It calls `self.get_entity` on that identifier; the call
495
+ routes to B and B decides access. No special handling distinguishes this
496
+ from following an attribute-level reference.
497
+
498
+ ### Trade-offs
499
+
500
+ - **Backend identities are unique only among cooperating deployments.** 50
501
+ random bits make a collision between any two deployments negligible, and the
502
+ peer table refuses the one that would matter. Accepted for identifiers short
503
+ enough to read, paste, and put in a URL.
504
+ - **A reference to a remote target persists that target's backend identity.**
505
+ Unavoidable: an unqualified identifier is ambiguous across deployments.
506
+ Made safe by the identity being immutable, so nothing stored ever needs
507
+ rewriting.
508
+ - **Remote reads pay owner latency on every call.** Accepted so that
509
+ authorization and freshness for remote entities come only from the owner,
510
+ never from a local copy.
511
+ - **Restoring one deployment's store onto a second live host produces two
512
+ deployments claiming one identity.** This is a clone, not a rename, and is
513
+ unsupported.
514
+ - **Cooperating deployments depend on issuers that exchange tokens**, within
515
+ a shared identity domain or across linked domains (`IDENTITY.md`). Accepted
516
+ so that no deployment holds signing keys, no token is valid beyond its
517
+ intended audience, and delegation is revocable at the issuer. A deployment
518
+ whose issuer offers no exchange, or whose principal has no linked account at
519
+ the target, holds references to remote targets but resolves them as
520
+ `undelegated`.
521
+ - **A dependent can be deleted by someone with no access to it.** Deleting
522
+ a target removes every local dependent, including ones the deleting
523
+ principal cannot read. Accepted because the dependent's type declared
524
+ that it cannot exist without the target.
525
+ - **Only typed columns can be dependent.** Keeping the lookup to one
526
+ indexed query per type rules out dependencies nested in JSON.
527
+ - **Background executions cannot follow remote references.** Accepted until a
528
+ durable, revocable credential reference exists (`IDENTITY.md`); the outcome
529
+ is a defined `Tombstone`, not silent failure.
530
+
531
+
532
+
533
+ ### Open items
534
+
535
+ - **Cross-deployment reverse lookup.** Whether an owning deployment learns of
536
+ references held by foreign entities (push on save, or query fan-out), and
537
+ how such results are access-filtered.
538
+ - **Forwarded strategy execution.** Lifecycle of a request executed by a
539
+ remote owner: status propagation, callbacks, and cancellation.
540
+ - **Top-level entities of a deleted principal.** A top-level entity has no
541
+ container, so nothing deletes it when its owner is deleted, and nothing
542
+ else can manage it unless it was shared. Options are deleting a
543
+ principal's unshared top-level entities with it, or transferring them;
544
+ this depends on ownership transfer (`AUTHORIZATION_TECHNICAL_TDD.md`, Open
545
+ items).
546
+ - **Peer table population.** Operator configuration versus a discovery
547
+ mechanism, and whether a deployment records which peers call it.
548
+ - **Delegation for background executions.** The credential-reference or
549
+ token-broker design that lets scheduled and CPU-bound executions obtain a
550
+ delegated token.
551
+ - **Live updates for remote entities.** A remote read through the gateway is
552
+ request/response and carries no subscription; a deployment broadcasts only
553
+ the entities it owns. The leaning is for the client SDK to subscribe to the
554
+ owning deployment directly, obtaining a token for that deployment's audience
555
+ from the issuer under the user's existing session (one login; silent
556
+ per-audience token acquisition), so the owner authorizes the user as
557
+ `sub` with no actor in the chain. Alternatives are snapshot-only remote
558
+ entities refreshed by the client, or the gateway relaying the owner's
559
+ broadcasts. Unresolved: how non-browser clients (agents, MCP) obtain
560
+ per-audience tokens, and how the SDK learns a peer's endpoint.
561
+