LearnNewsExamplesServices
Frontmatter
id14502
titleConcept-spine defrag: alias-cluster detection + canonical-id merge
stateClosed
labels
enhancementaiarchitecture
assigneesneo-gpt
createdAtJul 2, 2026, 9:39 PM
updatedAtJul 3, 2026, 10:57 AM
githubUrlhttps://github.com/neomjs/neo/issues/14502
authorneo-opus-vega
commentsCount5
parentIssue14472
subIssues
14515 Concept-spine alias-cluster detection report
subIssuesCompleted1
subIssuesTotal1
contentTrust
projected
quarantined0
signals[]
blockedBy[]
blocking[]
closedAtJul 3, 2026, 10:57 AM

Concept-spine defrag: alias-cluster detection + canonical-id merge

Closed v13.1.0/archive-v13-1-0-chunk-8 enhancementaiarchitecture
neo-opus-vega
neo-opus-vega commented on Jul 2, 2026, 9:39 PM

Context

Consumer-enabling leaf of epic #14472 (Golden Path v2), filed in the operator-directed full-fledging pass (2026-07-02: every sub executable, no scrap-hunting). Live latest-open sweep at 2026-07-02T19:37:34Z: no equivalent ticket; epic sub-graph carries only #14454 (closed) + #14474 (probe, in progress).

Empirical origin: the #14474 pre-implementation scan (on-ticket, 14:46Z) found the concept spine FRAGMENTED — one semantic query surfaced four distinct node-ids for the Golden Path concept (CONCEPT:GoldenPath · golden-path · CONCEPT:Golden Path Synthesis · a fourth variant) and three for Dream Pipeline (CLASS:DreamPipeline / dream-pipeline / CONCEPT:DreamPipeline) — duplicates minted under at least three id-conventions (CONCEPT:PascalCase, bare kebab-case, CONCEPT:Title Case).

The Problem

Every graduated consumer of #14472 anchors to concept ids. Over a fragmented spine, anchoring silently splits neighborhoods: retrieval walks reach a fraction of the real neighborhood, gap detection double-counts, measurement (consumer 4) attributes touches to different nodes for the same concept, and the sandman slice renders partial pictures. Fragmentation is plausibly the single largest reachability-gap class the epic will measure — and no defragmentation mechanism exists.

The Architectural Reality

  • Mint sites: ai/services/graph/SemanticGraphExtractor.mjs (session anchoring, TAGGED_CONCEPT @ 1.0 curated / 0.8 auto) and ai/services/memory-core/MailboxService.mjs (message-side tagging). Neither canonicalizes ids at mint time.
  • Edge decay: ai/services/memory-core/GraphService.mjs:73PROTECTED_EDGE_TYPES excludes concept edges (IMPLEMENTED_BY/PARENT_CONCEPT decay by design, ADR 0024); any merge must preserve decaying-scent semantics, not inflate weights.
  • The #14474 probe artifact (measurements file, in progress) quantifies alias-cluster size and neighborhood disjointness per sampled concept — this leaf's detection pass generalizes that measurement to the full 20,526-concept spine.

The Fix

One PR delivering four pieces:

  1. Detection pass — normalize ids (strip CONCEPT: prefix, case-fold, kebab-ize) → cluster report artifact under learn/agentos/measurements/ (cluster count, size distribution, top-N worst clusters, per-cluster neighborhood overlap/disjointness).
  2. Canonical-id policy — one convention wins (candidate: bare kebab-case, matching the curated delta-updates/golden-path precedent); decided IN the PR from the report data and stated in the module docblock.
  3. Merge executor — re-point all edges from alias nodes to the canonical node (weight on collision: MAX, never SUM — sum would inflate scent against ADR-0024 decay semantics); write an alias→canonical map node property (or sidecar) so historical references resolve; alias nodes tombstoned, never hard-deleted in the same pass.
  4. Mint-time guard — both mint sites canonicalize through one shared helper before writing; spec pins that a Pascal/Title-form input lands on the kebab canonical id.

Contract Ledger Matrix

Target Surface Source of Authority Proposed Behavior Fallback / Edge Case Docs Evidence
Concept node ids (graph) ADR 0024 taxonomy + curated-id precedent One canonical id per concept; aliases resolve via map Unresolvable/ambiguous cluster → left split + listed in the report (no forced merges) Module docblock states the policy Report artifact + probe re-run showing unified neighborhoods
SemanticGraphExtractor / MailboxService mint paths This leaf Canonicalize-before-write via shared helper Helper failure → write proceeds with raw id + warn (never block the write path) JSDoc on the helper Unit spec per mint site

Decision Record impact

aligned-with ADR 0024 (taxonomy + decay semantics respected; no new edge classes, no protection changes — those belong to the OQ1 anchoring leaf).

Acceptance Criteria

  • Cluster report artifact committed (full-spine scan; the two known clusters — Golden Path ×4, Dream Pipeline ×3 — appear and merge)
  • Canonical-id policy stated in the shared helper's docblock, applied by BOTH mint sites (unit spec each)
  • Merge executor: edges re-pointed with MAX-weight collision rule; alias map queryable; tombstoned aliases carry a pointer, no hard deletes; zero orphaned edges after the pass (probe-verified)
  • Hermetic spec for detect + merge on a fixture graph (no live-store writes in unit scope, per the #14031/#14045 write-guard discipline)
  • Post-merge: #14474's probe re-run over the merged spine shows single-neighborhood resolution for the two known clusters
  • PR Resolves this leaf, Refs #14472

Out of Scope

  • Anchoring architecture / edge protection (OQ1 leaf).
  • Retrieval consumption of the unified spine (consumer-1 leaf).
  • Re-triggering extraction over historical sessions (the merge operates on the existing graph).

Avoided Traps

  • SUM-merging weights — inflates scent; MAX preserves the strongest real signal under decay semantics.
  • Hard-deleting aliases — breaks historical references and session provenance; tombstone + map.
  • Blocking mint on canonicalization failure — the write path's never-fail contract outranks id hygiene (#12972 arc).
  • Forced merges of ambiguous clusters — a wrong merge is worse than a split; ambiguity stays split and visible in the report.

Sequencing

Consumes the #14474 measurements artifact for validation (soft gate: detection can build in parallel; the merge PR lands after the probe artifact exists).

Related: #14472 (parent epic), #14474 (probe — validation instrument), Discussion #14422 (graduation source; measured-reality items 2/4)

Origin Session ID: 8cf234b7-e698-47ca-99e2-bf865196b6aa

Retrieval Hint: concept spine defrag alias cluster canonical id merge TAGGED_CONCEPT mint-time guard

tobiu referenced in commit 9a5272f - "feat(graph): canonicalize concept spine aliases (#14502) (#14528) on Jul 3, 2026, 10:57 AM
tobiu closed this issue on Jul 3, 2026, 10:57 AM