---
id: 10089
title: '[docs] Document SQLite FK constraints on Graph Database.addEdge JSDoc'
state: CLOSED
labels:
  - documentation
  - enhancement
  - ai
assignees:
  - neo-gpt
createdAt: '2026-04-19T10:32:20Z'
updatedAt: '2026-06-02T09:24:27Z'
githubUrl: 'https://github.com/neomjs/neo/issues/10089'
author: tobiu
commentsCount: 1
parentIssue: null
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-06-02T09:24:27Z'
---
# [docs] Document SQLite FK constraints on Graph Database.addEdge JSDoc

## Context

During PR [#10084](https://github.com/neomjs/neo/pull/10084) implementation, the first test run failed with `SqliteError: FOREIGN KEY constraint failed` when `ConceptIngestor` tried to insert edges whose `target` strings had no matching graph node. The FK constraint is enforced in `ai/graph/storage/SQLite.mjs` but not surfaced in the public `Database.mjs#addEdge` API docs. Future implementers will hit the same error unless they proactively read the storage layer's schema.

This is a small but real discoverability gap. The fix is minutes of work; the benefit is durable across every future agent or human who touches graph ingestion.

## The Fix

Add to `ai/graph/Database.mjs`:

1. `addEdge(edge)` — JSDoc `@throws {SqliteError}` tag with explicit note: *"if `edge.target` is not already present as a node ID. The underlying SQLite schema enforces `FOREIGN KEY(target) REFERENCES nodes(id)`. Caller is responsible for ensuring target nodes exist before edge insertion."*
2. (Optional) same note on the class-level JSDoc `@summary` so it's visible at a glance

Mirror pattern for `addNode` if similar constraints exist (likely no — nodes are the parent table).

## Acceptance Criteria

- [ ] `Database.mjs#addEdge` JSDoc includes `@throws {SqliteError}` with FK constraint explanation
- [ ] Pattern follows existing Anchor-and-Echo JSDoc discipline in the file
- [ ] No code changes — documentation only
- [ ] Semantic reference: future `ask_knowledge_base("can I add an edge to a non-existent node?")` query returns the correct guidance after sync

## Origin Session ID

`62d6f155-e57f-4279-9b59-36c9e4ecbc5e` — surfaced in PR [#10084](https://github.com/neomjs/neo/pull/10084) self-review `[TOOLING_GAP]` tag

## Related

- Evidence of the friction: PR [#10084](https://github.com/neomjs/neo/pull/10084) — the FK miss cost ~10 min of iteration + one test failure before the schema reality was surfaced
- `ConceptIngestor.ensureEdgeTargetsExist` — the workaround pattern that emerged, now documented inline there


## Timeline

- 2026-04-19T10:32:21Z @tobiu added the `documentation` label
- 2026-04-19T10:32:21Z @tobiu added the `ai` label
- 2026-04-19T10:33:36Z @tobiu cross-referenced by #10030
- 2026-06-02T01:40:40Z @neo-gpt added the `enhancement` label
### @neo-gpt - 2026-06-02T01:40:47Z

**Input from GPT-5 (Codex Desktop):**

> ● Triaged per `ticket-triage` skill. Applied: `enhancement` (existing labels retained: `documentation`, `ai`). Stage retrospective passed.
> 
> Intake summary: premise verified against live issue body, Knowledge Base, and current source. `ai/graph/storage/SQLite.mjs` enables SQLite FKs and declares `Edges.source` / `Edges.target` as `FOREIGN KEY(... ) REFERENCES Nodes(id) ON DELETE CASCADE`; `ai/graph/Database.mjs#addEdge` is the public API surface that currently does not echo that constraint. Scope remains documentation-only.

- 2026-06-02T01:40:53Z @neo-gpt assigned to @neo-gpt
- 2026-06-02T01:45:24Z @neo-gpt cross-referenced by PR #12338
- 2026-06-02T07:52:57Z @neo-gpt referenced in commit `b0f894d` - "docs(ai): preserve graph ADR anchor (#10089)"
- 2026-06-02T09:24:28Z @tobiu referenced in commit `904f30a` - "docs(ai): document graph edge FK constraint (#10089) (#12338)

* docs(ai): document graph edge FK constraint (#10089)

* docs(ai): preserve graph ADR anchor (#10089)

---------

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-06-02T09:24:28Z @tobiu closed this issue

