metaobjects 0.9.0__py3-none-any.whl

metaobjects/datatype.py

@@ -0,0 +1,19 @@
+"""Coarse value-type classification shared across nodes."""
+from __future__ import annotations
+
+from enum import Enum
+
+
+class DataType(str, Enum):
+    STRING = "string"
+    INT = "int"
+    LONG = "long"
+    DOUBLE = "double"
+    # DECIMAL is the exact, Decimal-preserving numeric type (NUMERIC columns).
+    # Distinct from DOUBLE so field.decimal surfaces a native ``Decimal`` (lossless),
+    # never a lossy float — see ADR-0019 + the SP-D runtime return-type contract.
+    DECIMAL = "decimal"
+    BOOLEAN = "boolean"
+    DATE = "date"
+    OBJECT = "object"
+    STRING_ARRAY = "stringArray"

metaobjects/documentation/__init__.py

@@ -0,0 +1,28 @@
+"""Documentation provider — 7 universal common attrs (cross-language parity)."""
+from __future__ import annotations
+
+from .doc_constants import (
+    DOC_ATTR_ALIASES,
+    DOC_ATTR_DEPRECATED,
+    DOC_ATTR_DESCRIPTION,
+    DOC_ATTR_NAMES,
+    DOC_ATTR_NOTES,
+    DOC_ATTR_REPLACED_BY,
+    DOC_ATTR_SEE_ALSO,
+    DOC_ATTR_TITLE,
+)
+from .doc_provider import doc_provider
+from .doc_schema import common_doc_attrs
+
+__all__ = [
+    "DOC_ATTR_DESCRIPTION",
+    "DOC_ATTR_TITLE",
+    "DOC_ATTR_NOTES",
+    "DOC_ATTR_DEPRECATED",
+    "DOC_ATTR_REPLACED_BY",
+    "DOC_ATTR_SEE_ALSO",
+    "DOC_ATTR_ALIASES",
+    "DOC_ATTR_NAMES",
+    "common_doc_attrs",
+    "doc_provider",
+]

metaobjects/documentation/doc_constants.py

@@ -0,0 +1,20 @@
+"""Cross-language doc-attr constants. Bare strings (identical to TS/C#/Java)."""
+from __future__ import annotations
+
+DOC_ATTR_DESCRIPTION = "description"
+DOC_ATTR_TITLE       = "title"
+DOC_ATTR_NOTES       = "notes"
+DOC_ATTR_DEPRECATED  = "deprecated"
+DOC_ATTR_REPLACED_BY = "replacedBy"
+DOC_ATTR_SEE_ALSO    = "seeAlso"
+DOC_ATTR_ALIASES     = "aliases"
+
+DOC_ATTR_NAMES: tuple[str, ...] = (
+    DOC_ATTR_DESCRIPTION,
+    DOC_ATTR_TITLE,
+    DOC_ATTR_NOTES,
+    DOC_ATTR_DEPRECATED,
+    DOC_ATTR_REPLACED_BY,
+    DOC_ATTR_SEE_ALSO,
+    DOC_ATTR_ALIASES,
+)

metaobjects/documentation/doc_provider.py

@@ -0,0 +1,20 @@
+"""The DocumentationProvider — registers the 7 common doc attrs on every metatype."""
+from __future__ import annotations
+
+from ..provider import Provider
+from ..registry import TypeRegistry
+from .doc_schema import common_doc_attrs
+
+
+class _DocProvider(Provider):
+    """Subclass of Provider that also registers common doc attrs into the registry."""
+
+    def register_types(self, registry: TypeRegistry) -> None:
+        super().register_types(registry)
+        registry.register_common_attrs(common_doc_attrs)
+
+
+doc_provider = _DocProvider(
+    "metaobjects-documentation",
+    dependencies=("metaobjects-core-types",),
+)

metaobjects/documentation/doc_schema.py

