Support multiple catalog entries per runtime contract

README.md

@@ -82,8 +82,9 @@ ownership details are design decisions tracked in #32.
 ### One catalog, explicit kinds and bindings
 
 API Core now uses `wrangles_catalog` as the central identity table and links
-saved rows through `models.catalog_id`. The current public snapshot contains 99
-wrangle rows: 98 map to callable Registry entries, while `map` remains a
+saved rows through `models.catalog_id`. The current public snapshot contains 101
+wrangle rows: 100 bind to 98 callable Registry entries (the three lookup catalog
+keys share one `lookup` contract), while `map` remains a
 catalog-only row until it has an explicit executable or concept classification.
 Connectors, run capabilities, typed relationships and selected reusable
 concepts remain later additions to the same catalog design.

registry/CONTRACT.md

@@ -52,9 +52,33 @@ and additional guidance.
 API Core allocates `catalog_id` as a positive PostgreSQL `BIGINT`. Every JSON
 artifact represents it as a decimal string so JavaScript consumers cannot lose
 integer precision. The compiler joins catalog rows to callable entries by exact
-`wrangle_key`; missing rows, duplicate identities, key conflicts, kind
-conflicts, and title conflicts fail the build. The compiler never allocates or
-changes catalog IDs.
+`wrangle_key`. Each callable requires one canonical row whose `catalog_key`
+equals that callable key. Its ID remains the contract/page identity, independent
+of snapshot order. Additional catalog keys may share the same `wrangle_key`:
+for example, `lookup.key` and `lookup.semantic` both bind to the `lookup` contract.
+Catalog IDs and catalog keys remain unique; duplicate identities/keys, missing
+canonical rows and incompatible kinds fail the build. Canonical titles must
+match Docs; additional bindings retain their own catalog titles and statuses.
+The compiler never allocates or changes catalog IDs.
+
+Registry 0.3.1 exposes these mappings through `manifest.artifacts.catalog_bindings`,
+the checksummed `/registry/catalog/bindings.json` artifact. Its versioned envelope
+contains `format: wrangles-catalog-bindings`, `format_version: 0.1`,
+`registry_version`, `entry_count`, and `entries`. Each binding preserves
+`catalog_id`, `catalog_key`, `catalog_status`, `kind`, and `title`, and provides
+`wrangle_key`, `canonical_catalog_id`, `contract_json`, and `route`.
+Only bindings to public documented callables enter this artifact; catalog-only
+entries remain in the reconciliation report. The pinned snapshot must already
+be approved for public export, as before; this change adds no publication policy.
+
+A consumer preserves the selected binding's catalog ID/key while fetching its
+shared contract. It uses `wrangle_key` in recipe syntax and obtains the saved
+`model_id` separately from authorized model metadata. Bindings contain no model
+ID and do not grant execution or Recipe Writer eligibility. They create neither
+new callable keys nor duplicate contracts/pages. `manifest.entry_count` and
+`catalog.callable_entry_count` count callables; `catalog.binding_count` counts
+published bindings. Existing contract 0.3 readers can still use canonical entries;
+selection by subtype catalog ID requires the new bindings artifact.
 
 The source Markdown's `id` field is the previous documentation UUID. Contract
 0.3 publishes it as nullable `legacy_id` for migration tracing only. It is not a
@@ -326,7 +350,7 @@ terminated by one newline (`utf8-newline-separated-sorted-v1`).
 
 ## Versioning and lifecycle
 
-The pre-production Registry version is `0.3.0`. Version `0.2.0` makes the
+The pre-production Registry version is `0.3.1`. Version `0.2.0` makes the
 fail-closed Recipe Writer eligibility decision required for every entry and
 adds the compiled-contract and integrity metadata consumed by Registry clients.
 Version `0.2.1` introduces optional column-role and cardinality metadata plus
@@ -337,6 +361,10 @@ contract's canonical UUID field with string-valued `catalog_id` and
 `catalog_key`, and retains old UUIDs only as `legacy_id`. It also publishes
 catalog reconciliation as a checksummed bundle artifact. Source Markdown stays
 on schema 0.2 during this migration; generated contracts use contract 0.3.
