metaobjects 0.9.0__py3-none-any.whl

metaobjects/runtime/tph.py

@@ -0,0 +1,50 @@
+"""FR-017 — table-per-hierarchy (TPH) discriminator resolution for the runtime.
+
+A TPH SUBTYPE is an entity that declares ``@discriminatorValue`` and ``extends``
+(transitively) a base that declares ``@discriminator``. The ObjectManager uses
+this to:
+  - inject the discriminator value on create (the entity names the subtype; the
+    caller never sets it);
+  - scope every read/update/delete to the subtype (a row of a different subtype
+    is invisible), mirroring the generated per-subtype route's cross-subtype 404;
+  - treat the discriminator as immutable (stripped from update patches).
+
+The discriminator FIELD name lives on the base (``@discriminator``); the VALUE
+lives on the subtype (``@discriminatorValue``). For deep hierarchies the base may
+be any ancestor, so we walk the resolved super chain to find it.
+
+Mirrors the TS reference ``runtime-ts/src/tph.ts``.
+"""
+from __future__ import annotations
+
+from typing import NamedTuple
+
+from metaobjects.meta.core.object.object_constants import (
+    OBJECT_ATTR_DISCRIMINATOR,
+    OBJECT_ATTR_DISCRIMINATOR_VALUE,
+)
+from metaobjects.meta.meta_data import MetaData
+
+
+class TphSubtype(NamedTuple):
+    #: The discriminator field NAME (declared on the base via ``@discriminator``).
+    field: str
+    #: This subtype's discriminator VALUE (declared via ``@discriminatorValue``).
+    value: str
+
+
+def tph_subtype_of(entity: MetaData) -> TphSubtype | None:
+    """If *entity* is a TPH subtype, return its discriminator field + value; else
+    ``None``. A subtype declares ``@discriminatorValue`` (own attr) and inherits
+    ``@discriminator`` from an ancestor in its resolved super chain.
+    """
+    value = entity.attr(OBJECT_ATTR_DISCRIMINATOR_VALUE)  # own attr
+    if value is None:
+        return None
+    ancestor = entity.super_data
+    while ancestor is not None:
+        field = ancestor.attr(OBJECT_ATTR_DISCRIMINATOR)  # own attr on the base
+        if field is not None:
+            return TphSubtype(field=str(field), value=str(value))
+        ancestor = ancestor.super_data
+    return None

metaobjects/serializer_json.py

