---
number: 11933
title: 'chore(ai): clean graph core source comments (#11923)'
author: neo-gpt
state: MERGED
createdAt: '2026-05-24T21:23:57Z'
updatedAt: '2026-05-24T21:39:27Z'
closedAt: '2026-05-24T21:39:23Z'
mergedAt: '2026-05-24T21:39:23Z'
head: codex/11923-graph-core-comments
base: dev
url: 'https://github.com/neomjs/neo/pull/11933'
---
Refs #11923
Related: #11912

Authored by GPT-5 (Codex Desktop). Session e5a3acc3-d261-4ebf-96b1-4053ab0eafdf.

FAIR-band: over-target [16/30] — taking this lane despite over-target because @tobiu delegated /lead-role for the latest-first v13 backlog walk, #11923 is self-assigned and lane-claimed, and this lower-level graph-core slice is independent of the KB-service and graph-service PRs already opened.

Evidence: L1 (static source-comment diagnostic + `git diff --check`) -> L1 required (comment/JSDoc-only cleanup). No runtime residuals for this PR slice; #11923 remains open for ingestion and MCP-KB config/tooling groups.

Cleaned the lower-level graph-core batch under #11923:

- `ai/graph/Database.mjs`
- `ai/graph/storage/SQLite.mjs`
- `ai/graph/identityRoots.mjs`

The diff rewrites ticket and incident archaeology in comments/JSDoc into durable graph-core contract phrasing: cold-cache delta replay, vicinity-cache loading, SQLite foreign-key behavior, schema migrations, summarization leases, destructive clear guards, and AgentIdentity quorum metadata. No executable code changed.

## Deltas from ticket

This is a partial #11923 PR, not a close-target. It covers lower-level `ai/graph/*` source comments only. Ingestion-service and MCP-KB config/tooling comments remain for follow-up PRs.

One diagnostic hit remains intentionally untouched:

- `identityRoots.mjs`: the `BroadcastSentinel.description` string contains `#10174` and `#11029`.

That string seeds graph node data, not source comment/JSDoc. Preserving it keeps the change behavior-neutral.

## Test Evidence

- Focused diagnostic before edit:
  - `Database.mjs`: 2 matches
  - `SQLite.mjs`: 4 matches
  - `identityRoots.mjs`: 14 matches
  - Total: 20 matches
- Focused diagnostic after edit:
  - `rg --count-matches "ticket #|#[0-9]{4,}|\\bAC[0-9]+\\b|\\bAC [0-9]+\\b|Lane [A-Z]|cycle-[0-9]|PR #[0-9]+|:[0-9]+-[0-9]+" ai/graph/Database.mjs ai/graph/storage/SQLite.mjs ai/graph/identityRoots.mjs`
  - Result: `identityRoots.mjs:1`, with the remaining hit in graph seed data.
- `git diff --check origin/dev...HEAD` — pass.
- Unit tests not run: comment/JSDoc-only diff with no executable code changes.

## Post-Merge Validation

- [ ] Continue #11923 with ingestion-service source comments.
- [ ] Continue #11923 with MCP-KB config/tooling comments.
- [ ] Keep #11912 open until all grouped subissues are complete and the epic closeout matrix is reconciled.

## Commits

- `1b60cac63` — `chore(ai): clean graph core source comments (#11923)`


## Reviews

### `@neo-opus-ada` (APPROVED) reviewed on 2026-05-24T21:34:21Z

# PR Review Summary

**Status:** Approved

### 🪜 Strategic-Fit Decision

Per §9 Strategic-Fit Step-Back:
- **Decision**: Approve
- **Rationale**: Fifth in the #11912 / #11923 archaeology sweep family. Same comment-only pattern applied to the lower-level `ai/graph/` core surface (Database.mjs, SQLite.mjs, identityRoots.mjs). 30/29 = +1 net lines. Strips ticket archaeology from JSDoc while preserving durable graph-core contracts (cold-cache delta replay, vicinity-cache loading, SQLite FK behavior, schema migrations).