+Version `0.3.1` adds the checksummed many-to-one catalog bindings artifact while
+preserving canonical contract identities, recipe keys and the 88-key Recipe
+Writer baseline. Catalog reconciliation records additional bindings separately
+from its existing canonical matches, including their status/path differences.
 A production release will
 contain:
 

registry/README.md

@@ -65,6 +65,18 @@ npm run build
 and replaces the sanitized snapshot deterministically. It does not read or
 publish the `models` table.
 
+Multiple catalog rows may point to one `wrangle_key`. Keep a canonical row with
+`catalog_key = wrangle_key` (for example `81 / lookup / lookup`) and add subtype
+rows separately (`101 / lookup.key / lookup`, `102 / lookup.semantic / lookup`).
+The compiler retains one callable contract/page and publishes all corresponding
+IDs and keys in the checksummed `catalog/bindings.json` artifact, linked from
+the manifest. These are catalog selections, not additional executable aliases.
+Refresh the snapshot from authorized catalog metadata; do not invent missing
+titles, statuses or timestamps from a partial query result. The checked-in
+snapshot contains the original 99-row export plus the two complete lookup
+rows supplied by the catalog owner, updated on 2026-09-21. This is not evidence
+that every newer row in the live catalog has been exported.
+
 `compile:registry` produces the Docusaurus pages and public raw
 artifacts. `check:registry` fails when the source is invalid or the committed
 generated files are stale.

registry/catalog/api-core.json

@@ -6,9 +6,9 @@
     "system": "API Core",
     "repository": "https://github.com/wrangleworks/API-Core",
     "table": "public.wrangles_catalog",
-    "data_updated_through": "2026-09-16T08:44:50.975472Z"
+    "data_updated_through": "2026-09-21T09:29:40.543681Z"
   },
-  "entry_count": 99,
+  "entry_count": 101,
   "entries": [
     {
       "catalog_id": "1",
@@ -1197,6 +1197,30 @@
       "source": "registry-docs",
       "created_at": "2026-09-16T08:44:50.975472Z",
       "updated_at": "2026-09-16T08:44:50.975472Z"
+    },
+    {
+      "catalog_id": "101",
+      "catalog_key": "lookup.key",
+      "kind": "wrangle",
+      "wrangle_key": "lookup",
+      "title": "Lookup Key",
+      "registry_path": null,
+      "status": "active",
+      "source": "registry-docs",
+      "created_at": "2026-09-21T09:29:40.543681Z",
+      "updated_at": "2026-09-21T09:29:40.543681Z"
+    },
+    {
+      "catalog_id": "102",
+      "catalog_key": "lookup.semantic",
+      "kind": "wrangle",
+      "wrangle_key": "lookup",
+      "title": "Lookup Semantic",
+      "registry_path": null,
+      "status": "active",
+      "source": "registry-docs",
+      "created_at": "2026-09-21T09:29:40.543681Z",
+      "updated_at": "2026-09-21T09:29:40.543681Z"
     }
   ]
 }

registry/reports/catalog-reconciliation.json

@@ -1,18 +1,21 @@
 {
   "format": "wrangles-catalog-reconciliation",
   "format_version": "0.1",
-  "registry_version": "0.3.0",
+  "registry_version": "0.3.1",
   "catalog_source": {
     "system": "API Core",
     "repository": "https://github.com/wrangleworks/API-Core",
     "table": "public.wrangles_catalog",
-    "data_updated_through": "2026-09-16T08:44:50.975472Z"
+    "data_updated_through": "2026-09-21T09:29:40.543681Z"
   },
   "summary": {
-    "catalog_entries": 99,
+    "catalog_entries": 101,
     "registry_entries": 98,
     "matched_entries": 98,
     "conflicting_entries": 0,
+    "additional_binding_count": 2,
+    "conflicting_bindings": 0,
+    "additional_bindings_with_status_differences": 0,
     "entries_with_status_differences": 2,
     "entries_without_catalog_registry_path": 98,
     "catalog_only_entries": 1
@@ -1891,6 +1894,48 @@
       ]
     }
   ],
