metaobjects 0.9.0__py3-none-any.whl

metaobjects/meta/core/relationship/meta_relationship.py

@@ -0,0 +1,54 @@
+"""MetaRelationship — relationship.association / aggregation / composition node."""
+from __future__ import annotations
+
+from ...meta_data import MetaData
+from .relationship_constants import (
+    RELATIONSHIP_ATTR_CARDINALITY,
+    RELATIONSHIP_ATTR_OBJECT_REF,
+    RELATIONSHIP_ATTR_ON_DELETE,
+    RELATIONSHIP_ATTR_ON_UPDATE,
+    RELATIONSHIP_ATTR_SOURCE_REF_FIELD,
+    RELATIONSHIP_ATTR_SYMMETRIC,
+    RELATIONSHIP_ATTR_THROUGH,
+)
+
+
+class MetaRelationship(MetaData):
+    """A relationship.* node. Accessors mirror the TS reference / Java port —
+    own-attr reads; defaults for @onDelete/@onUpdate are resolved at consumption
+    time (codegen / migration) not here."""
+
+    def cardinality(self) -> str | None:
+        v = self.attr(RELATIONSHIP_ATTR_CARDINALITY)
+        return v if isinstance(v, str) else None
+
+    def object_ref(self) -> str | None:
+        """FQN of the target object (e.g., ``"acme::vehicle::Car"``)."""
+        v = self.attr(RELATIONSHIP_ATTR_OBJECT_REF)
+        return v if isinstance(v, str) else None
+
+    def through(self) -> str | None:
+        """Junction (through) entity name for M:N relationships."""
+        v = self.attr(RELATIONSHIP_ATTR_THROUGH)
+        return v if isinstance(v, str) else None
+
+    def source_ref_field(self) -> str | None:
+        """Source-side FK field on the junction (directed self-join disambiguator)."""
+        v = self.attr(RELATIONSHIP_ATTR_SOURCE_REF_FIELD)
+        return v if isinstance(v, str) else None
+
+    def symmetric(self) -> bool:
+        """Whether this M:N relationship is an undirected (symmetric) self-join."""
+        return self.attr(RELATIONSHIP_ATTR_SYMMETRIC) is True
+
+    def on_delete(self) -> str | None:
+        """Referential action on parent delete. ``None`` when not explicitly set
+        (default derives from subtype at consumption time)."""
+        v = self.attr(RELATIONSHIP_ATTR_ON_DELETE)
+        return v if isinstance(v, str) and v else None
+
+    def on_update(self) -> str | None:
+        """Referential action on key update. ``None`` when not explicitly set
+        (default: cascade at consumption time)."""
+        v = self.attr(RELATIONSHIP_ATTR_ON_UPDATE)
+        return v if isinstance(v, str) and v else None

metaobjects/meta/core/relationship/relationship_constants.py