@@ -0,0 +1,172 @@
+"""Canonical (fused-key) serializer. Deterministic per spec/conformance-tests.md."""
+from __future__ import annotations
+
+import json
+
+from .meta.meta_data import MetaData
+from .meta.persistence.source.source_constants import (
+    DEFAULT_SOURCE_KIND,
+    PHYSICAL_NAME_ATTR_BY_KIND,
+    SOURCE_ATTR_KIND,
+    SOURCE_ATTR_TABLE,
+    SOURCE_SUBTYPE_RDB,
+)
+from .shared.base_types import TYPE_SOURCE
+from .shared.separators import ATTR_PREFIX, FUSED_KEY_SEP
+from .shared.structural import (
+    KEY_ABSTRACT,
+    KEY_CHILDREN,
+    KEY_EXTENDS,
+    KEY_IS_ARRAY,
+    KEY_NAME,
+    KEY_PACKAGE,
+)
+
+_SOURCE_RDB_FUSED_KEY = f"{TYPE_SOURCE}{FUSED_KEY_SEP}{SOURCE_SUBTYPE_RDB}"
+
+
+def canonical_serialize(node: MetaData) -> str:
+    return _serialize(node, effective=False)
+
+
+def canonical_serialize_effective(node: MetaData) -> str:
+    """Like :func:`canonical_serialize`, but emits the EFFECTIVE tree —
+    ``children()`` + ``attrs()`` at every node (own + inherited via the super
+    chain), so the super-chain merge is materialized in the output.
+
+    Used by the conformance harness's ``expected-effective.json`` fixtures.
+    Mirrors the TS reference ``canonicalSerializeEffective``: ``extends`` is
+    still emitted on every node (the ref stays in the body), but inherited
+    members are inlined rather than referenced.
+    """
+    return _serialize(node, effective=True)
+
+
+def _serialize(node: MetaData, effective: bool) -> str:
+    parsed = _to_canonical(node, effective)
+    # FR-016 / ADR-0018 — rewrite legacy @table → kind-matching alias on
+    # source.rdb wrappers; run before serialization so the rewritten key sorts
+    # naturally with the rest of the body (alphabetical at our depth).
+    _rewrite_source_rdb_physical_names(parsed)
+    text = json.dumps(parsed, indent=2, ensure_ascii=False)
+    return text + "\n"
+
+
+def _to_canonical(node: MetaData, effective: bool = False) -> dict[str, object]:
+    return {f"{node.type}{FUSED_KEY_SEP}{node.sub_type}": _body(node, effective)}
+
+
+def _body(node: MetaData, effective: bool = False) -> dict[str, object]:
+    body: dict[str, object] = {}
+    if node.name:
+        body[KEY_NAME] = node.name
+    if node.package:
+        body[KEY_PACKAGE] = node.package
+    if node.super_ref:
+        body[KEY_EXTENDS] = node.super_ref
+    if node.is_abstract:
+        body[KEY_ABSTRACT] = True
+    if node.is_array:
+        body[KEY_IS_ARRAY] = True
+
+    # In effective mode use attrs()/children() (own + inherited via the super
+    # chain); in own mode use own_meta_attrs()/own_children() (declared here).
+    if effective:
+        for name in sorted(node.attrs()):
+            body[f"{ATTR_PREFIX}{name}"] = _normalize(node.attrs()[name])
+    else:
+        for attr in sorted(node.own_meta_attrs(), key=lambda a: a.name):
+            body[f"{ATTR_PREFIX}{attr.name}"] = _normalize(getattr(attr, "value", None))
+
+    children = node.children() if effective else node.own_children()
+    if children:
+        body[KEY_CHILDREN] = [_to_canonical(c, effective) for c in children]
+    return body
+
+
+def _rewrite_source_rdb_physical_names(value: object) -> None:
+    """FR-016 / ADR-0018 — rewrite legacy ``@table`` on source.rdb wrappers
+    whose ``@kind`` is non-table to the kind-matching alias
+    (``@view`` / ``@materializedView`` / ``@proc`` / ``@function``).
+
+    Mutates the parsed JSON in place; idempotent and a no-op for canonical
+    inputs (mirrors the TS reference ``rewriteSourceRdbPhysicalNames``).
+    """
+    if isinstance(value, list):
+        for item in value:
+            _rewrite_source_rdb_physical_names(item)
+        return
+    if not isinstance(value, dict):
+        return
+
+    rdb_body = value.get(_SOURCE_RDB_FUSED_KEY)
+    if isinstance(rdb_body, dict):
+        kind_raw = rdb_body.get(f"{ATTR_PREFIX}{SOURCE_ATTR_KIND}")
+        kind = kind_raw if isinstance(kind_raw, str) and kind_raw else DEFAULT_SOURCE_KIND
+        canonical_alias = PHYSICAL_NAME_ATTR_BY_KIND.get(kind)
+        if canonical_alias is not None and canonical_alias != SOURCE_ATTR_TABLE:
+            legacy_key = f"{ATTR_PREFIX}{SOURCE_ATTR_TABLE}"
+            canonical_key = f"{ATTR_PREFIX}{canonical_alias}"
+            legacy_value = rdb_body.get(legacy_key)
+            if legacy_value is not None and canonical_key not in rdb_body:
+                # Re-insert in alphabetical position by rebuilding the dict.
+                new_body: dict[str, object] = {}
+                # The rewrite changes the key — preserve original insertion
+                # order semantics by walking, swapping in the canonical key in
+                # @table's slot, then re-sorting only the @-prefixed keys.
+                for k, v in rdb_body.items():
+                    if k == legacy_key:
+                        continue
+                    new_body[k] = v
+                new_body[canonical_key] = legacy_value
+                # Restore structural-then-attr ordering with attrs alphabetically.
+                struct_keys = [
+                    KEY_NAME, KEY_PACKAGE, KEY_EXTENDS,
+                    KEY_ABSTRACT, KEY_IS_ARRAY,
+                ]
+                ordered: dict[str, object] = {}
+                for k in struct_keys:
+                    if k in new_body:
+                        ordered[k] = new_body[k]
+                attr_keys = sorted(
+                    k for k in new_body
+                    if k.startswith(ATTR_PREFIX)
+                )
+                for k in attr_keys:
+                    ordered[k] = new_body[k]
+                if KEY_CHILDREN in new_body:
+                    ordered[KEY_CHILDREN] = new_body[KEY_CHILDREN]
+                rdb_body.clear()
+                rdb_body.update(ordered)
+
+    # Recurse through every value (in particular ``children``).
+    for v in value.values():
+        _rewrite_source_rdb_physical_names(v)
+
+
+_SCALAR_TYPES = (str, int, float, bool, type(None))
+
+
+def _normalize(value: object) -> object:
+    """Mirror JSON.stringify: a whole-number float serializes as an int.
+
+    Object-valued attrs need different key order in canonical form, and the
+    serializer is schema-free — so distinguish by value shape, which exactly
+    tracks the object-attr subtypes:
+      * `properties` (e.g. @enumDoc / @enumAlias) is a flat scalar->scalar map ->
+        keys sort ordinally (cross-port canonical form; matches the Java
+        reference, whose Properties is unordered and serializes sorted).
+      * `filter` maps a field to an operator object ({eq:...}/{in:[...]}) — at
+        least one value is itself a dict/list -> declaration order is preserved
+        (significant). The FilterAttr desugar runs at set_value time, so filter
+        values are always op-object dicts before serialization reaches here.
+    """
+    if isinstance(value, float) and value.is_integer():
+        return int(value)
+    if isinstance(value, list):
+        return [_normalize(v) for v in value]
+    if isinstance(value, dict):
+        all_scalar = all(isinstance(v, _SCALAR_TYPES) for v in value.values())
+        items = sorted(value.items()) if all_scalar else value.items()
+        return {k: _normalize(v) for k, v in items}
+    return value

