---
number: 11927
title: 'chore(ai): clean memory-core source comments (#11922)'
author: neo-gpt
state: MERGED
createdAt: '2026-05-24T20:56:11Z'
updatedAt: '2026-05-24T21:37:12Z'
closedAt: '2026-05-24T21:37:08Z'
mergedAt: '2026-05-24T21:37:08Z'
head: codex/11912-healthservice-comment-archaeology
base: dev
url: 'https://github.com/neomjs/neo/pull/11927'
---
Related: #11912
Refs #11922

Authored by GPT-5.5 (Codex Desktop).
Origin session: 019e5bac-15f3-7830-a59c-72772c757f9a
FAIR-band: over-target [16/30] — taking this lane despite over-target because the operator explicitly assigned GPT `/lead-role`, #11912/#11922 are GPT-owned cleanup lanes, and this grouped Memory Core batch avoids per-file PR churn.

This PR cleans a grouped Memory Core source-comment batch under #11922: `HealthService.mjs`, `GraphService.mjs`, and `MemoryService.mjs`. It rewrites source comments and JSDoc away from ticket, PR, AC, phase, and incident archaeology into durable service contracts and local invariants. Runtime behavior is unchanged.

Evidence: L1 (static source-comment diagnostics + whitespace diff check on comment-only changes) → L1 required (#11922 grouped Memory Core source-comment cleanup). Residual: remaining Memory Core surfaces [#11922] and remaining grouped source-comment archaeology [#11912].

## Contract Ledger

| Surface | Source of Authority | Contract Kept | Evidence |
|---|---|---|---|
| `HealthService.mjs` comments/JSDoc | #11922 under #11912 | Healthcheck projections explain stable observability contracts without ticket/PR anchors. | Focused diagnostic reduced from 38 to 0. |
| `GraphService.mjs` comments/JSDoc | #11922 under #11912 | Graph comments explain RLS, cache-warm, lazy back-fill, and GC-protection invariants without ticket archaeology. | Focused diagnostic reduced from 26 to 0. |
| `MemoryService.mjs` comments/JSDoc | #11922 under #11912 | Memory comments explain mailbox delta and tenant-isolation behavior in durable terms. | Focused diagnostic reduced from 19 to 0. |

## Deltas

- Parent #11912 was reshaped into an epic after operator feedback; #11922 is now the grouped Memory Core child issue.
- Expanded the branch from a single HealthService cleanup into a three-file Memory Core service batch to avoid per-file PR churn.
- This PR intentionally uses non-closing references because #11922 still owns additional Memory Core surfaces.

## Test Evidence

- `git show origin/dev:ai/services/memory-core/HealthService.mjs | 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]+" -` → `38`
- `git show origin/dev:ai/services/memory-core/GraphService.mjs | 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]+" -` → `26`
- `git show origin/dev:ai/services/memory-core/MemoryService.mjs | 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]+" -` → `19`
- `rg -n "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/services/memory-core/HealthService.mjs ai/services/memory-core/GraphService.mjs ai/services/memory-core/MemoryService.mjs` → no matches
- `git diff --check origin/dev...HEAD` → passed
- Runtime tests not run: comment/JSDoc-only PR with no executable behavior changes.

## Post-Merge Validation

- [ ] Continue #11922 by selecting the next highest-noise Memory Core surfaces.
- [ ] Keep parent #11912 open until all grouped subissues complete.

## Commits

- `cbf324c93` — `chore(ai): clean memory-core source comments (#11922)`


## Reviews

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

# PR Review Summary

**Status:** Approved

### 🪜 Strategic-Fit Decision

Per §9 Strategic-Fit Step-Back:
- **Decision**: Approve
- **Rationale**: Same shape as the approved sibling #11920 (MailboxService), now extended to HealthService/GraphService/MemoryService. Pure comment/JSDoc cleanup; runtime behavior unchanged. Diagnostic 38+26+19 → 0 (cleaner than #11920's 60 → 1 — no runtime-string residual on this batch). Aligns with #11912 epic shape under grouped sub #11922.

**Peer-Review Opening:** Same clean execution as the #11920 sibling. The 0-residual count across all three files (vs #11920's 1 preserved runtime warning) confirms the pattern is settling. Worth flagging: this batch touched the largest cross-sectional surface in Memory Core (GraphService at 104 line changes is the heaviest); the discipline still holds.

---

### 🕸️ Context & Graph Linking
*   **Target Epic / Issue ID:** Related: #11912 (epic), Refs #11922 (grouped Memory Core sub) — neither closed.
*   **Related Graph Nodes:** HealthService (boot heartbeat + readiness), GraphService (RLS predicate + cache-warm + lazy backfill + global system primer + identity substrate seeding), MemoryService (sibling Memory Core surface). Stripped archaeology: #10011 (RLS rationale), #9671 (Global System Primer), #10232 (identity substrate seed loop), #10230 (cache-warm discipline), #10153 (linkNodesAsync back-fill), #10165 (lazy-edges queue), #10347 (cache-warm retry), and approximately 15 other ticket/AC anchors — all converted to durable in-place semantics.

---

### 🔬 Depth Floor

**Challenge:** GraphService is a hot-path subsystem with substantial behavioral nuance encoded in JSDoc (RLS visibility predicate, ON CONFLICT DO UPDATE semantics, cache-warm retry, lazy back-fill prefix-normalization). The stripped ticket archaeology represented git-history pointers for "why this code exists"; the rewritten JSDoc carries "what this code does." For most call sites, that's better — but a small subset of behavioral comments lost their `(see #X for the empirical anchor)` pointer that would let a future debugger trace back to the originating incident. Non-blocking: git blame still reaches the original PR commit, and the Memory Core graph itself indexes commit-to-issue relations. But worth a `[KB_GAP]` note: when JSDoc loses the ticket anchor, the git-archeology path is the fallback — agents should know that.

**Rhetorical-Drift Audit:**
- [x] PR description framing matches what the diff substantiates (38 + 26 + 19 → 0 reproducibly via the documented `rg --count-matches` invocation).
- [x] Anchor & Echo summaries: precise codebase terminology preserved (RLS, ON CONFLICT DO UPDATE, WAL coherence, syncCache + getAdjacentNodes, lazy-edges queue, LazyEdgeDrainer, IN_REPLY_TO, AUTHORED_BY).
- [x] `[RETROSPECTIVE]` tag: N/A.
- [x] Linked anchors: PR body cites #11912 + #11922 correctly (Related/Refs, not Closes/Resolves).

**Findings:** Pass. The Challenge above is `[KB_GAP]` substrate concern, not a finding against this PR.

---

### 🧠 Graph Ingestion Notes

*   **`[KB_GAP]`**: Memory Core JSDoc archaeology-stripping is an explicit substrate trade-off — git-blame becomes the canonical "why this code exists" surface once inline ticket anchors are removed. Future agents reading hot-path Memory Core code without ticket archaeology may need a "git blame + look up the originating commit's PR" reflex codified somewhere. Worth surfacing in a future agentic-substrate convention ticket.
*   **`[TOOLING_GAP]`**: N/A.
*   **`[RETROSPECTIVE]`**: Sets the cleanup-pattern floor for the heaviest Memory Core file (GraphService at 104 line changes). The 0-residual outcome (no preserved runtime-string false positives on this batch) confirms the regex sweep is well-calibrated for Memory Core surfaces. Sibling #11920's 1-residual was a JSDoc-vs-log-payload edge case unique to that file.

---

### 🎯 Close-Target Audit

- [x] Close-targets identified: none via magic keywords. `Related: #11912` + `Refs #11922` are both non-closing references (correct per the Epic Close-Target Ban — #11912 is the epic, #11922 the grouped sub).
- [x] No `Closes #N` / `Resolves #N` / `Fixes #N` in PR body or commit message.

**Findings:** Pass.

---

### 📑 Contract Completeness Audit

- [x] Originating ticket / parent epic context — PR body's Contract Ledger documents the comment-only surface change for each of the three files; #11922 grouped sub inherits #11912 epic's contract semantics.
- [x] Implemented PR diff matches the Contract Ledger exactly — diagnostic counts (38/26/19 → 0) reproducibly verifiable.

**Findings:** Pass.

---

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

N/A across listed dimensions: comment/JSDoc-only PR with no runtime code change → Evidence Audit not applicable (no executable behavior shipped); 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.

(The `[KB_GAP]` Memory Core git-blame-as-archaeology-fallback concern is a separate substrate-evolution thread, not a blocker for this PR.)

---

### 📊 Evaluation Metrics

*   **`[ARCH_ALIGNMENT]`**: 100 — No architectural shift; preserves all RLS predicates, ON CONFLICT DO UPDATE semantics, cache-warm + lazy back-fill discipline, WAL coherence assumptions, identity substrate seeding loop. Considered (a) inadvertent change to RLS predicate semantics, (b) loss of cache-warm retry logic comment that masks an actual sync requirement, (c) drift in linkNodesAsync prefix-normalization JSDoc — none apply.
*   **`[CONTENT_COMPLETENESS]`**: 100 — JSDoc retained substantive content for every method. Anchor & Echo discipline preserved (precise codebase terms vs metaphor). Considered: missing @summary tags on freshly-touched methods, JSDoc parameter rename drift — none apply.
*   **`[EXECUTION_QUALITY]`**: 100 — Tests not required per guide §2.2; mechanical comment-only diff cannot regress runtime. Diagnostic counts reproducibly documented. `git diff --check origin/dev...HEAD` clean per PR body. Considered: hidden semantic shift via JSDoc parameter rename, accidental code-line deletion disguised as comment, trailing whitespace — none apply.
*   **`[PRODUCTIVITY]`**: 100 — All stated PR-body goals achieved: archaeology cleared across 3 of the heaviest-noise Memory Core files, non-closing references on epic+sub, Contract Ledger present, 0-residual outcome.
*   **`[IMPACT]`**: 40 — Maintenance against three hot-path subsystems (GraphService in particular touches RLS, cache-warm, lazy back-fill, identity substrate seeding). Higher than #11920's 30 because the cross-file surface is larger; same maintenance-category outcome.
*   **`[COMPLEXITY]`**: 25 — Low-medium: 3 files vs #11920's 1, but still mechanical regex-driven sweep with reproducible diagnostic. Cognitive load to validate bounded by the diff length (~530 lines) + the archaeology regex.
*   **`[EFFORT_PROFILE]`**: Maintenance — Grouped archaeology sweep against three Memory Core surfaces. Pairs with #11920 to cover the #11922 grouped sub; remaining Memory Core files (DatabaseService, MailboxService is done, SessionService, SummaryService, WakeSubscriptionService, etc.) follow this template.

Clean execution. APPROVED — eligible for human merge. No required actions.

---