@@ -0,0 +1,51 @@
+"""Relationship subtype vocabulary (colocated)."""
+from ....shared.base_types import SUBTYPE_BASE
+
+RELATIONSHIP_SUBTYPE_ASSOCIATION = "association"
+RELATIONSHIP_SUBTYPE_AGGREGATION = "aggregation"
+RELATIONSHIP_SUBTYPE_COMPOSITION = "composition"
+
+RELATIONSHIP_SUBTYPES = (
+    SUBTYPE_BASE,
+    RELATIONSHIP_SUBTYPE_ASSOCIATION,
+    RELATIONSHIP_SUBTYPE_AGGREGATION,
+    RELATIONSHIP_SUBTYPE_COMPOSITION,
+)
+
+RELATIONSHIP_ATTR_OBJECT_REF = "objectRef"
+RELATIONSHIP_ATTR_CARDINALITY = "cardinality"
+# M:N junction (through) entity — a third entity declaring two identity.reference
+# children, one per FK side. The relationship's FK fields are DERIVED from those
+# references (the identity.reference SSOT for FK direction), never restated.
+RELATIONSHIP_ATTR_THROUGH = "through"
+# M:N directed-self-join disambiguator — names the source-side FK field on the
+# junction (the other reference is the target side). Mutually exclusive with
+# @symmetric.
+RELATIONSHIP_ATTR_SOURCE_REF_FIELD = "sourceRefField"
+# M:N undirected-self-join flag — union-on-read; valid only when @objectRef ==
+# the declaring entity. Mutually exclusive with @sourceRefField.
+RELATIONSHIP_ATTR_SYMMETRIC = "symmetric"
+
+# Cardinality values (for @cardinality). Open string at the metamodel level; the
+# CARDINALITY_MANY constant gates M:N validation/derivation.
+CARDINALITY_ONE = "one"
+CARDINALITY_MANY = "many"
+
+# --- Referential action attrs (@onDelete / @onUpdate) ----------------------
+
+RELATIONSHIP_ATTR_ON_DELETE = "onDelete"
+RELATIONSHIP_ATTR_ON_UPDATE = "onUpdate"
+
+# Canonical cross-language referential-action set (kebab-case, no "setDefault").
+# MUST equal TS migrate-ts FkAction; mirrors Java REFERENTIAL_ACTIONS.
+REFERENTIAL_ACTIONS = ("cascade", "set-null", "restrict", "no-action")
+
+# Default @onDelete per relationship subtype (rollout-decided defaults).
+ON_DELETE_DEFAULT_BY_SUBTYPE: dict[str, str] = {
+    RELATIONSHIP_SUBTYPE_COMPOSITION: "cascade",
+    RELATIONSHIP_SUBTYPE_AGGREGATION: "set-null",
+    RELATIONSHIP_SUBTYPE_ASSOCIATION: "restrict",
+}
+
+# Default @onUpdate (subtype-independent).
+ON_UPDATE_DEFAULT = "cascade"

metaobjects/meta/core/validator/validator_constants.py

@@ -0,0 +1,18 @@
+"""Validator subtype + attr vocabulary (colocated).
+
+Mirrors server/typescript/packages/metadata/src/core/validator/validator-constants.ts.
+These are the cross-port-identical names for the ``validator.*`` type family and the
+attrs codegen reads when emitting input-validation constraints.
+"""
+
+# Validator subtypes (peer of TS VALIDATOR_SUBTYPES).
+VALIDATOR_SUBTYPE_REQUIRED = "required"
+VALIDATOR_SUBTYPE_LENGTH = "length"
+VALIDATOR_SUBTYPE_REGEX = "regex"
+VALIDATOR_SUBTYPE_NUMERIC = "numeric"
+VALIDATOR_SUBTYPE_ARRAY = "array"
+
+# Validator attr keys (read by codegen when lowering validator children).
+VALIDATOR_ATTR_MIN = "min"
+VALIDATOR_ATTR_MAX = "max"
+VALIDATOR_ATTR_PATTERN = "pattern"

metaobjects/meta/meta_data.py

