metergraph-core 0.8.1__tar.gz → 0.8.2__tar.gz

{metergraph_core-0.8.1/src/metergraph_core.egg-info → metergraph_core-0.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: metergraph-core
-Version: 0.8.1
+Version: 0.8.2
 Summary: Open, effective-dated LLM pricing catalog and deterministic cost calculator for popular models across major providers and gateways, including OpenAI, Anthropic, Google Gemini, AWS Bedrock, OpenRouter, Vercel AI Gateway, and more.
 Author: Metergraph
 License-Expression: Apache-2.0
@@ -356,6 +356,41 @@ effective_from)` on a model the catalog already has:
   start on a later UTC date than the row it replaces, for the same reason.
 - `close_price` sets `effective_to` on the open row without a replacement.
 
+Catalog operations change which models exist and what calls they match:
+
+- `add_model` appends one complete model entry.
+- `add_alias` appends one alias to an existing model. A spelling another
+  model already holds is a conflict only while both aliases are in effect.
+- `close_alias` sets `effective_to` on an open alias, named by
+  `(canonical_id, provider, alias, channel)`; `expect` is the exact current
+  alias. An alias with dates must cite its source, so a close carries
+  `source_url` when the alias has none and must not when it has one.
+
+A `close_alias`, `close_price`, `add_alias` and `add_price` together move a
+spelling from a duplicate entry to the model it duplicates from a date. Calls
+before that date keep the old model and price, calls from it resolve to the
+surviving model, and the old entry stays for history with nothing in effect:
+
+```yaml
+  - op: close_alias
+    key: {canonical_id: example-host/model-a-instruct, provider: openrouter,
+          alias: example-host/model-a-instruct, channel: openrouter-api}
+    expect: {provider: openrouter, alias: example-host/model-a-instruct, channel: openrouter-api}
+    effective_to: "2026-10-20"
+    source_url: "https://..."
+  - op: close_price      # the duplicate's open openrouter-api row
+  - op: add_alias
+    key: {canonical_id: example/model-a, provider: openrouter,
+          alias: example-host/model-a-instruct, channel: openrouter-api}
+    expect: null
+    alias: {provider: openrouter, alias: example-host/model-a-instruct,
+            channel: openrouter-api, effective_from: "2026-10-20", source_url: "https://..."}
+  - op: add_price        # the same rate on example/model-a from 2026-10-20
+```
+
+Gateway discovery matches a spelling only through aliases in effect on the
+observation date, so it follows a moved spelling to its new model.
+
 A price id ends with the UTC date of its row's start. If two rows for one
 model, channel and region would still share an id (possible in a hand-edited
 catalog), each that does not start at UTC midnight also names its UTC start

{metergraph_core-0.8.1 → metergraph_core-0.8.2}/README.md

@@ -326,6 +326,41 @@ effective_from)` on a model the catalog already has:
   start on a later UTC date than the row it replaces, for the same reason.
 - `close_price` sets `effective_to` on the open row without a replacement.
 