+  "additional_bindings": [
+    {
+      "catalog_id": "101",
+      "catalog_key": "lookup.key",
+      "wrangle_key": "lookup",
+      "canonical_catalog_id": "81",
+      "title": "Lookup Key",
+      "catalog_status": "active",
+      "registry_status": "active",
+      "expected_registry_path": "registry/wrangles/_root/lookup.md",
+      "catalog_registry_path": null,
+      "status": "matched",
+      "conflicts": [],
+      "differences": [
+        {
+          "code": "registry_path_missing",
+          "expected": "registry/wrangles/_root/lookup.md",
+          "catalog": null
+        }
+      ]
+    },
+    {
+      "catalog_id": "102",
+      "catalog_key": "lookup.semantic",
+      "wrangle_key": "lookup",
+      "canonical_catalog_id": "81",
+      "title": "Lookup Semantic",
+      "catalog_status": "active",
+      "registry_status": "active",
+      "expected_registry_path": "registry/wrangles/_root/lookup.md",
+      "catalog_registry_path": null,
+      "status": "matched",
+      "conflicts": [],
+      "differences": [
+        {
+          "code": "registry_path_missing",
+          "expected": "registry/wrangles/_root/lookup.md",
+          "catalog": null
+        }
+      ]
+    }
+  ],
   "catalog_only_entries": [
     {
       "catalog_id": "99",

registry/reports/catalog-reconciliation.md

@@ -3,20 +3,32 @@
 Generated file. Do not edit directly.
 
 - Catalog source: `public.wrangles_catalog`
-- Catalog data updated through: `2026-09-16T08:44:50.975472Z`
-- Catalog rows: 99
+- Catalog data updated through: `2026-09-21T09:29:40.543681Z`
+- Catalog rows: 101
 - Callable Registry entries: 98
 - Identity matches: 98
 - Identity conflicts: 0
-- Lifecycle/status differences: 2
-- Missing catalog registry paths: 98
+- Additional catalog bindings: 2
+- Additional binding conflicts: 0
+- Canonical lifecycle/status differences: 2
+- Additional binding lifecycle/status differences: 0
+- Missing canonical catalog registry paths: 98
 - Catalog-only rows: 1
 
-The compiler joins callable entries to API Core by `wrangle_key`. A missing row,
-duplicate identity, key mismatch, kind mismatch, or title mismatch fails the build.
+The canonical row has `catalog_key = wrangle_key`; additional catalog keys may
+share its callable. Canonical identity never depends on snapshot order. A missing
+canonical row, duplicate identity/key, or incompatible kind fails the build.
+Canonical titles must match Docs; additional bindings retain their own titles.
 Status and path differences remain visible migration work and do not silently
 change the executable contract.
 
+## Additional bindings
+
+| Catalog ID | Catalog key | Wrangle key | Canonical catalog ID |
+| --- | --- | --- | --- |
+| `101` | `lookup.key` | `lookup` | `81` |
+| `102` | `lookup.semantic` | `lookup` | `81` |
+
 ## Status differences
 
 | Catalog ID | Wrangle key | API Core status | Registry lifecycle |

registry/reports/runtime-reconciliation.json

@@ -1,7 +1,7 @@
 {
   "format": "wrangles-registry-reconciliation",
   "format_version": "0.3",
-  "registry_version": "0.3.0",
+  "registry_version": "0.3.1",
   "runtime_source": {
     "repository": "https://github.com/wrangleworks/WranglesPY",
     "version": "1.20.2",

registry/reports/runtime-reconciliation.md

@@ -4,7 +4,7 @@ Generated file. Do not edit directly.
 
 - Runtime version: `1.20.2`
 - Runtime source: [`7916bf158e8b7e561270a1bea7b808f88956edc4`](https://github.com/wrangleworks/WranglesPY/commit/7916bf158e8b7e561270a1bea7b808f88956edc4)
-- Registry version: `0.3.0`
+- Registry version: `0.3.1`
 - Runtime entries: 98
 - Embedded Python schema docstrings: 96
 - Registry entries: 98

registry/schema/catalog-snapshot.schema.json

@@ -63,6 +63,7 @@
         },
         "kind": {"type": "string", "minLength": 1},
         "wrangle_key": {
+          "description": "Callable contract key; multiple distinct catalog IDs/keys may share it. The canonical row has catalog_key equal to wrangle_key.",
           "type": ["string", "null"],
           "pattern": "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)*$"
         },