@@ -0,0 +1,206 @@
+"""Abstract node base — Python port of the typed-tree MetaData (ADR-0002)."""
+from __future__ import annotations
+
+from typing import Callable, Optional, TypeVar, cast
+
+from ..attr_class_map import attr_class_for
+from ..shared.base_types import SUBTYPE_BASE, TYPE_ATTR
+from ..shared.separators import PACKAGE_SEP
+from ..source import CodeSource, ErrorSource
+
+T = TypeVar("T")
+
+
+class MetaData:
+    def __init__(self, type_: str, sub_type: str, name: str) -> None:
+        self.type = type_
+        self.sub_type = sub_type
+        self.name = name
+        self.package: Optional[str] = None
+        # The file-default package captured at PARSE time (the package declared
+        # on the owning file's root). Distinct from ``package`` (which an object
+        # node leaves unset — the parser does not fold the file-default package
+        # onto an object's own package). Used by super-resolution to match a
+        # cross-package fully-qualified ``extends`` over the MERGED tree, where
+        # per-file root packages are no longer reachable via the parent chain.
+        # Mirrors TS ``MetaData.fileDefaultPackage`` / ``resolutionKey()``.
+        self.file_default_package: Optional[str] = None
+        self.super_ref: Optional[str] = None
+        self.super_data: Optional[MetaData] = None
+        self.is_abstract = False
+        self.is_overlay = False
+        self.is_array = False
+        self.parent: Optional[MetaData] = None
+        self._attr_nodes: dict[str, MetaData] = {}  # name -> MetaAttr instance
+        self._children: list[MetaData] = []
+        self._cache: dict[str, object] = {}
+        self._frozen = False
+        # FR5a / ADR-0009 — provenance envelope. Always populated; defaults
+        # to CodeSource for programmatic / test construction. Loader phases
+        # (parser, merge) overwrite via set_source during the tree walk.
+        self._source: ErrorSource = CodeSource.DEFAULT
+
+    @property
+    def frozen(self) -> bool:
+        return self._frozen
+
+    @property
+    def source(self) -> ErrorSource:
+        """FR5a / ADR-0009 — provenance envelope for this node. Always populated."""
+        return self._source
+
+    def set_source(self, src: ErrorSource) -> None:
+        """Loader-internal: assign provenance. Honors the frozen-guard.
+
+        Called by parser / merge phases as they build the tree. Programmatic
+        callers (tests, plugins) may pass any envelope explicitly.
+        """
+        self._require_mutable()
+        self._source = src
+
+    def fqn(self) -> str:
+        """Own FQN: ``package::name`` if own package is set, else just ``name``."""
+        return self.name if not self.package else f"{self.package}{PACKAGE_SEP}{self.name}"
+
+    def resolution_key(self) -> str:
+        """Package-folded FQN: ``<pkg>::<name>`` where *pkg* is, in order:
+
+          1. this node's own ``package`` (when declared), else
+          2. its ``file_default_package`` (the file's root package captured at
+             PARSE time), else
+          3. the nearest ancestor's ``package`` (a programmatic fallback for
+             hand-built trees / plugins).
+
+        Returns the bare name when none is available.
+
+        This is the Python equivalent of the C#/TS ``ResolutionKey`` and is
+        consistent with the #37 super-resolution fix (``node.package or
+        node.file_default_package or ctx_pkg``). It is the package-folded form a
+        nested field's ``@objectRef`` uses AND the key the runtime object model
+        binds on (``ObjectClassRegistry`` / ``MetaObject.new_instance``). Distinct
+        from ``fqn()``, which stays bare for objects (the parser does not fold the
+        file-default package onto an object's own ``package``).
+
+        The ``file_default_package`` step is load-bearing: after a multi-file
+        MERGE an object node carries no own ``package`` and its parent is the
+        single merged root (also package-less), so the ancestor walk alone would
+        fall through to the bare name and bind the WRONG (package-less) registry
+        key. Folding the file-default package keeps the binding correct
+        regardless of merge order.
+        """
+        pkg = self.package or self.file_default_package
+        if not pkg:
+            node = self.parent
+            while node is not None:
+                if node.package:
+                    pkg = node.package
+                    break
+                node = node.parent
+        if pkg:
+            return f"{pkg}{PACKAGE_SEP}{self.name}"
+        return self.name
+
+    def _require_mutable(self) -> None:
+        if self._frozen:
+            raise RuntimeError(f"Cannot mutate frozen MetaData {self.fqn()}")
+
+    def set_attr(self, name: str, value: object, sub_type: str | None = None) -> None:
+        self._require_mutable()
+        resolved_sub = sub_type if sub_type is not None else SUBTYPE_BASE
+        ctor = attr_class_for(resolved_sub)
+        # attr_class_for always returns a MetaData subclass at runtime; cast for type safety.
+        attr = cast("MetaData", ctor(TYPE_ATTR, resolved_sub, name))
+        attr.parent = self
+        attr.set_value(value)  # type: ignore[attr-defined]
+        self._attr_nodes[name] = attr
+
+    def own_meta_attr(self, name: str) -> Optional[MetaData]:
+        return self._attr_nodes.get(name)
+
+    def own_meta_attrs(self) -> list[MetaData]:
+        return list(self._attr_nodes.values())
+
+    def attr(self, name: str) -> object:
+        """Own attr value for *name*, or ``None``."""
+        node = self._attr_nodes.get(name)
+        return getattr(node, "value", None) if node is not None else None
+
+    def own_attrs(self) -> dict[str, object]:
+        """Own attr value map — excludes inherited attrs."""
+        return {
+            name: getattr(node, "value", None)
+            for name, node in self._attr_nodes.items()
+            if getattr(node, "value", None) is not None
+        }
+
+    def attrs(self) -> dict[str, object]:
+        """Effective attr value map: own + inherited via super chain (own wins on key conflict).
+
+        Cycle-guarded and cached.
+        """
+        return self._cached("attrs", lambda: self._effective_attrs_inner({self}))
+
+    def _effective_attrs_inner(self, visited: "set[MetaData]") -> dict[str, object]:
+        """Compute effective attrs with cycle detection via *visited* set."""
+        if self.super_data is None or self.super_data in visited:
+            return self.own_attrs()
+        visited.add(self.super_data)
+        result = self.super_data._effective_attrs_inner(visited)
+        # own attrs override super
+        result.update(self.own_attrs())
+        return result
+
+    def add_child(self, child: "MetaData") -> None:
+        self._require_mutable()
+        child.parent = self
+        self._children.append(child)
+
+    def own_children(self) -> list["MetaData"]:
+        """Own (locally declared) children — excludes children inherited via extends."""
+        return list(self._children)
+
+    def children(self) -> list["MetaData"]:
+        """Effective children: own + inherited via the super chain, own shadowing super on (type, name).
+
+        Cycle-guarded and cached (after freeze).
+        """
+        return self._cached("children", lambda: self._effective_children_inner({self}))
+
+    def _effective_children_inner(
+        self, visited: "set[MetaData]"
+    ) -> list["MetaData"]:
+        """Compute effective children with cycle detection via *visited* set."""
+        if self.super_data is None or self.super_data in visited:
+            # No super, or super already on the current path — skip to avoid cycle.
+            result: list[MetaData] = list(self._children)
+        else:
+            visited.add(self.super_data)
+            result = self.super_data._effective_children_inner(visited)
+            for own in self._children:
+                idx = next(
+                    (i for i, c in enumerate(result)
+                     if c.type == own.type and c.name == own.name),
+                    None,
+                )
+                if idx is None:
+                    result.append(own)
+                else:
+                    result[idx] = own
+        return result
+
+    def freeze(self) -> None:
+        if self._frozen:
+            return
+        self._frozen = True
+        for attr in self._attr_nodes.values():
+            attr.freeze()
+        for child in self._children:
+            child.freeze()
+
+    def _cached(self, key: str, compute: Callable[[], T]) -> T:
+        if self._frozen and key in self._cache:
+            return cast(T, self._cache[key])
+        value = compute()
+        if self._frozen:
+            self._cache[key] = value
+        return value

