feat(py-render): FR-010 Phase 1 — tolerant recover engine + dirty-input conformance (Python port)

Native Python reimplementation of the FR-010 recover engine in metaobjects/render/recover/,
the forgiving tier beyond FR-006's strict Pydantic parser. 8-stage pipeline (strip → locate →
forgiving-read → malformed-vs-absent → coerce → classify), JSON + XML, never raises. Per-field
FieldRecovery classification + canonical value pinned by the shared fixtures/recover-conformance/
corpus — all 10 cases green, matching Java/C#.

Python idioms (Tier 2): enum.Enum (SCREAMING_SNAKE values for corpus parity), dataclasses,
MALFORMED/TRUNCATED unique sentinels, as_int/as_long both Optional[int] (one int type) truncating
toward zero, bool excluded from numeric helpers (Java instanceof Number parity). Nested-object
recover implemented (like TS/C#). Carries the fixed edge cases (JSON no-hang, TRUNCATED→MALFORMED,
XML no-throw, non-finite→MALFORMED, array partial, enum alias-fold).

Pre-merge gates (review + simplifier): ASCII-numeric gate rejects Python-permissive syntax
(underscore grouping, Unicode digits, radix prefixes) for cross-port parity (+regression);
JSON depth cap (_MAX_DEPTH=100) keeps recover never-raising on pathologically deep input where
Python's recursion limit would otherwise raise (+regression); simplifier modernized to match/case
+ X|None. KNOWN_GAPS records the divergences. 108 recover tests + render suite 179 green;
mypy --strict + ruff clean on the recover package.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: dmealing

server/python/src/metaobjects/render/__init__.py

@@ -1,5 +1,20 @@
-"""Render-tier engine (FR-004): the build-time template drift-check ``verify``."""
+"""Render-tier engine: the build-time template drift-check ``verify`` (FR-004) and
+the FR-010 tolerant ``recover`` parser."""
 
+from metaobjects.render.recover import (
+    FieldKind,
+    FieldRecovery,
+    FieldSpec,
+    Format,
+    RecoverOptions,
+    RecoverOutcome,
+    RecoverSchema,
+    RecoveryReport,
+    RecoveryResult,
+    Tolerance,
+    recover,
+    recover_map,
+)
 from metaobjects.render.verify import (
     ERR_OUTPUT_TAG_MISSING,
     ERR_PARTIAL_UNRESOLVED,
@@ -17,9 +32,21 @@
     "ERR_PARTIAL_UNRESOLVED",
     "ERR_REQUIRED_SLOT_UNUSED",
     "ERR_VAR_NOT_ON_PAYLOAD",
+    "FieldKind",
+    "FieldRecovery",
+    "FieldSpec",
+    "Format",
     "InMemoryProvider",
     "PayloadField",
     "Provider",
+    "RecoverOptions",
+    "RecoverOutcome",
+    "RecoverSchema",
+    "RecoveryReport",
+    "RecoveryResult",
+    "Tolerance",
     "VerifyError",
+    "recover",
+    "recover_map",
     "verify",
 ]

server/python/src/metaobjects/render/recover/KNOWN_GAPS.md

