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.

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
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
Stable cross-act identity	Dictionary constant with explicit identity

The companion lab material 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 introduces the four declaration forms.
• The companion page on bridges covers mappings between vocabularies.
• The companion page on migrations covers how shared dictionaries evolve.
• For placing metadata in the manifest, see Place metadata in the manifest.
• For construct-level detail, see the Vocabulary construct reference.