metaobjects/meta/meta_root.py

@@ -0,0 +1,8 @@
+"""MetaRoot — the metadata.root node."""
+from __future__ import annotations
+
+from .meta_data import MetaData
+
+
+class MetaRoot(MetaData):
+    pass

metaobjects/meta/persistence/db/__init__.py

@@ -0,0 +1 @@
+"""DB-domain (persistence-layer) physical attributes (cross-port `metaobjects-db`)."""

metaobjects/meta/persistence/db/db_constants.py

@@ -0,0 +1,41 @@
+"""DB-domain physical-column attribute keys on fields (cross-port `metaobjects-db`).
+
+Mirrors server/csharp/MetaObjects/Persistence/Db/DbConstants.cs and
+server/typescript/packages/metadata/src/persistence/db/db-constants.ts so the
+cross-language vocabulary stays byte-identical.
+"""
+from __future__ import annotations
+
+# ---------------------------------------------------------------------------
+# R6 Plan 2b — @dbColumnType physical column-type attribute (ADR-0013).
+#
+# The canonical *physical* escape hatch: selects the DB column type while
+# leaving the logical field subtype and its idiomatic native binding (ADR-0001)
+# untouched. A closed, validated, introspection-round-trippable value set — no
+# raw dialect passthrough (deferred). Own-only pairing validation lives in the
+# loader's validation_passes (ERR_BAD_ATTR_VALUE), mirroring the field.enum
+# @values precedent.
+# ---------------------------------------------------------------------------
+
+# Physical DB column-type override on a field (@dbColumnType). Closed value set:
+# DB_COLUMN_TYPE_UUID / DB_COLUMN_TYPE_JSONB / DB_COLUMN_TYPE_TIMESTAMP_TZ.
+FIELD_ATTR_DB_COLUMN_TYPE = "dbColumnType"
+
+# @db.indexed — boolean DB-domain attr on every field subtype. Suppresses the
+# @filterable-without-index warning by declaring an explicit index intent.
+# Mirrors TS persistence/db/db-constants.ts FIELD_ATTR_DB_INDEXED.
+FIELD_ATTR_DB_INDEXED = "db.indexed"
+
+# @dbColumnType: uuid — native Postgres uuid column (legal on field.string).
+DB_COLUMN_TYPE_UUID = "uuid"
+# @dbColumnType: jsonb — genuinely-open JSON column (legal on field.string).
+DB_COLUMN_TYPE_JSONB = "jsonb"
+# @dbColumnType: timestamp_with_tz — timestamp with time zone (legal on field.timestamp).
+DB_COLUMN_TYPE_TIMESTAMP_TZ = "timestamp_with_tz"
+
+# The closed set of legal @dbColumnType values.
+VALID_DB_COLUMN_TYPES = (
+    DB_COLUMN_TYPE_UUID,
+    DB_COLUMN_TYPE_JSONB,
+    DB_COLUMN_TYPE_TIMESTAMP_TZ,
+)

