[P0][Graph PR B] Add deterministic semantic multigraph storage and artifact v2

[mohanagy]

Parent: #649
ADR sequence: 2 of 4
Depends on: #656
Merge blocked by: #654
Qualification baseline: #655

---

Maintainer amendment after Stage 0 endpoint-identity audit

This section supersedes the absolute movement-stability invariant stated below. Read it first. Every clause elsewhere in this body that asserts the absolute rule is qualified to require two stable endpoints.

A mandatory adversarial review disproved the premise that a bounded set of route node IDs could be corrected to make fact identity universally movement-stable. Route-only partial re-keying is prohibited in this issue — it risks silent node collisions and an inconsistent identity policy. Making semantic node identities actually movement-stable is #704.

Endpoint identity is explicit, with four states

type EndpointIdentityStatus = 'stable' | 'context_bound' | 'unknown' | 'legacy'

interface EndpointIdentityQualification {
  readonly source: { readonly status: EndpointIdentityStatus; readonly reasons: readonly EndpointIdentityReason[] }
  readonly target: { readonly status: EndpointIdentityStatus; readonly reasons: readonly EndpointIdentityReason[] }
}

Status	Meaning
stable	positively audited: deterministic under the declared identity-policy version, repository-relative rather than checkout-root dependent, independent of incidental line/column/range, independent of unstable ordinals and collision order, collision-safe for the node kind. Absence of a known problem does not prove stable.
context_bound	known to depend on non-semantic context — source line/column/range, absolute workspace path, source ordinal or rawIndex, collision suffix, or adapter-local synthetic identity. Exact reasons must name the dependency.
unknown	the producer or compatibility caller does not supply enough information to classify. Not an alias for context_bound, and never silently stable.
legacy	v1-loaded endpoints whose historical identity policy cannot prove the current v2 guarantees.

Reason codes, at minimum: source_location_derived, absolute_workspace_path_derived, source_ordinal_derived, collision_suffix_derived, adapter_local_synthetic_identity, identity_policy_not_declared, identity_policy_not_audited, legacy_identity_policy. A status and its reasons must be internally consistent — stable carries no degradation reason; context_bound carries at least one context-dependency reason; unknown carries identity_policy_not_declared or identity_policy_not_audited; legacy carries legacy_identity_policy. Malformed combinations fail invariant validation.

This dimension is separate from discriminator completeness and must not be hidden in arbitrary metadata.

Admission policy

Status	Normal-mode behaviour
stable	retain
context_bound	retain, visibly degraded
unknown	retain, visibly degraded
legacy	retain only through the legacy compatibility path, visibly degraded

A fact is never rejected solely because an endpoint is unknown. Discarding real facts because the identity audit is incomplete would be worse than recording the uncertainty.

Hard failure remains correct for: missing source endpoint, missing target endpoint, malformed endpoint qualification, impossible status/reason combination, hash/payload invariant failure. A missing endpoint is not unknown; a malformed qualification is not unknown. Missing internal endpoints must not be auto-created.

Every admitted node carries one normalized status: audited producers attach stable or context_bound; the v1 loader attaches legacy; unmigrated or compatibility producers attach unknown with an explicit reason. addNode() stores it, addEdge() verifies both endpoints exist with valid stored qualifications, and copy/subgraph/load preserve them exactly. A compatibility API that omits qualification normalizes to unknown + identity_policy_not_declared — never to stable, and never by dropping the node.

The truthful movement rule

Moving an evidence location changes the occurrence ID, and does not change the fact ID, when both semantic endpoint identities are stable and the behaviour discriminator is unchanged.

For any other status the fact ID may change when the endpoint NodeId changes; the fact stays deterministic for one exact snapshot; the limitation is machine-visible; and it may not be cited as proof of cross-movement stability.

• IDs deterministic — for the exact source snapshot and declared identity policy.
• Movement-stable — a stronger, qualified property holding only for stable+stable facts.

Receipt: an exact 4 × 4 partition

The storage-only receipt carries an ordered source-status × target-status matrix. Outer key is source status, inner key is target status. For undirected facts, use the same canonical endpoint ordering as fact identity, and document it.

{
  "accounting_scope": "storage_only",
  "status": "degraded",
  "reasons": ["full_emission_accounting_not_available"],
  "endpoint_identity": {
    "statuses": ["stable", "context_bound", "unknown", "legacy"],
    "fact_pair_counts": { "stable": { "stable": 0, "context_bound": 0, "unknown": 0, "legacy": 0 }, "context_bound": {}, "unknown": {}, "legacy": {} },
    "reason_fact_counts": {}
  }
}

Partition invariant: the sum of all sixteen cells equals the number of facts retained in the artifact. No retained fact is absent from the matrix; none occupies more than one cell. There is no "worst status wins" precedence, because no single precedence preserves both endpoint statuses.

reason_fact_counts counts distinct retained facts carrying each reason. A fact with several reasons contributes to several counters, so reason counts are not a partition and their sum need not equal the fact count. This must be documented, not implied. Derived summaries such as fully_stable_facts should be computed from the matrix; if serialized redundantly they must be validated against it and disagreement must fail.

A missing endpoint produces no fact and therefore no cell — admission fails with a typed error. Durable accounting for the rejected candidate belongs to #658. Do not add missing, failed or rejected to the status union.

The receipt never claims valid.

Propagation is staged — PR B stores, it does not project

#657 makes the qualification available in the graph domain only: SemanticFact, KnowledgeGraph fact queries, artifact v2 and its loader, the storage-only receipt, and graph-specific inspection APIs directly required by artifact v2.