@@ -0,0 +1,24 @@
+"""The 7 universal doc common attrs as AttrSchema records."""
+from __future__ import annotations
+
+from ..meta.core.attr.attr_constants import ATTR_SUBTYPE_STRING
+from ..registry import AttrSchema
+from .doc_constants import (
+    DOC_ATTR_ALIASES,
+    DOC_ATTR_DEPRECATED,
+    DOC_ATTR_DESCRIPTION,
+    DOC_ATTR_NOTES,
+    DOC_ATTR_REPLACED_BY,
+    DOC_ATTR_SEE_ALSO,
+    DOC_ATTR_TITLE,
+)
+
+common_doc_attrs: list[AttrSchema] = [
+    AttrSchema(name=DOC_ATTR_DESCRIPTION,  value_type=ATTR_SUBTYPE_STRING,      required=False),
+    AttrSchema(name=DOC_ATTR_TITLE,        value_type=ATTR_SUBTYPE_STRING,      required=False),
+    AttrSchema(name=DOC_ATTR_NOTES,        value_type=ATTR_SUBTYPE_STRING,      required=False),
+    AttrSchema(name=DOC_ATTR_DEPRECATED,   value_type=ATTR_SUBTYPE_STRING,      required=False),
+    AttrSchema(name=DOC_ATTR_REPLACED_BY,  value_type=ATTR_SUBTYPE_STRING,      required=False),
+    AttrSchema(name=DOC_ATTR_SEE_ALSO,     value_type=ATTR_SUBTYPE_STRING,      required=False, is_array=True),
+    AttrSchema(name=DOC_ATTR_ALIASES,      value_type=ATTR_SUBTYPE_STRING,      required=False, is_array=True),
+]

metaobjects/errors.py

