Note where the enhanced query drops references (#760)

projects/pathway-browser/src/app/model/graph/event/event.model.ts

@@ -15,6 +15,14 @@ import { GO_BiologicalProcess } from '../go-term/go-biological-process.model';
  * As /data/query/enhanced sends it, which leaves out what an event has none of:
  * of 15 sampled pathways one had authors, reviewers or a review status, and
  * three of 15 reactions (#344).
+ *
+ * Asked without `includeRef=true` (either version), a list such as
+ * `literatureReference` can hold bare dbIds where the object was written
+ * earlier in the answer, often in the parent pathway (`eventOf`) or a preceding
+ * or following event; the types here do not say so. Dropping them loses
+ * references, as production's browser does (#760). Ask with `includeRef=true`
+ * and read through JSOGDeserializer, which resolves its back-references
+ * (`@ref`) to the objects they name, as the details pages do.
  */
 export interface Event extends DatabaseObject, InDepth, HasFigure {
   stId: string;

tools/content-node/data-query-endpoints.ts

@@ -391,6 +391,17 @@ export const dataQueryEndpoints: Endpoint[] = [
      * serialiser in the request's view. The entity popup, the website's
      * content pages and the IDG panel read it.
      *
+     * Kept byte for byte as Java answers it, so it keeps a trap. Without
+     * `includeRef=true`, this answer and /enhanced/v2 alike write an object in
+     * full only once and later as its bare dbId; and an event's neighbours (its
+     * preceding and following events, and since graph-core bb5e0ca0, Aug 2025,
+     * its parent pathways, `eventOf`) come before its `literatureReference` and
+     * the lists after it. A reference a neighbour also cites is therefore a bare
+     * number in the event's list, and a reader that keeps only objects loses it,
+     * which is #760 on production. Ask with `includeRef=true`, which marks each
+     * object with `@id` and points back with `{"@ref": …}`, and read through the
+     * site's JSOGDeserializer, as the details pages do (with v2).
+     *
      * Its relationships go both ways unless QueryObjectController's
      * needsIncomingRelationship says not (needsIncoming). The id is read as
      * getIdentifier reads it (inDepthId).