+Catalog operations change which models exist and what calls they match:
+
+- `add_model` appends one complete model entry.
+- `add_alias` appends one alias to an existing model. A spelling another
+  model already holds is a conflict only while both aliases are in effect.
+- `close_alias` sets `effective_to` on an open alias, named by
+  `(canonical_id, provider, alias, channel)`; `expect` is the exact current
+  alias. An alias with dates must cite its source, so a close carries
+  `source_url` when the alias has none and must not when it has one.
+
+A `close_alias`, `close_price`, `add_alias` and `add_price` together move a
+spelling from a duplicate entry to the model it duplicates from a date. Calls
+before that date keep the old model and price, calls from it resolve to the
+surviving model, and the old entry stays for history with nothing in effect:
+
+```yaml
+  - op: close_alias
+    key: {canonical_id: example-host/model-a-instruct, provider: openrouter,
+          alias: example-host/model-a-instruct, channel: openrouter-api}
+    expect: {provider: openrouter, alias: example-host/model-a-instruct, channel: openrouter-api}
+    effective_to: "2026-10-20"
+    source_url: "https://..."
+  - op: close_price      # the duplicate's open openrouter-api row
+  - op: add_alias
+    key: {canonical_id: example/model-a, provider: openrouter,
+          alias: example-host/model-a-instruct, channel: openrouter-api}
+    expect: null
+    alias: {provider: openrouter, alias: example-host/model-a-instruct,
+            channel: openrouter-api, effective_from: "2026-10-20", source_url: "https://..."}
+  - op: add_price        # the same rate on example/model-a from 2026-10-20
+```
+
+Gateway discovery matches a spelling only through aliases in effect on the
+observation date, so it follows a moved spelling to its new model.
+
 A price id ends with the UTC date of its row's start. If two rows for one
 model, channel and region would still share an id (possible in a hand-edited
 catalog), each that does not start at UTC midnight also names its UTC start

