Description
Edge CRUD and Bulk Management is the mutation surface for the universal Dots graph. It lets authorized callers create a validated relationship, create one only if it is absent, submit batches efficiently, and delete an edge through a lifecycle-aware path. Every operation is company-scoped and preserves the graph’s shared contracts rather than letting each product module write the polymorphic edge table directly.
The capability serves both interactive linking and high-volume platform producers. User-trust writes validate the requested verb and endpoint combination and report duplicates predictably. System importers receive a deliberately separate batch seam for trusted structural relationships, such as the thousands of file-to-symbol edges emitted during repo ingestion. Bulk insertion chunks values and uses conflict-safe persistence so retries return only genuinely inserted rows.
Selling Points
- Gives users and integrations one consistent way to connect knowledge across modules.
- Supports idempotent redraws without turning normal retries into duplicate failures.
- Batches large structural graphs instead of paying one database round trip per edge.
- Keeps authorization, validation, events, and row edge counts aligned with mutations.
- Preserves deletion auditability and emits graph lifecycle events for downstream consumers.
User Story
As an integration developer, I can submit a set of relationships discovered from an import and safely retry the request after a network interruption. Dots inserts only missing pairs, tells me what actually landed, and keeps the affected rows’ graph counts correct without custom reconciliation code.
Extension Surface
The rating is automatable because stable service and HTTP surfaces can be driven by clients and jobs. packages/api/src/routes/edges.ts exposes create, bulk-create, list, and delete routes, while packages/knowledge-graph/src/service.ts supplies injected authorization, event, and executor seams. Callers can automate operations, but they cannot replace validation or obtain the private system-trust path from a user route.
Capabilities & Limits
Capabilities include strict create with duplicate detection, conflict-tolerant create-if-absent, chunked bulk insertion, edge reads, and lifecycle-aware delete. Trusted platform writers can use a bounded system batch adapter. Limits are intentional: edge verbs and endpoint kinds must pass the governed contract, system-only relationships cannot be forged by normal callers, and direct table deletion is outside the supported surface because it would bypass events and maintenance.
Implementation Map
packages/knowledge-graph/src/service.tspackages/knowledge-graph/src/edges.tspackages/knowledge-graph/src/validate.tspackages/api/src/routes/edges.ts