cli.py

"""The ``metaobjects`` console-script — codegen `gen` + drift `verify` (SP-E Unit 2).

Two subcommands:

  metaobjects gen    <metadataDir> --out <dir> [--package <pkg>]
                     [--templates <dir>] [--template-spec <json>]
      Load metadata, run the Python codegen generator suite, and write files
      under ``--out`` (guarded by the @generated header). Prints each written
      file. Non-zero exit on a load error. ``--template-spec`` appends the
      declarative Mustache template generators (scope perEntity/perPackage/
      perModel + outputPattern) described by a JSON spec.

      ``--templates <dir>`` is the on-disk root every template ref resolves
      under. It feeds BOTH the ``--template-spec`` pass and the ``render-helper``
      generator's build-time drift gate; until 1.0.5 it reached only the former,
      so ``--generators render-helper`` read a hardcoded ``templates`` whatever
      this flag said.

  metaobjects verify <metadataDir> [--codegen] [--templates] [--db URL] ...
      Drift gate with explicit subverbs (ADR-0021 D2 — one verify vocabulary
      across ports):

        --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
                     ``--templates-root``.
        --db URL     REJECTED in the Python port (exit 2): schema verify is the
                     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.

Named ``metaobjects``, NOT ``meta``: ``meta`` is the Node schema CLI. This CLI
intentionally has NO ``migrate`` subcommand — schema is owned by the Node
toolchain (ADR-0015). The ``--codegen`` mode shares the exact same generation
code path as ``gen`` (verify = gen-to-temp + diff), so drift can never be a
generator-wiring divergence between the two commands.
"""

from __future__ import annotations

import argparse
import dataclasses
import json
import os
import re
import sys
import tempfile
from pathlib import Path
from typing import Callable

from metaobjects import MetaDataLoader
from metaobjects.errors import ErrorCode, MetaError, ParseError
from metaobjects.config.dependencies import (
    Collection,
    imported_from,
    refuse_library_package_misuse,
    refuse_unowned_packages,
)
from metaobjects.config.neutral_config import read_neutral_config
from metaobjects.field_lint import FieldLintFinding, lint_duplicate_fields, lint_reference_fields
from metaobjects.loader.meta_data_loader import LoadResult
from metaobjects.loader.sources import FileSource
from metaobjects.meta.core.object.meta_object import MetaObject
from metaobjects.agent_context import (
    AGENT_CONTEXT_MANIFEST_PATH,
    agent_context_staleness,
    installed_metaobjects_version,
)
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,
    ProjectConfig,
    TargetConfig,
    load_project_config,
)
from metaobjects.codegen.generator import Generator
from metaobjects.codegen.generators.entity_model import entity_model
from metaobjects.codegen.generators.extractor_generator import extractor_generator
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,
)
from metaobjects.codegen.generators.output_prompt_generator import (
    output_prompt_generator,
)
from metaobjects.codegen.generators.router_generator import router_generator
from metaobjects.codegen.generator_registry import (
    GENERATOR_REGISTRY,
    GeneratorBuildContext,
    get_generator,
    list_generators,
    unsatisfied_requires,
)
from metaobjects.codegen.runner import run_gen
from metaobjects.codegen import eject as owned
from metaobjects.codegen.generators.render_helper_generator import (
    _derive_payload_field_tree,
)
from metaobjects.codegen.value_objects import pkg_of, resolve_payload_vo
from metaobjects.meta.template import template_constants as tc
from metaobjects.naming import COLUMN_NAMING_STRATEGIES, DEFAULT_COLUMN_NAMING, package_of_resolution_key
from metaobjects.render.filesystem_provider import FilesystemProvider
from metaobjects.render.verify import (
    ERR_REQUIRED_SLOT_UNUSED,
    PayloadField,
    verify as render_verify,
)
from metaobjects.shared.base_types import TYPE_OBJECT, TYPE_TEMPLATE


#: The error a run with no generator selection reports.
#:
#: There is no default suite. This port used to run EIGHT generators for a caller who
#: named none — entity, router, filter-allowlist, names, payload, output-parser,
#: output-prompt, extractor — which is a shape nobody chose. Java has never had a
#: default set and has been right all along; TypeScript and C# dropped theirs in the
#: same change.
#:
#: Deciding WHICH code an application needs belongs to whoever is building it —
#: increasingly an LLM working in the repo, which is well able to make that call given a
#: truthful catalog and is badly served by a default that pre-empts it. ``--list`` is
#: that catalog.
NO_GENERATORS_SELECTED = (
    "gen: no generators selected. Nothing is generated until you choose it — "
    "pass --generators <a,b,c>. See the catalog: metaobjects gen --list"
)


class NoGeneratorsSelectedError(ValueError):
    """Raised when a codegen run names no generator. Carries the usage message."""

    def __init__(self) -> None:
        super().__init__(NO_GENERATORS_SELECTED)


def _resolve_providers(specs: list[str] | None) -> tuple[list[object], list[str]]:
    """Import consumer providers named as ``module:symbol`` (repeatable ``--provider``).

    The symbol must be a metaobjects ``Provider`` (or a list of them, or a zero-arg
    factory returning either). A provider carries CODE — factories and optional
    validators — so it is loaded as a native Python object, not a JSON file (#158).
    This is the Python CLI's idiomatic parity with TS ``metaobjects.config.ts``
    ``providers``; the underlying loader already accepts providers.
    """
    if not specs:
        return [], []
    import importlib

    from metaobjects.provider import Provider

    providers: list[object] = []
    errors: list[str] = []
    for spec in specs:
        module_name, sep, symbol = spec.partition(":")
        if not sep or not module_name or not symbol:
            errors.append(
                f"--provider '{spec}' must be in 'module:symbol' form "
                "(e.g. myapp.providers:my_provider)"
            )
            continue
        try:
            module = importlib.import_module(module_name)
        except Exception as exc:  # ImportError + anything raised at import time
            errors.append(f"--provider '{spec}': cannot import '{module_name}': {exc}")
            continue
        try:
            obj = getattr(module, symbol)
        except AttributeError:
            errors.append(
                f"--provider '{spec}': '{module_name}' has no attribute '{symbol}'"
            )
            continue
        # A zero-arg factory is supported: call it to obtain the provider(s).
        if callable(obj) and not isinstance(obj, Provider):
            try:
                obj = obj()
            except Exception as exc:
                errors.append(f"--provider '{spec}': factory '{symbol}()' raised: {exc}")
                continue
        for item in obj if isinstance(obj, list) else [obj]:
            if isinstance(item, Provider):
                providers.append(item)
            else:
                errors.append(
                    f"--provider '{spec}': '{symbol}' resolved to "
                    f"{type(item).__name__}, expected a metaobjects Provider"
                )
    return providers, errors


def _providers_from_args(args: argparse.Namespace) -> tuple[list[object], bool]:
    """Resolve ``--provider`` specs; print resolution errors. Returns (providers, ok)."""
    providers, errors = _resolve_providers(getattr(args, "provider", None))
    if errors:
        print("error: invalid --provider:", file=sys.stderr)
        for msg in errors:
            print(f"  {msg}", file=sys.stderr)
        return providers, False
    return providers, True


def _find_config(args: argparse.Namespace) -> Path | None:
    """The config path: ``--config`` if given (even if missing → clear load error),
    else ``./metaobjects.config.yaml`` in cwd when it exists, else ``None``."""
    explicit = getattr(args, "config", None)
    if explicit:
        return Path(explicit)
    default = Path.cwd() / CONFIG_FILENAME
    return default if default.is_file() else None


def _config_providers(config: ProjectConfig) -> tuple[list[object], bool]:
    """Resolve ``config.providers`` with the config file's directory on ``sys.path``.

    #267: prepend the config directory so a ``module:symbol`` provider living beside
    the config imports with no ``PYTHONPATH=``. Idempotent; the entry is left in
    place (a short-lived CLI process). Prints resolution errors; returns (providers, ok).
    """
    config_dir = str(config.config_dir)
    if config_dir not in sys.path:
        sys.path.insert(0, config_dir)
    providers, errors = _resolve_providers(config.providers)
    if errors:
        print("error: invalid provider in config:", file=sys.stderr)
        for msg in errors:
            print(f"  {msg}", file=sys.stderr)
        return providers, False
    return providers, True


def _select_targets(
    config: ProjectConfig, target_name: str | None
) -> tuple[list[TargetConfig], str | None]:
    """All targets, or the single ``--target`` (error string when the name is unknown)."""
    if target_name is None:
        return config.targets, None
    t = config.target(target_name)
    if t is None:
        known = ", ".join(sorted(x.name for x in config.targets))
        return [], f"unknown --target {target_name!r}; known targets: {known}"
    return [t], None


def _merge_libraries(*groups: "list[str] | tuple[str, ...] | None") -> list[str]:
    """Union several ``libraries`` selection-token groups, de-duplicated and
    order-preserving (first occurrence wins the position).

    Every group is a selection from a DIFFERENT source for the same concept —
    the neutral ``.metaobjects/config.json`` (FR-043 §12 Q4, read at every rung)
    and, where one exists, a per-port config surface's own ``libraries:`` key
    (Python's ``metaobjects.config.yaml``). Neither is authoritative over the
    other, so a project may declare libraries in either place or both.
    """
    seen: dict[str, None] = {}
    for group in groups:
        for token in group or ():
            seen.setdefault(token, None)
    return list(seen)


def _load_root(
    metadata_dir: str,
    strict: bool = False,
    providers: list[object] | None = None,
    libraries: list[str] | None = None,
    unknown_attr_out: list[str] | None = None,
) -> tuple[MetaData | None, list[str]]:
    """Load metadata; return ``(root, error_messages)``. ``root`` is None on error.

    ``unknown_attr_out`` — when given on a LENIENT load, a second strict load of the
    same metadata is run and its ``ERR_UNKNOWN_ATTR`` findings are appended, formatted,
    so ``gen`` can warn about what ``verify`` would reject instead of staying silent.

    ``strict`` (ADR-0023, #96) — when True, an undeclared own ``@attr`` →
    ``ERR_UNKNOWN_ATTR``. Defaults False so ``gen`` / ``docs`` keep the legacy
    open-attr load; only ``verify`` opts in (strict-by-default with a ``--lax``
    escape).

    ``providers`` (#158) — consumer providers (from ``--provider module:symbol``)
    composed ON TOP of the core set, so a config-registered custom subtype resolves
    through the standalone CLI just as it does when an app loads the loader directly.
    Empty/None keeps the core-providers-only default (``from_directory`` convenience).

    ``libraries`` — MetaObjects-shipped library packages (config key ``libraries``,
    e.g. ``["ai"]``). Without this the CLI could not load ``metaobjects::ai::LlmCallBase``,
    so ``metaobjects gen`` failed with ERR_UNRESOLVED_SUPER on exactly the metadata the
    registered ``trace-helper`` generator exists to consume — the generator was reachable
    from the CLI while its input was not. ADDITIVE to (never a replacement for) the
    neutral ``.metaobjects/config.json``'s own ``libraries`` key (FR-043 §12 Q4), which
    this function ALWAYS also reads, from the project holding ``metadata_dir``
    (:func:`project_root_for`) — an explicit-``metadata_dir`` CLI invocation
    (``gen``, ``docs``, ``verify --templates``, ``verify --codegen``'s
    regenerate-to-temp path) never resolves a `Collection`
    (:func:`resolve_metadata_location`'s docstring: rung 1 is not its concern), so
    without this an adopter whose opt-in lives only in ``.metaobjects/config.json``
    could not run any explicit-directory command against metadata using a library
    at all — exactly the gap ``config``-mode (:func:`_cmd_gen_config`) does not have,
    because it already threads ``config.libraries`` through
    :func:`_load_root_from_collection`.
    """
    try:
        neutral = read_neutral_config(project_root_for(metadata_dir))
    except ParseError as exc:
        return None, [f"{exc.code}: {exc}"]
    all_libraries = _merge_libraries(neutral.libraries if neutral is not None else None, libraries)

    def load(strict_load: bool) -> LoadResult:
        if providers:
            from metaobjects.core_types import core_providers

            return MetaDataLoader.from_directory(
                metadata_dir,
                providers=[*core_providers, *providers],
                strict=strict_load,
                libraries=all_libraries,
            )
        return MetaDataLoader.from_directory(
            metadata_dir, strict=strict_load, libraries=all_libraries
        )

    try:
        result = load(strict)
        if unknown_attr_out is not None and not strict and not result.errors:
            unknown_attr_out.extend(_unknown_attr_findings(load(True)))
    except OSError as e:
        # `DirectorySource.expand()` walks via `iterdir()` (not `rglob()`, so it
        # can follow a symlinked subdirectory — the I1 fix) and raises a plain
        # OSError (FileNotFoundError / NotADirectoryError, or `SymlinkLoopError`
        # on a symlink cycle) when `metadata_dir` itself can't be walked. Nothing
        # upstream of this call catches it, so it would otherwise surface as a
        # raw Python traceback instead of the coded "error: failed to load
        # metadata" every other `_load_root` failure prints. Mirrors the
        # TypeScript reference, which wraps the equivalent `readdir` failure in
        # a clean `Error` at the same boundary (`metadata-files.ts`,
        # `listMetadataFiles`: "cannot read metadata directory ...").
        return None, [f"cannot read metadata directory {metadata_dir}: {e}"]
    if result.errors:
        msgs = [f"{e.code}: {e.message}" for e in result.errors]
        return None, msgs
    try:
        # FR-043 §3.4 / §3.5 — same misuse guard the `Collection` load path runs
        # (`_load_collection_result`): an explicit-directory load opted into a
        # library was the one path that never checked for an ejected-copy
        # collision or an adopter node declared straight into the library's
        # package.
        refuse_library_package_misuse(result.root, all_libraries)
    except ParseError as exc:
        return None, [f"{exc.code}: {exc}"]
    return result.root, []