metaobjects/shared/base_types.py

@@ -0,0 +1,16 @@
+"""The base metamodel type names + the shared base/root subtype names."""
+TYPE_METADATA = "metadata"
+TYPE_OBJECT = "object"
+TYPE_FIELD = "field"
+TYPE_ATTR = "attr"
+TYPE_VALIDATOR = "validator"
+TYPE_IDENTITY = "identity"
+TYPE_RELATIONSHIP = "relationship"
+TYPE_VIEW = "view"
+TYPE_LAYOUT = "layout"
+TYPE_SOURCE = "source"
+TYPE_ORIGIN = "origin"
+TYPE_TEMPLATE = "template"
+
+SUBTYPE_BASE = "base"
+SUBTYPE_ROOT = "root"

metaobjects/shared/separators.py

@@ -0,0 +1,4 @@
+"""Structural separators shared across the metamodel (Tier-1 vocabulary)."""
+ATTR_PREFIX = "@"
+PACKAGE_SEP = "::"
+FUSED_KEY_SEP = "."

metaobjects/shared/structural.py

@@ -0,0 +1,9 @@
+"""Reserved structural body keys (NOT @-attrs). Documented order in conformance-tests.md."""
+KEY_NAME = "name"
+KEY_PACKAGE = "package"
+KEY_EXTENDS = "extends"
+KEY_ABSTRACT = "abstract"
+KEY_OVERLAY = "overlay"
+KEY_IS_ARRAY = "isArray"
+KEY_CHILDREN = "children"
+KEY_VALUE = "value"

metaobjects/source/__init__.py