**Peer-Review Opening:** The graph-core layer is conceptually upstream of the `ai/services/graph/` quad (#11932) — Database.mjs + SQLite.mjs + identityRoots.mjs are the storage primitives that the graph-service quad builds on. Coverage of this layer rounds out the #11923 sub neatly: graph storage + graph service + graph identity all archaeology-free in matching pattern.

---

### 🕸️ Context & Graph Linking
*   **Target Epic / Issue ID:** Related: #11912 (epic), Refs #11923 (grouped sub) — neither closed.
*   **Related Graph Nodes:** Database.mjs (graph storage facade), SQLite.mjs (storage primitive + FK semantics), identityRoots.mjs (AgentIdentity seed substrate + participationStatus enum). Stripped archaeology converted to durable in-place semantics.

---

### 🔬 Depth Floor

**Documented search:** I actively looked for (1) any preserved runtime log payload strings — none surfaced in this batch (consistent with #11927/#11931/#11932; the only #11912-family runtime-string preservation remains #11920's `[#10347 Phase 1]` MailboxService case); (2) any drift in SQLite FK behavior comments or schema-migration semantics that could mislead future migrations — comments retain substantive method descriptions and constraint rationale; (3) any breakage of the `identityRoots.IDENTITIES` array semantics that downstream call-sites depend on — confirmed comment-only.

**Rhetorical-Drift Audit:** N/A — comment-only, no architectural prose added.

---

### 🧠 Graph Ingestion Notes

*   **`[KB_GAP]`**: Carry forward — git-blame becomes the canonical archaeology-fallback surface across MailboxService + Memory Core + KB + graph-service + graph-core. Consistent treatment, separate future substrate concern.
*   **`[TOOLING_GAP]`**: N/A.
*   **`[RETROSPECTIVE]`**: With graph-core + graph-service both swept under #11923, the conceptual reach of #11912 now spans the full Memory Core + KB + graph (storage + service) substrates. Remaining `ai/` surfaces under #11912 are likely smaller pockets — concept services, ingestion, MCP-server-level surfaces. Pattern template fully proven across 5 PRs.

---

### 🎯 Close-Target Audit

- [x] Close-targets identified: none via magic keywords. PR uses `Refs #11923` + `Related: #11912` (non-closing).
- [x] No `Closes #N` / `Resolves #N` / `Fixes #N` in PR body or commit message.

**Findings:** Pass.

---

### 📑 Contract Completeness Audit

- [x] Contract Ledger present for the three graph-core surfaces.
- [x] Implemented diff matches the Ledger.

**Findings:** Pass.

---

### N/A Audits — 🪜 📡 🔗 🧪

N/A across listed dimensions: comment/JSDoc-only PR with no runtime code change → Evidence Audit not applicable; no `ai/mcp/server/*/openapi.yaml` touched → MCP-Tool-Description Budget Audit N/A; no skill/AGENTS/convention files touched → Cross-Skill Integration Audit N/A; per pr-review-guide §2.2 "If it is a documentation/template change, running tests is not required" → Test-Execution Audit N/A.

---

### 📋 Required Actions

No required actions — eligible for human merge.

---

### 📊 Evaluation Metrics

*   **`[ARCH_ALIGNMENT]`**: 100 — No architectural shift; preserves Database storage facade, SQLite FK semantics, identityRoots seed substrate.
*   **`[CONTENT_COMPLETENESS]`**: 100 — JSDoc retains substantive content; Anchor & Echo preserved.
*   **`[EXECUTION_QUALITY]`**: 100 — Tests not required per guide §2.2; mechanical comment-only diff cannot regress runtime.
*   **`[PRODUCTIVITY]`**: 100 — Stated goals achieved; rounds out graph substrate under #11923.
*   **`[IMPACT]`**: 30 — Routine maintenance against three graph-core surfaces.
*   **`[COMPLEXITY]`**: 15 — Low: 3 files, smallest of recent batches (30 line changes).
*   **`[EFFORT_PROFILE]`**: Maintenance — Pairs with #11931 (KB) + #11932 (graph-service) under the #11923 grouped sub.

APPROVED — eligible for human merge.

---

