# Bridges between vocabularies

No vocabulary covers everything. This page maps the five ways the corpus
connects vocabularies to each other and to outside knowledge — from
declared edition correspondence to hand-written mapping packages — with
a note on how mature each one is.

No commands are needed to follow this page. 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).

## Edition alignment

An `align` block declares correspondence between two editions of a
source, with a relation, a status, and a reviewer. Four maturity
facts, kept in sync with the alignment notes:

- Declaration support: the grammar compiles in real packages (**S**).
- Reading tools: no structural query returns align rows — the links
  question covers produces, reads, anchored, alias, and subtype only,
  so do not build tooling that assumes align rows are queryable (**S**).
- Adoption: broad — over two thousand blocks across dozens of source
  files observed in the corpus (**S**).
- Semantic effect: none — the block stays document metadata and never
  becomes rule content (**S**).

## Hand-written mapping packages

Where alignment exists today, it is an ordinary package of hand-written
mapping rules, not generated output — a **team convention** (T). The precedent maps shared
dictionary concepts — places, currencies, countries, courts — to
external knowledge-base records. Prefer this pattern when the mapping
needs human judgment: it is versioned, pinned, and reviewed like any
other package.

## Concept catalog

A derived full-text index over compiled packages helps authors find
candidate concepts before they coin new ones; it **requires a source
checkout** (I). The catalog never
merges semantics — it suggests, and the author still writes an explicit
import or mapping. Its command surface offers build, search, candidates,
and show operations over the compiled snapshot.

## Narrow alignment profiles

A dispatcher runs bespoke, hard-registered bridge modules for narrow
pairs: physical quantities against a units knowledge base, and order
theory against two proof assistants — **experimental** (X). Each bridge is custom code
for its pair, with its own policy and report schemas. This is the right
shape when two formal systems need a precise, verified seam — and the
wrong shape for anything broad, where the bespoke cost never pays off.

"Verified" here has a hard boundary: the check runs under a declared
interpretation, and semantic equivalence is not proved — the same line
the import report format draws with
`declared_mapping_assumption` and `semantic_equivalence_proved:
false` (see [the alignment
boundary](/corpus/import/#the-alignment-boundary-in-the-report-format)).

## Import mapping

External knowledge arrives through versioned import recipes: a recipe
pins its inputs and its mapping, and the ingest surface builds or
checks it (`law ingest check <recipe.json>`). This **requires a source
checkout** (I): `ingest` is absent from the public composition; see
[Import](/corpus/import/).
Mapping profiles
tune how much of the external graph becomes rules versus plain
retrievable knowledge. What does not fit stays out loudly: profile
reports carry a per-decision status and only accepted entries
proceed, and a mismatched recipe is refused with an error rather than
coerced silently (**I**).

A newer source-to-facts mapping contract exists as a schema with no
confirmed engine surface yet — **schema only** (O).

## Which bridge to reach for

- Same concept needed by two acts → share one dictionary import; no
  bridge at all. Counterexample: mapping between two local copies of
  "country" instead of importing the shared dictionary doubles
  maintenance and silently forks meaning.
- Correspondence between two existing vocabularies → a hand-written
  mapping package (**T**). Counterexample: a type alias cannot join
  two dictionaries — it only renames one type.
- Correspondence between two editions of one source → an `align`
  block. Counterexample: two acts in different languages are not two
  editions of one source; aligning them asserts a correspondence the
  sources never made.
- Candidate discovery before coining anything → the concept catalog
  (**I**). Counterexample: a catalog hit is a pointer, never an
  identity claim — it never licenses skipping the explicit import.

## What bridges are not

Some subject-matter packages reuse the word "bridge" in their names for
ordinary domain rules — tolling rules, identity rules, forensic
linkage. Those are regular packages, not mapping mechanisms, and this
page makes no claims about them.

## Where to go next

- The companion page on [local and shared vocabulary](/corpus/vocabulary/local-and-shared/) covers the
  dictionaries that mappings usually target.
- The companion page on the [audit surface](/corpus/vocabulary/audit/) shows how to query who reads
  what across packages.
- For construct-level detail, see [the Vocabulary construct reference](/constructs/vocabulary/).
- For structural queries over links, see [LawQL](/lawql/).