#657 must not change Pack v1 relationships or coverage fields, Pack answerability, context-pack governance, MCP response answerability, existing ready / verify_targets / insufficient transitions, or text renderers merely to expose this limitation. No optional Pack fields, no answerability cap, no partial PR-D implementation.

#657  store and serialize the limitation
#658  preserve it in the normalized-boundary integrity receipt
#659  project it compactly into Pack/MCP and cap answerability

The intermediate next branch may carry stored degradation before PR D consumes it. No beta may be published in that state.

Additional acceptance criteria

• Every fact records endpoint identity completeness.
• Every location-derived endpoint admitted by current producers is classified.
• The artifact reports degraded endpoint facts without claiming full identity stability.
• No partial node-ID rewrite introduces silent collisions.
• The dedicated semantic-node-identity issue ([P0] Introduce movement-stable semantic node identities and node evidence occurrences #704) is linked.
• Every retained fact occupies exactly one endpoint-status matrix cell.
• The 4 × 4 matrix sums exactly to retained facts.
• Unknown endpoint identity is retained only as explicit degradation.
• No unclassified endpoint silently becomes stable.
• Missing/malformed endpoints are not represented as identity statuses.
• PR B does not alter Pack/MCP/answerability.
• [P0][Graph PR C] Account for every normalized graph candidate and retain unresolved facts #658 and [P0][Graph PR D] Cap answerability from graph-integrity state #659 are linked as the propagation chain.

Additional non-goals

• global semantic node-ID rewrite ([P0] Introduce movement-stable semantic node identities and node evidence occurrences #704)
• node evidence occurrence migration ([P0] Introduce movement-stable semantic node identities and node evidence occurrences #704)
• cross-revision identity continuity for context-bound endpoints
• Pack / MCP / answerability propagation ([P0][Graph PR D] Cap answerability from graph-integrity state #659)
• terminal candidate accounting ([P0][Graph PR C] Account for every normalized graph candidate and retain unresolved facts #658)

Unchanged and still binding: multigraph storage, artifact v2, old-reader rejection, topology uniqueness, Pack required-field compatibility, and the performance gate.

---

Outcome

Replace endpoint-only relationship storage with a deterministic semantic multigraph that preserves behaviorally distinct facts, separate evidence occurrences, and unique endpoint-pair topology.

Introduce artifact v2 with deterministic round-trip behavior, safe v1 loading, and a proven mechanism preventing v0.32.1 from silently down-reading v2.

This issue corrects the confirmed silent-overwrite defect. It does not yet implement full normalized-candidate integrity accounting or answerability propagation.

Confirmed defect

At v0.32.1:

• KnowledgeGraph.edgeMap is keyed by source + target only;
• Map.set() makes insertion last-write-wins;
• calls followed by injects between the same endpoints leaves only injects;
• reversing insertion order leaves only calls;
• same-relation facts at different locations also collapse;
• serialization exports only the survivor;
• deserialization routes input through the same collapsing behavior.

This is P0 because valid semantic and provenance evidence can disappear deterministically while downstream retrieval and context compilation appear successful.

Architecture decision

Implement separate canonical concepts:

1. Semantic fact — one behaviorally distinct relationship.
2. Evidence occurrence — one adapter-owned observation supporting a fact.
3. Topology pair — one unique directed/undirected endpoint pair used by topology algorithms.
4. Storage-only integrity status — an honest temporary status until PR C adds full normalized-boundary accounting.

Conceptual semantic fact

interface SemanticFact {
  readonly id: SemanticFactId
  readonly direction: 'directed' | 'undirected'
  readonly source: NodeId
  readonly target: NodeId
  readonly relation: RelationType
  readonly discriminator: SemanticDiscriminator
  readonly endpointIdentity: EndpointIdentityQualification
  readonly occurrenceIds: readonly EvidenceOccurrenceId[]
  readonly annotations: Readonly<Record<string, CanonicalJson>>
}

Conceptual occurrence

interface EvidenceOccurrence {
  readonly id: EvidenceOccurrenceId
  readonly factId: SemanticFactId
  readonly owner: {
    readonly adapterId: string
    readonly strategy: string
    readonly sourceFile?: string
    readonly adapterVersion?: string
  }
  readonly sourceFile?: string
  readonly sourceRange?: SourceRange
  readonly targetFile?: string
  readonly targetRange?: SourceRange
  readonly siteKind?: string
  readonly adapterEvidenceKey?: string
  readonly provenance: readonly Provenance[]
  readonly confidenceObservations: readonly ConfidenceObservation[]
  readonly metadata: Readonly<Record<string, CanonicalJson>>
}

Adapt exact types to repository conventions without weakening the fact/occurrence separation.

Fact identity

Fact ID must be deterministic and content-derived from canonical semantic content:

"sf_" + SHA-256(canonical JSON {
  identitySchemaVersion,
  direction,
  source,
  target,
  relation,
  discriminator registry/policy version,
  discriminator completeness,
  canonical discriminator value
})

Requirements:

• full lowercase SHA-256 hex; no truncation;
• UTF-8 canonical input;
• NFC string normalization;
• lexically ordered object keys;
• finite JSON numbers only;
• explicit ordered versus set-like array handling;
• source ranges, adapter names, confidence, timestamps, scores, and arbitrary metadata excluded;
• directed endpoint order preserved;
• undirected endpoints canonically sorted;
• different canonical payloads producing one hash is a fatal invariant failure.

Renaming a node may change its node/fact ID. Moving an evidence location must not change fact identity when both endpoint identities are classified stable and the discriminator is unchanged. When either endpoint is context_bound, the fact ID may change and the fact is classified partial/degraded — see the maintainer amendment above.

Occurrence identity

Occurrence ID must be deterministic and adapter/evidence-site specific:

"eo_" + SHA-256(canonical JSON {
  occurrenceIdentitySchemaVersion,
  factId,
  adapterId,
  strategy,
  repositoryRelativeSourceFile,
  sourceRange,
  repositoryRelativeTargetFile,
  targetRange,
  siteKind,
  adapterEvidenceKey
})

Exclude confidence, mutable scores, timestamps, adapter version, absolute paths, and provenance ordering.

Required behavior:

• same adapter/site repeat merges deterministically;
• different adapters remain separate occurrences;
• different call/registration sites remain separate occurrences;
• moving a site changes occurrence ID but not fact ID when both endpoints are stable; when either endpoint is context_bound, the fact ID may also change and the fact is degraded;
• unchanged full generation reproduces IDs exactly;
• provenance and confidence disagreement remain observable.

When no range or stable evidence key exists, indistinguishable emissions may merge only with an explicit diagnostic such as occurrence_multiplicity_unknown; do not invent nondeterministic sequence IDs.

Relation discriminator registry v1

Add an exhaustive, static, versioned registry. There is no implicit endpoint-only fallback for unknown relations.

At minimum define policies for:

Calls

Behavior fields may include dispatch kind, invocation kind, optionality, overload identity, and resolution state.

Multiple sites with identical behavior are occurrences of one fact. Optional versus ordinary calls, construct versus call, or valid different overload targets may be separate facts.

Dependency injection and registrations

Cover current relations such as injects, provides, module/controller registration relations, with token, qualifier, scope, binding kind, resolved implementation, and resolution state where available.

Routes/middleware

Cover route/handler/controller/mount/middleware relations using HTTP method, normalized path, registration type, router scope, order where behaviorally relevant, and direct/decorator/config/generated origin.

Producers/consumers/jobs

Cover queue/topic/event/job identity, channel name, job type, routing key, role, and resolution state.

Imports/exports

Cover binding kind, imported binding, runtime versus type phase, static versus dynamic form, module specifier, and internal/external/unresolved state.

Explicit endpoint-only relations

Known structural relations may use a registered endpoint-only policy. The registry must list them explicitly.

Fallback behavior

• registered relation missing data: retain a partial/coarse fact only when endpoint-level meaning remains valid and record reasons;
• unregistered relation: do not invent endpoint-only identity; produce storage-boundary unresolved/degraded handling sufficient for this slice, with full accounting deferred to PR C;
• unknown metadata remains on occurrences and never enters identity blindly;
• conflicting valid discriminators create separate facts and an explicit conflict diagnostic, or are withheld when unsafe to canonicalize.

A registry version change invalidates identity caches and requires regeneration.

Duplicate/conflict policy

Implement and test:

Case	Required behavior
Same fact and same occurrence twice from one adapter	Merge occurrence; union provenance/confidence observations deterministically
Same fact/site from different adapters	One fact, separate occurrences
Same fact at different locations	One fact, separate occurrences when both endpoints are stable. With a context_bound endpoint the sites may yield separate facts; each is deterministic at one snapshot and classified degraded.
Same endpoints/relation, different valid discriminator	Separate facts
Same endpoint/relation with partial registered discriminator	Retain partial coarse fact with reasons when safe
Same occurrence, different confidence	Preserve all observations; no winner erases disagreement
Conflicting behavior metadata	Separate valid facts plus conflict diagnostic, or withhold as conflict; never last-write-wins
Legacy v1 fact	One legacy/partial fact and legacy occurrence; warn multiplicity is historically unrecoverable

No case permits arbitrary first-writer or last-writer selection.

Storage and indexes

Store facts by SemanticFactId, occurrences by EvidenceOccurrenceId, with deterministic secondary indexes for:

• source;
• target;
• relation;
• endpoint pair;
• fact-to-occurrence lookup.

The plural APIs introduced by #656 must now return all facts deterministically.

Topology remains unique-neighbor/unique-endpoint based:

• BFS/DFS/path existence: endpoint pairs;
• centrality: endpoint pairs;
• communities: endpoint pairs;
• bridges: endpoint pairs;
• relation-aware traversal: matching facts with deduplicated endpoint visits;
• semantic analysis/diff: facts;
• evidence strength/provenance: occurrences.

Occurrences must never create extra traversal steps or centrality weight. Initial ranking must not sum fact/occurrence multiplicity.

edgeAttributes(source, target) compatibility behavior after this issue:

• zero facts: existing unknown-edge behavior;
• exactly one fact: compatibility projection;
• multiple facts: typed AmbiguousEdgeError.

Internal code must already be migrated by #656.

Artifact v2

Canonical artifact:

out/graph.madar

Format:

MADAR_GRAPH_ARTIFACT/2
<canonical UTF-8 JSON payload>\n

Payload must include explicit versions for artifact, fact identity, occurrence identity, discriminator registry, repository revision, generation mode, nodes, facts, occurrences, hyperedges, community labels, and a storage-only integrity status.

Deterministic ordering:

• nodes by node ID;
• facts by fact ID;
• occurrences by occurrence ID;
• occurrence IDs within facts sorted;
• canonical object keys;
• deterministic hyperedge/label ordering.

A generated timestamp must not invalidate deterministic tests; inject/fix it in deterministic fixtures.

During the PR B → PR C interval, integrity must state honestly:

{
  "accounting_scope": "storage_only",
  "status": "degraded",
  "reasons": ["full_emission_accounting_not_available"]
}

It must not say valid before PR C.

Legacy artifact compatibility and old-reader rejection

Simply adding an unknown JSON field is unsafe because the v0.32.1 loader can ignore it.

Required migration behavior:

1. v2 uses the non-JSON magic header and distinct out/graph.madar path.
2. When v2 activates, preserve a valid existing v1 artifact as out/graph.v1.json where applicable.
3. Atomically replace default out/graph.json with a non-JSON tombstone:

MADAR_GRAPH_MOVED/2
Use out/graph.madar with Madar >= the v2-supporting version.

4. Prove using the exact v0.32.1 loader behavior:
   • old loader rejects graph.madar;
   • old loader rejects the tombstone;
   • new loader reads v2;
   • new loader reads legacy v1 as degraded.
5. Never down-convert v2 to v1 while claiming equivalence.
6. Rollback requires source regeneration using the prior binary.

New loader behavior for v1:

• recognize pure legacy JSON;
• convert each surviving link into one deterministic legacy fact and occurrence;
• mark discriminator completeness legacy/partial;
• emit legacy_parallel_facts_unrecoverable;
• permit bounded normal-mode use as degraded;
• reject qualification/strict use;
• recommend full regeneration.

Scope

Likely affected modules:

• src/contracts/graph.ts;
• src/contracts/types.ts;
• new focused semantic-graph/identity/canonicalization/discriminator modules;
• src/pipeline/build.ts;
• src/pipeline/export.ts;
• src/runtime/serve.ts;
• src/shared/workspace.ts;
• graph-copy/subgraph helpers;
• CLI graph-path resolution/help directly required by graph.madar.

Explicit non-goals

• Full normalized-candidate integrity receipt/state machine — PR C.
• Graph-integrity answerability cap — PR D.
• Retrieval/ranking redesign.
• SPI/legacy consolidation.
• Incremental indexing.
• MCP profiles/installers.
• Pack required-schema redesign.
• New languages/frameworks.
• Broad CLI refactor.

Required tests

Semantic preservation

• calls and injects on identical endpoints → two facts, one endpoint pair;
• same relation/different valid discriminator → separate facts;
• same fact/different sites → one fact, multiple occurrences;
• compiler and heuristic corroboration → separate occurrences;
• exact duplicate → deterministic merge;
• conflicting metadata → explicit conflict/no winner;
• unknown relation → unresolved/degraded, not topology.

Graph APIs/topology

• all facts returned deterministically;
• relationsBetween() stable;
• ambiguous compatibility API throws;
• successors/predecessors remain unique;
• fact/pair/occurrence counts differ correctly;
• centrality/community/bridges/path steps do not multiply;
• impact visits each node once;
• relation filters preserve all qualifying fact IDs.

Identity

• deterministic canonical JSON;
• stable fact and occurrence IDs;
• line move changes occurrence, not fact, for stable-endpoint facts; for a context_bound endpoint, assert instead that the fact is deterministic at one snapshot, classified context_bound, and contributes a degraded receipt reason;
• adapter change produces separate occurrence;
• canonical payload collision check is fatal;
• absolute paths/timestamps/scores do not affect identity.

Serialization/compatibility

• byte-deterministic v2 round trip;
• facts, discriminators, occurrences, provenance and storage-only receipt survive;
• v1 loads degraded;
• historical multiplicity warning;
• exact v0.32.1 loader rejects v2 and tombstone;
• corrupt header/body invalid;
• unsupported schema/identity/registry version incompatible;
• cache invalidation on version/revision changes.

Differential safety

• centrality, communities, bridges, and path topology match unique-pair baseline;
• Pack v1 external required schema remains unchanged;
• every changed Pack/retrieval output caused by newly preserved facts is reviewed;
• generated demo/eval graph regression;
• exporter/report/Neo4j representations distinguish facts from occurrences where exposed.

Performance and artifact gate

Measure representative before/after:

• generation time;
• serialization/loading time;
• peak RSS;
• artifact size;
• fact/occurrence/pair counts.

More than 2× cost in a material dimension requires explicit review and an accepted rationale; do not silently accept it.

Acceptance criteria

• Every valid fact admitted at the storage boundary survives.
• No Map.set() path can overwrite another semantic fact.
• Exact duplicate and conflict behavior follows the documented policy.
• Evidence/provenance survives merging.
• Topology is not multiplied by facts or occurrences.
• IDs and artifact bytes are deterministic.
• Artifact v2 cannot be silently down-read by v0.32.1.
• v1 loads only as visibly degraded and cannot qualify strict runs.
• Artifact/cache migration and rollback paths are tested.
• Pack v1 required fields remain compatible.
• Storage-only receipt never claims full validity.
• Performance/artifact measurements are published and reviewed.
• [P0] Stabilize the complete Vitest suite and protected CI merge gate #654 is complete before merge.
• All protected gates pass.

Preconditions carried from the #680 plural-projection audit

These are not new scope. They are the four findings the audit deliberately did not fix in PR A,
because none can be triggered or tested until this issue introduces fact multiplicity, plus the
testing gap that follows from the same cause. Each is recorded as a comment at its site in the
merged code; they are listed here so they gate the work rather than annotate it.
See #657 (comment) for the full audit.

• endpointEntries() still yields each endpoint pair exactly once under a fact-keyed store, and the Louvain accumulation in cluster.ts is re-verified. _edgeWeight is correctly non-additive, but the loop consuming it accumulates per entry (totalWeight +=, neighborWeights, nodeDegree). If this issue makes the store fact-keyed and that uniqueness lapses, Louvain weights inflate silently and the suite stays green.
• graphDiff() distinguishes facts that differ only by discriminator. Today it keys on endpoints + relation, so adding such a fact reports as no changes.
• N-order stability of relationsBetween() is proven against this issue's fact-ordering contract, not inherited from it. It currently delegates to factsBetween() order and does not normalise independently, so property 4 of [P0][Graph PR A] Introduce plural relationship queries and explicit topology APIs #656 must be re-established here.
• SVG export does not render multiplicity as visual weight. N facts currently draw N coincident lines, so alpha overdraw makes a connection look stronger purely because more facts share its endpoints — the same non-additive principle already corrected in cluster.ts.
• The plural-fact consumers enumerated in the feat(graph): PR A — plural relationship queries and explicit topology APIs (#656) #680 audit each have a test exercising N > 1. All of them are correct today only because N is always 1; none is currently characterised at N > 1.

Rollback

Revert this issue’s PR, restore/regenerate a real v1 out/graph.json from source using the prior binary, and retain graph.madar only as an ignored diagnostic backup. Never convert v2 to v1 while claiming semantic equivalence.

Agent handoff

Implement only PR B. Stop before full integrity accounting or answerability changes. The final report must include architecture conformance, exact model/index/serializer changes, compatibility fixture evidence, all output differences, performance measurements, complete validation, and rollback instructions.

---

Implementation amendment — PR B split

The conceptual ADR slice is unchanged. PR B is implemented as two sequential mergeable PRs because the legacy-path cutover changes a large public and test contract unrelated to graph storage (618 graph.json mentions across 60 test files, 148 of them hard JSON.parse assumptions, plus 130 in src, 366 in docs, and three public surfaces).

B1 — core multigraph and transitional artifact activation

• semantic fact / occurrence storage
• endpoint-pair topology
• relation registry
• storage-boundary degradation
• deterministic artifact v2
• canonical graph.madar generation
• new-reader preference for graph.madar
• fresh v1 graph.json compatibility mirror
• no tombstone activation
• no public graph resource rename
• no claim that the old default loader rejects

B2 — legacy graph-path cutover (#705)

• stop active v1 mirror generation
• preserve valid v1 as graph.v1.json
• write the graph.json tombstone
• migrate the public HTTP / MCP / installer surfaces
• migrate all tests, docs and fixtures
• exact old-default-reader rejection
• rollback and source regeneration

Dependency and release gates

#657 is completed only after B1 and B2.
#658 depends on B2.
No release is permitted between B1 and B2:
  no v0.33.0* tag, no npm next dist-tag,
  no GitHub beta/RC, no MCP Registry prerelease.

The transitional dual-artifact state is allowed on next only. It is not an approved release state.

Every acceptance criterion below concerning the graph.json tombstone, the default-path old-reader rejection, or the public graph resource contract is Owned by B2. Those criteria are unchanged, not removed.

[mohanagy]

Plural-projection audit complete — #657 may begin, with five recorded preconditions

PR A (#680) is merged into next as f91d893beed9. The mandatory plural-projection audit that gates this issue has been run — twice, independently and adversarially, because CodeRabbit was rate limited when #680 became mergeable and a 29-file production change to the graph layer would otherwise have merged with no independent review.

Audit method. All 19 factsBetween/relationsBetween call sites and all 30 factEntries() call sites were enumerated rather than sampled, because the prior audit in this area failed precisely by verifying a named set and generalising to the category. The five properties #656 requires were verified empirically, not by reading: absent pair → [], one fact → one item, relation filtering, stable ordering, and mutation isolation checked by attempting mutation at every depth and confirming the graph was unchanged.

Result. All four accumulation sites are correctly non-additive. Three defects were found and fixed in #680 before merge: returned values could alias graph state through functions and shared buffers; the new Neo4j multiplicity guard had an ambiguous key that falsely blocked exports for ids containing spaces; and only one of the two MERGE sinks was guarded. A further five findings from CodeRabbit's later review were also fixed, including rejecting poisoned attributes at write time rather than read time.

The five preconditions this issue must satisfy

These were deliberately not fixed in PR A, because none can be triggered or tested until fact multiplicity exists. Each is recorded as a short comment at its site in the merged code.

1. graphDiff() keys facts by endpoints + relation only (analyze.ts:970). Two facts differing solely by discriminator collapse to one key, so a real change reports as no changes. Semantic diff must operate on facts once facts are distinguishable.

2. Louvain weighting is only half-protected (cluster.ts). _edgeWeight is correctly non-additive, but the loop consuming it accumulates per entry — totalWeight +=, neighborWeights, nodeDegree. That defence holds only because endpointEntries() yields each pair once. It is contractually pinned today and keyed by edgeKey(source, target), but no test can pin it under multiplicity because multiplicity cannot be constructed yet. If this issue makes the store fact-keyed, Louvain weights inflate silently and the suite stays green. This is the one most likely to be missed.

3. N-order stability of relationsBetween() is inherited, not owned. It delegates to factsBetween() fact order rather than normalising independently. This issue mandates deterministic fact identity and ordering, so property 4 of [P0][Graph PR A] Introduce plural relationship queries and explicit topology APIs #656 must be re-proven here rather than assumed.

4. SVG export draws N coincident lines for N facts (export.ts:2043), making multiplicity visually additive through alpha overdraw — the same non-additive principle already corrected in cluster.ts.

5. 17 consumer files gained future-N behaviour with no N-characterization tests. They are correct today because N is always 1. Each needs a test that actually exercises N > 1 once the store can produce it.

Verdict

#657 may begin. Its ordered precondition — PR A merged and the plural-projection audit complete — is satisfied. The five items above should be written into this issue's acceptance criteria rather than left as code comments, so they gate the work rather than merely annotate it.

Two constraints unchanged: the graph order remains #656 → #657 → #658 → #659, and beta publication stays prohibited while the graph migration is partial.

Related parent: #649.

[mohanagy]

Preflight — #657 may begin

Verified against GitHub and origin/next at ee2115a2465c86306735494f526dca8baf0383bc, not asserted from memory.

Prerequisite	State
#656 (Graph PR A)	complete — PR #680 merged, 13/13 acceptance criteria with matrix
#654 (merge blocker)	complete
#655 technical baseline	merged — PR #681; 22 files under docs/qualification/ plus the validator present on next
#655 human criteria	open — criteria 2 and 3 only, independence of truth ownership and sealed holdout
#684	owns the holdout/person gate; states "Does not block: #655 merge, Phase 0 graph work, or regression-only Tier 1 execution"
next-blocker on #655	removed by maintainer decision — see the governance comment on #655

#657 may begin.

What remains binding

Every acceptance criterion on this issue stays in force, including the five carry-forward multiplicity gates added from the #680 plural-projection audit. Nineteen unchecked criteria, none waived. The one most likely to be missed, restated because it fails silently:

endpointEntries() must still yield each endpoint pair exactly once under a fact-keyed store. _edgeWeight is correctly non-additive, but the loop consuming it accumulates per entry — totalWeight +=, neighborWeights, nodeDegree. If this issue makes the store fact-keyed and that uniqueness lapses, Louvain weights inflate silently and the suite stays green.

Standing limitations for any evidence produced here

All qualification evidence remains regression-only. No generalization claim and no independent-holdout claim is permitted, because #684 is unsatisfied and a second AI agent directed by the same owner does not satisfy it.

This is PR B only. Terminal candidate accounting, answerability caps, and retrieval/ranking redesign belong to PR C and PR D. The sequence #656 → #657 → #658 → #659 is not compressed.

Phase 0 is not complete and the beta is not ready.

Refs #657. Related parent: #649.

[mohanagy]

Stage 0 architecture gate — verdict: hold before code

Base ee2115a2, worktree ../madar-657, branch roadmap/657-semantic-multigraph-v2, node v22.22.3 / npm 12.0.2, lock 0144eb0d…. No production code has changed.

Two decisions below conflict with normative requirements of this issue. Per the execution rules they are not being delegated to an implementation worker, and Stage 1 does not start until they are settled.

Process note, stated plainly: the three parallel read-only audits were dispatched but returned no reports — all three went idle without delivering, twice for two of them. The analysis below was performed directly instead, plus one Codex read-only pass for per-relation discriminator availability. It is single-threaded work, not the three-way independent cross-check the plan called for. Every claim is traced to file:line so it can be checked rather than trusted.

---

1. Relation registry — exhaustive, and it closes

31 distinct relations, every one from an in-repo producer. There is no canonical RelationType union today; relation is an open string and src/contracts/extraction.ts REQUIRED_EDGE_FIELDS validates presence only, never value. SPI adapters are in-repo compiled files, not third-party plugins, so the surface is statically enumerable.

Classification: 0 full · 16 partial · 15 endpoint-only · 0 unknown.

Endpoint-only (15), registered explicitly as #657 requires: cites, contains, declares, declares_controller, defines_action, defines_selector, inherits, loads_route, method, provides, rationale_for, references, renders, shared_across_repos, submits_route.

Partial (16), with the specific missing datum: calls (dispatch/invocation kind, optionality, overload identity, resolution state) · depends_on (dependency kind, token/qualifier, uniform method/origin) · enqueues_job (persisted worker key, queue/job decomposition, routing key, role) · handles_route (uniform HTTP method, origin, registration type, order) · imports / imports_from (specifier, binding kind, phase, form, resolution state) · injects (token, parameter index, qualifier, scope, binding kind) · middleware (order, scope, registration type, origin) · mounts_router (mount path, registration type, scope) · registered_in_store (per-edge reducer key) · registers_route (method/path, registration type, scope, origin, order) · updates_slice (lifecycle/case selector) · uses (use kind, resolution state) · uses_guard / uses_interceptor / uses_pipe (decorator scope and order).

No relation supports a full discriminator from data that exists on the edge today. That is not a stop by itself: this issue already permits a registered partial policy with recorded reasons, and partial-with-reasons is the honest representation. It becomes a stop only if a value is invented, which is precisely what must not happen for call dispatch semantics, injection scope/qualifier, import phase/form, decorator order, route origin, Redux lifecycle, and queue routing.

Registry identifier: madar.relation-discriminator-registry/1. A field-set, default, normalization, ordering or policy change bumps the version and requires regeneration.

2. The confirmed defect, measured

addEdge(a, b, {relation: 'calls',   site: 'line-10'})
addEdge(a, b, {relation: 'injects', site: 'line-20'})
factsBetween(a,b) → [{"relation":"injects","site":"line-20"}]   numberOfFacts() → 1

edgeMap.set(edgeKey(source,target), …) overwrites. The calls fact is destroyed. Self-graph at this base: 17,865 links across 17,865 distinct endpoint pairs — real multiplicity today is exactly zero, so no existing test exercises N > 1.

3. Storage and index design

Facts by SemanticFactId, occurrences by EvidenceOccurrenceId, secondary indexes for source, target, relation, endpoint pair, and fact→occurrence.

The load-bearing decision: endpointEntries() must derive from a dedicated endpoint-pair index or from the successor/predecessor sets — never from the fact store. neighbors() already flows from successorMap/predecessorMap, which are Sets and therefore unique by construction; endpointEntries() flows from edgeMap and is the one that breaks. cluster.ts::_edgeWeight is correctly non-additive, but the loop consuming it accumulates per entry (totalWeight +=, neighborWeights, nodeDegree), so if pair uniqueness lapses, Louvain weights inflate silently and the suite stays green.

4. Topology versus semantic projections — a larger gap than the carry-forward list implied

numberOfFacts() has 15 callers, and 14 of them label the value "edges": report.ts:108, wiki.ts:248, export.ts:346 (edges:), federate.ts:218 (totalEdges:), graph-summary.ts:598 (edge_count:), diff.ts:67-68, time-travel.ts:291, prompts.ts:159, compare.ts:750, neo4j.ts:275 (edges:), generate.ts:873, generate.ts:988 (edgeCount:), benchmark.ts:124 (edges:). Only serve.ts:592 says Facts: — corrected in #680 because a review happened to flag that single line.

Today all fifteen are harmless because facts equal pairs. Under multiplicity each becomes a fact count wearing a topology label. Several are machine-readable payload fields, and benchmark.ts:124 feeds benchmark receipts, so this is an output-differential and receipt-regeneration question, not a rename.

Other counts: numberOfEndpointPairs() 6 callers, uniqueNeighborDegree() 37 callers (topology, unique by construction, safe), numberOfEdges() and degree() 0 callers.

Plural-API call sites on this base: factsBetween 9, relationsBetween 10, factEntries 31, endpointEntries 7. Four accumulation sites, all non-additive selections (Math.max or lexicographic).

5. Artifact and old-reader design — solved, and better than expected

v0.32.1 is a git tag in this repository (60266f238a838d73303c20a1e8894ba47d1444d7). The exact released loader is recoverable offline with git show v0.32.1:src/runtime/serve.ts — no vendored tarball, no transcribed approximation, provenance pinned by tag SHA. That answers the fixture question this issue flagged as hardest.

Both v0.32.1 read paths were traced:

• loadGraph() (line 208): catch (SyntaxError) → throw "graph.json is corrupted…" — rejects loudly.
• readGraphArtifactRecord() (line 120): try { JSON.parse } catch { return {} } — swallows into an empty record. This looked exactly like the silent-partial-success hole the issue warns about, but its only caller, semanticAnomaliesSummary() at line 604, falls straight through to loadGraph() at line 610 when the record is empty.

Conclusion: v0.32.1 rejects a v2 artifact and the tombstone on every reachable path. The magic header is sufficient.

Note for the tombstone: generate in a linked worktree resolves output to the primary checkout's .git/madar/worktrees/<hash>/out/, not the worktree's own out/. The tombstone must land where resolution actually points.

6–12. Remaining items

Type/module ownership: new focused modules for canonical JSON, identity hashing, the discriminator registry, and the fact/occurrence model; src/contracts/graph.ts becomes the multigraph store; src/contracts/types.ts gains the fact/occurrence types.

N>1 consumer test matrix: every plural consumer plus all 15 count-API callers, since none can be exercised at N > 1 today.

Performance plan: self-graph at the base SHA, same command, Node, lockfile and cache condition. Baseline recorded: wall 403.34 s · peak RSS 841.5 MB · artifact 20.30 MB · 12,674 nodes · 17,865 links · 17,865 endpoint pairs · 5,719 communities. Any material dimension above 2× raises a human gate rather than being absorbed.

Staged commits: identity/registry → storage/indexes → artifact v2 + compatibility → integration/outputs. Not squashed.

Rollback: source regeneration with the prior binary. Never down-convert v2 to v1 while claiming equivalence.

---

Unresolved — these block Stage 1

A. Fact identity is unstable under code movement, today

This issue requires: "Moving an evidence location must not change fact identity." Fact identity hashes source and target, which are node IDs. Several route node IDs embed the line number:

• express.ts:85 — routeNodeId(filePath, ownerName, method, path, line) → _makeId(…, String(line))
• react-router.ts:627 — _makeId(context.filePath, 'route', fullPath, String(line))
• go-cross-file.ts:654 — includes absoluteLineNumber

So moving a route registration down a line changes the endpoint ID, which changes the fact ID, even with source ranges correctly excluded from the discriminator. Excluding ranges from the discriminator does not save this, because the instability enters through the endpoints.

Options: (1) accept and document the limitation for route relations in v1 of the registry; (2) change route node IDs to exclude line numbers — a node-identity change touching the artifact, caches and every consumer, well beyond PR B; (3) something else.

B. Occurrence multiplicity is destroyed upstream of storage

This issue requires "same fact at different locations → one fact, separate occurrences" and "different call/registration sites remain separate occurrences." Producers already collapse those before storage sees them:

• extract/core.ts:341-347 — addUniqueEdge keys on `${edge.source}|${edge.target}|${edge.relation}`, location ignored
• extract/call-resolution.ts:51 — endpoint-only seenPairs
• spi/build.ts:952 — SPI calls deduplicated by caller/callee before projection
• spi/framework-nestjs.ts:109 — Nest token bindings are explicitly last-write-wins, so conflicting provider bindings vanish before injects edges exist

Multigraph storage cannot recover occurrences that never reach it. PR B can be storage-correct while the end-to-end occurrence requirements remain unmet on real extraction, demonstrable only with synthetic input.

Options: (1) PR B is storage-only and the producer collapse is tracked as an explicit follow-up, with the occurrence acceptance criteria scoped to the storage boundary; (2) producer changes come into PR B, enlarging it beyond the stated scope; (3) something else.

Also noted, lower severity: SPI creates #<index> overload symbol IDs at spi/build.ts:421, but projection rebuilds node IDs from the unsuffixed name at projector.ts:420, so overload identity is lost before storage.

---

Refs #657. #655 remains open for human independence.

[mohanagy]

Stage 0 architecture decisions — implementation may resume

The Stage 0 hold is resolved. The historical Stage 0 comment stands unedited; this records the maintainer decisions and the inventory they required.

Decision A — stable fact identity is not waived

The option of accepting and merely documenting line-derived fact identity is rejected. The invariant stands:

Moving only an evidence location must not change semantic fact identity when the semantic endpoints and behaviour are unchanged.

A line number is evidence location, not route semantics. Route-like semantic node IDs must derive only from available semantic fields — repository-relative file identity, owner/router/controller scope, normalized method, normalized route path, registration kind — using the exact fields each adapter already supplies. Nothing is invented. Line and range remain on node evidence/attributes and on EvidenceOccurrence ranges, and must not enter semantic route-node identity, SemanticFactId, or the discriminator unless behaviourally meaningful.

Duplicate registrations sharing the same stable route identity, discriminator and behaviour become one route node, one fact, multiple occurrences. Behaviourally different registrations stay separate facts through endpoints or the registered discriminator. Line number is never used merely to avoid a collision.

Endpoint-identity inventory

Required before editing. Twelve constructors embed location entropy. Verified at ee2115a2.

Constructor	Node kind	Location component	Semantic entity or evidence site	Fact endpoint	Decision
frameworks/express.ts:86 routeNodeId	Express route	String(line)	semantic	yes	correct
frameworks/nest.ts:326 routeNodeId	Nest route	String(line)	semantic	yes	correct — same class, policy applies directly
frameworks/react-router.ts:627	React Router route	String(line)	semantic	yes	correct
extract/go-cross-file.ts:654	Go net/http route	absoluteLineNumber	semantic	yes	correct
extract/go-cross-file.ts:702	Go framework route	absoluteLineNumber	semantic	yes	correct
extract/go-cross-file.ts:596	chi router group	absoluteLineNumber	semantic registration entity	yes	correct — same class
frameworks/express.ts:541	anonymous inline handler	String(lineOf(...))	evidence site — anonymous AST entity	yes	leave — see limitation
frameworks/express.ts:1167	anonymous inline handler	String(lineOf(...))	evidence site	yes	leave — see limitation
extract.ts:269 sectionNodeId	document section	String(line)	evidence site; line disambiguates same-label sections	no	leave — not a route/registration class
extract/non-code.ts:2595	document section	String(line)	as above	no	leave
extract/python-rationale.ts:117	rationale	String(line)	a rationale is its location (docstring/comment at a line)	no	leave
extract.ts:706, non-code.ts:3080	bibliography reference	entry.rawIndex	semantic ordinal (reference [1] vs [2]), not a source position	no	leave

Six constructors corrected — the three named plus three of the same class. Anonymous/local AST node identity is not redesigned, per the scope boundary.

Bounded limitation, disclosed rather than hidden

express.ts:541 and express.ts:1167 identify anonymous inline handlers, where functionName may itself be inline ${relation} ${routeLabel}. For a genuinely anonymous arrow function, the line is the only thing distinguishing two otherwise identical handlers on the same route, and these IDs are used as targetId for middleware and handles_route.

So after this correction: the route node's identity is stable under movement, and so is the fact identity of relations whose endpoints are both named entities. A fact whose endpoint is an anonymous inline handler remains movement-sensitive. That is bounded to Express anonymous handlers, it is a consequence of not redesigning anonymous AST identity, and it will be stated in the PR rather than left for a reader to discover.

Decision B — #657 owns the storage boundary

The Stage 0 finding is valid: addUniqueEdge (location-blind), legacy seenPairs, SPI pre-projection dedupe, Nest last-write-wins bindings, and SPI overload projection loss all destroy occurrence distinctions upstream. Storage cannot recover what was never admitted.

#657 therefore proves exactly this and no more:

Every valid fact and occurrence admitted to the semantic-graph storage boundary survives or follows the documented exact-duplicate/conflict policy.

It does not claim every raw extractor or SPI emission reaches storage. The storage-only receipt remains mandatory and unchanged. Occurrence criteria are proven by exercising the real storage insertion/builder API with candidates constructed at that boundary — not by hand-writing a final artifact, and not represented as end-to-end extractor proof.

The upstream work is now tracked openly as #703 — [P0] Preserve evidence occurrences before the semantic-graph storage boundary, which lists every confirmed collapse site. It does not block #657, #658 or #659; it blocks end-to-end occurrence-completeness claims and the occurrence cells in #661. It is a known limitation, not hidden unfinished work.

Decision C — count semantics must be explicit

The 14-of-15 edge* labelling is not treated as automatically wrong. In a semantic multigraph a fact may legitimately be exposed as an edge, and a historical field that described serialized relationship records may remain a compatibility alias for semantic fact count. What is not allowed is ambiguity.

Before Stage 2, every one of the 15 callers gets a row stating file/symbol, existing label, compatibility surface, intended count (fact / endpoint-pair / occurrence), additive fields, and migration/test. Topology results use endpoint-pair count. Machine-readable fields get documented, test-pinned meaning. Where the schema allows, fact_count, endpoint_pair_count and occurrence_count are added additively. Benchmark and receipt outputs preserve comparison meaning — no historical field silently changes from relationships to pairs. Human-facing text prefers Facts / Endpoint pairs / Occurrences over an unexplained "Edges". Any field that cannot be classified without a public compatibility decision is a stop condition, and no snapshot is blanket-renamed.

Status

Stage 0 is unblocked, subject to the inventory above. All 19 acceptance criteria remain binding, including the five carry-forward multiplicity gates. No PR C or PR D scope is authorized. Implementation resumes at Stage 1 in roadmap/657-semantic-multigraph-v2, base ee2115a2.

Refs #657. Follow-up: #703. #655 remains open for human independence.