@@ -0,0 +1,79 @@
+"""FR5a / ADR-0009 — Loader error envelope + source-on-node.
+
+Cross-port-aligned types: every metaobjects port emits the same envelope shape
+so a tool consuming errors from multiple language ports can compare them
+byte-identically.
+
+Public surface re-exported here:
+    * ErrorSource hierarchy (abstract base + 6 variants).
+    * JsonPathBuilder + JsonPath helpers (canonical JSONPath construction).
+    * LoaderError / LoaderWarning / NodeContext / Contributor envelope types.
+    * semantic_diff(a, b) for FR5c overlay-merge consumption.
+
+See `docs/superpowers/specs/2026-05-25-fr5a-json-shape-loader-errors.md` and
+`spec/decisions/ADR-0009-loader-error-envelope-and-source-on-node.md`.
+"""
+from __future__ import annotations
+
+from .error_source import (
+    CodeSource,
+    Contributor,
+    DatabaseSource,
+    DbLocation,
+    ErrorSource,
+    JsonSource,
+    LoaderError,
+    LoaderWarning,
+    MergedSource,
+    NodeContext,
+    ResolvedSource,
+    WARN_DUPLICATE_DECLARATION,
+    WARN_LEGACY,
+    WARN_LEGACY_PHYSICAL_NAME_ALIAS,
+    YamlPosition,
+    YamlSource,
+    resolved_source,
+)
+from .json_path import JsonPath, JsonPathBuilder
+from .semantic_diff import semantic_diff
+from .yaml_positions import (
+    YamlPositionMap,
+    get_position_map,
+    get_yaml_position,
+    parse_yaml_with_positions,
+    set_position_map,
+)
+
+__all__ = [
+    # ErrorSource hierarchy
+    "ErrorSource",
+    "JsonSource",
+    "YamlSource",
+    "MergedSource",
+    "ResolvedSource",
+    "resolved_source",
+    "DatabaseSource",
+    "CodeSource",
+    # Supporting types
+    "Contributor",
+    "DbLocation",
+    "NodeContext",
+    "YamlPosition",
+    "LoaderError",
+    "LoaderWarning",
+    # FR5c — warning code constants
+    "WARN_DUPLICATE_DECLARATION",
+    "WARN_LEGACY",
+    "WARN_LEGACY_PHYSICAL_NAME_ALIAS",
+    # JSONPath
+    "JsonPathBuilder",
+    "JsonPath",
+    # Semantic diff
+    "semantic_diff",
+    # FR5b — YAML positions
+    "YamlPositionMap",
+    "get_position_map",
+    "get_yaml_position",
+    "set_position_map",
+    "parse_yaml_with_positions",
+]

metaobjects/source/error_source.py