def _load_collection_result(
    collection: Collection,
    strict: bool = False,
    providers: list[object] | None = None,
    libraries: list[str] | None = None,
) -> LoadResult:
    """Load a resolved `Collection`'s files — its dependency artifacts leading,
    each under its `dep:<name>/<artifact>` source id (FR-023) — then run the
    post-load ownership refusal (`ERR_DEPENDENCY_PACKAGE_NOT_OWNED`, DESIGN
    §11.5). Mirrors the TS `loadMemory` (`sdk/src/memory.ts`).

    ``libraries`` is ADDITIVE to ``collection.libraries`` (the neutral
    `.metaobjects/config.json`'s own key, read at every rung — FR-043 §12 Q4),
    never a replacement for it: a caller passes a per-port config surface's own
    selection here (Python's `metaobjects.config.yaml` `libraries:` key), and
    both are merged before resolving library sources.

    Lower-level than :func:`_load_root_from_collection`: this returns the raw
    `LoadResult` (structured `MetaError`s, a code + provenance on each) rather
    than the CLI's flattened `(root, message-strings)` contract, so a caller
    that needs the CODE or the offending FILE — the dependency corpus runner —
    can read them. ``refuse_unowned_packages`` runs AFTER the loader's own
    errors, never before: an unflagged overlay whose target the upstream
    removed fails first, with its own coded error.
    """
    # `collection.libraries` (FR-043 §12 Q4 — the neutral `.metaobjects/config.json`,
    # read at every rung) is merged with whatever the caller additionally passes
    # (a per-port config surface's own `libraries:` key, e.g. Python's
    # `metaobjects.config.yaml` — see `_cmd_gen_config`). Neither source is
    # authoritative over the other.
    all_libraries = _merge_libraries(collection.libraries, libraries)

    lib_sources: list[object] = []
    if all_libraries:
        from metaobjects.library import library_sources

        lib_sources = library_sources(all_libraries)

    sources = [FileSource(p, id=collection.file_ids.get(p)) for p in collection.files]

    if providers:
        from metaobjects.core_types import core_providers

        loader = MetaDataLoader(providers=[*core_providers, *providers], strict=strict)
    else:
        loader = MetaDataLoader(strict=strict)

    result = loader.load([*lib_sources, *sources])
    if not result.errors:
        refuse_unowned_packages(result.root, collection.imported_packages, collection.imported_nodes)
        # FR-043 §3.4 / §3.5 — the same rule for a shipped LIBRARY's package, where the
        # two ways to get it wrong are opposite: a node the library also declares (an
        # ejected copy, still opted in) and one it does not (a new node in someone
        # else's package).
        refuse_library_package_misuse(result.root, all_libraries)
    return result


def _load_root_from_collection(
    collection: Collection,
    strict: bool = False,
    providers: list[object] | None = None,
    libraries: list[str] | None = None,
    unknown_attr_out: list[str] | None = None,
) -> tuple[MetaData | None, list[str]]:
    """Load a resolved `Collection` — the source-resolution ladder's
    ``.metaobjects/config.json`` rung (:func:`resolve_metadata_location`), which
    can resolve to several directories, individual files, AND a dependency's
    snapshot artifact, none of which a single ``from_directory`` call can
    express. Mirrors :func:`_load_root`'s ``strict``/``providers``/``libraries``
    contract exactly (CLI-facing: flattened error messages, never a raised
    exception for a plain loader error).
    """
    try:
        result = _load_collection_result(collection, strict=strict, providers=providers, libraries=libraries)
    except ParseError as exc:
        return None, [f"{exc.code}: {exc}"]
    if result.errors:
        msgs = [f"{e.code}: {e.message}" for e in result.errors]
        return None, msgs
    if unknown_attr_out is not None and not strict:
        # See `_load_root`: what a strict load (`verify`) would reject, for `gen` to warn.
        try:
            strict_result = _load_collection_result(
                collection, strict=True, providers=providers, libraries=libraries
            )
        except ParseError:
            strict_result = None
        if strict_result is not None:
            unknown_attr_out.extend(_unknown_attr_findings(strict_result))
    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.
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."
)


def _format_unknown_attr(err: MetaError) -> str:
    """One ``gen`` warning: code + message (naming attribute and node), then the file."""
    env = getattr(err, "envelope", None)
    files = [f for f in (getattr(env, "files", None) or ()) if f]
    json_path = getattr(env, "json_path", None)
    where = " ".join(
        p for p in (", ".join(files) if files else None, f"at {json_path}" if json_path else None) if p
    )
    head = f"{err.code.value if hasattr(err.code, 'value') else err.code}: {err.message}"
    return f"{head}\n  in {where}" if where else head


def _unknown_attr_findings(result: LoadResult) -> list[str]:
    """The ERR_UNKNOWN_ATTR findings of a STRICT load, formatted for ``gen``."""
    return [
        _format_unknown_attr(e) for e in result.errors
        if (e.code.value if hasattr(e.code, "value") else e.code) == ErrorCode.ERR_UNKNOWN_ATTR.value
    ]


