Introduce overload-safe semantic identities

[samchon]

Work in progress, opened for visibility. The identity contract is implemented and the deterministic suite is green on all three operating systems, but two things are not done — they are spelled out in "What is not working" below, with the exact cause of each. Full handoff context is in #119.

Closes #65.

Summary

The position-invariant id contract path#qualifiedName:kind is not a unique semantic identity across languages: it collides for non-TypeScript overloads, multiple constructors, generic arities, partial declarations, extension methods, and same-named locals, so generic indexing silently deduplicates distinct declarations and strict providers reject the second valid node.

This introduces an intrinsic semantic identity for non-TypeScript declarations while keeping TypeScript ids byte-identical for ttsc parity — ttsc never emits overloads or constructors, so no TypeScript id changes and the pinned application contract and its prose grammar stay literally true.

Design

• semanticIdentity — a versioned identity record (language, native symbol, declaration role, module/target/translation-unit scope, and an overload discriminator folded into a sha256 digest) derived deterministically into an opaque id: @v2/<language>/<digest>#<name>:<role> when the provider can promise cross-edit stability, or @g2/… when only generation-scoped stability is honest. Legacy-id equivalents are retained for backward-compatible handle resolution.
• assignSemanticIdentities — promotes non-TypeScript nodes to intrinsic ids before dedupe and remaps edge endpoints. Undecorated callables, locals, and anonymous/generated declarations are marked generation-scoped rather than pretending their source coordinate is stable.
• Identity-aware dedupe/merge — semantic duplicates merge their declaration/implementation locations; a semantic-id collision is a producer defect; a legacy collision the generic path cannot disambiguate keeps the last declaration, while the strict provider boundary still rejects it.
• Resolution & serialization — SamchonGraphMemory indexes exact and legacy ids; resolveGraphHandle resolves an old undiscriminated handle to deterministic ranked candidates; wireEdges, reduce, and the benchmark viewer treat an opaque semantic id verbatim instead of splitting it as a path.

Because the id no longer carries the file for non-TypeScript nodes, anything that took the text before # now consults node.file. The #qualifiedName:kind suffix is preserved, so id.endsWith("#App.dispatch:method") still matches both legacy and semantic ids.

What is not working

1. Multi-location declarations crash the build (blocker). The swift, scala and ruby LSP experiment jobs fail with:

Error: @samchon/graph: semantic node has more than the declaration/implementation
location policy can preserve: @v2/swift/a06e3866…#Argument:namespace

mergeDuplicate in indexer/dedupeNodes.ts preserves only evidence + implementation and throws past that. A Swift type extended across several files, a reopened Ruby class, or a Scala companion legitimately has three or more declaration locations, so the throw kills the whole graph build. Issue #65's own Approach point 3 allows either "one semantic node with multiple provenance locations" or an explicit declaration/implementation policy — so this must become a deterministic, order-independent policy (preferably an ordered provenance list) rather than a crash, and it must not silently drop a location.

2. Coverage is 99.88% lines / 99.62% branches, not 100%. The Test step passes on all three operating systems; only the Coverage gate is red. Remaining gaps, each root-caused:

File	Uncovered	Missing input
indexer/dedupeNodes.ts	71-74	the fact-disagreement throw — two semantic nodes with the same id but a different name/kind
indexer/dedupeNodes.ts	82-85	the >2-locations throw — superseded by the policy fix above
SamchonGraphMemory.ts	205-208	fileOfEdgeSource is only called as evidence.file ?? …, so the edge needs no evidence.file and a semantic from absent from the dump
indexer/assignSemanticIdentities.ts	57	a parameter node whose qualifiedName has no (
indexer/assignSemanticIdentities.ts	159	the > ? 1 arm of the ambiguous-endpoint sort tiebreak
provider/semanticIdentity.ts	158-159	validateIdentity empty language/symbol/role throw
provider/semanticIdentity.ts	162-163	validateIdentity native.key === "" throw
provider/mergeGraphSlices.ts	124-125	edgeOrderKey's ?? "" / ?? 0 fallbacks — a strict edge with no evidence
provider/mergeGraphSlices.ts	131	the > ? 1 comparator arm
indexer/overrideEdges.ts	91	push's else arm — two members on the same semanticMemberKey group key

The three compareText helpers are left < right ? -1 : left > right ? 1 : 0; a sort over distinct keys can never return 0, so that arm is genuinely unreachable and wants a /* c8 ignore */ with a proof comment rather than a contrived test. Extend tests/test-graph/src/features/test_semantic_identity_edge_cases_stay_covered.ts, which already covers the rest of this surface and demonstrates the white-box idiom.

3. Deliberately deferred. Provider-native keys (Clang USRs, Roslyn ISymbol, JVM descriptors, Swift USRs) are not populated — the current discriminators come from lexical/static signatures. Those arrive with the language providers (#71–#84), which is what this contract exists to unblock.

What is verified

• pnpm --filter @samchon/graph build and @samchon/graph-test build — no errors
• Parity gate green: test_application_contract_reproduces_the_pinned_ttsc_reference, …fails_closed_on_drift, test_readme_embeds_the_exact_application_contract — TypeScript ids and the ttsc contract are unchanged
• The five semantic-identity regressions (distinguish provider symbols, keep overload ownership explicit, legacy handles remain resolvable, round-trip preserves references, edge cases stay covered)
• Broad local suite: static extractors for every language, dedupe/merge, real-codebase static dump, provider (fake server), resolver, resident — all Success
• Test step green on ubuntu, macOS and Windows
• Coverage step at 100% — see "What is not working" §2
• swift / scala / ruby LSP experiments — see "What is not working" §1

This is the P0 dependency of provider authority (#66), strict snapshot validation, and every language provider (#71–#84).

🤖 Generated with Claude Code

[samchon]

The local implementation is not mergeable yet, and the green GitHub checks cover only the empty reservation commit.

Reproduced blockers:

• ambiguous overload endpoints are assigned to the lexicographically first semantic hash;
• same-named non-callable locals are hashed before closure/final ownership and merge;
• TypeScript overload sets still collide because TypeScript is skipped by semantic assignment;
• valid symbols with 3+ partial locations are rejected, while generic identities include document scope and cannot merge cross-file partials;
• prefix-only detection reserves valid legacy @v2/** and @g2/** paths;
• display spelling participates in the final ID outside the identity digest;
• variable-to-property refinement occurs after semantic validation, leaving kind/ID/alias disagreement;
• semantic duplicate nodes/edges are normalized away before strict-provider validation;
• opaque IDs remove the file coordinate assumed by public IDs and compressed reached/tour payloads.

Acceptance must preserve canonical coordinate-bearing application structure, finalize ownership/kind before identity, bind overload endpoints only with signature/native proof, support arbitrary valid partial locations, reject exact duplicate provider facts, and add order/line-insertion/LSP/static/resident/dump regressions. #96/#97 lands first.

[samchon]

Handing this off. Full context for a fresh agent — the design, the CI state, the blocking >2-location bug, and every remaining coverage gap root-caused with the exact input to write — is in #119.

Current state: Test green on all 3 OSes; CI red on (1) the swift/scala/ruby experiments, which throw semantic node has more than the declaration/implementation location policy can preserve on real multi-location declarations, and (2) coverage at 99.88% lines / 99.62% branches. Both are fully diagnosed in #119 §3a and §3b.