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