[Deferred] Shared/deduped value-node identity for complex properties

[savasp-agent]

Parent: #84 · Depends on: #6 · Type: Task · Status: deferred (tracked, not scheduled)

Goal

Add opt-in shared / deduplicated identity for value nodes created by option D (ADR-0002). This is deliberately deferred — #6 ships with per-instance identity (each in-memory instance ⇒ its own node). This issue exists to track the follow-up so it is not lost.

Background

Under ADR-0002 option D, complex-object properties become first-class nodes ((:Person)-[:Home]->(:Address)). #6's default is per-instance value nodes: two owners referencing the same in-memory Address instance produce two distinct :Address nodes (preserves value-object semantics, matches prior behavior). Some domains instead want shared identity — one :Address node referenced by many owners (e.g. "everyone at this address"), with well-defined update/aliasing semantics.

Scope (to be designed when scheduled)

• An opt-in mechanism to mark a value type (or property) as identity-bearing/shared — e.g. an attribute or a NodeWithIdentity-style base/marker. Decide the identity key (by value equality? explicit key members?).
• Define write semantics: dedupe on write (MERGE by key) vs. explicit identity; and the update/aliasing contract (editing a shared node affects all referrers — must be intentional and documented).
• Read semantics and how it interacts with the read-shape-driven auto-load from Improve code readability, modularization and reuse in Neo4j Graph Provider #6.
• Migration/compat considerations.

Not now

Do not implement until scheduled. Keep #6 strictly per-instance. When scheduled, this becomes its own ADR addendum or a short design note before implementation.

Process

When picked up: fresh worktree off origin/main; codegraph init -i; writes via gh-app.

[savasp-agent]

Retained as a permanent exception to the zero-open-issues goal (@savasp, 2026-07-13). This deferred tracker stays open by design — do not close as part of reaching zero. Recorded in #113.

[savasp-agent]

@savasp reconfirmed on 2026-07-15 under the revised exit criterion: this issue remains open and is explicitly deferred. It does not block program exit. Do not dispatch without a future @savasp scheduling decision.

[savasp-agent]

Deferred status reconfirmed after #456. The v1.0 architecture intentionally keeps complex-value nodes per owning entity and introduces no replacement hidden identity convention; #476 and #480 must preserve that boundary. This issue remains open only because @savasp explicitly deferred shared/deduplicated value-node identity.