@@ -0,0 +1,266 @@
+"""FR5a / ADR-0009 — ErrorSource discriminated union + envelope types.
+
+Closed hierarchy over the provenance variants a metadata node or error can
+carry. The cross-port realization in Python uses ``@dataclass(frozen=True)`` so
+each variant is value-equal, hashable, and immutable.
+
+Pattern-match on the concrete subtype (``isinstance(src, JsonSource)``) to
+access variant-specific fields, or read ``src.format`` for the discriminant
+tag.
+
+Mirrors:
+    * TS  — `server/typescript/packages/metadata/src/source.ts`
+    * C#  — `server/csharp/MetaObjects/Source/ErrorSource.cs`
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import ClassVar, Optional
+
+
+# ---------------------------------------------------------------------------
+# Discriminated union: ErrorSource hierarchy
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class ErrorSource:
+    """Provenance envelope for a metadata node or loader error.
+
+    Abstract base — never instantiated directly. Every concrete variant
+    declares a class-level ``format`` constant that names its discriminant tag
+    in the cross-port wire shape.
+    """
+
+    # Subclasses override this class-level constant. Declared here as a
+    # placeholder so static type-checkers see a string attribute on the base.
+    format: ClassVar[str] = ""
+
+
+@dataclass(frozen=True)
+class YamlPosition:
+    """Optional YAML line/col source position (FR5b). 1-based."""
+
+    line: int
+    col: int
+
+
+@dataclass(frozen=True)
+class JsonSource(ErrorSource):
+    """Authoring-time: single JSON file (FR5a).
+
+    Args:
+        files: Length-1 tuple of project-root-relative file paths. The FR5a
+            invariant guarantees exactly one file — multi-file provenance lives
+            on :class:`MergedSource` (FR5c). Enforced at construction.
+        json_path: Canonical JSONPath string for the node within ``files[0]``.
+        yaml_position: FR5b — optional YAML line/col position. Populated by
+            the YAML loader when the JSON document was authored as YAML; for
+            cross-port-safety, the envelope's ``format`` discriminator stays
+            ``"json"`` (so the yaml-conformance fixtures stay byte-stable
+            until all four ports ship FR5b and the discriminator flips to
+            ``"yaml"``). See TS reference (server/typescript/packages/metadata/
+            src/source.ts) for the rationale.
+    """
+
+    files: tuple[str, ...]
+    json_path: str
+    yaml_position: Optional[YamlPosition] = None
+    format: ClassVar[str] = "json"
+
+    def __post_init__(self) -> None:
+        # FR5a invariant: exactly one file. Multi-file provenance is
+        # MergedSource (FR5c) territory; enforce here so the type can be
+        # trusted by cross-port comparison.
+        if len(self.files) != 1:
+            raise ValueError(
+                f"JsonSource requires exactly one file path; got {len(self.files)}. "
+                "Use MergedSource for multi-file provenance."
+            )
+
+
+@dataclass(frozen=True)
+class YamlSource(ErrorSource):
+    """Authoring-time: single YAML file with optional source-map positions (FR5b)."""
+
+    files: tuple[str, ...]
+    json_path: str
+    yaml_position: Optional[YamlPosition] = None
+    format: ClassVar[str] = "yaml"
+
+
+@dataclass(frozen=True)
+class Contributor:
+    """One contributor in a :class:`MergedSource`.
+
+    Args:
+        file: Path to the contributing file (project-root relative; forward slashes).
+        role: One of ``"overlay-base"``, ``"overlay-extension"``,
+            ``"extends-base"``, ``"extends-extension"``.
+    """
+
+    file: str
+    role: str
+
+
+@dataclass(frozen=True)
+class MergedSource(ErrorSource):
+    """Post-load: overlay merge that produced semantic change (FR5c)."""
+
+    files: tuple[str, ...]
+    json_path: str
+    contributors: tuple[Contributor, ...]
+    format: ClassVar[str] = "merged"
+
+
+@dataclass(frozen=True)
+class ResolvedSource(ErrorSource):
+    """Post-load: extends / @via / @objectRef / @payloadRef resolution failure (FR5d)."""
+
+    files: tuple[str, ...]
+    json_path: Optional[str] = None
+    referrer: Optional[str] = None
+    target: Optional[str] = None
+    format: ClassVar[str] = "resolved"
+
+
+def resolved_source(
+    referrer_source: ErrorSource,
+    referrer: str,
+    target: str,
+) -> ResolvedSource:
+    """FR5d — build a ``ResolvedSource`` envelope from a referrer node's source
+    envelope (typically a parse-time JsonSource / YamlSource) plus the referrer
+    FQN and the unresolved target string.
+
+    Mirrors TS ``resolvedSource()`` (server/typescript/packages/metadata/src/
+    source.ts). The resolved envelope carries:
+
+      * ``files``: the referrer's source files (best-effort — for json/yaml/
+        merged variants this is the referrer's files tuple; for code/database
+        variants, an empty tuple).
+      * ``json_path``: the referrer's json_path when known (the location of the
+        broken reference on disk).
+      * ``referrer``: the FQN of the metadata node that declared the broken
+        reference (e.g. ``"myapp::content::Video"``).
+      * ``target``: the unresolved reference string itself (e.g. ``"BaseEntity"``,
+        ``"Program.weeks.invalid"``).
+    """
+    if isinstance(referrer_source, (JsonSource, YamlSource, MergedSource, ResolvedSource)):
+        files = tuple(referrer_source.files)
+        json_path = referrer_source.json_path
+    else:
+        # CodeSource / DatabaseSource / abstract base — no files/json_path to plumb.
+        files = ()
+        json_path = None
+    return ResolvedSource(
+        files=files,
+        json_path=json_path,
+        referrer=referrer,
+        target=target,
+    )
+
+
+@dataclass(frozen=True)
+class DbLocation:
+    """Database location for a node sourced from a row."""
+
+    table: str
+    id: str
+
+
+@dataclass(frozen=True)
+class DatabaseSource(ErrorSource):
+    """Future: database-sourced metadata (FR5e, gated on FR-003)."""
+
+    db_location: DbLocation
+    json_path: Optional[str] = None
+    format: ClassVar[str] = "database"
+
+
+@dataclass(frozen=True)
+class CodeSource(ErrorSource):
+    """Programmatic / test construction.
+
+    The default for any node not built by a loader phase. Mirrors TS
+    ``codeSource(caller?)``.
+
+    Args:
+        caller: Optional human label (e.g. ``"QueriesTest.makePost"``).
+    """
+
+    caller: Optional[str] = None
+    format: ClassVar[str] = "code"
+
+    # Canonical singleton for the no-caller case (mirrors C# `CodeSource.Default`).
+    # The actual assignment lives below — Python doesn't allow self-reference in
+    # the dataclass body.
+    DEFAULT: ClassVar[CodeSource]
+
+
+CodeSource.DEFAULT = CodeSource(caller=None)
+
+
+# ---------------------------------------------------------------------------
+# Envelope types: error / warning structures
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class NodeContext:
+    """Optional structural context attached to a loader error.
+
+    RECOMMENDED per ADR-0009; conformance does not enforce population.
+    """
+
+    type: Optional[str] = None
+    sub_type: Optional[str] = None
+    name: Optional[str] = None
+    fqn: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class LoaderError:
+    """Envelope shape every loader error conforms to. ADR-0009 §Decision.
+
+    ``code``, ``message`` and ``source`` are REQUIRED (conformance-enforced).
+    The remaining fields are RECOMMENDED; FR5a does not populate them, FR5b–FR5e
+    may.
+    """
+
+    code: str
+    message: str
+    source: ErrorSource
+    suggestions: tuple[str, ...] = field(default_factory=tuple)
+    fixture: Optional[str] = None
+    node: Optional[NodeContext] = None
+
+
+@dataclass(frozen=True)
+class LoaderWarning:
+    """Warning envelope — same shape as :class:`LoaderError` but a ``WARN_*`` code.
+
+    Today's initial warning codes:
+        * ``WARN_DUPLICATE_DECLARATION`` — emitted by overlay-merge when a
+          duplicate-with-no-change is detected (FR5c).
+        * ``WARN_LEGACY`` — legacy ``warnings: list[str]`` messages wrapped at
+          the loader boundary so the envelope channel is uniform.
+    """
+
+    code: str
+    message: str
+    source: ErrorSource
+    suggestions: tuple[str, ...] = field(default_factory=tuple)
+    fixture: Optional[str] = None
+    node: Optional[NodeContext] = None
+
+
+# FR5c — string constants for warning codes. Mirrors the TS WARNING_CODES
+# export. Keeping the values aligned across ports is part of the conformance
+# contract.
+WARN_DUPLICATE_DECLARATION: str = "WARN_DUPLICATE_DECLARATION"
+WARN_LEGACY: str = "WARN_LEGACY"
+#: FR-016 / ADR-0018 — emitted when a source.rdb uses the pre-1.0 ``@table``
+#: spelling with a non-table ``@kind`` (e.g. ``@kind: "view"`` + ``@table``).
+#: Loader accepts; the canonical serializer rewrites to the kind-matching alias.
+WARN_LEGACY_PHYSICAL_NAME_ALIAS: str = "WARN_LEGACY_PHYSICAL_NAME_ALIAS"