@@ -0,0 +1,124 @@
+"""Stable error/warning vocabulary. Codes (not messages) are the conformance contract."""
+from __future__ import annotations
+
+from enum import Enum
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:  # avoid runtime import cycles
+    from .source import ErrorSource
+
+
+class ErrorCode(str, Enum):
+    ERR_MALFORMED_JSON = "ERR_MALFORMED_JSON"
+    ERR_TOP_LEVEL_NOT_OBJECT = "ERR_TOP_LEVEL_NOT_OBJECT"
+    ERR_UNKNOWN_TYPE = "ERR_UNKNOWN_TYPE"
+    ERR_UNKNOWN_SUBTYPE = "ERR_UNKNOWN_SUBTYPE"
+    ERR_MISSING_SUBTYPE = "ERR_MISSING_SUBTYPE"
+    ERR_DUPLICATE_NAME = "ERR_DUPLICATE_NAME"
+    ERR_UNRESOLVED_SUPER = "ERR_UNRESOLVED_SUPER"
+    ERR_INVALID_SUBTYPE_CHILD = "ERR_INVALID_SUBTYPE_CHILD"
+    ERR_UNKNOWN_ATTR = "ERR_UNKNOWN_ATTR"
+    ERR_MISSING_REQUIRED_ATTR = "ERR_MISSING_REQUIRED_ATTR"
+    ERR_BAD_ATTR_VALUE = "ERR_BAD_ATTR_VALUE"
+    ERR_BAD_DEFAULT_SORT_FIELD = "ERR_BAD_DEFAULT_SORT_FIELD"
+    ERR_PROVIDER_DEPENDENCY_CYCLE = "ERR_PROVIDER_DEPENDENCY_CYCLE"
+    ERR_PROVIDER_DUPLICATE_ID = "ERR_PROVIDER_DUPLICATE_ID"
+    ERR_PROVIDER_MISSING_DEPENDENCY = "ERR_PROVIDER_MISSING_DEPENDENCY"
+    ERR_PROVIDER_ATTR_CONFLICT = "ERR_PROVIDER_ATTR_CONFLICT"
+    ERR_SUBTYPE_RULE_VIOLATION = "ERR_SUBTYPE_RULE_VIOLATION"
+    ERR_OVERLAY_NO_TARGET = "ERR_OVERLAY_NO_TARGET"
+    # FR5c — two contributing files set the same @attr to different non-empty
+    # values on the same node. Carries a `MergedSource` envelope with both
+    # contributors listed (ADR-0009 §Overlay-merge).
+    ERR_MERGE_CONFLICT = "ERR_MERGE_CONFLICT"
+    ERR_MALFORMED_YAML = "ERR_MALFORMED_YAML"
+    # YAML 1.2 silently coerced an unquoted scalar to a type incompatible with the
+    # declared attr valueType (ADR-0006 D2). Authors should quote the value.
+    ERR_YAML_COERCION = "ERR_YAML_COERCION"
+    ERR_INVALID_ORIGIN = "ERR_INVALID_ORIGIN"
+    # FR-017 — M:N relationship slim-vocabulary validation (junction-missing-two-
+    # references / sourceRefField-not-matching / M:N-attr-on-1:N). The symmetric-
+    # on-hetero + symmetric+sourceRefField rules emit ERR_BAD_ATTR_VALUE instead.
+    ERR_INVALID_RELATIONSHIP = "ERR_INVALID_RELATIONSHIP"
+    ERR_BAD_ATTR_FILTER = "ERR_BAD_ATTR_FILTER"
+    # Reserved structural body key authored as an @-attr (source-v2 / ADR-0007).
+    ERR_RESERVED_ATTR = "ERR_RESERVED_ATTR"
+    # Source-v2 multi-source one-primary rule (ADR-0007).
+    ERR_SOURCE_NO_PRIMARY = "ERR_SOURCE_NO_PRIMARY"
+    ERR_SOURCE_MULTIPLE_PRIMARY = "ERR_SOURCE_MULTIPLE_PRIMARY"
+    # FR-016 / ADR-0018 — per-kind physical-name aliases on source.rdb.
+    ERR_PHYSICAL_NAME_KIND_MISMATCH = "ERR_PHYSICAL_NAME_KIND_MISMATCH"
+    ERR_PHYSICAL_NAME_MULTIPLE = "ERR_PHYSICAL_NAME_MULTIPLE"
+    # FR-013 — field-level @readOnly cross-attribute rules. Cross-language
+    # vocabulary; Python loader does not emit these yet (FR-013 Python fan-out
+    # is a separate workstream), but the enum tracks the shared corpus codes.
+    ERR_READONLY_ASSIGNED_PRIMARY = "ERR_READONLY_ASSIGNED_PRIMARY"
+    ERR_READONLY_DOWNGRADE = "ERR_READONLY_DOWNGRADE"
+    # FR-015 — source.rdb @parameterRef typed-input validation. Cross-language
+    # vocabulary; Python loader does not emit these yet, but the enum tracks
+    # the shared corpus codes.
+    ERR_PARAMETER_REF_UNRESOLVED = "ERR_PARAMETER_REF_UNRESOLVED"
+    ERR_PARAMETER_REF_NOT_VALUE_OBJECT = "ERR_PARAMETER_REF_NOT_VALUE_OBJECT"
+    ERR_PARAMETER_REF_ON_NON_CALLABLE_KIND = "ERR_PARAMETER_REF_ON_NON_CALLABLE_KIND"
+    ERR_PARAMETER_REF_PASSTHROUGH_TYPE_MISMATCH = "ERR_PARAMETER_REF_PASSTHROUGH_TYPE_MISMATCH"
+    # FR-014 — TPH discriminator cross-attribute validation. Cross-language
+    # vocabulary; Python loader does not emit these yet.
+    ERR_DISCRIMINATOR_FIELD_NOT_FOUND = "ERR_DISCRIMINATOR_FIELD_NOT_FOUND"
+    ERR_DISCRIMINATOR_VALUE_DUPLICATE = "ERR_DISCRIMINATOR_VALUE_DUPLICATE"
+    ERR_DISCRIMINATOR_VALUE_MISSING = "ERR_DISCRIMINATOR_VALUE_MISSING"
+    ERR_DISCRIMINATOR_VALUE_TYPE_MISMATCH = "ERR_DISCRIMINATOR_VALUE_TYPE_MISMATCH"
+    # Cross-language vocabulary for features other ports added (FR-003 storage, FR-004 template);
+    # the Python loader does not emit these yet, but the enum tracks the shared corpus codes.
+    ERR_INVALID_TEMPLATE = "ERR_INVALID_TEMPLATE"
+    ERR_STORAGE_FLATTENED_ARRAY = "ERR_STORAGE_FLATTENED_ARRAY"
+    ERR_STORAGE_WITHOUT_OBJECT_REF = "ERR_STORAGE_WITHOUT_OBJECT_REF"
+    # ADR-0013: a field.object REQUIRES @objectRef (open/untyped JSON uses the
+    # physical @dbColumnType: jsonb escape hatch on field.string).
+    ERR_OBJECT_FIELD_WITHOUT_OBJECT_REF = "ERR_OBJECT_FIELD_WITHOUT_OBJECT_REF"
+    ERR_PARTIAL_UNRESOLVED = "ERR_PARTIAL_UNRESOLVED"
+    ERR_REQUIRED_SLOT_UNUSED = "ERR_REQUIRED_SLOT_UNUSED"
+    ERR_VAR_NOT_ON_PAYLOAD = "ERR_VAR_NOT_ON_PAYLOAD"
+    ERR_OUTPUT_TAG_MISSING = "ERR_OUTPUT_TAG_MISSING"
+    # SP-H Unit9 — @filterable: true on a field subtype with no filter-operator
+    # band (e.g. field.object). Would silently generate an empty-ops filter.
+    ERR_FILTERABLE_UNSUPPORTED_SUBTYPE = "ERR_FILTERABLE_UNSUPPORTED_SUBTYPE"
+    # ADR-0023 — a registration was attempted against a registry sealed after its
+    # agreed metamodel-provider bootstrap. Codegen cannot invent metamodel attrs.
+    ERR_REGISTRY_SEALED = "ERR_REGISTRY_SEALED"
+    ERR_UNKNOWN = "ERR_UNKNOWN"
+
+
+class MetaError:
+    """A loader error. ``code`` is the conformance-compared value; ``message`` is human text.
+
+    FR5a / ADR-0009: ``envelope`` is the structured provenance envelope every
+    cross-language port emits — populated by the parser (JSON tree-walk) and by
+    validation passes that have access to a node's ``source``. Legacy ``source``
+    (the file path) / ``path`` remain for backward-compat (the conformance
+    adapter only inspects ``code``); new sites should pass ``envelope``.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        code: ErrorCode = ErrorCode.ERR_UNKNOWN,
+        source: str | None = None,
+        path: str | None = None,
+        envelope: Optional[ErrorSource] = None,
+    ) -> None:
+        self.message = message
+        self.code = code
+        self.source = source
+        self.path = path
+        self.envelope = envelope
+
+    def __repr__(self) -> str:
+        return f"MetaError({self.code.name}: {self.message!r})"
+
+
+class ParseError(Exception):
+    """Raised by the parser in strict mode; carries a code."""
+
+    def __init__(self, message: str, code: ErrorCode = ErrorCode.ERR_UNKNOWN) -> None:
+        super().__init__(message)
+        self.code = code

metaobjects/loader/merge.py

@@ -0,0 +1,287 @@
+"""Multi-file / overlay merge: fold parsed roots into one (post-parse, pre-super-resolve).
+
+FR5c — the merge phase is the cross-port attribution hub. Tracks which
+files contributed to each post-merge node and, on each ``_merge_into``
+call:
+
+  1. **ERR_MERGE_CONFLICT** — same ``@attr`` name set with different
+     non-empty values on both contributors → hard error with a
+     :class:`MergedSource` envelope listing both files and the conflicting
+     attr's jsonPath. Last-writer-wins still applies to the merged tree.
+  2. **MergedSource upgrade** — when the new contributor actually changed
+     the post-merge canonical (semantic_diff returns True), the target's
+     ``source`` envelope is upgraded to :class:`MergedSource` with
+     alphabetically-sorted ``files``/``contributors`` (overlay-base for
+     the first file, overlay-extension for the rest).
+  3. **WARN_DUPLICATE_DECLARATION** — when the new contributor's content
+     produced no semantic change AND the new file isn't already a
+     contributor, emit a warning (string channel + envelope channel).
+     The node's source is NOT upgraded — the warning surfaces the
+     redundancy.
+
+Cross-port contract (TS reference ``parser-core.ts``):
+  * Alphabetical file order across contributors[] (matches DirectorySource
+    sorting).
+  * Single error code ``ERR_MERGE_CONFLICT``; per-attr provenance deferred.
+  * "Conflict" = both sides set, both non-empty, values differ. Empty
+    string and absent are NOT conflicts.
+"""
+from __future__ import annotations
+
+import json
+from typing import Optional
+
+from ..errors import ErrorCode, MetaError
+from ..meta.meta_data import MetaData
+from ..serializer_json import canonical_serialize
+from ..source import (
+    Contributor,
+    ErrorSource,
+    JsonSource,
+    LoaderWarning,
+    MergedSource,
+    WARN_DUPLICATE_DECLARATION,
+    YamlSource,
+)
+from ..source.semantic_diff import semantic_diff
+
+
+def merge_roots(
+    roots: list[MetaData],
+    errors: list[MetaError],
+    warnings: Optional[list[str]] = None,
+    envelope_warnings: Optional[list[LoaderWarning]] = None,
+) -> MetaData:
+    """Merge all roots into the first. Returns the merged root (or raises if empty).
+
+    FR5c — *warnings* and *envelope_warnings*, when provided, receive
+    :data:`WARN_DUPLICATE_DECLARATION` messages for duplicate-with-no-change
+    contributions. They default to throwaway lists to preserve the prior
+    `merge_roots(roots, errors)` two-arg signature for any in-tree caller
+    that hasn't been updated yet.
+    """
+    if not roots:
+        raise ValueError("merge_roots requires at least one root")
+    if warnings is None:
+        warnings = []
+    if envelope_warnings is None:
+        envelope_warnings = []
+    target = roots[0]
+    for src in roots[1:]:
+        _merge_into(target, src, errors, warnings, envelope_warnings)
+    return target
+
+
+def _source_files(env: ErrorSource) -> tuple[str, ...]:
+    """Extract the ``files`` tuple from any envelope that carries one.
+
+    Returns an empty tuple for code / database envelopes (no file context).
+    """
+    if isinstance(env, (JsonSource, YamlSource, MergedSource)):
+        return tuple(env.files)
+    return ()
+
+
+def _source_json_path(env: ErrorSource) -> Optional[str]:
+    """Extract the ``json_path`` from any envelope that carries one."""
+    if isinstance(env, (JsonSource, YamlSource, MergedSource)):
+        return env.json_path
+    return None
+
+
+def _build_contributors(files: tuple[str, ...]) -> tuple[Contributor, ...]:
+    """Build a contributors tuple — first file is overlay-base, rest are
+    overlay-extension. *files* must already be deduplicated + sorted.
+    """
+    return tuple(
+        Contributor(
+            file=f,
+            role="overlay-base" if i == 0 else "overlay-extension",
+        )
+        for i, f in enumerate(files)
+    )
+
+
+def _is_empty_value(v: object) -> bool:
+    """Mirror TS ``isEmptyValue``: ``None``, ``""``, and ``[]`` are empty;
+    everything else is set.
+    """
+    if v is None:
+        return True
+    if isinstance(v, str) and v == "":
+        return True
+    if isinstance(v, list) and not v:
+        return True
+    return False
+
+
+def _attr_values_equal(a: object, b: object) -> bool:
+    """Structural value equality matching TS ``attrValuesEqual``: scalars
+    compared by ``==``; lists/dicts compared key-order-independently via a
+    canonical-key-sorted JSON dump (the same substrate the canonical
+    serializer + semantic_diff use).
+    """
+    if a == b:
+        return True
+    if isinstance(a, (list, dict)) and isinstance(b, (list, dict)):
+        try:
+            return json.dumps(a, sort_keys=True) == json.dumps(b, sort_keys=True)
+        except (TypeError, ValueError):
+            return False
+    return False
+
+
+def _detect_attr_merge_conflicts(
+    target: MetaData,
+    src: MetaData,
+    errors: list[MetaError],
+) -> None:
+    """FR5c — for every own @-attr on *src*, check whether *target* already
+    declares the same attr with a different non-empty value. If so, emit an
+    ``ERR_MERGE_CONFLICT`` carrying a :class:`MergedSource` envelope naming
+    both contributors.
+
+    The merge itself proceeds (last-writer-wins) so the loader sees one
+    canonical tree; the error surfaces the conflict.
+    """
+    target_files = _source_files(target.source)
+    src_files = _source_files(src.source)
+    target_json_path = _source_json_path(target.source)
+
+    pre_attrs: dict[str, object] = {
+        attr.name: getattr(attr, "value", None) for attr in target.own_meta_attrs()
+    }
+
+    for src_attr in src.own_meta_attrs():
+        attr_name = src_attr.name
+        if attr_name not in pre_attrs:
+            continue
+        existing_val = pre_attrs[attr_name]
+        new_val = getattr(src_attr, "value", None)
+
+        if _is_empty_value(new_val) or _is_empty_value(existing_val):
+            continue
+        if _attr_values_equal(existing_val, new_val):
+            continue
+
+        # Conflict — build the MergedSource envelope.
+        combined = sorted(set(target_files) | set(src_files))
+        conflict_files = tuple(combined)
+        attr_path = (
+            f"{target_json_path}.@{attr_name}"
+            if target_json_path
+            else f"@{attr_name}"
+        )
+        envelope = MergedSource(
+            files=conflict_files,
+            json_path=attr_path,
+            contributors=_build_contributors(conflict_files),
+        )
+        errors.append(
+            MetaError(
+                f"attr '@{attr_name}' conflicts: existing value "
+                f"{json.dumps(existing_val)} differs from new value "
+                f"{json.dumps(new_val)} on {target.fqn()}",
+                ErrorCode.ERR_MERGE_CONFLICT,
+                envelope=envelope,
+            )
+        )
+
+
+def _merge_into(
+    target: MetaData,
+    src: MetaData,
+    errors: list[MetaError],
+    warnings: list[str],
+    envelope_warnings: list[LoaderWarning],
+) -> None:
+    """Merge *src*'s own attrs/children into *target* in place.
+
+    FR5c — runs three diagnostics around the merge:
+      1. ``ERR_MERGE_CONFLICT`` on conflicting @-attrs (before the write).
+      2. ``MergedSource`` upgrade when the merge produced semantic change.
+      3. ``WARN_DUPLICATE_DECLARATION`` when no semantic change occurred
+         AND the contributor file is new.
+
+    The root is intentionally excluded from FR5c diagnostics: it is a
+    synthetic accumulator (every file declares ``metadata.root``), not an
+    author-meaningful node. The merge attribution applies to
+    ``object.entity`` / ``field.*`` / etc.
+    """
+    is_root = target.parent is None  # root has no parent
+    fr5c_active = not is_root and target.name != ""
+
+    pre_canonical: Optional[str] = None
+    if fr5c_active:
+        pre_canonical = canonical_serialize(target)
+        _detect_attr_merge_conflicts(target, src, errors)
+
+    # attrs: source overwrites target (last-writer-wins)
+    for attr in src.own_meta_attrs():
+        target.set_attr(attr.name, getattr(attr, "value", None), sub_type=attr.sub_type)
+    # children: merge by (type, name), else append
+    for sc in src.own_children():
+        tc = next(
+            (c for c in target.own_children() if c.type == sc.type and c.name == sc.name),
+            None,
+        )
+        if tc is not None:
+            _merge_into(tc, sc, errors, warnings, envelope_warnings)
+        else:
+            if getattr(sc, "is_overlay", False):
+                errors.append(
+                    MetaError(
+                        f"overlay node '{sc.fqn()}' has no merge target",
+                        ErrorCode.ERR_OVERLAY_NO_TARGET,
+                        path=sc.fqn(),
+                    )
+                )
+            sc.parent = target
+            target.add_child(sc)
+
+    if not fr5c_active or pre_canonical is None:
+        return
+
+    # Post-merge: compare shapes and upgrade source / emit warning.
+    post_canonical = canonical_serialize(target)
+    pre_parsed = json.loads(pre_canonical)
+    post_parsed = json.loads(post_canonical)
+    changed = semantic_diff(pre_parsed, post_parsed)
+
+    existing_env = target.source
+    existing_files = list(_source_files(existing_env))
+    src_files = list(_source_files(src.source))
+    json_path = _source_json_path(existing_env)
+
+    new_contributor_file = src_files[0] if src_files else "<unknown>"
+
+    if changed:
+        all_files = sorted(set(existing_files + src_files))
+        merged_files = tuple(all_files)
+        merged_env = MergedSource(
+            files=merged_files,
+            json_path=json_path if json_path is not None else "$",
+            contributors=_build_contributors(merged_files),
+        )
+        target.set_source(merged_env)
+    elif existing_files and new_contributor_file not in existing_files:
+        # Identical re-declaration from a different file → warn.
+        all_files = sorted(set(existing_files + [new_contributor_file]))
+        warn_files = tuple(all_files)
+        warn_env = MergedSource(
+            files=warn_files,
+            json_path=json_path if json_path is not None else "$",
+            contributors=_build_contributors(warn_files),
+        )
+        message = f"duplicate declaration of {target.fqn()} with no semantic change"
+        # Legacy string channel — what the conformance runner checks against
+        # expected-warnings.json (a list[str]).
+        warnings.append(message)
+        # Envelope channel — typed code + source for downstream tooling.
+        envelope_warnings.append(
+            LoaderWarning(
+                code=WARN_DUPLICATE_DECLARATION,
+                message=message,
+                source=warn_env,
+            )
+        )