metaobjects 0.9.0__py3-none-any.whl

metaobjects/codegen/generators/template_generator.py

@@ -0,0 +1,70 @@
+"""template_generator() — Python port of the TS rc.12 factory.
+
+Walks the loaded MetaRoot -> renders shared Mustache templates via the
+metaobjects.render engine -> returns EmittedFile[]. Same Generator Protocol
+as the per-entity hand-coded generators; just adds the "Mustache template"
++ "walk that yields a data dict per output" primitives.
+
+Design: spec/design-docs/2026-05-28-cross-port-template-generator.md.
+Cross-port byte-equivalence verified via fixtures/render-conformance/template-generator/.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable, Iterable, Sequence
+
+from metaobjects.codegen.generator import EmittedFile, GenContext, Generator
+from metaobjects.render import escapers
+from metaobjects.render.renderer import RenderRequest, render
+from metaobjects.render.verify import Provider
+
+
+@dataclass
+class _TemplateGenerator:
+    name: str
+    template: str
+    walk: Callable[[Any], Sequence[dict]]
+    provider: Provider
+    format: str = escapers.FORMAT_TEXT
+
+    def generate(self, ctx: GenContext) -> list[EmittedFile]:
+        walk_results: Iterable[dict] = self.walk(ctx.loaded_root)
+        files: list[EmittedFile] = []
+        for entry in walk_results:
+            content = render(
+                RenderRequest(
+                    payload=entry["data"],
+                    provider=self.provider,
+                    ref=self.template,
+                    format=self.format,
+                )
+            )
+            files.append(EmittedFile(path=entry["output_path"], content=content))
+        return files
+
+
+def template_generator(
+    *,
+    name: str,
+    template: str,
+    walk: Callable[[Any], Sequence[dict]],
+    provider: Provider,
+    format: str = escapers.FORMAT_TEXT,
+) -> Generator:
+    """Build a Generator that renders a Mustache template per walk entry.
+
+    Args:
+        name: kebab-case identifier; surfaces in diagnostics.
+        template: ref resolved by the provider (e.g. "custom/hello").
+        walk: callback that takes the loaded MetaRoot and returns a list of
+            dicts shaped {"data": <payload>, "output_path": <relative path>}.
+        provider: ref-resolver for the template.
+        format: render format ("text", "html", "markdown", ...). Defaults to text.
+    """
+    return _TemplateGenerator(
+        name=name,
+        template=template,
+        walk=walk,
+        provider=provider,
+        format=format,
+    )

metaobjects/codegen/generators/tph_plan.py

@@ -0,0 +1,120 @@
+"""FR-017 Tier 4 — codegen-side descriptor for a table-per-hierarchy (TPH) base.
+
+Mirrors the C# ``TphPlan`` / TS ``tph-discriminator.ts``: an ``object.entity``
+carrying ``@discriminator`` is the TPH base; concrete entities that ``extends`` it
+and declare ``@discriminatorValue`` are its subtypes, all sharing ONE physical
+table (single-table inheritance). The plan is the single source of truth every
+TPH-aware generator reads, so the route-segment rule and subtype set never drift.
+
+The per-subtype REST route segment is the ``@discriminatorValue`` lowercased
+(``"Bridge"`` → ``bridge``, ``"PriorAuth"`` → ``priorauth``) — derived in exactly
+one place (:func:`route_segment`).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from metaobjects.meta.core.object.meta_object import MetaObject
+from metaobjects.meta.core.object.object_constants import (
+    OBJECT_ATTR_DISCRIMINATOR,
+    OBJECT_ATTR_DISCRIMINATOR_VALUE,
+)
+
+
+@dataclass(frozen=True)
+class TphSubtypePlan:
+    #: The concrete subtype entity.
+    entity: MetaObject
+    #: Its ``@discriminatorValue`` (e.g. ``"Bridge"``).
+    value: str
+    #: The per-subtype REST route segment (e.g. ``"bridge"``).
+    route_segment: str
+
+
+@dataclass(frozen=True)
+class TphPlan:
+    #: The discriminator base entity.
+    base: MetaObject
+    #: The discriminator field name (the base's ``@discriminator``).
+    discriminator_field: str
+    #: Concrete subtypes in stable (name-sorted) order.
+    subtypes: list[TphSubtypePlan]
+
+
+def route_segment(discriminator_value: str) -> str:
+    """The per-subtype REST route segment — the ONE place this rule lives: the
+    discriminator value lowercased."""
+    return discriminator_value.lower()
+
+
+def _discriminator_root(obj: MetaObject) -> MetaObject | None:
+    """The nearest ``@discriminator``-bearing ancestor (or self), walking ``extends``."""
+    cursor: MetaObject | None = obj
+    while cursor is not None:
+        field = cursor.attr(OBJECT_ATTR_DISCRIMINATOR)  # own attr
+        if isinstance(field, str) and field:
+            return cursor
+        cursor = cursor.super_data  # type: ignore[assignment]
+    return None
+
+
+def tph_subtype_binding(obj: MetaObject) -> tuple[str, str] | None:
+    """For a concrete TPH subtype, return ``(discriminator_field, discriminator_value)``
+    — the field NAME inherited from the ``@discriminator`` base + this subtype's own
+    ``@discriminatorValue``. ``None`` when *obj* is not a subtype. Used by the entity
+    generator to pin the inherited discriminator field to a ``Literal`` on the subtype."""
+    value = obj.attr(OBJECT_ATTR_DISCRIMINATOR_VALUE)  # own attr
+    if not isinstance(value, str) or not value:
+        return None
+    root = _discriminator_root(obj)
+    if root is None or root is obj:
+        return None
+    field = root.attr(OBJECT_ATTR_DISCRIMINATOR)
+    if not isinstance(field, str) or not field:
+        return None
+    return (field, value)
+
+
+def is_tph_subtype(obj: MetaObject) -> bool:
+    """True when *obj* is a concrete TPH subtype: it declares ``@discriminatorValue``
+    and (transitively) extends a ``@discriminator``-bearing base. Such an entity emits
+    NO standalone table/router — it is folded into the base's single table."""
+    value = obj.attr(OBJECT_ATTR_DISCRIMINATOR_VALUE)  # own attr
+    if not isinstance(value, str) or not value:
+        return False
+    root = _discriminator_root(obj)
+    return root is not None and root is not obj
+
+
+def tph_plan_for(base: MetaObject, object_index: dict[str, MetaObject]) -> TphPlan | None:
+    """The :class:`TphPlan` for a discriminator base, or ``None`` when *base* is not a
+    discriminator base (no ``@discriminator``, or no concrete subtypes)."""
+    disc_field = base.attr(OBJECT_ATTR_DISCRIMINATOR)  # own attr
+    if not isinstance(disc_field, str) or not disc_field:
+        return None
+    subtypes: list[TphSubtypePlan] = []
+    for obj in object_index.values():
+        if obj is base or getattr(obj, "is_abstract", False):
+            continue
+        value = obj.attr(OBJECT_ATTR_DISCRIMINATOR_VALUE)  # own attr
+        if not isinstance(value, str) or not value:
+            continue
+        # Walk the extends chain looking for `base`.
+        cursor = obj.super_data
+        found = False
+        while cursor is not None:
+            if cursor is base:
+                found = True
+                break
+            cursor = cursor.super_data
+        if found:
+            subtypes.append(TphSubtypePlan(obj, value, route_segment(value)))
+    if not subtypes:
+        return None
+    subtypes.sort(key=lambda s: s.entity.name)
+    return TphPlan(base, disc_field, subtypes)
+
+
+def is_tph_base(obj: MetaObject, object_index: dict[str, MetaObject]) -> bool:
+    """True when *obj* carries ``@discriminator`` AND has at least one concrete subtype."""
+    return tph_plan_for(obj, object_index) is not None

