Align the canonical graph model and enforce document/edge integrity #11

New issue

Closed

opened 2026-07-30 04:06:17 +00:00 by lost-rob0t · 0 comments

lost-rob0t commented

2026-07-30 04:06:17 +00:00

(Migrated from github.com)

Problem

PR #3 introduces a Lisp graph model that is not aligned with the existing Quasar UI models.

The UI currently has graph-workspace records based on document membership, positions, viewport, layout, selection, and groups. It also contains a typed canonical graph-document model. The Lisp control plane adds a third representation: generic node and edge arrays.

Validation is currently too weak:

documents require only _id;
node documentId references are not checked against existing documents;
node deletion can leave incident edges;
document deletion can leave referencing graph nodes;
backend-generated stable IDs are not implemented;
object types and required StarIntel fields are not validated;
several errors use unrelated codes.

Found during review of PR #3.

Required changes

Decide and document one canonical durable graph model.
Prefer canonical StarIntel documents/relations plus named graph-view membership and committed presentation state, unless there is a concrete reason for a separate graph-document database.
Treat Cytoscape nodes/edges as projections rather than an additional authoritative intelligence store.
Define mappings between StarIntel documents, relation documents, graph membership, positions, and UI projections.
Validate required document fields and supported object types.
Validate node-to-document references.
Define deletion semantics for documents, nodes, and incident edges.
Generate backend IDs for new durable objects unless valid imported IDs are supplied.
Return authoritative created/updated objects in responses and events, not only IDs.
Use stable, accurate error codes for duplicate IDs, invalid types, missing graphs, and invalid references.

Acceptance criteria

One canonical graph/state contract is documented and used by Lisp and frontend adapters.
No successful mutation can create dangling document/node/edge references.
Deletion behavior is deterministic and tested.
Responses/events contain the authoritative object needed to reconcile optimistic UI state.
Existing graph lists, document membership, positions, groups, cross-dataset relations, and fullscreen behavior can be represented without parallel durable models.

Related PR: #3

## Problem PR #3 introduces a Lisp graph model that is not aligned with the existing Quasar UI models. The UI currently has graph-workspace records based on document membership, positions, viewport, layout, selection, and groups. It also contains a typed canonical graph-document model. The Lisp control plane adds a third representation: generic node and edge arrays. Validation is currently too weak: - documents require only `_id`; - node `documentId` references are not checked against existing documents; - node deletion can leave incident edges; - document deletion can leave referencing graph nodes; - backend-generated stable IDs are not implemented; - object types and required StarIntel fields are not validated; - several errors use unrelated codes. Found during review of PR #3. ## Required changes - Decide and document one canonical durable graph model. - Prefer canonical StarIntel documents/relations plus named graph-view membership and committed presentation state, unless there is a concrete reason for a separate graph-document database. - Treat Cytoscape nodes/edges as projections rather than an additional authoritative intelligence store. - Define mappings between StarIntel documents, relation documents, graph membership, positions, and UI projections. - Validate required document fields and supported object types. - Validate node-to-document references. - Define deletion semantics for documents, nodes, and incident edges. - Generate backend IDs for new durable objects unless valid imported IDs are supplied. - Return authoritative created/updated objects in responses and events, not only IDs. - Use stable, accurate error codes for duplicate IDs, invalid types, missing graphs, and invalid references. ## Acceptance criteria - One canonical graph/state contract is documented and used by Lisp and frontend adapters. - No successful mutation can create dangling document/node/edge references. - Deletion behavior is deterministic and tested. - Responses/events contain the authoritative object needed to reconcile optimistic UI state. - Existing graph lists, document membership, positions, groups, cross-dataset relations, and fullscreen behavior can be represented without parallel durable models. Related PR: #3