The catalog and catalog_version

This page explains the live vocabulary that programs can reference and the token that detects change.

The catalog is the server's queryable inventory of environment-bound names; catalog_version identifies the visible snapshot.

Guides teach grammar. The catalog answers a different question: which names exist now? A workflow language may permit a device call, but only the catalog can say that light.lobby exists, which actions it supports, and what maximum risk it carries.

Catalog access supports list, get, and, when declared, changed_since. Responses are scoped to the caller's authorization. Every response carries an opaque catalog_version. Clients compare the token for equality; they do not parse it. The token changes when a visible entry is added, removed, or changed.

This is a real Harborview get result:

{
  "entry": {
    "id": "lock.dock_door",
    "kind": "lock",
    "name": "Loading-dock door",
    "risk": "destructive",
    "risk_hints": {
      "readOnly": false,
      "destructive": true,
      "openWorld": false
    }
  },
  "catalog_version": "cv_590fefad56a7a504"
}

The token pins validation to execution. If the visible catalog changes after validation, execution can refuse before any effect occurs. In Harborview, removing light.floor2_west changes the boot token from cv_590fefad56a7a504 to cv_d4e1f4237c537ac0.

The token is not a semantic version. It says “this visible catalog is the same,” not “this change is compatible.”

Formal rules: Part II §5.4, Catalog entry and catalog version, Part II §6.3, lookup, and Part IV §3, Computing catalog_version.

Next: Validation · Drift and recovery