Markdown for LLMs

Local and shared vocabulary

The source Markdown for this article. Copy it into your assistant or download it as a text file.

# Local and shared vocabulary

Not every declaration is meant to travel. This page explains the two
scopes vocabulary lives in — local to one package, or shared across many
through versioned dictionary packages — and how to keep the boundary clean.

Each claim carries a status in words with a letter mark; the full legend
is on the [topic index](/corpus/#how-this-topic-marks-confidence).

## Local vocabulary

Declarations marked `internal` stay inside their package — **available
in the public release** (S). They can
be renamed, reshaped, or removed without coordinating with anyone, because
no other package can reference them — provided the promised public
behaviour stays put. Prefer `internal` for modeling
details that only your own rules need.

That freedom covers names and shapes, not answers. Renaming an
internal declaration cannot move any other package, because no other
package can name it — but changing what an internal criterion accepts
moves every public answer downstream of it. In the lab fixtures, the
rule that completes registration is local to its package, yet three
fee rules and one appeal rule in other packages read the public
`registered` predicate it feeds: tighten the local criterion and
parcels stop being registered, so fee answers disappear, with no
signature touched at all. Internal means unreferenceable from
outside, never unobservable through public predicates.

Within a package, files declare their intra-package dependencies in a
single `use self::{…}` block per file (**S**). In the explicit authoring
mode the block lists exactly what the file uses from its own package, and
the `law fix imports` command regenerates these blocks from the
resolution journal.
Run that command only for packages you own; never across the whole tree.

## Shared dictionaries

When several packages need the same concepts — countries, currencies,
courts, kinship — the corpus ships them as ordinary versioned packages
whose names start with `vocab.` (**S**). Examples live in the corpus
today: `vocab.geo` (regions, stations, points with trilingual labels),
`vocab.currency`, `vocab.country`, `vocab.courts`, `vocab.kinship`, and
more than two dozen others.

Dictionary packages follow strict rules (**S**, held by review):

- Types and constants only: no rules and no source blocks inside.
- No jurisdiction of their own: the importing act supplies the context.
- Versioned like any package: consumers pin an exact version, so the
  meaning they tested against is the meaning they keep.

Importing a dictionary is the same mechanism as importing any package:
declare the dependency in the manifest, pin it in the lockfile, and the
locked world links it by name.

## Choosing a scope

| Situation | Scope |
|---|---|
| Concept used by one act alone | Local `internal` declaration |
| Concept reused across acts | Shared `vocab.*` dictionary package |
| Same meaning, different display per language | Shared declaration; vary labels and overlays — see [languages](/corpus/vocabulary/languages/) |
| Genuinely different meanings | Separate local declarations; never one shared node with two minds |
| Unsure whether two wordings mean the same | Keep both local; merge only through an explicit mapping later — see [bridges](/corpus/vocabulary/bridges/) |
| Stable cross-act identity | Dictionary constant with explicit identity |

The companion [lab material](/corpus/lab/) follows this split: package
`labparcels.iface` is the shared interface every other fixture imports,
while each consumer keeps its own rules local.

## Where to go next

- The companion page on [modeling vocabulary](/corpus/vocabulary/modeling/) introduces the four
  declaration forms.
- The companion page on [bridges](/corpus/vocabulary/bridges/) covers mappings between vocabularies.
- The companion page on [migrations](/corpus/vocabulary/migrations/) covers how shared dictionaries evolve.
- For placing metadata in the manifest, see
  [Place metadata in the manifest](/recipes/n-package/package-metadata/).
- For construct-level detail, see [the Vocabulary construct reference](/constructs/vocabulary/).