[jgrodziski]

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

explain no longer asks a model to define function words: or, of, by, with, all, is. This is fix (e) from the PetClinic findings.

Why

The PetClinic run (#40) paid for 10 of its 301 word entries on grammar, plus one module glossary entry:

word	identifier	the model's sense
by	findById, findByLastNameStartingWith	"lookup criterion", "query criterion"
with	findByLastNameStartingWith, loadPetWithVisit	"matching relation", "association" (ambiguous)
is	isDuplicatePetNameViolation	"boolean predicate"
of	getNrOfSpecialties	"identifier connector"
all	findAll ×2	"complete collection", "complete result scope" (ambiguous)
or	VIEWS_OWNER_CREATE_OR_UPDATE_FORM, VIEWS_PETS_CREATE_OR_UPDATE_FORM	"alternative form purpose" (ambiguous)

The owner module then reconciled or into a glossary entry, and --polysemy listed it. At ~120 completion tokens per word (#40), the cost is small. The noise in the glossary and the polysemy reader is the real problem.

The change

• FUNCTION_WORDS is a new export of define.ts in @codegraph/vocabulary, with 60 words:
  • articles and determiners, pronouns, conjunctions, prepositions, auxiliaries and modals, and not.
• definitionSpeller and rankedWords leave these words out whatever class they get: or, by and is are on the technical list, all and the are domain.
  • The module glossary's candidates are its types' asked words, so it loses them too. rankedWords is filtered as well, so the two never disagree.
• Nothing else moves: the cloud, the four classes, --class, drift and the artifact are unchanged. Every word is still counted and tagged (§20.1). Only what layer 2 asks changes.

Worth a look in review

• A list, not a fifth class. A function class would have changed:

  • the vocabulary artifact;
  • the tab's class toggles, which are literals restated in navigator-ui;
  • --class and the carriers route;

  all for a question only explain asks. The cost of that choice: in the cloud, the and all stay domain and or stays technical.

• What is deliberately not on the list: words that name a thing as often as they join two:

  • no (a number: orderNo);
  • may and will;
  • phrasal-verb particles (out of checkOut, up of signUp);
  • prepositions of time and order (before, after, between).

  The list is English only: du in getNomDuClient is still asked. It is contestable, like DEFAULT_TECHNICAL.

• No option to override it. explain takes no technical list either. A correction is a code change, and the fingerprint shows what it touches.

• ⚠ What it costs a store already paid for. The asked words are part of the fingerprint. A unit whose names spell a function word goes stale, and through the Merkle chain so does every unit that depends on it. On PetClinic (a copy of the paid store, --dry-run):

  • before: all 106 calls reused;
  • after: 53 calls to redo (~121 k prompt and ~56 k completion tokens, about $0.08 at the run's prices);
  • only 9 of those units are stale directly: 7 operations, plus 2 controllers with an …_OR_… view field. The other 44 are stale through their dependencies.

  Nothing is lost before the next run. The old records stay, and the readers show their or entries until those are replaced.

• The fingerprint comment was wrong about this. It said a lexicon correction "re-explains exactly the units whose words it changed". It now says the change also reaches the units' dependents (its own commit).

  • Whether a words-only change should cascade is a design question. The Merkle chain exists because a dependent quotes its dependency's summary, and a re-explained dependency writes a new one.
  • Stopping the cascade would mean hashing dependencies without their words. That changes every dependent's fingerprint once, so it is not done here.

Docs

• docs/insights.md and the side-car reference say function words are not asked.
• The Java fixture's --estimate and --dry-run are reprinted on four website pages: 114 474 prompt and 52 415 completion tokens, $0.0429 (was 114 483 / 52 900 / $0.0432).
  • This includes a miss from fix(insights): the estimate's measured word cost (M19c) #40: three --dry-run blocks (reference explain, how-to Estimate the cost, the explain tutorial) still showed the pre-measurement ~41670 completion tokens.
• PLAN §20.3: an "As built — function words" note, and a one-line pointer in layer 2's design text.

Verification

• Red first. The speller and glossary tests failed against the base (["shop", "day", "of", "the"]), then passed.
• Mutant. Restoring the class-only filter in rankedWords alone fails "lists no function word, so a glossary is not cut on one".
• 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: vocabulary 348 (+3), cli 1,037, insights 158 (+1 skipped), core 544, analyzer 614, viz 143, navigator-ui 114, 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. The stale count above comes from --dry-run on a copy of the store, with the base branch's speller as control (0 stale). The paid store in ~/spring-petclinic was not opened by this branch.

Still owed for M19c:

• (c) don't ask a module to reconcile words no type defined;
• (d) count a word as polysemous only with at least two distinct senses;
• 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	bfe8082	Commit Preview URL Branch Preview URL	Nov 03 2026, 11:31 AM