Add spell catalog overlay resolution

docs/integrations/dnd-spell-catalog-overlays.md

@@ -0,0 +1,64 @@
+# D&D Spell-Catalog Overlay Contract
+
+This document defines the JSON format accepted by the D&D spell catalog
+resolver. An overlay supplies campaign-specific spell names and aliases for
+recognition. It does not supply spell rules, levels, classes, effects, or
+source evidence.
+
+## Shape
+
+An overlay bundle has this shape:
+
+```json
+{
+  "schema_version": "notarius.dnd.spell-catalog-overlay.v1",
+  "catalogs": [
+    {
+      "id": "campaign.example",
+      "ruleset": "dnd-5e-2014",
+      "source": {
+        "title": "Example campaign spells",
+        "version": "1",
+        "url": "",
+        "license": ""
+      },
+      "spells": [
+        {
+          "name": "Aegis of Emberfall",
+          "aliases": ["Emberfall Aegis"]
+        }
+      ]
+    }
+  ]
+}
+```
+
+The top-level `schema_version` and `catalogs` fields are required. The schema
+version must be exactly `notarius.dnd.spell-catalog-overlay.v1`, and at least
+one catalog is required. Catalogs require a unique, non-empty, trimmed `id`,
+the exact `dnd-5e-2014` `ruleset`, a `source`, and a non-empty `spells` array.
+
+`source.title` is required and must be non-empty and trimmed. `source.version`,
+`source.url`, and `source.license` are optional strings and may be empty.
+Each spell requires a non-empty, trimmed `name`. `aliases` may be omitted or
+may be an array of trimmed, non-empty strings; JSON `null` is not an alias
+array. Overlay objects contain no other supported spell fields.
+
+Decoding is strict: unknown fields, malformed JSON, trailing JSON values, and
+non-string optional source fields are rejected.
+
+## Composition
+
+The resolver always starts with the embedded D&D 5e 2014 SRD catalog. Overlay
+catalogs are sorted by `id` before composition, so the input order does not
+affect the result. A new canonical name adds a recognition entry. A canonical
+name matching an existing canonical name augments that spell and keeps the
+established canonical display spelling. Repeated aliases for the same spell
+are idempotent.
+
+Canonical-name display conflicts and canonical/alias or alias/alias collisions
+between different spells are errors, including collisions with the embedded
+catalog. Canonical names and aliases use the catalog's case, whitespace, and
+common-apostrophe normalization rules. The effective catalog returns canonical
+names in sorted order and produces a semantic SHA-256 digest that is stable
+under JSON formatting, object-key, catalog, spell, and alias reordering.

docs/internal/modules.md

@@ -70,6 +70,17 @@ license details live beside the asset in `SOURCES.md`. This domain-owned data is
 separate from `internal/modules/dnd/shared`, which is reserved for reusable
 prompt and source-reference machinery.
 
+`ResolveEffectiveCatalog` builds the immutable recognition view used by later
+D&D consumers. It starts with the embedded SRD catalog and optionally applies
+one strict JSON overlay from the `spell_catalog` item in a materialized
+reference set. Overlay catalogs are ordered by ID, may add names and aliases,
+and may augment an existing canonical spell without replacing its display
+name. Cross-spell lookup collisions are errors. The effective view exposes
+sorted canonical names, normalized lookup, overlay identities, and a semantic
+digest; overlay content remains contextual reference material rather than
+source evidence. Its external JSON contract is defined in the
+[spell-catalog overlay contract](../integrations/dnd-spell-catalog-overlays.md).
+
 ## Input Adapter
 
 ### `internal/modules/seriatim/input/transcript`