metaobjects 1.1.4__tar.gz → 1.2.0__tar.gz

{metaobjects-1.1.4 → metaobjects-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: metaobjects
-Version: 1.1.4
+Version: 1.2.0
 Summary: Cross-language metadata standard: declare typed entities once, generate idiomatic drift-checked code across languages — Python port.
 Project-URL: Homepage, https://metaobjects.dev
 Project-URL: Repository, https://github.com/metaobjectsdev/metaobjects
@@ -25,7 +25,7 @@ Requires-Python: >=3.11
 Requires-Dist: pyyaml>=6.0
 Provides-Extra: dev
 Requires-Dist: mypy>=1.10; extra == 'dev'
-Requires-Dist: pydantic>=2; extra == 'dev'
+Requires-Dist: pydantic>=2.8; extra == 'dev'
 Requires-Dist: pytest-xdist>=3.6; extra == 'dev'
 Requires-Dist: pytest>=8; extra == 'dev'
 Requires-Dist: ruff>=0.6; extra == 'dev'
@@ -34,6 +34,8 @@ Requires-Dist: fastapi>=0.110; extra == 'integration'
 Requires-Dist: httpx>=0.27; extra == 'integration'
 Requires-Dist: pg8000>=1.31; extra == 'integration'
 Requires-Dist: pymysql>=1.1; extra == 'integration'
+Provides-Extra: jinja
+Requires-Dist: jinja2>=3.1; extra == 'jinja'
 Provides-Extra: mysql
 Requires-Dist: pymysql>=1.1; extra == 'mysql'
 Description-Content-Type: text/markdown
@@ -84,8 +86,8 @@ The primary public API is the **loader** (`load_directory` / `load_uris` /
 `load_string`, `MetaDataLoader`, `LoadResult`, `ErrorCode`, `MetaError`). The
 distribution also ships the Python implementations of the other pillars used by the CLI
 and tooling: `codegen` (Pydantic + FastAPI emit — reference generators you own:
-`metaobjects eject <name>` copies one into your repo), `render` (Mustache + payload-VO +
-verify), and `runtime` (a DB-API 2 `ObjectManager` — pg8000 / psycopg on Postgres, the standard library's `sqlite3` on SQLite, PyMySQL on MySQL 8 (`pip install metaobjects[mysql]`) — no SQLAlchemy).
+`metaobjects eject <name>` copies one into your repo), `render` (Mustache, or Jinja with
+`pip install metaobjects[jinja]` — ADR-0061 — + payload-VO + verify), and `runtime` (a DB-API 2 `ObjectManager` — pg8000 / psycopg on Postgres, the standard library's `sqlite3` on SQLite, PyMySQL on MySQL 8 (`pip install metaobjects[mysql]`) — no SQLAlchemy).
 Schema migrations are owned by the TypeScript `meta` CLI (ADR-0015); there is
 **no `migrate` module** in this distribution.
 

{metaobjects-1.1.4 → metaobjects-1.2.0}/README.md

@@ -44,8 +44,8 @@ The primary public API is the **loader** (`load_directory` / `load_uris` /
 `load_string`, `MetaDataLoader`, `LoadResult`, `ErrorCode`, `MetaError`). The
 distribution also ships the Python implementations of the other pillars used by the CLI
 and tooling: `codegen` (Pydantic + FastAPI emit — reference generators you own:
-`metaobjects eject <name>` copies one into your repo), `render` (Mustache + payload-VO +
-verify), and `runtime` (a DB-API 2 `ObjectManager` — pg8000 / psycopg on Postgres, the standard library's `sqlite3` on SQLite, PyMySQL on MySQL 8 (`pip install metaobjects[mysql]`) — no SQLAlchemy).
+`metaobjects eject <name>` copies one into your repo), `render` (Mustache, or Jinja with
+`pip install metaobjects[jinja]` — ADR-0061 — + payload-VO + verify), and `runtime` (a DB-API 2 `ObjectManager` — pg8000 / psycopg on Postgres, the standard library's `sqlite3` on SQLite, PyMySQL on MySQL 8 (`pip install metaobjects[mysql]`) — no SQLAlchemy).
 Schema migrations are owned by the TypeScript `meta` CLI (ADR-0015); there is
 **no `migrate` module** in this distribution.
 

{metaobjects-1.1.4 → metaobjects-1.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "metaobjects"
-version = "1.1.4"
+version = "1.2.0"
 description = "Cross-language metadata standard: declare typed entities once, generate idiomatic drift-checked code across languages — Python port."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -50,7 +50,7 @@ Issues = "https://github.com/metaobjectsdev/metaobjects/issues"
 Changelog = "https://github.com/metaobjectsdev/metaobjects/blob/main/CHANGELOG.md"
 
 [project.optional-dependencies]
-dev = ["pytest>=8", "pytest-xdist>=3.6", "mypy>=1.10", "ruff>=0.6", "pydantic>=2"]
+dev = ["pytest>=8", "pytest-xdist>=3.6", "mypy>=1.10", "ruff>=0.6", "pydantic>=2.8"]
 # On-demand cross-language conformance suites — persistence + api-contract.
 # pg8000 is pure-python so this extra installs cleanly without native deps;
 # the persistence harness shells out to the docker CLI directly (matches the
@@ -62,6 +62,10 @@ integration = ["pg8000>=1.31", "PyMySQL>=1.1", "fastapi>=0.110", "httpx>=0.27"]
 # so like pg8000 it installs without native build dependencies. SQLite needs nothing: the
 # driver wraps the standard library's `sqlite3`.
 mysql = ["PyMySQL>=1.1"]
+# Jinja templates (ADR-0061): the second template engine beside Mustache. Imported only when a
+# `.jinja` / `.j2` / `.jinja2` template is rendered or checked, so a Mustache-only project
+# installs nothing extra.
+jinja = ["jinja2>=3.1"]
 
 [[tool.mypy.overrides]]
 # PyMySQL ships no type information.
@@ -110,9 +114,16 @@ dev = [
     # The validator-parity corpus (tests/codegen/test_validation_conformance.py)
     # imports pydantic to exercise the generated Pydantic models, so it must be here
     # or the CI `uv run pytest` collection fails with ModuleNotFoundError.
-    "pydantic>=2",
+    "pydantic>=2.8",
     # ruff is the Python codegen format pass (src/metaobjects/codegen/format.py); the
     # cli-registry corpus runs codegen, so without ruff in the group `uv run pytest`
     # fails at format time with "No module named ruff".
     "ruff>=0.6",
+    # The generated-router mypy gate (tests/codegen/test_router_mypy_strict.py) type-checks
+    # the emitted FastAPI routers under `mypy --strict`. The framework those routers import
+    # comes from `--extra integration`, which the python lane always passes.
+    "mypy>=1.10",
+    # The Jinja engine and its conformance corpora (fixtures/jinja-*-conformance/) run in the
+    # default suite, so the optional `jinja` extra's dependency is in the dev group too.
+    "jinja2>=3.1",
 ]

{metaobjects-1.1.4 → metaobjects-1.2.0}/src/metaobjects/cli.py

@@ -21,7 +21,7 @@ Two subcommands:
       across ports):
 
         --codegen    regenerate into a temp dir + diff against the committed
-                     ``--out`` tree (Python's historical default behavior).
+                     ``--out`` tree.
                      The column naming comes from ``naming.columns`` in
                      ``.metaobjects/config.json`` (ADR-0058), the same setting
                      ``gen`` reads, so the ``names`` generator's constants match
@@ -38,9 +38,9 @@ Two subcommands:
                      migrate engine (ADR-0015), not this CLI.
 
       Combining flags runs each requested mode and aggregates the exit code
-      (non-zero if ANY mode drifts). A bare ``verify`` keeps the historical
-      default = ``--codegen`` (back-compat) and prints a one-line note that the
-      explicit subverbs exist.
+      (non-zero if ANY mode drifts). A bare ``verify`` runs ``--codegen`` and
+      ``--templates`` (the cross-port default gate set) and prints a one-line
+      note that the explicit subverbs exist.
 
 Named ``metaobjects``, NOT ``meta``: ``meta`` is the Node schema CLI. This CLI
 intentionally has NO ``migrate`` subcommand — schema is owned by the Node
@@ -89,7 +89,7 @@ from metaobjects.requirement_check import (
     scan_requirements,
     summarise_requirements,
 )
-from metaobjects.codegen.config import GenConfig
+from metaobjects.codegen.config import DEFAULT_API_PREFIX, GenConfig
 from metaobjects.codegen.overwrite_policy import (
     has_hash_manifest,
     is_pristine_generated,
@@ -141,6 +141,7 @@ from metaobjects.naming import (
     package_of_resolution_key,
     removed_naming_source_message,
 )
+from metaobjects.render.engine import template_engine_of
 from metaobjects.render.filesystem_provider import FilesystemProvider
 from metaobjects.render.verify import (
     ERR_REQUIRED_SLOT_UNUSED,
@@ -608,12 +609,13 @@ def _load_root_from_collection(
     return result.root, []
 
 
-#: Trailing advice after ``gen``'s unknown-attribute warnings. ``gen`` has no strict
-#: flag of its own; ``verify`` is the strict door (ADR-0023), so that is what it names.
+#: Trailing advice after ``gen``'s unknown-attribute warnings. ``gen`` loads leniently
+#: unless ``--strict``; ``verify`` is strict by default (ADR-0023), so the line names both.
 UNKNOWN_ATTR_GEN_ADVICE = (
     "metaobjects gen loads leniently and generated anyway, but `metaobjects verify` "
     "rejects this metadata (ADR-0023): fix or remove the attribute - a typo'd one "
-    "(`isAbstrakt`, `requird`) silently changes what is generated."
+    "(`isAbstrakt`, `requird`) silently changes what is generated. "
+    "Pass `--strict` to make `gen` refuse it too."
 )
 
 
@@ -647,13 +649,35 @@ def _print_unknown_attr_warnings(findings: list[str]) -> None:
     print(f"warning: {UNKNOWN_ATTR_GEN_ADVICE}", file=sys.stderr)
 
 
-def _strict_load_hint() -> str:
-    """Actionable next-steps when strict verify rejects an undeclared @attr."""
+def _print_identical_owned_notice(root: Path) -> None:
+    """ONE advisory line when owned generator copies are identical to the shipped ones: an
+    owned copy that was never edited only costs the adopter upgrades. Advisory: the exit
+    code is unchanged, and a project with no owned copies reads no file."""
+    try:
+        names = [e.name for e in owned.identical_owned(root)]
+    except Exception:  # noqa: BLE001 — advisory; a packaged module that cannot be read says nothing
+        return
+    if names:
+        print(
+            f"note: owned generator copy identical to the shipped one: {', '.join(names)}. "
+            "Run `metaobjects eject --undo` to drop the copies and track the shipped "
+            "generators again.",
+            file=sys.stderr,
+        )
+
+
+def _strict_load_hint(strict_flag: str = "verify") -> str:
+    """Actionable next-steps when a strict load rejects an undeclared @attr."""
+    opt_out = (
+        "OR drop `--strict` to keep the lenient load"
+        if strict_flag == "--strict"
+        else "OR re-run with `--lax` to keep the legacy open-attr load"
+    )
+    who = "gen --strict" if strict_flag == "--strict" else "verify"
     return (
-        "verify is strict (ADR-0023): every authored @attr must be declared. Fix: "
+        f"{who} is strict (ADR-0023): every authored @attr must be declared. Fix: "
         "register the attr on a metadata provider, OR move arbitrary author-supplied "
-        "properties into an `attr.properties` bag, OR re-run with `--lax` to keep the "
-        "legacy open-attr load."
+        f"properties into an `attr.properties` bag, {opt_out}."
     )
 
 
@@ -875,6 +899,7 @@ def _run_suite(
     baseline: str = "default",
     refused_out: list[str] | None = None,
     select: Callable[[str], bool] | None = None,
+    api_prefix: str = DEFAULT_API_PREFIX,
     overwrite_hand_edits: frozenset[str] = frozenset(),
     overwrite_paths_out: set[str] | None = None,
 ) -> list[str]:
@@ -917,6 +942,7 @@ def _run_suite(
         emit_package_init=emit_package_init,
         gen_state_dir=gen_state_dir,
         column_naming=column_naming,
+        api_prefix=api_prefix,
         # Manifest keys are relative to the PROJECT, which is what the manifest is
         # anchored on — not to ``--out``, which varies per run while the manifest does
         # not. Passed alongside gen_state_dir because the two are one decision: state
@@ -1248,9 +1274,17 @@ def _cmd_fmt(args: argparse.Namespace) -> int:
 
 
 def _cmd_eject(args: argparse.Namespace) -> int:
-    """Copy reference generators into ``codegen/generators/`` to own (ADR-0034 Am. 3)."""
+    """Copy reference generators into ``codegen/generators/`` to own (ADR-0034 Am. 3), or
+    with ``--undo`` drop the copies that are identical to the shipped ones."""
     root = Path(args.root) if args.root else Path.cwd()
-    result = owned.eject(args.names, root, force=args.force)
+    if args.undo:
+        result = owned.undo(args.names, root, force=args.force)
+    elif not args.names:
+        print("error: name at least one generator to eject (`metaobjects gen --list` shows "
+              "them), or pass --undo", file=sys.stderr)
+        return 2
+    else:
+        result = owned.eject(args.names, root, force=args.force)
     for line in result.out:
         print(line)
     for line in result.err:
@@ -1258,6 +1292,57 @@ def _cmd_eject(args: argparse.Namespace) -> int:
     return result.code
 
 
+#: The metadata a fresh ``init`` writes: a loadable, empty model to author into.
+_INIT_METADATA = "metadata:\n  package: app\n  children: []\n"
+
+_INIT_CONFIG = """\
+# What `metaobjects gen` generates: each target names its outDir and its generators.
+# `metaobjects gen --list` shows the catalog.
+metadata: metaobjects
+targets:
+  app:
+    outDir: generated
+    generators: []
+"""
+
+_INIT_DOCS_CONFIG = """\
+  docs:
+    outDir: docs
+    generators: [api-docs]
+"""
+
+
+def _cmd_init(args: argparse.Namespace) -> int:
+    """Scaffold ``metaobjects.config.yaml`` and the ``metaobjects/`` metadata directory.
+
+    Never overwrites: a file that exists is reported and left alone. ``--with-docs`` adds a
+    ``docs`` target running ``api-docs``; without it no documentation generator is wired.
+    """
+    root = Path(args.root) if args.root else Path.cwd()
+    config = _INIT_CONFIG + (_INIT_DOCS_CONFIG if args.with_docs else "")
+    wrote: list[str] = []
+    kept: list[str] = []
+    for rel, text in (
+        (_CONFIG_NAME, config),
+        ("metaobjects/meta.app.yaml", _INIT_METADATA),
+    ):
+        path = root / rel
+        if path.exists():
+            kept.append(rel)
+            continue
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(text, encoding="utf-8")
+        wrote.append(rel)
+    for rel in wrote:
+        print(f"wrote {rel}")
+    for rel in kept:
+        print(f"kept {rel} (already exists)")
+    if args.with_docs and _CONFIG_NAME in kept:
+        print("note: add the docs target yourself: `docs: {outDir: docs, generators: [api-docs]}`")
+    print("next: describe your entities in metaobjects/, then run `metaobjects gen`.")
+    return 0
+
+
 def _warn_if_agent_context_stale() -> None:
     """Print ONE advisory line to stderr if the scaffolded agent context is stale.
 
@@ -1534,7 +1619,7 @@ def _run_gen_targets(
                 written = _run_suite(
                     root, out_dir, gens, t.entities, gen_state_dir=gen_state_dir,
                     column_naming=column_naming, project_root=project_root, baseline=baseline,
-                    refused_out=refused_out, select=select,
+                    refused_out=refused_out, select=select, api_prefix=config.api_prefix,
                     overwrite_hand_edits=overwrite, overwrite_paths_out=overwrite_paths_out,
                 )
             if spec_gens:
@@ -1542,7 +1627,7 @@ def _run_gen_targets(
                     root, out_dir, spec_gens, t.entities, emit_package_init=False,
                     gen_state_dir=gen_state_dir, column_naming=column_naming,
                     project_root=project_root, baseline=baseline, refused_out=refused_out,
-                    select=select,
+                    select=select, api_prefix=config.api_prefix,
                 )
         except ValueError as exc:  # intra-target run_gen collision → clean error
             errors.append(f"target '{t.name}': {exc}")
@@ -1608,17 +1693,23 @@ def _cmd_gen_config(args: argparse.Namespace) -> int:
     if collection is None:
         return 1
 
+    # `--strict` is the load `verify` uses (ADR-0023): an unknown attribute is an error and
+    # nothing is written. Without it `gen` loads leniently and only warns.
+    strict = bool(getattr(args, "strict", False))
     unknown_attrs: list[str] = []
     root, load_errors = _load_root_from_collection(
-        collection, providers=providers, libraries=config.libraries,
+        collection, strict=strict, providers=providers, libraries=config.libraries,
         unknown_attr_out=unknown_attrs,
     )
     if root is None:
         print("error: failed to load metadata:", file=sys.stderr)
         for msg in load_errors:
             print(f"  {msg}", file=sys.stderr)
+        if strict and any("ERR_UNKNOWN_ATTR" in m for m in load_errors):
+            print(_strict_load_hint(strict_flag="--strict"), file=sys.stderr)
         return 1
     _print_unknown_attr_warnings(unknown_attrs)
+    _print_identical_owned_notice(config.config_dir)
 
     template_root, templates_refusal = _template_root_for_config(args, config)
     if templates_refusal is not None:
@@ -1786,7 +1877,9 @@ def _relative_set(root: Path, nested: list[Path] | None = None) -> dict[str, str
         if p.suffix in _UNCOMPARED_SUFFIXES:
             continue
         try:
-            files[str(rel)] = p.read_text(encoding="utf-8")
+            # Bytes, not read_text(): text mode translates \r\n and lone \r to \n, so a
+            # committed CRLF file would compare equal to the LF the generator wrote.
+            files[str(rel)] = p.read_bytes().decode("utf-8")
         except (UnicodeDecodeError, OSError):
             continue
     return files
@@ -2401,6 +2494,7 @@ def _verify_templates(args: argparse.Namespace) -> int:
             for e in render_verify(
                 text, fields, provider=provider,
                 required_slots=req_slots, required_tags=req_tags,
+                engine=template_engine_of(provider, ref),
             ):
                 if e.code == ERR_REQUIRED_SLOT_UNUSED:
                     continue  # an unused required slot is a warning, not drift
@@ -2668,8 +2762,11 @@ def _verify_requirements(args: argparse.Namespace, model: "_VerifyModel | None")
 
 def _cmd_verify(args: argparse.Namespace) -> int:
     """Subverb dispatch (ADR-0021 D2). Run each requested mode; aggregate exit =
-    max (non-zero if ANY mode drifts). Bare ``verify`` (no subverb) keeps the
-    historical default = ``--codegen`` + a one-line note advertising the subverbs.
+    max (non-zero if ANY mode drifts). Bare ``verify`` (no subverb) runs the
+    cross-port default gate set, ``--codegen`` + ``--templates`` (the requirement
+    ledger runs on every verify) + a one-line note advertising the subverbs.
+    ``--templates`` is skipped with a note when the run names no config and no
+    ``--prompts`` root, since there is then no template directory to resolve.
     """
     naming_refusal = _refuse_column_naming_flag(args)
     if naming_refusal is not None:
@@ -2684,12 +2781,24 @@ def _cmd_verify(args: argparse.Namespace) -> int:
 
     if not any_explicit:
         print(
-            "metaobjects verify — running --codegen (default). Explicit "
+            "metaobjects verify — running --codegen --templates (default). Explicit "
             "subverbs: --codegen (codegen drift), --templates (template/prompt "
             "drift), --db (schema drift — not supported in Python).",
             file=sys.stderr,
         )
         run_codegen = True
+        if args.metadata_dir is None:
+            has_template_root = _find_config(args) is not None
+        else:
+            has_template_root = bool(getattr(args, "templates_root", None))
+        if not has_template_root:
+            print(
+                "metaobjects verify — template gate skipped: no metaobjects.config.yaml "
+                "and no --prompts directory, so there is no template root to resolve against.",
+                file=sys.stderr,
+            )
+        else:
+            run_templates = True
 
     exit_code = 0
     gates_stderr = _RecordedStderr(sys.stderr)
@@ -2798,6 +2907,14 @@ def _build_parser() -> argparse.ArgumentParser:
             "as `templateSpec: <path>` in metaobjects.config.yaml"
         ),
     )
+    gen.add_argument(
+        "--strict",
+        action="store_true",
+        help=(
+            "strict-attr load, the one `verify` uses (ADR-0023): an undeclared attribute is "
+            "an error and nothing is written. Without it gen loads leniently and warns."
+        ),
+    )
     gen.add_argument(
         "--templates",
         default=None,
@@ -2850,7 +2967,7 @@ def _build_parser() -> argparse.ArgumentParser:
         "verify",
         help=(
             "drift gate — explicit subverbs --codegen / --templates / --db "
-            "(ADR-0021 D2); bare verify defaults to --codegen"
+            "(ADR-0021 D2); bare verify runs --codegen and --templates"
         ),
     )
     verify.add_argument(
@@ -3008,38 +3125,37 @@ def _build_parser() -> argparse.ArgumentParser:
         "eject",
         help="copy reference generators into codegen/generators/ to own and edit",
     )
-    eject_p.add_argument("names", nargs="+", metavar="NAME", help="stable generator names")
+    eject_p.add_argument("names", nargs="*", metavar="NAME", help="stable generator names")
     eject_p.add_argument("--force", action="store_true",
-                         help="replace an existing owned copy with the reference")
+                         help="replace an existing owned copy with the reference "
+                              "(with --undo: remove a copy that differs from it)")
+    eject_p.add_argument(
+        "--undo", action="store_true",
+        help="drop owned copies identical to the shipped generator (all of them, or the "
+             "names given); a copy that differs is refused unless --force; prints the "
+             "config edit, never makes it",
+    )
     eject_p.add_argument("--root", default=None, help="project root (default: cwd)")
     eject_p.set_defaults(func=_cmd_eject)
 
+    init_p = sub.add_parser(
+        "init",
+        help="scaffold metaobjects.config.yaml and metaobjects/ (never overwrites a file)",
+    )
+    init_p.add_argument("--with-docs", action="store_true",
+                        help="also wire the api-docs generator (a `docs` target)")
+    init_p.add_argument("--root", default=None, help="project root (default: cwd)")
+    init_p.set_defaults(func=_cmd_init)
+
     agent_docs = sub.add_parser(
         "agent-docs",
         help=(
-            "scaffold the slim MetaObjects Claude Code agent context "
-            "(.metaobjects/AGENTS.md + CLAUDE.md + the metaobjects-* skills)"
+            "moved to the Node CLI: run `npx meta agent-docs --server python` "
+            "(this command scaffolds nothing and exits 1)"
         ),
     )
-    agent_docs.add_argument(
-        "--server",
-        action="append",
-        default=None,
-        metavar="LANG",
-        help="server language (repeatable): typescript|java|kotlin|csharp|python",
-    )
-    agent_docs.add_argument(
-        "--client",
-        action="append",
-        default=None,
-        metavar="FRAMEWORK",
-        help="client framework (repeatable): react|tanstack|angular",
-    )
-    agent_docs.add_argument(
-        "--out",
-        default=None,
-        help="output project root (default: cwd)",
-    )
+    for ignored_flag in ("--server", "--client", "--out"):
+        agent_docs.add_argument(ignored_flag, help=argparse.SUPPRESS)
     agent_docs.set_defaults(func=_cmd_agent_docs)
 
     return parser

{metaobjects-1.1.4 → metaobjects-1.2.0}/src/metaobjects/codegen/collection_name_collision.py

@@ -16,10 +16,14 @@ entities and the colliding name.
 """
 from __future__ import annotations
 
-from metaobjects.apidocs.naming import pluralize
+from metaobjects.apidocs.naming import pluralize, route_path
 from metaobjects.errors import ErrorCode
 from metaobjects.meta.core.object.meta_object import MetaObject
 from metaobjects.meta.core.object.object_constants import OBJECT_SUBTYPE_VALUE
+from metaobjects.meta.persistence.source.meta_source import MetaSource
+from metaobjects.runtime.tph import tph_subtype_of
+
+from .instance_artifacts import is_abstract
 
 ERR_COLLECTION_NAME_COLLISION = ErrorCode.ERR_COLLECTION_NAME_COLLISION.value
 
@@ -56,3 +60,31 @@ def assert_no_collection_name_collisions(entities: list[MetaObject]) -> None:
                 )
         else:
             owner_of_plural[plural] = obj
+    _assert_no_route_segment_collisions(entities)
+
+
+def _assert_no_route_segment_collisions(entities: list[MetaObject]) -> None:
+    """The route half. The REST segment is the entity NAME snake_cased and then
+    pluralized (:func:`route_path`), so ``ApiKey`` and ``APIKey`` both serve
+    ``/api_keys`` while their pluralized names differ and pass the check above.
+    Counts only objects that actually get a route: not a value object, not abstract,
+    not sourceless, not a TPH subtype (folded into its base and served under it)."""
+    owner_of_segment: dict[str, MetaObject] = {}
+    for obj in entities:
+        if obj.sub_type == OBJECT_SUBTYPE_VALUE or is_abstract(obj):
+            continue
+        # ADR-0039: children() resolves — an inherited source still gets a route.
+        if not any(isinstance(c, MetaSource) for c in obj.children()):
+            continue
+        if tph_subtype_of(obj) is not None:
+            continue
+        segment = route_path(obj.name)
+        existing = owner_of_segment.get(segment)
+        if existing is None:
+            owner_of_segment[segment] = obj
+        elif existing.resolution_key() != obj.resolution_key():
+            raise ValueError(
+                f'{ERR_COLLECTION_NAME_COLLISION}: "{existing.name}" and "{obj.name}" both resolve '
+                f'to the REST collection segment "{segment}" — rename one entity so its '
+                "snake_cased, pluralized route segment is distinct."
+            )

{metaobjects-1.1.4 → metaobjects-1.2.0}/src/metaobjects/codegen/config.py

@@ -5,6 +5,9 @@ from dataclasses import dataclass, field
 
 from metaobjects.naming import DEFAULT_COLUMN_NAMING
 
+#: What generated routers mount under when no ``apiPrefix`` is configured.
+DEFAULT_API_PREFIX = "/api"
+
 
 @dataclass
 class GenConfig:
@@ -54,6 +57,11 @@ class GenConfig:
     # constant this generator emits names a different column than the one a row
     # actually lands in.
     column_naming: str = DEFAULT_COLUMN_NAMING
+    # The path the generated routers mount under (and the api docs name): ``/api/authors``
+    # by default, ``/v1/authors`` for ``/v1``, ``/authors`` for ``""``. The CLI fills it from
+    # ``apiPrefix`` in ``metaobjects.config.yaml``, the Python spelling of the TypeScript
+    # config's key of the same name.
+    api_prefix: str = DEFAULT_API_PREFIX
     # First-time-on-existing-file behaviour. "default" refuses a file that cannot be
     # proved to be generated output; "adopt" records what is on disk as the baseline and
     # writes nothing — the one run a project with no committed manifest can perform (the