metaobjects/meta/persistence/db/db_provider.py

@@ -0,0 +1,60 @@
+"""db_provider — the DB-domain MetaDataTypeProvider (cross-port ``metaobjects-db``).
+
+Registers the DB-domain physical field attributes — ``@column`` and ``@dbColumnType``
+— by EXTENDING the core-registered field types via :meth:`TypeRegistry.extend`.
+
+These are DB-domain concerns, NOT core field properties, so they live in this domain
+provider rather than on ``core_types._FIELD_COMMON_ATTRS`` — the same end-state as Java
+(``CoreDBMetaDataProvider``), TypeScript (``dbProvider``), and C#
+(``DbMetaDataProvider``), keeping all domain field-attrs in domain providers.
+
+Note: the loader's ``_validate_db_column_type`` pass (the closed-set + (subtype × value)
+pairing enforcement) runs UNCONDITIONALLY — it is not gated on this provider being
+composed. This provider's job is to DECLARE the attrs (so the YAML coercion guard knows
+their value types and the attr-schema validation accepts them as known) — the pairing
+legality is still owned by the loader pass, mirroring the field.enum ``@values`` precedent.
+"""
+from __future__ import annotations
+
+from ...core.attr.attr_constants import ATTR_SUBTYPE_STRING
+from ...core.field import field_constants as fc
+from ....provider import Provider
+from ....registry import AttrSchema, TypeRegistry
+from ....shared.base_types import TYPE_FIELD
+from .db_constants import FIELD_ATTR_DB_COLUMN_TYPE
+
+# Every field subtype the DB-domain attrs apply to: the shared FIELD_SUBTYPES tuple
+# (which deliberately excludes ``enum`` — registered separately in core_types) PLUS
+# ``field.enum``. Mirrors the TS dbProvider's FIELD_SUBTYPES loop and the C#
+# DbMetaDataProvider (whose FIELD_SUBTYPES includes enum) — Python reaches the same
+# coverage by appending enum here.
+_DB_FIELD_SUBTYPES: tuple[str, ...] = (*fc.FIELD_SUBTYPES, fc.FIELD_SUBTYPE_ENUM)
+
+# @column — physical column-name override on a field. Bare string attr.
+_COLUMN_SCHEMA = AttrSchema(name=fc.FIELD_ATTR_COLUMN, value_type=ATTR_SUBTYPE_STRING, required=False)
+
+# @dbColumnType — physical column-type override on a field. Registered as a bare string
+# attr (NO allowed_values) — matching Java/TS/C#, which register it unconstrained and let
+# ONLY the loader's _validate_db_column_type pass enforce the closed set (so an unknown
+# value fires exactly ONE ERR_BAD_ATTR_VALUE).
+_DB_COLUMN_TYPE_SCHEMA = AttrSchema(
+    name=FIELD_ATTR_DB_COLUMN_TYPE, value_type=ATTR_SUBTYPE_STRING, required=False
+)
+
+
+def _register(registry: TypeRegistry) -> None:
+    for sub_type in _DB_FIELD_SUBTYPES:
+        registry.extend(
+            TYPE_FIELD,
+            sub_type,
+            attributes=[_COLUMN_SCHEMA, _DB_COLUMN_TYPE_SCHEMA],
+        )
+
+
+def _make_db_provider() -> Provider:
+    p = Provider("metaobjects-db", dependencies=("metaobjects-core-types",))
+    p.on_register(_register)
+    return p
+
+
+db_provider = _make_db_provider()

