docs(spec): sharded, two-wave L4 for #112 step 4

[rahlk]

Spec for #112 Step 4, extended with a second wave that recovers what plain sharding drops. Committed as provenance; no code.

The argument, in three measurements

Why restructuring cannot fix whole-vscode L4. On vscode/src at -a 4, RSS is already 21.33 GB when the interprocedural phase begins, and that phase's entire retained state is 0.48 GB (datas 0.34, ddg 0.09, summaries 0.05). L4 is the cheapest phase in the run by retained bytes. The rest is tsc's own parse/bind/check state. Six restructurings were measured and none moved the ceiling, because they were all targeting fractions of a gigabyte against a ~10 GB gap.

Why sharding by program works. can://<lang>/<app>/<fileKey>/<sig> embeds no program identity, so with --input and --app-name pinned the same file yields a byte-identical id in any shard. ownerProgram assigns each file to exactly one program, so modules are disjoint and the union is concatenation. Neo4j already MERGEs on the id, so it unions shards with no new code. Peak becomes the largest program — measured at 28.75 GB for vscode's src.

What plain sharding costs, and why wave 2 exists. Measured on the whole-vscode -a 3 output by replicating ownerProgram's rule over the repo's 99 tsconfig scope dirs: 97.4% of in-project call edges are same-program, 2.6% (28,345) cross. Wave 2 recovers those — and it needs no tsc state at all, only ~1 GB of graph IR, which is why it is affordable.

What the spec commits to

• Wave 1 per program; wave 2 as a pure-IR cross-shard stitch
• Acceptance is an equivalence property: wave1 + wave2 must be byte-identical to a single-process L4 on any repo where that completes (vscode/src, the fixture apps, superset)
• A proposed CLI surface (--program, --emit-ir, --stitch) and a 4-unit decomposition, both flagged as needing sign-off

Caveats it states plainly

• The margin is thin: largest shard 28.75 GB against a wall observed at 28.0–31.7 GB, and program granularity is the floor — sharding by input root instead would change every fileKey and break the union
• L4's loss under wave 1 alone exceeds 2.6%: that figure counts edges, and summaries propagate transitively, so 2.6% is the floor on the damage, not the estimate
• Cross-program edges run both directions (copilot → src 5,420, src → copilot 2,416), so real SCCs span programs — wave 2 must redo the fixpoint, not just compose callee summaries into callers
• It cannot be validated against a whole-vscode L4 baseline, because that baseline is exactly what does not exist

Open

The decomposition and CLI surface are proposals. Units are listed to be filed just-in-time as each is picked up, not up front.