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,389 @@
1
+ # Agent Frontend — Technical Design
2
+
3
+ ## Introduction
4
+
5
+ An agent is a client of a GraphCore deployment, in the same position as the
6
+ web frontend: it acts for the user who connected it, reads what that user
7
+ may read, and acts through strategies. Unlike the web frontend, the agent
8
+ host (Claude, ChatGPT, an IDE agent) cannot run our code. The **agent
9
+ frontend** therefore renders for it on the server: an ASGI app, separate
10
+ from Django, that resolves addresses, renders them as text for a language
11
+ model, and exposes the result over MCP. It reaches the kernel only through
12
+ `GraphAPI`, as the web frontend does.
13
+
14
+ The problem it solves is entry and orientation. The entity graph has no
15
+ fixed shape an agent can memorize: containers nest, apps add types, and
16
+ access differs per user. The agent frontend gives an agent what the web
17
+ client gives a person: a home, addresses it can open, and actions that
18
+ depend on where it is. The surface is hypermedia: the agent holds renders
19
+ and verbs, never view logic or state.
20
+
21
+ It is also shaped by where its output goes. Every render the agent reads
22
+ stays in its context window for the rest of the conversation. Renders are
23
+ compact by default, tool definitions never change, and writes return small
24
+ results.
25
+
26
+ This document is part of the view system (`VIEW_SYSTEM_TDD.md`), which
27
+ defines addresses, the route table, client registries, render versions,
28
+ and mirroring. It does not cover authorization
29
+ (`AUTHORIZATION_TECHNICAL_TDD.md`) or identity (`IDENTITY.md`).
30
+
31
+ ## Definitions
32
+
33
+ - **Agent**: a program, typically a language model with a tool-calling
34
+ loop, connected over MCP. An agent is not a principal. It forwards the
35
+ credentials of the user who connected it, and every read and write is
36
+ that user's.
37
+ - **Agent host**: the application running the agent and its MCP client:
38
+ Claude, Claude Code, ChatGPT.
39
+ - **Agent frontend**: the `agent` client: `graphcore.agent_frontend`, an
40
+ ASGI app served beside Django by the same server. It holds the agent
41
+ registry, renders addresses, and serves the MCP endpoint.
42
+ - **Address**: as in `VIEW_SYSTEM_TDD.md`. Every tool that reads or acts at
43
+ a place takes its address as `at`.
44
+ - **Agent view**: a render function registered with `@agent_view`. It
45
+ renders one view name and declares the view's tools.
46
+ - **Render**: Markdown produced for one address: a header, the view's
47
+ content, its child placements, and its tool signatures.
48
+ - **Placement**: another address placed inside a render, **full** (rendered
49
+ with its own agent view) or **compact** (one line: label, type, address).
50
+ - **View tool**: a tool an agent view offers at its address. Either a
51
+ **strategy tool**, which runs one registered strategy, or an
52
+ **operation**, which is view code that performs several reads and
53
+ strategy executions as one tool.
54
+ - **Tool signature**: a view tool written compactly in a render:
55
+ `review_document(doc: entity, verdict: approve|reject, note?: str)`.
56
+ - **Generic tools**: the four MCP tools the endpoint exposes: `open`,
57
+ `find`, `call`, `act`.
58
+
59
+
60
+
61
+ ## Requirements
62
+
63
+ 1. **Stable entry.** An agent starts at `/` and reaches any entity its user
64
+ may read with the generic tools alone, without prior knowledge of the
65
+ graph or app-specific tools.
66
+ 2. **Location-dependent affordances.** The tools offered at an address are
67
+ the ones its view declares, decided in code by the app, as the web view
68
+ decides its controls.
69
+ 3. **Parity with the web client.** The data an agent view renders is data
70
+ the web client shows at the same address, read through the same
71
+ `GraphAPI` calls.
72
+ 4. **Composition.** A view places other addresses without knowing how they
73
+ render. Each placement is rendered by the agent view resolved for it,
74
+ registered or default.
75
+ 5. **Curation without lock-in.** A view may show a subset and offer
76
+ operations; `find` and `act` still reach everything the user may read
77
+ and do.
78
+ 6. **No new authority.** Agent views, operations, and defaults confer no
79
+ access. Every read and write passes through `GraphAPI` as the user.
80
+ 7. **Stateless.** The server holds nothing between calls. Every call names
81
+ its address; no session, location, or subscription is kept.
82
+ 8. **Fixed tool list.** The MCP tool list is the same for every user, every
83
+ address, and every call.
84
+ 9. **Context economy.** Renders place children compactly unless the view
85
+ asks for more, tool signatures are compact, and writes return small
86
+ results.
87
+ 10. **Stale writes are refused.** A write states the render version it was
88
+ based on; a changed address refuses it.
89
+ 11. **Readable on its own.** A render is complete without view state,
90
+ layout, or an earlier render.
91
+
92
+
93
+
94
+ ## Architecture
95
+
96
+
97
+
98
+ ### Serving and transport
99
+
100
+ ```
101
+ uvicorn (graphcore run, one port)
102
+ /mcp ← agent host (MCP) → agent frontend (ASGI) → GraphAPI client ┐
103
+ all else ← browser (HTTP/WS) → Django (ASGI) │ in-process
104
+ GraphAPI ◄──────┘
105
+ ```
106
+
107
+ - The agent frontend is its own ASGI app, separate from Django. The
108
+ deployment's ASGI entry routes `/mcp` to it and everything else to
109
+ Django, so `graphcore run` serves both on one port. It is deployed and
110
+ launched with the rest of the backend and adds no role, port, or proxy.
111
+ - It calls `GraphAPI` through a client interface. The implementation in use
112
+ calls `GraphAPI` in the same process. An implementation over the
113
+ backend's HTTP and WebSocket transports would let the agent frontend run
114
+ as its own server without changing its code.
115
+ - Its code is `graphcore.agent_frontend`, in the `graphcore` package,
116
+ structured as a library: a public API for apps' agent views, depending
117
+ on the `GraphAPI` client interface and the public types and never on
118
+ Django or the backend's modules.
119
+ - At startup it reads the route table and the strategy registry's request
120
+ schemas from `GraphAPI`, and registers the agent views of every installed
121
+ app (`VIEW_SYSTEM_TDD.md`, App bootstrap).
122
+ - The MCP endpoint uses Streamable HTTP without a session identifier. Each
123
+ request is authenticated and answered on its own.
124
+ - The endpoint requires a bearer token on every request, authenticates it
125
+ through the `GraphAPI` client, and passes the user as the principal of
126
+ every `GraphAPI` call. A missing or invalid token gets a 401. Its
127
+ `WWW-Authenticate: Bearer resource_metadata="…"` points at
128
+ `/.well-known/oauth-protected-resource/mcp`, which names the issuer, so an
129
+ MCP host signs the user in at the issuer itself (dynamic client registration,
130
+ then code + PKCE) and never needs a pasted token. See
131
+ `kernel/backend/graphcore/auth/authn/README.md` (Telling clients where to
132
+ sign in).
133
+
134
+
135
+
136
+ ### Generic tools
137
+
138
+ The endpoint exposes exactly these tools.
139
+
140
+
141
+ | Tool | Does | Authorization |
142
+ | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------- |
143
+ | `open(at, version?)` | Returns the render at `at`. With `version`, the render also states whether the address changed since that version. | Read on the address's entity, when it has one; every read the render makes. |
144
+ | `find(type, predicate?, limit?)` | Runs the access-scoped typed query. Returns matches compactly: label, type, address. | The kernel's read scoping of `list_entities`. |
145
+ | `call(at, tool, params, seen_version?)` | Resolves the view at `at`, checks that `tool` is one of its view tools, and runs it. | Each strategy execution, as the user. |
146
+ | `act(strategy, target?, params)` | Runs any registered strategy, outside any view. | The strategy's invocation and persistence checks. |
147
+
148
+
149
+ `open` and `find` read; `call` and `act` write. `call` is the curated path;
150
+ `act` is the escape hatch that keeps a view from locking the agent out of
151
+ anything, as typing a URL bypasses a page's buttons.
152
+
153
+ `call`:
154
+
155
+ - Without `seen_version`, it runs unchecked. With it, the server
156
+ re-renders `at` and refuses a mismatch with `Stale`, returning the
157
+ current version and a one-line description of what changed.
158
+ - `params` are checked against the tool's request schema. A mismatch
159
+ returns `InvalidRequest` with the full JSON schema.
160
+ - A success returns the tool's result, the address, its new render
161
+ version, and a one-line note of what changed. It never returns a render;
162
+ the agent calls `open` when it wants one.
163
+
164
+ The endpoint's MCP `instructions` state: start with `open("/")`; every
165
+ render begins with its address and version; renders are snapshots, so
166
+ re-open an address before answering about its current state; pass
167
+ `seen_version` when acting on a render.
168
+
169
+ ### Resources
170
+
171
+ Each route is a resource template whose URI is the deployment's base URL
172
+ followed by the route. `resources/read` returns the same render as `open`.
173
+ The endpoint does not support `resources/subscribe`, which needs state
174
+ held per connection (Requirement 7).
175
+
176
+ ### Render format
177
+
178
+ ```markdown
179
+ # Handbook · stacks.Stack
180
+ address: /e/k3x9…/m2p… · version: 7f3a…
181
+
182
+ The team handbook. 42 documents, 3 awaiting review.
183
+
184
+ ## Awaiting review
185
+ - Onboarding · stacks.Document · /e/k3x9…/a81…
186
+ - Expense policy · stacks.Document · /e/k3x9…/b02…
187
+ - On-call · stacks.Document · /e/k3x9…/c77…
188
+
189
+ ## Tools
190
+ - create_document(title: str, folder?: entity) — Create a document in this stack.
191
+ - review_document(doc: entity, verdict: approve|reject, note?: str) — Record a review.
192
+ - publish_reviewed() — Publish every approved document in this stack.
193
+ ```
194
+
195
+ - The header is the label and type (or the view name when there is no
196
+ entity), the address, and the render version.
197
+ - A compact placement is one line: label, type, address.
198
+ - A full placement is the child's render under a heading, without its
199
+ tools section.
200
+ - Tool signatures list parameters with their types and a one-line
201
+ description. `entity` marks a parameter that takes an address or
202
+ identifier.
203
+
204
+
205
+
206
+ ### Agent views
207
+
208
+ An agent view is a function in the app's agent frontend package (`backend/<app>_agent_frontend/`), by convention in `agent_views.py`:
209
+
210
+ ```python
211
+ async def stack_tools(ctx, stack):
212
+ return [
213
+ strategy_tool('CreateDocument', bind=stack.entity_id),
214
+ strategy_tool('ReviewDocument', name='review_document'),
215
+ publish_reviewed,
216
+ ]
217
+
218
+ @agent_view('stacks.stack', default_for=['stacks.Stack'], tools=stack_tools)
219
+ async def stack(ctx, stack):
220
+ docs = await ctx.children(stack, 'stacks.Document')
221
+ pending = [d for d in docs if d.review_status == 'pending']
222
+ return [
223
+ f"{stack.description}\n\n{len(docs)} documents, {len(pending)} awaiting review.",
224
+ "## Awaiting review",
225
+ *[ctx.place(d.id) for d in pending],
226
+ ]
227
+ ```
228
+
229
+ - Entity types are named by their registry identifiers (`'stacks.Stack'`) and
230
+ strategies by their bare registry names (`'CreateDocument'`). The
231
+ agent frontend does not import the app's backend.
232
+ - `ctx` carries the user and the address, and offers `GraphAPI` reads
233
+ (`ctx.get`, `ctx.children`, `ctx.find`, `ctx.query`), the route table (`ctx.routes`),
234
+ registered agent views by name (`ctx.view`), and placement.
235
+ - `ctx.place(target, full=False)` places an entity identifier (its
236
+ `/e/{entity}` address) or any address. Placement records the address;
237
+ the frontend renders it.
238
+ - The function returns a list of strings and placements, joined in order.
239
+ - `@agent_view(name, default_for=[...], tools=fn)`. `tools` is
240
+ `async def (ctx, entity) -> list`, called on every render with the same
241
+ `ctx` and entity as the view; `entity` is `None` for a view with no entity.
242
+ - Every module-level agent view defined in an app's agent frontend
243
+ package is registered at startup. A view one module imports from another
244
+ package is not registered again.
245
+ - The registry has two layers. The base views (see Defaults) form the
246
+ lower layer; app views form the upper one. An app view with the same name
247
+ or `default_for` type as a base view replaces it. Two app views with the
248
+ same name, or claiming `default_for` on the same type, fail at
249
+ registration.
250
+
251
+ A parent never sees how a placement renders. The child's agent view, or the
252
+ default, decides that, as `<EntityView entityId={id} />` does in the web
253
+ client.
254
+
255
+ ### Resolution
256
+
257
+ As in `VIEW_SYSTEM_TDD.md`, with the agent registry, where every view,
258
+ base or app, is found the same way: by the view name its route resolves to.
259
+
260
+ 1. For `entity`, the agent view whose `default_for` includes the entity's
261
+ type.
262
+ 2. The agent view registered under the route's view name: `home` at `/`,
263
+ `entity` at `/e/{entity}`, an app's own name at its routes.
264
+ 3. For a route with an entity, the agent view registered as `entity`.
265
+ 4. A placeholder naming the view and its address.
266
+
267
+ The agent client stores no view state of its own. It reads the view
268
+ entities other clients store: a `graphcore.View` renders with the
269
+ base `view` view (step 1), as the agent view its `component` names, over the
270
+ entity it `renders`. View names are shared across clients, so a web view and
271
+ an agent view registered under one name render the same view entity.
272
+ Choosing an agent view for a placement through stored view state is an open
273
+ item.
274
+
275
+ ### Placement depth
276
+
277
+ Placements have no depth limit; a view decides how much of its children to
278
+ render. A render larger than the endpoint's size limit fails with
279
+ `RenderTooLarge`, naming the address, rather than being truncated. The
280
+ limit is below the tool-result limits of common agent hosts, so a host
281
+ never truncates a render.
282
+
283
+ ### View tools
284
+
285
+ A **strategy tool** names a registered strategy and declares its target:
286
+
287
+ - **`takes_target=True`** (the default): the agent supplies the target. The
288
+ tool's signature and schema gain a required `target` parameter, an entity
289
+ id or address.
290
+ - **`takes_target=False`**: the strategy runs untargeted, on the
291
+ deployment's authority. The agent sees no target.
292
+ - **`bind=<entity id>`**: the view fixes the target, so the agent sees no
293
+ target. `bind` takes precedence over `takes_target`.
294
+
295
+ ```python
296
+ async def stack_tools(ctx, stack):
297
+ return [
298
+ # Bound: runs on this stack.
299
+ # Signature: archive_stack()
300
+ strategy_tool('ArchiveStack', bind=stack.entity_id),
301
+ # Default: the agent supplies `target`.
302
+ # Signature: review_document(target: entity, verdict: str)
303
+ strategy_tool('ReviewDocument', name='review_document'),
304
+ # takes_target=False: runs untargeted on the deployment's authority.
305
+ # Signature: create_stack(name: str)
306
+ strategy_tool('CreateStack', takes_target=False),
307
+ ]
308
+
309
+ @agent_view('stacks.stack', default_for=['stacks.Stack'], tools=stack_tools)
310
+ async def stack(ctx, stack): ...
311
+ ```
312
+
313
+ Its schema is the strategy's request schema from the registry, with
314
+ `target` added only when the agent supplies it. The Tools list shows each tool as a compact
315
+ signature; a parameter that is not a scalar shows as `json`, and the full
316
+ schema is returned in the error when `call` rejects the parameters.
317
+
318
+ An **operation** is a function decorated with `@operation`, taking `ctx`
319
+ and its parameters and declaring its request schema. It performs reads and
320
+ strategy executions through `ctx`, each checked as the user; it has no
321
+ other path. Operations exist for multi-step tasks ("create a document in
322
+ the review folder and assign a reviewer") and computed targets ("archive
323
+ every document in this stack with no edits in 90 days").
324
+
325
+ A tool's name and description default to the strategy's; the view may set
326
+ either.
327
+
328
+ ### Defaults
329
+
330
+ Every address renders and acts with no app agent-view code at all. The
331
+ defaults are the base views in `graphcore.agent_frontend.base`, declared
332
+ with `@agent_view` like any app view and registered in the base layer:
333
+
334
+ - **`entity`**: three sections. `## Entity` states the base entity's
335
+ structural keys plainly: id, type, owner (marked `(you)` for the caller),
336
+ parent as label, type and address or `none (top level)`, version and sibling
337
+ position. `## Fields` prints every other key of `to_dict()`, `attributes`
338
+ included: strings bare, other values as JSON, an entity identifier with its
339
+ address, and a value longer than 500 characters cut with its full length.
340
+ `## Children (n)` places the children compactly, in sibling order. Tools
341
+ are the strategies the policy allows on the type, each as a strategy tool
342
+ bound to the entity. An app that adds a strategy to another app's type
343
+ with `policy.extend` adds it to that type's default tools. The sections
344
+ are exported (`entity_summary`, `entity_fields`, `children_section`) for an
345
+ app view to reuse.
346
+ - **`home`**: `## Places`, a compact placement of every route other than
347
+ `/` that needs no entity, then the user's top-level entities grouped by
348
+ type, placed compactly. Tools are the strategies on the deployment's
349
+ allowlist. The web client's `TopBar` links the same routes.
350
+ - **`view`**, the default for `graphcore.View`: a view renders as
351
+ itself, as in the web client. It calls the agent view its `component`
352
+ names (`ctx.view(name)`) with the entity it `renders`, or with none, under
353
+ one line naming the component and the view entity. The component reads the view
354
+ entity's stored `state` as `ctx.view_state` (empty outside a view entity),
355
+ so it shows what another client stored there, such as a selection. Tools are the
356
+ component's, then the view entity's own. Without an agent view of that name,
357
+ or when the name is the `view` view's own, it renders with `entity` under a
358
+ note; when its `renders` entity is not readable, it says so.
359
+
360
+ An app replaces any of them by registering an agent view under its name, or,
361
+ for `view`, claiming `graphcore.View` in `default_for`:
362
+
363
+ ```python
364
+ from graphcore.agent_frontend import agent_view
365
+ from graphcore.agent_frontend.base import children_section, entity_fields, type_tools
366
+
367
+ @agent_view('entity', tools=type_tools)
368
+ async def entity(ctx, entity):
369
+ return ['\n'.join(entity_fields(ctx, entity)), *await children_section(ctx, entity)]
370
+ ```
371
+
372
+ The module also exports its parts for reuse: `entity_summary`,
373
+ `entity_fields`, `children_section`, `places`, `grouped`, `type_tools`,
374
+ `deployment_tools`, and the views `entity_view` and `home_view`. A view with `default_for` that wants the type's default tools
375
+ returns `type_tools(ctx, entity)` from its `tools`.
376
+
377
+
378
+
379
+ ### Authorization
380
+
381
+ The agent frontend performs no checks and skips none:
382
+
383
+ - Renders, including every placement, are built from `GraphAPI` reads,
384
+ which refuse what the user may not read. A render cannot place an entity
385
+ the user cannot open.
386
+ - `call` and `act` run strategies through `GraphAPI` as the user.
387
+ - An operation's steps are checked one by one; a refused step raises, and
388
+ the operation reports the refusal.
389
+
@@ -0,0 +1,152 @@
1
+ # Kernel Architecture Principles
2
+
3
+ How the kernel is organized and the rules code must follow.
4
+
5
+ ## The pattern
6
+
7
+ Hexagonal at the boundary, command-based in the core.
8
+
9
+ - **Not Django active record**: storage is a private decision below the
10
+ serialization boundary; the interchange model, not the Django model, is the
11
+ entity.
12
+ - **Not full tactical DDD**: the consistency unit is fixed globally — one
13
+ optimistic-locked entity — so aggregate machinery would re-derive settled
14
+ kernel contract.
15
+ - **CQRS by construction**: strategies are the only writes (command pattern,
16
+ a kernel invariant); views and ACL-scoped queries are the read side.
17
+
18
+ ## The rules
19
+
20
+ 1. **Entities hold domain state and behavior, and declare metadata. They
21
+ never call infrastructure.** No imports of DB, cache, channels, or
22
+ adapters from an entity class.
23
+ 2. **Declarative metadata on domain classes is legitimate; imperative
24
+ infrastructure calls are not.** `write_once_fields`, `ownerless`, param
25
+ schemas on entities; `CPU_BOUND`, `read_only_strategy` on strategies;
26
+ `can_contain`, `read`, `delete` in a type's access policy — facts about the
27
+ type, read by the layer that owns the concern (the executor, for the
28
+ strategy examples; the engine, for the policy ones), never invoked by the
29
+ class itself.
30
+ 3. **Strategies are the only writes.** Transports get no side paths around
31
+ the executor.
32
+ 4. **Kernel services are stateless orchestrators, one concern each**
33
+ (graph engine, access policy, broadcast, persistence), composed by
34
+ constructor injection. Components swap; classes don't subclass. No
35
+ constructor builds a collaborator it was not given — no `param=None`
36
+ replaced by a constructed default, no reach for a process-wide
37
+ singleton. `graphcore/runtime.py` is the one place that wires concrete
38
+ components together; see its docstring.
39
+ 5. **One boundary facade (`GraphAPI`); transports are adapters** doing wire
40
+ format and error mapping only. Pull (request/response) goes through the
41
+ facade; push (broadcast) is a separate surface delivered only by
42
+ transports that can push.
43
+ 6. **Dependencies point inward**: transport → api → services → domain.
44
+ A service must not import its callers, including their input or result
45
+ types. The service owns its contract; callers depend on that contract.
46
+ `domain/` may depend on shared types and kernel errors, never on its
47
+ consumers.
48
+ (Known exception, to be removed: `Entity.get_entity_type_id()` reads the
49
+ registry.)
50
+ 7. **The engine and ports are agnostic of concrete entity types.**
51
+ `EntityService` (the engine) knows only `Entity`. Type-specific behavior
52
+ reaches it through a port — an interface whose contract names no concrete
53
+ entity type (access, persistence, broadcast, scheduling, authentication)
54
+ — or through declarative metadata on the type. The kernel ships kernel
55
+ entity types (`User`, `Group`, `Grant`,
56
+ `Deployment`, `StrategyRequest`); adapters and kernel
57
+ services that depend on one document that dependence. An application
58
+ extends a kernel type by subclassing it, which is required to get the
59
+ behavior adapters give that type; an application that needs different
60
+ behavior without subclassing writes its own adapter for that port.
61
+ Replacing an adapter must not require changing the engine.
62
+ 8. **Prefer declarative state and reconciliation, with entities as the
63
+ source of truth.** When any part of the system must follow entity state
64
+ (infrastructure, derived stores, external mirrors), the entity declares
65
+ the desired state and that part reconciles toward it, both on committed
66
+ changes and by periodically re-reading the full entity state, so a
67
+ missed change converges. Where reconciliation lives (an adapter, a
68
+ service, a task) is decided per case. What holds everywhere:
69
+ - changing desired state is one ordinary write to the entity;
70
+ - the follower never writes its status back onto entities;
71
+ - a failure to reconcile never fails the write that caused it;
72
+ - consumers tolerate lag by checking entity state at the point of use.
73
+
74
+ Exceptions: authorization and persistence are on the write path and are
75
+ synchronous; side effects that must happen exactly once are not
76
+ reconciled state. Scheduling is an example (`docs/SCHEDULING_TDD.md` in
77
+ the monorepo).
78
+
79
+ Type-to-infrastructure bindings (storage models/adapters, views, strategies)
80
+ live in the **registry**, not on the domain class — registry binding, not
81
+ dependency injection: the class is the lookup key, never a consumer of the
82
+ bound value.
83
+
84
+ ## Shared types
85
+
86
+ Shared input and result types live in `graphcore/types/`, organized by
87
+ concern. They must not depend on APIs, services, or infrastructure.
88
+ Component-specific types stay with their owning component.
89
+
90
+ ## Package map
91
+
92
+ ```
93
+ graphcore/
94
+ public/ # app-author import surface (re-exports from domain/)
95
+ api/ # boundary facade: GraphAPI and payload conversion
96
+ types/ # shared input and result types, organized by concern
97
+ domain/ # entity/ and strategy/ implementations
98
+ registry/ # binding layer: type directories, discovery, decorators
99
+ # (see registry/README.md for the startup lifecycle)
100
+ graph/ # the entity-graph engine (EntityService orchestrates
101
+ # persistence and broadcast, and calls the access port)
102
+ persistence/ # the storage seam: EntityRepository contract, with the
103
+ # Django implementation (column split, compiler) under
104
+ # persistence/django
105
+ execution/ # strategy executor, dispatchers, Celery tasks
106
+ scheduling/ # the Scheduler port and its default adapter
107
+ auth/ # authentication: verify token, map (iss, sub) → Principal
108
+ transport/ # HTTP/WS adapters, routing, urls
109
+ errors.py # KernelError hierarchy (transports map these to the wire)
110
+ docs/ # doc topics + discovery (and this file)
111
+ runtime.py # composition root: Runtime, build_runtime, django_runtime,
112
+ # get_runtime — the only module naming concrete
113
+ # infrastructure or reading GRAPHCORE_* settings;
114
+ # called only from process entrypoints
115
+ ```
116
+
117
+ Root keeps only framework contracts (`apps.py`, `models.py`, `migrations/`,
118
+ `celery.py`, `urls.py` re-export, `test_settings.py`).
119
+
120
+ Planned extractions (created when their component lands): `access/` (ACL
121
+ policy + group resolution out of the graph engine), `broadcast/` (event
122
+ fan-out out of the graph engine).
123
+
124
+ ## Conventions
125
+
126
+ - **`to_dict()` is full-fidelity; `to_client()` is the wire boundary; there
127
+ is no third representation.** `to_dict()` is the complete,
128
+ JSON-compatible, round-trippable state — system fields, typed subclass
129
+ fields, the attribute bag nested under `attributes` — and never the derived
130
+ projections (`children_ids`, `parent_ids`, `ancestor_ids`, `reference_ids`). `from_dict`
131
+ is its classmethod inverse. `to_client()` defaults to `to_dict()` plus
132
+ those four projections and is what every consumer (frontend, agent
133
+ context, CLI, MCP, other backends) is read through; override it per-type
134
+ to drop fields that shouldn't reach a client (e.g. auth correlation keys)
135
+ or trim heavy payloads (e.g. an audio entity's chunk data). Storage *is*
136
+ `to_dict()`/`from_dict()` too: the Django repository maps typed fields and the nested `attributes` bag directly to their columns using the bound model's `_meta` —
137
+ there is no mapper and no separate record type.
138
+ - **Reads tombstone, writes raise.** Absence and denial on reads resolve to
139
+ a `Tombstone(cause)` so a failed hop never breaks a surrounding render;
140
+ write failures raise typed `KernelError`s that adapters map mechanically.
141
+ - **`Principal`, never a raw user id or token**, is who is calling; it is
142
+ produced by a pluggable authenticator at the boundary.
143
+ - **Two authoring tiers per entity type.** The *attribute path*: generic base
144
+ strategies (set/remove attributes, generic create) over the schemaless
145
+ `attributes` dict — a fully functional app with zero new code, at the cost
146
+ of no type enforcement. The *typed path*: an entity subclass with class
147
+ fields and its own storage model — the generic attribute strategies cannot
148
+ touch class fields, so a typed entity's invariants are only reachable
149
+ through strategies it declares. Graduating a type is how you buy
150
+ enforcement; kernel-sensitive types (e.g. `Grant`) use the typed
151
+ path for exactly this property. (When to graduate, and what the migration
152
+ looks like, still needs design work.)