feat(context_for_task): say when a seed's callers are complete (per-call resolver outcome, schema 8)

[golimpio]

What

context_for_task now says when a seed's caller list is complete, and when it isn't, it names the exact calls left to check.

Agents re-grep what the pack already covered: in our directed-use study, 22 of 38 post-pack searches named pack identifiers, 16 of them in one run looking for call sites of its own seeds. A ranked "N callers, more may exist" never lets an agent stop. The index records every call expression, so it can tell which calls of a name the resolver left open.

• Schema 8: topology_call_sites.outcome records the resolver's bucket for every site, written by each full or scoped pass. There is also an index on (language, callee). The index rebuilds once.

• Store.OpenCallSites(name): the calls of a name that no edge accounts for exactly:

  • a receiver whose type no declaration states;
  • an unmatched qualified name;
  • a bare name;
  • a block-scoped local, since the extractor's local marker is function-wide;
  • a same-file call when the file declares the name twice;
  • a top-level call;
  • an unread call.

  Each carries whether its file dot-imports a package.

• Census line for each Go function or method seed, and each top declaration of a file seed, which is what agents usually pass. The counts come from the index, not the walk:

  • callers of X: complete (every recorded call of X resolves): N in the index, M listed here, or
  • N in the index, M listed here; K unresolved call(s) of X may also be it: a.go:12 (receiver), … Check these, not the whole tree.

  The calls-only caveat (function values and interface calls are not calls of X) is stated once.

• Two Go extractor fixes found by the oracle check:

  • a generic call F[T](x) had no same-file edge;
  • a name declared twice in one file got an edge, at confidence 1.0, to whichever was declared last. It now gets none and stays open.

Verification

• Oracle check, free and run privately. For every Go callable in a file go/packages loads, the census claim was compared with the type checker's static callers:

  codebase	callables	"complete"	wrong "complete"	open
  plumb (7368d41 tree)	9,184	7,231 (79%)	0	1,953
  golang.org/x/tools	4,475	3,062 (68%)	0	1,413

  These are the numbers at the final head (cf1a166). The first plumb re-run showed 1 wrong claim, but that was a stale oracle: a private harness file in the checkout had changed after the oracle pairs were dumped. A fresh dump gives 0.

  The first pass found 1 wrong claim on plumb and 10 on x/tools: generic calls, dot imports, block-scoped shadows, same-file name collisions. Each is fixed and pinned by a test, and both codebases were re-run to 0.

• Tests:

  • TestOpenCallSites covers each open kind, plus controls: a resolved call and a once-declared same-file call.
  • TestCouldCall is a 17-row table.
  • The file-seed census runs end to end.
  • The extractor tests cover generic and ambiguous calls, with a same-file control.
  • The existing caller-wording tests moved to the census contract.
  • The same-package fixture that simulates a pre-local-tier index now also records those calls as open, as that build did.

• Mutation: 24 guard mutants across four runs, all killed. Two first-round survivors (the truncated-hub guard and same-line dedup) led to the callerCounts and noteOpen helpers and their tests. Two mutants that didn't compile were rewritten and re-run.

• verify-full in a container (PLAN-526 script, non-root, history bundle): exit 0 at cf1a166, with no failures, 60 ok packages and at most one daemon. The main control (7368d41) is also exit 0, so the fail sets are equal.

• CI: 9/9 on cf1a166.

Review (scarlet-badger, independent): CONTINUE

Round 1 asked for fixes, and all were made with tests:

• B1: open calls outside within are counted, never named, and "complete" is not said while one exists.
• S1: no "complete" while the index is not fresh, or while any Go file failed to extract.
• Q1: a call left "resolved" whose edge is gone (its target deleted or renamed, the caller unchanged) counts as open ("stale"). Recursion is excluded.
• Q2: an external call whose qualifier names the seed's package clause counts as open.

Known residuals (recorded, rare)

• A Go file over max_file_size is never recorded by the indexer, so only the caveat ("in the files the index holds") covers its calls.
• The stale check works by name. If a function calls a.X and b.X, and a.X is deleted, the remaining b.X edge still accounts for the dangling site.
• An import alias whose path fails to map (import foo ".../p"; foo.Seed()) is not treated as open: the qualifier is compared with the package clause, not the import path.
• "building" also suppresses "complete". This is deliberately conservative during an edit loop.

Contract change

PLAN-462 forbade any "no callers" wording because the syntactic graph could not back it. The census now backs it when it is true, so complete … 0 in the index is allowed. It appears only when no recorded call of the name is open.

🤖 Generated with Claude Code

[atlas-from-plumb]

Approved under the owner's standing delegation. The bar is met on head 0b920e3:

• Independent review (scarlet-badger): round 1 FIX (B1 scope, S1 unread files, Q1 stale outcomes, Q2 external), all fixed with tests; round 2 CONTINUE.
• CI 9/9 on 0b920e3.
• make verify-full-container: exit 0, 61 ok, no FAIL, at most 1 daemon, Revision 0b920e3. Main control at 7368d41 was also green.
• Mutation: 24/24 guard mutants killed.
• Oracle check against go/packages: 0 wrong 'complete' claims, out of 7,231 on plumb and 3,062 on x/tools.
• Rebased over #643: range-diff all '='; CHANGELOG +16/0.