metaobjects 0.24.4__tar.gz → 0.25.0__tar.gz

{metaobjects-0.24.4 → metaobjects-0.25.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: metaobjects
-Version: 0.24.4
+Version: 0.25.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

{metaobjects-0.24.4 → metaobjects-0.25.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "metaobjects"
-version = "0.24.4"
+version = "0.25.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"

{metaobjects-0.24.4 → metaobjects-0.25.0}/src/metaobjects/__init__.py

@@ -35,6 +35,7 @@ from .meta.core.object.object_extract import (
     extract_schema_for,
 )
 from .meta.core.object.value_object import ValueObject
+from .naming import resolve_column_name
 
 # Module-level shortcuts: the 99% case for callers who don't need a
 # long-lived loader. Signatures + docstrings come straight from the
@@ -58,6 +59,7 @@ __all__ = [
     "load_directory",
     "load_uris",
     "load_string",
+    "resolve_column_name",
     # Runtime object model (Phase A)
     "ValueObject",
     "MetaObjectAware",

{metaobjects-0.24.4 → metaobjects-0.25.0}/src/metaobjects/agent_context/scaffold.py

@@ -10,6 +10,7 @@ installed MetaObjects version.
 
 from __future__ import annotations
 
+import re
 from dataclasses import dataclass
 from importlib.metadata import PackageNotFoundError, version as _pkg_version
 
@@ -76,6 +77,61 @@ class Manifest:
         )
 
 
+# The sentinel a port stamps when it cannot resolve its own installed version.
+_UNRESOLVED_VERSION = "0.0.0"
+
+_RELEASE_RE = re.compile(r"^(\d+)\.(\d+)\.(\d+)$")
+
+
+def _release_series(version: object) -> tuple[int, int] | None:
+    """Ordered release coordinate ``(minor, patch)``, or ``None`` when not orderable.
+
+    The MAJOR is deliberately dropped. It is a per-registry constant, not information:
+    npm/PyPI/NuGet ship ``0.<m>.<p>`` and Maven Central the same ``<m>.<p>`` on its
+    historical major ``7``, so minor.patch IS the shared release coordinate across all
+    four ports.
+
+    ``None`` means "not orderable, so nudge", and deliberately covers prereleases
+    (``0.24.5-rc.1``), build metadata (``0.24.5+abc``) and the ``0.0.0`` sentinel. Each
+    must keep nudging: an RC-scaffolded context against a final release is still worth
+    refreshing, and an unknown install must never assert "in sync".
+    """
+    if not isinstance(version, str):
+        return None
+    v = version.strip()
+    if v == _UNRESOLVED_VERSION:
+        return None
+    m = _RELEASE_RE.match(v)
+    if m is None:
+        return None
+    return int(m.group(2)), int(m.group(3))
+
+
+def _context_is_ahead_of_install(generated_by: object, current_version: str) -> bool:
+    """True when the manifest was stamped by a release STRICTLY NEWER than the install.
+
+    The one exemption from "any drift nudges", and it exists because of the
+    publish-what-changed rule (docs/RELEASING.md): a registry publishes only when it has
+    a changed product file, so a port legitimately sits behind npm — while
+    ``meta agent-docs``, the canonical scaffolder for EVERY port, stamps the npm version
+    it was run from. A Python install at ``0.24.4`` whose context was scaffolded by npm
+    ``0.24.7`` is correct, and nudging it is issue #347 exactly: the remedy re-runs the
+    scaffolder, which re-stamps ``0.24.7``, so the advisory can never be satisfied and
+    fires on every build forever.
+
+    KNOWN BOUND, stated rather than hidden: ordering on minor.patch assumes both versions
+    sit in the same release SERIES. That holds for every release to date and after the
+    1.0/8.0 cut, but not ACROSS it — there a ``0.24.x`` context against a ``1.0.0``
+    install reads as "ahead" and the nudge is suppressed once. A missed advisory, never a
+    wrong action.
+    """
+    stamped = _release_series(generated_by)
+    installed = _release_series(current_version)
+    if stamped is None or installed is None:
+        return False  # not orderable → nudge
+    return stamped > installed
+
+
 def agent_context_staleness(
     manifest: dict[str, object] | None, current_version: str
 ) -> str | None:
@@ -85,15 +141,18 @@ def agent_context_staleness(
     is in sync — and a one-line advisory message otherwise. Pure + advisory:
     never raises, never blocks, never writes.
 
-    The comparison is **exact equality** on purpose: ANY drift nudges (a
-    re-scaffold is cheap + idempotent). Do NOT "fix" this into a semver compare —
-    a prerelease/build-metadata difference is still a reason to refresh.
+    The comparison is **exact equality** first: ANY drift nudges (a re-scaffold is
+    cheap + idempotent), so this is not a semver compare — a prerelease or
+    build-metadata difference is still a reason to refresh. See
+    ``_context_is_ahead_of_install`` for the ONE case that is exempt.
     """
     if manifest is None:
         return None  # no agent context here → nothing to nudge
     generated_by = manifest.get("generatedBy")
     if generated_by == current_version:
         return None  # in sync
+    if _context_is_ahead_of_install(generated_by, current_version):
+        return None  # scaffolded by a NEWER release than this install — see below
     frm = generated_by if generated_by else "an older MetaObjects"
     return (
         f"MetaObjects agent context was generated by {frm}; "

{metaobjects-0.24.4 → metaobjects-0.25.0}/src/metaobjects/apidocs/builder.py

@@ -4,7 +4,7 @@ This is the ACCURATE-BY-CONSTRUCTION half of the api-docs pipeline: every
 documented symbol name comes from the :mod:`metaobjects.apidocs.naming` seam (never
 re-concatenated here — the SAME seam the real generators delegate to), and every
 inclusion decision comes from an applies-predicate that REUSES the corresponding
-generator's own gate helpers (``emits_instance_artifacts`` / ``_primary_source_rdb``
+generator's own gate helpers (``emits_instance_artifacts`` / ``primary_rdb_source``
 + source kind / ``resolve_payload_vo`` / format check / ``is_tph_subtype``) rather
 than re-implementing the gate. The result is that what this builder documents ==
 what the generators emit, by SHARING the single source of truth.
@@ -47,9 +47,9 @@ from metaobjects.codegen.generators.payload_vo_generator import (
     is_field_required,
     resolve_payload_vo,
 )
-from metaobjects.codegen.generators.router_generator import _primary_source_rdb
 from metaobjects.codegen.generators.tph_plan import is_tph_subtype
 from metaobjects.codegen.instance_artifacts import emits_instance_artifacts, is_abstract
+from metaobjects.source_resolution import primary_rdb_source
 from metaobjects.meta.core.field import field_constants as fc
 from metaobjects.meta.core.field.meta_field import MetaField
 from metaobjects.meta.core.object.meta_object import MetaObject
@@ -91,7 +91,7 @@ def _is_writable_table_entity(obj: MetaObject, object_index: dict[str, MetaObjec
         return False
     if is_tph_subtype(obj):
         return False
-    src = _primary_source_rdb(obj)
+    src = primary_rdb_source(obj)
     if src is None:
         return False
     return src.effective_kind() == SOURCE_KIND_TABLE
@@ -261,7 +261,13 @@ class PythonApiModelBuilder:
         add("PUT " + item, "update (PUT alias)")
         add("DELETE " + item, "delete")
 
-        # M:N traversal — GET /<source-plural>/{id}/<relation>.
+        # M:N traversal — GET /<source-plural>/{id}/<relation>. `docs` has no
+        # `GenConfig`/`--column-naming` of its own (see `cli.py`'s docs handler) and
+        # this loop reads only `.target_entity` / `.relation_name` off the
+        # descriptor — never a physical column/table name — so resolving it under
+        # the port default here changes nothing observable; threading a naming
+        # strategy through would mean inventing a config seam this command doesn't
+        # have, for a value nothing here would read.
         for d in resolve_m2m_descriptors(entity, object_index):
             target = object_index.get(d.target_entity)
             target_name = target.name if target is not None else d.target_entity

{metaobjects-0.24.4 → metaobjects-0.25.0}/src/metaobjects/cli.py

@@ -17,6 +17,9 @@ Two subcommands:
 
         --codegen    regenerate into a temp dir + diff against the committed
                      ``--out`` tree (Python's historical default behavior).
+                     ``--column-naming`` must match the strategy ``gen`` was
+                     run with (R31) or the ``names`` generator's constants
+                     report spurious drift.
         --templates  template/prompt ``{{field}}`` ↔ payload-VO drift — the
                      render ``verify()`` gate — resolving each ``template.*``
                      node's refs via a filesystem provider rooted at
@@ -55,6 +58,7 @@ from metaobjects.agent_context import (
 )
 from metaobjects.meta.meta_data import MetaData
 from metaobjects.codegen.config import GenConfig
+from metaobjects.codegen.overwrite_policy import has_hash_manifest, read_generated_hash
 from metaobjects.codegen.project_config import (
     CONFIG_FILENAME,
     ConfigError,
@@ -68,6 +72,7 @@ from metaobjects.codegen.generators.extractor_generator import extractor_generat
 from metaobjects.codegen.generators.filter_allowlist_generator import (
     filter_allowlist_generator,
 )
+from metaobjects.codegen.generators.names_generator import names_generator
 from metaobjects.codegen.generators.output_parser_generator import (
     output_parser_generator,
 )
@@ -87,6 +92,7 @@ from metaobjects.codegen.generators.render_helper_generator import (
     _resolve_payload_vo,
 )
 from metaobjects.meta.template import template_constants as tc
+from metaobjects.naming import COLUMN_NAMING_STRATEGIES, DEFAULT_COLUMN_NAMING
 from metaobjects.render.filesystem_provider import FilesystemProvider
 from metaobjects.render.verify import (
     ERR_REQUIRED_SLOT_UNUSED,
@@ -117,6 +123,7 @@ def _default_generators() -> list[Generator]:
         entity_model(),
         router_generator(),
         filter_allowlist_generator(),
+        names_generator(),
         payload_vo_generator(),
         output_parser_generator(),
         output_prompt_generator(),
@@ -368,6 +375,7 @@ def _run_suite(
     entity_filter: list[str] | None = None,
     emit_package_init: bool = True,
     gen_state_dir: str | None = None,
+    column_naming: str = DEFAULT_COLUMN_NAMING,
 ) -> list[str]:
     """Run a generator suite against an ALREADY-LOADED ``root`` into ``out_dir``.
 
@@ -396,6 +404,7 @@ def _run_suite(
         out_dir=out_dir,
         emit_package_init=emit_package_init,
         gen_state_dir=gen_state_dir,
+        column_naming=column_naming,
     )
     suite = generators if generators is not None else _default_generators()
     result = run_gen(config, root, generators=suite, entity_filter=entity_filter)
@@ -412,6 +421,7 @@ def _generate(
     emit_package_init: bool = True,
     strict: bool = False,
     providers: list[object] | None = None,
+    column_naming: str = DEFAULT_COLUMN_NAMING,
 ) -> tuple[list[str], list[str]]:
     """Run the generator suite into ``out_dir``.
 
@@ -426,6 +436,10 @@ def _generate(
     ``(written_paths, errors)``. On a load error, ``errors`` is non-empty and no
     files are written. ``strict`` (ADR-0023, #96) is threaded to the load — the
     ``verify --codegen`` caller passes True; ``gen`` keeps the default False.
+    ``column_naming`` (R31) must match the strategy the committed output was
+    produced with, or the ``names`` generator's constants regenerate under the
+    wrong strategy and every ``<ENTITY>_<FIELD>_COLUMN`` reports spurious drift —
+    the caller reads it from the SAME ``--column-naming`` flag `gen` accepts.
     """
     root, errors = _load_root(metadata_dir, strict=strict, providers=providers)
     if root is None:
@@ -438,7 +452,10 @@ def _generate(
     # directory deleted seconds later. The real gen paths anchor their own manifest via
     # gen_state_dir_for().
     return (
-        _run_suite(root, out_dir, generators, entity_filter, emit_package_init, None),
+        _run_suite(
+            root, out_dir, generators, entity_filter, emit_package_init, None,
+            column_naming=column_naming,
+        ),
         [],
     )
 
@@ -454,6 +471,65 @@ def gen_state_dir_for(metadata_dir: str) -> str:
     return str(Path(metadata_dir).resolve().parent / ".metaobjects" / ".gen-state")
 
 
+#: The conventional declarative-template-spec file (SP-1 §4), discovered when
+#: ``--template-spec`` is not passed. VISIBLE and at the project root on purpose:
+#: this repo splits author input (visible — ``metaobjects/``, ``templates/``) from
+#: tool state (hidden — ``.metaobjects/``), and a spec is authored, not generated.
+#: It also sits beside the ``templates/`` dir its refs resolve under.
+TEMPLATE_SPEC_FILENAME = "template-spec.json"
+
+
+def project_root_for(metadata_dir: str) -> Path:
+    """The project a metadata directory belongs to: its PARENT — the directory
+    holding ``metaobjects/``. Same rule as :func:`gen_state_dir_for` (which is
+    anchored here) and the C# port's ``GenCommand.ProjectRootFor``."""
+    return Path(metadata_dir).resolve().parent
+
+
+def template_spec_path_for(metadata_dir: str, explicit: str | None) -> str | None:
+    """Resolve the template-spec to use, or ``None`` for "no template generators".
+
+    An explicit ``--template-spec`` always wins and is used verbatim (a flag naming
+    a missing file stays a hard error at read time — silently ignoring a path the
+    user typed would be worse). Otherwise the conventional
+    ``<projectRoot>/template-spec.json`` is used IF it exists.
+
+    **Every code path that builds a generator list must call this.** The defect this
+    exists to prevent is `gen` and `verify --codegen` resolving the spec differently:
+    `gen` honoured the flag while `verify` built its own list and never looked, so
+    `verify` regenerated WITHOUT the template generators and reported their committed
+    output as stale — with a remedy that loops (regenerating cannot produce files the
+    regen does not know about).
+    """
+    if explicit:
+        return explicit
+    candidate = project_root_for(metadata_dir) / TEMPLATE_SPEC_FILENAME
+    return str(candidate) if candidate.is_file() else None
+
+
+def template_spec_generators(
+    metadata_dir: str, explicit: str | None, templates_dir: str,
+) -> tuple[list[Generator], str | None]:
+    """The declarative Mustache generators for this project, or an error message.
+
+    Returns ``(generators, None)`` on success — an EMPTY list when there is no spec
+    at all — and ``([], message)`` when a spec was found but could not be used.
+    """
+    spec_path = template_spec_path_for(metadata_dir, explicit)
+    if spec_path is None:
+        return [], None
+    from metaobjects.codegen.template_codegen.template_spec import (
+        parse_template_spec,
+        template_spec_to_generators,
+    )
+
+    try:
+        spec = parse_template_spec(json.loads(Path(spec_path).read_text(encoding="utf-8")))
+    except (OSError, ValueError) as exc:
+        return [], f"error: invalid template-spec {spec_path!r}: {exc}"
+    return template_spec_to_generators(spec, FilesystemProvider(templates_dir)), None
+
+
 def resolve_metadata_location(
     config: ProjectConfig | None,
     root: Path,
@@ -696,20 +772,12 @@ def _cmd_gen(args: argparse.Namespace) -> int:
     # SEPARATE pass with emit_package_init=False — no Python __init__.py is injected
     # into their (possibly non-Python) output tree. Templates resolve under
     # --templates via a FilesystemProvider.
-    spec_gens: list[Generator] = []
-    if getattr(args, "template_spec", None):
-        from metaobjects.codegen.template_codegen.template_spec import (
-            parse_template_spec,
-            template_spec_to_generators,
-        )
-
-        try:
-            spec = parse_template_spec(json.loads(Path(args.template_spec).read_text(encoding="utf-8")))
-        except (OSError, ValueError) as exc:
-            print(f"error: invalid --template-spec: {exc}", file=sys.stderr)
-            return 1
-        provider = FilesystemProvider(args.templates)
-        spec_gens = template_spec_to_generators(spec, provider)
+    spec_gens, spec_err = template_spec_generators(
+        args.metadata_dir, getattr(args, "template_spec", None), args.templates,
+    )
+    if spec_err is not None:
+        print(spec_err, file=sys.stderr)
+        return 1
 
     entities = _parse_entities(getattr(args, "entities", None))
     providers, providers_ok = _providers_from_args(args)
@@ -724,7 +792,11 @@ def _cmd_gen(args: argparse.Namespace) -> int:
             print(f"  {msg}", file=sys.stderr)
         return 1
     gen_state = gen_state_dir_for(args.metadata_dir)
-    written = _run_suite(root, args.out, generators, entities, gen_state_dir=gen_state)
+    column_naming = getattr(args, "column_naming", None) or DEFAULT_COLUMN_NAMING
+    written = _run_suite(
+        root, args.out, generators, entities,
+        gen_state_dir=gen_state, column_naming=column_naming,
+    )
     if spec_gens:
         # The template-spec pass renders user-supplied templates: a bad ref or a
         # wrong --templates dir raises RenderError (not OSError/ValueError, so it
@@ -734,7 +806,7 @@ def _cmd_gen(args: argparse.Namespace) -> int:
         try:
             spec_written = _run_suite(
                 root, args.out, spec_gens, entities, emit_package_init=False,
-                gen_state_dir=gen_state,
+                gen_state_dir=gen_state, column_naming=column_naming,
             )
         except RenderError as exc:
             print(
@@ -845,7 +917,11 @@ def _cmd_gen_neutral_fallback(args: argparse.Namespace) -> int:
         return 1
 
     gen_state = str(root_dir.resolve() / ".metaobjects" / ".gen-state")
-    written = _run_suite(root, args.out, generators, entities, gen_state_dir=gen_state)
+    column_naming = getattr(args, "column_naming", None) or DEFAULT_COLUMN_NAMING
+    written = _run_suite(
+        root, args.out, generators, entities,
+        gen_state_dir=gen_state, column_naming=column_naming,
+    )
     for path in written:
         print(path)
     print(f"metaobjects gen: wrote {len(written)} file(s) to {args.out}")
@@ -864,6 +940,23 @@ def _cmd_gen_config(args: argparse.Namespace) -> int:
     config_path = _find_config(args)
     if config_path is None:
         return _cmd_gen_neutral_fallback(args)
+    # An EXPLICIT --template-spec here was silently ignored: config mode goes straight
+    # to _run_gen_targets, which has no spec pass. Refuse instead of accepting a flag
+    # that does nothing. It cannot simply be honoured, because a spec has no `target`
+    # (the CLI ports reject that field outright) while config mode is target-shaped, so
+    # there is no non-arbitrary outDir to write into. A DISCOVERED spec is ignored here
+    # rather than refused — discovery must not hard-fail a command that never asked for
+    # it, and gen/verify agree in config mode either way, so no drift can result.
+    if getattr(args, "template_spec", None):
+        print(
+            "error: --template-spec is not supported in declarative-config mode "
+            f"({config_path}): a template-spec entry names no target, and config mode "
+            "writes per target, so there is no outDir to render into. Run the explicit "
+            "form instead: metaobjects gen <metadata_dir> --out <dir> --template-spec "
+            "<json> --templates <dir>.",
+            file=sys.stderr,
+        )
+        return 2
     try:
         config = load_project_config(config_path)
     except ConfigError as exc:
@@ -903,33 +996,83 @@ def _cmd_gen_config(args: argparse.Namespace) -> int:
     return 0
 
 
+#: Never compared: interpreter droppings, not generated artifacts. A committed
+#: ``__pycache__`` would otherwise read as drift on every run.
+_UNCOMPARED_DIRS = {"__pycache__", ".gen-state", ".metaobjects"}
+_UNCOMPARED_SUFFIXES = {".pyc", ".pyo"}
+
+
 def _relative_set(root: Path) -> dict[str, str]:
-    """Map every ``*.py`` file under ``root`` to its content, keyed by rel path.
+    """Map every generated-artifact file under ``root`` to its content, keyed by rel path.
 
-    Scoped to ``*.py`` because the Python codegen suite emits only Python sources;
-    if a generator ever emits a non-``.py`` artifact, broaden this glob so ``verify``
-    drift-checks it too.
+    Deliberately NOT scoped to ``*.py``. It was, with a note saying to broaden it "if a
+    generator ever emits a non-``.py`` artifact" — and one does: the declarative
+    ``--template-spec`` generators emit text/markdown/csv/json/xml/html by design. The
+    consequence was a gate that answered ``in sync`` with a template-emitted file
+    DELETED and another CORRUPTED, because neither was a ``.py`` and neither was
+    compared. A gate silent about its own output is worse than one that is wrong.
+
+    Binary files are skipped rather than decoded: every generator this project ships
+    emits text, so an undecodable file is by definition not ours.
     """
     files: dict[str, str] = {}
-    if root.exists():
-        for p in sorted(root.rglob("*.py")):
-            files[str(p.relative_to(root))] = p.read_text()
+    if not root.exists():
+        return files
+    for p in sorted(root.rglob("*")):
+        if not p.is_file():
+            continue
+        rel = p.relative_to(root)
+        if any(part in _UNCOMPARED_DIRS for part in rel.parts):
+            continue
+        if p.suffix in _UNCOMPARED_SUFFIXES:
+            continue
+        try:
+            files[str(rel)] = p.read_text(encoding="utf-8")
+        except (UnicodeDecodeError, OSError):
+            continue
     return files
 
 
-def _diff_report(expected: dict[str, str], committed: dict[str, str]) -> int:
+def _is_ours_for(gen_state_dir: str | None):
+    """Jurisdiction predicate for the ``extra`` verdict: did WE write this path?
+
+    ``out_dir`` is a DIRECTORY, not a namespace this tool owns — the same ruling the
+    TypeScript gate reached (0.24.3), for the same reason. Broadening the comparison
+    beyond ``*.py`` means the gate now sees every stranger's file too, and convicting
+    those turns a project with zero drift into a red build.
+
+    The manifest already records what we WROTE, keyed relative to ``out_dir`` — the
+    same key space this diff uses — so it answers the ownership question exactly.
+    FAILS CLOSED, matching :func:`is_pristine_generated`: with no manifest at all
+    nothing is proven, so every file stays in scope and the old verdict stands.
+    """
+    if gen_state_dir is None or not has_hash_manifest(gen_state_dir):
+        return lambda _rel: True
+    return lambda rel: read_generated_hash(gen_state_dir, rel) is not None
+
+
+def _diff_report(
+    expected: dict[str, str],
+    committed: dict[str, str],
+    gen_state_dir: str | None = None,
+) -> int:
     """Compare a regenerated file map against the committed one; print the
     standard ``verify --codegen`` drift report. Returns 0 (in sync) or 1.
 
     Extracted so the explicit-``<metadata_dir>`` flag mode
     (:func:`_verify_codegen`) and the ``.metaobjects/config.json`` fallback
     rung (:func:`_verify_codegen_neutral_fallback`) report drift identically.
+
+    ``gen_state_dir`` scopes the ``extra`` verdict to files we have a record of
+    writing — see :func:`_is_ours_for`. Omit it to keep the unscoped verdict.
     """
+    is_ours = _is_ours_for(gen_state_dir)
     changed = sorted(
         k for k in expected if k in committed and expected[k] != committed[k]
     )
     missing = sorted(k for k in expected if k not in committed)  # not yet committed
-    extra = sorted(k for k in committed if k not in expected)  # stale committed file
+    # A committed file a fresh regen would not emit is STALE only if it is ours.
+    extra = sorted(k for k in committed if k not in expected and is_ours(k))
 
     if not changed and not missing and not extra:
         print(f"metaobjects verify: in sync ({len(expected)} file(s)).")
@@ -973,13 +1116,37 @@ def _verify_codegen(args: argparse.Namespace) -> int:
     # ADR-0023 strict-by-default (#96): verify loads strict unless --lax is given,
     # so an undeclared/typo'd own @attr fails verify (matching Java's Maven goal).
     strict = not getattr(args, "lax", False)
+    # R31: the `names` generator's constants are strategy-dependent (#248-adjacent —
+    # the same generator Task 9 turned on). A regen that defaults to `literal` while
+    # the committed output was produced with `gen --column-naming snake_case` (or any
+    # other non-default strategy) convicts every <ENTITY>_<FIELD>_COLUMN constant as
+    # drift — a gate failing work the product itself sanctions. Must match the `gen`
+    # invocation that produced --out, exactly like --entities above.
+    column_naming = getattr(args, "column_naming", None) or DEFAULT_COLUMN_NAMING
     providers, providers_ok = _providers_from_args(args)
     if not providers_ok:
         return 1
+    # The declarative template generators, resolved by the SAME rule `gen` uses —
+    # explicit flag, else the conventional <projectRoot>/template-spec.json. Without
+    # this, verify regenerated only the default suite and then reported every
+    # spec-emitted file as `extra:` ("stale committed file"), exiting 1 with a remedy
+    # that loops: `gen` reproduces those files but the next verify fails identically.
+    # `verify` spells the templates dir --templates-root (its --templates is the
+    # subverb selector), so the flag is read per-verb and threaded to one resolver.
+    spec_gens, spec_err = template_spec_generators(
+        args.metadata_dir,
+        getattr(args, "template_spec", None),
+        getattr(args, "templates_root", None) or "templates",
+    )
+    if spec_err is not None:
+        print(spec_err, file=sys.stderr)
+        return 1
+
     with tempfile.TemporaryDirectory() as tmp:
         entities = _parse_entities(getattr(args, "entities", None))
         written, errors = _generate(
-            args.metadata_dir, tmp, None, entities, strict=strict, providers=providers
+            args.metadata_dir, tmp, None, entities, strict=strict, providers=providers,
+            column_naming=column_naming,
         )
         if errors:
             print("error: failed to load metadata:", file=sys.stderr)
@@ -989,10 +1156,30 @@ def _verify_codegen(args: argparse.Namespace) -> int:
                 print(_strict_load_hint(), file=sys.stderr)
             return 1
 
+        if spec_gens:
+            # Mirror `gen`'s SECOND pass exactly, emit_package_init=False included —
+            # a diff against output produced by a two-pass gen has to be produced the
+            # same way, or the __init__.py placement alone reads as drift.
+            from metaobjects.render.renderer import RenderError
+
+            try:
+                _generate(
+                    args.metadata_dir, tmp, spec_gens, entities,
+                    emit_package_init=False, strict=strict, providers=providers,
+                    column_naming=column_naming,
+                )
+            except RenderError as exc:
+                print(
+                    f"error: template-spec render failed (check the template refs and "
+                    f"the templates dir): {exc}",
+                    file=sys.stderr,
+                )
+                return 1
+
         expected = _relative_set(Path(tmp))
         committed = _relative_set(Path(args.out))
 
-    return _diff_report(expected, committed)
+    return _diff_report(expected, committed, gen_state_dir_for(args.metadata_dir))
 
 
 def _verify_codegen_neutral_fallback(args: argparse.Namespace) -> int:
@@ -1018,6 +1205,10 @@ def _verify_codegen_neutral_fallback(args: argparse.Namespace) -> int:
         return 1
 
     strict = not getattr(args, "lax", False)
+    # R31 — see _verify_codegen: must match the strategy `gen` (this same rung)
+    # produced --out with, or the `names` generator's constants regenerate under
+    # the wrong strategy and report spurious drift.
+    column_naming = getattr(args, "column_naming", None) or DEFAULT_COLUMN_NAMING
     providers, providers_ok = _providers_from_args(args)
     if not providers_ok:
         return 1
@@ -1033,11 +1224,18 @@ def _verify_codegen_neutral_fallback(args: argparse.Namespace) -> int:
                 print(_strict_load_hint(), file=sys.stderr)
             return 1
 
-        _run_suite(root, tmp, None, entities, gen_state_dir=None)
+        _run_suite(
+            root, tmp, None, entities, gen_state_dir=None, column_naming=column_naming
+        )
         expected = _relative_set(Path(tmp))
         committed = _relative_set(Path(args.out))
 
-    return _diff_report(expected, committed)
+    # This rung has NO positional metadata dir — cwd is the project (same anchor
+    # `_cmd_gen_neutral_fallback` writes its manifest to), so the jurisdiction lookup
+    # must be built from that, not from args.metadata_dir (None here by definition).
+    return _diff_report(
+        expected, committed, str(root_dir.resolve() / ".metaobjects" / ".gen-state")
+    )
 
 
 def _temp_slot_for(temp_root: Path, real_outdir: str, config_dir: Path) -> str:
@@ -1150,7 +1348,11 @@ def _verify_codegen_config(args: argparse.Namespace) -> int:
                 k for k in expected if k in committed and expected[k] != committed[k]
             )
             missing = sorted(k for k in expected if k not in committed)
-            extra = sorted(k for k in committed if k not in expected)
+            # Same jurisdiction rule as _diff_report — this rung inlines its diff to
+            # report per-target, so the guard has to be inlined with it. Without it,
+            # broadening the comparison past *.py convicts every stranger's file.
+            is_ours = _is_ours_for(gen_state_dir_for(config.metadata_dir()))
+            extra = sorted(k for k in committed if k not in expected and is_ours(k))
 
             names = "+".join(
                 t.name for t in closure if config.out_dir_for(t) == real_outdir
@@ -1411,6 +1613,19 @@ def _build_parser() -> argparse.ArgumentParser:
         help="directory of metadata JSON/YAML files",
     )
     gen.add_argument("--out", default=None, help="output directory for generated code")
+    gen.add_argument(
+        "--column-naming",
+        dest="column_naming",
+        choices=COLUMN_NAMING_STRATEGIES,
+        default=DEFAULT_COLUMN_NAMING,
+        help=(
+            "column-naming strategy for a field with no explicit @column "
+            f"(default: {DEFAULT_COLUMN_NAMING!r}, matching this port's "
+            "ObjectManager default — NOT `meta migrate`'s snake_case). Read by "
+            "the `names` generator; pass the same strategy the schema was "
+            "created with."
+        ),
+    )
     gen.add_argument(
         "--generators",
         default=None,
@@ -1550,6 +1765,19 @@ def _build_parser() -> argparse.ArgumentParser:
         action="store_true",
         help="codegen drift: regenerate to a temp dir + diff vs --out (default)",
     )
+    verify.add_argument(
+        "--column-naming",
+        dest="column_naming",
+        choices=COLUMN_NAMING_STRATEGIES,
+        default=DEFAULT_COLUMN_NAMING,
+        help=(
+            "column-naming strategy the committed --out was generated with (default: "
+            f"{DEFAULT_COLUMN_NAMING!r}, matching `gen`'s default). The `names` "
+            "generator's constants are strategy-dependent, so a --codegen regen must "
+            "use the SAME strategy `gen` was run with or every <ENTITY>_<FIELD>_COLUMN "
+            "constant reports spurious drift."
+        ),
+    )
     verify.add_argument(
         "--templates",
         action="store_true",