From 089d5682369fbf5c8eb83ea7778631bed17b6422 Mon Sep 17 00:00:00 2001
From: Ubuntu <ubuntu@localhost.localdomain>
Date: Sat, 1 Aug 2026 08:23:35 +0800
Subject: [PATCH] docs(scope-resolution): document
 GITNEXUS_MAX_PROPERTY_DISPATCH_FANOUT in README and .env.example

Add a dedicated troubleshooting subsection and .env.example entry for the
GITNEXUS_MAX_PROPERTY_DISPATCH_FANOUT environment variable, matching the
format used by the sibling GITNEXUS_MAX_CALLABLE_VALUE_TARGETS knob.

Closes maintainer request: "Could you please document this in the readme
plus the .env.example?"
---
 gitnexus/.env.example |  7 +++++++
 gitnexus/README.md    | 23 +++++++++++++++++++++++
 2 files changed, 30 insertions(+)

diff --git a/gitnexus/.env.example b/gitnexus/.env.example
index 8b90c7ae73..b82643c17f 100644
--- a/gitnexus/.env.example
+++ b/gitnexus/.env.example
@@ -23,3 +23,10 @@
 # Personal Access Token with Code (Read) scope for cloning private repos.
 # Used for both self-hosted and cloud (dev.azure.com) Azure DevOps.
 # AZURE_DEVOPS_PAT=your-pat-here
+
+# Scope-resolution property-key dispatch cap (default 32). Per-property-key
+# registration cap in the property-dispatch scope-resolution pass. Raise for
+# repos whose provider/hook tables lose CALLS coverage on a legitimate key.
+# Positive integer only — non-integer or < 1 values fall back to 32.
+# See README § "Scope-resolution property-key dispatch cap".
+# GITNEXUS_MAX_PROPERTY_DISPATCH_FANOUT=32
diff --git a/gitnexus/README.md b/gitnexus/README.md
index 5c4c7b72a0..f097baa5b6 100644
--- a/gitnexus/README.md
+++ b/gitnexus/README.md
@@ -662,6 +662,29 @@ After scope resolution, analyze prunes inert block-local value symbols (a functi
 
 Programmatic callers can pass `keepLocalValueSymbols: true` in `PipelineOptions` instead of setting the env var.
 
+### Scope-resolution property-key dispatch cap
+
+During scope resolution GitNexus synthesizes CALLS edges through *property-key
+dispatch* — call sites like `hooks.emitScopeCaptures()` where a property key is
+registered by multiple definitions across the codebase. To keep this fan-in
+bounded, each property key is capped at **32 registrations**: a key registered
+by more than 32 distinct functions is skipped entirely (no CALLS are synthesized
+through it), and the dropped key names are surfaced in the analyze log for
+operator visibility. The cap is calibrated at 2× this repo's own provider table
+(16 legitimate registrations, one per language provider).
+
+| Variable                                | Default | Effect                                                                                                                                                                                                                                                                                                                |
+| --------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `GITNEXUS_MAX_PROPERTY_DISPATCH_FANOUT` | `32`    | Per-property-key registration cap in the property-dispatch scope-resolution pass. Set to a positive integer to raise it for repositories whose provider/hook tables exceed the default and lose CALLS coverage on a legitimate key; non-integer or `< 1` values fall back to `32`. Lowering it tightens the overflow budget. |
+
+```bash
+# A property key registered by 40 functions overflows the default 32 and drops
+# all CALLS through it — raise the cap for that repo and rebuild so scope
+# resolution reruns.
+export GITNEXUS_MAX_PROPERTY_DISPATCH_FANOUT=64
+npx gitnexus analyze --force
+```
+
 ### Hook augmentation and skip diagnostics
 
 The Claude Code / Antigravity hooks keep their **stderr** silent on normal skip