{metergraph_core-0.8.1 → metergraph_core-0.8.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "metergraph-core"
-version = "0.8.1"
+version = "0.8.2"
 description = "Open, effective-dated LLM pricing catalog and deterministic cost calculator for popular models across major providers and gateways, including OpenAI, Anthropic, Google Gemini, AWS Bedrock, OpenRouter, Vercel AI Gateway, and more."
 readme = "README.md"
 license = "Apache-2.0"

{metergraph_core-0.8.1 → metergraph_core-0.8.2}/src/metergraph_core/catalog_delta.py

@@ -15,7 +15,15 @@ catalog already has:
 It also supports reviewed catalog expansion:
 
 - ``add_model`` appends one complete model entry.
-- ``add_alias`` appends one alias to an existing model.
+- ``add_alias`` appends one alias to an existing model. A spelling another
+  model holds conflicts only while both aliases are in effect, so a spelling
+  can move to another model from a date.
+- ``close_alias`` sets ``effective_to`` on the open alias its ``expect``
+  names, so a spelling closed and reopened on one model keeps its earlier
+  window. With an
+  ``add_alias`` for the same spelling on another model in one delta, it
+  moves that spelling: calls before the date keep the old model, calls from
+  it resolve to the new one.
 
 ``provenance`` references the observations and evidence the delta came
 from.
@@ -34,7 +42,7 @@ from .loader import CatalogError, _canonical_json, load_catalog_document
 CATALOG_DELTA_SCHEMA_VERSION = 2
 PRICING_DELTA_KIND = "pricing_delta"
 PRICE_OPERATIONS = ("add_price", "replace_price", "close_price")
-CATALOG_OPERATIONS = ("add_model", "add_alias")
+CATALOG_OPERATIONS = ("add_model", "add_alias", "close_alias")
 OPERATIONS = PRICE_OPERATIONS + CATALOG_OPERATIONS
 
 RATE_FIELDS = (
@@ -116,12 +124,14 @@ class DeltaOperation:
     expect: Mapping[str, Any] | None
     # The new row for add/replace; None for close.
     price: Mapping[str, Any] | None
-    # The closing date for close_price.
+    # The closing date for close_price and close_alias.
     effective_to: str | None
     # The complete entry for add_model.
     model: Mapping[str, Any] | None = None
     # The alias row for add_alias.
     alias: Mapping[str, Any] | None = None
+    # The source a close_alias cites, for an alias that cites none.
+    source_url: str | None = None
 
 
 @dataclass(frozen=True, slots=True)
@@ -197,7 +207,7 @@ def _parse_model_key(raw: Any, label: str) -> ModelKey:
     return ModelKey(_text(raw["canonical_id"]))
 
 
-def _parse_alias_key(raw: Any, label: str) -> AliasKey:
+def _parse_alias_key(raw: Any, label: str, op: str) -> AliasKey:
     if not isinstance(raw, Mapping):
         raise CatalogDeltaError(f"{label}: key must be a mapping")
     fields = ("canonical_id", "provider", "alias", "channel")
@@ -205,7 +215,7 @@ def _parse_alias_key(raw: Any, label: str) -> AliasKey:
         if _text(raw.get(field)) is None:
             raise CatalogDeltaError(f"{label}: key needs {field}")
     if set(raw) != set(fields):
-        raise CatalogDeltaError(f"{label}: add_alias key has unknown fields")
+        raise CatalogDeltaError(f"{label}: {op} key has unknown fields")
     return AliasKey(
         _text(raw["canonical_id"]),
         _text(raw["provider"]).lower(),
@@ -324,8 +334,8 @@ def _parse_operation(index: int, raw: Any) -> DeltaOperation:
         raise CatalogDeltaError(f"{label}: unknown op {op!r}")
     if op == "add_model":
         key: OperationKey = _parse_model_key(raw.get("key"), label)
-    elif op == "add_alias":
-        key = _parse_alias_key(raw.get("key"), label)
+    elif op in ("add_alias", "close_alias"):
+        key = _parse_alias_key(raw.get("key"), label, op)
     else:
         key = _parse_key(raw.get("key"), label)
     expect = raw.get("expect")
@@ -338,6 +348,7 @@ def _parse_operation(index: int, raw: Any) -> DeltaOperation:
     effective_to = None
     model = None
     alias = None
+    source_url = None
     if op == "add_model":
         if "price" in raw or "alias" in raw or "effective_to" in raw:
             raise CatalogDeltaError(f"{label}: add_model takes only model")
@@ -346,6 +357,18 @@ def _parse_operation(index: int, raw: Any) -> DeltaOperation:
         if "price" in raw or "model" in raw or "effective_to" in raw:
             raise CatalogDeltaError(f"{label}: add_alias takes only alias")
         alias = _parse_alias(raw.get("alias"), key, label)
+    elif op == "close_alias":
+        if set(raw) - {"op", "key", "expect", "effective_to", "source_url"}:
+            raise CatalogDeltaError(
+                f"{label}: close_alias takes only effective_to and source_url"
+            )
+        effective_to = _iso_date(raw.get("effective_to"))
+        if effective_to is None:
+            raise CatalogDeltaError(f"{label}: invalid effective_to")
+        if "source_url" in raw:
+            source_url = _text(raw.get("source_url"))
+            if source_url is None:
+                raise CatalogDeltaError(f"{label}: invalid source_url")
     elif op == "close_price":
         if "price" in raw:
             raise CatalogDeltaError(f"{label}: close_price takes no price")
@@ -369,6 +392,7 @@ def _parse_operation(index: int, raw: Any) -> DeltaOperation:
         effective_to=effective_to,
         model=model,
         alias=alias,
+        source_url=source_url,
     )
 
 
@@ -480,8 +504,53 @@ def _key_label(key: OperationKey) -> str:
     return key.canonical_id
 
 
-def _precondition(document: Mapping[str, Any], operation: DeltaOperation) -> str | None:
-    """Why ``operation`` does not apply to ``document``, or None when it does."""
+def _alias_rows(
+    entry: Mapping[str, Any], key: AliasKey
+) -> list[Mapping[str, Any]]:
+    return [
+        alias
+        for alias in entry.get("aliases") or []
+        if isinstance(alias, Mapping)
+        and (_text(alias.get("provider")) or "").lower() == key.provider
+        and (_text(alias.get("alias")) or "").lower() == key.alias
+        and _text(alias.get("channel")) == key.channel
+    ]
+
+
+def _expected_aliases(
+    entry: Mapping[str, Any], operation: DeltaOperation
+) -> list[Mapping[str, Any]]:
+    """The rows under a close_alias key that equal its ``expect``. A key can
+    hold several windows of one spelling; ``expect`` names the one to end."""
+    expected = _canonical_json(operation.expect)
+    return [
+        alias
+        for alias in _alias_rows(entry, operation.key)
+        if _canonical_json(alias) == expected
+    ]
+
+
+def _windows_overlap(
+    left_from: Any, left_to: Any, right_from: Any, right_to: Any
+) -> bool:
+    """Whether two alias windows share an instant; a missing bound is open,
+    as the catalog loader reads it."""
+    left_from, left_to = _instant(left_from), _instant(left_to)
+    right_from, right_to = _instant(right_from), _instant(right_to)
+    return (left_to is None or right_from is None or right_from < left_to) and (
+        right_to is None or left_from is None or left_from < right_to
+    )
+
+
+def _precondition(
+    document: Mapping[str, Any],
+    operation: DeltaOperation,
+    closing: Mapping[AliasKey, str] | None = None,
+) -> str | None:
+    """Why ``operation`` does not apply to ``document``, or None when it does.
+
+    ``closing`` maps the key of each alias a close_alias in the same delta
+    ends to its ``effective_to``, so an alias can move in one delta."""
     if operation.op == "add_model":
         key = operation.key
         if _model_indexes(document, key.canonical_id):
@@ -502,13 +571,69 @@ def _precondition(document: Mapping[str, Any], operation: DeltaOperation) -> str
             return "unknown_model"
         if len(models) > 1:
             return "duplicate_model"
-        for canonical_id, provider, name in _aliases(document):
-            if (provider, name) == (key.provider, key.alias):
-                return (
-                    "alias_exists"
-                    if canonical_id == key.canonical_id
-                    else "alias_conflict"
-                )
+        closing = closing or {}
+        new = operation.alias or {}
+        for entry in document.get("models") or []:
+            if not isinstance(entry, Mapping):
+                continue
+            canonical_id = str(entry.get("canonical_id") or "")
+            for alias in entry.get("aliases") or []:
+                if not isinstance(alias, Mapping):
+                    continue
+                provider = (_text(alias.get("provider")) or "").lower()
+                name = (_text(alias.get("alias")) or "").lower()
+                if (provider, name) != (key.provider, key.alias):
+                    continue
+                ends = alias.get("effective_to")
+                if ends is None:
+                    ends = closing.get(
+                        AliasKey(
+                            canonical_id,
+                            provider,
+                            name,
+                            _text(alias.get("channel")) or "",
+                        )
+                    )
+                if _windows_overlap(
+                    alias.get("effective_from"),
+                    ends,
+                    new.get("effective_from"),
+                    new.get("effective_to"),
+                ):
+                    return (
+                        "alias_exists"
+                        if canonical_id == key.canonical_id
+                        else "alias_conflict"
+                    )
+        return None
+    if operation.op == "close_alias":
+        key = operation.key
+        models = _model_indexes(document, key.canonical_id)
+        if not models:
+            return "unknown_model"
+        if len(models) > 1:
+            return "duplicate_model"
+        entry = document["models"][models[0]]
+        if not _alias_rows(entry, key):
+            return "alias_missing"
+        rows = _expected_aliases(entry, operation)
+        if not rows:
+            return "expect_mismatch"
+        if len(rows) > 1:
+            return "duplicate_alias"
+        row = rows[0]
+        if row.get("effective_to") is not None:
+            return "alias_not_open"
+        starts = _instant(row.get("effective_from"))
+        if starts is not None and _instant(operation.effective_to) <= starts:
+            return "not_after_start"
+        # A dated alias must cite its source, so a close supplies one for an
+        # alias that has none, and never replaces one it has.
+        if _text(row.get("source_url")) is None:
+            if operation.source_url is None:
+                return "source_url_needed"
+        elif operation.source_url is not None:
+            return "source_url_exists"
         return None
     model_index, rows, reason = _locate(document, operation)
     if reason is not None:
@@ -565,10 +690,15 @@ def apply_catalog_delta(
     delta = parse_catalog_delta(delta_document)
     if not isinstance(document, Mapping):
         raise CatalogDeltaError("catalog document must be a mapping")
+    closing = {
+        operation.key: operation.effective_to
+        for operation in delta.operations
+        if operation.op == "close_alias"
+    }
     conflicts = tuple(
         DeltaConflict(operation.index, operation.op, operation.key, reason)
         for operation in delta.operations
-        if (reason := _precondition(document, operation)) is not None
+        if (reason := _precondition(document, operation, closing)) is not None
     )
     if conflicts:
         raise CatalogDeltaConflict(conflicts)
@@ -586,6 +716,16 @@ def apply_catalog_delta(
                 copy.deepcopy(dict(operation.alias))
             )
             continue
+        if operation.op == "close_alias":
+            [model_index] = _model_indexes(result, operation.key.canonical_id)
+            # The first equal row is the one checked: an alias this delta
+            # adds under the same key starts after this one ends, so it never
+            # equals ``expect``.
+            alias = _expected_aliases(result["models"][model_index], operation)[0]
+            alias["effective_to"] = operation.effective_to
+            if operation.source_url is not None:
+                alias["source_url"] = operation.source_url
+            continue
         model_index, rows, _ = _locate(result, operation)
         prices = result["models"][model_index].setdefault("prices", [])
         if operation.op == "add_price":

{metergraph_core-0.8.1 → metergraph_core-0.8.2}/src/metergraph_core/data/prices.yaml

@@ -4985,7 +4985,7 @@ models:
         cache_read_per_mtok: 0.125
         batch_input_per_mtok: 0.625
         batch_output_per_mtok: 5
-        source_url: https://ai-gateway.vercel.sh/v1/models
+        source_url: https://developers.openai.com/api/docs/models/gpt-5
       - channel: vercel-ai-gateway
         region: global
         effective_from: "2026-10-02"
@@ -5010,7 +5010,7 @@ models:
         input_per_mtok: 1.75
         output_per_mtok: 14
         cache_read_per_mtok: 0.175
-        source_url: https://ai-gateway.vercel.sh/v1/models
+        source_url: https://developers.openai.com/api/docs/models/gpt-5.3-codex
       - channel: vercel-ai-gateway
         region: global
         effective_from: "2026-10-02"
@@ -5141,11 +5141,22 @@ models:
       - channel: openai-api
         region: global
         effective_from: "2026-07-09"
+        effective_to: "2026-10-27"
         input_per_mtok: 12.5
         output_per_mtok: 75
         cache_read_per_mtok: 1.25
         cache_write_5m_per_mtok: 15.625
-        source_url: https://ai-gateway.vercel.sh/v1/models
+        source_url: https://developers.openai.com/api/docs/models/gpt-5.6-cyber
+      - channel: openai-api
+        region: global
+        effective_from: "2026-10-27"
+        input_per_mtok: 12.5
+        output_per_mtok: 75
+        cache_read_per_mtok: 1.25
+        cache_write_5m_per_mtok: 15.625
+        rules:
+          long_context: {threshold: 272000, threshold_counts_cached_tokens: true, input_multiplier: 2, output_multiplier: 1.5}
+        source_url: https://developers.openai.com/api/docs/models/gpt-5.6-cyber
   - canonical_id: openai/o4-mini
     publisher: openai
     aliases:
@@ -5163,7 +5174,7 @@ models:
         cache_read_per_mtok: 0.275
         batch_input_per_mtok: 0.55
         batch_output_per_mtok: 2.2
-        source_url: https://ai-gateway.vercel.sh/v1/models
+        source_url: https://developers.openai.com/api/docs/models/o4-mini
       - channel: vercel-ai-gateway
         region: global
         effective_from: "2025-04-16"

{metergraph_core-0.8.1 → metergraph_core-0.8.2}/src/metergraph_core/refresh.py

@@ -619,6 +619,8 @@ def _gateway_price(
 
 # Reviewed gateway spellings for publishers the catalog already names.
 _GATEWAY_PUBLISHER_PREFIXES = {
+    "bytedance-seed": "bytedance",
+    "meta-llama": "meta",
     "mistralai": "mistral",
     "qwen": "alibaba",
     "z-ai": "zai",
@@ -642,8 +644,48 @@ def _identity_shape(model_key: str) -> tuple[str, str]:
     return prefix, "".join(character for character in suffix if character.isalnum())
 
 
+def _current_identity(
+    entry: Mapping[str, Any], day: date
+) -> tuple[str | None, list[Mapping[str, Any]]]:
+    """``entry``'s canonical id and its aliases in effect on ``day``.
+
+    An alias that has ended no longer names the model, so a spelling moved to
+    another model matches only there. The canonical id is left out when it is
+    also one of the model's alias spellings and none of those is in effect,
+    as ``_names`` treats the canonical tail."""
+    aliases = [a for a in entry.get("aliases") or [] if isinstance(a, Mapping)]
+    current = [a for a in aliases if _in_effect(a, day, dated=False)]
+    canonical_id = str(entry.get("canonical_id") or "").strip().lower()
+    spelled = {str(a.get("alias") or "").strip().lower() for a in aliases}
+    active = {str(a.get("alias") or "").strip().lower() for a in current}
+    if canonical_id in spelled and canonical_id not in active:
+        return None, current
+    return canonical_id, current
+
+
+def _channel_models(
+    document: Mapping[str, Any], source: PriceSource, model_key: str, day: date
+) -> list[Mapping[str, Any]]:
+    """Models with an alias in effect on ``day`` that spells ``model_key`` on
+    the source's own channel. That alias is the reviewed mapping for this
+    gateway, so it decides even while another channel still gives the
+    spelling to a different model."""
+    provider, wanted = source.provider.lower(), model_key.strip().lower()
+    return [
+        entry
+        for entry in document.get("models") or []
+        if isinstance(entry, Mapping)
+        and any(
+            str(alias.get("provider") or "").strip().lower() == provider
+            and str(alias.get("alias") or "").strip().lower() == wanted
+            and alias.get("channel") == source.channel
+            for alias in _current_identity(entry, day)[1]
+        )
+    ]
+
+
 def _exact_models(
-    document: Mapping[str, Any], model_key: str
+    document: Mapping[str, Any], model_key: str, day: date
 ) -> list[Mapping[str, Any]]:
     publisher, _, _ = _catalog_gateway_identity(model_key).partition("/")
     wanted = {
@@ -654,17 +696,15 @@ def _exact_models(
     for entry in document.get("models") or []:
         if not isinstance(entry, Mapping):
             continue
-        names = {str(entry.get("canonical_id") or "").strip().lower()}
+        canonical_id, aliases = _current_identity(entry, day)
+        names = {canonical_id} if canonical_id else set()
         names.update(
-            str(alias.get("alias") or "").strip().lower()
-            for alias in entry.get("aliases") or []
-            if isinstance(alias, Mapping)
+            str(alias.get("alias") or "").strip().lower() for alias in aliases
         )
         names.update(
             f"{publisher}/{str(alias.get('alias') or '').strip().lower()}"
-            for alias in entry.get("aliases") or []
-            if isinstance(alias, Mapping)
-            and _catalog_publisher(alias.get("provider")) == publisher
+            for alias in aliases
+            if _catalog_publisher(alias.get("provider")) == publisher
         )
         if wanted & names:
             found.append(entry)
@@ -672,21 +712,21 @@ def _exact_models(
 
 
 def _near_models(
-    document: Mapping[str, Any], model_key: str
+    document: Mapping[str, Any], model_key: str, day: date
 ) -> list[Mapping[str, Any]]:
     wanted = _identity_shape(model_key)
     found = []
     for entry in document.get("models") or []:
         if not isinstance(entry, Mapping):
             continue
-        shapes = {_identity_shape(str(entry.get("canonical_id") or ""))}
+        canonical_id, aliases = _current_identity(entry, day)
+        shapes = {_identity_shape(canonical_id)} if canonical_id else set()
         shapes.update(
             _identity_shape(
                 f"{_catalog_publisher(alias.get('provider'))}/"
                 f"{str(alias.get('alias') or '').strip().lower()}"
             )
-            for alias in entry.get("aliases") or []
-            if isinstance(alias, Mapping)
+            for alias in aliases
         )
         if wanted in shapes:
             found.append(entry)
@@ -703,9 +743,11 @@ def _gateway_additions(
     operations: list[dict[str, Any]] = []
     identity_exclusions: list[dict[str, Any]] = []
     for rate in extraction.rates:
-        matches = _exact_models(document, rate.model_key)
+        matches = _channel_models(
+            document, source, rate.model_key, observed_on
+        ) or _exact_models(document, rate.model_key, observed_on)
         if not matches:
-            near = _near_models(document, rate.model_key)
+            near = _near_models(document, rate.model_key, observed_on)
             if near:
                 identity_exclusions.append(
                     {

{metergraph_core-0.8.1 → metergraph_core-0.8.2/src/metergraph_core.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: metergraph-core
-Version: 0.8.1
+Version: 0.8.2
 Summary: Open, effective-dated LLM pricing catalog and deterministic cost calculator for popular models across major providers and gateways, including OpenAI, Anthropic, Google Gemini, AWS Bedrock, OpenRouter, Vercel AI Gateway, and more.
 Author: Metergraph
 License-Expression: Apache-2.0
@@ -356,6 +356,41 @@ effective_from)` on a model the catalog already has:
   start on a later UTC date than the row it replaces, for the same reason.
 - `close_price` sets `effective_to` on the open row without a replacement.
 
+Catalog operations change which models exist and what calls they match:
+
+- `add_model` appends one complete model entry.
+- `add_alias` appends one alias to an existing model. A spelling another
+  model already holds is a conflict only while both aliases are in effect.
+- `close_alias` sets `effective_to` on an open alias, named by
+  `(canonical_id, provider, alias, channel)`; `expect` is the exact current
+  alias. An alias with dates must cite its source, so a close carries
+  `source_url` when the alias has none and must not when it has one.
+
+A `close_alias`, `close_price`, `add_alias` and `add_price` together move a
+spelling from a duplicate entry to the model it duplicates from a date. Calls
+before that date keep the old model and price, calls from it resolve to the
+surviving model, and the old entry stays for history with nothing in effect:
+
+```yaml
+  - op: close_alias
+    key: {canonical_id: example-host/model-a-instruct, provider: openrouter,
+          alias: example-host/model-a-instruct, channel: openrouter-api}
+    expect: {provider: openrouter, alias: example-host/model-a-instruct, channel: openrouter-api}
+    effective_to: "2026-10-20"
+    source_url: "https://..."
+  - op: close_price      # the duplicate's open openrouter-api row
+  - op: add_alias
+    key: {canonical_id: example/model-a, provider: openrouter,
+          alias: example-host/model-a-instruct, channel: openrouter-api}
+    expect: null
+    alias: {provider: openrouter, alias: example-host/model-a-instruct,
+            channel: openrouter-api, effective_from: "2026-10-20", source_url: "https://..."}
+  - op: add_price        # the same rate on example/model-a from 2026-10-20
+```
+
+Gateway discovery matches a spelling only through aliases in effect on the
+observation date, so it follows a moved spelling to its new model.
+
 A price id ends with the UTC date of its row's start. If two rows for one
 model, channel and region would still share an id (possible in a hand-edited
 catalog), each that does not start at UTC midnight also names its UTC start