metaobjects/codegen/generators/trace_helper_generator.py

@@ -0,0 +1,336 @@
+"""Trace-helper codegen — one ``record_<entity>.py`` per concrete ``object.entity``
+that (a) transitively ``extends`` ``metaobjects::ai::LlmCallBase`` AND (b) nests a
+``template.prompt`` carrying ``@responseRef`` and/or ``@payloadRef``.
+
+AI LLM-call trace persistence — Unit 2 Slice 2 (Python port). Cross-port parity
+with the TypeScript ``trace-helper-file.ts`` (``record<Entity>`` + ``call<Entity>``)
+and the Java ``LlmTraceHelperGenerator`` (``record<Entity>`` only). This Python
+port emits the ``record_<entity>`` half ONLY — the render→call→record loop needs an
+``LlmClient`` seam that is BYO / vendor-neutral (ADR-0024), so ``call<Entity>`` is
+intentionally NOT emitted (matching Java).
+
+The emitted helper exposes a single ``record_<snake>(recorder, input, redact=None)``
+that:
+
+1. runs the tolerant extract (``extract`` from ``metaobjects.render.extract``,
+   which NEVER raises) of ``input.llm_response_text`` against a baked
+   ``_RESPONSE_SCHEMA`` (the response VO's field shape — emitted via the SAME
+   ``extract_schema_emitter`` path the output-parser generator uses for its
+   tolerant ``extract_lenient_*`` twin);
+2. derives ``status``/``error_detail`` from the extract report's lost-required gate
+   (a lost ``@required`` field → ``status="error"`` + a ``"lost required: …"`` detail);
+3. builds the base trace row via the Slice-1 ``build_llm_call_row`` (the 18
+   ``LlmCallBase`` base fields + raw ``llmRequest``/``llmResponse``), folding in the
+   derived status/error_detail by replacing the input;
+4. sets the typed ``voRequest`` (``input.llm_request``) and ``voResponse``
+   (``outcome.data`` — the extracted mirror dict) columns on the row → native jsonb;
+5. persists the row ONCE via the supplied recorder (the never-throwing Slice-1
+   ``persist_llm_call_row``, which redacts then records);
+6. returns a typed ``<Entity>TraceResult`` (``status``, ``error_detail``,
+   ``vo_response``).
+
+Skips (no helper emitted) when the entity is abstract, does not derive from
+``LlmCallBase``, has no nested ``template.prompt``, or that prompt carries NEITHER
+``@responseRef`` NOR ``@payloadRef`` (both gate the helper — matching the TS
+reference). The response VO is resolved via ``resolve_payload_vo`` (short-name OR
+FQN); a non-``object.value`` target is a hard generator error (matching Java).
+
+STI/TPH discriminator handling is DEFERRED (matching the Java port's Slice 2 — a
+plain trace entity is the target).
+"""
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from metaobjects.codegen import extract_schema_emitter as rse
+from metaobjects.codegen.constants import generated_header
+from metaobjects.codegen.format import ruff_format
+from metaobjects.codegen.generator import EmittedFile, GenContext, Generator
+from metaobjects.codegen.generators.payload_vo_generator import resolve_payload_vo
+from metaobjects.meta.core.object.meta_object import MetaObject
+from metaobjects.meta.core.object.object_constants import OBJECT_SUBTYPE_ENTITY
+from metaobjects.meta.meta_data import MetaData
+from metaobjects.meta.template import template_constants as tc
+from metaobjects.meta.template.meta_template import MetaTemplate
+from metaobjects.shared.base_types import TYPE_TEMPLATE
+
+_GENERATOR_NAME = "trace-helper"
+
+#: The abstract base entity a trace entity must (transitively) ``extends``.
+#: Cross-port constant — mirrors TS ``LLM_CALL_BASE`` / Java ``LLM_CALL_BASE``.
+LLM_CALL_BASE = "LlmCallBase"
+
+
+def _snake_case(name: str) -> str:
+    """``GreetingCall`` → ``greeting_call``. PascalCase → snake_case with no
+    acronym handling — matches the convention used by sibling generators
+    (``output_parser_generator._snake_case`` etc.)."""
+    out: list[str] = []
+    for i, ch in enumerate(name):
+        if ch.isupper() and i > 0:
+            out.append("_")
+        out.append(ch.lower())
+    return "".join(out)
+
+
+def _extends_base(entity: MetaObject) -> bool:
+    """Walk the resolved super chain looking for a node SHORT-named
+    :data:`LLM_CALL_BASE`. ``MetaData.name`` holds the short name only (the package
+    lives on ``MetaData.package``), so a plain ``name`` compare is the short-name
+    test — mirrors the Java ``getShortName()`` walk and the TS ``superResolved``
+    walk."""
+    cur = entity.super_data
+    visited: set[int] = set()
+    while cur is not None and id(cur) not in visited:
+        if cur.name == LLM_CALL_BASE:
+            return True
+        visited.add(id(cur))
+        cur = cur.super_data
+    return False
+
+
+def _first_prompt(entity: MetaObject) -> MetaTemplate | None:
+    """First OWN ``template.prompt`` child of *entity*, or ``None``. Own-only —
+    the trace prompt is declared inline on the concrete trace entity (Slice 1/3
+    derive the typed columns from it)."""
+    for child in entity.own_children():
+        if (
+            isinstance(child, MetaTemplate)
+            and child.type == TYPE_TEMPLATE
+            and child.sub_type == tc.TEMPLATE_SUBTYPE_PROMPT
+        ):
+            return child
+    return None
+
+
+def render_trace_helper(entity: MetaObject, root: MetaData) -> str | None:
+    """Render one ``record_<entity>.py`` for a concrete trace ``object.entity``.
+
+    Returns ``None`` when the entity is not a trace-helper target (abstract, not
+    ``LlmCallBase``-derived, no nested ``template.prompt``, or that prompt carries
+    neither ``@responseRef`` nor ``@payloadRef``).
+
+    Raises ``ValueError`` when the prompt's ``@responseRef`` does not resolve to an
+    ``object.value`` (matching the Java port's hard ``GeneratorException``)."""
+    if entity.is_abstract:
+        return None
+    if not _extends_base(entity):
+        return None
+
+    prompt = _first_prompt(entity)
+    if prompt is None:
+        return None
+
+    response_ref = prompt.response_ref()
+    payload_ref = prompt.payload_ref()
+    # Both gate the helper — at least one of @responseRef / @payloadRef must be
+    # present (matches the TS reference, which needs @responseRef to type the result
+    # and @payloadRef to type the request).
+    if response_ref is None and payload_ref is None:
+        return None
+
+    # The response VO drives the baked extract schema + the typed voResponse. When
+    # only @payloadRef is set we still emit a helper (the request is typed); the
+    # extract schema falls back to an empty descriptor (no response VO to shape it).
+    response_vo = resolve_payload_vo(root, response_ref) if response_ref else None
+    if response_ref is not None and response_vo is None:
+        raise ValueError(
+            f"{_GENERATOR_NAME}: entity {entity.name!r} prompt @responseRef "
+            f"{response_ref!r} does not resolve to an object.value"
+        )
+
+    entity_name = entity.name
+    snake = _snake_case(entity_name)
+    record_fn = f"record_{snake}"
+    result_class = f"{entity_name}TraceResult"
+
+    # Derive the parse format from the prompt's @format attr (default json) — the
+    # SAME rule the output-parser / extractor generators use.
+    fmt = prompt.attr(tc.TEMPLATE_ATTR_FORMAT)
+    fmt_str = fmt if isinstance(fmt, str) else tc.TEMPLATE_FORMAT_DEFAULT
+
+    fqn = entity.fqn()
+
+    # Baked response-extract schema. REUSE the extract_schema_emitter exactly as the
+    # output-parser generator does for its tolerant ``extract_lenient_*`` twin:
+    # ``schema_literal(vo, fmt, root_name)`` emits an
+    # ``ExtractSchema(Format.X, "<root>", [FieldSpec(...), …])`` literal, and
+    # ``extract_map_imports(vo)`` returns the sorted/deduped ``extract_map`` accessor
+    # names the literal's FieldSpec helpers reference. ``root_name`` is the response
+    # VO's short name (the JSON/XML root the tolerant reader locates). When there is
+    # no response VO (only @payloadRef set) the schema is an empty descriptor whose
+    # extract yields ``{}``.
+    if response_vo is not None:
+        schema_literal = rse.schema_literal(response_vo, fmt_str, response_vo.name)
+        helpers = rse.extract_map_imports(response_vo)
+    else:
+        schema_literal = f'ExtractSchema({_format_enum(fmt_str)}, "response", [])'
+        helpers = []
+
+    request_doc = payload_ref if payload_ref else "the structured request object"
+
+    lines: list[str] = [
+        generated_header(entity_name, fqn),
+        "from __future__ import annotations",
+        "",
+        "import dataclasses",
+        "from dataclasses import dataclass",
+        "",
+        "from metaobjects.render.extract import (",
+        "    ExtractSchema,",
+        "    FieldKind,",
+        "    FieldSpec,",
+        "    Format,",
+        "    extract,",
+        ")",
+    ]
+    if helpers:
+        lines.append("from metaobjects.render.extract.extract_map import (")
+        for h in helpers:
+            lines.append(f"    {h},")
+        lines.append(")")
+    lines.extend(
+        [
+            "from metaobjects.runtime import (",
+            "    LlmCallInput,",
+            "    LlmCallRecorder,",
+            "    LlmCallRow,",
+            "    STATUS_ERROR,",
+            "    STATUS_OK,",
+            "    build_llm_call_row,",
+            "    persist_llm_call_row,",
+            ")",
+            "",
+            "from collections.abc import Callable",
+            "",
+            "",
+            "# AI-trace baked response-extract descriptor — the format/root/field shape",
+            "# the tolerant parser repairs the model's raw response text against.",
+            f"_RESPONSE_SCHEMA: ExtractSchema = {schema_literal}",
+            "",
+            "",
+            "@dataclass(frozen=True, slots=True)",
+            f"class {result_class}:",
+            f'    """Typed result of ``{record_fn}``: the derived call outcome plus the',
+            "    best-effort extracted response VO.",
+            "",
+            "    * ``status`` — ``STATUS_OK`` | ``STATUS_ERROR`` (a lost ``@required``",
+            "      response field → ``STATUS_ERROR``).",
+            "    * ``error_detail`` — a ``\"lost required: …\"`` summary when ``status`` is",
+            "      ``STATUS_ERROR``, else ``None``.",
+            "    * ``vo_response`` — the extracted response mirror dict (``None`` only when",
+            '      extraction produced nothing)."""',
+            "    status: str",
+            "    error_detail: str | None",
+            "    vo_response: dict | None",
+            "",
+            "",
+            f"def {record_fn}(",
+            "    recorder: LlmCallRecorder,",
+            "    input: LlmCallInput,",
+            "    redact: Callable[[LlmCallRow], LlmCallRow] | None = None,",
+            f") -> {result_class}:",
+            f'    """Record a single ``{entity_name}`` LLM call: extract the typed response',
+            "    VO from ``input.llm_response_text`` and persist ONE trace row (the base",
+            "    envelope + raw I/O + typed voRequest/voResponse) via ``recorder`` —",
+            "    regardless of whether extraction succeeded.",
+            "",
+            "    The tolerant ``extract`` NEVER raises; a lost ``@required`` response field",
+            "    drives ``status``/``error_detail`` (it does not abort the persist). The",
+            f"    request payload (``input.llm_request``, typed as ``{request_doc}`` at the",
+            "    call site) is threaded through as the typed ``voRequest`` column.",
+            "",
+            "    :param recorder: the never-throwing write-side seam (Slice-1 recorder).",
+            "    :param input:    the LLM call fields (envelope + raw request/response text).",
+            "    :param redact:   optional row redaction applied before the single record.",
+            '    """',
+            "    outcome = extract(input.llm_response_text, _RESPONSE_SCHEMA)",
+            "    failed = outcome.report.has_lost_required()",
+            "    status = STATUS_ERROR if failed else STATUS_OK",
+            "    error_detail = (",
+            '        "lost required: " + ", ".join(outcome.report.lost_required())',
+            "        if failed",
+            "        else None",
+            "    )",
+            "    # Extraction owns the derived status/error_detail — fold them into the input",
+            "    # before building the base row (dataclasses.replace, leaving the original",
+            "    # input untouched).",
+            "    effective = dataclasses.replace(",
+            "        input, status=status, error_detail=error_detail",
+            "    )",
+            "    row = build_llm_call_row(effective)",
+            "    # Typed columns → native jsonb (pg8000 binds dict/list straight to jsonb).",
+            "    row[\"voResponse\"] = outcome.data",
+            "    row[\"voRequest\"] = input.llm_request",
+            "    # Persist ONCE (redact-then-record; the recorder never raises).",
+            "    persist_llm_call_row(recorder, row, redact)",
+            f"    return {result_class}(status, error_detail, outcome.data)",
+            "",
+            "",
+            f'__all__ = ["{record_fn}", "{result_class}"]',
+            "",
+        ]
+    )
+    return "\n".join(lines)
+
+
+def _format_enum(fmt: str) -> str:
+    """``"xml"`` → ``Format.XML``; anything else → ``Format.JSON``. Matches the
+    extract_schema_emitter's private ``_format_enum`` (kept local to avoid reaching
+    into a private helper)."""
+    return "Format.XML" if fmt.lower() == tc.TEMPLATE_FORMAT_XML else "Format.JSON"
+
+
+class TraceHelperGenerator:
+    """Generator wrapping :func:`render_trace_helper`. Emits one
+    ``record_<entity>.py`` per concrete ``object.entity`` that derives from
+    ``LlmCallBase`` and nests a ``template.prompt`` with ``@responseRef`` /
+    ``@payloadRef`` (skips everything else)."""
+
+    name = _GENERATOR_NAME
+
+    def __init__(self, *, filter: Callable[[MetaObject], bool] | None = None) -> None:
+        # The ``filter`` arg matches the cross-generator contract.
+        self.filter = filter
+
+    def _render_module(self, entity: MetaObject, root: MetaData) -> str | None:
+        """EXTENSION SEAM — render the whole ``record_<entity>`` module for one trace
+        entity. Defaults to :func:`render_trace_helper`. Override to pre/post-process
+        the emitted source or replace the render path entirely."""
+        return render_trace_helper(entity, root)
+
+    def generate(self, ctx: GenContext) -> list[EmittedFile]:
+        root = ctx.loaded_root
+        if root is None:
+            return []
+        files: list[EmittedFile] = []
+        # Stable name order — deterministic emission (matches the other generators).
+        entities = sorted(
+            (
+                c
+                for c in root.own_children()
+                if isinstance(c, MetaObject) and c.sub_type == OBJECT_SUBTYPE_ENTITY
+            ),
+            key=lambda c: c.name,
+        )
+        for entity in entities:
+            if self.filter is not None and not self.filter(entity):
+                continue
+            content = self._render_module(entity, root)
+            if content is None:
+                continue
+            files.append(
+                EmittedFile(
+                    path=f"record_{_snake_case(entity.name)}.py",
+                    content=ruff_format(content),
+                )
+            )
+        return files
+
+
+def trace_helper_generator(
+    *, filter: Callable[[MetaObject], bool] | None = None
+) -> Generator:
+    """Factory mirroring the TS ``traceHelperFile()`` and the Java
+    ``LlmTraceHelperGenerator``. Stable cross-port name ``trace-helper``."""
+    return TraceHelperGenerator(filter=filter)