metaobjects/meta/persistence/origin/meta_origin.py

@@ -0,0 +1,8 @@
+"""MetaOrigin — origin.passthrough / origin.aggregate node."""
+from __future__ import annotations
+
+from ...meta_data import MetaData
+
+
+class MetaOrigin(MetaData):
+    pass

metaobjects/meta/persistence/origin/origin_constants.py

@@ -0,0 +1,20 @@
+"""Origin subtype vocabulary (colocated)."""
+from ....shared.base_types import SUBTYPE_BASE
+
+ORIGIN_SUBTYPE_PASSTHROUGH = "passthrough"
+ORIGIN_SUBTYPE_AGGREGATE = "aggregate"
+ORIGIN_SUBTYPE_COLLECTION = "collection"
+ORIGIN_SUBTYPES = (
+    SUBTYPE_BASE,
+    ORIGIN_SUBTYPE_PASSTHROUGH,
+    ORIGIN_SUBTYPE_AGGREGATE,
+    ORIGIN_SUBTYPE_COLLECTION,
+)
+
+# passthrough attrs
+ORIGIN_ATTR_FROM = "from"
+ORIGIN_ATTR_VIA = "via"
+
+# aggregate attrs
+ORIGIN_ATTR_AGG = "agg"
+ORIGIN_ATTR_OF = "of"

metaobjects/meta/persistence/source/meta_source.py

