[jgrodziski]

Ninth step of milestone M19c in PLAN.md §20 (word cloud / glossary, #6). Stacked on #43 (itself on #42, #40, #39, #38, #37, #36 and #35): this PR's diff is the four commits after #43.

A module's polysemous flag now counts only when the senses it lists are at least two. This is fix (d) from the PetClinic findings.

Why

A module reconciles what its types said of a word. When its types disagree, it sets polysemous and lists each type with its sense. On PetClinic, 2 of the run's 16 flags (over 52 glossary entries) listed one sense only:

word	module	listed senses
owners	owner	OwnerController, PetController, VisitController: all "owner repository dependency"
or	owner	OwnerController, PetController: both "alternative form purpose"

--polysemy listed both words. --glossary and --word printed a polysemous: cell for them. The Vocabulary tab and the Navigate panel said "its types disagree", with nothing to disagree on.

The change

• typesDisagree(entry) in @codegraph/insights glossary.ts: the entry is flagged polysemous and lists at least two distinct senses, case and spacing aside. That is the comparison --polysemy already made across modules.
• Every reader asks it:
  • --polysemy, which lists a word when a module's flag holds or when two modules define it differently;
  • the polysemous: cell of --word and --glossary;
  • the Navigate panel's glossary line;
  • the Vocabulary tab's "its types disagree".
• The page restates the rule. navigator-ui imports nothing of @codegraph/insights, not even types. A test runs both versions over the same cases and requires the same answers, the way the answer kinds are pinned. A sense the page cannot read counts as none, never a throw.
• A flag that doesn't hold adds no sense to a word's count in --polysemy. Its one sense rewords the entry's own, so counting it would inflate the ordering.

Worth a look in review

• Read, not rewritten.
  • The record keeps polysemous: true as the model wrote it. The store holds what was paid for, and the side-car's decode → import → export stays the identity.
  • Clearing the flag on receipt would still leave the records already paid for, so every reader would need the rule anyway.
• Both the flag and the senses are needed.
  • The flag is the model's judgement of meaning; the senses are its evidence.
  • Two differently worded senses the model did not flag ("a request", "a customer's request") stay one sense. The model judged them the same, and a reader cannot second-guess that.
• Lexical, not semantic.
  • In the owner module, pet keeps its flag over four wordings of "animal under care" ("animal subject", "animal being validated"…).
  • Judging meaning would take a model call, and the readers make none. The rule removes only flags whose own senses don't support them.
• The prompt is unchanged.
  • It already says to flag a word "when the types disagree on it".
  • Rewording it means a new PROMPT_VERSION, which every fingerprint includes: all 106 PetClinic calls again, for something a reader can check.
  • No fingerprint input moves, so no record goes stale.
• or is gone twice. fix(vocabulary): no definitions of function words (M19c) #42 stopped asking for it. Until PetClinic is re-run, its paid entry is still in the store, and this rule hides its flag.

Docs

• docs/insights.md, docs/cli.md (--word, --polysemy) and the side-car reference's polysemous row: a reader counts the flag only when it lists at least two senses.
• PLAN §20.3:
  • an "As built — two senses to a polysemy" note;
  • a pointer from layer 3's --polysemy.

Verification

• Red first.

  • insights: polysemyReport listed total, whose flag lists one type, and counted 3 senses for price, whose two types give one sense differing only in case and spacing. typesDisagree did not exist.
  • cli: against the base sources, --glossary printed a polysemous: cell for lines, whose two types give one sense, and --polysemy listed it.
  • navigator-ui: the panel said "Its types disagree" for a one-sense owners, and the pin test had nothing to pin.

• Mutants, each run alone with the file restored byte for byte:

  • trusting the raw flag in polysemyReport;
  • counting every listed sense;
  • dropping the flag from the rule;
  • comparing senses without normalizing them;
  • accepting a single listed sense.

  Each one fails a test.

• Not covered by a unit test: the Vocabulary tab's one-line change has no component test. A screenshot covers it instead (below).

• Gate.

  • Build: every package except the website (snap Hugo 0.168's unknown output format "llms", pnpm -r build fails on a fresh clone: unknown output format "llms" for kind "home" #23).
  • Typecheck is green and eslint is clean on the changed files.
  • ./build.sh --ts --sea passes its smoke gates ("all gates passed").

• Tests: insights 162 (+2, +1 skipped), navigator-ui 115 (+1), cli 1,037, vocabulary 348, core 544, analyzer 614, viz 143, city 94, extractor-typescript 66, scm 56, navigator 40, llm 34.

  • All green, except analyzer's scale.test.ts, which timed out under the full parallel run and passes alone (the known flake; the analyzer is untouched).

• PetClinic, on a copy of the paid store in the scratchpad (the store in ~/spring-petclinic was not opened):

  • --polysemy lists 14 words, down from 16: owners and or are gone, and every remaining word is flagged with at least two senses.
  • serve on the copy, Vocabulary tab, at 1600×1000:
    • owners shows the owner module's sense and meaning with no "its types disagree" line;
    • pets keeps it: Owner "owned pets", PetController "pet records".

Still owed for M19c:

• whether a words-only change should cascade to dependents (fix(vocabulary): no definitions of function words (M19c) #42);
• docs/vocabulary.md and the README;
• the live run on the Java fixture;
• §20.4's definition of done restated on PetClinic.

Part of #6.

🤖 Generated with Claude Code

https://claude.ai/code/session_01PKCVgyop39vhNa45r7zM8w

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	codegraph	9eb6583	Commit Preview URL Branch Preview URL	Nov 03 2026, 05:12 PM