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