@@ -0,0 +1,137 @@
+"""MetaSource — source.rdb node (ADR-0007 / FR-016 / ADR-0018).
+
+Declares where an object's data lives. The rdb paradigm uses per-kind
+physical-name aliases (@table / @view / @materializedView / @proc / @function)
++ @kind / @role / @schema attrs; read-only-ness is derived from @kind.
+"""
+from __future__ import annotations
+
+from ...meta_data import MetaData
+from .source_constants import (
+    ALL_PHYSICAL_NAME_ALIASES,
+    DEFAULT_SOURCE_KIND,
+    DEFAULT_SOURCE_ROLE,
+    PHYSICAL_NAME_ATTR_BY_KIND,
+    SOURCE_ATTR_KIND,
+    SOURCE_ATTR_ROLE,
+    SOURCE_ATTR_SCHEMA,
+    SOURCE_ATTR_TABLE,
+    SOURCE_READ_ONLY_KINDS,
+)
+
+
+def _to_snake_case(s: str) -> str:
+    """``MyName`` → ``my_name``; ``HTTPServer`` → ``http_server`` (mirrors TS
+    ``toSnakeCase`` regex pair, ASCII-only)."""
+    if not s:
+        return s
+    # Run 1: split between an uppercase-run and an upper+lower head.
+    out: list[str] = []
+    n = len(s)
+    for i, ch in enumerate(s):
+        is_upper = "A" <= ch <= "Z"
+        if is_upper and i > 0:
+            prev = s[i - 1]
+            prev_upper = "A" <= prev <= "Z"
+            prev_alnum_lower = ("a" <= prev <= "z") or ("0" <= prev <= "9")
+            nxt = s[i + 1] if i + 1 < n else ""
+            nxt_lower = "a" <= nxt <= "z"
+            if prev_alnum_lower:
+                out.append("_")
+            elif prev_upper and nxt_lower:
+                out.append("_")
+        out.append(ch.lower())
+    return "".join(out)
+
+
+def _pluralize(s: str) -> str:
+    """Trivial cross-port pluralization (matches TS ``pluralize``)."""
+    if not s:
+        return s
+    lower = s.lower()
+    if lower.endswith(("s", "x", "z", "ch", "sh")):
+        return s + "es"
+    if len(s) >= 2 and lower[-1] == "y" and lower[-2] not in "aeiou":
+        return s[:-1] + "ies"
+    return s + "s"
+
+
+class MetaSource(MetaData):
+    """A source.* node. Accessors mirror the TS reference (meta-source.ts) and
+    the Java port (MetaSource.java) — own-attr reads, with per-paradigm defaults.
+    """
+
+    def table_name(self) -> str | None:
+        """Physical SQL table name from the legacy ``@table`` slot. Returns
+        ``None`` if absent. Kept as a back-compat slot-only accessor: callers
+        should use :meth:`physical_name` for the FR-016 four-step rule.
+        """
+        v = self.attr(SOURCE_ATTR_TABLE)
+        return v if isinstance(v, str) and v else None
+
+    def effective_kind(self) -> str:
+        """The value of ``@kind``, defaulting to ``"table"`` when omitted
+        (ADR-0007 Rule 3 — per-paradigm default)."""
+        v = self.attr(SOURCE_ATTR_KIND)
+        return v if isinstance(v, str) and v else DEFAULT_SOURCE_KIND
+
+    def role(self) -> str:
+        """The value of ``@role``, defaulting to ``"primary"`` when omitted."""
+        v = self.attr(SOURCE_ATTR_ROLE)
+        return v if isinstance(v, str) and v else DEFAULT_SOURCE_ROLE
+
+    def is_read_only(self) -> bool:
+        """True when ``@kind`` names a read-only construct (view,
+        materializedView, storedProc, tableFunction)."""
+        return self.effective_kind() in SOURCE_READ_ONLY_KINDS
+
+    def is_writable(self) -> bool:
+        """True when this source is writable (i.e. not read-only)."""
+        return not self.is_read_only()
+
+    def schema(self) -> str | None:
+        """The value of ``@schema``, or ``None`` if absent."""
+        v = self.attr(SOURCE_ATTR_SCHEMA)
+        return v if isinstance(v, str) and v else None
+
+    def physical_name(self) -> str:
+        """Resolved physical SQL name for this source (FR-016 / ADR-0018).
+
+        Four-step rule:
+            1. Kind-matching alias (e.g. ``@proc`` when ``@kind: "storedProc"``).
+            2. Legacy ``@table`` for non-table kind (pre-1.0 fallback).
+            3. Source's bare structural ``name`` via snake_case
+               (no pluralize — the source's name IS the logical name).
+            4. Owning entity's name via ``pluralize(snake_case())``.
+
+        Callers needing the legacy raw ``@table`` slot only should use
+        :meth:`table_name`; codegen / runtime should use ``physical_name``.
+        """
+        kind = self.effective_kind()
+
+        # Step 1: kind-matching alias.
+        canonical_attr = PHYSICAL_NAME_ATTR_BY_KIND.get(kind)
+        if canonical_attr is not None:
+            v = self.attr(canonical_attr)
+            if isinstance(v, str) and v:
+                return v
+
+        # Step 2: legacy @table for non-table kind.
+        if canonical_attr != SOURCE_ATTR_TABLE:
+            legacy = self.attr(SOURCE_ATTR_TABLE)
+            if isinstance(legacy, str) and legacy:
+                return legacy
+
+        # Step 3: source's structural name → snake_case (no pluralize).
+        if self.name:
+            return _to_snake_case(self.name)
+
+        # Step 4: owning entity's name → pluralize(snake_case).
+        owner = self.parent
+        if owner is not None and getattr(owner, "name", ""):
+            return _pluralize(_to_snake_case(owner.name))
+
+        return ""
+
+
+__all__ = ["MetaSource", "ALL_PHYSICAL_NAME_ALIASES"]