metaobjects/codegen/instance_artifacts.py

@@ -0,0 +1,15 @@
+"""Guard for the abstract concept (mirrors the TS instance-artifacts module).
+
+An abstract entity must never produce instance/write artifacts (routers, filter
+allowlists, CREATE TABLE DDL). The Pydantic base *model* is a separate, configurable
+shape concern (emit_abstract_shapes, default on) handled in entity_model.
+"""
+from metaobjects.meta.core.object.meta_object import MetaObject
+
+
+def is_abstract(entity: MetaObject) -> bool:
+    return entity.is_abstract is True
+
+
+def emits_instance_artifacts(entity: MetaObject) -> bool:
+    return not is_abstract(entity)

metaobjects/codegen/output_format_spec_emitter.py

@@ -0,0 +1,79 @@
+"""Turns a payload value-object + its ``template.output`` node into a Python source
+literal for an :class:`~metaobjects.render.OutputFormatSpec` — the artifact-1 prompt
+descriptor used by the FR-010 output-prompt codegen.
+
+Emits ``OutputFormatSpec(Format.X, "rootName", PromptStyle.X, [PromptField(...), …])``.
+Mirrors the C# / Java ``OutputFormatSpecEmitter`` adapted to Python (keyword args for
+the long ``PromptField`` ctor to keep the emitted source readable + order-robust).
+Bounded scope: scalar / enum. Nested object → ``FieldKind.OBJECT`` placeholder.
+"""
+from __future__ import annotations
+
+from metaobjects.codegen import fr010_field_mapping as fm
+from metaobjects.meta.core.field import field_constants as fc
+from metaobjects.meta.meta_data import MetaData
+from metaobjects.meta.template import template_constants as tc
+
+
+def _format_enum(template: MetaData) -> str:
+    fmt = template.attr(tc.TEMPLATE_ATTR_FORMAT)
+    return (
+        "Format.XML"
+        if isinstance(fmt, str) and fmt.lower() == "xml"
+        else "Format.JSON"
+    )
+
+
+def _prompt_style_enum(template: MetaData) -> str:
+    style = template.attr(tc.TEMPLATE_ATTR_PROMPT_STYLE)
+    if style == tc.PROMPT_STYLE_INLINE:
+        return "PromptStyle.INLINE"
+    if style == tc.PROMPT_STYLE_EXAMPLE_ONLY:
+        return "PromptStyle.EXAMPLE_ONLY"
+    return "PromptStyle.GUIDE"
+
+
+def _opt_string_attr(field: MetaData, attr_name: str) -> str:
+    v = field.attr(attr_name)
+    return fm.py_string_literal(v) if isinstance(v, str) else "None"
+
+
+def _prompt_field_literal(field: MetaData) -> str:
+    name = field.name
+    req = "True" if fm.is_required(field) else "False"
+    array = "True" if fm.is_array(field) else "False"
+
+    if field.sub_type == fc.FIELD_SUBTYPE_OBJECT:
+        return (
+            f'PromptField("{name}", FieldKind.OBJECT, {req}, array={array})'
+            "  # FR-010: nested prompt deferred"
+        )
+
+    example = _opt_string_attr(field, fc.FIELD_ATTR_EXAMPLE)
+    instruction = _opt_string_attr(field, fc.FIELD_ATTR_INSTRUCTION)
+
+    if field.sub_type == fc.FIELD_SUBTYPE_ENUM:
+        values_lit = fm.string_list_literal(fm.enum_values(field))
+        enum_doc_lit = fm.properties_map_literal(field.attr(fc.FIELD_ATTR_ENUM_DOC))
+        return (
+            f'PromptField("{name}", FieldKind.ENUM, {req}, array={array}, '
+            f"enum_values={values_lit}, enum_doc={enum_doc_lit}, "
+            f"example={example}, instruction={instruction})"
+        )
+
+    kind = fm.scalar_kind(field.sub_type) or "STRING"
+    return (
+        f'PromptField("{name}", FieldKind.{kind}, {req}, array={array}, '
+        f"example={example}, instruction={instruction})"
+    )
+
+
+def spec_literal(vo: MetaData, template: MetaData, root_name: str) -> str:
+    """Emit ``OutputFormatSpec(Format.X, "rootName", PromptStyle.X, [PromptField(...), …])``."""
+    format_enum = _format_enum(template)
+    style_enum = _prompt_style_enum(template)
+    field_lits = [_prompt_field_literal(f) for f in fm.fields(vo)]
+    body = ", ".join(field_lits)
+    return (
+        f'OutputFormatSpec({format_enum}, "{root_name}", {style_enum}, [{body}])'
+    )

metaobjects/codegen/overwrite_policy.py

@@ -0,0 +1,27 @@
+"""Per-file write decision based on the @generated marker.
+Mirrors codegen-ts/src/overwrite-policy.ts. Three-way merge is a later enhancement."""
+from __future__ import annotations
+
+import os
+
+from .constants import GENERATED_MARKER
+
+# status: "new" | "overwrite" | "refused" | "skipped"
+
+
+def decide_and_write(path: str, content: str, strategy: str = "overwrite") -> str:
+    if not os.path.exists(path):
+        os.makedirs(os.path.dirname(path) or ".", exist_ok=True)
+        with open(path, "w", encoding="utf-8") as fh:
+            fh.write(content)
+        return "new"
+
+    with open(path, encoding="utf-8") as fh:
+        current = fh.read()
+    if GENERATED_MARKER not in current:
+        return "refused"
+    if strategy == "skip-existing":
+        return "skipped"
+    with open(path, "w", encoding="utf-8") as fh:
+        fh.write(content)
+    return "overwrite"