@@ -0,0 +1,53 @@
+# FR-010 Python recover engine — known gaps & intentional cross-port divergences
+
+Scope: the tolerant `recover` pipeline (`metaobjects/render/recover/`). The Java engine
+(`server/java/render/.../recover/`) is the cross-port reference; `fixtures/recover-conformance/`
+is the oracle. All 10 corpus cases pass.
+
+## Additive capability (TS + C# + Python, beyond Java/Kotlin codegen deferral)
+
+- **Nested-object recover is implemented** — a `FieldSpec` with a nested `RecoverSchema`
+  (the `object_(...)` factory) is descended into, classifying sub-fields with dotted paths
+  (`meta.n`). Mirrors the Java/C# `extract` OBJECT recursion. Dormant under the corpus (no
+  nested fixture) and under FR-010 codegen (which emits a scalar placeholder for parity), so
+  it changes no shared-corpus result.
+
+## Intentional, documented divergences (NOT bugs)
+
+The cross-port contract pins *classification + canonical value* (numbers ±1e-9), not byte-
+identical native parsing.
+
+- **Java-style numeric suffixes / hex-float literals.** Java's `Double.parseDouble` accepts
+  `"42d"`/`"42f"` and hex-float forms (→ RECOVERED); Python rejects them → **MALFORMED** (same
+  accepted divergence the C#/TS ports record). The load-bearing behavior — finite-only,
+  `NaN`/`±Infinity` → MALFORMED — is identical.
+
+- **ASCII-numeric gate (parity guard, not a divergence).** Python's `int()`/`float()` accept
+  underscore digit grouping (`"1_000"`, PEP 515), Unicode digits (`"１２３"`, `"٣"`), and radix
+  prefixes (`"0x10"`) that Java/C# reject. `coerce` gates numeric strings on an ASCII-only
+  pattern so these all classify **MALFORMED**, matching the strict cross-port behavior (C#).
+
+- **NBSP-trailing numerics.** `"1 "` → Python `str.strip()` removes the NBSP (Unicode
+  whitespace) leaving `"1"` → RECOVERED, as does C# `Trim()`; Java `trim()` keeps it →
+  MALFORMED. A pre-existing Java/C# disagreement on whitespace trimming; Python sides with C#.
+  Not corpus-exercised.
+
+## NIT (no cross-port consensus, no corpus case)
+
+- **Out-of-int64-range integers** (e.g. `"9999999999999999999"`): Python has arbitrary-precision
+  ints (RECOVERED with the exact value); Java saturates to `Long.MAX_VALUE`, C# wraps on the
+  cast. The three ports already disagree, so there is no single canonical value to match. No
+  corpus int approaches 2^63. Left as-is.
+
+## Python-specific defensive bound
+
+- **JSON nesting depth cap (`_MAX_DEPTH = 100`).** Python's recursion limit is far below the
+  JVM/.NET stack, so a pathologically deep input (hundreds of nested brackets) would raise
+  `RecursionError` — violating the never-throws contract. Past the cap the container is skipped
+  (string-aware, non-recursive) and recorded as garbled (→ MALFORMED). Far above any realistic
+  payload nesting; the other ports rely on their larger native stacks instead.
+
+## Bounded deferral (parity with all ports)
+
+- Array-of-enum is not specialized (a scalar array recovers via `as_string_list`).
+- `as_int`/`as_long` are identical (`Optional[int]`; Python has one int type), truncating toward zero.

server/python/src/metaobjects/render/recover/__init__.py

@@ -0,0 +1,56 @@
+"""FR-010 tolerant ``recover`` engine (Tier 2).
+
+A forgiving parser that takes dirty LLM output (fenced / preamble / prose-wrapped /
+truncated / trailing-comma JSON, unclosed-tag XML) and recovers it into a typed
+``dict``, classifying each field. It NEVER raises — the forgiving tier beyond
+FR-006's strict Pydantic parser.
+
+Public entry point: :func:`recover`.
+"""
+from __future__ import annotations
+
+from metaobjects.render.recover import recover_map
+from metaobjects.render.recover.coerce import MALFORMED
+from metaobjects.render.recover.json_forgiving_reader import (
+    TRUNCATED,
+    JsonForgivingReader,
+)
+from metaobjects.render.recover.recover import recover
+from metaobjects.render.recover.types import (
+    Coercion,
+    FieldKind,
+    FieldRecovery,
+    FieldSpec,
+    Format,
+    Normalizer,
+    OnField,
+    RecoverOptions,
+    RecoverOutcome,
+    RecoverSchema,
+    RecoveryReport,
+    RecoveryResult,
+    Tolerance,
+)
+from metaobjects.render.recover.xml_forgiving_reader import XmlForgivingReader
+
+__all__ = [
+    "MALFORMED",
+    "TRUNCATED",
+    "Coercion",
+    "FieldKind",
+    "FieldRecovery",
+    "FieldSpec",
+    "Format",
+    "JsonForgivingReader",
+    "Normalizer",
+    "OnField",
+    "RecoverOptions",
+    "RecoverOutcome",
+    "RecoverSchema",
+    "RecoveryReport",
+    "RecoveryResult",
+    "Tolerance",
+    "XmlForgivingReader",
+    "recover",
+    "recover_map",
+]

server/python/src/metaobjects/render/recover/coerce.py

@@ -0,0 +1,171 @@
+"""Stage 7: canonicalize a raw scalar string per its FieldSpec.
+
+Returns the ``MALFORMED`` sentinel when the value is present but uncoercible.
+
+Cross-port number rules (parity with C#/TS, an accepted divergence from Java):
+
+- Non-finite (NaN / ±Infinity) → MALFORMED.
+- Radix-prefixed strings (``0x..`` / ``0b..`` / ``0o..``) are REJECTED. Python's
+  ``int(s, 0)`` would accept them but Java's ``Long.parseLong`` / C#'s
+  ``long.TryParse`` reject them — so the C# and TS ports added this guard; we match.
+- We do NOT replicate Java's ``Double.parseDouble`` suffix tolerance
+  (``"42d"`` / hex-float) — documented accepted divergence (same as C#/TS).
+"""
+from __future__ import annotations
+
+import math
+import re
+from typing import Final
+
+from metaobjects.render.recover.types import (
+    Coercion,
+    FieldKind,
+    FieldSpec,
+    RecoverOptions,
+    RecoveryReport,
+    Tolerance,
+)
+
+# Sentinel: the value was present but could not be coerced to the declared kind/vocabulary.
+MALFORMED: Final = object()
+
+# A canonical ASCII numeric literal (int / decimal / scientific). Python's int()/float()
+# are far more permissive than Java/C# numeric parsing — they accept underscore digit
+# grouping ("1_000", PEP 515), Unicode digits ("１２３"), and radix prefixes ("0x10"). Gating
+# on this ASCII-only pattern rejects all of those → MALFORMED, matching the strict cross-port
+# behavior (C#'s TryParse). `[0-9]` (not `\d`) keeps it ASCII-only.
+_ASCII_NUMERIC = re.compile(r"^[+-]?(?:[0-9]+\.?[0-9]*|\.[0-9]+)(?:[eE][+-]?[0-9]+)?$")
+
+
+def value(
+    raw: str | None,
+    spec: FieldSpec,
+    opts: RecoverOptions,
+    field_path: str,
+    report: RecoveryReport,
+) -> object:
+    """Canonicalize ``raw`` to the native type described by ``spec``, or MALFORMED."""
+    if raw is None:
+        return MALFORMED
+
+    # OnField hook takes priority.
+    if opts.on_field is not None:
+        hooked = opts.on_field(field_path, raw, spec)
+        if hooked is not None:
+            report.add_coercion(Coercion(field_path, raw, str(hooked), "onField"))
+            return hooked
+
+    # Per-field runtime normalizer (bounded 20% surface). Keyed by path, then simple name.
+    norm = opts.normalizers.get(field_path)
+    if norm is None:
+        norm = opts.normalizers.get(spec.name)
+    if norm is not None:
+        normalized = norm(raw)
+        if normalized is not None:
+            report.add_coercion(Coercion(field_path, raw, str(normalized), "normalizer"))
+            return normalized
+
+    ci = opts.tolerance != Tolerance.STRICT
+    match spec.kind:
+        case FieldKind.ENUM:
+            return _coerce_enum(raw, spec, opts, field_path, report, ci)
+        case FieldKind.INT | FieldKind.LONG:
+            return _coerce_int(raw, spec, field_path, report)
+        case FieldKind.DOUBLE:
+            return _coerce_double(raw, spec, field_path, report)
+        case FieldKind.BOOLEAN:
+            return _coerce_bool(raw, ci)
+        case _:
+            return raw
+
+
+def _coerce_enum(
+    raw: str,
+    spec: FieldSpec,
+    opts: RecoverOptions,
+    path: str,
+    report: RecoveryReport,
+    ci: bool,
+) -> object:
+    if spec.enum_values is not None:
+        for v in spec.enum_values:
+            if v == raw:
+                return v
+            if ci and v.lower() == raw.lower():
+                report.add_coercion(Coercion(path, raw, v, "case"))
+                return v
+    schema_target = None if spec.enum_alias is None else spec.enum_alias.get(raw)
+    runtime_target = opts.aliases.get(raw)
+    if runtime_target is not None:
+        kind = (
+            "runtime-alias-override"
+            if schema_target is not None and schema_target != runtime_target
+            else "alias"
+        )
+        report.add_coercion(Coercion(path, raw, runtime_target, kind))
+        return runtime_target
+    if schema_target is not None:
+        report.add_coercion(Coercion(path, raw, schema_target, "alias"))
+        return schema_target
+    return MALFORMED
+
+
+def _coerce_int(raw: str, spec: FieldSpec, path: str, report: RecoveryReport) -> object:
+    trimmed = raw.strip()
+    if not _ASCII_NUMERIC.match(trimmed):
+        return MALFORMED
+    # Integer parse first (matches Java Long.parseLong / C# long.TryParse), then a
+    # float fallback (matches Java's Double.parseDouble fallback).
+    try:
+        return _clamp(float(int(trimmed)), spec, path, report, as_long=True)
+    except ValueError:
+        pass
+    try:
+        d = float(trimmed)
+    except ValueError:
+        return MALFORMED
+    return _clamp(d, spec, path, report, as_long=True)
+
+
+def _coerce_double(raw: str, spec: FieldSpec, path: str, report: RecoveryReport) -> object:
+    trimmed = raw.strip()
+    if not _ASCII_NUMERIC.match(trimmed):
+        return MALFORMED
+    try:
+        d = float(trimmed)
+    except ValueError:
+        return MALFORMED
+    return _clamp(d, spec, path, report, as_long=False)
+
+
+def _clamp(
+    n: float, spec: FieldSpec, path: str, report: RecoveryReport, as_long: bool
+) -> object:
+    # Non-finite (NaN, ±Infinity) → MALFORMED (cross-port classification parity).
+    if not math.isfinite(n):
+        return MALFORMED
+    c = n
+    if spec.min is not None and c < spec.min:
+        c = spec.min
+    if spec.max is not None and c > spec.max:
+        c = spec.max
+    if c != n:
+        report.add_coercion(Coercion(path, _num_str(n), _num_str(c), "clamp"))
+    # Truncate toward zero for integer kinds (math.trunc / int()).
+    return math.trunc(c) if as_long else c
+
+
+def _num_str(n: float) -> str:
+    # Render integral floats without a trailing ".0" to read like Java/C# longs in notes.
+    if n == math.trunc(n) and math.isfinite(n):
+        return str(int(n))
+    return str(n)
+
+
+def _coerce_bool(raw: str, ci: bool) -> object:
+    t = raw.strip().lower() if ci else raw.strip()
+    if t in ("true", "yes", "1"):
+        return True
+    if t in ("false", "no", "0"):
+        return False
+    return MALFORMED