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,710 @@
1
+ from graphcore.types.access import Perm
2
+ from graphcore.types.identity import Principal
3
+ from graphcore.types.entities import EntityFilter, EntityPage, Tombstone
4
+ from graphcore.types.entity_id import backend_of, deployment_entity_id, new_entity_id
5
+ from graphcore.types.query import AllOf, AnyOf, EntityQuery, Equal, InValues, PageRequest, Predicate
6
+ from graphcore.execution.strategy_context import KERNEL_INTERNAL, current_strategy
7
+ from graphcore.errors import InvalidRequest, NotFound, Forbidden, RemoteUnavailable
8
+ from graphcore.domain.entity.Entity import Entity
9
+ from graphcore.registry.registry import Registry
10
+ from graphcore.persistence.repository import NOT_LOADED, EntityRepository, Precondition
11
+ from graphcore.graph.entity_cache import EntityCache
12
+ from graphcore.auth.authz.access_port import AccessPort
13
+ from graphcore.broadcast.broadcaster import Broadcaster
14
+ from graphcore.scheduling.scheduler import Scheduler
15
+ from graphcore.gateway.remote import RemoteGateway
16
+ from graphcore.errors import ConcurrentModificationError, PreconditionFailed
17
+ from dataclasses import replace
18
+ from typing import Optional
19
+ import logging
20
+
21
+ logger = logging.getLogger(__name__)
22
+
23
+ class EntityService:
24
+ def __init__(self, registry: Registry, repository: EntityRepository, cache: EntityCache,
25
+ access_adapter: AccessPort, broadcaster: Broadcaster, scheduler: Scheduler,
26
+ backend_id: str, gateway: RemoteGateway):
27
+ self.registry = registry
28
+ self.repository = repository
29
+ self.cache = cache
30
+ self.access_adapter = access_adapter
31
+ self.broadcaster = broadcaster
32
+ self.scheduler = scheduler
33
+ self.backend_id = backend_id
34
+ self.deployment_entity_id = deployment_entity_id(backend_id)
35
+ self.gateway = gateway
36
+
37
+ def create(self, entity_cls, **kwargs):
38
+ """The only path that mints an identifier. The id carries this
39
+ deployment's identity, which is why it is not the entity's to
40
+ choose."""
41
+ return entity_cls(entity_id=new_entity_id(self.backend_id), **kwargs)
42
+
43
+ def _is_local(self, entity_id) -> bool:
44
+ """The routing rule, and the only place the backend segment is read
45
+ besides the containment check in `save_to_db`. A value that is not an
46
+ identifier at all (PUBLIC, a bare subject id) stays on the local path,
47
+ where it resolves to nothing as it always has."""
48
+ try:
49
+ return backend_of(entity_id) == self.backend_id
50
+ except InvalidRequest:
51
+ return True
52
+
53
+ def _read_permission(self, entity_type_id: str) -> Perm:
54
+ return self.registry.policy.read_permission(self.registry.entities.get_entity_class(entity_type_id))
55
+
56
+ async def _can_read(self, principal: Principal, entity) -> bool:
57
+ perm = self._read_permission(entity.entity_type_id)
58
+ return await self.access_adapter.allows(principal, perm, entity.entity_id)
59
+
60
+ async def _read_predicate(self, principal: Principal) -> Predicate:
61
+ """What `principal` may read: each registered type filtered by its
62
+ own read permission. The predicate language has no NotIn, so when
63
+ types differ every type id is listed under its permission."""
64
+ type_ids_by_perm: dict[Perm, set[str]] = {}
65
+ for type_id, entity_cls in self.registry.entities.get_all_entities().items():
66
+ type_ids_by_perm.setdefault(self.registry.policy.read_permission(entity_cls), set()).add(type_id)
67
+ filters = await self.access_adapter.read_filters(principal, list(type_ids_by_perm))
68
+ if len(type_ids_by_perm) == 1:
69
+ (perm,) = type_ids_by_perm
70
+ return filters[perm]
71
+ return AnyOf(tuple(
72
+ AllOf((InValues('entity_type_id', type_ids), filters[perm]))
73
+ for perm, type_ids in type_ids_by_perm.items()
74
+ ))
75
+
76
+ async def get_entity(self, entity_id, principal: Principal):
77
+ """Get an entity by its ID from storage with authorization check.
78
+
79
+ Authorization is answered by the AccessPort against persisted state
80
+ on every call, so a revoked grant applies on the very next read. No
81
+ payload cache: the access decision loads the entity anyway. A remote
82
+ identifier goes to the gateway instead: no local access decision.
83
+ """
84
+ if not self._is_local(entity_id):
85
+ result = (await self.gateway.get_entities([str(entity_id)], principal))[str(entity_id)]
86
+ if isinstance(result, Tombstone):
87
+ raise RemoteUnavailable(
88
+ f"Entity {entity_id} could not be read from its owning deployment",
89
+ cause=result.cause,
90
+ )
91
+ return result
92
+
93
+ db_entity = await self.load_from_db(entity_id)
94
+ if db_entity is None:
95
+ raise NotFound(f"Entity with ID {entity_id} not found")
96
+
97
+ if not await self._can_read(principal, db_entity):
98
+ raise Forbidden(
99
+ f"User {principal.principal_entity_id} does not have read access to entity {entity_id}"
100
+ )
101
+
102
+ return db_entity
103
+
104
+ async def save_entity(self, entity, principal: Principal, precondition: Optional[Precondition] = None,
105
+ existing=NOT_LOADED):
106
+ """Save an entity with authorization check and broadcast the update.
107
+ `existing` is kernel code's own copy of the entity as it loaded it,
108
+ before changing it (None for a create), to save reading it again."""
109
+ receipt = await self.save_to_db(entity, principal, precondition, existing)
110
+
111
+ # Cached payloads are used only at their stored version, so a save
112
+ # leaves them be - except a create, whose version 1 a deleted entity
113
+ # of the same id may have cached.
114
+ if receipt.created:
115
+ self.cache.delete_entity(entity.entity_id)
116
+
117
+ # Touched set (Containment): parents whose `children_ids` projection
118
+ # this write changed. Deleted from cache - never version-bumped, so
119
+ # no parent row write and no version collision with a concurrent
120
+ # sibling create - then republished with their fresh projection.
121
+ touched_parent_ids = receipt.touched_parent_ids
122
+ if touched_parent_ids:
123
+ self.cache.delete_entities(list(touched_parent_ids))
124
+
125
+ # A reparent rewrites the subtree's `ancestor_ids` without bumping any
126
+ # descendant's version, so a cached payload would keep serving the
127
+ # pre-move ancestry forever. Invalidate, but do not republish: a move
128
+ # is not a write to the things being carried.
129
+ if receipt.moved_descendant_ids:
130
+ self.cache.delete_entities(list(receipt.moved_descendant_ids))
131
+
132
+ change = None
133
+ try:
134
+ change = await self.access_adapter.entity_saved(entity, receipt.previous)
135
+ except Exception:
136
+ logger.exception("AccessPort.entity_saved hook failed for entity %s", entity.entity_id)
137
+ try:
138
+ await self.scheduler.entity_saved(entity, receipt.previous)
139
+ except Exception:
140
+ logger.exception("Scheduler.entity_saved hook failed for entity %s", entity.entity_id)
141
+
142
+ broadcaster = self.broadcaster
143
+ await broadcaster.publish_save(entity)
144
+ await self._publish_reference_changes(entity, receipt.previous)
145
+ for touched_parent_id in touched_parent_ids:
146
+ touched_parent = await self.load_from_db(touched_parent_id)
147
+ if touched_parent is not None:
148
+ await broadcaster.publish_save(touched_parent)
149
+ for access_change in (change if isinstance(change, list) else ([change] if change else [])):
150
+ await broadcaster.publish_access_change(access_change)
151
+
152
+ logger.debug("Entity %s saved and broadcast", entity.entity_id)
153
+ return entity
154
+
155
+ async def _publish_reference_changes(self, entity, previous) -> None:
156
+ current = set(entity.reference_ids)
157
+ before = set(previous.reference_ids if previous is not None else ())
158
+ await self.broadcaster.publish_reference_changes(
159
+ entity, sorted(current - before), sorted(before - current),
160
+ )
161
+
162
+ async def delete_entity_tree(self, root_id: str, principal: Principal,
163
+ precondition: Optional[Precondition] = None) -> list[str]:
164
+ """The TDD's deletion chokepoint: authorize once against the root,
165
+ then delete the whole containment closure with no per-descendant
166
+ checks ("grants on nothing govern nothing" - a descendant's own
167
+ grants do not protect it once its containing scope is gone).
168
+ """
169
+ principal_entity_id = principal.principal_entity_id
170
+ strategy_cls = current_strategy()
171
+ if strategy_cls is None:
172
+ raise Forbidden(f"No strategy context for deletion of entity {root_id}")
173
+
174
+ root = await self.repository.load(root_id)
175
+ if root is None:
176
+ raise NotFound(f"Entity with ID {root_id} not found")
177
+
178
+ if strategy_cls is not KERNEL_INTERNAL:
179
+ if self.registry.strategies.is_read_only(strategy_cls):
180
+ raise Forbidden(
181
+ f"Strategy {strategy_cls.__name__} is declared read_only_strategy=True "
182
+ f"and may not delete entity {root_id}"
183
+ )
184
+ entity_type = self.registry.entities.get_entity_class(root.entity_type_id)
185
+ if entity_type is not None:
186
+ self.registry.policy.require_listed(entity_type, strategy_cls, 'delete')
187
+ perm = self.registry.policy.delete_permission(entity_type)
188
+ if not await self.access_adapter.allows(principal, perm, root_id):
189
+ raise Forbidden(f"User {principal_entity_id} does not have {perm} on entity {root_id}")
190
+
191
+ delete_ids = {str(root_id)} | await self.repository.descendant_ids(root_id)
192
+ subtree_roots = [root] + await self._add_dependents(delete_ids)
193
+ if strategy_cls is not KERNEL_INTERNAL:
194
+ await self.access_adapter.check_delete(delete_ids)
195
+
196
+ # Parents outside the deletion whose `children_ids` projection loses
197
+ # a subtree - touched-set cache invalidation and republish, same as
198
+ # an ordinary save (see save_entity).
199
+ external_parent_ids = {
200
+ e.parent_id for e in subtree_roots if e.parent_id and e.parent_id not in delete_ids
201
+ }
202
+ self.cache.delete_entities(list(external_parent_ids))
203
+
204
+ deleted = await self.delete_entities(list(delete_ids), principal=principal, precondition=precondition)
205
+
206
+ for parent_id in external_parent_ids:
207
+ touched_parent = await self.load_from_db(parent_id)
208
+ if touched_parent is not None:
209
+ await self.broadcaster.publish_save(touched_parent)
210
+
211
+ return deleted
212
+
213
+ def _dependent_fields(self) -> list[tuple[frozenset, str]]:
214
+ """`(type_ids, field)` per class declaring `dependent_on`, each with
215
+ the registered subclasses that inherit the declaration."""
216
+ by_declaring: dict[tuple[type, str], set[str]] = {}
217
+ for type_id, entity_cls in self.registry.entities.get_all_entities().items():
218
+ declaring = next((c for c in entity_cls.__mro__ if 'dependent_on' in vars(c)), None)
219
+ for field in entity_cls.dependent_on:
220
+ by_declaring.setdefault((declaring, field), set()).add(type_id)
221
+ return [(frozenset(type_ids), field) for (_, field), type_ids in by_declaring.items()]
222
+
223
+ async def _add_dependents(self, delete_ids: set) -> list:
224
+ """Grow `delete_ids` in place with every dependent of an id in it,
225
+ and their containment closures, in rounds until one adds nothing.
226
+ Returns the dependents found, each the root of an added subtree."""
227
+ fields = self._dependent_fields()
228
+ frontier = set(delete_ids)
229
+ roots = []
230
+ while frontier and fields:
231
+ hits = set()
232
+ for type_ids, field in fields:
233
+ hits |= await self.repository.dependent_ids(type_ids, field, frontier)
234
+ hits -= delete_ids
235
+ added = set(hits)
236
+ for hit in hits:
237
+ added |= await self.repository.descendant_ids(hit)
238
+ added -= delete_ids
239
+ roots += [e for e in (await self.repository.load_many(hits)).values() if e.entity_id in added]
240
+ delete_ids |= added
241
+ frontier = added
242
+ return roots
243
+
244
+ async def delete_entities(self, entity_ids: list[str], principal: Principal,
245
+ precondition: Optional[Precondition] = None) -> list[str]:
246
+ """Remove multiple entities from cache/DB and broadcast deletions in batches.
247
+
248
+ Internal path: authorization for a deletion happens once, at
249
+ ``delete_entity_tree``'s root check, never per row here
250
+ (`AUTHORIZATION_TECHNICAL_TDD.md`, cascade).
251
+ """
252
+ unique_entity_ids = []
253
+ seen_ids = set()
254
+ for entity_id in entity_ids:
255
+ entity_id = str(entity_id)
256
+ if not entity_id or entity_id in seen_ids:
257
+ continue
258
+ seen_ids.add(entity_id)
259
+ unique_entity_ids.append(entity_id)
260
+
261
+ if not unique_entity_ids:
262
+ return []
263
+
264
+ logger.debug("Clearing entities from cache: %s", unique_entity_ids)
265
+
266
+ adapter = self.access_adapter
267
+ delete_plan = await adapter.prepare_delete(unique_entity_ids)
268
+
269
+ self.cache.delete_entities(unique_entity_ids)
270
+
271
+ receipt = await self.repository.delete_many(unique_entity_ids, precondition)
272
+ existing_entity_ids = receipt.entity_ids
273
+ if existing_entity_ids:
274
+ logger.debug("Deleted entities from storage: %s", existing_entity_ids)
275
+
276
+ broadcaster = self.broadcaster
277
+
278
+ # Tombstones go out before any access-change fallout below: revoking
279
+ # a deleted scope's own grants would otherwise drop the grantee's
280
+ # channel membership before the scope's own tombstone reached them.
281
+ for deleted_entity in receipt.entities:
282
+ await broadcaster.publish_delete(deleted_entity)
283
+
284
+ try:
285
+ changes = await adapter.entities_deleted(delete_plan)
286
+ except Exception:
287
+ logger.exception("AccessPort.entities_deleted hook failed for entities %s", unique_entity_ids)
288
+ changes = []
289
+ for access_change in changes:
290
+ await broadcaster.publish_access_change(access_change)
291
+
292
+ if existing_entity_ids:
293
+ try:
294
+ await self.scheduler.entities_deleted(list(existing_entity_ids))
295
+ except Exception:
296
+ logger.exception("Scheduler.entities_deleted hook failed")
297
+
298
+ return existing_entity_ids
299
+
300
+ async def entity_exists_in_db(self, entity_id):
301
+ """Check if entity exists in storage"""
302
+ return bool(await self.repository.versions([entity_id]))
303
+
304
+ def load_from_cache(self, entity_id):
305
+ """Load an entity from cache"""
306
+ return self.cache.get_entity(entity_id)
307
+
308
+ def load_entities_from_cache(self, entity_ids):
309
+ """Load multiple entities from cache"""
310
+ return self.cache.get_entities(entity_ids)
311
+
312
+ async def load_from_db(self, entity_id):
313
+ """Load an entity from storage"""
314
+ return await self.repository.load(entity_id)
315
+
316
+
317
+ async def get_entities(self, entity_ids: list, principal: Principal) -> dict:
318
+ """Bulk-fetch entities by ID. Returns {entity_id: entity} for permitted entities.
319
+
320
+ Uses a single Redis MGET for cache hits and a grouped IN-query for DB misses.
321
+ Authorization always comes from the AccessPort against persisted state
322
+ (never from the cached payload's permissions), via a single batched
323
+ read predicate regardless of cache hit/miss mix, not N.
324
+ Identifiers minted elsewhere are partitioned off first: the
325
+ repository is never asked for one, and the local AccessPort never
326
+ decides about one.
327
+ """
328
+ if not entity_ids:
329
+ return {}
330
+
331
+ requested = list(dict.fromkeys(str(eid) for eid in entity_ids))
332
+ remote_ids = [eid for eid in requested if not self._is_local(eid)]
333
+ unique_ids = [eid for eid in requested if eid not in set(remote_ids)]
334
+ remote = await self.gateway.get_entities(remote_ids, principal) if remote_ids else {}
335
+ if not unique_ids:
336
+ return remote
337
+
338
+ # 1. Bulk cache lookup (single Redis MGET), one batched version query,
339
+ # and one batched readability decision.
340
+ cached = self.cache.get_entities(unique_ids)
341
+ versions = await self.repository.versions(unique_ids)
342
+ readable_ids = await self.repository.list_ids(AllOf((
343
+ InValues('entity_id', set(unique_ids)),
344
+ await self._read_predicate(principal),
345
+ )))
346
+
347
+ # 2. A cached payload is only usable if its version still matches the
348
+ # DB - otherwise it predates a write and must be reloaded.
349
+ miss_ids = [
350
+ eid for eid in unique_ids
351
+ if eid in versions and (
352
+ eid not in cached or cached[eid].version != versions[eid]
353
+ )
354
+ ]
355
+
356
+ db_entities = {}
357
+ if miss_ids:
358
+ db_entities = await self.load_entities_from_db(miss_ids)
359
+ if db_entities:
360
+ self.cache.set_entities(db_entities)
361
+
362
+ result = {}
363
+ for entity_id in unique_ids:
364
+ if entity_id not in versions:
365
+ result[entity_id] = Tombstone(entity_id=entity_id, cause='missing')
366
+ continue
367
+
368
+ entity = db_entities.get(entity_id) if entity_id in miss_ids else cached.get(entity_id)
369
+ if entity is None:
370
+ continue
371
+
372
+ if entity_id in readable_ids:
373
+ result[entity_id] = entity
374
+ else:
375
+ # Entity exists but the requester has no read access → tombstone.
376
+ # The client uses this to render a ghost node rather than
377
+ # treating the slot as "still loading".
378
+ result[entity_id] = Tombstone(entity_id=entity_id, cause='forbidden')
379
+
380
+ result.update(remote)
381
+ return result
382
+
383
+ async def list_entities(
384
+ self, principal: Principal, entity_filter: EntityFilter,
385
+ cursor: str = None, limit: int = 25,
386
+ ) -> EntityPage[Entity]:
387
+ """The general, enforced entity listing read: type/parent/`where`-
388
+ filtered, keyset-paginated on entity_id, and authorized via
389
+ `_read_predicate` rather than a per-candidate `allows()`
390
+ loop. Backs the access-subject picker and any future type browser.
391
+
392
+ `entity_filter.where`, if set, is conjoined with the access
393
+ predicate the same way type/parent are - never applied as a
394
+ separate post-filter. The criteria and the access predicate go to
395
+ storage as one statement, so filtering always happens before the
396
+ limit - a page is never narrowed in Python.
397
+
398
+ `entity_filter.granted_to_me` narrows to the caller's granted
399
+ resources (no `PUBLIC` grants), conjoined the same way.
400
+ """
401
+ predicates = [await self._read_predicate(principal)]
402
+ if entity_filter.granted_to_me:
403
+ granted = await self.access_adapter.granted_resources(principal, include_public=False)
404
+ predicates.append(InValues('entity_id', granted))
405
+ entity_filter = replace(entity_filter, granted_to_me=False)
406
+ predicate = AllOf((Predicate.from_filter(entity_filter), *predicates))
407
+ return await self.repository.list_entities(
408
+ EntityQuery(predicate, PageRequest(limit=limit, cursor=cursor))
409
+ )
410
+
411
+ async def referrers(
412
+ self, target_id: str, principal: Principal, where: Optional[Predicate] = None,
413
+ cursor: Optional[str] = None, limit: int = 25,
414
+ ) -> EntityPage[Entity]:
415
+ """The entities the caller can read that hold a reference to
416
+ `target_id`, narrowed by `where`. The reverse-index match, `where`
417
+ and the access predicate go to storage as one statement - the target
418
+ itself is never read."""
419
+ predicate = await self._read_predicate(principal)
420
+ if where is not None:
421
+ predicate = AllOf((where, predicate))
422
+ return await self.repository.referrers(
423
+ str(target_id), predicate, PageRequest(limit=limit, cursor=cursor),
424
+ )
425
+
426
+ async def load_entities_from_db(self, entity_ids: list) -> dict:
427
+ """Bulk-load entities from storage. Returns {entity_id: entity}."""
428
+ return await self.repository.load_many(entity_ids)
429
+
430
+ async def find_entities(self, predicate: Predicate) -> dict:
431
+ """Unauthorized entity lookup for kernel-internal callers (the grant
432
+ strategies, which are already gated on ManageAccess by the executor).
433
+ Never reachable from a transport."""
434
+ return await self.repository.load_many(await self.repository.list_ids(predicate))
435
+
436
+ async def _check_persistence_authorization(self, entity, existing, principal: Principal) -> None:
437
+ """The TDD's persistence chokepoint: governed by whichever strategy
438
+ is running this save (never by the entity's own claimed state, which
439
+ closes the laundering hole - see docs/AUTHORIZATION_TECHNICAL_TDD.md,
440
+ Enforcement). New entities are checked against the *persisted*
441
+ parent, never the in-memory object being created.
442
+ """
443
+ strategy_cls = current_strategy()
444
+ if strategy_cls is None:
445
+ raise Forbidden(
446
+ f"No strategy context for save of entity {entity.entity_id} - writes must run "
447
+ "through a strategy or a documented kernel-internal context"
448
+ )
449
+ if strategy_cls is KERNEL_INTERNAL:
450
+ return
451
+ if principal is None:
452
+ raise Forbidden(f"Save of entity {entity.entity_id} has no acting principal")
453
+
454
+ entity_type = type(entity)
455
+ policy = self.registry.policy
456
+ if existing is None and not policy.is_creatable(entity_type):
457
+ raise Forbidden(f"{entity_type.__name__} is created only by kernel code")
458
+
459
+ # Refused outright, not perm-checked: required_permission()'s read-only
460
+ # fallback is the type's read permission, held since invocation.
461
+ if self.registry.strategies.is_read_only(strategy_cls):
462
+ raise Forbidden(
463
+ f"Strategy {strategy_cls.__name__} is declared read_only_strategy=True "
464
+ f"and may not persist entity {entity.entity_id}"
465
+ )
466
+
467
+ policy.require_listed(entity_type, strategy_cls, 'write')
468
+
469
+ adapter = self.access_adapter
470
+ for field, field_perm in policy.deployment_fields(entity_type).items():
471
+ value = getattr(entity, field, None)
472
+ if value is not None and (existing is None or getattr(existing, field, None) != value):
473
+ if not await adapter.allows(principal, field_perm, self.deployment_entity_id):
474
+ raise Forbidden(
475
+ f"User {principal.principal_entity_id} does not have {field_perm} on the "
476
+ f"deployment to set {field} of {entity_type.__name__}"
477
+ )
478
+
479
+ if existing is None:
480
+ await self._check_create(entity, principal)
481
+ return
482
+
483
+ perm = policy.required_permission(entity_type, strategy_cls)
484
+ if not await adapter.allows(principal, perm, entity.entity_id):
485
+ raise Forbidden(
486
+ f"User {principal.principal_entity_id} does not have {perm} on entity {entity.entity_id}"
487
+ )
488
+ # A move leaves the old parent and enters the new one exactly as if
489
+ # the entity were created there.
490
+ if entity.parent_id != existing.parent_id:
491
+ if existing.parent_id and not await adapter.allows(principal, perm, existing.parent_id):
492
+ raise Forbidden(
493
+ f"User {principal.principal_entity_id} does not have {perm} on parent "
494
+ f"{existing.parent_id} of entity {entity.entity_id}"
495
+ )
496
+ await self._check_create(entity, principal)
497
+ await adapter.check_save(entity, existing)
498
+
499
+ async def _check_create(self, entity, principal: Principal) -> None:
500
+ """The creation rule: the type's create permission on the parent, or
501
+ on the deployment when there is no parent."""
502
+ perm = self.registry.policy.create_permission(type(entity))
503
+ target = entity.parent_id or self.deployment_entity_id
504
+ if not await self.access_adapter.allows(principal, perm, target):
505
+ where = f"parent {entity.parent_id}" if entity.parent_id else "the deployment"
506
+ raise Forbidden(
507
+ f"User {principal.principal_entity_id} does not have {perm} on {where} "
508
+ f"to create {type(entity).__name__}"
509
+ )
510
+
511
+ async def _check_can_contain(self, entity) -> None:
512
+ """Structural, so it holds for kernel-internal writes too."""
513
+ refusing = self.registry.policy.parent_type_ids_refusing(type(entity))
514
+ if not refusing:
515
+ return
516
+ parent_ids = await self.repository.list_ids(AllOf((
517
+ Equal('entity_id', entity.parent_id),
518
+ InValues('entity_type_id', refusing),
519
+ )))
520
+ if parent_ids:
521
+ parent = await self.repository.load(entity.parent_id)
522
+ parent_type = self.registry.entities.get_entity_class(parent.entity_type_id)
523
+ raise InvalidRequest(
524
+ f"{parent_type.__name__ if parent_type else parent.entity_type_id} "
525
+ f"cannot contain {type(entity).__name__}"
526
+ )
527
+
528
+ async def _check_contained_by(self, entity) -> None:
529
+ """Structural, so it holds for kernel-internal writes too."""
530
+ allowed = self.registry.policy.contained_by(type(entity))
531
+ if allowed is None:
532
+ return
533
+ names = ' or '.join(cls.__name__ for cls in allowed)
534
+ if not entity.parent_id:
535
+ raise InvalidRequest(
536
+ f"{type(entity).__name__} cannot be top-level; it must be placed inside {names}"
537
+ )
538
+ parent = await self.repository.load(entity.parent_id)
539
+ if parent is None:
540
+ raise InvalidRequest(f"Parent {entity.parent_id} of {type(entity).__name__} does not exist")
541
+ parent_type = self.registry.entities.get_entity_class(parent.entity_type_id)
542
+ if parent_type is None or not issubclass(parent_type, allowed):
543
+ raise InvalidRequest(
544
+ f"{type(entity).__name__} must be placed inside {names}, "
545
+ f"not {parent_type.__name__ if parent_type else parent.entity_type_id}"
546
+ )
547
+
548
+ async def save_to_db(self, entity, principal: Principal, precondition: Optional[Precondition] = None,
549
+ existing=NOT_LOADED):
550
+ """Persist an entity, with the permission check the TDD puts at this
551
+ chokepoint, and return the repository's `SaveReceipt`."""
552
+ try:
553
+ if existing is NOT_LOADED or (existing is not None and existing.version != entity.version):
554
+ existing = await self.repository.load(entity.entity_id)
555
+
556
+ # Access is derived from the containment chain, and a deployment
557
+ # computes that chain only over entities it owns - so containment
558
+ # stops at the deployment boundary, ahead of any access decision.
559
+ if entity.parent_id and backend_of(entity.parent_id) != self.backend_id:
560
+ raise InvalidRequest(
561
+ f"parent_id {entity.parent_id} is not local; "
562
+ "containment does not cross deployments"
563
+ )
564
+
565
+ if existing is None or existing.parent_id != entity.parent_id:
566
+ if entity.parent_id:
567
+ await self._check_can_contain(entity)
568
+ await self._check_contained_by(entity)
569
+
570
+ if existing is not None:
571
+ for field in type(entity).write_once_fields:
572
+ if getattr(existing, field) is not None and getattr(entity, field) != getattr(existing, field):
573
+ raise InvalidRequest(f"{field} of {entity.entity_id} cannot change once set")
574
+
575
+ # Enforcement (the TDD's persistence chokepoint): governed by
576
+ # the strategy running this save, never by the in-memory entity.
577
+ await self._check_persistence_authorization(entity, existing, principal)
578
+
579
+ # Owner is immutable once set, and a new entity always belongs to
580
+ # the acting principal - caller-supplied owner state is never
581
+ # trusted either way.
582
+ if existing is not None:
583
+ entity.owner = existing.owner
584
+ elif type(entity).ownerless or principal is None:
585
+ entity.owner = None
586
+ else:
587
+ entity.owner = principal.principal_entity_id
588
+
589
+ receipt = await self.repository.save(entity, precondition, previous=existing)
590
+ except (ConcurrentModificationError, PreconditionFailed):
591
+ raise
592
+ except Exception as e:
593
+ logger.error(f"Error saving entity {entity.entity_id} to storage: {e}")
594
+ raise
595
+
596
+ return receipt
597
+
598
+ def clear_entities(self, entity_ids):
599
+ """Remove multiple entities from cache"""
600
+ self.cache.delete_entities(entity_ids)
601
+
602
+ def clear_all_entities(self):
603
+ """Remove all entities from cache"""
604
+ self.cache.clear_all_entities()
605
+
606
+
607
+ async def recurse_children(self, entity_id, principal: Principal, entity_type_id=None, visited=None):
608
+ """
609
+ Recursively get all children of a specific type until no children are left.
610
+
611
+ Traverses breadth-first, fetching each level in a single batched
612
+ ``get_entities`` call rather than one ``get_entity`` per node, so the
613
+ number of queries is bounded by tree depth instead of node count.
614
+
615
+ Args:
616
+ entity_id: The ID of the entity to start from
617
+ principal: Caller for permission checks. Required — there
618
+ is no unfiltered traversal mode; a broad-access caller needs a
619
+ service principal whose ACL grants say so, not a bypass argument.
620
+ entity_type_id: Optional entity type ID to filter by (e.g., 'Node')
621
+ visited: Set of visited entity IDs to prevent infinite loops
622
+
623
+ Returns:
624
+ List of entities in the graph
625
+ """
626
+ if visited is None:
627
+ visited = set()
628
+
629
+ if entity_id in visited:
630
+ logger.warning(f"Circular reference detected: entity {entity_id} already visited")
631
+ return []
632
+
633
+ entities = []
634
+ frontier = [entity_id]
635
+
636
+ while frontier:
637
+ batch_ids = []
638
+ for eid in frontier:
639
+ if eid in visited:
640
+ continue
641
+ visited.add(eid)
642
+ batch_ids.append(eid)
643
+
644
+ if not batch_ids:
645
+ break
646
+
647
+ fetched = await self.get_entities(batch_ids, principal)
648
+
649
+ next_frontier = []
650
+ for eid in batch_ids:
651
+ node = fetched.get(eid)
652
+ if node is None or isinstance(node, Tombstone):
653
+ # Missing entity or forbidden tombstone - skip, matching the
654
+ # previous behavior of catching get_entity's ValueError/PermissionError.
655
+ continue
656
+ if entity_type_id is None or node.get_entity_type_id() == entity_type_id:
657
+ entities.append(node)
658
+ next_frontier.extend(node.children_ids or [])
659
+
660
+ frontier = next_frontier
661
+
662
+ return entities
663
+
664
+ async def get_parent_ids_by_type(self, entity_id, entity_type_id: str, principal: Principal):
665
+ """
666
+ Get parent IDs of a specific type from an entity.
667
+
668
+ Args:
669
+ entity_id: The entity to get parents from
670
+ entity_type_id: The entity type ID to filter by (e.g., 'Node')
671
+ principal: Caller for permission checks
672
+
673
+ Returns:
674
+ List of parent entity IDs matching the type
675
+ """
676
+ entity = await self.get_entity(entity_id, principal)
677
+ parent_ids = list(entity.parent_ids)
678
+ if not parent_ids:
679
+ return []
680
+
681
+ parents = await self.get_entities(parent_ids, principal)
682
+ return [
683
+ pid for pid in parent_ids
684
+ if not isinstance(parents.get(pid), Tombstone) and parents.get(pid) is not None
685
+ and parents[pid].get_entity_type_id() == entity_type_id
686
+ ]
687
+
688
+ async def get_children_ids_by_type(self, entity_id, entity_type_id: str, principal: Principal):
689
+ """
690
+ Get children IDs of a specific type from an entity.
691
+
692
+ Args:
693
+ entity_id: The entity to get children from
694
+ entity_type_id: The entity type ID to filter by (e.g., 'Node')
695
+ principal: Caller for permission checks
696
+
697
+ Returns:
698
+ List of child entity IDs matching the type
699
+ """
700
+ entity = await self.get_entity(entity_id, principal)
701
+ child_ids = list(entity.children_ids)
702
+ if not child_ids:
703
+ return []
704
+
705
+ children = await self.get_entities(child_ids, principal)
706
+ return [
707
+ cid for cid in child_ids
708
+ if not isinstance(children.get(cid), Tombstone) and children.get(cid) is not None
709
+ and children[cid].get_entity_type_id() == entity_type_id
710
+ ]