metaobjects 1.0.5rc10__tar.gz → 1.0.7__tar.gz

{metaobjects-1.0.5rc10 → metaobjects-1.0.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: metaobjects
-Version: 1.0.5rc10
+Version: 1.0.7
 Summary: Cross-language metadata standard: declare typed entities once, generate idiomatic drift-checked code across languages — Python port.
 Project-URL: Homepage, https://metaobjects.dev
 Project-URL: Repository, https://github.com/metaobjectsdev/metaobjects
@@ -78,7 +78,8 @@ else:
 The primary public API is the **loader** (`load_directory` / `load_uris` /
 `load_string`, `MetaDataLoader`, `LoadResult`, `ErrorCode`, `MetaError`). The
 distribution also ships the Python implementations of the other pillars used by the CLI
-and tooling: `codegen` (Pydantic + FastAPI emit), `render` (Mustache + payload-VO +
+and tooling: `codegen` (Pydantic + FastAPI emit — reference generators you own:
+`metaobjects eject <name>` copies one into your repo), `render` (Mustache + payload-VO +
 verify), and `runtime` (a DB-API 2 `ObjectManager` — pg8000 / psycopg — no SQLAlchemy).
 Schema migrations are owned by the TypeScript `meta` CLI (ADR-0015); there is
 **no `migrate` module** in this distribution.

{metaobjects-1.0.5rc10 → metaobjects-1.0.7}/README.md

@@ -43,7 +43,8 @@ else:
 The primary public API is the **loader** (`load_directory` / `load_uris` /
 `load_string`, `MetaDataLoader`, `LoadResult`, `ErrorCode`, `MetaError`). The
 distribution also ships the Python implementations of the other pillars used by the CLI
-and tooling: `codegen` (Pydantic + FastAPI emit), `render` (Mustache + payload-VO +
+and tooling: `codegen` (Pydantic + FastAPI emit — reference generators you own:
+`metaobjects eject <name>` copies one into your repo), `render` (Mustache + payload-VO +
 verify), and `runtime` (a DB-API 2 `ObjectManager` — pg8000 / psycopg — no SQLAlchemy).
 Schema migrations are owned by the TypeScript `meta` CLI (ADR-0015); there is
 **no `migrate` module** in this distribution.

{metaobjects-1.0.5rc10 → metaobjects-1.0.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "metaobjects"
-version = "1.0.5rc10"
+version = "1.0.7"
 description = "Cross-language metadata standard: declare typed entities once, generate idiomatic drift-checked code across languages — Python port."
 readme = "README.md"
 requires-python = ">=3.11"

{metaobjects-1.0.5rc10 → metaobjects-1.0.7}/src/metaobjects/cli.py

@@ -105,6 +105,7 @@ from metaobjects.codegen.generator_registry import (
     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,
 )
@@ -501,10 +502,14 @@ def _template_root_for(args: argparse.Namespace) -> str:
 
 
 def _resolve_generators(
-    names: str, ctx: GeneratorBuildContext | None = None,
+    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).
 
@@ -519,17 +524,27 @@ def _resolve_generators(
     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(requested):
+        for warning in unsatisfied_requires(selected):
             print(f"warning: {warning}", file=sys.stderr)
     return gens, errors
 
@@ -968,17 +983,42 @@ def _cmd_docs(args: argparse.Namespace) -> int:
     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 ""
-        print(f"{entry.name} — {entry.description}{requires}")
+        status = owned.owned_status(root, entry)
+        mark = f" [owned — {status}]" if status is not None else ""
+        print(f"{entry.name} — {entry.description}{requires}{mark}")
     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.
 
@@ -1161,7 +1201,8 @@ def _run_gen_targets(
         gens: list[Generator] | None = None
         if t.generators is not None:
             gens, gen_errors = _resolve_generators(
-                ",".join(t.generators), build_ctx or GeneratorBuildContext())
+                ",".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
@@ -2365,6 +2406,16 @@ def _build_parser() -> argparse.ArgumentParser:
     )
     verify.set_defaults(func=_cmd_verify)
 
+    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=(

metaobjects-1.0.7/src/metaobjects/codegen/eject.py

@@ -0,0 +1,168 @@
+"""`metaobjects eject` — copy a reference generator into the adopter's repo to own.
+
+ADR-0034 Amendment 3: a generator is a reference helper, not a guarantee. The adopter
+copies it with ``eject``, wires the copy into ``generators`` as ``module:symbol`` (the
+syntax ``providers`` already accepts), and ``gen`` / ``verify --codegen`` run the copy.
+Mirrors the TypeScript ``meta eject``: the copy is verbatim, an existing copy is never
+overwritten without ``--force``, and the config is never edited — eject prints the entry
+to wire instead.
+
+A copy imports the same ``metaobjects.codegen.*`` module paths the packaged generator
+does. Those module paths are the documented surface an owned generator builds on.
+"""
+from __future__ import annotations
+
+import importlib
+import inspect
+import sys
+import tempfile
+from collections import Counter
+from dataclasses import dataclass
+from pathlib import Path
+
+from metaobjects.codegen.generator import Generator
+from metaobjects.codegen.generator_registry import (
+    GENERATOR_REGISTRY,
+    GeneratorBuildContext,
+    GeneratorEntry,
+)
+
+#: Where an owned copy lands, relative to the project root. Mirrors the TS layout.
+OWNED_DIR = Path("codegen") / "generators"
+
+
+def owned_stem(name: str) -> str:
+    """The module name of an owned copy: the stable name with ``-`` as ``_``."""
+    return name.replace("-", "_")
+
+
+def owned_path(root: Path, name: str) -> Path:
+    return root / OWNED_DIR / f"{owned_stem(name)}.py"
+
+
+def owned_token(entry: GeneratorEntry) -> str:
+    """The ``module:symbol`` entry that wires an owned copy of *entry*."""
+    return f"codegen.generators.{owned_stem(entry.name)}:{entry.symbol}"
+
+
+def packaged_source(entry: GeneratorEntry) -> str:
+    assert entry.source_module is not None
+    module = importlib.import_module(entry.source_module)
+    assert module.__file__ is not None
+    return Path(module.__file__).read_text(encoding="utf-8")
+
+
+def ejectable() -> list[GeneratorEntry]:
+    return [e for e in GENERATOR_REGISTRY.values() if e.source is not None]
+
+
+@dataclass
+class EjectResult:
+    code: int
+    out: list[str]
+    err: list[str]
+
+
+def eject(names: list[str], root: Path, *, force: bool = False) -> EjectResult:
+    """Copy each named generator. Every name is checked before any file is written."""
+    known = {e.name: e for e in ejectable()}
+    unknown = [n for n in names if n not in known]
+    if unknown:
+        return EjectResult(2, [], [
+            f"unknown or non-ejectable generator(s): {', '.join(unknown)}; "
+            f"ejectable: {', '.join(sorted(known))}",
+        ])
+    existing = [n for n in names if owned_path(root, n).exists()]
+    if existing and not force:
+        return EjectResult(1, [], [
+            f"already owned: {', '.join(str(owned_path(root, n).relative_to(root)) for n in existing)}. "
+            "Eject never overwrites your copy; pass --force to replace it with the reference.",
+        ])
+
+    (root / OWNED_DIR).mkdir(parents=True, exist_ok=True)
+    for init in (root / "codegen" / "__init__.py", root / OWNED_DIR / "__init__.py"):
+        if not init.exists():
+            init.write_text("", encoding="utf-8")
+
+    out: list[str] = []
+    for n in names:
+        entry = known[n]
+        target = owned_path(root, n)
+        target.write_text(packaged_source(entry), encoding="utf-8")
+        out.append(f"ejected {n} -> {target.relative_to(root)}")
+        out.append(f"  wire it: replace \"{n}\" in `generators` with {owned_token(entry)}")
+    out.append("")
+    out.append(
+        "The copies are yours: edit them freely. Keep only one of the packaged name and your "
+        "copy in `generators` — wiring both runs both, and they write the same files."
+    )
+    return EjectResult(0, out, [])
+
+
+def _normalised(text: str) -> Counter[str]:
+    return Counter(line.rstrip() for line in text.splitlines() if line.strip())
+
+
+def owned_status(root: Path, entry: GeneratorEntry) -> str | None:
+    """``identical`` / ``DIFFERS: N behind, M of your own``, or ``None`` if not owned.
+
+    Line-multiset comparison, the same shape as TS ``owned-copy.ts``: *behind* counts
+    reference lines the copy lacks, *of your own* counts copy lines the reference lacks.
+    """
+    path = owned_path(root, entry.name)
+    if entry.source is None or not path.exists():
+        return None
+    mine = _normalised(path.read_text(encoding="utf-8"))
+    ref = _normalised(packaged_source(entry))
+    behind = sum((ref - mine).values())
+    own = sum((mine - ref).values())
+    if behind == 0 and own == 0:
+        return "identical"
+    return f"DIFFERS: {behind} behind, {own} of your own"
+
+
+def build_owned(spec: str, root: Path, ctx: GeneratorBuildContext) -> tuple[Generator | None, str | None]:
+    """Resolve a ``module:symbol`` generator entry against the project at *root*.
+
+    The symbol may be a Generator, or a factory: one taking ``template_root`` (the
+    render-helper shape) gets the build context's template root; one taking a single
+    positional argument gets the build context; otherwise it is called with none.
+    """
+    module_name, sep, symbol = spec.partition(":")
+    if not sep or not module_name or not symbol:
+        return None, (f"generator {spec!r} is neither a registered name nor a "
+                      "'module:symbol' reference to an owned copy")
+    root_str = str(root.resolve())
+    if root_str not in sys.path:
+        sys.path.insert(0, root_str)
+    # A module of the same name imported from another project (or an earlier copy) would
+    # be reused from the cache; drop any entry that does not live under this root.
+    top = module_name.split(".")[0]
+    for key in [k for k in sys.modules if k == top or k.startswith(top + ".")]:
+        file = getattr(sys.modules[key], "__file__", None)
+        if file is None or not str(Path(file).resolve()).startswith(root_str):
+            del sys.modules[key]
+    try:
+        module = importlib.import_module(module_name)
+    except Exception as exc:  # ImportError and anything raised at import time
+        return None, f"generator {spec!r}: cannot import {module_name!r}: {exc}"
+    obj = getattr(module, symbol, None)
+    if obj is None:
+        return None, f"generator {spec!r}: {module_name!r} has no attribute {symbol!r}"
+    if not hasattr(obj, "generate") and callable(obj):
+        params = inspect.signature(obj).parameters
+        required = [p for p in params.values()
+                    if p.default is inspect.Parameter.empty
+                    and p.kind in (p.POSITIONAL_ONLY, p.POSITIONAL_OR_KEYWORD)]
+        try:
+            if "template_root" in params:
+                obj = obj(template_root=ctx.template_root or tempfile.gettempdir())
+            elif len(required) == 1:
+                obj = obj(ctx)
+            else:
+                obj = obj()
+        except Exception as exc:
+            return None, f"generator {spec!r}: factory {symbol}() raised: {exc}"
+    if not hasattr(obj, "generate") or not hasattr(obj, "name"):
+        return None, f"generator {spec!r}: {symbol!r} is not a generator (needs name and generate)"
+    return obj, None

{metaobjects-1.0.5rc10 → metaobjects-1.0.7}/src/metaobjects/codegen/generator_registry.py

@@ -108,6 +108,21 @@ class GeneratorEntry:
     #: Not gated cross-port (the manifest carries no such column); surfaced by ``--list``
     #: and warned about by :func:`unsatisfied_requires`.
     requires: tuple[str, ...] = ()
+    #: The packaged factory an adopter copies with ``metaobjects eject`` (ADR-0034
+    #: Amendment 3). Its module is the file copied; its name is the ``module:symbol``
+    #: symbol the copy is wired by. ``None`` = not ejectable (the ``template`` primitive
+    #: has no emit logic of its own to own).
+    source: Callable[..., Generator] | None = None
+
+    @property
+    def source_module(self) -> str | None:
+        """Dotted module path of the file ``eject`` copies, or ``None``."""
+        return self.source.__module__ if self.source is not None else None
+
+    @property
+    def symbol(self) -> str | None:
+        """The factory name an owned copy exports, or ``None``."""
+        return self.source.__name__ if self.source is not None else None
 
 
 def _template_primitive(_ctx: GeneratorBuildContext) -> Generator:
@@ -149,10 +164,16 @@ def _render_helper_default(ctx: GeneratorBuildContext) -> Generator:
 GENERATOR_REGISTRY: dict[str, GeneratorEntry] = {
     "entity": GeneratorEntry(
         name="entity",
-        description="Per-entity model/class — the entity module (table-backed or value object).",
+        description=(
+            "Per-entity model/class — the entity module (table-backed or value object). "
+            "[A field with @stringFormat email is typed pydantic EmailStr, which imports "
+            "email-validator when the class is defined, so the consuming project needs "
+            "`pydantic[email]` — without it the generated module fails at import.]"
+        ),
         tier="native",
         layer="model",
         factory=lambda _ctx: entity_model(),
+        source=entity_model,
     ),
     "routes": GeneratorEntry(
         name="routes",
@@ -160,6 +181,7 @@ GENERATOR_REGISTRY: dict[str, GeneratorEntry] = {
         tier="native",
         layer="api",
         factory=lambda _ctx: router_generator(),
+        source=router_generator,
     ),
     "output-parser": GeneratorEntry(
         name="output-parser",
@@ -168,6 +190,7 @@ GENERATOR_REGISTRY: dict[str, GeneratorEntry] = {
         layer="capability",
         factory=lambda _ctx: output_parser_generator(),
         requires=("entity",),
+        source=output_parser_generator,
     ),
     "output-prompt": GeneratorEntry(
         name="output-prompt",
@@ -175,6 +198,7 @@ GENERATOR_REGISTRY: dict[str, GeneratorEntry] = {
         tier="native",
         layer="capability",
         factory=lambda _ctx: output_prompt_generator(),
+        source=output_prompt_generator,
     ),
     "render-helper": GeneratorEntry(
         name="render-helper",
@@ -183,6 +207,7 @@ GENERATOR_REGISTRY: dict[str, GeneratorEntry] = {
         layer="capability",
         factory=_render_helper_default,
         requires=("entity",),
+        source=render_helper_generator,
     ),
     "extractor": GeneratorEntry(
         name="extractor",
@@ -191,6 +216,7 @@ GENERATOR_REGISTRY: dict[str, GeneratorEntry] = {
         layer="capability",
         factory=lambda _ctx: extractor_generator(),
         requires=("entity",),
+        source=extractor_generator,
     ),
     "template": GeneratorEntry(
         name="template",
@@ -205,6 +231,7 @@ GENERATOR_REGISTRY: dict[str, GeneratorEntry] = {
         tier="native",
         layer="api",
         factory=lambda _ctx: filter_allowlist_generator(),
+        source=filter_allowlist_generator,
     ),
     "names": GeneratorEntry(
         name="names",
@@ -212,6 +239,7 @@ GENERATOR_REGISTRY: dict[str, GeneratorEntry] = {
         tier="native",
         layer="model",
         factory=lambda _ctx: names_generator(),
+        source=names_generator,
     ),
     "trace-helper": GeneratorEntry(
         name="trace-helper",
@@ -219,6 +247,7 @@ GENERATOR_REGISTRY: dict[str, GeneratorEntry] = {
         tier="native",
         layer="capability",
         factory=lambda _ctx: trace_helper_generator(),
+        source=trace_helper_generator,
     ),
 }
 

{metaobjects-1.0.5rc10 → metaobjects-1.0.7}/src/metaobjects/codegen/generators/router_generator.py

@@ -431,6 +431,32 @@ def _sort_parse_fn_lines() -> list[str]:
     ]
 
 
+def _auth_docstring_paragraph(*, read_only: bool) -> str:
+    """The auth-seam paragraph appended to every generated router's module docstring
+    (#367). A generated router is unauthenticated by construction — the consumer wires
+    a dependency onto `app.include_router` — and until this, nothing in the emitted
+    module said so, mirroring the gap the TS route generators closed for #367 with a
+    doc-comment above the register function. Python has no `expose` option to narrow a
+    generated router down to a safe subset (non-TS REST templates are frozen for
+    features), so the escape hatch for anything a dependency cannot express — a
+    row-ownership rule — is `metaobjects eject`, not a narrowing flag.
+
+    *read_only* only swaps "these endpoints" for "these read endpoints" on a
+    projection's GET-only surface; the guidance is otherwise identical. Returned text
+    starts and ends with a newline so a caller can splice it directly between the
+    docstring's summary line and the closing `\"\"\"`."""
+    verbs = "read endpoints" if read_only else "endpoints"
+    return (
+        "\n"
+        f"Auth: these {verbs} are unauthenticated. To guard them, include the router with a\n"
+        "dependency, e.g. `app.include_router(router, dependencies=[Depends(require_auth)])`.\n"
+        "\n"
+        'A row-ownership rule ("only the owner may read this row") cannot be expressed as a\n'
+        "router dependency: eject this generator with `metaobjects eject` and hand-write\n"
+        "those endpoints.\n"
+    )
+
+
 class RouterGenerator:
     """One ``<entity_snake>_router.py`` per routed object (FastAPI ``APIRouter``):
     full CRUD for a writable source, read-only for a view-backed one.
@@ -882,7 +908,9 @@ class RouterGenerator:
         parts.append(
             h + "\n"
             + f'"""GENERATED — TPH polymorphic REST router for the {short_name} hierarchy '
-            + '(single-table inheritance: polymorphic base + per-subtype CRUD)."""\n'
+            + '(single-table inheritance: polymorphic base + per-subtype CRUD).\n'
+            + _auth_docstring_paragraph(read_only=False)
+            + '"""\n'
         )
         parts.append("from __future__ import annotations")
         parts.append("")
@@ -1232,7 +1260,9 @@ class RouterGenerator:
         parts: list[str] = []
         parts.append(
             generated_header(short_name, _effective_fqn(entity)).rstrip() + "\n"
-            + f'"""GENERATED — REST router for {short_name} entity. Implements the cross-port API contract."""\n'
+            + f'"""GENERATED — REST router for {short_name} entity. Implements the cross-port API contract.\n'
+            + _auth_docstring_paragraph(read_only=False)
+            + '"""\n'
         )
         parts.append("from __future__ import annotations")
         parts.append("")
@@ -1401,7 +1431,9 @@ class RouterGenerator:
             generated_header(short_name, _effective_fqn(entity)).rstrip() + "\n"
             + f'"""GENERATED — read-only REST router for the {short_name} projection.\n\n'
             + "Implements the cross-port API contract: GET list + GET by id; every write\n"
-            + 'verb answers 405 {"error": "method_not_allowed"}."""\n'
+            + 'verb answers 405 {"error": "method_not_allowed"}.\n'
+            + _auth_docstring_paragraph(read_only=True)
+            + '"""\n'
         )
         parts.append("from __future__ import annotations")
         parts.append("")

{metaobjects-1.0.5rc10 → metaobjects-1.0.7}/src/metaobjects/codegen/runner.py

@@ -151,6 +151,7 @@ def run_gen(
 
     refused: list[str] = []
     adopted: list[str] = []
+    untracked = 0
     for full, (content, _by) in emitted.items():
         # The out-dir-relative name: what the manifest used to be keyed by, and still
         # what a refusal is REPORTED as (it is the name the reader sees in `--out`).
@@ -173,11 +174,17 @@ def run_gen(
             if config.project_root
             else rel
         )
+        # A file written OUTSIDE the project has no place in the project's manifest: its
+        # key would be `../`-relative and committed into `.hashes.json`. It gets the
+        # manifest-less rule a run with no project gets — written, never recorded.
+        outside = bool(config.project_root) and (key.startswith("..") or os.path.isabs(key))
+        if outside:
+            untracked += 1
         status = decide_and_write(
             full,
             content,
             merge_strategy,
-            gen_state_dir=config.gen_state_dir,
+            gen_state_dir=None if outside else config.gen_state_dir,
             rel_path=key,
             legacy_rel_path=rel if key != rel else None,
             baseline=config.baseline,
@@ -188,6 +195,13 @@ def run_gen(
         elif status == "adopted":
             adopted.append(rel)
 
+    if untracked:
+        result.warnings.append(
+            f"{untracked} generated file(s) were written outside the project root and are "
+            f"not recorded in .metaobjects/.gen-state/.hashes.json, so hand-edit protection "
+            f"does not apply to them beyond the @generated header rule."
+        )
+
     if refused:
         if not tracking_hashes:
             # No state to reason from, so decide_and_write can only have refused for

{metaobjects-1.0.5rc10 → metaobjects-1.0.7}/src/metaobjects/render/extract/extract.py

@@ -45,7 +45,7 @@ def extract(
     span: str | None
     raw: dict[str, object]
     if schema.format == Format.JSON:
-        span = _locate.json(stripped)
+        span = _select_json(text, stripped, schema.fields, ci)
         raw = {} if span is None else JsonForgivingReader().read(span)
     elif o.rootless:
         span = None if stripped == "" else stripped
@@ -199,12 +199,39 @@ def _extract_value(
     # A text element that also carried XML attributes is represented by XmlForgivingReader
     # as a dict with the body under TEXT_KEY. A scalar field reads that text (attributes
     # ignored for scalars — preserving pre-attribute-support behaviour).
-    if isinstance(present, dict) and TEXT_KEY in present:
+    if isinstance(present, dict):
+        # An element with no text of its own (only child elements) is not a scalar value.
+        # Never stringify the dict: that delivered "{'child': ...}" as the field's text.
+        if TEXT_KEY not in present:
+            return MALFORMED
         present = present[TEXT_KEY]
     raw_str = present if isinstance(present, str) else str(present)
     return _coerce.value(raw_str, f, o, path, report)
 
 
+def _select_json(
+    text: str | None, stripped: str, fields: list[FieldSpec], ci: bool
+) -> str | None:
+    """Pick the JSON object that answers the schema. Fenced blocks are searched first, then
+    the whole reply, and the first object carrying at least one declared field wins, so a
+    draft object, an echoed format example or a brace in prose no longer shadows the real
+    answer (#363). A fenced object with none of the declared fields falls through the same
+    way. When nothing carries a declared field, the first-object rule (``locate.json``)
+    decides."""
+    for region in [*_strip.fenced_bodies(text), stripped]:
+        for candidate in _locate.json_candidates(region):
+            parsed = JsonForgivingReader().read(candidate)
+            if any(_carries(parsed, f.name, ci) for f in fields):
+                return candidate
+    return _locate.json(stripped)
+
+
+def _carries(raw: dict[str, object], name: str, ci: bool) -> bool:
+    if name in raw:
+        return True
+    return ci and any(k.lower() == name.lower() for k in raw)
+
+
 def _lookup(raw: dict[str, object], name: str, ci: bool) -> object | None:
     """Case-folding lookup honoring tolerance."""
     if name in raw:

{metaobjects-1.0.5rc10 → metaobjects-1.0.7}/src/metaobjects/render/extract/locate.py

@@ -1,6 +1,7 @@
 """Stages 2-3: isolate and select the payload root span.
 
-Selection rule: first-closed-else-first-open.
+JSON: extract picks among json_candidates by the schema (fenced first, first object carrying a
+declared field); json() (first-closed-else-first-open) is its fallback.
 """
 from __future__ import annotations
 
@@ -22,6 +23,28 @@ def json(text: str | None) -> str | None:
     return None if first_open < 0 else text[first_open:]
 
 
+def json_candidates(text: str | None) -> list[str]:
+    """Every top-level object span in ``text``, in order: each balanced {...} (nested objects
+    are part of their parent, not separate spans), and, for a '{' that never closes, the text
+    from it to the end."""
+    out: list[str] = []
+    if text is None:
+        return out
+    tail_added = False
+    i = 0
+    while i < len(text):
+        if text[i] == "{":
+            end = _scan_balanced(text, i)
+            if end >= 0:
+                out.append(text[i : end + 1])
+                i = end
+            elif not tail_added:
+                out.append(text[i:])
+                tail_added = True
+        i += 1
+    return out
+
+
 def _scan_balanced(s: str, open_idx: int) -> int:
     """Return index of the matching ``}``, or -1 if unterminated. String-aware."""
     depth = 0

{metaobjects-1.0.5rc10 → metaobjects-1.0.7}/src/metaobjects/render/extract/strip.py

@@ -18,3 +18,11 @@ def strip(raw: str | None) -> str:
     if m:
         return (raw[: m.start()] + m.group(1) + raw[m.end():]).strip()
     return raw.strip()
+
+
+def fenced_bodies(raw: str | None) -> list[str]:
+    """The body of every fenced block, in order. Locate searches these before the whole
+    text, because a model told to fence its answer puts the answer there."""
+    if raw is None:
+        return []
+    return [m.group(1) for m in _FENCE.finditer(raw)]