# Vercy Thing Registry

**What this is.** The list an AI or a robot checks when it meets something and
needs to know what kind of thing it is before any deeper model exists: a road, a
house, a grasshopper, a phone charger, a ghost. The world-model catalogue at
`/models/` answers *what model does this domain need*. This registry answers the
question underneath it: *what is that, and what can be done with it*.

**Registry only.** Each entry carries identity, naming, placement on several
analytical planes, and provenance. No bundles, no layers, no content. A thing
earns a full meta-model when a task needs one; until then it is registered, and
that is enough to recognise it and to route to something that knows more.

## Two layers

The registry is built from two sources, because neither covers what the other does.

**The lexical layer** registers what English has bothered to name: the everyday
vocabulary, with a facet set derived from the lexicon's own structure. Rich per
entry, about 20,000 entries.

**The Wikidata layer** registers what a lexicon cannot hold: 173,648 kinds of
device, vehicle, machine, material, building and tool, including the ones with
no ordinary English word at all. Thinner per entry - name, placement, how many
Wikipedia languages describe it, provenance.

These two layers are not equals, and it matters which one you trust for what.

**The lexical layer is authoritative on granularity.** Its merges were checked
against the rule and hold: locust folds into grasshopper, poodle into dog.

**The Wikidata layer is authoritative on coverage.** Its merges are advisory.
Wikidata's subclass graph is a tangle rather than a taxonomy - a grasshopper is
reachable from *food* in fewer hops than from *organism* - and the signal
available there, how many Wikipedias describe a concept, measures notability
rather than ordinariness. Notability keeps rising all the way up a branch, so
the climb sometimes overshoots: in this build `grasshopper` folds into `insect`,
which is one level too coarse. The lexical layer has that pair right, which is
why it, not this one, decides granularity.

Read the Wikidata layer as an index of what exists, and the lexical layer as
the ruling on how finely to cut it. An entry that both name carries
`also_registered_as`, so the two views of the same thing resolve to each other;
6,103 entries are named by both.

## Files

| File | Use |
|------|-----|
| [`registry.jsonl`](registry.jsonl) | Lexical layer, one JSON object per line, 20,532 entries with full facets. |
| [`registry.csv`](registry.csv) | The same entries flattened, for filtering without a JSON parser. |
| [`index.json`](index.json) | Counts per plane, per domain and per facet, plus the facet vocabularies. |
| [`registry-wikidata.jsonl.gz`](registry-wikidata.jsonl.gz) | Wikidata layer, 173,648 entries, one JSON object per line, gzipped (15 MB). |
| [`registry-wikidata.csv.gz`](registry-wikidata.csv.gz) | The same entries flattened (4.7 MB). |
| [`index-wikidata.json`](index-wikidata.json) | Counts, provenance and the overlap with the lexical layer. |

## An entry

```json
{
  "registry_id": "vr.tr.grasshopper",
  "record_plane": "thing",
  "code": "grasshopper",
  "name": "grasshopper",
  "definition": "terrestrial plant-eating insect with hind legs adapted for leaping",
  "alternate_names": ["hopper", "locust", "short-horned grasshopper", "..."],
  "plane": "PHY",
  "domain": "PHY.LIV",
  "category": "Physical world and living systems",
  "lexical_class": "noun.animal",
  "facets": {
    "substance": "living", "origin": "natural", "agency": "autonomous",
    "mobility": "self-moving", "scale": "not-applicable",
    "affordances": ["observable"]
  },
  "markers": ["animal"],
  "granularity": {"level": "basic", "merged": 8, "merged_from": [{"name": "locust", "...": "..."}]},
  "parents": ["oewn-02228043-n"],
  "status": "registered",
  "source": {"dataset": "oewn:2024", "synset": "oewn-02229081-n", "license": "CC BY 4.0"}
}
```

## The analytical planes

A thing is filed on several planes at once, because different questions cut the
world differently. Filter on whichever one your task needs.

| Plane | Values |
|-------|--------|
| `plane` / `domain` | `PHY` physical world and living systems · `SOC` society, people and institutions · `INF` information and virtual systems · `ACT` activities and processes · `XCT` cross-cutting context. Second level in `index.json`. |
| `substance` | `material` `living` `social` `information` `activity` `energy` `place` `form` `mental` `abstract` |
| `origin` | `natural` `manufactured` `conceptual` |
| `agency` | `inert` `autonomous` `collective` `operable` |
| `mobility` | `fixed` `portable` `self-moving` `varies` `not-applicable` |
| `scale` | `handheld` `vehicle` `built` `geographic` `cosmic` `not-applicable` |
| `affordances` | `graspable` `traversable` `consumable` `operable` `readable` `hazardous` `observable` |

`markers` records which broad subtrees the thing belongs to (`artifact`,
`vehicle`, `building`, `weapon`, `food`, `animal`, `person`, …). The facets are
derived from those markers and from the lexical class, so a consumer that
disagrees with a facet can recompute it from the markers.

## The granularity rule

Tell a grasshopper from a caterpillar. Do not bother telling a grasshopper from
a locust unless a task asks for it.

That is the basic level of categorisation, and it has a measurable signature: of
all the ways to name a thing, the basic level is the one people actually use. So
for every concept the builder walks its ancestor chain and keeps the node whose
own name is the commonest ordinary word, subject to two guards: the name must be
a single word, and the node must not head a subtree larger than 250 (that is
what separates a category like *animal* from a thing like *dog*).

Everything finer folds into the kept entry as an alias and keeps its own
definition in `granularity.merged_from`, so nothing is lost and any split can be
reintroduced for a task that needs it.

```
locust      -> grasshopper        highway  -> road
poodle      -> dog                cottage  -> house
sedan       -> car                armchair -> seat
grasshopper -> grasshopper        caterpillar -> caterpillar
```

45,538 finer distinctions are folded into 20,532 entries this way. Look a merged
name up in `alternate_names` and you land on the entry that covers it.

## Coverage and honesty about it

20,532 entries built from the noun half of Open English WordNet 2024. That
covers the things English has bothered to name, which is a large fraction of
what a general-purpose agent meets, and it is not everything. Known gaps:

- **Products and models.** Largely closed by the Wikidata layer: smartphone,
  excavator, wind turbine, traffic light, fire hydrant and solar panel are
  registered there and were missing before. Individual commercial models are
  still out: they are instances, and this registry lists kinds.
- **Species below the basic level.** Deliberate: see the granularity rule.
- **Named individuals.** Out of scope by design: this registry lists kinds.
- **Non-English naming.** Entries carry English lemmas only so far. The
  interlingual index (`source.ili`) is recorded on every entry, which is the
  hook a multilingual pass attaches to.

## Provenance and licence

Every entry names the synset it came from. The source is Open English WordNet
2024, CC BY 4.0. The registry itself is published under the licence of this
repository.

The Wikidata layer is built from two extracts of the class graph, fetched with
`bash tools/fetch_wikidata_classes.sh <dir>` and turned into entries by
`python tools/build_thing_registry_wikidata.py <dir>`. The extracts come from
QLever rather than the official query service, which caps a query at 60 seconds
and cannot return a graph of 5.2 million edges.

Rebuild the lexical layer with `python tools/build_thing_registry.py` (needs `wn` and `wordfreq`,
and `python -m wn download oewn:2024` once). The build is deterministic: the same
source and the same thresholds produce the same registry.