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,522 @@
1
+ # View Entities
2
+
3
+ ## Introduction
4
+
5
+ A view is how an entity is shown: which component renders it and the UI
6
+ state that component remembers (collapsed sections, panel sizes, the chosen
7
+ tab). The kernel stores that state as a `View` so it survives reloads,
8
+ follows a user across devices, and can be shared. This document defines how
9
+ views are found, when they are stored, who can see them, and how view
10
+ components are written in a client.
11
+
12
+ A view references the entity it shows; it is never stored under that
13
+ entity. Showing an entity therefore never reads, writes, or rebroadcasts it.
14
+
15
+ This document is part of the view system (`VIEW_SYSTEM_TDD.md`), which
16
+ defines clients, addresses, and the route table.
17
+
18
+ ## Definitions
19
+
20
+ - **Client**: as in `VIEW_SYSTEM_TDD.md`: the React frontend (`web`), the
21
+ agent frontend (`agent`). Each client has its own view registry. The kernel
22
+ treats view names and view state as opaque. The agent client stores no
23
+ view state.
24
+ - **Address**: as in `VIEW_SYSTEM_TDD.md`: a path on the deployment
25
+ (`/`, `/e/<backend_id>/<local_id>`, an app route, a client route), the same
26
+ for every client. A **page** is what a client shows at one address.
27
+ - **View component**: a component declared once with
28
+ `defineView(name, Component, options)`. Its **view name** is unique within
29
+ its client's registry.
30
+ - **View**: stored view state. Every view is its own entity, with
31
+ these fields:
32
+ - `component`: a view name, or null to use the default component for the
33
+ shown entity's type;
34
+ - `renders`: the identifier of the entity shown, or null when the view
35
+ shows no single entity (an app home, a dashboard, a settings page);
36
+ - `client`: the client that stores it;
37
+ - `slot`: its name among its siblings;
38
+ - `address`: the page it is on;
39
+ - `state`: a JSON object owned by the component.
40
+ - **Siblings**: entities with the same parent; for a top-level entity, the
41
+ same owner's other top-level entities.
42
+ - **Slot**: a view's name among its siblings. A top-level view on a page
43
+ has the page's address as its slot. A view inside another view has the
44
+ name code gives its placement, which defaults to the view name; code names
45
+ a slot to tell apart two placements of the same component showing the same
46
+ entity.
47
+ - **Placement**: the chain of steps from where a client starts (a page, or
48
+ a view opened by id) down to a view. Each step is a slot and the entity
49
+ shown there.
50
+
51
+ Every view is stored, and every view is the same kind of entity. Two words
52
+ describe how a view came to exist; they are not fields, and code never
53
+ branches on them:
54
+
55
+ - **Implicit view**: stored because code renders a view component at a
56
+ placement and its state changed. Nobody creates it on purpose. It is found
57
+ by where it sits: its slot and `renders` among its siblings.
58
+ - **Explicit view**: created on purpose at runtime, by a user (from the
59
+ gallery), an app, or an agent, with `CreateView`. It is found by its
60
+ id: it opens at `/e/<id>`, a composite shows it by holding its id, and it
61
+ can be shared. It has no slot and no address.
62
+
63
+ Examples, for Alice using the web client:
64
+
65
+ | View | parent | `slot` | `renders` | `address` |
66
+ |---|---|---|---|---|
67
+ | her page for project P | none | `/e/…/P` | P | `/e/…/P` |
68
+ | the outline of document D on that page | the view above | `outline` | D | `/e/…/P` |
69
+ | her settings page | none | `/settings` | none | `/settings` |
70
+ | an explicit view V of P | none | none | P | none |
71
+ | the outline of D inside V | V | `outline` | D | none |
72
+
73
+ ## Requirements
74
+
75
+ 1. **Rendering never writes.** Any entity renders without a View,
76
+ with the state defaults its component declares. An implicit view is
77
+ created only when its state first changes.
78
+ 2. **Showing an entity never touches it.** Creating, changing, or deleting
79
+ a view never reads, writes, or rebroadcasts the entity it shows, and
80
+ needs no permission on that entity beyond what reading it needs.
81
+ 3. **Each placement keeps its own state.** The same entity shown at two
82
+ placements keeps separate state. Two placements at the same position
83
+ share state unless code names separate slots.
84
+ 4. **Siblings are unique by client, slot, and entity.** Two concurrent
85
+ first changes at the same placement produce one view.
86
+ 5. **View state is shared by sharing a view.** A page's views are visible
87
+ only to their owner. Everything rendered inside a view opened by id is
88
+ stored in it and shares its access.
89
+ 6. **Web view code is plain React.** A component is declared once and
90
+ rendered as ordinary JSX. Callers pass the entity to show and nothing
91
+ else. No component declares where its state is stored.
92
+ 7. **The component is fixed in code or chosen at runtime.** Code can render
93
+ a specific view component, or render an entity and let the stored view,
94
+ then the entity type's default component, decide.
95
+ 8. **Clients share addresses, not view names.** State is stored under the
96
+ address a client rendered, so the same place has the same address in
97
+ every client. A view name is resolved only by the client that renders
98
+ it; a name a client does not know resolves to that client's default for
99
+ the entity's type.
100
+ 9. **No entity is created under a principal.**
101
+ 10. **Deleting a local entity deletes the views that show it.** A view of a
102
+ remote or unreadable entity shows a tombstone and survives.
103
+ 11. **A refused write is visible.** A view-state change the caller may not
104
+ store is reported as an error and leaves the state unchanged.
105
+ 12. **A page loads in one query.** Every stored view on a page, at any
106
+ depth, is found by one ordinary entity query, and the views inside a
107
+ view opened by id by another. No client computes a key or builds a
108
+ string to find a view.
109
+
110
+ ## Architecture
111
+
112
+ ### Storage
113
+
114
+ `View` is a typed entity with its own storage model:
115
+
116
+ | Column | Type | Notes |
117
+ | --- | --- | --- |
118
+ | `component` | string, null | mutable |
119
+ | `renders` | string, null | indexed, write-once |
120
+ | `client` | string | write-once |
121
+ | `slot` | string, null | write-once |
122
+ | `address` | string, null | write-once; indexed with `client` |
123
+ | `position_key` | char(64), null | unique, write-once, server-only |
124
+ | `state` | JSON | default `{}` |
125
+
126
+ - `position_key` enforces Requirement 4. The server computes it as the
127
+ lowercase hex SHA-256 of the view's sibling scope (its parent, or its owner
128
+ when it is top-level), `client`, `slot`, and `renders`. It is unique on its
129
+ own, so the constraint needs no base-table column. Clients never read,
130
+ send, or compute it.
131
+ - `View.write_once_fields = ('renders', 'client', 'slot', 'address',
132
+ 'position_key')`.
133
+ - `View.dependent_on = ('renders',)`
134
+ (`ENTITY_REFERENCE_TDD.md`, Dependent references).
135
+
136
+ Invariants:
137
+
138
+ - A view has a `slot` exactly when it has a `position_key`.
139
+ - A top-level view with a slot is a page's view: its slot and its
140
+ `address` are the page's address, and its `renders` is the entity the route
141
+ table resolves for the address, or null for an address the table does not
142
+ match.
143
+ - A view inside a page's view has that page's `address`, at every depth. A
144
+ view inside a view without an address has none.
145
+ - A placement has at most 64 steps. A longer one, which only a component
146
+ that renders itself produces, is refused with `InvalidRequest`.
147
+ - An address starts with `/`, has no trailing `/` except `/` itself, and
148
+ has no query or fragment. The server refuses any other form.
149
+ - Only `SetViewState` sets `slot`, and views are never moved, so a
150
+ view's fields cannot disagree with where it is stored.
151
+ - A view's children are views and its own grants. Data entities are never
152
+ stored under a view; a view shows them by reference.
153
+
154
+ ### Strategies
155
+
156
+ **`SetViewState`** changes a view's state, creating it first when
157
+ it does not exist.
158
+
159
+ - With a target, the target is the view to change.
160
+ - Without a target (the strategy is on the deployment's allowlist), plain
161
+ parameters name the view by where it sits:
162
+
163
+ ```json
164
+ { "client": "web", "address": "/e/b/l",
165
+ "placement": [{ "slot": "outline", "renders": "gc://b/d" }] }
166
+
167
+ { "client": "web", "view": "gc://b/v",
168
+ "placement": [{ "slot": "outline", "renders": "gc://b/d" }] }
169
+ ```
170
+
171
+ Exactly one of `address` (start at that page's view) and `view` (start at
172
+ that view) is given. With `address`, `placement` may be empty, naming the
173
+ page's view itself; with `view`, it has at least one step. The strategy:
174
+ 1. starts at the page's view, finding or creating it as a top-level view
175
+ of the caller with `slot` and `address` set to the address; or at `view`,
176
+ which must be a readable view;
177
+ 2. walks the placement, finding each step among the current view's
178
+ children by `position_key` and creating it when missing, with the step's
179
+ `slot` and `renders`, the `client`, and the `address` of the view above;
180
+ 3. applies the change to the last view.
181
+
182
+ Creating a missing view on the way is how a change deep in the tree is
183
+ stored before anything around it has changed. A unique-constraint failure
184
+ means a concurrent request created that view; the strategy re-reads and
185
+ continues.
186
+ - `state` is shallow-merged into the view's state; a key set to null is
187
+ removed. `component`, when given, replaces the stored one.
188
+ - Returns the view's identifier.
189
+
190
+ **`CreateView`** creates an explicit view.
191
+
192
+ - Params: `renders`, `component`, `state`. The parent is the strategy's
193
+ optional target, as for `CreateEntity`: with one, the view is
194
+ placed in that entity (any data entity that allows it, or another view) and
195
+ shares its access; without one, it is top-level and owned by the caller.
196
+ The `Entity` policy lists `CreateView: Create()`, so any type that
197
+ does not restrict its allowlist can hold views.
198
+ - Returns the view's identifier.
199
+
200
+ **`DeleteEntity`** deletes a view and the views inside it.
201
+ Deleting an implicit view resets that placement, and everything inside it,
202
+ to its defaults.
203
+
204
+ ### Policy
205
+
206
+ ```python
207
+ policy.define(
208
+ View,
209
+ shareable=True,
210
+ can_contain=[View, Grant],
211
+ strategies={
212
+ SetViewState: Write(),
213
+ CreateView: Create(),
214
+ DeleteEntity: Delete(),
215
+ CreateGrant: ManageAccess(),
216
+ },
217
+ other_strategies=False,
218
+ )
219
+ ```
220
+
221
+ - `DeleteEntity` needs `Delete` to run on a view, the same
222
+ permission the deletion itself checks on the view.
223
+ - The deployment's allowlist includes `SetViewState: Create()` and
224
+ `CreateView: Create()`, so a member creates top-level views under
225
+ the creation rule: `Create` on the deployment.
226
+ - A view inside another view needs `Create` on that view, and a view placed
227
+ in an entity needs `Create` on that entity, through the same rule.
228
+ - `User` is defined with `can_contain=[]`.
229
+ - `shareable=True` with no grants leaves a view visible only to its owner.
230
+ Granting on a view shares it and every view inside it: an `editor` changes
231
+ the shared state, a `viewer` sees it and cannot change it.
232
+
233
+ ### Lookup
234
+
235
+ All lookups are ordinary `list_entities` queries over `View`:
236
+
237
+ - **A page**: `AllOf(Equal('owner', me), Equal('client', c),
238
+ Equal('address', a))` returns the page's view and every view inside it.
239
+ - **The views inside a view opened by id**:
240
+ `AllOf(ContainsValue('ancestor_ids', v), Equal('client', c))`.
241
+ - **A view**: by identifier.
242
+ - **The views of an entity**: `InValues('renders', ids)`.
243
+
244
+ A client matches the rows to its placements itself: the page's view is the
245
+ top-level row whose slot is the address, and each step below is the child
246
+ of the previous view with that step's `slot` and `renders`. A placement
247
+ whose parent view is absent has no view either, because a view is never
248
+ created without the views above it.
249
+
250
+ The web client batches every page and every view it opens by id in one
251
+ frame into one request. A page costs one round trip however deeply its
252
+ views nest. The one dependent read is a view whose id is itself stored
253
+ state (a panel or gallery card holding it): its views are found once the
254
+ state naming it has loaded.
255
+
256
+ ### Deletion
257
+
258
+ - **Deleting a shown entity** deletes every local view whose `renders`
259
+ names it, through `dependent_on`.
260
+ - **Deleting a view, or the entity a view is placed in,** deletes the views
261
+ inside it, through containment.
262
+ - Together these delete every view whose placement runs through a deleted
263
+ entity. On Alice's page for project P, the outline of document D is a child
264
+ of the page's view (`renders = P`). Deleting P deletes the page's view, and
265
+ the outline's view with it, although D still exists.
266
+ - An id held in state (a panel, a gallery card) is a plain value, not a
267
+ reference; when its view is deleted, it renders a tombstone.
268
+ - **A deleted principal's top-level views** fall under the open item for
269
+ top-level entities of a deleted principal (`ENTITY_REFERENCE_TDD.md`).
270
+
271
+ ### Frontend
272
+
273
+ #### Declaring a view component
274
+
275
+ ```tsx
276
+ function DocOutline({ entityId }: ViewProps) {
277
+ const doc = useEntity(entityId);
278
+ const [state, update] = useViewState({ collapsed: [] as string[] });
279
+ ...
280
+ }
281
+
282
+ export const DocOutlineView = defineView('docs.doc_outline', DocOutline, {
283
+ defaultFor: [DOC],
284
+ });
285
+ ```
286
+
287
+ An app's frontend entry exports its view components:
288
+
289
+ ```ts
290
+ export { DocOutlineView } from './DocOutline';
291
+ export { DocsHomeView } from './DocsHome';
292
+ ```
293
+
294
+ The installed-apps codegen imports each app's entry, and the registry
295
+ registers every export declared with `defineView`. `defineView` is the only
296
+ declaration. Two components with the same name, or two claiming
297
+ `defaultFor` on the same entity type, fail when the registry is built. An
298
+ app's entry point is declared with `defineView(name, Component, { entry: true })`.
299
+
300
+ #### What a view component does when rendered
301
+
302
+ The component `defineView` returns takes `entityId?` and `slot?` along with
303
+ the component's own props. Rendering it:
304
+
305
+ 1. reads the enclosing `ViewContext`: where the client started and the
306
+ placement so far;
307
+ 2. adds the step `slot ?? name` showing `entityId`;
308
+ 3. finds its view among the loaded rows;
309
+ 4. provides a `ViewContext` with the longer placement to everything inside
310
+ it;
311
+ 5. renders the component.
312
+
313
+ At the top of the tree, with no enclosing `ViewContext`, the context is the
314
+ current page's view: the client and the page's address, with a trailing `/`
315
+ dropped, and the empty placement. No component declares it. A placement at
316
+ the top of a page adds a step, so two placements side by side keep separate
317
+ state. The one exception is the main view of a route the library mounts
318
+ (`/`, `/e/<id>`, and app routes): it is the page's view itself rather than
319
+ a step below it. Outside a router there is no page, and state is not
320
+ stored.
321
+
322
+ #### `useViewState`
323
+
324
+ `useViewState(defaults)` returns `[state, update]`.
325
+
326
+ - `state` is the view's stored `state` merged over `defaults`, or `defaults`
327
+ alone when no view exists.
328
+ - `update(patch)` sends `SetViewState`: targeted at the view when it
329
+ exists, or with where it sits when it does not.
330
+ - State comes from the store, which is fed by `entity_update`. A refused
331
+ request is reported as an error and the store is unchanged.
332
+
333
+ `useViewState` takes no view name and no entity: both come from
334
+ `ViewContext`. A plain page component that calls it stores state in its
335
+ page's view.
336
+
337
+ `useCreateView()` returns `createView({ renders, component, state })`,
338
+ which creates a top-level explicit view owned by the user and resolves to
339
+ its id, or null when refused. Code that lists the views it creates keeps
340
+ their ids in its own state.
341
+
342
+ #### `EntityView`
343
+
344
+ `<EntityView entityId={id} slot? />` renders an entity whose component is
345
+ not fixed in code. Its view name is `entity`, and the chosen component
346
+ renders at its step. The component is, in order:
347
+
348
+ 1. the stored view's `component`, when this client knows it;
349
+ 2. the registry's `defaultFor` component for the entity's type;
350
+ 3. `BaseEntity`.
351
+
352
+ Choosing another component from the view toolbar sets `component` through
353
+ `useViewState`'s update path.
354
+
355
+ When `id` names a view, `EntityView` renders that view: its component, its
356
+ `renders`, and its `state`. The client starts there, so everything inside
357
+ it is stored in it.
358
+
359
+ A tombstone renders as a placeholder carrying its cause.
360
+
361
+ #### Routes
362
+
363
+ The web client reads the route table from the server
364
+ (`VIEW_SYSTEM_TDD.md`). `AppRoutes`, mounted as the shell's catch-all,
365
+ renders `/` and one route per app entry; `EntityRoute` renders `/e/<id>`.
366
+
367
+ - `/e/<id>` renders `<EntityView entityId={id} />` as the page's view: for
368
+ a data entity, the principal's view of the page `/e/<id>`; for a view, that
369
+ view.
370
+ - An app route renders the component registered under its view name as the
371
+ page's view, with the route's entity when it has one.
372
+ - `/` renders the registry's `home` view, else `ViewGallery`.
373
+ - Client routes (`/admin`, the auth page) are mounted by `GraphCoreApp`
374
+ beside `AppRoutes` and take precedence over it. Their pages store view state
375
+ in their page's view like any route, with nothing to declare.
376
+ - Public pages (`definePage`) are not views. `GraphCoreRouter` renders them
377
+ outside `GraphCoreProvider`, with no view state and no sign-in.
378
+
379
+ #### Composites
380
+
381
+ A composite lists what it shows in its state, as ids:
382
+
383
+ ```tsx
384
+ function HBoxView() {
385
+ const [state, update] = useViewState({
386
+ panels: [] as { entityId: string; slot?: string }[],
387
+ sizes: {} as Record<string, number>,
388
+ });
389
+ return (
390
+ <SplitPane sizes={state.sizes}>
391
+ {state.panels.map(p => (
392
+ <EntityView key={p.slot ?? p.entityId} entityId={p.entityId} slot={p.slot} />
393
+ ))}
394
+ </SplitPane>
395
+ );
396
+ }
397
+ ```
398
+
399
+ - Adding a panel is one state change on the composite. Removing one never
400
+ deletes what it showed.
401
+ - A panel's own state is an implicit view created the first time it changes.
402
+ - The composite passes a panel's `slot` to keep two panels of one entity
403
+ independent; how it generates one is the composite's choice.
404
+ - A panel holding a view's id renders that view.
405
+
406
+ A composite on a page is a personal layout. A layout others should see is
407
+ an explicit view, shared with them or placed in a shared entity.
408
+
409
+ #### Gallery
410
+
411
+ `ViewGallery` is a composite declared with `{ entry: true }` and rendered at
412
+ `/`. Its state holds the ids of the user's explicit views, as a composite
413
+ holds panels:
414
+
415
+ ```tsx
416
+ const [{ views }, update] = useViewState({ views: [] as string[] });
417
+ const createView = useCreateView();
418
+
419
+ const add = async (preset: string) => {
420
+ const id = await createView({ component: preset });
421
+ if (id) await update({ views: [...views, id] });
422
+ };
423
+ ```
424
+
425
+ Each card opens `/e/<view id>`. Removing a card removes its id.
426
+
427
+ ### Worked examples
428
+
429
+ **Opening a document.** Alice opens `/e/D`. The route renders
430
+ `<EntityView entityId={D} />` as the page's view. The client queries
431
+ Alice's web views at `/e/D`; none exist, so the type's default component
432
+ renders with its defaults. Nothing is written.
433
+
434
+ **Collapsing a section.** Alice collapses a heading. `update` sends
435
+ `SetViewState` with no target, `client: web`, `address: /e/D`, and
436
+ an empty placement. The executor checks the deployment's allowlist;
437
+ persistence checks `Create` on the deployment for a top-level `View`.
438
+ The view is created, owned by Alice, with `slot` and `address` `/e/D`, and
439
+ `entity_update` puts it in her store.
440
+
441
+ **A dashboard written in code.**
442
+
443
+ ```tsx
444
+ function ProjectDashboard({ entityId }: ViewProps) {
445
+ const project = useEntity(entityId);
446
+ return (
447
+ <TwoColumns>
448
+ <KanbanBoardView entityId={project.board_id} />
449
+ <DocOutlineView entityId={project.doc_id} />
450
+ </TwoColumns>
451
+ );
452
+ }
453
+ ```
454
+
455
+ Rendered at `/e/P` through its `defaultFor`, it is the page's view.
456
+ Collapsing a board column before anything else on the page has changed
457
+ stores two views in one request: the page's view (`slot = /e/P`,
458
+ `renders = P`, empty state) and its child (`slot = kanban_board`,
459
+ `renders = B`) holding the change, both with `address = /e/P`. The board's
460
+ own page, `/e/B`, is unaffected. Reloading `/e/P` finds both in one query.
461
+
462
+ **Creating a view from the gallery.** Alice picks a preset. The gallery
463
+ sends `CreateView` with no target, creating a top-level view V
464
+ owned by Alice, then adds V's id to its own state. The card opens `/e/V`.
465
+
466
+ **Sharing a dashboard.** Alice creates an explicit view V of P and grants
467
+ Bob `editor` on it. Both open it by id. A column Bob collapses is stored as
468
+ a child of V (`slot = kanban_board`, `renders = B`, no address), and Alice
469
+ receives it because she can read V. (V renders the dashboard itself, so its
470
+ board is the first step.)
471
+
472
+ **Deleting a document.** Bob deletes D. Every view with `renders = D` is
473
+ deleted, with the views inside each: Alice's view of the page `/e/D`, the
474
+ outline of D on her project page, and every explicit view of D. A gallery
475
+ card holding a deleted view's id shows a tombstone.
476
+
477
+ ## Trade-offs
478
+
479
+ - **State belongs to the placement.** The same document in two places has
480
+ two states. This is Requirement 3.
481
+ - **One view per placement** rather than one document per page. Each
482
+ placement is its own entity with its own access, history, and dependent
483
+ reference, at the cost of a row per placement that has changed.
484
+ - **Where a view sits is plain fields, not a string.** A view stores its
485
+ own `slot` and `renders` and its page's `address`; the client matches rows
486
+ to placements itself. No client builds a key, and the server alone defines
487
+ what makes two siblings the same. The server hashes a view's sibling scope,
488
+ client, slot, and entity for its unique constraint, privately.
489
+ - **One identity rule.** A page's view is a top-level view whose slot is
490
+ the address; every other view's slot is its placement name. Uniqueness among
491
+ siblings, a general kernel notion, covers both.
492
+ - **Lists of views are ids in state** rather than containment. A gallery or
493
+ composite holds the ids it shows, so containment means only nesting.
494
+ Creating a view from the gallery is two writes (create, then add its id);
495
+ when the second fails, the view exists and no gallery lists it.
496
+ - **One state object per placement across component changes.** Switching a
497
+ placement's component keeps its state; each component reads the keys it
498
+ declares and ignores the rest.
499
+ - **Shared state is all-or-nothing.** Everyone with access to a view sees
500
+ the same state; there is no personal layer over a shared view.
501
+ - **A nested change stores the views above it.** The first change deep in
502
+ the tree also creates every view above it that does not exist yet, with
503
+ empty state: at most one row per nesting level, once.
504
+ - **A page query returns every view stored on the page,** including views
505
+ for placements not shown at the moment. Pages hold few views; a page that
506
+ outgrows one result page is read with the query's cursor.
507
+ - **A panel or card whose entity is deleted stays until removed.** Lists
508
+ live in state, which is not a dependent field, so the entry shows a
509
+ tombstone rather than silently disappearing.
510
+
511
+ ## Open items
512
+
513
+ - **Views of entities on other deployments.** A client renders a remote
514
+ entity in an iframe of the owning deployment's page. Sharing such a view
515
+ across deployments needs capability subjects (share links), an open item
516
+ in `AUTHORIZATION_TECHNICAL_TDD.md`.
517
+ - **Personal state over shared views.**
518
+ - **Templates**: creating a view from another view's state.
519
+ - **Mobile clients**: their registries and view state
520
+ (`VIEW_SYSTEM_TDD.md`).
521
+ - **Live updates for remote entities shown in views**, inherited from
522
+ `ENTITY_REFERENCE_TDD.md`.