docs(schema): define call-edge weight semantics or separate occurrences from provider evidence

[rahlk]

Problem

TSCallEdge.weight has no documented semantic contract. Within a provider it aggregates repeated (source,target) discoveries, while the union provider also sums weights across analyzers for the same edge. Therefore it is neither a unique source callsite count nor simply a provider-confidence count.

provenance already records provider agreement, but consumers cannot tell how much of weight came from repeated callsites versus duplicate TSC/Jelly evidence.

Reproduction

In OWASP Juice Shop 6244c59:

• app.ts contains one call to server.start();
• the merged edge has weight: 2 and provenance: ["tsc", "jelly"].

The behavior is intentional in code and tests:

• src/semantic_analysis/provider.ts sums ex.weight += e.weight while unioning provenance;
• test/union-provider.test.ts explicitly expects weights 2 and 3 to merge as 5.

But README.md and src/schema/schema.ts list weight without explaining whether downstream graph algorithms should interpret 2 as two calls, two providers, stronger confidence, or something else.

Expected behavior

The schema must give consumers an unambiguous quantity. Occurrence multiplicity and provider agreement are different dimensions and should not be silently conflated.

Acceptance criteria

Choose and document one contract:

1. Keep weight as total provider evidence and explicitly document that it is not callsite frequency; or
2. Make weight a deduplicated source-callsite occurrence count and retain provider agreement solely in provenance; or
3. Replace/supplement it with explicit fields such as occurrence_count and evidence_count (with source locations if available).

Then:

• document the contract in the JSON schema/reference and README;
• add examples for one call found by two providers and two callsites found by one provider;
• ensure JSON and Neo4j expose the same semantics;
• coordinate any schema change with the sibling analyzers and v2 contract epic epic: cldk-forge compliance — contract-correctness cluster #26.