def _print_unknown_attr_warnings(findings: list[str]) -> None:
    """``gen`` loads leniently; an unknown attribute ``verify`` would reject is named here
    as a warning (attribute, node, file). Advisory only: the exit code is unchanged."""
    if not findings:
        return
    for f in findings:
        print(f"warning: {f}", file=sys.stderr)
    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."""
    return (
        "verify 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."
    )


#: The canonical directory name for authored template bodies. Named `prompts` because
#: that is what the Node CLI has always called it (`DEFAULT_PROMPTS_DIR`), and the Node
#: CLI is the schema door every project meets first.
DEFAULT_PROMPTS_DIR = "prompts"

#: The name this port defaulted to before 1.0.5, kept as the FALLBACK rather than
#: replaced. Flipping the default outright would move where an existing project's
#: template refs resolve from, and a project whose bodies are in `templates/` would
#: start finding nothing — a silent drift-gate failure, or worse a `verify --codegen`
#: that convicts committed output. A fallback breaks nobody: a project with
#: `templates/` and no `prompts/` behaves exactly as it did.
LEGACY_TEMPLATES_DIR = "templates"


def _default_template_root(base: str | Path = ".") -> str:
    """The template root to use when the caller named none.

    `prompts` when it exists, else `templates`. The two halves of the toolchain
    disagreed about this: the Node CLI has always defaulted to `prompts`, while this
    port and C#'s `GenCommand` defaulted to `templates`, so a project following the
    Node CLI's layout — which this repo's own adopter estate does — had a `gen` that
    looked somewhere its `prompts/` was not.
    """
    return (DEFAULT_PROMPTS_DIR if Path(base, DEFAULT_PROMPTS_DIR).is_dir()
            else LEGACY_TEMPLATES_DIR)


def _template_root_for(args: argparse.Namespace) -> str:
    """The on-disk template root for THIS invocation. Never ``None``.

    EVERY path that builds a generator list must call this, for the same reason the C#
    port says it of its template-spec resolution: ``gen`` and ``verify --codegen``
    regenerate the same suite and diff the result, so if they resolve the template root
    differently, ``verify`` builds ``render-helper`` against another directory and
    reports the committed helpers as stale — with a remedy that loops, since
    regenerating cannot fix a disagreement about where the templates are. That is also
    why the fallback applies to BOTH commands: a default on one and not the other is the
    same disagreement wearing a different hat.

    The two commands spell the directory differently, and that is not cosmetic. On
    ``gen`` it is ``--templates <dir>``. On ``verify`` ``--templates`` is the BOOLEAN
    prompt-drift subverb and the directory is ``--prompts <dir>`` (F101's converged
    spelling; ``--templates-root`` is its deprecated alias, and argparse lands both on
    ``templates_root``). Hence the isinstance check rather than a plain ``or`` chain:
    ``getattr(args, "templates")`` is a ``True`` on one of these commands, and ``or``
    would hand a boolean to a path join.
    """
    gen_dir = getattr(args, "templates", None)
    if isinstance(gen_dir, str) and gen_dir:
        return gen_dir
    explicit_verify = getattr(args, "templates_root", None)
    if explicit_verify:
        return explicit_verify
    return _default_template_root()


def _resolve_generators(
    names: str, ctx: GeneratorBuildContext | None = None, owned_root: Path | None = None,
) -> tuple[list[Generator], list[str]]:
    """Resolve a comma-separated list of STABLE generator names via the registry.

    An entry of the form ``module:symbol`` is an adopter-owned copy (``metaobjects
    eject``), imported with *owned_root* (default: the working directory) on ``sys.path``
    — the config directory in config mode, so a copy beside the config resolves.

    Returns ``(generators, errors)``. An unknown name produces a clear error and
    no generators (so the caller can fail with exit code != 0).

    *ctx* carries what a factory needs beyond the metadata — today the on-disk template
    root, which ``render-helper`` requires for its build-time drift gate. It used to be
    absent entirely: the registry hardcoded ``template_root="templates"``, so
    ``--templates`` reached the template-spec pass and nothing else, and selecting
    ``render-helper`` read a directory the user had never named.
    """
    if ctx is None:
        ctx = GeneratorBuildContext()
    requested = [n.strip() for n in names.split(",") if n.strip()]
    gens: list[Generator] = []
    errors: list[str] = []
    selected: list[str] = []
    for n in requested:
        entry = get_generator(n)
        if entry is None and (":" in n or "." in n):
            gen, err = owned.build_owned(n, owned_root or Path.cwd(), ctx)
            if err is not None:
                errors.append(err)
                continue
            gens.append(gen)
            selected.append(gen.name)
            continue
        if entry is None:
            known = ", ".join(sorted(GENERATOR_REGISTRY))
            errors.append(f"unknown generator {n!r}; known: {known}")
            continue
        gens.append(entry.factory(ctx))
        selected.append(n)
    if not errors and not gens:
        errors.append("no generators selected (empty --generators list)")
    if not errors:
        for warning in unsatisfied_requires(selected):
            print(f"warning: {warning}", file=sys.stderr)
    return gens, errors


def _parse_entities(value: str | None) -> list[str] | None:
    """Parse a comma-separated ``--entities`` value into a name list (``None`` =
    no filter = generate every entity). Blank names are dropped."""
    if not value:
        return None
    names = [n.strip() for n in value.split(",") if n.strip()]
    return names or None


def _refuse_imported_entities(
    entity_names: list[str] | None,
    root: MetaData,
    collection: Collection,
) -> str | None:
    """FR-023 §11.1 item 2 — the error message for a target's ``entities:`` (or
    ``--entities``) naming ONLY objects imported from a dependency and excluded
    from output (imported metadata is load-only by default; only the project's
    own `scope.include` naming the package literally opts it in). Returns
    `None` for every other case, INCLUDING a name matching nothing at all —
    that stays the runner's own "no entities matched" warning, unchanged.
    Mirrors the TS `refuseImportedPositional` (`cli/src/commands/gen.ts`).

    A named entity is a bare NAME, not a fully-qualified one, so two packages
    declaring the same short name are both candidates; the refusal fires only
    when NONE of them would generate.
    """
    if not entity_names:
        return None
    # ADR-0039 sanctioned own: top-level object scan on the loader ROOT
    # (metadata.root is never extended, so own == effective) — mirrors
    # `codegen.runner._objects`.
    all_objects = [
        c for c in root.own_children() if c.type == TYPE_OBJECT and isinstance(c, MetaObject)
    ]
    for name in entity_names:
        matches = [o for o in all_objects if o.name == name]
        if not matches:
            continue  # nothing loaded by this name — the runner's own warning covers it
        all_excluded = all(
            collection.imported(o.resolution_key()) and not collection.in_scope(o.resolution_key())
            for o in matches
        )
        if not all_excluded:
            continue
        fqn = matches[0].resolution_key()
        pkg = package_of_resolution_key(fqn)
        dep_name = imported_from(pkg, collection.dependencies) or pkg
        return (
            f"error: '{name}' ({fqn}) is imported from dependency '{dep_name}' and is not "
            "generated here — add its package to scope.include in .metaobjects/config.json"
        )
    return None


def _run_suite(
    root: MetaData,
    out_dir: str,
    generators: list[Generator] | None = None,
    entity_filter: list[str] | None = None,
    emit_package_init: bool = True,
    gen_state_dir: str | None = None,
    column_naming: str = DEFAULT_COLUMN_NAMING,
    project_root: str | None = None,
    baseline: str = "default",
    refused_out: list[str] | None = None,
    select: Callable[[str], bool] | None = None,
) -> list[str]:
    """Run a generator suite against an ALREADY-LOADED ``root`` into ``out_dir``.

    Split out from :func:`_generate` so a single gen invocation can load the
    metadata once and run multiple passes against it (the default Python suite +
    the ``--template-spec`` pass). See :func:`_generate` for the parameter
    semantics. Returns the written paths.

    ``select`` (FR-023 §11.1 item 2) — normally a resolved `Collection`'s
    `in_scope`: the output filter that excludes an imported dependency's
    objects from codegen unless the project's own `scope.include` names their
    package. `None` (the default) admits everything, byte-identical to a
    project with no dependencies.

    NOTE: ``run_gen``'s output-path collision guard is per-pass — a
    ``--template-spec`` ``outputPattern`` that collides with a default-suite path
    is not flagged across the two passes (it would overwrite, since default files
    carry the ``@generated`` header). Accepted marginal limitation (requires user
    misconfiguration).
    """
    # The hash manifest gives `metaobjects gen` hand-edit detection: without it the
    # write path falls back to the legacy @generated-marker rule, which cannot tell an
    # edited generated file from a pristine one (an edited file keeps its marker).
    # COMMIT `.gen-state/.hashes.json`.
    #
    # Anchored on the caller's project, NEVER on `Path.cwd()`. cwd is whatever directory
    # the process happens to sit in, so a cwd default leaks a `.metaobjects/` into any
    # package that merely runs a test through this function — the exact leak codegen-ts's
    # runner refuses, for the same reason. No project ⇒ no manifest ⇒ documented weaker
    # guarantees, rather than state scattered somewhere arbitrary.
    config = GenConfig(
        out_dir=out_dir,
        emit_package_init=emit_package_init,
        gen_state_dir=gen_state_dir,
        column_naming=column_naming,
        # 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
        # that lives in the project must be keyed by the project.
        project_root=project_root,
        # `--baseline=adopt`: record what is on disk and write nothing. The refusal it
        # exists for is the pre-manifest one, so it reaches every real gen path and no
        # verify path (those pass gen_state_dir=None and record nothing at all).
        baseline=baseline,
    )
    # No default suite — see NO_GENERATORS_SELECTED. A caller that names none gets a
    # usage error and an empty out dir, never a shape this CLI picked.
    if not generators:
        raise NoGeneratorsSelectedError
    suite = generators
    result = run_gen(config, root, generators=suite, entity_filter=entity_filter, select=select)
    for warning in result.warnings:
        print(f"warning: {warning}")
    # A refusal is a FAILED gate, and the return value carries only what was WRITTEN — so
    # without this the one fact a CI step reads (the exit code) could not see it. An
    # out-list rather than a changed return type: five call sites read the written paths,
    # and only the ones that own an exit code care about the refusals.
    if refused_out is not None:
        refused_out.extend(path for path, status in result.files if status == "refused")
    return [path for path, status in result.files if status != "refused"]


def _generate(
    metadata_dir: str,
    out_dir: str,
    generators: list[Generator] | None = None,
    entity_filter: list[str] | None = None,
    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``.

    ``generators`` defaults to the zero-config default suite; pass a registry-
    resolved subset for ``--generators``. ``entity_filter`` (the ``--entities``
    allowlist) restricts which entities are EMITTED while the WHOLE model is still
    loaded, so cross-entity references (``extends`` bases, ``@objectRef`` VOs)
    resolve — emit a subset without splitting the metadata. ``emit_package_init``
    is ``False`` for the format-agnostic ``--template-spec`` generators (whose
    output is text/markdown/csv/json/xml/html, never a Python package) so no
    spurious ``__init__.py`` is scattered through their output tree. Returns
    ``(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:
        return [], errors
    # The project root is the metadata dir's parent — the directory holding
    # `metaobjects/`, which is where `.metaobjects/` belongs beside it.
    # verify --codegen is the ONLY caller of _generate, and it regenerates into a
    # throwaway temp dir purely to diff. It must NOT record a manifest: that would
    # mutate the user's project from a read-only drift check, with keys relative to a
    # 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,
            column_naming=column_naming,
        ),
        [],
    )


def gen_state_dir_for(metadata_dir: str) -> str:
    """Where a project's codegen hash manifest lives.

    Anchored on the project — never on ``Path.cwd()``, which is whatever directory the
    process happens to sit in and would scatter ``.metaobjects/`` into any package that
    merely runs a generator.

    It resolves the project through :func:`project_root_for` rather than repeating
    ``Path(metadata_dir).resolve().parent``. That function's own docstring already claimed
    this one "is anchored here" while the code spelled the rule out a second time, and the
    manifest key and the manifest LOCATION have to agree on where the project is or a
    lookup finds nothing and every file reads as "not ours".
    """
    return str(project_root_for(metadata_dir) / ".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,
) -> Collection:
    """The precedence ladder for where metadata lives, rungs 2-4. First match wins.
    Returns the full FR-023-aware `Collection` at EVERY rung — `dependencies` (and
    `scope`/`migrate.scope`) are read from `root`'s neutral `.metaobjects/config.json`
    regardless of which rung supplied the OWN files (DESIGN §2.3).

    2. This port's native surface — ``metadata`` in ``metaobjects.config.yaml``.
    3. ``sources`` in the port-neutral ``.metaobjects/config.json``.
    4. The built-in default directory.

    Rung 1 — an explicit CLI argument (the positional ``metadata_dir``) — is
    NOT this function's concern: every command handler that accepts one already
    loads it directly via ``_load_root(args.metadata_dir)`` (``MetaDataLoader
    .from_directory``, a single-directory load with no resolve-then-rejoin step
    of its own) BEFORE this function would even be reachable, so this function is
    only ever called with rung 1 already having been tried and found absent. An
    earlier revision accepted an ``explicit`` parameter and duplicated rung 1
    here via `resolve_sources` — reachable from no command handler, so it could
    silently drift from the real rung-1 path (e.g. picking up
    `source_resolver.py`'s CLI-facing `_pending` exclusion while
    `_load_root`'s loader-level walk does not) with nothing to notice. Removed
    rather than wired: replumbing every metadataDir-taking command onto
    `resolve_sources`'s `from_uris`-based load instead of `from_directory` is a
    materially different, higher-risk change than this ladder needs.

    A file that EXISTS at any rung but is malformed raises rather than falling
    through to the next rung. See
    `docs/superpowers/specs/2026-08-19-cross-port-metadata-sources-design.md` §5.
    """
    from metaobjects.config.source_resolver import (
        build_collection,
        resolve_collection_full,
        resolve_sources,
    )

    if config is not None:
        # `config.metadata_dir()` is already resolved to an absolute path
        # (`ProjectConfig._resolve_under`), so the base passed here is
        # likewise irrelevant to resolving OWN files — but `root` is still
        # where `.metaobjects/config.json` (dependencies/scope) is read from.
        own_files = resolve_sources(root, [{"path": config.metadata_dir()}])
        return build_collection(root, own_files)

    # Rungs 3 and 4 both live in `resolve_collection_full`.
    return resolve_collection_full(root)


def _resolve_metadata_location_or_print_error(
    config: ProjectConfig | None, root: Path
) -> Collection | None:
    """``resolve_metadata_location`` for the no-explicit-``metadata_dir`` CLI
    paths (``docs``, and the ``gen``/``verify --codegen`` neutral fallbacks),
    translating a raised ``ParseError`` into this CLI's print-and-return-1
    convention instead of letting it propagate. Returns ``None`` on failure —
    the caller has nothing further to print and should return 1.
    """
    try:
        return resolve_metadata_location(config=config, root=root)
    except ParseError as exc:
        print(f"error: could not resolve metadata location: {exc}", file=sys.stderr)
        return None


#: The default api-surface subdir (the cross-port contract's ``api/python``).
_DOCS_DEFAULT_API_SUBDIR = "api/python"


def _cmd_docs(args: argparse.Namespace) -> int:
    """``docs`` — emit the generated Python SDK api surface (the ``api/python``
    surface of the cross-port SDK-docs contract) under ``--out``.

    Wiring only: every symbol name comes from the ``PythonApiModelBuilder`` (which
    keys off the naming seam + each generator's applies-predicate) and every path
    comes from :mod:`metaobjects.apidocs.paths` — nothing is re-derived here. Output
    paths are collision-checked (duplicate page path → failure) BEFORE anything is
    written, mirroring the C# ``DocsCommand`` / the Java Mojo. Layout is ``package``
    (the cross-port contract). ``--model-base-url`` federates the model back-links
    when set."""
    from metaobjects.apidocs import (
        Layout,
        PythonApiDocsRenderer,
        PythonApiModelBuilder,
        doc_page_output_path,
        model_cross_href,
    )

    providers, providers_ok = _providers_from_args(args)
    if not providers_ok:
        return 1

    if args.metadata_dir is None:
        # Mirrors `gen`'s no-positional routing (#267): rung 2 (`metadata` in
        # `metaobjects.config.yaml`, if one is found), else rungs 3-4 via
        # `resolve_metadata_location` (the neutral `.metaobjects/config.json`
        # `sources` key this feature adds, else the built-in default
        # directory). Before this, `metadata_dir` was a REQUIRED positional
        # here, so this ladder was unreachable from `docs` even though `gen`
        # and `verify --codegen` could both already reach it.
        root_dir = Path.cwd()
        config: ProjectConfig | None = None
        config_path = _find_config(args)
        if config_path is not None:
            try:
                config = load_project_config(config_path)
            except ConfigError as exc:
                print(f"error: {exc}", file=sys.stderr)
                return 1
        collection = _resolve_metadata_location_or_print_error(config, root_dir)
        if collection is None:
            return 1
        docs_libraries: list[str] | None = None
        if config is not None:
            # `config` was already loaded above (to resolve rung 2's `metadata`
            # key) — its OWN `providers`/`libraries` must reach this load too,
            # exactly as `gen`'s config-mode load does (`_cmd_gen_config`), or a
            # project relying on either (e.g. `libraries: ["ai"]` to resolve
            # `extends: metaobjects::ai::LlmCallBase`) fails `docs` with
            # `ERR_UNRESOLVED_SUPER` while `gen` on the same config succeeds.
            config_providers, config_providers_ok = _config_providers(config)
            if not config_providers_ok:
                return 1
            providers = [*providers, *config_providers]
            docs_libraries = config.libraries
        root, errors = _load_root_from_collection(
            collection, providers=providers, libraries=docs_libraries
        )
        project_default = root_dir.name
    else:
        root, errors = _load_root(args.metadata_dir, providers=providers)
        project_default = Path(args.metadata_dir).resolve().name

    if root is None:
        print("error: failed to load metadata:", file=sys.stderr)
        for msg in errors:
            print(f"  {msg}", file=sys.stderr)
        return 1

    api_subdir = args.api_subdir or _DOCS_DEFAULT_API_SUBDIR
    project = args.project or project_default
    model_base_url = getattr(args, "model_base_url", None)

    model = PythonApiModelBuilder().build(root, project)
    renderer = PythonApiDocsRenderer()
    layout = Layout.PACKAGE

    # Collect rel-path → content first so a duplicate page path fails BEFORE any write.
    emitted: dict[str, str] = {}

    def _put(path: str, content: str) -> None:
        if path in emitted:
            raise ValueError(f"docs — duplicate api page output path: {path}")
        emitted[path] = content

    try:
        for unit in model.units:
            page_path = doc_page_output_path(layout, unit.package, unit.node)
            api_page_path_from_docs_root = f"{api_subdir}/{page_path}"
            href = model_cross_href(api_page_path_from_docs_root, page_path, model_base_url)
            _put(page_path, renderer.render_unit_page(unit, href))
        _put("README.md", renderer.render_index(model, layout))
        _put("AGENT-API.md", renderer.render_agent_api(model))
    except ValueError as exc:
        # A duplicate output path (e.g. two units that resolve to the same page) is a
        # clean user-facing failure, not a stack trace.
        print(f"error: {exc}", file=sys.stderr)
        return 1

    api_root = Path(args.out) / api_subdir
    written: list[str] = []
    for rel, content in emitted.items():
        dest = api_root / rel
        dest.parent.mkdir(parents=True, exist_ok=True)
        dest.write_text(content, encoding="utf-8")
        written.append(f"{api_subdir}/{rel}")

    for path in sorted(written):
        print(path)
    print(f"metaobjects docs: wrote {len(written)} file(s) to {args.out}")
    return 0


#: ADR-0034 Amendment 3: generators are reference helpers you own with ``metaobjects
#: eject``. Printed above the ``--list`` entries.
LIST_HEADER = (
    "Reference generators — each is a helper, not a guarantee: `metaobjects eject <name>`\n"
    "copies it into codegen/generators/ and the copy is yours to change. What MetaObjects\n"
    "guarantees (verify, render) is not a generator and is not listed.\n"
    "Select with --generators <name,...>:"
)


def _cmd_list(_args: argparse.Namespace) -> int:
    """Print each registered generator ``<stable-name> — <description>`` and exit 0.

    Does NOT run codegen — pure discoverability (ADR-0021 D3).
    """
    print(LIST_HEADER)
    root = Path.cwd()
    for entry in list_generators():
        requires = f" (requires: {', '.join(entry.requires)})" if entry.requires else ""
        status = owned.owned_status(root, entry)
        mark = f" [owned — {status}]" if status is not None else ""
        print(f"{entry.name} — {entry.description}{requires}{mark}")
    for path, status in owned.runtime_status(root):
        print(f"runtime {path.as_posix()} [owned — {status}]")
    return 0


def _describe_fmt_report(report: "object", cwd: Path) -> str:
    from metaobjects import fmt

    try:
        rel = report.path.relative_to(cwd)
    except ValueError:
        rel = report.path
    if report.status == fmt.STATUS_FORMATTED:
        return f"  reformatted  {rel}"
    if report.status == fmt.STATUS_WOULD_FORMAT:
        return f"  not canonical  {rel}"
    if report.status == fmt.STATUS_UNCHANGED:
        return f"  ok           {rel}"
    if report.status == fmt.STATUS_SKIPPED_YAML:
        return f"  skipped (yaml)     {rel} — {report.detail}"
    if report.status == fmt.STATUS_SKIPPED_OVERLAY:
        return (
            f"  skipped (overlay)  {rel} — this file declares an overlay fmt "
            "cannot resolve standalone"
        )
    if report.status == fmt.STATUS_ERROR:
        return f"  error        {rel} — {report.detail}"
    return f"  {report.status}  {rel}"  # pragma: no cover — exhaustive in practice


def _cmd_fmt(args: argparse.Namespace) -> int:
    """``fmt`` (#304) — rewrite metadata files into canonical form; ``--check``
    lists non-canonical files and exits non-zero without changing anything.

    Mirrors the TS reference surface exactly: no ``metadata_dir`` positional —
    files come from the neutral ``.metaobjects/config.json`` ladder
    (:func:`resolve_metadata_location`, rungs 3-4; this command does not read
    this port's own ``metaobjects.config.yaml`` rung 2, matching the scope the
    C# and Java ports also keep for `fmt`), optionally narrowed by explicit
    file arguments.
    """
    from metaobjects import fmt
    from metaobjects.core_types import core_providers
    from metaobjects.library import library_sources
    from metaobjects.provider import compose_registry

    providers_extra, providers_ok = _providers_from_args(args)
    if not providers_ok:
        return 1
    providers = [*core_providers, *providers_extra]
    registry = compose_registry(providers)

    cwd = Path.cwd()
    collection = _resolve_metadata_location_or_print_error(None, cwd)
    if collection is None:
        return 1

    all_files = list(collection.files)
    own_files = list(collection.own_files)

    if args.files:
        wanted = [Path(f).resolve() for f in args.files]
        owned_set = {p.resolve() for p in own_files}
        missing = [str(p) for p in wanted if p not in owned_set]
        if missing:
            print(
                "error: not among this project's resolved metadata sources: "
                + ", ".join(missing),
                file=sys.stderr,
            )
            print(
                "metaobjects fmt only formats files the metadata-location ladder "
                "already resolves — pass no arguments to format every one of them.",
                file=sys.stderr,
            )
            return 1
        wanted_set = {p for p in wanted}
        targets = [p for p in own_files if p.resolve() in wanted_set]
    else:
        targets = own_files

    lib_sources = library_sources(list(collection.libraries)) if collection.libraries else []

    result = fmt.run(
        all_files=all_files,
        target_files=targets,
        file_ids=dict(collection.file_ids),
        registry=registry,
        lib_sources=lib_sources,
        check=bool(args.check),
        providers=providers,
    )

    if result.fatal is not None:
        print(f"error: {result.fatal}", file=sys.stderr)
        return 1

    if not result.files:
        print("metaobjects fmt — no metadata files to format.")
        return 0

    for report in result.files:
        print(_describe_fmt_report(report, cwd))

    errored = sum(1 for r in result.files if r.status == fmt.STATUS_ERROR)
    needs_format = sum(1 for r in result.files if r.status == fmt.STATUS_WOULD_FORMAT)
    reformatted = sum(1 for r in result.files if r.status == fmt.STATUS_FORMATTED)

    if args.check:
        if needs_format or errored:
            suffix = f", {errored} error(s)" if errored else ""
            print(
                f"metaobjects fmt --check — {needs_format} file(s) not canonical{suffix}. "
                "Run `metaobjects fmt` to fix.",
                file=sys.stderr,
            )
            return 1
        print("metaobjects fmt --check — every file is already canonical.")
        return 0

    if errored:
        print(
            f"metaobjects fmt — {errored} file(s) could not be formatted safely (left unchanged).",
            file=sys.stderr,
        )
        return 1

    print(f"metaobjects fmt — {reformatted} file(s) reformatted.")
    return 0


def _cmd_eject(args: argparse.Namespace) -> int:
    """Copy reference generators into ``codegen/generators/`` to own (ADR-0034 Am. 3)."""
    root = Path(args.root) if args.root else Path.cwd()
    result = owned.eject(args.names, root, force=args.force)
    for line in result.out:
        print(line)
    for line in result.err:
        print(f"error: {line}", file=sys.stderr)
    return result.code


def _warn_if_agent_context_stale() -> None:
    """Print ONE advisory line to stderr if the scaffolded agent context is stale.

    Reads ``<cwd>/.metaobjects/.agent-context.json`` (if present), compares its
    stamped ``generatedBy`` to the installed version, and nudges a re-scaffold on
    any drift. Advisory only: never raises, never changes the exit code, never
    writes — a missing or corrupt manifest is silently ignored.
    """
    try:
        manifest_path = Path.cwd() / AGENT_CONTEXT_MANIFEST_PATH
        if not manifest_path.is_file():
            return
        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
        if not isinstance(manifest, dict):
            return
        msg = agent_context_staleness(manifest, installed_metaobjects_version())
        if msg is not None:
            print(msg, file=sys.stderr)
    except Exception:  # noqa: BLE001 — advisory; any failure is silently ignored
        return


def _cmd_gen(args: argparse.Namespace) -> int:
    # `--list` is a pure discoverability path: print the registry and exit, no codegen.
    if getattr(args, "list", False):
        return _cmd_list(args)

    _warn_if_agent_context_stale()

    # #267: config mode ⇔ no positional <metadata_dir>. The explicit
    # <metadata_dir> + --out flag path below is untouched (byte-identical).
    if args.metadata_dir is None:
        return _cmd_gen_config(args)
    if args.out is None:
        print(
            "error: gen requires <metadata_dir> and --out "
            "(or a metaobjects.config.yaml / --list).",
            file=sys.stderr,
        )
        return 2

    generators: list[Generator] | None = None
    if args.generators:
        generators, gen_errors = _resolve_generators(
            args.generators, GeneratorBuildContext(_template_root_for(args)))
        if gen_errors:
            print("error: invalid --generators selection:", file=sys.stderr)
            for msg in gen_errors:
                print(f"  {msg}", file=sys.stderr)
            return 1

    # SP-1: declarative Mustache generators from a JSON template-spec. Their output
    # is format-agnostic (text/markdown/csv/json/xml/html), so they run as a SECOND,
    # 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, spec_err = template_spec_generators(
        args.metadata_dir, getattr(args, "template_spec", None),
        _template_root_for(args),
    )
    if spec_err is not None:
        print(spec_err, file=sys.stderr)
        return 1

    # Codegen is opt-in: refuse at the door when nothing is selected, rather than letting
    # the run reach the generator loop and fail with an empty out dir half-created. A
    # template spec IS a selection (flag or the conventional template-spec.json), so a
    # project that generates only from one is not refused; verify already agreed.
    if not generators and not spec_gens:
        print(f"error: {NO_GENERATORS_SELECTED}", file=sys.stderr)
        return 2

    entities = _parse_entities(getattr(args, "entities", None))
    providers, providers_ok = _providers_from_args(args)
    if not providers_ok:
        return 1
    # Load the metadata ONCE; both the default suite and the (optional)
    # --template-spec pass run against this single loaded root.
    unknown_attrs: list[str] = []
    root, load_errors = _load_root(
        args.metadata_dir, providers=providers, 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)
        return 1
    _print_unknown_attr_warnings(unknown_attrs)
    gen_state = gen_state_dir_for(args.metadata_dir)
    # Same anchor the manifest itself uses. Both passes below key against it, so a
    # `--template-spec` artifact and a default-suite artifact land in one key space.
    gen_project_root = str(project_root_for(args.metadata_dir))
    column_naming = getattr(args, "column_naming", None) or DEFAULT_COLUMN_NAMING
    baseline = getattr(args, "baseline", None) or "default"
    refused: list[str] = []
    try:
        written = _run_suite(
            root, args.out, generators, entities,
            gen_state_dir=gen_state, column_naming=column_naming,
            project_root=gen_project_root, baseline=baseline, refused_out=refused,
        ) if generators else []
    except ValueError as exc:
        # A generator refused the model — a run_gen output collision, or
        # `render-helper`'s build-time drift gate. The targets path below has caught
        # this since #267; this path did not, and the gap only became reachable when
        # `--templates` started reaching `render-helper` at all: before that the gate
        # ran against a hardcoded "templates" and a CLI user could not aim it.
        print(f"error: codegen failed: {exc}", file=sys.stderr)
        if "render-helper drift" in str(exc):
            root_shown = _template_root_for(args)
            print(
                f"  template refs resolved under {root_shown!r} — pass "
                f"--templates <dir> to point at the directory holding them",
                file=sys.stderr,
            )
        return 1
    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
        # escapes the parse-time guard above). Report it as a clean error.
        from metaobjects.render.renderer import RenderError

        try:
            spec_written = _run_suite(
                root, args.out, spec_gens, entities, emit_package_init=False,
                gen_state_dir=gen_state, column_naming=column_naming,
                project_root=gen_project_root, baseline=baseline, refused_out=refused,
            )
        except RenderError as exc:
            print(
                f"error: --template-spec render failed (check the template refs and "
                f"--templates dir {_template_root_for(args)!r}): {exc}",
                file=sys.stderr,
            )
            return 1
        written = list(written) + spec_written
    for path in written:
        print(path)
    print(f"metaobjects gen: wrote {len(written)} file(s) to {args.out}")
    if refused:
        # A refusal is a failed gate, matching TypeScript's `meta gen` (exit 1). Python and
        # C# used to warn and exit 0, so an adopter wiring this into CI as a drift gate was
        # green while codegen refused to write — a gate that did not gate. The warnings
        # above carry the detail; this line carries the verdict.
        print(
            f"metaobjects gen: FAILED — {len(refused)} file(s) refused (see the warnings "
            f"above; `--baseline=adopt` records what you have and writes nothing)",
            file=sys.stderr,
        )
        return 1
    return 0


def _run_gen_targets(
    config: ProjectConfig,
    targets: list[TargetConfig],
    root: MetaData,
    *,
    gen_state_dir: str | None = None,
    project_root: str | None = None,
    baseline: str = "default",
    refused_out: list[str] | None = None,
    select: Callable[[str], bool] | None = None,
    build_ctx: GeneratorBuildContext | None = None,
) -> tuple[list[str], list[str]]:
    """Run each target's suite into its ``outDir``. Returns (all_written, errors).

    This is the path the manifest keying matters most on: every target writes into its
    OWN ``outDir`` while all of them share ONE ``gen_state_dir``, so out-dir-relative
    keys meant target B's hash could claim ownership of target A's identically-named
    file. ``project_root`` is the common anchor that makes the keys distinct.

    Cross-target duplicate-output-path guard (#267): ``run_gen``'s collision guard
    is per-pass, so two targets writing the same full path would silently clobber
    (generated files carry the @generated header). We accumulate every written full
    path across targets and record an error when two targets emit the same one.
    (Detection is post-write — the colliding file may already be on disk — but the
    command still fails, so a misconfigured gate is caught in CI.)

    ``select`` (FR-023 §11.1 item 2) — see :func:`_run_suite`; the SAME predicate
    applies to every target, since a `Collection`'s scope is project-wide.
    """
    all_written: list[str] = []
    seen: dict[str, str] = {}  # full path -> target name
    errors: list[str] = []
    for t in targets:
        gens: list[Generator] | None = None
        if t.generators is not None:
            gens, gen_errors = _resolve_generators(
                ",".join(t.generators), build_ctx or GeneratorBuildContext(),
                owned_root=config.config_dir)
            if gen_errors:
                errors.extend(f"target '{t.name}': {m}" for m in gen_errors)
                continue
        out_dir = config.out_dir_for(t)
        try:
            written = _run_suite(
                root, out_dir, gens, t.entities, gen_state_dir=gen_state_dir,
                project_root=project_root, baseline=baseline, refused_out=refused_out,
                select=select,
            )
        except ValueError as exc:  # intra-target run_gen collision → clean error
            errors.append(f"target '{t.name}': {exc}")
            continue
        for full in written:
            if Path(full).name == "__init__.py":
                continue  # auto-emitted package marker — byte-identical across targets sharing an outDir; not a real collision
            prior = seen.get(full)
            if prior is not None and prior != t.name:
                errors.append(
                    f"duplicate output path across targets: {full!r} written by "
                    f"both '{prior}' and '{t.name}'."
                )
            else:
                seen[full] = t.name
        all_written.extend(written)
    return all_written, errors


def _cmd_gen_neutral_fallback(args: argparse.Namespace) -> int:
    """``gen`` with no positional ``metadata_dir`` AND no ``metaobjects.config.yaml``.

    Descends the source-resolution ladder's remaining rungs — ``sources`` in
    ``.metaobjects/config.json``, else the built-in default directory — via
    :func:`resolve_metadata_location`. There is no declarative target registry
    at this rung (that is what a ``metaobjects.config.yaml`` provides), so
    ``--out`` is required exactly as it is in explicit-``<metadata_dir>`` flag
    mode; this function otherwise mirrors ``_cmd_gen``'s flag-mode body, minus
    the ``--template-spec`` pass (out of scope for this rung).
    """
    if args.out is None:
        print(
            "error: gen requires <metadata_dir> and --out "
            "(or a metaobjects.config.yaml / --list).",
            file=sys.stderr,
        )
        return 2

    root_dir = Path.cwd()
    collection = _resolve_metadata_location_or_print_error(None, root_dir)
    if collection is None:
        return 1

    generators: list[Generator] | None = None
    if args.generators:
        generators, gen_errors = _resolve_generators(
            args.generators, GeneratorBuildContext(_template_root_for(args)))
        if gen_errors:
            print("error: invalid --generators selection:", file=sys.stderr)
            for msg in gen_errors:
                print(f"  {msg}", file=sys.stderr)
            return 1

    entities = _parse_entities(getattr(args, "entities", None))
    providers, providers_ok = _providers_from_args(args)
    if not providers_ok:
        return 1

    root, load_errors = _load_root_from_collection(collection, providers=providers)
    if root is None:
        print("error: failed to load metadata:", file=sys.stderr)
        for msg in load_errors:
            print(f"  {msg}", file=sys.stderr)
        return 1

    imported_refusal = _refuse_imported_entities(entities, root, collection)
    if imported_refusal is not None:
        print(imported_refusal, file=sys.stderr)
        return 2

    gen_state = str(root_dir.resolve() / ".metaobjects" / ".gen-state")
    column_naming = getattr(args, "column_naming", None) or DEFAULT_COLUMN_NAMING
    refused: list[str] = []
    written = _run_suite(
        root, args.out, generators, entities,
        gen_state_dir=gen_state, column_naming=column_naming,
        select=collection.in_scope,
        project_root=str(root_dir.resolve()),
        baseline=getattr(args, "baseline", None) or "default",
        refused_out=refused,
    )
    for path in written:
        print(path)
    print(f"metaobjects gen: wrote {len(written)} file(s) to {args.out}")
    if refused:
        # A refusal is a failed gate, matching TypeScript's `meta gen` (exit 1). Python and
        # C# used to warn and exit 0, so an adopter wiring this into CI as a drift gate was
        # green while codegen refused to write — a gate that did not gate. The warnings
        # above carry the detail; this line carries the verdict.
        print(
            f"metaobjects gen: FAILED — {len(refused)} file(s) refused (see the warnings "
            f"above; `--baseline=adopt` records what you have and writes nothing)",
            file=sys.stderr,
        )
        return 1
    return 0


def _cmd_gen_config(args: argparse.Namespace) -> int:
    """``gen`` with no positional ``metadata_dir`` → declarative-config mode (#267).

    Load ``metaobjects.config.yaml``, load metadata ONCE, and run every target
    (or ``--target``) into its own ``outDir`` with a cross-target duplicate-path
    guard. Providers resolve relative to the config file (no ``PYTHONPATH=``).
    No ``metaobjects.config.yaml`` at all → :func:`_cmd_gen_neutral_fallback`
    (the ladder's remaining rungs), not an error.
    """
    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:
        print(f"error: {exc}", file=sys.stderr)
        return 1

    targets, target_err = _select_targets(config, getattr(args, "target", None))
    if target_err:
        print(f"error: {target_err}", file=sys.stderr)
        return 1

    providers, providers_ok = _config_providers(config)
    if not providers_ok:
        return 1

    # FR-023: rung 2 (this native `metaobjects.config.yaml` surface) still reads
    # `dependencies`/`scope`/`migrate.scope` from the project's neutral
    # `.metaobjects/config.json` (DESIGN §2.3 — dependencies apply at EVERY rung).
    collection = _resolve_metadata_location_or_print_error(
        config, project_root_for(config.metadata_dir())
    )
    if collection is None:
        return 1

    unknown_attrs: list[str] = []
    root, load_errors = _load_root_from_collection(
        collection, 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)
        return 1
    _print_unknown_attr_warnings(unknown_attrs)

    for t in targets:
        imported_refusal = _refuse_imported_entities(t.entities, root, collection)
        if imported_refusal is not None:
            print(imported_refusal, file=sys.stderr)
            return 2

    refused: list[str] = []
    written, errors = _run_gen_targets(
        config, targets, root,
        gen_state_dir=gen_state_dir_for(config.metadata_dir()),
        project_root=str(project_root_for(config.metadata_dir())),
        baseline=getattr(args, "baseline", None) or "default",
        refused_out=refused,
        select=collection.in_scope,
        build_ctx=GeneratorBuildContext(_template_root_for(args)),
    )
    if errors:
        for msg in errors:
            print(f"error: {msg}", file=sys.stderr)
        return 1
    for path in written:
        print(path)
    print(
        f"metaobjects gen: wrote {len(written)} file(s) across {len(targets)} target(s)."
    )
    if refused:
        # A refusal is a failed gate, matching TypeScript's `meta gen` (exit 1). Python and
        # C# used to warn and exit 0, so an adopter wiring this into CI as a drift gate was
        # green while codegen refused to write — a gate that did not gate. The warnings
        # above carry the detail; this line carries the verdict.
        print(
            f"metaobjects gen: FAILED — {len(refused)} file(s) refused (see the warnings "
            f"above; `--baseline=adopt` records what you have and writes nothing)",
            file=sys.stderr,
        )
        return 1
    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 generated-artifact file under ``root`` to its content, keyed by rel path.

    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 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 _out_prefix(out_dir: str, project_root: Path) -> str:
    """The out dir, relative to the project — the translation between this diff's
    out-dir-relative keys and the manifest's project-relative ones.

    BOTH SIDES RESOLVED, and that is the whole content of this function. `project_root`
    arrives resolved; relpath from a resolved anchor to an unresolved path is not the
    path between the two directories, and under a directory symlink it walks OUT of the
    project. Every lookup then misses, `is_ours` is false for every file, and the gate
    prints a clean verdict over stale output — silent in the direction that matters.
    It is written once here rather than at each of the three call sites, because three
    spellings of one translation is how they came to disagree in the first place.
    """
    return os.path.relpath(Path(out_dir).resolve(), project_root)


def _is_ours_for(gen_state_dir: str | None, out_prefix: str = ""):
    """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, so it answers the ownership question
    exactly — but it is keyed relative to the PROJECT while this diff is keyed relative
    to ``out_dir``. ``out_prefix`` (the out dir, relative to the project) is what turns
    one into the other. Getting this wrong is silent in the direction that matters: a
    lookup that finds nothing makes ``is_ours`` false for every file, and the gate simply
    stops reporting stale output while still printing a clean verdict.

    The out-dir-relative name is tried as a fallback, because that is how a manifest
    written before the re-keying spells it — the same fallback ``decide_and_write``
    makes, so the write path and the gate cannot disagree about which entry is a record
    of this file.

    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

    def is_ours(rel: str) -> bool:
        key = os.path.join(out_prefix, rel) if out_prefix else rel
        return read_generated_hash(gen_state_dir, key, legacy_rel_path=rel) is not None

    return is_ours


def _diff_report(
    expected: dict[str, str],
    committed: dict[str, str],
    gen_state_dir: str | None = None,
    out_prefix: str = "",
) -> 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.
    ``out_prefix`` is the committed out dir relative to the project, which is what
    translates this diff's out-dir-relative keys into the manifest's project-relative
    ones; omit it only when the two coincide.
    """
    is_ours = _is_ours_for(gen_state_dir, out_prefix)
    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
    # 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)).")
        return 0

    print("error: generated code is out of sync with metadata.", file=sys.stderr)
    for k in changed:
        print(f"  drifted: {k}", file=sys.stderr)
    for k in missing:
        print(f"  missing: {k}", file=sys.stderr)
    for k in extra:
        print(f"  extra:   {k}", file=sys.stderr)
    print(
        "regenerate (metaobjects gen) and commit the result.",
        file=sys.stderr,
    )
    return 1



def _no_generators_selected(out_dir: str) -> int:
    """``verify --codegen`` with nothing selected: pass only if nothing would go unchecked.

    There is no default suite (1.0.4), so with no ``--generators`` nothing is regenerated.
    If ``out_dir`` already holds generated files, reporting success would be a false green
    — a gate written before 1.0.4, relying on the default, silently stopped checking
    anything. That is an error; an empty or absent ``out_dir`` is not.
    """
    committed = [p for p in Path(out_dir).rglob("*.py") if p.name != "__init__.py"] if Path(out_dir).is_dir() else []
    if committed:
        print(
            f"error: verify --codegen: no generators selected, but {out_dir} holds "
            f"{len(committed)} generated file(s) that would go unchecked. There is no "
            "default suite: pass --generators <a,b,c> naming the same suite `gen` ran "
            "(metaobjects gen --list is the catalog).",
            file=sys.stderr,
        )
        return 1
    print(
        "verify --codegen: no generators selected and no generated output to check. "
        "Pass --generators <a,b,c> naming the same suite `gen` ran "
        "(metaobjects gen --list is the catalog).",
    )
    return 0

def _verify_codegen(args: argparse.Namespace) -> int:
    """``verify --codegen`` — regenerate to a temp dir + diff vs committed ``--out``.

    Python's historical ``verify`` behavior, unchanged. Reuses the exact ``gen``
    code path (gen-to-temp + diff), so drift can never be a generator-wiring
    divergence between the two commands.
    """
    # #267: config mode ⇔ no positional <metadata_dir>. The legacy
    # <metadata_dir> + --out diff below is untouched.
    if args.metadata_dir is None:
        return _verify_codegen_config(args)
    if args.out is None:
        print(
            "error: verify --codegen requires --out (the committed output dir).",
            file=sys.stderr,
        )
        return 2

    # Reuse the exact gen code path — regenerate into a throwaway temp dir. The
    # --entities filter must match the `gen` that produced --out, or the diff
    # reports the un-emitted entities as spurious drift.
    # 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

    # `verify --codegen` re-runs the SELECTION and compares. Codegen is opt-in, so the
    # selection has to be named — with none, there is no generated output to check, and
    # saying so beats silently regenerating a suite this project never asked for and
    # convicting every file of being missing.
    selection: list[Generator] | None = None
    if getattr(args, "generators", None):
        selection, gen_errors = _resolve_generators(
            args.generators, GeneratorBuildContext(_template_root_for(args)))
        if gen_errors:
            print("error: invalid --generators selection:", file=sys.stderr)
            for msg in gen_errors:
                print(f"  {msg}", file=sys.stderr)
            return 1
    elif not spec_gens:
        return _no_generators_selected(args.out)

    with tempfile.TemporaryDirectory() as tmp:
        entities = _parse_entities(getattr(args, "entities", None))
        written: list[str] = []
        errors: list[str] = []
        if selection is not None:
            written, errors = _generate(
                args.metadata_dir, tmp, selection, entities, strict=strict,
                providers=providers, column_naming=column_naming,
            )
        if errors:
            print("error: failed to load metadata:", file=sys.stderr)
            for msg in errors:
                print(f"  {msg}", file=sys.stderr)
            if strict and any("ERR_UNKNOWN_ATTR" in m for m in errors):
                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))

    # The manifest is keyed relative to the project; this diff is keyed relative to
    # `--out`. Hand over the prefix that translates one into the other, or the
    # jurisdiction lookup finds nothing and the `extra` verdict silently empties.
    project_root = project_root_for(args.metadata_dir)
    return _diff_report(
        expected, committed, gen_state_dir_for(args.metadata_dir),
        _out_prefix(args.out, project_root),
    )


def _verify_codegen_neutral_fallback(args: argparse.Namespace) -> int:
    """``verify --codegen`` with no positional ``metadata_dir`` AND no
    ``metaobjects.config.yaml``.

    Descends the source-resolution ladder's remaining rungs via
    :func:`resolve_metadata_location`, exactly like
    :func:`_cmd_gen_neutral_fallback`. There is no declarative target registry
    at this rung, so ``--out`` (the committed dir to diff against) is required
    exactly as it is in explicit-``<metadata_dir>`` flag mode.
    """
    if args.out is None:
        print(
            "error: verify --codegen requires --out (the committed output dir).",
            file=sys.stderr,
        )
        return 2

    root_dir = Path.cwd()
    collection = _resolve_metadata_location_or_print_error(None, root_dir)
    if collection is None:
        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

    # Same rule as _verify_codegen: the selection must be named, because there is no
    # default suite to regenerate and diff against.
    if not getattr(args, "generators", None):
        return _no_generators_selected(args.out)
    selection, gen_errors = _resolve_generators(
        args.generators, GeneratorBuildContext(_template_root_for(args)))
    if gen_errors:
        print("error: invalid --generators selection:", file=sys.stderr)
        for msg in gen_errors:
            print(f"  {msg}", file=sys.stderr)
        return 1

    with tempfile.TemporaryDirectory() as tmp:
        entities = _parse_entities(getattr(args, "entities", None))
        root, load_errors = _load_root_from_collection(collection, strict=strict, providers=providers)
        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(), file=sys.stderr)
            return 1

        imported_refusal = _refuse_imported_entities(entities, root, collection)
        if imported_refusal is not None:
            print(imported_refusal, file=sys.stderr)
            return 2

        _run_suite(
            root, tmp, selection, entities, gen_state_dir=None, column_naming=column_naming,
            select=collection.in_scope,
        )
        expected = _relative_set(Path(tmp))
        committed = _relative_set(Path(args.out))

    # 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"),
        _out_prefix(args.out, root_dir.resolve()),
    )


def _temp_slot_for(temp_root: Path, real_outdir: str, config_dir: Path) -> str:
    """The temp mirror of a committed ``outDir``.

    Keyed by the real outDir's path relative to ``config_dir`` when it lives under
    it, else a sanitized flat name — mirroring the TS ``computeCodegenDrift``
    ``tempFor``. Two targets sharing a real outDir map to the SAME slot so their
    co-resident regen accumulates into one tree: the diff is then union-of-
    co-resident-regen vs the shared committed dir, so the other target's files are
    never false ``extra`` drift.
    """
    try:
        rel = Path(real_outdir).relative_to(config_dir)
    except ValueError:
        rel = None
    if rel is None:
        safe = re.sub(r"[^A-Za-z0-9]+", "_", real_outdir)
        return str(temp_root / safe)
    return str(temp_root / rel)


def _verify_codegen_config(args: argparse.Namespace) -> int:
    """``verify --codegen`` with no positional ``metadata_dir`` → config mode (#267).

    Symmetric with ``gen`` config mode: ONE whole-selection regen into a temp tree
    (reusing :func:`_run_gen_targets` — the exact gen pipeline, so verify rejects
    exactly what gen rejects, including the cross-target duplicate-output-path
    guard), then a diff per UNIQUE real outDir. Targets that share an outDir are
    verified TOGETHER — the diff is the union of their co-resident regen vs the
    shared committed dir, so a shared outDir is never a false-positive ``extra``
    drift (mirrors the TS ``computeCodegenDrift`` unit = unique outDir).
    ``--target`` widens to the outDir-sharing closure (an outDir is verified as a
    unit). Strict-by-default (ADR-0023) unless ``--lax``.
    No ``metaobjects.config.yaml`` at all → :func:`_verify_codegen_neutral_fallback`
    (the ladder's remaining rungs), not an error.
    """
    config_path = _find_config(args)
    if config_path is None:
        return _verify_codegen_neutral_fallback(args)
    try:
        config = load_project_config(config_path)
    except ConfigError as exc:
        print(f"error: {exc}", file=sys.stderr)
        return 1

    selected, target_err = _select_targets(config, getattr(args, "target", None))
    if target_err:
        print(f"error: {target_err}", file=sys.stderr)
        return 1

    # Widen to the outDir-sharing closure: a shared outDir is verified as a unit,
    # so --target a (whose outDir b also writes) pulls b in.
    selected_outdirs = {config.out_dir_for(t) for t in selected}
    closure = [t for t in config.targets if config.out_dir_for(t) in selected_outdirs]
    added = [t.name for t in closure if t not in selected]
    if added:
        target_arg = getattr(args, "target", None)
        print(
            f"note: --target {target_arg!r} shares an outDir with "
            f"{', '.join(added)}; verifying the shared outDir as a unit.",
            file=sys.stderr,
        )

    strict = not getattr(args, "lax", False)
    providers, providers_ok = _config_providers(config)
    if not providers_ok:
        return 1

    # FR-023: see the matching comment in `_cmd_gen_config` — dependencies apply
    # at this rung too.
    collection = _resolve_metadata_location_or_print_error(
        config, project_root_for(config.metadata_dir())
    )
    if collection is None:
        return 1

    root, load_errors = _load_root_from_collection(
        collection, strict=strict, providers=providers, libraries=config.libraries
    )
    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(), file=sys.stderr)
        return 1

    for t in closure:
        imported_refusal = _refuse_imported_entities(t.entities, root, collection)
        if imported_refusal is not None:
            print(imported_refusal, file=sys.stderr)
            return 2

    with tempfile.TemporaryDirectory() as temp_root:
        # Map each unique real outDir to ONE temp slot (shared real dir => shared slot).
        temp_for: dict[str, str] = {}
        for t in closure:
            real = config.out_dir_for(t)
            if real not in temp_for:
                temp_for[real] = _temp_slot_for(Path(temp_root), real, config.config_dir)
        remapped = [
            dataclasses.replace(t, out_dir=temp_for[config.out_dir_for(t)]) for t in closure
        ]

        # The exact gen pipeline into the temp tree — verify now rejects exactly
        # what gen rejects (incl. the cross-target duplicate-output-path guard).
        # gen_state_dir stays None: this regenerates into a temp tree purely to
        # diff, so recording a manifest would mutate the user's project from a
        # read-only drift check, keyed to a directory deleted seconds later.
        # build_ctx from the SAME resolver `gen` uses — a verify that resolved the
        # template root differently would regenerate render-helper against another
        # directory and convict the committed output of being stale.
        _written, errors = _run_gen_targets(
            config, remapped, root, select=collection.in_scope,
            build_ctx=GeneratorBuildContext(_template_root_for(args)))
        if errors:
            for msg in errors:
                print(f"error: {msg}", file=sys.stderr)
            return 1

        exit_code = 0
        for real_outdir in sorted(temp_for):
            tmp_slot = temp_for[real_outdir]
            expected = _relative_set(Path(tmp_slot))
            committed = _relative_set(Path(real_outdir))

            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)
            # 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.
            #
            # PER-TARGET prefix, because that is the whole point on this rung: two
            # targets with different outDirs share one manifest, and the key that tells
            # their identically-named files apart is the one anchored on the project.
            is_ours = _is_ours_for(
                gen_state_dir_for(config.metadata_dir()),
                _out_prefix(real_outdir, project_root_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
            )
            if not changed and not missing and not extra:
                print(
                    f"metaobjects verify [{names}]: in sync ({len(expected)} file(s))."
                )
                continue
            exit_code = max(exit_code, 1)
            print(
                f"error: [{names}] generated code is out of sync with metadata.",
                file=sys.stderr,
            )
            for k in changed:
                print(f"  drifted: {k}", file=sys.stderr)
            for k in missing:
                print(f"  missing: {k}", file=sys.stderr)
            for k in extra:
                print(f"  extra:   {k}", file=sys.stderr)
            print("regenerate (metaobjects gen) and commit the result.", file=sys.stderr)
        return exit_code


#: The text-ref attrs a ``template.*`` node may carry. Each is resolved through
#: the filesystem provider and run through the render ``verify()`` gate. A prompt
#: / document uses ``@textRef``; an email uses subject / html / (optional) text
#: part-refs. We check whichever are declared (matching the render-helper gate).
_TEMPLATE_TEXT_REF_ATTRS = (
    tc.TEMPLATE_ATTR_TEXT_REF,
    tc.TEMPLATE_ATTR_SUBJECT_REF,
    tc.TEMPLATE_ATTR_HTML_BODY_REF,
    tc.TEMPLATE_ATTR_TEXT_BODY_REF,
)


def _attr_str_list(raw: object) -> list[str] | None:
    """Coerce a string-array attr (a list, or a single string) to ``list[str]``; ``None``
    when absent — the shape :func:`render.verify` expects for required_slots/required_tags."""
    if isinstance(raw, str):
        return [raw]
    if isinstance(raw, (list, tuple)):
        return [str(x) for x in raw]
    return None


def _verify_templates(args: argparse.Namespace) -> int:
    """``verify --templates`` — the template/prompt ``{{field}}`` ↔ payload drift gate.

    For each ``template.*`` node: resolve its ``@payloadRef`` to an
    ``object.value`` + derive its field tree (reusing the render-helper
    generator's derivation — nested ``@objectRef`` resolved by short-name,
    cycle-guarded), resolve each declared text-ref through a
    :class:`FilesystemProvider` rooted at ``--templates-root``, and run the render
    ``verify()`` engine ({{field}} ↔ payload-field drift). Any drift — an
    unresolvable ref or a non-warning ``verify`` error — is reported and fails
    (exit 1). Clean → 0. Reuses the render engine + field-tree walk; nothing is
    reimplemented here.
    """
    if args.metadata_dir is None:
        print(
            "error: verify --templates requires <metadata_dir> (it is not "
            "config-driven; the config's targets registry drives --codegen only).",
            file=sys.stderr,
        )
        return 2

    template_root = getattr(args, "templates_root", None)
    if not template_root:
        print(
            "error: verify --templates requires --prompts (the on-disk "
            "template/prompt dir).",
            file=sys.stderr,
        )
        return 2

    # ADR-0023 strict-by-default (#96) — same as --codegen: an undeclared @attr
    # fails verify unless --lax is passed.
    strict = not getattr(args, "lax", False)
    providers, providers_ok = _providers_from_args(args)
    if not providers_ok:
        return 1
    root, errors = _load_root(args.metadata_dir, strict=strict, providers=providers)
    if root is None:
        print("error: failed to load metadata:", file=sys.stderr)
        for msg in errors:
            print(f"  {msg}", file=sys.stderr)
        if strict and any("ERR_UNKNOWN_ATTR" in m for m in errors):
            print(_strict_load_hint(), file=sys.stderr)
        return 1

    provider = FilesystemProvider(template_root)
    # Toolcall templates have no renderable text body (the body IS the schema) —
    # skip them; there is no {{field}} drift to check.
    templates = [
        # ADR-0039 sanctioned own: top-level scan on the loader ROOT (never extended, own == effective)
        c
        for c in root.own_children()
        if c.type == TYPE_TEMPLATE and c.sub_type != tc.TEMPLATE_SUBTYPE_TOOLCALL
    ]

    if not templates:
        print("metaobjects verify --templates: no template.* nodes found.")
        return 0

    error_count = 0
    checked = 0
    for tmpl in sorted(templates, key=lambda c: c.name):
        payload_ref = tmpl.get_meta_attr(tc.TEMPLATE_ATTR_PAYLOAD_REF)  # ADR-0039: template attr resolves via extends (not origin; templates CAN extend)
        if not isinstance(payload_ref, str) or not payload_ref:
            print(f"error: [{tmpl.name}] missing @payloadRef.", file=sys.stderr)
            error_count += 1
            continue
        # ADR-0042 (#228): the referrer is THIS template — a bare @payloadRef
        # resolves in ITS OWN package first.
        vo = resolve_payload_vo(root, payload_ref, pkg_of(tmpl))
        if vo is None:
            print(
                f"error: [{tmpl.name}] @payloadRef '{payload_ref}' did not "
                "resolve to an object.value.",
                file=sys.stderr,
            )
            error_count += 1
            continue

        fields: list[PayloadField] = _derive_payload_field_tree(root, vo, frozenset())

        refs = [
            val
            for a in _TEMPLATE_TEXT_REF_ATTRS
            # ADR-0039: template attr resolves via extends (not origin; templates CAN extend)
            if isinstance(val := tmpl.get_meta_attr(a), str) and val
        ]
        if not refs:
            print(
                f"error: [{tmpl.name}] declares no resolvable text-ref "
                "(@textRef / @subjectRef / @htmlBodyRef / @textBodyRef).",
                file=sys.stderr,
            )
            error_count += 1
            continue

        # #193/#230: @requiredSlots/@requiredTags are a template.prompt concept — enforced ONLY on
        # the prompt path (the email/document output gate does not apply them per-part; the #193
        # cross-port consensus). A prompt whose body omits a required output tag →
        # ERR_OUTPUT_TAG_MISSING (drift, fails); an unused required slot → ERR_REQUIRED_SLOT_UNUSED
        # (warning). This brings Python to parity with TS/Java/C# (previously it enforced neither).
        is_prompt = tmpl.sub_type == tc.TEMPLATE_SUBTYPE_PROMPT
        # ADR-0039: resolving read — an inherited @requiredSlots/@requiredTags is honored.
        req_slots = _attr_str_list(tmpl.get_meta_attr(tc.TEMPLATE_ATTR_REQUIRED_SLOTS)) if is_prompt else None
        req_tags = _attr_str_list(tmpl.get_meta_attr(tc.TEMPLATE_ATTR_REQUIRED_TAGS)) if is_prompt else None

        for ref in refs:
            text = provider.resolve(ref)
            if text is None:
                print(
                    f"error: [{tmpl.name}] ref '{ref}' did not resolve under "
                    f"{template_root} (missing template).",
                    file=sys.stderr,
                )
                error_count += 1
                continue
            checked += 1
            for e in render_verify(
                text, fields, provider=provider,
                required_slots=req_slots, required_tags=req_tags,
            ):
                if e.code == ERR_REQUIRED_SLOT_UNUSED:
                    continue  # an unused required slot is a warning, not drift
                print(
                    f"error: [{tmpl.name}] ref '{ref}' — {e.code}: {e.path}",
                    file=sys.stderr,
                )
                error_count += 1

    if error_count > 0:
        print(
            f"metaobjects verify --templates: {error_count} drift error(s).",
            file=sys.stderr,
        )
        return 1
    print(f"metaobjects verify --templates: {checked} template ref(s) clean.")
    return 0


def _verify_db(_args: argparse.Namespace) -> int:
    """``verify --db`` — REJECTED in the Python port (ADR-0021 D2).

    Schema drift is owned by the migrate engine (ADR-0015), not this codegen CLI.
    """
    print(
        "error: verify --db is not supported in the Python port; schema verify "
        "is the migrate engine (the Node `meta` CLI, ADR-0015).",
        file=sys.stderr,
    )
    return 2


#: Opt-out for the advisory field lint, beside ``--no-field-lint`` (Node `meta` parity).
FIELD_LINT_ENV = "META_NO_FIELD_LINT"


def _field_lint_findings(args: argparse.Namespace) -> "list[FieldLintFinding] | None":
    """Load the metadata ``verify`` was pointed at and run the field lint over it.

    Returns ``None`` when there is nothing to lint: the metadata could not be located
    or did not load. Every such failure is already reported by the gate that ran, with
    its own message and exit code, so this stays silent.

    Loads LENIENT, deliberately: the lint must report the same findings under
    ``--lax`` as without it, and an unknown attr is the strict gate's finding, not
    this one's.
    """
    from metaobjects.loader.sources import DirectorySource

    providers, _errors = _resolve_providers(getattr(args, "provider", None))
    if args.metadata_dir is not None:
        root, _ = _load_root(args.metadata_dir, providers=providers)
        files = [source.path for source in DirectorySource(args.metadata_dir).expand()]
    else:
        config_path = _find_config(args)
        config = load_project_config(config_path) if config_path is not None else None
        libraries: "list[str] | None" = None
        if config is not None:
            # Quiet on purpose: a bad provider is the gate's error to print, once.
            providers, _errors = _resolve_providers(config.providers)
            libraries = config.libraries
            start = project_root_for(config.metadata_dir())
        else:
            start = Path.cwd()
        collection = resolve_metadata_location(config=config, root=start)
        root, _ = _load_root_from_collection(collection, providers=providers, libraries=libraries)
        # The project's OWN files — a dependency artifact is not the adopter's to edit.
        files = list(collection.own_files)
    if root is None:
        return None
    return [*lint_reference_fields(root), *lint_duplicate_fields(files)]


def _run_field_lint_advisory(args: argparse.Namespace) -> None:
    """The field AUTHORING lint (see :mod:`metaobjects.field_lint`) — runs on every
    ``verify``, whichever gates were selected. Warnings ONLY: it prints to stderr and
    never changes the exit code. Muted by ``--no-field-lint`` or ``META_NO_FIELD_LINT=1``.
    """
    if getattr(args, "no_field_lint", False) or os.environ.get(FIELD_LINT_ENV) == "1":
        return
    try:
        findings = _field_lint_findings(args)
    except Exception:  # noqa: BLE001 — an advisory scan never breaks verify
        return
    if not findings:
        return
    print(
        f"metaobjects verify — fields: {len(findings)} authoring warning(s) "
        "(advisory — does not fail the build):",
        file=sys.stderr,
    )
    for finding in findings:
        print(f"  {finding.code} [{finding.path}]: {finding.message}", file=sys.stderr)


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.
    """
    _warn_if_agent_context_stale()

    run_db = args.db is not None
    run_templates = bool(args.templates)
    run_codegen = bool(args.codegen)
    any_explicit = run_db or run_templates or run_codegen

    if not any_explicit:
        print(
            "metaobjects verify — running --codegen (default). Explicit "
            "subverbs: --codegen (codegen drift), --templates (template/prompt "
            "drift), --db (schema drift — not supported in Python).",
            file=sys.stderr,
        )
        run_codegen = True

    exit_code = 0
    if run_db:
        exit_code = max(exit_code, _verify_db(args))
    if run_codegen:
        exit_code = max(exit_code, _verify_codegen(args))
    if run_templates:
        exit_code = max(exit_code, _verify_templates(args))
    _run_field_lint_advisory(args)
    return exit_code


def _cmd_agent_docs(args: argparse.Namespace) -> int:
    """``agent-docs`` — redirect to the canonical Node meta CLI scaffolder."""
    print(
        "agent-context scaffolding moved to the meta CLI — run: "
        "npx meta agent-docs --server python [--client <fw>] [--out <dir>]",
        file=sys.stderr,
    )
    return 1


def _build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(
        prog="metaobjects",
        description=(
            "MetaObjects Python codegen CLI. Generate idiomatic Python from "
            "metadata and verify it has not drifted. Schema migrations are "
            "owned by the Node `meta` CLI (ADR-0015) — there is no `migrate` "
            "subcommand here."
        ),
        epilog="--version, -v, -V  print the version and exit",
    )
    sub = parser.add_subparsers(dest="command", required=True)

    gen = sub.add_parser("gen", help="run codegen, writing files under --out")
    # metadata_dir / --out are optional so `gen --list` works without them.
    gen.add_argument(
        "metadata_dir",
        nargs="?",
        default=None,
        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,
        help=(
            "REQUIRED — comma-separated STABLE generator names to run "
            "(e.g. entity,routes). Codegen is opt-in: there is no default suite, so a "
            "run that names none is a usage error. See `gen --list` for the catalog."
        ),
    )
    gen.add_argument(
        "--list",
        action="store_true",
        help="list registered generators (stable name + description) and exit",
    )
    gen.add_argument(
        "--baseline",
        choices=("default", "adopt"),
        default="default",
        help=(
            "first-time-on-existing-file behaviour. 'default' refuses a file that cannot "
            "be proved to be generated output; 'adopt' records the files you have as the "
            "baseline and writes NOTHING — the one run a project with no committed "
            ".gen-state/.hashes.json can perform, since nothing writes a manifest until a "
            "gen succeeds. Adopting DECLARES those files to be generated output: the next "
            "gen regenerates over them, so commit before you run it."
        ),
    )
    gen.add_argument(
        "--template-spec",
        dest="template_spec",
        default=None,
        help=(
            "path to a JSON template-spec ({\"generators\":[{name,template,scope,"
            "outputPattern,format?}]}) — declarative Mustache generators appended "
            "to the suite (SP-1). Templates resolve under --templates. For output "
            "to be regenerable, the template must emit the @generated header itself "
            "(the codegen write path refuses to overwrite files lacking it)."
        ),
    )
    gen.add_argument(
        "--templates",
        default=None,
        help=(
            "on-disk root that template refs resolve under — used by "
            "--template-spec AND by the render-helper generator's drift gate "
            "(default: prompts/ when it exists, else templates/)"
        ),
    )
    gen.add_argument(
        "--package",
        default=None,
        help="(reserved) package hint; Python derives package from metadata",
    )
    gen.add_argument(
        "--entities",
        default=None,
        help=(
            "comma-separated entity NAMES to emit (allowlist). The whole model is "
            "still loaded so `extends` bases and @objectRef VOs resolve; only the "
            "named entities are written. Omit to emit every entity."
        ),
    )
    gen.add_argument(
        "--provider",
        action="append",
        metavar="module:symbol",
        help=(
            "load a consumer metadata Provider as 'module:symbol' (repeatable) — the "
            "Python parity of TS metaobjects.config.ts providers, so a custom subtype "
            "resolves through the standalone CLI (#158)"
        ),
    )
    gen.add_argument(
        "--config",
        default=None,
        help=(
            "path to a metaobjects.config.yaml (declarative targets registry). "
            "Config mode runs when no <metadata_dir> is given; default lookup is "
            "./metaobjects.config.yaml in cwd."
        ),
    )
    gen.add_argument(
        "--target",
        default=None,
        help="run only this named target from the config (default: every target)",
    )
    gen.set_defaults(func=_cmd_gen)

    docs = sub.add_parser(
        "docs",
        help=(
            "emit the native Python SDK api-reference docs (the api/python "
            "surface of the cross-port SDK-docs contract) under --out"
        ),
    )
    # Optional, like `gen`'s: an omitted positional falls through the same
    # location ladder (`metaobjects.config.yaml`'s `metadata` key, else the
    # neutral `.metaobjects/config.json` `sources`, else the default directory)
    # instead of hard-requiring the caller to name a directory.
    docs.add_argument(
        "metadata_dir",
        nargs="?",
        default=None,
        help="directory of metadata JSON/YAML files (omit to use the config ladder)",
    )
    docs.add_argument(
        "--out",
        required=True,
        help="docs output root; pages land under <out>/api/python",
    )
    docs.add_argument(
        "--api-subdir",
        dest="api_subdir",
        default=None,
        help="api-surface subdir under --out (default: api/python)",
    )
    docs.add_argument(
        "--project",
        default=None,
        help="project name shown in the docs (default: the metadata dir name)",
    )
    docs.add_argument(
        "--model-base-url",
        dest="model_base_url",
        default=None,
        help="federate the model back-links to an absolute base URL (default: relative)",
    )
    docs.add_argument(
        "--provider",
        action="append",
        metavar="module:symbol",
        help="load a consumer metadata Provider as 'module:symbol' (repeatable; #158)",
    )
    docs.set_defaults(func=_cmd_docs)

    verify = sub.add_parser(
        "verify",
        help=(
            "drift gate — explicit subverbs --codegen / --templates / --db "
            "(ADR-0021 D2); bare verify defaults to --codegen"
        ),
    )
    verify.add_argument(
        "metadata_dir",
        nargs="?",
        default=None,
        help=(
            "directory of metadata JSON/YAML files. Omit to use a "
            "metaobjects.config.yaml (--codegen config mode, #267)."
        ),
    )
    verify.add_argument(
        "--codegen",
        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",
        help=(
            "template drift: each template.* node's {{field}} ↔ payload-VO "
            "field tree (render verify); requires --prompts"
        ),
    )
    verify.add_argument(
        "--db",
        default=None,
        metavar="URL",
        help="schema drift — NOT supported in the Python port (exit 2)",
    )
    verify.add_argument(
        "--out",
        default=None,
        help="committed output directory to diff against (for --codegen)",
    )
    # F101 — the prompt directory is spelled three ways across the ports: `--prompts <dir>`
    # (Node `meta`, the reference), `--templates <root>` (dotnet meta, inline on the subverb)
    # and `--templates-root` here. `--prompts` is the converged spelling, adopted from the
    # reference port because it does not overload the subverb's own name. `--templates-root`
    # keeps working — the 1.0 CLI surface is frozen, so this is additive; the old spelling is
    # deprecated in 1.1 and stays until a major. argparse's FIRST option string is the one
    # help prints, so the converged name leads.
    verify.add_argument(
        "--prompts",
        "--templates-root",
        dest="templates_root",
        default=None,
        help=(
            "on-disk template/prompt dir the --templates gate resolves refs against "
            "(--templates-root is the deprecated alias)"
        ),
    )
    verify.add_argument(
        "--entities",
        default=None,
        help="comma-separated entity allowlist for --codegen drift (match `gen --entities`)",
    )
    verify.add_argument(
        "--no-field-lint",
        action="store_true",
        help=(
            "suppress the advisory field AUTHORING lint (a reference identity over a "
            "missing field; a duplicate field name) — never a gate, it cannot fail the "
            "build. META_NO_FIELD_LINT=1 does the same."
        ),
    )
    verify.add_argument(
        "--lax",
        action="store_true",
        help=(
            "opt out of strict-attr load (ADR-0023, #96): verify is strict by "
            "default — an undeclared/typo'd @attr fails. --lax restores the legacy "
            "open-attr load."
        ),
    )
    verify.add_argument(
        "--provider",
        action="append",
        metavar="module:symbol",
        help="load a consumer metadata Provider as 'module:symbol' (repeatable; #158)",
    )
    verify.add_argument(
        "--config",
        default=None,
        help=(
            "path to a metaobjects.config.yaml. Config mode runs when no "
            "<metadata_dir> is given; default ./metaobjects.config.yaml in cwd. "
            "Drives --codegen per-target regen+diff."
        ),
    )
    verify.add_argument(
        "--target",
        default=None,
        help="verify only this named target from the config (default: every target)",
    )
    verify.add_argument(
        "--generators",
        default=None,
        help=(
            "comma-separated STABLE generator names — must MATCH the `gen` that "
            "produced --out. `verify --codegen` re-runs the selection and diffs; with "
            "none named there is nothing to check and it says so."
        ),
    )
    verify.set_defaults(func=_cmd_verify)

    fmt_p = sub.add_parser(
        "fmt",
        help="rewrite metadata files into canonical form (#304)",
    )
    fmt_p.add_argument(
        "files",
        nargs="*",
        metavar="FILE",
        help="optional explicit file(s) to format — must be members of this "
        "project's resolved metadata sources; omit to format every one of them",
    )
    fmt_p.add_argument(
        "--check",
        action="store_true",
        help="list files that are not canonical and exit non-zero; changes nothing",
    )
    fmt_p.add_argument(
        "--provider",
        action="append",
        default=None,
        metavar="MODULE:SYMBOL",
        help="consumer-registered Provider(s), repeatable (module:symbol)",
    )
    fmt_p.set_defaults(func=_cmd_fmt)

    eject_p = sub.add_parser(
        "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("--force", action="store_true",
                         help="replace an existing owned copy with the reference")
    eject_p.add_argument("--root", default=None, help="project root (default: cwd)")
    eject_p.set_defaults(func=_cmd_eject)

    agent_docs = sub.add_parser(
        "agent-docs",
        help=(
            "scaffold the slim MetaObjects Claude Code agent context "
            "(.metaobjects/AGENTS.md + CLAUDE.md + the metaobjects-* skills)"
        ),
    )
    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)",
    )
    agent_docs.set_defaults(func=_cmd_agent_docs)

    return parser


# The three spellings that print the bare version — the same set every port's CLI answers.
VERSION_FLAGS = ("--version", "-v", "-V")


def _refuse_extras(parser: argparse.ArgumentParser, command: str, extras: list[str]) -> int:
    """Refuse what a subcommand did not consume, naming the subcommand and its flags.

    argparse attributes a subcommand's unknown flag to the TOP-LEVEL parser: it printed
    ``usage: metaobjects [-h] {gen,docs,...}`` and ``unrecognized arguments: --x``, which
    names neither the command nor a flag that would have worked. This is the one wording
    every port's CLI uses for it, and it exits 2.
    """
    subparser = next(
        (
            action.choices.get(command)
            for action in parser._actions  # noqa: SLF001 — argparse exposes no public accessor
            if isinstance(action, argparse._SubParsersAction)  # noqa: SLF001
        ),
        None,
    )
    first = extras[0]
    if not first.startswith("-") or subparser is None:
        print(f"unexpected argument {first!r} for `metaobjects {command}`", file=sys.stderr)
        return 2
    valid = sorted(
        ", ".join(action.option_strings)
        for action in subparser._actions  # noqa: SLF001
        if action.option_strings and "--help" not in action.option_strings
    )
    print(
        f"unknown flag {first} for `metaobjects {command}`. Valid flags: {', '.join(valid)} "
        "(also accepted everywhere: --help)",
        file=sys.stderr,
    )
    return 2


def main(argv: list[str] | None = None) -> int:
    """Entry point. Returns the process exit code (does not call ``sys.exit``)."""
    raw = sys.argv[1:] if argv is None else argv
    if len(raw) == 1 and raw[0] in VERSION_FLAGS:
        print(installed_metaobjects_version())
        return 0
    parser = _build_parser()
    args, extras = parser.parse_known_args(raw)
    if extras:
        return _refuse_extras(parser, args.command, extras)
    return int(args.func(args))


if __name__ == "__main__":  # pragma: no cover
    sys.exit(main())